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>init</code></dt>
  16       <dd>
  17         Initializes the database, if it is empty.  If the database has already
  18         been initialized, this command has no effect.
  19       </dd>
  20
  21       <dt><code>show [<var>switch</var> | <var>router</var>]</code></dt>
  22       <dd>
  23         Prints a brief overview of the database contents.  If
  24         <var>switch</var> is provided, only records related to that
  25         logical switch are shown. If
  26         <var>router</var> is provided, only records related to that
  27         logical router are shown.
  28       </dd>
  29     </dl>
  30
  31     <h1>Logical Switch Commands</h1>
  32
  33     <dl>
  34       <dt><code>ls-add</code></dt>
  35       <dd>
  36         <p>
  37           Creates a new, unnamed logical switch, which initially has no ports.
  38           The switch does not have a name, other commands must refer to this
  39           switch by its UUID.
  40         </p>
  41       </dd>
  42
  43       <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>ls-add</code> <var>switch</var></dt>
  44       <dd>
  45         <p>
  46           Creates a new logical switch named <var>switch</var>, which
  47           initially has no ports.
  48         </p>
  49
  50         <p>
  51           The OVN northbound database schema does not require logical switch
  52           names to be unique, but the whole point to the names is to provide an
  53           easy way for humans to refer to the switches, making duplicate names
  54           unhelpful.  Thus, without any options, this command regards it as an
  55           error if <var>switch</var> is a duplicate name.  With
  56           <code>--may-exist</code>, adding a duplicate name succeeds but does
  57           not create a new logical switch.  With <code>--add-duplicate</code>,
  58           the command really creates a new logical switch with a duplicate
  59           name.  It is an error to specify both options.  If there are multiple
  60           logical switches with a duplicate name, configure the logical switches
  61           using the UUID instead of the <var>switch</var> name.
  62         </p>
  63       </dd>
  64
  65       <dt>[<code>--if-exists</code>] <code>ls-del</code> <var>switch</var></dt>
  66       <dd>
  67         Deletes <var>switch</var>.  It is an error if <var>switch</var> does
  68         not exist, unless <code>--if-exists</code> is specified.
  69       </dd>
  70
  71       <dt><code>ls-list</code></dt>
  72       <dd>
  73         Lists all existing switches on standard output, one per line.
  74       </dd>
  75     </dl>
  76
  77     <h1>Logical Switch ACL Commands</h1>
  78     <dl>
  79       <dt>[<code>--log</code>] <code>acl-add</code> <var>switch</var> <var>direction</var> <var>priority</var> <var>match</var> <var>action</var></dt>
  80       <dd>
  81         Adds the specified ACL to <var>switch</var>.
  82         <var>direction</var> must be either <code>from-lport</code> or
  83         <code>to-lport</code>.  <var>priority</var> must be between
  84         <code>1</code> and <code>65534</code>, inclusive.  If
  85         <code>--log</code> is specified, packet logging is enabled for the
  86         ACL.  A full description of the fields are in <code>ovn-nb</code>(5).
  87       </dd>
  88
  89       <dt><code>acl-del</code> <var>switch</var> [<var>direction</var> [<var>priority</var> <var>match</var>]]</dt>
  90       <dd>
  91         Deletes ACLs from <var>switch</var>.  If only
  92         <var>switch</var> is supplied, all the ACLs from the logical
  93         switch are deleted.  If <var>direction</var> is also specified,
  94         then all the flows in that direction will be deleted from the
  95         logical switch.  If all the fields are given, then a single flow
  96         that matches all the fields will be deleted.
  97       </dd>
  98
  99       <dt><code>acl-list</code> <var>switch</var></dt>
 100       <dd>
 101         Lists the ACLs on <var>switch</var>.
 102       </dd>
 103     </dl>
 104
 105     <h1>Logical Switch Port Commands</h1>
 106     <dl>
 107       <dt>[<code>--may-exist</code>] <code>lsp-add</code> <var>switch</var> <var>port</var></dt>
 108       <dd>
 109         <p>
 110           Creates on <var>lswitch</var> a new logical switch port named
 111           <var>port</var>.
 112         </p>
 113
 114         <p>
 115           It is an error if a logical port named <var>port</var> already
 116           exists, unless <code>--may-exist</code> is specified.  Regardless of
 117           <code>--may-exist</code>, it is an error if the existing port is in
 118           some logical switch other than <var>switch</var> or if it has a
 119           parent port.
 120         </p>
 121       </dd>
 122
 123       <dt>[<code>--may-exist</code>] <code>lsp-add</code> <var>switch</var> <var>port</var> <var>parent</var> <var>tag</var></dt>
 124       <dd>
 125         <p>
 126           Creates on <var>switch</var> a logical switch port named
 127           <var>port</var> that is a child of <var>parent</var> that is
 128           identifed with VLAN ID <var>tag</var>.  This is useful in
 129           cases such as virtualized container environments where Open
 130           vSwitch does not have a direct connection to the container's
 131           port and it must be shared with the virtual machine's port.
 132         </p>
 133
 134         <p>
 135           It is an error if a logical port named <var>port</var> already
 136           exists, unless <code>--may-exist</code> is specified.  Regardless of
 137           <code>--may-exist</code>, it is an error if the existing port is not
 138           in <var>switch</var> or if it does not have the specified
 139           <var>parent</var> and <var>tag</var>.
 140         </p>
 141       </dd>
 142
 143       <dt>[<code>--if-exists</code>] <code>lsp-del</code> <var>port</var></dt>
 144       <dd>
 145         Deletes <var>port</var>.  It is an error if <var>port</var> does
 146         not exist, unless <code>--if-exists</code> is specified.
 147       </dd>
 148
 149       <dt><code>lsp-list</code> <var>switch</var></dt>
 150       <dd>
 151         Lists all the logical switch ports within <var>switch</var> on
 152         standard output, one per line.
 153       </dd>
 154
 155       <dt><code>lsp-get-parent</code> <var>port</var></dt>
 156       <dd>
 157         If set, get the parent port of <var>port</var>.  If not set, print
 158         nothing.
 159       </dd>
 160
 161       <dt><code>lsp-get-tag</code> <var>port</var></dt>
 162       <dd>
 163         If set, get the tag for <var>port</var> traffic.  If not set, print
 164         nothing.
 165       </dd>
 166
 167       <dt><code>lsp-set-addresses</code> <var>port</var> [<var>address</var>]...</dt>
 168       <dd>
 169         Sets the addresses associated with <var>port</var> to
 170         <var>address</var>.  Each <var>address</var> should be either an
 171         Ethernet address or an Ethernet address followed by an IP address
 172         (separated by a space and quoted to form a single command-line
 173         argument).  The special form <code>unknown</code> is also valid.
 174         Multiple Ethernet addresses or Ethernet+IP pairs may be set. If no
 175         <var>address</var> argument is given, <var>port</var> will have no
 176         addresses associated with it.
 177       </dd>
 178
 179       <dt><code>lsp-get-addresses</code> <var>port</var></dt>
 180       <dd>
 181         Lists all the addresses associated with <var>port</var> on standard
 182         output, one per line.
 183       </dd>
 184
 185       <dt><code>lsp-set-port-security</code> <var>port</var> [<var>addrs</var>]...</dt>
 186       <dd>
 187         <p>
 188           Sets the port security addresses associated with <var>port</var> to
 189           <var>addrs</var>.  Multiple sets of addresses may be set by using
 190           multiple <var>addrs</var> arguments.  If no <var>addrs</var> argument
 191           is given, <var>port</var> will not have port security enabled.
 192         </p>
 193
 194         <p>
 195           Port security limits the addresses from which a logical port may send
 196           packets and to which it may receive packets.  See the
 197           <code>ovn-nb</code>(5) documentation for the <ref
 198           column="port_security" table="Logical_Switch_Port"/> column in
 199           the <ref table="Logical_Switch_Port"/> table for details.
 200         </p>
 201       </dd>
 202
 203       <dt><code>lsp-get-port-security</code> <var>port</var></dt>
 204       <dd>
 205         Lists all the port security addresses associated with <var>port</var>
 206         on standard output, one per line.
 207       </dd>
 208
 209       <dt><code>lsp-get-up</code> <var>port</var></dt>
 210       <dd>
 211         Prints the state of <var>port</var>, either <code>up</code> or
 212         <code>down</code>.
 213       </dd>
 214
 215       <dt><code>lsp-set-enabled</code> <var>port</var> <var>state</var></dt>
 216       <dd>
 217         Set the administrative state of <var>port</var>, either <code>enabled</code>
 218         or <code>disabled</code>.  When a port is disabled, no traffic is allowed into
 219         or out of the port.
 220       </dd>
 221
 222       <dt><code>lsp-get-enabled</code> <var>port</var></dt>
 223       <dd>
 224         Prints the administrative state of <var>port</var>, either <code>enabled</code>
 225         or <code>disabled</code>.
 226       </dd>
 227
 228       <dt><code>lsp-set-type</code> <var>port</var> <var>type</var></dt>
 229       <dd>
 230         Set the type for the logical port.  No special types have been implemented yet.
 231       </dd>
 232
 233       <dt><code>lsp-get-type</code> <var>port</var></dt>
 234       <dd>
 235         Get the type for the logical port.
 236       </dd>
 237
 238       <dt><code>lsp-set-options</code> <var>port</var> [<var>key=value</var>]...</dt>
 239       <dd>
 240         Set type-specific key-value options for the logical port.
 241       </dd>
 242
 243       <dt><code>lsp-get-options</code> <var>port</var></dt>
 244       <dd>
 245         Get the type-specific options for the logical port.
 246       </dd>
 247
 248     </dl>
 249
 250     <h1>Logical Router Commands</h1>
 251
 252     <dl>
 253       <dt><code>lr-add</code></dt>
 254       <dd>
 255         <p>
 256           Creates a new, unnamed logical router, which initially has no ports.
 257           The router does not have a name, other commands must refer to this
 258           router by its UUID.
 259         </p>
 260       </dd>
 261
 262       <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>lr-add</code> <var>router</var></dt>
 263       <dd>
 264         <p>
 265           Creates a new logical router named <var>router</var>, which
 266           initially has no ports.
 267         </p>
 268
 269         <p>
 270           The OVN northbound database schema does not require logical router
 271           names to be unique, but the whole point to the names is to provide an
 272           easy way for humans to refer to the routers, making duplicate names
 273           unhelpful.  Thus, without any options, this command regards it as an
 274           error if <var>router</var> is a duplicate name.  With
 275           <code>--may-exist</code>, adding a duplicate name succeeds but does
 276           not create a new logical router.  With <code>--add-duplicate</code>,
 277           the command really creates a new logical router with a duplicate
 278           name.  It is an error to specify both options.  If there are multiple
 279           logical routers with a duplicate name, configure the logical routers
 280           using the UUID instead of the <var>router</var> name.
 281         </p>
 282       </dd>
 283
 284       <dt>[<code>--if-exists</code>] <code>lr-del</code> <var>router</var></dt>
 285       <dd>
 286         Deletes <var>router</var>.  It is an error if <var>router</var> does
 287         not exist, unless <code>--if-exists</code> is specified.
 288       </dd>
 289
 290       <dt><code>lr-list</code></dt>
 291       <dd>
 292         Lists all existing routers on standard output, one per line.
 293       </dd>
 294     </dl>
 295
 296     <h1>Logical Router Port Commands</h1>
 297
 298     <dl>
 299       <dt>[<code>--may-exist</code>] <code>lrp-add</code> <var>router</var> <var>port</var> <var>mac</var> <var>network</var>... [<code>peer=</code><var>peer</var>]</dt>
 300       <dd>
 301         <p>
 302           Creates on <var>router</var> a new logical router port named
 303           <var>port</var> with Ethernet address <var>mac</var> and one
 304           or more IP address/netmask for each <var>network</var>.
 305         </p>
 306
 307         <p>
 308           The optional argument <code>peer</code> identifies a logical
 309           router port that connects to this one.  The following example
 310           adds a router port with an IPv4 and IPv6 address with peer
 311           <code>lr1</code>:
 312         </p>
 313
 314         <p>
 315           <code>lrp-add lr0 lrp0 00:11:22:33:44:55 192.168.0.1/24 2001:db8::1/64 peer=lr1</code>
 316         </p>
 317
 318         <p>
 319           It is an error if a logical router port named <var>port</var>
 320           already exists, unless <code>--may-exist</code> is specified.
 321           Regardless of <code>--may-exist</code>, it is an error if the
 322           existing router port is in some logical router other than
 323           <var>router</var>.
 324         </p>
 325       </dd>
 326
 327       <dt>[<code>--if-exists</code>] <code>lrp-del</code> <var>port</var></dt>
 328       <dd>
 329         Deletes <var>port</var>.  It is an error if <var>port</var> does
 330         not exist, unless <code>--if-exists</code> is specified.
 331       </dd>
 332
 333       <dt><code>lrp-list</code> <var>router</var></dt>
 334       <dd>
 335         Lists all the logical router ports within <var>router</var> on
 336         standard output, one per line.
 337       </dd>
 338
 339       <dt><code>lrp-set-enabled</code> <var>port</var> <var>state</var></dt>
 340       <dd>
 341         Set the administrative state of <var>port</var>, either
 342         <code>enabled</code> or <code>disabled</code>.  When a port is
 343         disabled, no traffic is allowed into or out of the port.
 344       </dd>
 345
 346       <dt><code>lrp-get-enabled</code> <var>port</var></dt>
 347       <dd>
 348         Prints the administrative state of <var>port</var>, either
 349         <code>enabled</code> or <code>disabled</code>.
 350       </dd>
 351     </dl>
 352
 353     <h1>Logical Router Static Route Commands</h1>
 354
 355     <dl>
 356       <dt>[<code>--may-exist</code>] <code>lr-route-add</code> <var>router</var> <var>prefix</var> <var>nexthop</var> [<var>port</var>]</dt>
 357       <dd>
 358         <p>
 359           Adds the specified route to <var>router</var>.
 360           <var>prefix</var> describes an IPv4 or IPv6 prefix for this
 361           route, such as <code>192.168.100.0/24</code>.
 362           <var>nexthop</var> specifies the gateway to use for this
 363           route, which should be the IP address of one of
 364           <var>router</var> logical router ports or the IP address of a
 365           logical port.  If <var>port</var> is specified, packets that
 366           match this route will be sent out that port.  When
 367           <var>port</var> is omitted, OVN infers the output port based
 368           on <var>nexthop</var>.
 369         </p>
 370
 371         <p>
 372           It is an error if a route with <var>prefix</var> already exists,
 373           unless <code>--may-exist</code> is specified.
 374         </p>
 375       </dd>
 376
 377       <dt>[<code>--if-exists</code>] <code>lr-route-del</code> <var>router</var> [<var>prefix</var>]</dt>
 378       <dd>
 379         <p>
 380           Deletes routes from <var>router</var>.  If only <var>router</var>
 381           is supplied, all the routes from the logical router are
 382           deleted.  If <var>prefix</var> is also specified, then all the
 383           routes that match the prefix will be deleted from the logical
 384           router.
 385         </p>
 386
 387         <p>
 388           It is an error if <code>prefix</code> is specified and there
 389           is no matching route entry, unless <code>--if-exists</code> is
 390           specified.
 391         </p>
 392       </dd>
 393
 394       <dt><code>lr-route-list</code> <var>router</var></dt>
 395       <dd>
 396         Lists the routes on <var>router</var>.
 397       </dd>
 398     </dl>
 399
 400     <h1>DHCP Options commands</h1>
 401
 402     <dl>
 403       <dt><code>dhcp-options-create</code> <var>cidr</var> [<var>key=value</var>]</dt>
 404       <dd>
 405         Creates a new DHCP Options entry in the <code>DHCP_Options</code> table
 406         with the specified <code>cidr</code> and optional <code>external-ids</code>.
 407       </dd>
 408
 409       <dt><code>dhcp-options-list</code></dt>
 410       <dd>
 411         Lists the DHCP Options entries.
 412       </dd>
 413
 414       <dt><code>dhcp-options-del</code> <var>dhcp-option</var></dt>
 415       <dd>
 416         Deletes the DHCP Options entry referred by <var>dhcp-option</var> UUID.
 417       </dd>
 418
 419       <dt><code>dhcp-options-set-options</code> <var>dhcp-option</var> [<var>key=value</var>]...</dt>
 420       <dd>
 421         Set the DHCP Options for the <var>dhcp-option</var> UUID.
 422       </dd>
 423
 424       <dt><code>dhcp-options-get-options</code> <var>dhcp-option</var></dt>
 425       <dd>
 426         Lists the DHCP Options for the <var>dhcp-option</var> UUID.
 427       </dd>
 428     </dl>
 429
 430     <h1>Database Commands</h1>
 431     <p>These commands query and modify the contents of <code>ovsdb</code> tables.
 432     They are a slight abstraction of the <code>ovsdb</code> interface and
 433     as suchthey operate at a lower level than other <code>ovn-nbctl</code> commands.</p>
 434     <p><var>Identifying Tables, Records, and Columns</var></p>
 435     <p>Each of these commands has a <var>table</var> parameter to identify a table
 436     within the database.  Many of them also take a <var>record</var> parameter
 437     that identifies a particular record within a table.  The <var>record</var>
 438     parameter may be the UUID for a record, and many tables offer
 439     additional ways to identify records.  Some commands also take
 440     <var>column</var> parameters that identify a particular field within the
 441     records in a table.</p>
 442     <p>The following tables are currently defined:</p>
 443     <dl>
 444       <dt><code>Logical_Switch</code></dt>
 445       <dd>
 446         An L2 logical switch.  Records may be identified by name.
 447       </dd>
 448
 449       <dt><code>Logical_Switch_Port</code></dt>
 450       <dd>
 451         A port within an L2 logical switch.  Records may be identified by name.
 452       </dd>
 453
 454       <dt><code>ACL</code></dt>
 455       <dd>
 456         An ACL rule for a logical switch that points to it through its <var>acls</var> column.
 457       </dd>
 458
 459       <dt><code>Logical_Router</code></dt>
 460       <dd>
 461         An L3 logical router.  Records may be identified by name.
 462       </dd>
 463
 464       <dt><code>Logical_Router_Port</code></dt>
 465       <dd>
 466         A port within an L3 logical router.  Records may be identified by name.
 467       </dd>
 468
 469     <dt><code>Logical_Router_Static_Route</code></dt>
 470     <dd>
 471       A static route belonging to an L3 logical router.
 472     </dd>
 473
 474     </dl>
 475
 476     <xi:include href="lib/db-ctl-base.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 477
 478     <h1>Options</h1>
 479
 480     <dl>
 481       <dt><code>--no-wait</code> | <code>--wait=none</code></dt>
 482       <dt><code>--wait=sb</code></dt>
 483       <dt><code>--wait=hv</code></dt>
 484
 485       <dd>
 486         <p>
 487           These options control whether and how <code>ovn-nbctl</code> waits
 488           for the OVN system to become up-to-date with changes made in an
 489           <code>ovn-nbctl</code> invocation.
 490         </p>
 491
 492         <p>
 493           By default, or if <code>--no-wait</code> or <code>--wait=none</code>,
 494           <code>ovn-nbctl</code> exits immediately after confirming that
 495           changes have been committed to the northbound database, without
 496           waiting.
 497         </p>
 498
 499         <p>
 500           With <code>--wait=sb</code>, before <code>ovn-nbctl</code> exits, it
 501           waits for <code>ovn-northd</code> to bring the southbound database
 502           up-to-date with the northbound database updates.
 503         </p>
 504
 505         <p>
 506           With <code>--wait=hv</code>, before <code>ovn-nbctl</code> exits, it
 507           additionally waits for all OVN chassis (hypervisors and gateways) to
 508           become up-to-date with the northbound database updates.  (This can
 509           become an indefinite wait if any chassis is malfunctioning.)
 510         </p>
 511       </dd>
 512
 513     <dt><code>--db</code> <var>database</var></dt>
 514     <dd>
 515       The OVSDB database remote to contact.  If the <env>OVN_NB_DB</env>
 516       environment variable is set, its value is used as the default.
 517       Otherwise, the default is <code>unix:@RUNDIR@/db.sock</code>, but this
 518       default is unlikely to be useful outside of single-machine OVN test
 519       environments.
 520     </dd>
 521
 522     <dt><code>-h</code> | <code>--help</code></dt>
 523     <dt><code>-o</code> | <code>--options</code></dt>
 524     <dt><code>-V</code> | <code>--version</code></dt>
 525     </dl>
 526
 527     <h1>Logging options</h1>
 528     <dl>
 529     <dt><code>-v</code><var>spec</var>, <code>--verbose=</code><var>spec</var></dt>
 530     <dt><code>-v</code>, <code>--verbose</code></dt>
 531     <dt><code>--log-file</code>[<code>=</code><var>file</var>]</dt>
 532     <dt><code>--syslog-target=</code><var>host</var><code>:</code><var>port</var></dt>
 533     </dl>
 534
 535     <h1>PKI configuration (required to use SSL)</h1>
 536     <dl>
 537     <dt><code>-p</code>, <code>--private-key=</code><var>file</var>  file with private key</dt>
 538     <dt><code>-c</code>, <code>--certificate=</code><var>file</var>  file with certificate for private key</dt>
 539     <dt><code>-C</code>, <code>--ca-cert=</code><var>file</var>      file with peer CA certificate</dt>
 540     </dl>
 541
 542 </manpage>