1 <?xml version="1.0" encoding="utf-8"?>
2 <manpage program="ovn-nbctl" section="8" title="ovn-nbctl">
4 <p>ovn-nbctl -- Open Virtual Network northbound db management utility</p>
7 <p><code>ovn-nbctl</code> [<var>options</var>] <var>command</var> [<var>arg</var>...]</p>
10 <p>This utility can be used to manage the OVN northbound database.</p>
12 <h1>General Commands</h1>
15 <dt><code>init</code></dt>
17 Initializes the database, if it is empty. If the database has already
18 been initialized, this command has no effect.
21 <dt><code>show [<var>switch</var> | <var>router</var>]</code></dt>
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.
31 <h1>Logical Switch Commands</h1>
34 <dt><code>ls-add</code></dt>
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
43 <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>ls-add</code> <var>switch</var></dt>
46 Creates a new logical switch named <var>switch</var>, which
47 initially has no ports.
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.
65 <dt>[<code>--if-exists</code>] <code>ls-del</code> <var>switch</var></dt>
67 Deletes <var>switch</var>. It is an error if <var>switch</var> does
68 not exist, unless <code>--if-exists</code> is specified.
71 <dt><code>ls-list</code></dt>
73 Lists all existing switches on standard output, one per line.
77 <h1>Logical Switch ACL Commands</h1>
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>
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).
89 <dt><code>acl-del</code> <var>switch</var> [<var>direction</var> [<var>priority</var> <var>match</var>]]</dt>
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.
99 <dt><code>acl-list</code> <var>switch</var></dt>
101 Lists the ACLs on <var>switch</var>.
105 <h1>Logical Switch Port Commands</h1>
107 <dt>[<code>--may-exist</code>] <code>lsp-add</code> <var>switch</var> <var>port</var></dt>
110 Creates on <var>lswitch</var> a new logical switch port named
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
123 <dt>[<code>--may-exist</code>] <code>lsp-add</code> <var>switch</var> <var>port</var> <var>parent</var> <var>tag</var></dt>
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.
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>.
143 <dt>[<code>--if-exists</code>] <code>lsp-del</code> <var>port</var></dt>
145 Deletes <var>port</var>. It is an error if <var>port</var> does
146 not exist, unless <code>--if-exists</code> is specified.
149 <dt><code>lsp-list</code> <var>switch</var></dt>
151 Lists all the logical switch ports within <var>switch</var> on
152 standard output, one per line.
155 <dt><code>lsp-get-parent</code> <var>port</var></dt>
157 If set, get the parent port of <var>port</var>. If not set, print
161 <dt><code>lsp-get-tag</code> <var>port</var></dt>
163 If set, get the tag for <var>port</var> traffic. If not set, print
167 <dt><code>lsp-set-addresses</code> <var>port</var> [<var>address</var>]...</dt>
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.
179 <dt><code>lsp-get-addresses</code> <var>port</var></dt>
181 Lists all the addresses associated with <var>port</var> on standard
182 output, one per line.
185 <dt><code>lsp-set-port-security</code> <var>port</var> [<var>addrs</var>]...</dt>
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.
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.
203 <dt><code>lsp-get-port-security</code> <var>port</var></dt>
205 Lists all the port security addresses associated with <var>port</var>
206 on standard output, one per line.
209 <dt><code>lsp-get-up</code> <var>port</var></dt>
211 Prints the state of <var>port</var>, either <code>up</code> or
215 <dt><code>lsp-set-enabled</code> <var>port</var> <var>state</var></dt>
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
222 <dt><code>lsp-get-enabled</code> <var>port</var></dt>
224 Prints the administrative state of <var>port</var>, either <code>enabled</code>
225 or <code>disabled</code>.
228 <dt><code>lsp-set-type</code> <var>port</var> <var>type</var></dt>
230 Set the type for the logical port. No special types have been implemented yet.
233 <dt><code>lsp-get-type</code> <var>port</var></dt>
235 Get the type for the logical port.
238 <dt><code>lsp-set-options</code> <var>port</var> [<var>key=value</var>]...</dt>
240 Set type-specific key-value options for the logical port.
243 <dt><code>lsp-get-options</code> <var>port</var></dt>
245 Get the type-specific options for the logical port.
250 <h1>Logical Router Commands</h1>
253 <dt><code>lr-add</code></dt>
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
262 <dt>[<code>--may-exist</code> | <code>--add-duplicate</code>] <code>lr-add</code> <var>router</var></dt>
265 Creates a new logical router named <var>router</var>, which
266 initially has no ports.
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.
284 <dt>[<code>--if-exists</code>] <code>lr-del</code> <var>router</var></dt>
286 Deletes <var>router</var>. It is an error if <var>router</var> does
287 not exist, unless <code>--if-exists</code> is specified.
290 <dt><code>lr-list</code></dt>
292 Lists all existing routers on standard output, one per line.
296 <h1>Logical Router Port Commands</h1>
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>
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>.
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
315 <code>lrp-add lr0 lrp0 00:11:22:33:44:55 192.168.0.1/24 2001:db8::1/64 peer=lr1</code>
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
327 <dt>[<code>--if-exists</code>] <code>lrp-del</code> <var>port</var></dt>
329 Deletes <var>port</var>. It is an error if <var>port</var> does
330 not exist, unless <code>--if-exists</code> is specified.
333 <dt><code>lrp-list</code> <var>router</var></dt>
335 Lists all the logical router ports within <var>router</var> on
336 standard output, one per line.
339 <dt><code>lrp-set-enabled</code> <var>port</var> <var>state</var></dt>
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.
346 <dt><code>lrp-get-enabled</code> <var>port</var></dt>
348 Prints the administrative state of <var>port</var>, either
349 <code>enabled</code> or <code>disabled</code>.
353 <h1>Logical Router Static Route Commands</h1>
356 <dt>[<code>--may-exist</code>] <code>lr-route-add</code> <var>router</var> <var>prefix</var> <var>nexthop</var> [<var>port</var>]</dt>
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>.
372 It is an error if a route with <var>prefix</var> already exists,
373 unless <code>--may-exist</code> is specified.
377 <dt>[<code>--if-exists</code>] <code>lr-route-del</code> <var>router</var> [<var>prefix</var>]</dt>
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
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
394 <dt><code>lr-route-list</code> <var>router</var></dt>
396 Lists the routes on <var>router</var>.
400 <h1>DHCP Options commands</h1>
403 <dt><code>dhcp-options-create</code> <var>cidr</var> [<var>key=value</var>]</dt>
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>.
409 <dt><code>dhcp-options-list</code></dt>
411 Lists the DHCP Options entries.
414 <dt><code>dhcp-options-del</code> <var>dhcp-option</var></dt>
416 Deletes the DHCP Options entry referred by <var>dhcp-option</var> UUID.
419 <dt><code>dhcp-options-set-options</code> <var>dhcp-option</var> [<var>key=value</var>]...</dt>
421 Set the DHCP Options for the <var>dhcp-option</var> UUID.
424 <dt><code>dhcp-options-get-options</code> <var>dhcp-option</var></dt>
426 Lists the DHCP Options for the <var>dhcp-option</var> UUID.
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>
444 <dt><code>Logical_Switch</code></dt>
446 An L2 logical switch. Records may be identified by name.
449 <dt><code>Logical_Switch_Port</code></dt>
451 A port within an L2 logical switch. Records may be identified by name.
454 <dt><code>ACL</code></dt>
456 An ACL rule for a logical switch that points to it through its <var>acls</var> column.
459 <dt><code>Logical_Router</code></dt>
461 An L3 logical router. Records may be identified by name.
464 <dt><code>Logical_Router_Port</code></dt>
466 A port within an L3 logical router. Records may be identified by name.
469 <dt><code>Logical_Router_Static_Route</code></dt>
471 A static route belonging to an L3 logical router.
476 <xi:include href="lib/db-ctl-base.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
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>
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.
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
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.
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.)
513 <dt><code>--db</code> <var>database</var></dt>
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
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>
527 <h1>Logging options</h1>
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>
535 <h1>PKI configuration (required to use SSL)</h1>
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>