ovn/utilities/ovn-nbctl.8.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <manpage program="ovn-nbctl" section="8" title="ovn-nbctl">
   3     <h1>Name</h1>
   4     <p>ovn-nbctl -- Open Virtual Network northbound db management utility</p>
   5
   6     <h1>Synopsys</h1>
   7     <p><code>ovn-nbctl</code> [<var>options</var>] <var>command</var> [<var>arg</var>...]</p>
   8
   9     <h1>Description</h1>
  10     <p>This utility can be used to manage the OVN northbound database.</p>
  11
  12     <h1>General Commands</h1>
  13
  14     <dl>
  15       <dt><code>show [<var>lswitch</var>]</code></dt>
  16       <dd>
  17         Prints a brief overview of the database contents.  If
  18         <var>lswitch</var> is provided, only records related to that
  19         logical switch are shown.
  20       </dd>
  21     </dl>
  22
  23     <h1>Logical Switch Commands</h1>
  24
  25     <dl>
  26       <dt><code>lswitch-add</code> [<var>lswitch</var>]</dt> <dd> Creates a new logical switch named <var>lswitch</var>.  If
  27         <var>lswitch</var> is not provided, the switch will not have a
  28         name so other commands must refer to this switch by its UUID.
  29         Initially the switch will have no ports.
  30       </dd>
  31
  32       <dt><code>lswitch-del</code> <var>lswitch</var></dt>
  33       <dd>
  34         Deletes <var>lswitch</var>.
  35       </dd>
  36
  37       <dt><code>lswitch-list</code></dt>
  38       <dd>
  39         Lists all existing switches on standard output, one per line.
  40       </dd>
  41
  42       <dt><code>lswitch-set-external-id</code> <var>lswitch</var> <var>key</var> [<var>value</var>]</dt>
  43       <dd>
  44         <p>Sets or clears an ``external ID'' value on <var>lswitch</var>.
  45         These values are intended to identify entities external to OVN
  46         with which <var>lswitch</var> is associated.  The OVN Northbound
  47         database schema may specify well-known <var>key</var> values,
  48         but <var>key</var> and <var>value</var> are otherwise arbitrary
  49         strings.</p>
  50
  51         <p>If <var>value</var> is specified, then <var>key</var> is set to
  52         <var>value</var> for <var>lswitch</var>, overwriting any
  53         previous value.  If <var>value</var> is omitted, then
  54         <var>key</var> is removed from <var>lswitch</var>'s set of
  55         external IDs (if it was present.</p>
  56        </dd>
  57
  58       <dt><code>lswitch-get-external-id</code> <var>lswitch</var> [<var>key</var>]</dt>
  59       <dd>
  60         Queries the external IDs on <var>lswitch</var>.  If
  61         <var>key</var> is specified, the output is the value for that
  62         <var>key</var> or the empty string if <var>key</var> is unset.
  63         If <var>key</var> is omitted, the output is
  64         <var>key</var><code>=</code><var>value</var>, one per line, for
  65         each key-value pair.
  66       </dd>
  67     </dl>
  68
  69     <h1>Logical Port Commands</h1>
  70     <dl>
  71       <dt><code>lport-add</code> <var>lswitch</var> <var>lport</var></dt>
  72       <dd>
  73         Creates on <var>lswitch</var> a new logical port named
  74         <var>lport</var>.
  75       </dd>
  76
  77       <dt><code>lport-add</code> <var>lswitch</var> <var>lport</var> <var>parent</var> <var>tag</var></dt>
  78       <dd>
  79         Creates on <var>lswitch</var> a logical port named <var>lport</var>
  80         that is a child of <var>parent</var> that is identied with
  81         <var>tag</var>.  This is useful in cases such as virtualized
  82         container environments where Open vSwitch does not have a direct
  83         connection to the container's port and it must be shared with
  84         the virtual machine's port.
  85       </dd>
  86
  87       <dt><code>lport-del</code> <var>lport</var></dt>
  88       <dd>
  89         Deletes <var>lport</var>.
  90       </dd>
  91
  92       <dt><code>lport-list</code> <var>lswitch</var></dt>
  93       <dd>
  94         Lists all the logical ports within <var>lswitch</var> on
  95         standard output, one per line.
  96       </dd>
  97
  98       <dt><code>lport-get-parent</code> <var>lport</var></dt>
  99       <dd>
 100         If set, get the parent port of <var>lport</var>.  If not set, print
 101         nothing.
 102       </dd>
 103
 104       <dt><code>lport-get-tag</code> <var>lport</var></dt>
 105       <dd>
 106         If set, get the tag for <var>lport</var> traffic.  If not set, print
 107         nothing.
 108       </dd>
 109
 110       <dt><code>lport-set-external-id</code> <var>lport</var> <var>key</var> [<var>value</var>]</dt>
 111       <dd>
 112         <p>Sets or clears an ``external ID'' value on <var>lport</var>.
 113         These values are intended to identify entities external to OVN
 114         with which <var>lport</var> is associated.  The OVN Northbound
 115         database schema may specify well-known <var>key</var> values,
 116         but <var>key</var> and <var>value</var> are otherwise arbitrary
 117         strings.</p>
 118
 119         <p>If <var>value</var> is specified, then <var>key</var> is set to
 120         <var>value</var> for <var>lport</var>, overwriting any
 121         previous value.  If <var>value</var> is omitted, then
 122         <var>key</var> is removed from <var>lport</var>'s set of
 123         external IDs (if it was present.</p>
 124       </dd>
 125
 126       <dt><code>lport-get-external-id</code> <var>lport</var> [<var>key</var>]</dt>
 127       <dd>
 128         Queries the external IDs on <var>lport</var>.  If
 129         <var>key</var> is specified, the output is the value for that
 130         <var>key</var> or the empty string if <var>key</var> is unset.
 131         If <var>key</var> is omitted, the output is
 132         <var>key</var><code>=</code><var>value</var>, one per line, for
 133         each key-value pair.
 134       </dd>
 135
 136       <dt><code>lport-set-macs</code> <var>lport</var> [<var>mac</var>]...</dt>
 137       <dd>
 138         Sets the MACs associated with <var>lport</var> to
 139         <var>mac</var>.  Multiple MACs may be sets by using multiple
 140         <var>mac</var> arguments.  If no <var>mac</var> argument is
 141         given, <var>lport</var> will have no MACs associated with it.
 142       </dd>
 143
 144       <dt><code>lport-get-macs</code> <var>lport</var></dt>
 145       <dd>
 146         Lists all the MACs associated with <var>lport</var> on standard
 147         output, one per line.
 148       </dd>
 149
 150       <dt><code>lport-set-port-security</code> <var>lport</var> [<var>addrs</var>]...</dt>
 151       <dd>
 152         <p>
 153           Sets the port security addresses associated with <var>lport</var> to
 154           <var>addrs</var>.  Multiple sets of addresses may be set by using
 155           multiple <var>addrs</var> arguments.  If no <var>addrs</var> argument
 156           is given, <var>lport</var> will not have port security enabled.
 157         </p>
 158
 159         <p>
 160           Port security limits the addresses from which a logical port may send
 161           packets and to which it may receive packets.  See the
 162           <code>ovn-nb</code>(5) documentation for the <ref
 163           column="port_security" table="Logical_Port"/> column in the <ref
 164           table="Logical_Port"/> table for details.
 165         </p>
 166       </dd>
 167
 168       <dt><code>lport-get-port-security</code> <var>lport</var></dt>
 169       <dd>
 170         Lists all the port security addresses associated with <var>lport</var>
 171         on standard output, one per line.
 172       </dd>
 173
 174       <dt><code>lport-get-up</code> <var>lport</var></dt>
 175       <dd>
 176         Prints the state of <var>lport</var>, either <code>up</code> or
 177         <code>down</code>.
 178       </dd>
 179
 180       <dt><code>lport-set-enabled</code> <var>lport</var> <var>state</var></dt>
 181       <dd>
 182         Set the administrative state of <var>lport</var>, either <code>enabled</code>
 183         or <code>disabled</code>.  When a port is disabled, no traffic is allowed into
 184         or out of the port.
 185       </dd>
 186
 187       <dt><code>lport-get-enabled</code> <var>lport</var></dt>
 188       <dd>
 189         Prints the administrative state of <var>lport</var>, either <code>enabled</code>
 190         or <code>disabled</code>.
 191       </dd>
 192
 193       <dt><code>lport-set-type</code> <var>lport</var> <var>type</var></dt>
 194       <dd>
 195         Set the type for the logical port.  No special types have been implemented yet.
 196       </dd>
 197
 198       <dt><code>lport-get-type</code> <var>lport</var></dt>
 199       <dd>
 200         Get the type for the logical port.
 201       </dd>
 202
 203       <dt><code>lport-set-options</code> <var>lport</var> [<var>key=value</var>]...</dt>
 204       <dd>
 205         Set type-specific key-value options for the logical port.
 206       </dd>
 207
 208       <dt><code>lport-get-options</code> <var>lport</var></dt>
 209       <dd>
 210         Get the type-specific options for the logical port.
 211       </dd>
 212
 213     </dl>
 214
 215     <h1>Options</h1>
 216
 217     <dl>
 218     <dt><code>-d</code> <var>database</var></dt>
 219     <dt><code>--db</code> <var>database</var></dt>
 220     <dd>
 221       The OVSDB database remote to contact.  If the <env>OVN_NB_DB</env>
 222       environment variable is set, its value is used as the default.
 223       Otherwise, the default is <code>unix:@RUNDIR@/db.sock</code>, but this
 224       default is unlikely to be useful outside of single-machine OVN test
 225       environments.
 226     </dd>
 227
 228     <dt><code>-h</code> | <code>--help</code></dt>
 229     <dt><code>-o</code> | <code>--options</code></dt>
 230     <dt><code>-V</code> | <code>--version</code></dt>
 231     </dl>
 232
 233     <h1>Logging options</h1>
 234     <dl>
 235     <dt><code>-v</code><var>spec</var>, <code>--verbose=</code><var>spec</var></dt>
 236     <dt><code>-v</code>, <code>--verbose</code></dt>
 237     <dt><code>--log-file</code>[<code>=</code><var>file</var>]</dt>
 238     <dt><code>--syslog-target=</code><var>host</var><code>:</code><var>port</var></dt>
 239     </dl>
 240
 241     <h1>PKI configuration (required to use SSL)</h1>
 242     <dl>
 243     <dt><code>-p</code>, <code>--private-key=</code><var>file</var>  file with private key</dt>
 244     <dt><code>-c</code>, <code>--certificate=</code><var>file</var>  file with certificate for private key</dt>
 245     <dt><code>-C</code>, <code>--ca-cert=</code><var>file</var>      file with peer CA certificate</dt>
 246     </dl>
 247
 248 </manpage>