ovn: make external_ids naming uniform

[mirror_ovs.git] / ovn / controller / ovn-controller.8.xml

<?xml version="1.0" encoding="utf-8"?>
<manpage program="ovn-controller" section="8" title="ovn-controller">
    <h1>Name</h1>
    <p>ovn-controller -- Open Virtual Network local controller</p>

    <h1>Synopsis</h1>
    <p><code>ovn-controller</code> [<var>options</var>] [<var>ovs-database</var>]</p>

    <h1>Description</h1>
    <p>
      <code>ovn-controller</code> is the local controller daemon for
      OVN, the Open Virtual Network.  It connects up to the OVN
      Southbound database (see <code>ovn-sb</code>(5)) over the OVSDB
      protocol, and down to the Open vSwitch database (see
      <code>ovs-vswitchd.conf.db</code>(5)) over the OVSDB protocol and
      to <code>ovs-vswitchd</code>(8) via OpenFlow.  Each hypervisor and
      software gateway in an OVN deployment runs its own independent
      copy of <code>ovn-controller</code>; thus,
      <code>ovn-controller</code>'s downward connections are
      machine-local and do not run over a physical network.
    </p>

    <h1>Configuration</h1>
    <p>
      <code>ovn-controller</code> retrieves most of its configuration
      information from the local Open vSwitch's ovsdb-server instance.
      The default location is <code>db.sock</code> in the local Open
      vSwitch's "run" directory.  It may be overridden by specifying the
      <var>ovs-database</var> argument in one of the following forms:
    </p>
    <ul>
      <li>
        <p>
          <code>ssl:<var>ip</var>:<var>port</var></code>
        </p>
        <p>
          The specified SSL <var>port</var> on the host at the given
          <var>ip</var>, which must be expressed as an IP address (not a DNS
          name) in IPv4 or IPv6 address format.  If <var>ip</var> is an IPv6
          address, then wrap <var>ip</var> with square brackets, e.g.:
          <code>ssl:[::1]:6640</code>.  The <code>--private-key</code>,
          <code>--certificate</code> and either of <code>--ca-cert</code>
          or <code>--bootstrap-ca-cert</code> options are mandatory when this
          form is used.
        </p>
      </li>
      <li>
        <p>
          <code>tcp:<var>ip</var>:<var>port</var></code>
        </p>
        <p>
          Connect to the given TCP <var>port</var> on <var>ip</var>, where
          <var>ip</var> can be IPv4 or IPv6 address. If <var>ip</var> is an
          IPv6 address, then wrap <var>ip</var> with square brackets, e.g.:
          <code>tcp:[::1]:6640</code>.
        </p>
      </li>
      <li>
        <p>
          <code>unix:<var>file</var></code>
        </p>
        <p>
          On POSIX, connect to the Unix domain server socket named
          <var>file</var>.
        </p>
        <p>
          On Windows, connect to a localhost TCP port whose value is written
          in <var>file</var>.
        </p>
      </li>
    </ul>
    <p>
      <code>ovn-controller</code> assumes it gets configuration
      information from the following keys in the <code>Open_vSwitch</code>
      table of the local OVS instance:
    </p>
    <dl>
      <dt><code>external_ids:system-id</code></dt>
      <dd>The chassis name to use in the Chassis table.</dd>

      <dt><code>external_ids:hostname</code></dt>
      <dd>The hostname to use in the Chassis table.</dd>

      <dt><code>external_ids:ovn-bridge</code></dt>
      <dd>
        The integration bridge to which logical ports are attached.  The
        default is <code>br-int</code>.  If this bridge does not exist when
        ovn-controller starts, it will be created automatically with the
        default configuration suggested in <code>ovn-architecture</code>(7).
      </dd>

      <dt><code>external_ids:ovn-remote</code></dt>
      <dd>
        <p>
          The OVN database that this system should connect to for its
          configuration.
        </p>

        <p>
          Currently, <code>ovn-controller</code> does not support changing this
          setting mid-run.  If the value needs to change, the daemon must be
          restarted.  (This behavior should be improved.)
        </p>
      </dd>

      <dt><code>external_ids:ovn-remote-probe-interval</code></dt>
      <dd>
        <p>
          The inactivity probe interval of the connection to the OVN database,
          in milliseconds.
          If the value is zero, it disables the connection keepalive feature.
        </p>

        <p>
          If the value is nonzero, then it will be forced to a value of
          at least 1000 ms.
        </p>
      </dd>

      <dt><code>external_ids:ovn-encap-type</code></dt>
      <dd>
        <p>
          The encapsulation type that a chassis should use to connect to
          this node.  Multiple encapsulation types may be specified with
          a comma-separated list.  Each listed encapsulation type will
          be paired with <code>ovn-encap-ip</code>.
        </p>

        <p>
          Supported tunnel types for connecting hypervisors
          are <code>geneve</code> and <code>stt</code>.  Gateways may
          use <code>geneve</code>, <code>vxlan</code>, or
          <code>stt</code>.
        </p>

        <p>
          Due to the limited amount of metadata in <code>vxlan</code>,
          the capabilities and performance of connected gateways will be
          reduced versus other tunnel formats.
        </p>
      </dd>

      <dt><code>external_ids:ovn-encap-ip</code></dt>
      <dd>
        The IP address that a chassis should use to connect to this node
        using encapsulation types specified by
        <code>external_ids:ovn-encap-type</code>.
      </dd>

      <dt><code>external_ids:ovn-bridge-mappings</code></dt>
      <dd>
        A list of key-value pairs that map a physical network name to a local
        ovs bridge that provides connectivity to that network.  An example
        value mapping two physical network names to two ovs bridges would be:
        <code>physnet1:br-eth0,physnet2:br-eth1</code>.
      </dd>
    </dl>

    <h1>Open vSwitch Database Usage</h1>

    <p>
      <code>ovn-controller</code> uses a number of <code>external_ids</code>
      keys in the Open vSwitch database to keep track of ports and interfaces.
      For proper operation, users should not change or clear these keys:
    </p>

    <dl>
      <dt>
        <code>external_ids:ovn-chassis-id</code> in the <code>Port</code> table
      </dt>
      <dd>
        The presence of this key identifies a tunnel port within the
        integration bridge as one created by <code>ovn-controller</code> to
        reach a remote chassis.  Its value is the chassis ID of the remote
        chassis.
      </dd>

      <dt>
        <code>external_ids:ovn-localnet-port</code> in the <code>Port</code>
        table
      </dt>
      <dd>
        <p>
          The presence of this key identifies a patch port as one created by
          <code>ovn-controller</code> to connect the integration bridge and
          another bridge to implement a <code>localnet</code> logical port.
          Its value is the name of the logical port with <code>type</code>
          set to <code>localnet</code> that the port implements. See
          <code>external_ids:ovn-bridge-mappings</code>, above, for more
          information.
        </p>

        <p>
          Each <code>localnet</code> logical port is implemented as a pair of
          patch ports, one in the integration bridge, one in a different
          bridge, with the same <code>external_ids:ovn-localnet-port</code>
          value.
        </p>
      </dd>

      <dt>
        <code>external_ids:ovn-l2gateway-port</code> in the <code>Port</code>
        table
      </dt>
      <dd>
        <p>
          The presence of this key identifies a patch port as one created by
          <code>ovn-controller</code> to connect the integration bridge and
          another bridge to implement a <code>l2gateway</code> logical port.
          Its value is the name of the logical port with <code>type</code>
          set to <code>l3gateway</code> that the port implements. See
          <code>external_ids:ovn-bridge-mappings</code>, above, for more
          information.
        </p>

        <p>
          Each <code>l2gateway</code> logical port is implemented as a pair
          of patch ports, one in the integration bridge, one in a different
          bridge, with the same <code>external_ids:ovn-l2gateway-port</code>
          value.
        </p>
      </dd>

      <dt>
        <code>external_ids:ovn-logical-patch-port</code> in the
        <code>Port</code> table
      </dt>

      <dd>
        <p>
          This key identifies a patch port as one created by
          <code>ovn-controller</code> to implement an OVN logical patch port
          within the integration bridge.  Its value is the name of the OVN
          logical patch port that it implements.
        </p>
      </dd>
    </dl>

    <h1>Runtime Management Commands</h1>
    <p>
      <code>ovs-appctl</code> can send commands to a running
      <code>ovn-controller</code> process.  The currently supported
      commands are described below.
      <dl>
      <dt><code>exit</code></dt>
      <dd>
        Causes <code>ovn-controller</code> to gracefully terminate.
      </dd>

      <dt><code>ct-zone-list</code></dt>
      <dd>
        Lists each local logical port and its connection tracking zone.
      </dd>
      </dl>
    </p>

</manpage>