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> | <var>router</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. If
  20         <var>router</var> is provided, only records related to that
  21         logical router are shown.
  22       </dd>
  23     </dl>
  24
  25     <h1>Logical Switch Commands</h1>
  26
  27     <dl>
  28       <dt><code>lswitch-add</code></dt>
  29       <dd>
  30         <p>
  31           Creates a new, unnamed logical switch, which initially has no ports.
  32           The switch does not have a name, other commands must refer to this
  33           switch by its UUID.
  34         </p>
  35       </dd>
  36
  37       <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>lswitch-add</code> <var>lswitch</var></dt>
  38       <dd>
  39         <p>
  40           Creates a new logical switch named <var>lswitch</var>, which
  41           initially has no ports.
  42         </p>
  43
  44         <p>
  45           The OVN northbound database schema does not require logical switch
  46           names to be unique, but the whole point to the names is to provide an
  47           easy way for humans to refer to the switches, making duplicate names
  48           unhelpful.  Thus, without any options, this command regards it as an
  49           error if <var>lswitch</var> is a duplicate name.  With
  50           <code>--may-exist</code>, adding a duplicate name succeeds but does
  51           not create a new logical switch.  With <code>--add-duplicate</code>,
  52           the command really creates a new logical switch with a duplicate
  53           name.  It is an error to specify both options.
  54         </p>
  55       </dd>
  56
  57       <dt>[<code>--if-exists</code>] <code>lswitch-del</code> <var>lswitch</var></dt>
  58       <dd>
  59         Deletes <var>lswitch</var>.  It is an error if <var>lswitch</var> does
  60         not exist, unless <code>--if-exists</code> is specified.
  61       </dd>
  62
  63       <dt><code>lswitch-list</code></dt>
  64       <dd>
  65         Lists all existing switches on standard output, one per line.
  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 Router Port Commands</h1>
  98
  99     <dl>
 100       <dt>[<code>--may-exist</code>] <code>lrport-add</code> <var>router</var> <var>lrport</var></dt>
 101       <dd>
 102         <p>
 103           Creates on <var>router</var> a new logical router port named
 104           <var>lrport</var>.
 105         </p>
 106
 107         <p>
 108           It is an error if a logical router port named <var>lrport</var>
 109           already exists, unless <code>--may-exist</code> is specified.
 110           Regardless of <code>--may-exist</code>, it is an error if the
 111           existing router port is in some logical router other than
 112           <var>router</var>.
 113         </p>
 114       </dd>
 115
 116       <dt>[<code>--if-exists</code>] <code>lrport-del</code> <var>lrport</var></dt>
 117       <dd>
 118         Deletes <var>lrport</var>.  It is an error if <var>lrport</var> does
 119         not exist, unless <code>--if-exists</code> is specified.
 120       </dd>
 121
 122       <dt><code>lrport-list</code> <var>router</var></dt>
 123       <dd>
 124         Lists all the logical router ports within <var>router</var> on
 125         standard output, one per line.
 126       </dd>
 127
 128       <dt><code>lrport-set-mac-address</code> <var>lrport</var>
 129                 <var>address</var>...</dt>
 130       <dd>
 131         Sets the address associated with <var>lrport</var> to
 132         <var>address</var>.  <var>address</var> should be either an
 133         Ethernet address or an Ethernet address followed by an IP address
 134         (separated by a space and quoted to form a single command-line
 135         argument).  The special form <code>unknown</code> is also valid.
 136       </dd>
 137
 138       <dt><code>lrport-get-mac-address</code> <var>lrport</var></dt>
 139       <dd>
 140         Lists the mac address associated with <var>lrport</var> on standard
 141         output.
 142       </dd>
 143
 144       <dt><code>lrport-set-enabled</code> <var>lrport</var> <var>state</var></dt>
 145       <dd>
 146         Set the administrative state of <var>lrport</var>,
 147         either <code>enabled</code> or <code>disabled</code>.
 148         When a port is disabled, no traffic is allowed into
 149         or out of the port.
 150       </dd>
 151
 152       <dt><code>lrport-get-enabled</code> <var>lrport</var></dt>
 153       <dd>
 154         Prints the administrative state of <var>lrport</var>,
 155         either <code>enabled</code> or <code>disabled</code>.
 156       </dd>
 157
 158     </dl>
 159     <h1>Logical Port Commands</h1>
 160     <dl>
 161       <dt>[<code>--may-exist</code>] <code>lport-add</code> <var>lswitch</var> <var>lport</var></dt>
 162       <dd>
 163         <p>
 164           Creates on <var>lswitch</var> a new logical port named
 165           <var>lport</var>.
 166         </p>
 167
 168         <p>
 169           It is an error if a logical port named <var>lport</var> already
 170           exists, unless <code>--may-exist</code> is specified.  Regardless of
 171           <code>--may-exist</code>, it is an error if the existing port is in
 172           some logical switch other than <var>lswitch</var> or if it has a
 173           parent port.
 174         </p>
 175       </dd>
 176
 177       <dt>[<code>--may-exist</code>] <code>lport-add</code> <var>lswitch</var> <var>lport</var> <var>parent</var> <var>tag</var></dt>
 178       <dd>
 179         <p>
 180           Creates on <var>lswitch</var> a logical port named <var>lport</var>
 181           that is a child of <var>parent</var> that is identifed with VLAN ID
 182           <var>tag</var>.  This is useful in cases such as virtualized
 183           container environments where Open vSwitch does not have a direct
 184           connection to the container's port and it must be shared with
 185           the virtual machine's port.
 186         </p>
 187
 188         <p>
 189           It is an error if a logical port named <var>lport</var> already
 190           exists, unless <code>--may-exist</code> is specified.  Regardless of
 191           <code>--may-exist</code>, it is an error if the existing port is not
 192           in <var>lswitch</var> or if it does not have the specified
 193           <var>parent</var> and <var>tag</var>.
 194         </p>
 195       </dd>
 196
 197       <dt>[<code>--if-exists</code>] <code>lport-del</code> <var>lport</var></dt>
 198       <dd>
 199         Deletes <var>lport</var>.  It is an error if <var>lport</var> does
 200         not exist, unless <code>--if-exists</code> is specified.
 201       </dd>
 202
 203       <dt><code>lport-list</code> <var>lswitch</var></dt>
 204       <dd>
 205         Lists all the logical ports within <var>lswitch</var> on
 206         standard output, one per line.
 207       </dd>
 208
 209       <dt><code>lport-get-parent</code> <var>lport</var></dt>
 210       <dd>
 211         If set, get the parent port of <var>lport</var>.  If not set, print
 212         nothing.
 213       </dd>
 214
 215       <dt><code>lport-get-tag</code> <var>lport</var></dt>
 216       <dd>
 217         If set, get the tag for <var>lport</var> traffic.  If not set, print
 218         nothing.
 219       </dd>
 220
 221       <dt><code>lport-set-addresses</code> <var>lport</var> [<var>address</var>]...</dt>
 222       <dd>
 223         Sets the addresses associated with <var>lport</var> to
 224         <var>address</var>.  Each <var>address</var> should be either an
 225         Ethernet address or an Ethernet address followed by an IP address
 226         (separated by a space and quoted to form a single command-line
 227         argument).  The special form <code>unknown</code> is also valid.
 228         Multiple Ethernet addresses or Ethernet+IP pairs may be set. If no
 229         <var>address</var> argument is given, <var>lport</var> will have no
 230         addresses associated with it.
 231       </dd>
 232
 233       <dt><code>lport-get-addresses</code> <var>lport</var></dt>
 234       <dd>
 235         Lists all the addresses associated with <var>lport</var> on standard
 236         output, one per line.
 237       </dd>
 238
 239       <dt><code>lport-set-port-security</code> <var>lport</var> [<var>addrs</var>]...</dt>
 240       <dd>
 241         <p>
 242           Sets the port security addresses associated with <var>lport</var> to
 243           <var>addrs</var>.  Multiple sets of addresses may be set by using
 244           multiple <var>addrs</var> arguments.  If no <var>addrs</var> argument
 245           is given, <var>lport</var> will not have port security enabled.
 246         </p>
 247
 248         <p>
 249           Port security limits the addresses from which a logical port may send
 250           packets and to which it may receive packets.  See the
 251           <code>ovn-nb</code>(5) documentation for the <ref
 252           column="port_security" table="Logical_Port"/> column in the <ref
 253           table="Logical_Port"/> table for details.
 254         </p>
 255       </dd>
 256
 257       <dt><code>lport-get-port-security</code> <var>lport</var></dt>
 258       <dd>
 259         Lists all the port security addresses associated with <var>lport</var>
 260         on standard output, one per line.
 261       </dd>
 262
 263       <dt><code>lport-get-up</code> <var>lport</var></dt>
 264       <dd>
 265         Prints the state of <var>lport</var>, either <code>up</code> or
 266         <code>down</code>.
 267       </dd>
 268
 269       <dt><code>lport-set-enabled</code> <var>lport</var> <var>state</var></dt>
 270       <dd>
 271         Set the administrative state of <var>lport</var>, either <code>enabled</code>
 272         or <code>disabled</code>.  When a port is disabled, no traffic is allowed into
 273         or out of the port.
 274       </dd>
 275
 276       <dt><code>lport-get-enabled</code> <var>lport</var></dt>
 277       <dd>
 278         Prints the administrative state of <var>lport</var>, either <code>enabled</code>
 279         or <code>disabled</code>.
 280       </dd>
 281
 282       <dt><code>lport-set-type</code> <var>lport</var> <var>type</var></dt>
 283       <dd>
 284         Set the type for the logical port.  No special types have been implemented yet.
 285       </dd>
 286
 287       <dt><code>lport-get-type</code> <var>lport</var></dt>
 288       <dd>
 289         Get the type for the logical port.
 290       </dd>
 291
 292       <dt><code>lport-set-options</code> <var>lport</var> [<var>key=value</var>]...</dt>
 293       <dd>
 294         Set type-specific key-value options for the logical port.
 295       </dd>
 296
 297       <dt><code>lport-get-options</code> <var>lport</var></dt>
 298       <dd>
 299         Get the type-specific options for the logical port.
 300       </dd>
 301
 302     </dl>
 303
 304     <h1>Logical Router Commands</h1>
 305
 306     <dl>
 307       <dt><code>lr-add</code></dt>
 308       <dd>
 309         <p>
 310           Creates a new, unnamed logical router, which initially has no ports.
 311           The router does not have a name, other commands must refer to this
 312           router by its UUID.
 313         </p>
 314       </dd>
 315
 316       <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>lr-add</code> <var>router</var></dt>
 317       <dd>
 318         <p>
 319           Creates a new logical router named <var>router</var>, which
 320           initially has no ports.
 321         </p>
 322
 323         <p>
 324           The OVN northbound database schema does not require logical router
 325           names to be unique, but the whole point to the names is to provide an
 326           easy way for humans to refer to the routers, making duplicate names
 327           unhelpful.  Thus, without any options, this command regards it as an
 328           error if <var>router</var> is a duplicate name.  With
 329           <code>--may-exist</code>, adding a duplicate name succeeds but does
 330           not create a new logical router.  With <code>--add-duplicate</code>,
 331           the command really creates a new logical router with a duplicate
 332           name.  It is an error to specify both options.
 333         </p>
 334       </dd>
 335
 336       <dt>[<code>--if-exists</code>] <code>lr-del</code> <var>router</var></dt>
 337       <dd>
 338         Deletes <var>router</var>.  It is an error if <var>router</var> does
 339         not exist, unless <code>--if-exists</code> is specified.
 340       </dd>
 341
 342       <dt><code>lr-list</code></dt>
 343       <dd>
 344         Lists all existing routers on standard output, one per line.
 345       </dd>
 346     </dl>
 347
 348     <h1>Database Commands</h1>
 349     <p>These commands query and modify the contents of <code>ovsdb</code> tables.
 350     They are a slight abstraction of the <code>ovsdb</code> interface and
 351     as suchthey operate at a lower level than other <code>ovn-nbctl</code> commands.</p>
 352     <p><var>Identifying Tables, Records, and Columns</var></p>
 353     <p>Each of these commands has a <var>table</var> parameter to identify a table
 354     within the database.  Many of them also take a <var>record</var> parameter
 355     that identifies a particular record within a table.  The <var>record</var>
 356     parameter may be the UUID for a record, and many tables offer
 357     additional ways to identify records.  Some commands also take
 358     <var>column</var> parameters that identify a particular field within the
 359     records in a table.</p>
 360     <p>The following tables are currently defined:</p>
 361     <dl>
 362       <dt><code>Logical_Switch</code></dt>
 363       <dd>
 364         An L2 logical switch.  Records may be identified by name.
 365       </dd>
 366
 367       <dt><code>Logical_Port</code></dt>
 368       <dd>
 369         A port within an L2 logical switch.  Records may be identified by name.
 370       </dd>
 371
 372       <dt><code>ACL</code></dt>
 373       <dd>
 374         An ACL rule for a logical switch that points to it through its <var>acls</var> column.
 375       </dd>
 376
 377       <dt><code>Logical_Router</code></dt>
 378       <dd>
 379         An L3 logical router.  Records may be identified by name.
 380       </dd>
 381
 382       <dt><code>Logical_Router_Port</code></dt>
 383       <dd>
 384         A port within an L3 logical router.  Records may be identified by name.
 385       </dd>
 386
 387     <dt><code>Logical_Router_Static_Route</code></dt>
 388     <dd>
 389       A static route belonging to an L3 logical router.
 390     </dd>
 391
 392     </dl>
 393
 394     <xi:include href="lib/db-ctl-base.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 395
 396     <h1>Options</h1>
 397
 398     <dl>
 399     <dt><code>--db</code> <var>database</var></dt>
 400     <dd>
 401       The OVSDB database remote to contact.  If the <env>OVN_NB_DB</env>
 402       environment variable is set, its value is used as the default.
 403       Otherwise, the default is <code>unix:@RUNDIR@/db.sock</code>, but this
 404       default is unlikely to be useful outside of single-machine OVN test
 405       environments.
 406     </dd>
 407
 408     <dt><code>-h</code> | <code>--help</code></dt>
 409     <dt><code>-o</code> | <code>--options</code></dt>
 410     <dt><code>-V</code> | <code>--version</code></dt>
 411     </dl>
 412
 413     <h1>Logging options</h1>
 414     <dl>
 415     <dt><code>-v</code><var>spec</var>, <code>--verbose=</code><var>spec</var></dt>
 416     <dt><code>-v</code>, <code>--verbose</code></dt>
 417     <dt><code>--log-file</code>[<code>=</code><var>file</var>]</dt>
 418     <dt><code>--syslog-target=</code><var>host</var><code>:</code><var>port</var></dt>
 419     </dl>
 420
 421     <h1>PKI configuration (required to use SSL)</h1>
 422     <dl>
 423     <dt><code>-p</code>, <code>--private-key=</code><var>file</var>  file with private key</dt>
 424     <dt><code>-c</code>, <code>--certificate=</code><var>file</var>  file with certificate for private key</dt>
 425     <dt><code>-C</code>, <code>--ca-cert=</code><var>file</var>      file with peer CA certificate</dt>
 426     </dl>
 427
 428 </manpage>