util: New function nullable_xstrdup().

[mirror_ovs.git] / ovn / utilities / 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>Synopsys</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>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.
        </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>Logical Switch ACL Commands</h1>
    <dl>
      <dt>[<code>--log</code>] <code>acl-add</code> <var>switch</var> <var>direction</var> <var>priority</var> <var>match</var> <var>action</var></dt>
      <dd>
        Adds the specified ACL 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>1</code> and <code>65534</code>, inclusive.  If
        <code>--log</code> is specified, packet logging is enabled for the
        ACL.  A full description of the fields are in <code>ovn-nb</code>(5).
      </dd>

      <dt><code>acl-del</code> <var>switch</var> [<var>direction</var> [<var>priority</var> <var>match</var>]]</dt>
      <dd>
        Deletes ACLs from <var>switch</var>.  If only
        <var>switch</var> is supplied, all the ACLs 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 given, then a single flow
        that matches all the fields will be deleted.
      </dd>

      <dt><code>acl-list</code> <var>switch</var></dt>
      <dd>
        Lists the ACLs on <var>switch</var>.
      </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</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
          identifed with VLAN ID <var>tag</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</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>
        Sets the addresses associated with <var>port</var> to
        <var>address</var>.  Each <var>address</var> should be either an
        Ethernet address or an Ethernet address followed by an IP address
        (separated by a space and quoted to form a single command-line
        argument).  The special form <code>unknown</code> is also valid.
        Multiple Ethernet addresses or Ethernet+IP pairs may be set. If no
        <var>address</var> argument is given, <var>port</var> will have no
        addresses associated with it.
      </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>
        Set the type for the logical port.  No special types have been implemented yet.
      </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>

    </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.
        </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> [<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 IP
          address/netmask <var>network</var>.  If <var>peer</var> is
          specified, it identifies a logical router port that connects
          to this one.
        </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>
    </dl>

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

    <dl>
      <dt>[<code>--may-exist</code>] <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>
          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 <code>prefix</code> 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>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 suchthey 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, and 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>The following tables are currently defined:</p>
    <dl>
      <dt><code>Logical_Switch</code></dt>
      <dd>
        An L2 logical switch.  Records may be identified by name.
      </dd>

      <dt><code>Logical_Switch_Port</code></dt>
      <dd>
        A port within an L2 logical switch.  Records may be identified by name.
      </dd>

      <dt><code>ACL</code></dt>
      <dd>
        An ACL rule for a logical switch that points to it through its <var>acls</var> column.
      </dd>

      <dt><code>Logical_Router</code></dt>
      <dd>
        An L3 logical router.  Records may be identified by name.
      </dd>

      <dt><code>Logical_Router_Port</code></dt>
      <dd>
        A port within an L3 logical router.  Records may be identified by name.
      </dd>

    <dt><code>Logical_Router_Static_Route</code></dt>
    <dd>
      A static route belonging to an L3 logical router.
    </dd>

    </dl>

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

    <h1>Options</h1>

    <dl>
    <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@/db.sock</code>, but this
      default is unlikely to be useful outside of single-machine OVN test
      environments.
    </dd>

    <dt><code>-h</code> | <code>--help</code></dt>
    <dt><code>-o</code> | <code>--options</code></dt>
    <dt><code>-V</code> | <code>--version</code></dt>
    </dl>

    <h1>Logging options</h1>
    <dl>
    <dt><code>-v</code><var>spec</var>, <code>--verbose=</code><var>spec</var></dt>
    <dt><code>-v</code>, <code>--verbose</code></dt>
    <dt><code>--log-file</code>[<code>=</code><var>file</var>]</dt>
    <dt><code>--syslog-target=</code><var>host</var><code>:</code><var>port</var></dt>
    </dl>

    <h1>PKI configuration (required to use SSL)</h1>
    <dl>
    <dt><code>-p</code>, <code>--private-key=</code><var>file</var>  file with private key</dt>
    <dt><code>-c</code>, <code>--certificate=</code><var>file</var>  file with certificate for private key</dt>
    <dt><code>-C</code>, <code>--ca-cert=</code><var>file</var>      file with peer CA certificate</dt>
    </dl>

</manpage>