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