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>ACL Commands</h1>
  70     <dl>
  71       <dt>[<code>--log</code>] <code>acl-add</code> <var>lswitch</var> <var>direction</var> <var>priority</var> <var>match</var> <var>action</var></dt>
  72       <dd>
  73         Adds the specified ACL to <var>lswitch</var>.
  74         <var>direction</var> must be either <code>from-lport</code> or
  75         <code>to-lport</code>.  <var>priority</var> must be between
  76         <code>1</code> and <code>65534</code>, inclusive.  If
  77         <code>--log</code> is specified, packet logging is enabled for the
  78         ACL.  A full description of the fields are in <code>ovn-nb</code>(5).
  79       </dd>
  80
  81       <dt><code>acl-del</code> <var>lswitch</var> [<var>direction</var> [<var>priority</var> <var>match</var>]]</dt>
  82       <dd>
  83         Deletes ACLs from <var>lswitch</var>.  If only
  84         <var>lswitch</var> is supplied, all the ACLs from the logical
  85         switch are deleted.  If <var>direction</var> is also specified,
  86         then all the flows in that direction will be deleted from the
  87         logical switch.  If all the fields are given, then a single flow
  88         that matches all the fields will be deleted.
  89       </dd>
  90
  91       <dt><code>acl-list</code> <var>lswitch</var></dt>
  92       <dd>
  93         Lists the ACLs on <var>lswitch</var>.
  94       </dd>
  95     </dl>
  96
  97     <h1>Logical Port Commands</h1>
  98     <dl>
  99       <dt><code>lport-add</code> <var>lswitch</var> <var>lport</var></dt>
 100       <dd>
 101         Creates on <var>lswitch</var> a new logical port named
 102         <var>lport</var>.
 103       </dd>
 104
 105       <dt><code>lport-add</code> <var>lswitch</var> <var>lport</var> <var>parent</var> <var>tag</var></dt>
 106       <dd>
 107         Creates on <var>lswitch</var> a logical port named <var>lport</var>
 108         that is a child of <var>parent</var> that is identifed with VLAN ID
 109         <var>tag</var>.  This is useful in cases such as virtualized
 110         container environments where Open vSwitch does not have a direct
 111         connection to the container's port and it must be shared with
 112         the virtual machine's port.
 113       </dd>
 114
 115       <dt><code>lport-del</code> <var>lport</var></dt>
 116       <dd>
 117         Deletes <var>lport</var>.
 118       </dd>
 119
 120       <dt><code>lport-list</code> <var>lswitch</var></dt>
 121       <dd>
 122         Lists all the logical ports within <var>lswitch</var> on
 123         standard output, one per line.
 124       </dd>
 125
 126       <dt><code>lport-get-parent</code> <var>lport</var></dt>
 127       <dd>
 128         If set, get the parent port of <var>lport</var>.  If not set, print
 129         nothing.
 130       </dd>
 131
 132       <dt><code>lport-get-tag</code> <var>lport</var></dt>
 133       <dd>
 134         If set, get the tag for <var>lport</var> traffic.  If not set, print
 135         nothing.
 136       </dd>
 137
 138       <dt><code>lport-set-external-id</code> <var>lport</var> <var>key</var> [<var>value</var>]</dt>
 139       <dd>
 140         <p>Sets or clears an ``external ID'' value on <var>lport</var>.
 141         These values are intended to identify entities external to OVN
 142         with which <var>lport</var> is associated.  The OVN Northbound
 143         database schema may specify well-known <var>key</var> values,
 144         but <var>key</var> and <var>value</var> are otherwise arbitrary
 145         strings.</p>
 146
 147         <p>If <var>value</var> is specified, then <var>key</var> is set to
 148         <var>value</var> for <var>lport</var>, overwriting any
 149         previous value.  If <var>value</var> is omitted, then
 150         <var>key</var> is removed from <var>lport</var>'s set of
 151         external IDs (if it was present.</p>
 152       </dd>
 153
 154       <dt><code>lport-get-external-id</code> <var>lport</var> [<var>key</var>]</dt>
 155       <dd>
 156         Queries the external IDs on <var>lport</var>.  If
 157         <var>key</var> is specified, the output is the value for that
 158         <var>key</var> or the empty string if <var>key</var> is unset.
 159         If <var>key</var> is omitted, the output is
 160         <var>key</var><code>=</code><var>value</var>, one per line, for
 161         each key-value pair.
 162       </dd>
 163
 164       <dt><code>lport-set-macs</code> <var>lport</var> [<var>mac</var>]...</dt>
 165       <dd>
 166         Sets the MACs associated with <var>lport</var> to
 167         <var>mac</var>.  Multiple MACs may be sets by using multiple
 168         <var>mac</var> arguments.  If no <var>mac</var> argument is
 169         given, <var>lport</var> will have no MACs associated with it.
 170       </dd>
 171
 172       <dt><code>lport-get-macs</code> <var>lport</var></dt>
 173       <dd>
 174         Lists all the MACs associated with <var>lport</var> on standard
 175         output, one per line.
 176       </dd>
 177
 178       <dt><code>lport-set-port-security</code> <var>lport</var> [<var>addrs</var>]...</dt>
 179       <dd>
 180         <p>
 181           Sets the port security addresses associated with <var>lport</var> to
 182           <var>addrs</var>.  Multiple sets of addresses may be set by using
 183           multiple <var>addrs</var> arguments.  If no <var>addrs</var> argument
 184           is given, <var>lport</var> will not have port security enabled.
 185         </p>
 186
 187         <p>
 188           Port security limits the addresses from which a logical port may send
 189           packets and to which it may receive packets.  See the
 190           <code>ovn-nb</code>(5) documentation for the <ref
 191           column="port_security" table="Logical_Port"/> column in the <ref
 192           table="Logical_Port"/> table for details.
 193         </p>
 194       </dd>
 195
 196       <dt><code>lport-get-port-security</code> <var>lport</var></dt>
 197       <dd>
 198         Lists all the port security addresses associated with <var>lport</var>
 199         on standard output, one per line.
 200       </dd>
 201
 202       <dt><code>lport-get-up</code> <var>lport</var></dt>
 203       <dd>
 204         Prints the state of <var>lport</var>, either <code>up</code> or
 205         <code>down</code>.
 206       </dd>
 207
 208       <dt><code>lport-set-enabled</code> <var>lport</var> <var>state</var></dt>
 209       <dd>
 210         Set the administrative state of <var>lport</var>, either <code>enabled</code>
 211         or <code>disabled</code>.  When a port is disabled, no traffic is allowed into
 212         or out of the port.
 213       </dd>
 214
 215       <dt><code>lport-get-enabled</code> <var>lport</var></dt>
 216       <dd>
 217         Prints the administrative state of <var>lport</var>, either <code>enabled</code>
 218         or <code>disabled</code>.
 219       </dd>
 220
 221       <dt><code>lport-set-type</code> <var>lport</var> <var>type</var></dt>
 222       <dd>
 223         Set the type for the logical port.  No special types have been implemented yet.
 224       </dd>
 225
 226       <dt><code>lport-get-type</code> <var>lport</var></dt>
 227       <dd>
 228         Get the type for the logical port.
 229       </dd>
 230
 231       <dt><code>lport-set-options</code> <var>lport</var> [<var>key=value</var>]...</dt>
 232       <dd>
 233         Set type-specific key-value options for the logical port.
 234       </dd>
 235
 236       <dt><code>lport-get-options</code> <var>lport</var></dt>
 237       <dd>
 238         Get the type-specific options for the logical port.
 239       </dd>
 240
 241     </dl>
 242
 243     <h1>Options</h1>
 244
 245     <dl>
 246     <dt><code>--db</code> <var>database</var></dt>
 247     <dd>
 248       The OVSDB database remote to contact.  If the <env>OVN_NB_DB</env>
 249       environment variable is set, its value is used as the default.
 250       Otherwise, the default is <code>unix:@RUNDIR@/db.sock</code>, but this
 251       default is unlikely to be useful outside of single-machine OVN test
 252       environments.
 253     </dd>
 254
 255     <dt><code>-h</code> | <code>--help</code></dt>
 256     <dt><code>-o</code> | <code>--options</code></dt>
 257     <dt><code>-V</code> | <code>--version</code></dt>
 258     </dl>
 259
 260     <h1>Logging options</h1>
 261     <dl>
 262     <dt><code>-v</code><var>spec</var>, <code>--verbose=</code><var>spec</var></dt>
 263     <dt><code>-v</code>, <code>--verbose</code></dt>
 264     <dt><code>--log-file</code>[<code>=</code><var>file</var>]</dt>
 265     <dt><code>--syslog-target=</code><var>host</var><code>:</code><var>port</var></dt>
 266     </dl>
 267
 268     <h1>PKI configuration (required to use SSL)</h1>
 269     <dl>
 270     <dt><code>-p</code>, <code>--private-key=</code><var>file</var>  file with private key</dt>
 271     <dt><code>-c</code>, <code>--certificate=</code><var>file</var>  file with certificate for private key</dt>
 272     <dt><code>-C</code>, <code>--ca-cert=</code><var>file</var>      file with peer CA certificate</dt>
 273     </dl>
 274
 275 </manpage>