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     </dl>
  42
  43     <h1>ACL Commands</h1>
  44     <dl>
  45       <dt>[<code>--log</code>] <code>acl-add</code> <var>lswitch</var> <var>direction</var> <var>priority</var> <var>match</var> <var>action</var></dt>
  46       <dd>
  47         Adds the specified ACL to <var>lswitch</var>.
  48         <var>direction</var> must be either <code>from-lport</code> or
  49         <code>to-lport</code>.  <var>priority</var> must be between
  50         <code>1</code> and <code>65534</code>, inclusive.  If
  51         <code>--log</code> is specified, packet logging is enabled for the
  52         ACL.  A full description of the fields are in <code>ovn-nb</code>(5).
  53       </dd>
  54
  55       <dt><code>acl-del</code> <var>lswitch</var> [<var>direction</var> [<var>priority</var> <var>match</var>]]</dt>
  56       <dd>
  57         Deletes ACLs from <var>lswitch</var>.  If only
  58         <var>lswitch</var> is supplied, all the ACLs from the logical
  59         switch are deleted.  If <var>direction</var> is also specified,
  60         then all the flows in that direction will be deleted from the
  61         logical switch.  If all the fields are given, then a single flow
  62         that matches all the fields will be deleted.
  63       </dd>
  64
  65       <dt><code>acl-list</code> <var>lswitch</var></dt>
  66       <dd>
  67         Lists the ACLs on <var>lswitch</var>.
  68       </dd>
  69     </dl>
  70
  71     <h1>Logical Port Commands</h1>
  72     <dl>
  73       <dt><code>lport-add</code> <var>lswitch</var> <var>lport</var></dt>
  74       <dd>
  75         Creates on <var>lswitch</var> a new logical port named
  76         <var>lport</var>.
  77       </dd>
  78
  79       <dt><code>lport-add</code> <var>lswitch</var> <var>lport</var> <var>parent</var> <var>tag</var></dt>
  80       <dd>
  81         Creates on <var>lswitch</var> a logical port named <var>lport</var>
  82         that is a child of <var>parent</var> that is identifed with VLAN ID
  83         <var>tag</var>.  This is useful in cases such as virtualized
  84         container environments where Open vSwitch does not have a direct
  85         connection to the container's port and it must be shared with
  86         the virtual machine's port.
  87       </dd>
  88
  89       <dt><code>lport-del</code> <var>lport</var></dt>
  90       <dd>
  91         Deletes <var>lport</var>.
  92       </dd>
  93
  94       <dt><code>lport-list</code> <var>lswitch</var></dt>
  95       <dd>
  96         Lists all the logical ports within <var>lswitch</var> on
  97         standard output, one per line.
  98       </dd>
  99
 100       <dt><code>lport-get-parent</code> <var>lport</var></dt>
 101       <dd>
 102         If set, get the parent port of <var>lport</var>.  If not set, print
 103         nothing.
 104       </dd>
 105
 106       <dt><code>lport-get-tag</code> <var>lport</var></dt>
 107       <dd>
 108         If set, get the tag for <var>lport</var> traffic.  If not set, print
 109         nothing.
 110       </dd>
 111
 112       <dt><code>lport-set-addresses</code> <var>lport</var> [<var>address</var>]...</dt>
 113       <dd>
 114         Sets the addresses associated with <var>lport</var> to
 115         <var>address</var>.  Each <var>address</var> should be either an
 116         Ethernet address or an Ethernet address followed by an IP address
 117         (separated by a space and quoted to form a single command-line
 118         argument).  The special form <code>unknown</code> is also valid.
 119         Multiple Ethernet addresses or Ethernet+IP pairs may be set. If no
 120         <var>address</var> argument is given, <var>lport</var> will have no
 121         addresses associated with it.
 122       </dd>
 123
 124       <dt><code>lport-get-addresses</code> <var>lport</var></dt>
 125       <dd>
 126         Lists all the addresses associated with <var>lport</var> on standard
 127         output, one per line.
 128       </dd>
 129
 130       <dt><code>lport-set-port-security</code> <var>lport</var> [<var>addrs</var>]...</dt>
 131       <dd>
 132         <p>
 133           Sets the port security addresses associated with <var>lport</var> to
 134           <var>addrs</var>.  Multiple sets of addresses may be set by using
 135           multiple <var>addrs</var> arguments.  If no <var>addrs</var> argument
 136           is given, <var>lport</var> will not have port security enabled.
 137         </p>
 138
 139         <p>
 140           Port security limits the addresses from which a logical port may send
 141           packets and to which it may receive packets.  See the
 142           <code>ovn-nb</code>(5) documentation for the <ref
 143           column="port_security" table="Logical_Port"/> column in the <ref
 144           table="Logical_Port"/> table for details.
 145         </p>
 146       </dd>
 147
 148       <dt><code>lport-get-port-security</code> <var>lport</var></dt>
 149       <dd>
 150         Lists all the port security addresses associated with <var>lport</var>
 151         on standard output, one per line.
 152       </dd>
 153
 154       <dt><code>lport-get-up</code> <var>lport</var></dt>
 155       <dd>
 156         Prints the state of <var>lport</var>, either <code>up</code> or
 157         <code>down</code>.
 158       </dd>
 159
 160       <dt><code>lport-set-enabled</code> <var>lport</var> <var>state</var></dt>
 161       <dd>
 162         Set the administrative state of <var>lport</var>, either <code>enabled</code>
 163         or <code>disabled</code>.  When a port is disabled, no traffic is allowed into
 164         or out of the port.
 165       </dd>
 166
 167       <dt><code>lport-get-enabled</code> <var>lport</var></dt>
 168       <dd>
 169         Prints the administrative state of <var>lport</var>, either <code>enabled</code>
 170         or <code>disabled</code>.
 171       </dd>
 172
 173       <dt><code>lport-set-type</code> <var>lport</var> <var>type</var></dt>
 174       <dd>
 175         Set the type for the logical port.  No special types have been implemented yet.
 176       </dd>
 177
 178       <dt><code>lport-get-type</code> <var>lport</var></dt>
 179       <dd>
 180         Get the type for the logical port.
 181       </dd>
 182
 183       <dt><code>lport-set-options</code> <var>lport</var> [<var>key=value</var>]...</dt>
 184       <dd>
 185         Set type-specific key-value options for the logical port.
 186       </dd>
 187
 188       <dt><code>lport-get-options</code> <var>lport</var></dt>
 189       <dd>
 190         Get the type-specific options for the logical port.
 191       </dd>
 192
 193     </dl>
 194
 195     <h1>Database Commands</h1>
 196     <p>These commands query and modify the contents of <code>ovsdb</code> tables.
 197     They are a slight abstraction of the <code>ovsdb</code> interface and
 198     as suchthey operate at a lower level than other <code>ovn-nbctl</code> commands.</p>
 199     <p><var>Identifying Tables, Records, and Columns</var></p>
 200     <p>Each of these commands has a <var>table</var> parameter to identify a table
 201     within the database.  Many of them also take a <var>record</var> parameter
 202     that identifies a particular record within a table.  The <var>record</var>
 203     parameter may be the UUID for a record, and many tables offer
 204     additional ways to identify records.  Some commands also take
 205     <var>column</var> parameters that identify a particular field within the
 206     records in a table.</p>
 207     <p>The following tables are currently defined:</p>
 208     <dl>
 209       <dt><code>Logical_Switch</code></dt>
 210       <dd>
 211         An L2 logical switch.  Records may be identified by name.
 212       </dd>
 213
 214       <dt><code>Logical_Port</code></dt>
 215       <dd>
 216         A port within an L2 logical switch.  Records may be identified by name.
 217       </dd>
 218
 219       <dt><code>ACL</code></dt>
 220       <dd>
 221         An ACL rule for a logical switch that points to it through its <var>acls</var> column.
 222       </dd>
 223
 224       <dt><code>Logical_Router</code></dt>
 225       <dd>
 226         An L3 logical router.  Records may be identified by name.
 227       </dd>
 228
 229       <dt><code>Logical_Router_Port</code></dt>
 230       <dd>
 231         A port within an L3 logical router.  Records may be identified by name.
 232       </dd>
 233
 234     </dl>
 235
 236     <xi:include href="lib/db-ctl-base.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 237
 238     <h1>Options</h1>
 239
 240     <dl>
 241     <dt><code>--db</code> <var>database</var></dt>
 242     <dd>
 243       The OVSDB database remote to contact.  If the <env>OVN_NB_DB</env>
 244       environment variable is set, its value is used as the default.
 245       Otherwise, the default is <code>unix:@RUNDIR@/db.sock</code>, but this
 246       default is unlikely to be useful outside of single-machine OVN test
 247       environments.
 248     </dd>
 249
 250     <dt><code>-h</code> | <code>--help</code></dt>
 251     <dt><code>-o</code> | <code>--options</code></dt>
 252     <dt><code>-V</code> | <code>--version</code></dt>
 253     </dl>
 254
 255     <h1>Logging options</h1>
 256     <dl>
 257     <dt><code>-v</code><var>spec</var>, <code>--verbose=</code><var>spec</var></dt>
 258     <dt><code>-v</code>, <code>--verbose</code></dt>
 259     <dt><code>--log-file</code>[<code>=</code><var>file</var>]</dt>
 260     <dt><code>--syslog-target=</code><var>host</var><code>:</code><var>port</var></dt>
 261     </dl>
 262
 263     <h1>PKI configuration (required to use SSL)</h1>
 264     <dl>
 265     <dt><code>-p</code>, <code>--private-key=</code><var>file</var>  file with private key</dt>
 266     <dt><code>-c</code>, <code>--certificate=</code><var>file</var>  file with certificate for private key</dt>
 267     <dt><code>-C</code>, <code>--ca-cert=</code><var>file</var>      file with peer CA certificate</dt>
 268     </dl>
 269
 270 </manpage>