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>ACL Logging</h1>
    <p>
      ACL log messages are logged through <code>ovn-controller</code>'s
      logging mechanism.  ACL log entries have the module
      <code>acl_log</code> at log level <code>info</code>.  Configuring
      logging is described below in the <code>Logging Options</code>
      section.
    </p>

    <h1>Options</h1>

    <h2>Daemon Options</h2>
    <xi:include href="lib/daemon.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

    <h2>Logging Options</h2>
    <xi:include href="lib/vlog.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

    <h2>PKI Options</h2>
    <p>
      PKI configuration is required in order to use SSL for the connections to
      the Northbound and Southbound databases.
    </p>
    <xi:include href="lib/ssl.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
    <xi:include href="lib/ssl-bootstrap.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
    <xi:include href="lib/ssl-peer-ca-cert.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

    <h2>Other Options</h2>

    <xi:include href="lib/common.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>


    <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 as an OVSDB active or passive
      connection method, as described in <code>ovsdb</code>(7).
    </p>

    <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-bridge-datapath-type</code></dt>
      <dd>
        This configuration is optional. If set, then the datapath type of
        the integration bridge will be set to the configured value. If this
        option is not set, then <code>ovn-controller</code> will not modify
        the existing <code>datapath-type</code> of the integration bridge.
      </dd>

      <dt><code>external_ids:ovn-remote</code></dt>
      <dd>
        <p>
          The OVN database that this system should connect to for its
          configuration, in one of the same forms documented above for the
          <var>ovs-database</var>.
        </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-openflow-probe-interval</code></dt>
      <dd>
        <p>
          The inactivity probe interval of the OpenFlow connection to the
          OpenvSwitch integration bridge, in seconds.
          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 5s.
        </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>

      <dt><code>external_ids:ovn-encap-csum</code></dt>
      <dd>
        <code>ovn-encap-csum</code> indicates that encapsulation checksums can
        be transmitted and received with reasonable performance. It is a hint
        to senders transmitting data to this chassis that they should use
        checksums to protect OVN metadata. Set to <code>true</code> to enable
        or <code>false</code> to disable. Depending on the capabilities of the
        network interface card, enabling encapsulation checksum may incur
        performance loss. In such cases, encapsulation checksums can be disabled.
      </dd>

      <dt><code>external_ids:ovn-cms-options</code></dt>
      <dd>
        A list of options that will be consumed by the CMS Plugin and which
        specific to this particular chassis. An example would be:
        <code>cms_option1,cms_option2:foo</code>.
      </dd>

      <dt><code>external_ids:ovn-transport-zones</code></dt>
      <dd>
        <p>
          The transport zone(s) that this chassis belongs to. Transport
          zones is a way to group different chassis so that tunnels are only
          formed between members of the same group(s). Multiple transport
          zones may be specified with a comma-separated list. For example:
          tz1,tz2,tz3.
        </p>
        <p>
          If not set, the Chassis will be considered part of a default
          transport zone.
        </p>
      </dd>
      <dt><code>external_ids:ovn-chassis-mac-mappings</code></dt>
      <dd>
        A list of key-value pairs that map a chassis specific mac to
        a physical network name. An example
        value mapping two chassis macs to two physical network names would be:
        <code>physnet1:aa:bb:cc:dd:ee:ff,physnet2:a1:b2:c3:d4:e5:f6</code>.
        These are the macs that ovn-controller will replace a router port
        mac with, if packet is going from a distributed router port on
        vlan type logical switch.
      </dd>
    </dl>

    <p>
      <code>ovn-controller</code> reads the following values from the
      <code>Open_vSwitch</code> database of the local OVS instance:
    </p>

    <dl>
      <dt><code>datapath-type</code> from <ref table="Bridge" db="Open_vSwitch"/> table</dt>
      <dd>
        This value is read from local OVS integration bridge row of
        <ref table="Bridge" db="Open_vSwitch"/> table and populated in
        <ref key="datapath-type" table="Chassis" column="external_ids"
        db="OVN_Southbound"/> of the <ref table="Chassis" db="OVN_Southbound"/>
        table in the OVN_Southbound database.
      </dd>

      <dt><code>iface-types</code> from <ref table="Open_vSwitch" db="Open_vSwitch"/> table</dt>
      <dd>
        This value is populated in <ref key="iface-types" table="Chassis"
        column="external_ids" db="OVN_Southbound"/> of the
        <ref table="Chassis" db="OVN_Southbound"/> table in the OVN_Southbound
        database.
      </dd>

      <dt><code>private_key</code>, <code>certificate</code>,
          <code>ca_cert</code>, and <code>bootstrap_ca_cert</code>
          from <ref table="SSL" db="Open_vSwitch"/> table</dt>
      <dd>
        These values provide the SSL configuration used for connecting
        to the OVN southbound database server when an SSL connection type
        is configured via <code>external_ids:ovn-remote</code>.  Note that
        this SSL configuration can also be provided via command-line options,
        the configuration in the database takes precedence if both are present.
      </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:ct-zone-*</code> in the <code>Bridge</code> table
      </dt>
      <dd>
        Logical ports and gateway routers are assigned a connection
        tracking zone by <code>ovn-controller</code> for stateful
        services.  To keep state across restarts of
        <code>ovn-controller</code>, these keys are stored in the
        integration bridge's Bridge table.  The name contains a prefix
        of <code>ct-zone-</code> followed by the name of the logical
        port or gateway router's zone key.  The value for this key
        identifies the zone used for this port.
      </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>l2gateway</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-l3gateway-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 a <code>l3gateway</code>
          logical port. Its value is the name of the logical port with type
          set to <code>l3gateway</code>. This patch port is similar to
          the OVN logical patch port, except that <code>l3gateway</code>
          port can only be bound to a paticular chassis.
        </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>OVN Southbound Database Usage</h1>

    <p>
      <code>ovn-controller</code> reads from much of the
      <code>OVN_Southbound</code> database to guide its operation.
      <code>ovn-controller</code> also writes to the following tables:
    </p>

    <dl>
      <dt><code>Chassis</code></dt>
      <dd>
        Upon startup, <code>ovn-controller</code> creates a row in this table
        to represent its own chassis.  Upon graceful termination, e.g. with
        <code>ovs-appctl -t ovn-controller exit</code> (but not
        <code>SIGTERM</code>), <code>ovn-controller</code> removes its row.
      </dd>

      <dt><code>Encap</code></dt>
      <dd>
        Upon startup, <code>ovn-controller</code> creates a row or rows in this
        table that represent the tunnel encapsulations by which its chassis can
        be reached, and points its <code>Chassis</code> row to them.  Upon
        graceful termination, <code>ovn-controller</code> removes these rows.
      </dd>

      <dt><code>Port_Binding</code></dt>
      <dd>
        At runtime, <code>ovn-controller</code> sets the <code>chassis</code>
        columns of ports that are resident on its chassis to point to its
        <code>Chassis</code> row, and, conversely, clears the
        <code>chassis</code> column of ports that point to its
        <code>Chassis</code> row but are no longer resident on its chassis.
        The <code>chassis</code> column has a weak reference type, so when
        <code>ovn-controller</code> gracefully exits and removes its
        <code>Chassis</code> row, the database server automatically clears any
        remaining references to that row.
      </dd>

      <dt><code>MAC_Binding</code></dt>
      <dd>
        At runtime, <code>ovn-controller</code> updates the
        <code>MAC_Binding</code> table as instructed by <code>put_arp</code>
        and <code>put_nd</code> logical actions.  These changes persist beyond
        the lifetime of <code>ovn-controller</code>.
      </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>

      <dt><code>meter-table-list</code></dt>
      <dd>
        Lists each meter table entry and its local meter id.
      </dd>

      <dt><code>group-table-list</code></dt>
      <dd>
        Lists each group table entry and its local group id.
      </dd>

      <dt><code>inject-pkt</code> <var>microflow</var></dt>
      <dd>
      <p>
        Injects <var>microflow</var> into the connected Open vSwitch
        instance.  <var>microflow</var> must contain an ingress logical
        port (<code>inport</code> argument) that is present on the Open
        vSwitch instance.
      </p>

      <p>
        The <var>microflow</var> argument describes the packet whose
        forwarding is to be simulated, in the syntax of an OVN logical
        expression, as described in <code>ovn-sb</code>(5), to express
        constraints.  The parser understands prerequisites; for example,
        if the expression refers to <code>ip4.src</code>, there is no
        need to explicitly state <code>ip4</code> or <code>eth.type ==
        0x800</code>.
      </p>
      </dd>

      <dt><code>connection-status</code></dt>
      <dd>
        Show OVN SBDB connection status for the chassis.
      </dd>
      </dl>
    </p>

</manpage>