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> [<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 IP
 298           address/netmask <var>network</var>.  If <var>peer</var> is
 299           specified, it identifies a logical router port that connects
 300           to this one.
 301         </p>
 302
 303         <p>
 304           It is an error if a logical router port named <var>port</var>
 305           already exists, unless <code>--may-exist</code> is specified.
 306           Regardless of <code>--may-exist</code>, it is an error if the
 307           existing router port is in some logical router other than
 308           <var>router</var>.
 309         </p>
 310       </dd>
 311
 312       <dt>[<code>--if-exists</code>] <code>lrp-del</code> <var>port</var></dt>
 313       <dd>
 314         Deletes <var>port</var>.  It is an error if <var>port</var> does
 315         not exist, unless <code>--if-exists</code> is specified.
 316       </dd>
 317
 318       <dt><code>lrp-list</code> <var>router</var></dt>
 319       <dd>
 320         Lists all the logical router ports within <var>router</var> on
 321         standard output, one per line.
 322       </dd>
 323
 324       <dt><code>lrp-set-enabled</code> <var>port</var> <var>state</var></dt>
 325       <dd>
 326         Set the administrative state of <var>port</var>, either
 327         <code>enabled</code> or <code>disabled</code>.  When a port is
 328         disabled, no traffic is allowed into or out of the port.
 329       </dd>
 330
 331       <dt><code>lrp-get-enabled</code> <var>port</var></dt>
 332       <dd>
 333         Prints the administrative state of <var>port</var>, either
 334         <code>enabled</code> or <code>disabled</code>.
 335       </dd>
 336     </dl>
 337
 338     <h1>Logical Router Static Route Commands</h1>
 339
 340     <dl>
 341       <dt>[<code>--may-exist</code>] <code>lr-route-add</code> <var>router</var> <var>prefix</var> <var>nexthop</var> [<var>port</var>]</dt>
 342       <dd>
 343         <p>
 344           Adds the specified route to <var>router</var>.
 345           <var>prefix</var> describes an IPv4 or IPv6 prefix for this
 346           route, such as <code>192.168.100.0/24</code>.
 347           <var>nexthop</var> specifies the gateway to use for this
 348           route, which should be the IP address of one of
 349           <var>router</var> logical router ports or the IP address of a
 350           logical port.  If <var>port</var> is specified, packets that
 351           match this route will be sent out that port.  When
 352           <var>port</var> is omitted, OVN infers the output port based
 353           on <var>nexthop</var>.
 354         </p>
 355
 356         <p>
 357           It is an error if a route with <var>prefix</var> already exists,
 358           unless <code>--may-exist</code> is specified.
 359         </p>
 360       </dd>
 361
 362       <dt>[<code>--if-exists</code>] <code>lr-route-del</code> <var>router</var> [<var>prefix</var>]</dt>
 363       <dd>
 364         <p>
 365           Deletes routes from <var>router</var>.  If only <var>router</var>
 366           is supplied, all the routes from the logical router are
 367           deleted.  If <var>prefix</var> is also specified, then all the
 368           routes that match the prefix will be deleted from the logical
 369           router.
 370         </p>
 371
 372         <p>
 373           It is an error if <code>prefix</code> is specified and there
 374           is no matching route entry, unless <code>--if-exists</code> is
 375           specified.
 376         </p>
 377       </dd>
 378
 379       <dt><code>lr-route-list</code> <var>router</var></dt>
 380       <dd>
 381         Lists the routes on <var>router</var>.
 382       </dd>
 383     </dl>
 384
 385     <h1>Database Commands</h1>
 386     <p>These commands query and modify the contents of <code>ovsdb</code> tables.
 387     They are a slight abstraction of the <code>ovsdb</code> interface and
 388     as suchthey operate at a lower level than other <code>ovn-nbctl</code> commands.</p>
 389     <p><var>Identifying Tables, Records, and Columns</var></p>
 390     <p>Each of these commands has a <var>table</var> parameter to identify a table
 391     within the database.  Many of them also take a <var>record</var> parameter
 392     that identifies a particular record within a table.  The <var>record</var>
 393     parameter may be the UUID for a record, and many tables offer
 394     additional ways to identify records.  Some commands also take
 395     <var>column</var> parameters that identify a particular field within the
 396     records in a table.</p>
 397     <p>The following tables are currently defined:</p>
 398     <dl>
 399       <dt><code>Logical_Switch</code></dt>
 400       <dd>
 401         An L2 logical switch.  Records may be identified by name.
 402       </dd>
 403
 404       <dt><code>Logical_Switch_Port</code></dt>
 405       <dd>
 406         A port within an L2 logical switch.  Records may be identified by name.
 407       </dd>
 408
 409       <dt><code>ACL</code></dt>
 410       <dd>
 411         An ACL rule for a logical switch that points to it through its <var>acls</var> column.
 412       </dd>
 413
 414       <dt><code>Logical_Router</code></dt>
 415       <dd>
 416         An L3 logical router.  Records may be identified by name.
 417       </dd>
 418
 419       <dt><code>Logical_Router_Port</code></dt>
 420       <dd>
 421         A port within an L3 logical router.  Records may be identified by name.
 422       </dd>
 423
 424     <dt><code>Logical_Router_Static_Route</code></dt>
 425     <dd>
 426       A static route belonging to an L3 logical router.
 427     </dd>
 428
 429     </dl>
 430
 431     <xi:include href="lib/db-ctl-base.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 432
 433     <h1>Options</h1>
 434
 435     <dl>
 436     <dt><code>--db</code> <var>database</var></dt>
 437     <dd>
 438       The OVSDB database remote to contact.  If the <env>OVN_NB_DB</env>
 439       environment variable is set, its value is used as the default.
 440       Otherwise, the default is <code>unix:@RUNDIR@/db.sock</code>, but this
 441       default is unlikely to be useful outside of single-machine OVN test
 442       environments.
 443     </dd>
 444
 445     <dt><code>-h</code> | <code>--help</code></dt>
 446     <dt><code>-o</code> | <code>--options</code></dt>
 447     <dt><code>-V</code> | <code>--version</code></dt>
 448     </dl>
 449
 450     <h1>Logging options</h1>
 451     <dl>
 452     <dt><code>-v</code><var>spec</var>, <code>--verbose=</code><var>spec</var></dt>
 453     <dt><code>-v</code>, <code>--verbose</code></dt>
 454     <dt><code>--log-file</code>[<code>=</code><var>file</var>]</dt>
 455     <dt><code>--syslog-target=</code><var>host</var><code>:</code><var>port</var></dt>
 456     </dl>
 457
 458     <h1>PKI configuration (required to use SSL)</h1>
 459     <dl>
 460     <dt><code>-p</code>, <code>--private-key=</code><var>file</var>  file with private key</dt>
 461     <dt><code>-c</code>, <code>--certificate=</code><var>file</var>  file with certificate for private key</dt>
 462     <dt><code>-C</code>, <code>--ca-cert=</code><var>file</var>      file with peer CA certificate</dt>
 463     </dl>
 464
 465 </manpage>