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