ovn-controller: Avoid overlooking changes that occur during commit.

[mirror_ovs.git] / ovn / 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>lswitch</var>]</code></dt>
      <dd>
        Prints a brief overview of the database contents.  If
        <var>lswitch</var> is provided, only records related to that
        logical switch are shown.
      </dd>
    </dl>

    <h1>Logical Switch Commands</h1>

    <dl>
      <dt><code>lswitch-add</code> [<var>lswitch</var>]</dt>
      <dd>
        Creates a new logical switch named <var>lswitch</var>.  If
        <var>lswitch</var> is not provided, the switch will not have a
        name so other commands must refer to this switch by its UUID.
        Initially the switch will have no ports.
      </dd>

      <dt><code>lswitch-del</code> <var>lswitch</var></dt>
      <dd>
        Deletes <var>lswitch</var>.
      </dd>

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

      <dt><code>lswitch-set-external-id</code> <var>lswitch</var> <var>key</var> [<var>value</var>]</dt>
      <dd>
        <p>Sets or clears an ``external ID'' value on <var>lswitch</var>.
        These values are intended to identify entities external to OVN
        with which <var>lswitch</var> is associated.  The OVN Northbound
        database schema may specify well-known <var>key</var> values,
        but <var>key</var> and <var>value</var> are otherwise arbitrary
        strings.</p>

        <p>If <var>value</var> is specified, then <var>key</var> is set to
        <var>value</var> for <var>lswitch</var>, overwriting any
        previous value.  If <var>value</var> is omitted, then
        <var>key</var> is removed from <var>lswitch</var>'s set of
        external IDs (if it was present.</p>
       </dd>

      <dt><code>lswitch-get-external-id</code> <var>lswitch</var> [<var>key</var>]</dt>
      <dd>
        Queries the external IDs on <var>lswitch</var>.  If
        <var>key</var> is specified, the output is the value for that
        <var>key</var> or the empty string if <var>key</var> is unset.
        If <var>key</var> is omitted, the output is
        <var>key</var><code>=</code><var>value</var>, one per line, for
        each key-value pair.
      </dd>
    </dl>

    <h1>Logical Port Commands</h1>
    <dl>
      <dt><code>lport-add</code> <var>lswitch</var> <var>lport</var></dt>
      <dd>
        Creates on <var>lswitch</var> a new logical port named
        <var>lport</var>.
      </dd>

      <dt><code>lport-add</code> <var>lswitch</var> <var>lport</var> <var>parent</var> <var>tag</var></dt>
      <dd>
        Creates on <var>lswitch</var> a logical port named <var>lport</var>
        that is a child of <var>parent</var> that is identied with
        <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.
      </dd>

      <dt><code>lport-del</code> <var>lport</var></dt>
      <dd>
        Deletes <var>lport</var>.
      </dd>

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

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

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

      <dt><code>lport-set-external-id</code> <var>lport</var> <var>key</var> [<var>value</var>]</dt>
      <dd>
        <p>Sets or clears an ``external ID'' value on <var>lport</var>.
        These values are intended to identify entities external to OVN
        with which <var>lport</var> is associated.  The OVN Northbound
        database schema may specify well-known <var>key</var> values,
        but <var>key</var> and <var>value</var> are otherwise arbitrary
        strings.</p>

        <p>If <var>value</var> is specified, then <var>key</var> is set to
        <var>value</var> for <var>lport</var>, overwriting any
        previous value.  If <var>value</var> is omitted, then
        <var>key</var> is removed from <var>lport</var>'s set of
        external IDs (if it was present.</p>
      </dd>

      <dt><code>lport-get-external-id</code> <var>lport</var> [<var>key</var>]</dt>
      <dd>
        Queries the external IDs on <var>lport</var>.  If
        <var>key</var> is specified, the output is the value for that
        <var>key</var> or the empty string if <var>key</var> is unset.
        If <var>key</var> is omitted, the output is
        <var>key</var><code>=</code><var>value</var>, one per line, for
        each key-value pair.
      </dd>

      <dt><code>lport-set-macs</code> <var>lport</var> [<var>mac</var>]...</dt>
      <dd>
        Sets the MACs associated with <var>lport</var> to
        <var>mac</var>.  Multiple MACs may be sets by using multiple
        <var>mac</var> arguments.  If no <var>mac</var> argument is
        given, <var>lport</var> will have no MACs associated with it.
      </dd>

      <dt><code>lport-get-macs</code> <var>lport</var></dt>
      <dd>
        Lists all the MACs associated with <var>lport</var> on standard
        output, one per line.
      </dd>

      <dt><code>lport-set-port-security</code> <var>lport</var> [<var>addrs</var>]...</dt>
      <dd>
	<p>
          Sets the port security addresses associated with <var>lport</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>lport</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_Port"/> column in the <ref
	  table="Logical_Port"/> table for details.
	</p>
      </dd>

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

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

      <dt><code>lport-set-enabled</code> <var>lport</var> <var>state</var></dt>
      <dd>
        Set the administrative state of <var>lport</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>lport-get-enabled</code> <var>lport</var></dt>
      <dd>
        Prints the administrative state of <var>lport</var>, either <code>enabled</code>
        or <code>disabled</code>.
      </dd>

    </dl>

    <h1>Options</h1>

    <dl>
    <dt><code>-d</code> <var>database</var></dt>
    <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>