ovn-nbctl.8.xml

<?xml version="1.0" encoding="utf-8"?>
<manpage program="ovn-nbctl" section="8" title="ovn-nbctl">
    <h1>Name</h1>
    <p>ovn-nbctl -- Open Virtual Network northbound db management utility</p>

    <h1>Synopsis</h1>
    <p><code>ovn-nbctl</code> [<var>options</var>] <var>command</var> [<var>arg</var>...]</p>

    <h1>Description</h1>
    <p>This utility can be used to manage the OVN northbound database.</p>

    <h1>General Commands</h1>

    <dl>
      <dt><code>init</code></dt>
      <dd>
        Initializes the database, if it is empty.  If the database has already
        been initialized, this command has no effect.
      </dd>

      <dt><code>show [<var>switch</var> | <var>router</var>]</code></dt>
      <dd>
        Prints a brief overview of the database contents.  If
        <var>switch</var> is provided, only records related to that
        logical switch are shown. If
        <var>router</var> is provided, only records related to that
        logical router are shown.
      </dd>
    </dl>

    <h1>Logical Switch Commands</h1>

    <dl>
      <dt><code>ls-add</code></dt>
      <dd>
        <p>
          Creates a new, unnamed logical switch, which initially has no ports.
          The switch does not have a name, other commands must refer to this
          switch by its UUID.
        </p>
      </dd>

      <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>ls-add</code> <var>switch</var></dt>
      <dd>
        <p>
          Creates a new logical switch named <var>switch</var>, which
          initially has no ports.
        </p>

        <p>
          The OVN northbound database schema does not require logical switch
          names to be unique, but the whole point to the names is to provide an
          easy way for humans to refer to the switches, making duplicate names
          unhelpful.  Thus, without any options, this command regards it as an
          error if <var>switch</var> is a duplicate name.  With
          <code>--may-exist</code>, adding a duplicate name succeeds but does
          not create a new logical switch.  With <code>--add-duplicate</code>,
          the command really creates a new logical switch with a duplicate
          name.  It is an error to specify both options.  If there are multiple
          logical switches with a duplicate name, configure the logical switches
          using the UUID instead of the <var>switch</var> name.
        </p>
      </dd>

      <dt>[<code>--if-exists</code>] <code>ls-del</code> <var>switch</var></dt>
      <dd>
        Deletes <var>switch</var>.  It is an error if <var>switch</var> does
        not exist, unless <code>--if-exists</code> is specified.
      </dd>

      <dt><code>ls-list</code></dt>
      <dd>
        Lists all existing switches on standard output, one per line.
      </dd>
    </dl>

    <h1>ACL Commands</h1>
    <p>
      These commands operates on ACL objects for a given <var>entity</var>.
      The <var>entity</var> can be either a logical switch or a port group.
      The <var>entity</var> can be specified as uuid or name.  The
      <code>--type</code> option can be used to specify the type of the
      <var>entity</var>, in case both a logical switch and a port groups exist
      with the same name specified for <var>entity</var>.  <code>type</code>
      must be either <code>switch</code> or <code>port-group</code>.
    </p>
    <dl>
      <dt>[<code>--type=</code>{<code>switch</code> | <code>port-group</code>}] [<code>--log</code>] [<code>--meter=</code><var>meter</var>] [<code>--severity=</code><var>severity</var>] [<code>--name=</code><var>name</var>] [<code>--may-exist</code>] <code>acl-add</code> <var>entity</var> <var>direction</var> <var>priority</var> <var>match</var> <var>verdict</var></dt>
      <dd>
        <p>
          Adds the specified ACL to <var>entity</var>.  <var>direction</var>
          must be either <code>from-lport</code> or <code>to-lport</code>.
          <var>priority</var> must be between <code>0</code> and
          <code>32767</code>, inclusive.  A full description of the fields are
          in <code>ovn-nb</code>(5).  If <code>--may-exist</code> is specified,
          adding a duplicated ACL succeeds but the ACL is not really created.
          Without <code>--may-exist</code>, adding a duplicated ACL results in
          error.
        </p>

        <p>
          The <code>--log</code> option enables packet logging for the ACL.
          The options <code>--severity</code> and <code>--name</code> specify a
          severity and name, respectively, for log entries (and also enable
          logging).  The severity must be one of <code>alert</code>,
          <code>warning</code>, <code>notice</code>, <code>info</code>, or
          <code>debug</code>.  If a severity is not specified, the default is
          <code>info</code>.  The <code>--meter=<var>meter</var></code> option
          is used to rate-limit packet logging.  The <var>meter</var> argument
          names a meter configured by <code>meter-add</code>.
        </p>
      </dd>

      <dt>[<code>--type=</code>{<code>switch</code> | <code>port-group</code>}] <code>acl-del</code> <var>entity</var> [<var>direction</var> [<var>priority</var> <var>match</var>]]</dt>
      <dd>
        Deletes ACLs from <var>entity</var>.  If only <var>entity</var> is
        supplied, all the ACLs from the <var>entity</var> are deleted.  If
        <var>direction</var> is also specified, then all the flows in that
        direction will be deleted from the <var>entity</var>.  If all the
        fields are given, then a single flow that matches all the fields will
        be deleted.
      </dd>

      <dt>[<code>--type=</code>{<code>switch</code> | <code>port-group</code>}] <code>acl-list</code> <var>entity</var> </dt>
      <dd>
        Lists the ACLs on <var>entity</var>.
      </dd>
    </dl>

    <h1>Logical Switch QoS Rule Commands</h1>
    <dl>
      <dt>[<code>--may-exist</code>] <code>qos-add</code> <var>switch</var> <var>direction</var> <var>priority</var> <var>match</var> [<code>dscp=</code><var>dscp</var>] [<code>rate=</code><var>rate</var> [<code>burst=</code><var>burst</var>]]</dt>
      <dd>
        <p>
          Adds QoS marking and metering rules to <var>switch</var>.
          <var>direction</var> must be either <code>from-lport</code> or
          <code>to-lport</code>.  <var>priority</var> must be between
          <code>0</code> and <code>32767</code>, inclusive.
        </p>

        <p>
          If <code>dscp=</code><var>dscp</var> is specified, then
          matching packets will have DSCP marking applied.
          <var>dscp</var> must be between <code>0</code> and
          <code>63</code>, inclusive.  If <code>rate=</code><var>rate</var>
          is specified then matching packets will have metering applied
          at <var>rate</var> kbps.  If metering is configured, then
          <code>burst=</code><var>burst</var> specifies the burst rate
          limit in kilobits.  <code>dscp</code> and/or <code>rate</code>
          are required arguments.
        </p>

        <p>
          If <code>--may-exist</code> is specified, adding a duplicated
          QoS rule succeeds but the QoS rule is not really created.
          Without <code>--may-exist</code>, adding a duplicated QoS rule
          results in error.
        </p>
      </dd>

      <dt><code>qos-del</code> <var>switch</var> [<var>direction</var> [<var>priority</var> <var>match</var>]]</dt>
      <dd>
        Deletes QoS rules from <var>switch</var>.  If only
        <var>switch</var> is supplied, all the QoS rules from the logical
        switch are deleted.  If <var>direction</var> is also specified,
        then all the flows in that direction will be deleted from the
        logical switch.  If all the fields are supplied, then a single
        flow that matches the given fields will be deleted.
      </dd>

      <dt><code>qos-list</code> <var>switch</var></dt>
      <dd>
        Lists the QoS rules on <var>switch</var>.
      </dd>
    </dl>

    <h1>Meter Commands</h1>
    <dl>
        <dt><code>meter-add</code> <var>name</var> <var>action</var> <var>rate</var> <var>unit</var> [<var>burst</var>]</dt>
      <dd>
        <p>
          Adds the specified meter.  <var>name</var> must be a unique
          name to identify this meter.  The <var>action</var> argument
          specifies what should happen when this meter is exceeded.
          The only supported action is <code>drop</code>.
        </p>

        <p>
          The <var>unit</var> specifies the unit for the <var>rate</var>
          argument; valid values are <code>kbps</code> and
          <code>pktps</code> for kilobits per second and packets per
          second, respectively.  The <var>burst</var> option
          configures the maximum burst allowed for the band in kilobits
          or packets depending on whether the <var>unit</var> chosen was
          <code>kbps</code> or <code>pktps</code>, respectively.  If a
          burst is not supplied, the switch is free to select some
          reasonable value depending on its configuration.
        </p>

        <p>
          <code>ovn-nbctl</code> only supports adding a meter with a
          single band, but the other commands support meters with
          multiple bands.
        </p>

        <p>
          Names that start with "__" (two underscores) are reserved for
          internal use by OVN, so <code>ovn-nbctl</code> does not allow
          adding them.
        </p>
      </dd>

      <dt><code>meter-del</code> [<var>name</var>]</dt>
      <dd>
        <p>
          Deletes meters.  By default, all meters are deleted.  If
          <var>name</var> is supplied, only the meter with that name
          will be deleted.
      </p>
      </dd>

      <dt><code>meter-list</code></dt>
      <dd>
        <p>
          Lists all meters.
        </p>
      </dd>
    </dl>

    <h1>Logical Switch Port Commands</h1>
    <dl>
      <dt>[<code>--may-exist</code>] <code>lsp-add</code> <var>switch</var> <var>port</var></dt>
      <dd>
        <p>
          Creates on <var>lswitch</var> a new logical switch port named
          <var>port</var>.
        </p>

        <p>
          It is an error if a logical port named <var>port</var> already
          exists, unless <code>--may-exist</code> is specified.  Regardless of
          <code>--may-exist</code>, it is an error if the existing port is in
          some logical switch other than <var>switch</var> or if it has a
          parent port.
        </p>
      </dd>

      <dt>[<code>--may-exist</code>] <code>lsp-add</code> <var>switch</var> <var>port</var> <var>parent</var> <var>tag_request</var></dt>
      <dd>
        <p>
          Creates on <var>switch</var> a logical switch port named
          <var>port</var> that is a child of <var>parent</var> that is
          identified with VLAN ID <var>tag_request</var>,
          which must be between <code>0</code> and
          <code>4095</code>, inclusive. If
          <var>tag_request</var> is <code>0</code>, <code>ovn-northd</code>
          generates a tag that is unique in the scope of <var>parent</var>.
          This is useful in cases such as virtualized container environments
          where Open vSwitch does not have a direct connection to the
          container's port and it must be shared with the virtual machine's
          port.
        </p>

        <p>
          It is an error if a logical port named <var>port</var> already
          exists, unless <code>--may-exist</code> is specified.  Regardless of
          <code>--may-exist</code>, it is an error if the existing port is not
          in <var>switch</var> or if it does not have the specified
          <var>parent</var> and <var>tag_request</var>.
        </p>
      </dd>

      <dt>[<code>--if-exists</code>] <code>lsp-del</code> <var>port</var></dt>
      <dd>
        Deletes <var>port</var>.  It is an error if <var>port</var> does
        not exist, unless <code>--if-exists</code> is specified.
      </dd>

      <dt><code>lsp-list</code> <var>switch</var></dt>
      <dd>
        Lists all the logical switch ports within <var>switch</var> on
        standard output, one per line.
      </dd>

      <dt><code>lsp-get-parent</code> <var>port</var></dt>
      <dd>
        If set, get the parent port of <var>port</var>.  If not set, print
        nothing.
      </dd>

      <dt><code>lsp-get-tag</code> <var>port</var></dt>
      <dd>
        If set, get the tag for <var>port</var> traffic.  If not set, print
        nothing.
      </dd>

      <dt><code>lsp-set-addresses</code> <var>port</var> [<var>address</var>]...</dt>
      <dd>
        <p>
          Sets the addresses associated with <var>port</var> to
          <var>address</var>.  Each <var>address</var> should be one of the
          following:
        </p>

        <dl>
          <dt>an Ethernet address, optionally followed by a space and one or more IP addresses</dt>
          <dd>
            OVN delivers packets for the Ethernet address to this port.
          </dd>

          <dt><code>unknown</code></dt>
          <dd>
            OVN delivers unicast Ethernet packets whose destination MAC address
            is not in any logical port's addresses column to ports with address
            <code>unknown</code>.
          </dd>

          <dt><code>dynamic</code></dt>
          <dd>
            Use this keyword to make <code>ovn-northd</code> generate a
            globally unique MAC address and choose an unused IPv4 address with
            the logical port's subnet and store them in the port's
            <code>dynamic_addresses</code> column.
          </dd>

          <dt><code>router</code></dt>
          <dd>
            Accepted only when the <code>type</code> of the logical switch
            port is <code>router</code>.  This indicates that the Ethernet,
            IPv4, and IPv6 addresses for this logical switch port should be
            obtained from the connected logical router port, as specified by
            <code>router-port</code> in <code>lsp-set-options</code>.
          </dd>
        </dl>

        <p>
          Multiple addresses may be set.  If no <var>address</var> argument is
          given, <var>port</var> will have no addresses associated with it.
        </p>
      </dd>

      <dt><code>lsp-get-addresses</code> <var>port</var></dt>
      <dd>
        Lists all the addresses associated with <var>port</var> on standard
        output, one per line.
      </dd>

      <dt><code>lsp-set-port-security</code> <var>port</var> [<var>addrs</var>]...</dt>
      <dd>
        <p>
          Sets the port security addresses associated with <var>port</var> to
          <var>addrs</var>.  Multiple sets of addresses may be set by using
          multiple <var>addrs</var> arguments.  If no <var>addrs</var> argument
          is given, <var>port</var> will not have port security enabled.
        </p>

        <p>
          Port security limits the addresses from which a logical port may send
          packets and to which it may receive packets.  See the
          <code>ovn-nb</code>(5) documentation for the <ref
          column="port_security" table="Logical_Switch_Port"/> column in
          the <ref table="Logical_Switch_Port"/> table for details.
        </p>
      </dd>

      <dt><code>lsp-get-port-security</code> <var>port</var></dt>
      <dd>
        Lists all the port security addresses associated with <var>port</var>
        on standard output, one per line.
      </dd>

      <dt><code>lsp-get-up</code> <var>port</var></dt>
      <dd>
        Prints the state of <var>port</var>, either <code>up</code> or
        <code>down</code>.
      </dd>

      <dt><code>lsp-set-enabled</code> <var>port</var> <var>state</var></dt>
      <dd>
        Set the administrative state of <var>port</var>, either <code>enabled</code>
        or <code>disabled</code>.  When a port is disabled, no traffic is allowed into
        or out of the port.
      </dd>

      <dt><code>lsp-get-enabled</code> <var>port</var></dt>
      <dd>
        Prints the administrative state of <var>port</var>, either <code>enabled</code>
        or <code>disabled</code>.
      </dd>

      <dt><code>lsp-set-type</code> <var>port</var> <var>type</var></dt>
      <dd>
        <p>
          Set the type for the logical port.  The type must be one of the following:
        </p>

        <dl>
          <dt><code>(empty string)</code></dt>
          <dd>
            A VM (or VIF) interface.
          </dd>

          <dt><code>router</code></dt>
          <dd>
            A connection to a logical router.
          </dd>

          <dt><code>localnet</code></dt>
          <dd>
            A connection to a locally accessible network from each ovn-controller
            instance. A logical switch can only have a single localnet port
            attached. This is used to model direct connectivity to an existing
            network.
          </dd>

          <dt><code>localport</code></dt>
          <dd>
            A connection to a local VIF. Traffic that arrives on a localport is
            never forwarded over a tunnel to another chassis. These ports are
            present on every chassis and have the same address in all of them.
            This is used to model connectivity to local services that run on
            every hypervisor.
          </dd>

          <dt><code>l2gateway</code></dt>
          <dd>
            A connection to a physical network.
          </dd>

          <dt><code>vtep</code></dt>
          <dd>
            A port to a logical switch on a VTEP gateway.
          </dd>
        </dl>

      </dd>

      <dt><code>lsp-get-type</code> <var>port</var></dt>
      <dd>
        Get the type for the logical port.
      </dd>

      <dt><code>lsp-set-options</code> <var>port</var> [<var>key=value</var>]...</dt>
      <dd>
        Set type-specific key-value options for the logical port.
      </dd>

      <dt><code>lsp-get-options</code> <var>port</var></dt>
      <dd>
        Get the type-specific options for the logical port.
      </dd>

      <dt><code>lsp-set-dhcpv4-options</code> <var>port</var>
          <var>dhcp_options</var></dt>
      <dd>
        Set the DHCPv4 options for the logical port.  The
        <var>dhcp_options</var> is a UUID referring to a set of DHCP options in
        the <ref table="DHCP_Options" /> table.
      </dd>

      <dt><code>lsp-get-dhcpv4-optoins</code> <var>port</var></dt>
      <dd>
        Get the configured DHCPv4 options for the logical port.
      </dd>

      <dt><code>lsp-set-dhcpv6-options</code> <var>port</var>
          <var>dhcp_options</var></dt>
      <dd>
          Set the DHCPv6 options for the logical port.  The
          <var>dhcp_options</var> is a UUID referring to a set of DHCP options
          in the <ref table="DHCP_Options" /> table.
      </dd>

      <dt><code>lsp-get-dhcpv6-optoins</code> <var>port</var></dt>
      <dd>
        Get the configured DHCPv6 options for the logical port.
      </dd>

    </dl>

    <h1>Logical Router Commands</h1>

    <dl>
      <dt><code>lr-add</code></dt>
      <dd>
        <p>
          Creates a new, unnamed logical router, which initially has no ports.
          The router does not have a name, other commands must refer to this
          router by its UUID.
        </p>
      </dd>

      <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>lr-add</code> <var>router</var></dt>
      <dd>
        <p>
          Creates a new logical router named <var>router</var>, which
          initially has no ports.
        </p>

        <p>
          The OVN northbound database schema does not require logical router
          names to be unique, but the whole point to the names is to provide an
          easy way for humans to refer to the routers, making duplicate names
          unhelpful.  Thus, without any options, this command regards it as an
          error if <var>router</var> is a duplicate name.  With
          <code>--may-exist</code>, adding a duplicate name succeeds but does
          not create a new logical router.  With <code>--add-duplicate</code>,
          the command really creates a new logical router with a duplicate
          name.  It is an error to specify both options.  If there are multiple
          logical routers with a duplicate name, configure the logical routers
          using the UUID instead of the <var>router</var> name.
        </p>
      </dd>

      <dt>[<code>--if-exists</code>] <code>lr-del</code> <var>router</var></dt>
      <dd>
        Deletes <var>router</var>.  It is an error if <var>router</var> does
        not exist, unless <code>--if-exists</code> is specified.
      </dd>

      <dt><code>lr-list</code></dt>
      <dd>
        Lists all existing routers on standard output, one per line.
      </dd>
    </dl>

    <h1>Logical Router Port Commands</h1>

    <dl>
      <dt>[<code>--may-exist</code>] <code>lrp-add</code> <var>router</var> <var>port</var> <var>mac</var> <var>network</var>... [<code>peer=</code><var>peer</var>]</dt>
      <dd>
        <p>
          Creates on <var>router</var> a new logical router port named
          <var>port</var> with Ethernet address <var>mac</var> and one
          or more IP address/netmask for each <var>network</var>.
        </p>

        <p>
          The optional argument <code>peer</code> identifies a logical
          router port that connects to this one.  The following example
          adds a router port with an IPv4 and IPv6 address with peer
          <code>lr1</code>:
        </p>

        <p>
          <code>lrp-add lr0 lrp0 00:11:22:33:44:55 192.168.0.1/24 2001:db8::1/64 peer=lr1</code>
        </p>

        <p>
          It is an error if a logical router port named <var>port</var>
          already exists, unless <code>--may-exist</code> is specified.
          Regardless of <code>--may-exist</code>, it is an error if the
          existing router port is in some logical router other than
          <var>router</var>.
        </p>
      </dd>

      <dt>[<code>--if-exists</code>] <code>lrp-del</code> <var>port</var></dt>
      <dd>
        Deletes <var>port</var>.  It is an error if <var>port</var> does
        not exist, unless <code>--if-exists</code> is specified.
      </dd>

      <dt><code>lrp-list</code> <var>router</var></dt>
      <dd>
        Lists all the logical router ports within <var>router</var> on
        standard output, one per line.
      </dd>

      <dt><code>lrp-set-enabled</code> <var>port</var> <var>state</var></dt>
      <dd>
        Set the administrative state of <var>port</var>, either
        <code>enabled</code> or <code>disabled</code>.  When a port is
        disabled, no traffic is allowed into or out of the port.
      </dd>

      <dt><code>lrp-get-enabled</code> <var>port</var></dt>
      <dd>
        Prints the administrative state of <var>port</var>, either
        <code>enabled</code> or <code>disabled</code>.
      </dd>

      <dt><code>lrp-set-gateway-chassis</code> <var>port</var>
          <var>chassis</var> [<var>priority</var>]</dt>
      <dd>
        Set gateway chassis for <var>port</var>. <var>chassis</var>
        is the name of the chassis. This creates a gateway chassis entry
        in Gateway_Chassis table. It won't check if chassis really exists
        in OVN_Southbound database. Priority will be set to 0
        if <var>priority</var> is not provided by user. <var>priority</var>
        must be between <code>0</code> and <code>32767</code>, inclusive.
      </dd>
      <dt><code>lrp-del-gateway-chassis</code> <var>port</var>
          <var>chassis</var></dt>
      <dd>
        Deletes gateway chassis from <var>port</var>.  It is an error if
        gateway chassis with <var>chassis</var> for <var>port</var> does
        not exist.
      </dd>
      <dt><code>lrp-get-gateway-chassis</code> <var>port</var></dt>
      <dd>
        Lists all the gateway chassis with priority within <var>port</var> on
        standard output, one per line, ordered based on priority.
      </dd>
    </dl>

    <h1>Logical Router Static Route Commands</h1>

    <dl>
      <dt>[<code>--may-exist</code>] [<code>--policy</code>=<var>POLICY</var>] <code>lr-route-add</code> <var>router</var> <var>prefix</var> <var>nexthop</var> [<var>port</var>]</dt>
      <dd>
        <p>
          Adds the specified route to <var>router</var>.
          <var>prefix</var> describes an IPv4 or IPv6 prefix for this
          route, such as <code>192.168.100.0/24</code>.
          <var>nexthop</var> specifies the gateway to use for this
          route, which should be the IP address of one of
          <var>router</var> logical router ports or the IP address of a
          logical port.  If <var>port</var> is specified, packets that
          match this route will be sent out that port.  When
          <var>port</var> is omitted, OVN infers the output port based
          on <var>nexthop</var>.
        </p>

        <p>
          <code>--policy</code> describes the policy used to make routing
          decisions.  This should be one of "dst-ip" or "src-ip".  If not
          specified, the default is "dst-ip".
        </p>

        <p>
          It is an error if a route with <var>prefix</var> already exists,
          unless <code>--may-exist</code> is specified.
        </p>
      </dd>

      <dt>[<code>--if-exists</code>] <code>lr-route-del</code> <var>router</var> [<var>prefix</var>]</dt>
      <dd>
        <p>
          Deletes routes from <var>router</var>.  If only <var>router</var>
          is supplied, all the routes from the logical router are
          deleted.  If <var>prefix</var> is also specified, then all the
          routes that match the prefix will be deleted from the logical
          router.
        </p>

        <p>
          It is an error if <var>prefix</var> is specified and there
          is no matching route entry, unless <code>--if-exists</code> is
          specified.
        </p>
      </dd>

      <dt><code>lr-route-list</code> <var>router</var></dt>
      <dd>
        Lists the routes on <var>router</var>.
      </dd>
    </dl>

    <h1>NAT Commands</h1>

    <dl>
      <dt>[<code>--may-exist</code>] <code>lr-nat-add</code> <var>router</var> <var>type</var> <var>external_ip</var> <var>logical_ip</var> [<var>logical_port</var> <var>external_mac</var>]</dt>
      <dd>
        <p>
          Adds the specified NAT to <var>router</var>.
          The <var>type</var> must be one of <code>snat</code>,
          <code>dnat</code>, or <code>dnat_and_snat</code>.
          The <var>external_ip</var> is an IPv4 address.
          The <var>logical_ip</var> is an IPv4 network (e.g 192.168.1.0/24)
          or an IPv4 address.
          The <var>logical_port</var> and <var>external_mac</var> are only
          accepted when <var>router</var> is a distributed router (rather
          than a gateway router) and <var>type</var> is
          <code>dnat_and_snat</code>.
          The <var>logical_port</var> is the name of an existing logical
          switch port where the <var>logical_ip</var> resides.
          The <var>external_mac</var> is an Ethernet address.
        </p>
        <p>
          When <var>type</var> is <code>dnat</code>, the externally
          visible IP address <var>external_ip</var> is DNATted to the
          IP address <var>logical_ip</var> in the logical space.
        </p>
        <p>
          When <var>type</var> is <code>snat</code>, IP packets with their
          source IP address that either matches the IP address in
          <var>logical_ip</var> or is in the network provided by
          <var>logical_ip</var> is SNATed into the IP address in
          <var>external_ip</var>.
        </p>
        <p>
          When <var>type</var> is <code>dnat_and_snat</code>,
          the externally visible IP address <var>external_ip</var>
          is DNATted to the IP address <var>logical_ip</var> in
          the logical space.  In addition, IP packets with the source
          IP address that matches <var>logical_ip</var> is SNATed into
          the IP address in <var>external_ip</var>.
        </p>
        <p>
          When the <var>logical_port</var> and <var>external_mac</var>
          are specified, the NAT rule will be programmed on the chassis
          where the <var>logical_port</var> resides.  This includes
          ARP replies for the <var>external_ip</var>, which return the
          value of <var>external_mac</var>.  All packets transmitted
          with source IP address equal to <var>external_ip</var> will
          be sent using the <var>external_mac</var>.
        </p>
        <p>
          It is an error if a NAT already exists with the same values
          of <var>router</var>, <var>type</var>, <var>external_ip</var>,
          and <var>logical_ip</var>, unless <code>--may-exist</code> is
          specified.  When <code>--may-exist</code>,
          <var>logical_port</var>, and <var>external_mac</var> are all
          specified, the existing values of <var>logical_port</var> and
          <var>external_mac</var> are overwritten.
        </p>
      </dd>

      <dt>[<code>--if-exists</code>] <code>lr-nat-del</code> <var>router</var> [<var>type</var> [<var>ip</var>]]</dt>
      <dd>
        <p>
          Deletes NATs from <var>router</var>.  If only <var>router</var>
          is supplied, all the NATs from the logical router are
          deleted.  If <var>type</var> is also specified, then all the
          NATs that match the <var>type</var> will be deleted from the logical
          router.  If all the fields are given, then a single NAT rule
          that matches all the fields will be deleted.  When <var>type</var>
          is <code>snat</code>, the <var>ip</var> should be logical_ip.
          When <var>type</var> is <code>dnat</code> or
          <code>dnat_and_snat</code>, the <var>ip</var> shoud be external_ip.
        </p>

        <p>
          It is an error if <var>ip</var> is specified and there
          is no matching NAT entry, unless <code>--if-exists</code> is
          specified.
        </p>
      </dd>

      <dt><code>lr-nat-list</code> <var>router</var></dt>
      <dd>
        Lists the NATs on <var>router</var>.
      </dd>
    </dl>

    <h1>Load Balancer Commands</h1>
    <dl>
      <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>lb-add</code> <var>lb</var> <var>vip</var> <var>ips</var> [<var>protocol</var>]</dt>
      <dd>
        <p>
         Creates a new load balancer named <var>lb</var> with the provided
         <var>vip</var> and <var>ips</var> or adds the <var>vip</var> to
         an existing <var>lb</var>.  <var>vip</var> should be a
         virtual IP address (or an IP address and a port number with
         <code>:</code> as a separator).  Examples for <var>vip</var> are
         <code>192.168.1.4</code>, <code>fd0f::1</code>, and
         <code>192.168.1.5:8080</code>. <var>ips</var> should be comma
         separated IP endpoints (or comma separated IP addresses and port
         numbers with <code>:</code> as a separator).  <var>ips</var> must
         be the same address family as <var>vip</var>.  Examples for
         <var>ips</var> are <code>10.0.0.1,10.0.0.2</code>or
         <code>[fdef::1]:8800,[fdef::2]:8800</code>.
        </p>

        <p>
         The optional argument <var>protocol</var> must be either
         <code>tcp</code> or <code>udp</code>.  This argument is useful when
         a port number is provided as part of the <var>vip</var>.  If the
         <var>protocol</var> is unspecified and a port number is provided as
         part of the <var>vip</var>, OVN assumes the <var>protocol</var> to
         be <code>tcp</code>.
        </p>

        <p>
         It is an error if the <var>vip</var> already exists in the load
         balancer named <var>lb</var>, unless <code>--may-exist</code> is
         specified.  With <code>--add-duplicate</code>, the command really
         creates a new load balancer with a duplicate name.
        </p>

        <p>
         The following example adds a load balancer.
        </p>

        <p>
         <code>lb-add lb0 30.0.0.10:80
         192.168.10.10:80,192.168.10.20:80,192.168.10.30:80 udp</code>
        </p>
      </dd>

      <dt>[<code>--if-exists</code>] <code>lb-del</code> <var>lb</var> [<var>vip</var>]</dt>
      <dd>
        Deletes <var>lb</var> or the <var>vip</var> from <var>lb</var>.
        If <var>vip</var> is supplied, only the <var>vip</var> will be
        deleted from the <var>lb</var>.  If only the <var>lb</var> is supplied,
        the <var>lb</var> will be deleted.  It is an error if <var>vip</var>
        does not already exist in <var>lb</var>, unless
        <code>--if-exists</code> is specified.
      </dd>

      <dt><code>lb-list</code> [<var>lb</var>]</dt>
      <dd>
        Lists the LBs.  If <var>lb</var> is also specified, then only the
        specified <var>lb</var> will be listed.
      </dd>

      <dt>[<code>--may-exist</code>] <code>ls-lb-add</code> <var>switch</var> <var>lb</var></dt>
      <dd>
        Adds the specified <var>lb</var> to <var>switch</var>.
        It is an error if a load balancer named <var>lb</var> already exists
        in the <var>switch</var>, unless <code>--may-exist</code> is specified.
      </dd>

      <dt>[<code>--if-exists</code>] <code>ls-lb-del</code> <var>switch</var> [<var>lb</var>]</dt>
      <dd>
        Removes <var>lb</var> from <var>switch</var>.  If only
        <var>switch</var> is supplied, all the LBs from the logical switch are
        removed.  If <var>lb</var> is also specified, then only the
        <var>lb</var> will be removed from the logical switch.
        It is an error if <var>lb</var> does not exist in the
        <var>switch</var>, unless <code>--if-exists</code> is specified.
      </dd>

      <dt><code>ls-lb-list</code> <var>switch</var></dt>
      <dd>
        Lists the LBs for the given <var>switch</var>.
      </dd>

      <dt>[<code>--may-exist</code>] <code>lr-lb-add</code> <var>router</var> <var>lb</var></dt>
      <dd>
        Adds the specified <var>lb</var> to <var>router</var>.
        It is an error if a load balancer named <var>lb</var> already exists
        in the <var>router</var>, unless <code>--may-exist</code> is specified.
      </dd>

      <dt>[<code>--if-exists</code>] <code>lr-lb-del</code> <var>router</var> [<var>lb</var>]</dt>
      <dd>
        Removes <var>lb</var> from <var>router</var>.  If only
        <var>router</var> is supplied, all the LBs from the logical router are
        removed.  If <var>lb</var> is also specified, then only the
        <var>lb</var> will be removed from the logical router.
        It is an error if <var>lb</var> does not exist in the
        <var>router</var>, unless <code>--if-exists</code> is specified.
      </dd>

      <dt><code>lr-lb-list</code> <var>router</var></dt>
      <dd>
        Lists the LBs for the given <var>router</var>.
      </dd>
    </dl>


    <h1>DHCP Options commands</h1>

    <dl>
      <dt><code>dhcp-options-create</code> <var>cidr</var> [<var>key=value</var>]</dt>
      <dd>
        Creates a new DHCP Options entry in the <code>DHCP_Options</code> table
        with the specified <code>cidr</code> and optional <code>external-ids</code>.
      </dd>

      <dt><code>dhcp-options-list</code></dt>
      <dd>
        Lists the DHCP Options entries.
      </dd>

      <dt><code>dhcp-options-del</code> <var>dhcp-option</var></dt>
      <dd>
        Deletes the DHCP Options entry referred by <var>dhcp-option</var> UUID.
      </dd>

      <dt><code>dhcp-options-set-options</code> <var>dhcp-option</var> [<var>key=value</var>]...</dt>
      <dd>
        Set the DHCP Options for the <var>dhcp-option</var> UUID.
      </dd>

      <dt><code>dhcp-options-get-options</code> <var>dhcp-option</var></dt>
      <dd>
        Lists the DHCP Options for the <var>dhcp-option</var> UUID.
      </dd>
    </dl>

    <h1>Port Group commands</h1>

    <dl>
      <dt><code>pg-add</code> <var>group</var> [<var>port</var>]...</dt>
      <dd>
        Creates a new port group in the <code>Port_Group</code> table named
        <code>group</code> with optional <code>ports</code> added to the group.
      </dd>

      <dt><code>pg-set-ports</code> <var>group</var> <var>port</var>...</dt>
      <dd>
        Sets <code>ports</code> on the port group named <code>group</code>. It
        is an error if <code>group</code> does not exist.
      </dd>

      <dt><code>pg-del</code> <var>group</var></dt>
      <dd>
        Deletes port group <code>group</code>. It is an error if
        <code>group</code> does not exist.
      </dd>
    </dl>

    <h1>Database Commands</h1>
    <p>These commands query and modify the contents of <code>ovsdb</code> tables.
    They are a slight abstraction of the <code>ovsdb</code> interface and
    as such they operate at a lower level than other <code>ovn-nbctl</code> commands.</p>
    <p><var>Identifying Tables, Records, and Columns</var></p>
    <p>Each of these commands has a <var>table</var> parameter to identify a table
    within the database.  Many of them also take a <var>record</var> parameter
    that identifies a particular record within a table.  The <var>record</var>
    parameter may be the UUID for a record, which may be abbreviated to its
    first 4 (or more) hex digits, as long as that is unique.  Many tables offer
    additional ways to identify records.  Some commands also take
    <var>column</var> parameters that identify a particular field within the
    records in a table.</p>

    <p>
      For a list of tables and their columns, see <code>ovn-nb</code>(5) or
      see the table listing from the <code>--help</code> option.
    </p>

    <p>
      Record names must be specified in full and with correct capitalization,
      except that UUIDs may be abbreviated to their first 4 (or more) hex
      digits, as long as that is unique within the table.  Names of tables and
      columns are not case-sensitive, and <code>-</code> and <code>_</code> are
      treated interchangeably.  Unique abbreviations of table and column names
      are acceptable, e.g. <code>d</code> or <code>dhcp</code> is sufficient
      to identify the <code>DHCP_Options</code> table.
    </p>

    <xi:include href="lib/db-ctl-base.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

    <h1>Synchronization Commands</h1>

    <dl>
      <dt>sync</dt>
      <dd>
        Ordinarily, <code>--wait=sb</code> or <code>--wait=hv</code> only waits
        for changes by the current <code>ovn-nbctl</code> invocation to take
        effect.  This means that, if none of the commands supplied to
        <code>ovn-nbctl</code> change the database, then the command does not
        wait at all.  With the <code>sync</code> command, however,
        <code>ovn-nbctl</code> waits even for earlier changes to the database
        to propagate down to the southbound database or all of the OVN chassis,
        according to the argument to <code>--wait</code>.
      </dd>
    </dl>

    <h1>Remote Connectivity Commands</h1>
    <dl>
      <dt><code>get-connection</code></dt>
      <dd>
      Prints the configured connection(s).
      </dd>

      <dt><code>del-connection</code></dt>
      <dd>
      Deletes the configured connection(s).
      </dd>

      <dt>[<code>--inactivity-probe=</code><var>msecs</var>] <code>set-connection</code> <var>target</var>...</dt>
      <dd>
        Sets the configured manager target or targets.  Use
        <code>--inactivity-probe=</code><var>msecs</var> to override the default
        idle connection inactivity probe time.  Use 0 to disable inactivity probes.
      </dd>
    </dl>

    <h1>SSL Configuration Commands</h1>
    <dl>
      <dt><code>get-ssl</code></dt>
      <dd>
      Prints the SSL configuration.
      </dd>

      <dt><code>del-ssl</code></dt>
      <dd>
      Deletes the current SSL configuration.
      </dd>

      <dt>[<code>--bootstrap</code>] <code>set-ssl</code>
         <var>private-key</var> <var>certificate</var> <var>ca-cert</var>
         [<var>ssl-protocol-list</var> [<var>ssl-cipher-list</var>]]</dt>
      <dd>
      Sets the SSL configuration.
      </dd>
    </dl>

    <h1>Daemon Mode</h1>

    <p>
      When it is invoked in the most ordinary way, <code>ovn-nbctl</code>
      connects to an OVSDB server that hosts the northbound database, retrieves
      a partial copy of the database that is complete enough to do its work,
      sends a transaction request to the server, and receives and processes the
      server's reply.  In common interactive use, this is fine, but if the
      database is large, the step in which <code>ovn-nbctl</code> retrieves a
      partial copy of the database can take a long time, which yields poor
      performance overall.
    </p>

    <p>
      To improve performance in such a case, <code>ovn-nbctl</code> offers a
      "daemon mode," in which the user first starts <code>ovn-nbctl</code>
      running in the background and afterward uses the daemon to execute
      operations.  Over several <code>ovn-nbctl</code> command invocations,
      this performs better overall because it retrieves a copy of the database
      only once at the beginning, not once per program run.
    </p>

    <p>
      Use the <code>--detach</code> option to start an <code>ovn-nbctl</code>
      daemon.  With this option, <code>ovn-nbctl</code> prints the name of a
      control socket to stdout.  The client should save this name in
      environment variable <env>OVN_NB_DAEMON</env>.  Under the Bourne shell
      this might be done like this:
    </p>

    <pre fixed="yes">
      export OVN_NB_DAEMON=$(ovn-nbctl --pidfile --detach)
    </pre>

    <p>
      When <env>OVN_NB_DAEMON</env> is set, <code>ovn-nbctl</code>
      automatically and transparently uses the daemon to execute its commands.
    </p>

    <p>
      When the daemon is no longer needed, kill it and unset the environment
      variable, e.g.:
    </p>

    <pre fixed="yes">
      kill $(cat /var/run/ovn-nbctl.pid)
      unset OVN_NB_DAEMON
    </pre>

    <p>
      Daemon mode is experimental.
    </p>

    <h2>Daemon Commands</h2>

    <p>
      Daemon mode is internally implemented using the same mechanism used by
      <code>ovs-appctl</code>.  One may also use <code>ovs-appctl</code>
      directly with the following commands:
    </p>

    <dl>
      <dt>
        <code>run</code> [<var>options</var>] <var>command</var>
        [<var>arg</var>...] [<code>--</code> [<var>options</var>]
        <var>command</var> [<var>arg</var>...] ...]
      </dt>
      <dd>
        Instructs the daemon process to run one or more <code>ovn-nbctl</code>
        commands described above and reply with the results of running these
        commands. Accepts the <code>--no-wait</code>, <code>--wait</code>,
        <code>--timeout</code>, <code>--dry-run</code>, <code>--oneline</code>,
        and the options described under <code>Table Formatting Options</code>
        in addition to the the command-specific options.
      </dd>

      <dt><code>exit</code></dt>
      <dd>Causes <code>ovn-nbctl</code> to gracefully terminate.</dd>
    </dl>

    <h1>Options</h1>

    <dl>
      <dt><code>--no-wait</code> | <code>--wait=none</code></dt>
      <dt><code>--wait=sb</code></dt>
      <dt><code>--wait=hv</code></dt>

      <dd>
        <p>
          These options control whether and how <code>ovn-nbctl</code> waits
          for the OVN system to become up-to-date with changes made in an
          <code>ovn-nbctl</code> invocation.
        </p>

        <p>
          By default, or if <code>--no-wait</code> or <code>--wait=none</code>,
          <code>ovn-nbctl</code> exits immediately after confirming that
          changes have been committed to the northbound database, without
          waiting.
        </p>

        <p>
          With <code>--wait=sb</code>, before <code>ovn-nbctl</code> exits, it
          waits for <code>ovn-northd</code> to bring the southbound database
          up-to-date with the northbound database updates.
        </p>

        <p>
          With <code>--wait=hv</code>, before <code>ovn-nbctl</code> exits, it
          additionally waits for all OVN chassis (hypervisors and gateways) to
          become up-to-date with the northbound database updates.  (This can
          become an indefinite wait if any chassis is malfunctioning.)
        </p>

        <p>
          Ordinarily, <code>--wait=sb</code> or <code>--wait=hv</code> only
          waits for changes by the current <code>ovn-nbctl</code> invocation to
          take effect.  This means that, if none of the commands supplied to
          <code>ovn-nbctl</code> change the database, then the command does not
          wait at all.  Use the <code>sync</code> command to override this
          behavior.
        </p>
      </dd>

    <dt><code>--db</code> <var>database</var></dt>
    <dd>
      The OVSDB database remote to contact.  If the <env>OVN_NB_DB</env>
      environment variable is set, its value is used as the default.
      Otherwise, the default is <code>unix:@RUNDIR@/ovnnb_db.sock</code>, but this
      default is unlikely to be useful outside of single-machine OVN test
      environments.
    </dd>

    <dt><code>--leader-only</code></dt>
    <dt><code>--no-leader-only</code></dt>
    <dd>
      By default, or with <code>--no-leader-only</code>, when the database
      server is a clustered database, <code>ovn-nbctl</code> will use any server
      in the cluster, which means that for read-only transactions it can report
      and act on stale data (transactions that modify the database are always
      serialized even with <code>--no-leader-only</code>). With
      <code>--leader-only</code>, <code>ovn-nbctl</code> will avoid servers other
      than the cluster leader.  This ensures that any data that
      <code>ovn-nbctl</code> reads and reports is up-to-date. Refer to
      <code>Understanding Cluster Consistency</code> in <code>ovsdb</code>(7)
      for more information.
    </dd>
    </dl>

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

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

    <h1>Table Formatting Options</h1>
    These options control the format of output from the <code>list</code> and
    <code>find</code> commands.
    <xi:include href="lib/table.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

    <h2>PKI Options</h2>
    <p>
      PKI configuration is required to use SSL for the connection to the
      database.
    </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"/>

    <h2>Other Options</h2>

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

</manpage>