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_request
</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 identified with VLAN ID
<var>tag_request
</var>. If
129 <var>tag_request
</var> is
<code>0</code>,
<code>ovn-northd
</code>
130 generates a tag that is unique in the scope of
<var>parent
</var>.
131 This is useful in cases such as virtualized container environments
132 where Open vSwitch does not have a direct connection to the
133 container's port and it must be shared with the virtual machine's
138 It is an error if a logical port named
<var>port
</var> already
139 exists, unless
<code>--may-exist
</code> is specified. Regardless of
140 <code>--may-exist
</code>, it is an error if the existing port is not
141 in
<var>switch
</var> or if it does not have the specified
142 <var>parent
</var> and
<var>tag_request
</var>.
146 <dt>[
<code>--if-exists
</code>]
<code>lsp-del
</code> <var>port
</var></dt>
148 Deletes
<var>port
</var>. It is an error if
<var>port
</var> does
149 not exist, unless
<code>--if-exists
</code> is specified.
152 <dt><code>lsp-list
</code> <var>switch
</var></dt>
154 Lists all the logical switch ports within
<var>switch
</var> on
155 standard output, one per line.
158 <dt><code>lsp-get-parent
</code> <var>port
</var></dt>
160 If set, get the parent port of
<var>port
</var>. If not set, print
164 <dt><code>lsp-get-tag
</code> <var>port
</var></dt>
166 If set, get the tag for
<var>port
</var> traffic. If not set, print
170 <dt><code>lsp-set-addresses
</code> <var>port
</var> [
<var>address
</var>]...
</dt>
173 Sets the addresses associated with
<var>port
</var> to
174 <var>address
</var>. Each
<var>address
</var> should be one of the
179 <dt>an Ethernet address, optionally followed by a space and one or more IP addresses
</dt>
181 OVN delivers packets for the Ethernet address to this port.
184 <dt><code>unknown
</code></dt>
186 OVN delivers unicast Ethernet packets whose destination MAC address
187 is not in any logical port's addresses column to ports with address
188 <code>unknown
</code>.
191 <dt><code>dynamic
</code></dt>
193 Use this keyword to make
<code>ovn-northd
</code> generate a
194 globally unique MAC address and choose an unused IPv4 address with
195 the logical port's subnet and store them in the port's
196 <code>dynamic_addresses
</code> column.
201 Multiple addresses may be set. If no
<var>address
</var> argument is
202 given,
<var>port
</var> will have no addresses associated with it.
206 <dt><code>lsp-get-addresses
</code> <var>port
</var></dt>
208 Lists all the addresses associated with
<var>port
</var> on standard
209 output, one per line.
212 <dt><code>lsp-set-port-security
</code> <var>port
</var> [
<var>addrs
</var>]...
</dt>
215 Sets the port security addresses associated with
<var>port
</var> to
216 <var>addrs
</var>. Multiple sets of addresses may be set by using
217 multiple
<var>addrs
</var> arguments. If no
<var>addrs
</var> argument
218 is given,
<var>port
</var> will not have port security enabled.
222 Port security limits the addresses from which a logical port may send
223 packets and to which it may receive packets. See the
224 <code>ovn-nb
</code>(
5) documentation for the
<ref
225 column=
"port_security" table=
"Logical_Switch_Port"/> column in
226 the
<ref table=
"Logical_Switch_Port"/> table for details.
230 <dt><code>lsp-get-port-security
</code> <var>port
</var></dt>
232 Lists all the port security addresses associated with
<var>port
</var>
233 on standard output, one per line.
236 <dt><code>lsp-get-up
</code> <var>port
</var></dt>
238 Prints the state of
<var>port
</var>, either
<code>up
</code> or
242 <dt><code>lsp-set-enabled
</code> <var>port
</var> <var>state
</var></dt>
244 Set the administrative state of
<var>port
</var>, either
<code>enabled
</code>
245 or
<code>disabled
</code>. When a port is disabled, no traffic is allowed into
249 <dt><code>lsp-get-enabled
</code> <var>port
</var></dt>
251 Prints the administrative state of
<var>port
</var>, either
<code>enabled
</code>
252 or
<code>disabled
</code>.
255 <dt><code>lsp-set-type
</code> <var>port
</var> <var>type
</var></dt>
257 Set the type for the logical port. No special types have been implemented yet.
260 <dt><code>lsp-get-type
</code> <var>port
</var></dt>
262 Get the type for the logical port.
265 <dt><code>lsp-set-options
</code> <var>port
</var> [
<var>key=value
</var>]...
</dt>
267 Set type-specific key-value options for the logical port.
270 <dt><code>lsp-get-options
</code> <var>port
</var></dt>
272 Get the type-specific options for the logical port.
277 <h1>Logical Router Commands
</h1>
280 <dt><code>lr-add
</code></dt>
283 Creates a new, unnamed logical router, which initially has no ports.
284 The router does not have a name, other commands must refer to this
289 <dt>[
<code>--may-exist
</code> |
<code>--add-duplicate
</code>]
<code>lr-add
</code> <var>router
</var></dt>
292 Creates a new logical router named
<var>router
</var>, which
293 initially has no ports.
297 The OVN northbound database schema does not require logical router
298 names to be unique, but the whole point to the names is to provide an
299 easy way for humans to refer to the routers, making duplicate names
300 unhelpful. Thus, without any options, this command regards it as an
301 error if
<var>router
</var> is a duplicate name. With
302 <code>--may-exist
</code>, adding a duplicate name succeeds but does
303 not create a new logical router. With
<code>--add-duplicate
</code>,
304 the command really creates a new logical router with a duplicate
305 name. It is an error to specify both options. If there are multiple
306 logical routers with a duplicate name, configure the logical routers
307 using the UUID instead of the
<var>router
</var> name.
311 <dt>[
<code>--if-exists
</code>]
<code>lr-del
</code> <var>router
</var></dt>
313 Deletes
<var>router
</var>. It is an error if
<var>router
</var> does
314 not exist, unless
<code>--if-exists
</code> is specified.
317 <dt><code>lr-list
</code></dt>
319 Lists all existing routers on standard output, one per line.
323 <h1>Logical Router Port Commands
</h1>
326 <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>
329 Creates on
<var>router
</var> a new logical router port named
330 <var>port
</var> with Ethernet address
<var>mac
</var> and one
331 or more IP address/netmask for each
<var>network
</var>.
335 The optional argument
<code>peer
</code> identifies a logical
336 router port that connects to this one. The following example
337 adds a router port with an IPv4 and IPv6 address with peer
342 <code>lrp-add lr0 lrp0
00:
11:
22:
33:
44:
55 192.168.0.1/
24 2001:db8::
1/
64 peer=lr1
</code>
346 It is an error if a logical router port named
<var>port
</var>
347 already exists, unless
<code>--may-exist
</code> is specified.
348 Regardless of
<code>--may-exist
</code>, it is an error if the
349 existing router port is in some logical router other than
354 <dt>[
<code>--if-exists
</code>]
<code>lrp-del
</code> <var>port
</var></dt>
356 Deletes
<var>port
</var>. It is an error if
<var>port
</var> does
357 not exist, unless
<code>--if-exists
</code> is specified.
360 <dt><code>lrp-list
</code> <var>router
</var></dt>
362 Lists all the logical router ports within
<var>router
</var> on
363 standard output, one per line.
366 <dt><code>lrp-set-enabled
</code> <var>port
</var> <var>state
</var></dt>
368 Set the administrative state of
<var>port
</var>, either
369 <code>enabled
</code> or
<code>disabled
</code>. When a port is
370 disabled, no traffic is allowed into or out of the port.
373 <dt><code>lrp-get-enabled
</code> <var>port
</var></dt>
375 Prints the administrative state of
<var>port
</var>, either
376 <code>enabled
</code> or
<code>disabled
</code>.
380 <h1>Logical Router Static Route Commands
</h1>
383 <dt>[
<code>--may-exist
</code>] [
<code>--policy
</code>=
<var>POLICY
</var>]
<code>lr-route-add
</code> <var>router
</var> <var>prefix
</var> <var>nexthop
</var> [
<var>port
</var>]
</dt>
386 Adds the specified route to
<var>router
</var>.
387 <var>prefix
</var> describes an IPv4 or IPv6 prefix for this
388 route, such as
<code>192.168.100.0/
24</code>.
389 <var>nexthop
</var> specifies the gateway to use for this
390 route, which should be the IP address of one of
391 <var>router
</var> logical router ports or the IP address of a
392 logical port. If
<var>port
</var> is specified, packets that
393 match this route will be sent out that port. When
394 <var>port
</var> is omitted, OVN infers the output port based
395 on
<var>nexthop
</var>.
399 <code>--policy
</code> describes the policy used to make routing
400 decisions. This should be one of
"dst-ip" or
"src-ip". If not
401 specified, the default is
"dst-ip".
405 It is an error if a route with
<var>prefix
</var> already exists,
406 unless
<code>--may-exist
</code> is specified.
410 <dt>[
<code>--if-exists
</code>]
<code>lr-route-del
</code> <var>router
</var> [
<var>prefix
</var>]
</dt>
413 Deletes routes from
<var>router
</var>. If only
<var>router
</var>
414 is supplied, all the routes from the logical router are
415 deleted. If
<var>prefix
</var> is also specified, then all the
416 routes that match the prefix will be deleted from the logical
421 It is an error if
<code>prefix
</code> is specified and there
422 is no matching route entry, unless
<code>--if-exists
</code> is
427 <dt><code>lr-route-list
</code> <var>router
</var></dt>
429 Lists the routes on
<var>router
</var>.
433 <h1>Load Balancer Commands
</h1>
435 <dt>[
<code>--may-exist
</code> |
<code>--add-duplicate
</code>]
<code>lb-add
</code> <var>lb
</var> <var>vip
</var> <var>ips
</var> [
<var>protocol
</var>]
</dt>
438 Creates a new load balancer named
<var>lb
</var> with the provided
439 <var>vip
</var> and
<var>ips
</var> or adds the
<var>vip
</var> to
440 an existing
<var>lb
</var>.
<var>vip
</var> should be a
441 virtual IPv4 address (or an IPv4 address and a port number with
442 <code>:
</code> as a separator). Examples for
<var>vip
</var> are
443 <code>192.168.1.4</code> and
<code>192.168.1.5:
8080</code>.
444 <var>ips
</var> should be comma separated IPv4 endpoints (or comma
445 separated IPv4 addresses and port numbers with
<code>:
</code> as a
446 separator). Examples for
<var>ips
</var> are
<code>10.0.0.1,
10.0.0.2
447 </code>or
<code>20.0.0.10:
8800,
20.0.0.11:
8800</code>.
451 The optional argument
<var>protocol
</var> must be either
452 <code>tcp
</code> or
<code>udp
</code>. This argument is useful when
453 a port number is provided as part of the
<var>vip
</var>. If the
454 <var>protocol
</var> is unspecified and a port number is provided as
455 part of the
<var>vip
</var>, OVN assumes the
<var>protocol
</var> to
460 It is an error if the
<var>vip
</var> already exists in the load
461 balancer named
<var>lb
</var>, unless
<code>--may-exist
</code> is
462 specified. With
<code>--add-duplicate
</code>, the command really
463 creates a new load balancer with a duplicate name.
467 The following example adds a load balancer.
471 <code>lb-add lb0
30.0.0.10:
80
472 192.168.10.10:
80,
192.168.10.20:
80,
192.168.10.30:
80 udp
</code>
476 <dt>[
<code>--if-exists
</code>]
<code>lb-del
</code> <var>lb
</var> [
<var>vip
</var>]
</dt>
478 Deletes
<var>lb
</var> or the
<var>vip
</var> from
<var>lb
</var>.
479 If
<var>vip
</var> is supplied, only the
<var>vip
</var> will be
480 deleted from the
<var>lb
</var>. If only the
<var>lb
</var> is supplied,
481 the
<var>lb
</var> will be deleted. It is an error if
<var>vip
</var>
482 does not already exist in
<var>lb
</var>, unless
483 <code>--if-exists
</code> is specified.
486 <dt><code>lb-list
</code> [
<var>lb
</var>]
</dt>
488 Lists the LBs. If
<var>lb
</var> is also specified, then only the
489 specified
<var>lb
</var> will be listed.
492 <dt>[
<code>--may-exist
</code>]
<code>ls-lb-add
</code> <var>switch
</var> <var>lb
</var></dt>
494 Adds the specified
<var>lb
</var> to
<var>switch
</var>.
495 It is an error if a load balancer named
<var>lb
</var> already exists
496 in the
<var>switch
</var>, unless
<code>--may-exist
</code> is specified.
499 <dt>[
<code>--if-exists
</code>]
<code>ls-lb-del
</code> <var>switch
</var> [
<var>lb
</var>]
</dt>
501 Removes
<var>lb
</var> from
<var>switch
</var>. If only
502 <var>switch
</var> is supplied, all the LBs from the logical switch are
503 removed. If
<var>lb
</var> is also specified, then only the
504 <var>lb
</var> will be removed from the logical switch.
505 It is an error if
<var>lb
</var> does not exist in the
506 <var>switch
</var>, unless
<code>--if-exists
</code> is specified.
509 <dt><code>ls-lb-list
</code> <var>switch
</var></dt>
511 Lists the LBs for the given
<var>switch
</var>.
514 <dt>[
<code>--may-exist
</code>]
<code>lr-lb-add
</code> <var>router
</var> <var>lb
</var></dt>
516 Adds the specified
<var>lb
</var> to
<var>router
</var>.
517 It is an error if a load balancer named
<var>lb
</var> already exists
518 in the
<var>router
</var>, unless
<code>--may-exist
</code> is specified.
521 <dt>[
<code>--if-exists
</code>]
<code>lr-lb-del
</code> <var>router
</var> [
<var>lb
</var>]
</dt>
523 Removes
<var>lb
</var> from
<var>router
</var>. If only
524 <var>router
</var> is supplied, all the LBs from the logical router are
525 removed. If
<var>lb
</var> is also specified, then only the
526 <var>lb
</var> will be removed from the logical router.
527 It is an error if
<var>lb
</var> does not exist in the
528 <var>router
</var>, unless
<code>--if-exists
</code> is specified.
531 <dt><code>lr-lb-list
</code> <var>router
</var></dt>
533 Lists the LBs for the given
<var>router
</var>.
538 <h1>DHCP Options commands
</h1>
541 <dt><code>dhcp-options-create
</code> <var>cidr
</var> [
<var>key=value
</var>]
</dt>
543 Creates a new DHCP Options entry in the
<code>DHCP_Options
</code> table
544 with the specified
<code>cidr
</code> and optional
<code>external-ids
</code>.
547 <dt><code>dhcp-options-list
</code></dt>
549 Lists the DHCP Options entries.
552 <dt><code>dhcp-options-del
</code> <var>dhcp-option
</var></dt>
554 Deletes the DHCP Options entry referred by
<var>dhcp-option
</var> UUID.
557 <dt><code>dhcp-options-set-options
</code> <var>dhcp-option
</var> [
<var>key=value
</var>]...
</dt>
559 Set the DHCP Options for the
<var>dhcp-option
</var> UUID.
562 <dt><code>dhcp-options-get-options
</code> <var>dhcp-option
</var></dt>
564 Lists the DHCP Options for the
<var>dhcp-option
</var> UUID.
568 <h1>Database Commands
</h1>
569 <p>These commands query and modify the contents of
<code>ovsdb
</code> tables.
570 They are a slight abstraction of the
<code>ovsdb
</code> interface and
571 as suchthey operate at a lower level than other
<code>ovn-nbctl
</code> commands.
</p>
572 <p><var>Identifying Tables, Records, and Columns
</var></p>
573 <p>Each of these commands has a
<var>table
</var> parameter to identify a table
574 within the database. Many of them also take a
<var>record
</var> parameter
575 that identifies a particular record within a table. The
<var>record
</var>
576 parameter may be the UUID for a record, and many tables offer
577 additional ways to identify records. Some commands also take
578 <var>column
</var> parameters that identify a particular field within the
579 records in a table.
</p>
580 <p>The following tables are currently defined:
</p>
582 <dt><code>Logical_Switch
</code></dt>
584 An L2 logical switch. Records may be identified by name.
587 <dt><code>Logical_Switch_Port
</code></dt>
589 A port within an L2 logical switch. Records may be identified by name.
592 <dt><code>ACL
</code></dt>
594 An ACL rule for a logical switch that points to it through its
<var>acls
</var> column.
597 <dt><code>Logical_Router
</code></dt>
599 An L3 logical router. Records may be identified by name.
602 <dt><code>Logical_Router_Port
</code></dt>
604 A port within an L3 logical router. Records may be identified by name.
607 <dt><code>Logical_Router_Static_Route
</code></dt>
609 A static route belonging to an L3 logical router.
612 <dt><code>Address_Set
</code></dt>
614 An address set that can be used in ACLs.
617 <dt><code>Load_Balancer
</code></dt>
619 A load balancer for a logical switch that points to it through its
<var>load_balancer
</var> column.
622 <dt><code>NAT
</code></dt>
624 A NAT rule for a Gateway router.
627 <dt><code>DHCP_Options
</code></dt>
632 <dt><code>NB_Global
</code></dt>
634 North bound global configurations.
639 <xi:include href=
"lib/db-ctl-base.xml" xmlns:
xi=
"http://www.w3.org/2003/XInclude"/>
641 <h1>Synchronization Commands
</h1>
646 Ordinarily,
<code>--wait=sb
</code> or
<code>--wait=hv
</code> only waits
647 for changes by the current
<code>ovn-nbctl
</code> invocation to take
648 effect. This means that, if none of the commands supplied to
649 <code>ovn-nbctl
</code> change the database, then the command does not
650 wait at all. With the
<code>sync
</code> command, however,
651 <code>ovn-nbctl
</code> waits even for earlier changes to the database
652 to propagate down to the southbound database or all of the OVN chassis,
653 according to the argument to
<code>--wait
</code>.
660 <dt><code>--no-wait
</code> |
<code>--wait=none
</code></dt>
661 <dt><code>--wait=sb
</code></dt>
662 <dt><code>--wait=hv
</code></dt>
666 These options control whether and how
<code>ovn-nbctl
</code> waits
667 for the OVN system to become up-to-date with changes made in an
668 <code>ovn-nbctl
</code> invocation.
672 By default, or if
<code>--no-wait
</code> or
<code>--wait=none
</code>,
673 <code>ovn-nbctl
</code> exits immediately after confirming that
674 changes have been committed to the northbound database, without
679 With
<code>--wait=sb
</code>, before
<code>ovn-nbctl
</code> exits, it
680 waits for
<code>ovn-northd
</code> to bring the southbound database
681 up-to-date with the northbound database updates.
685 With
<code>--wait=hv
</code>, before
<code>ovn-nbctl
</code> exits, it
686 additionally waits for all OVN chassis (hypervisors and gateways) to
687 become up-to-date with the northbound database updates. (This can
688 become an indefinite wait if any chassis is malfunctioning.)
692 Ordinarily,
<code>--wait=sb
</code> or
<code>--wait=hv
</code> only
693 waits for changes by the current
<code>ovn-nbctl
</code> invocation to
694 take effect. This means that, if none of the commands supplied to
695 <code>ovn-nbctl
</code> change the database, then the command does not
696 wait at all. Use the
<code>sync
</code> command to override this
701 <dt><code>--db
</code> <var>database
</var></dt>
703 The OVSDB database remote to contact. If the
<env>OVN_NB_DB
</env>
704 environment variable is set, its value is used as the default.
705 Otherwise, the default is
<code>unix:@RUNDIR@/db.sock
</code>, but this
706 default is unlikely to be useful outside of single-machine OVN test
711 <h1>Logging options
</h1>
712 <xi:include href=
"lib/vlog.xml" xmlns:
xi=
"http://www.w3.org/2003/XInclude"/>
715 PKI configuration is required to use SSL for the connection to the
718 <xi:include href=
"lib/ssl.xml" xmlns:
xi=
"http://www.w3.org/2003/XInclude"/>
720 <h2>Other Options
</h2>
722 <xi:include href=
"lib/common.xml" xmlns:
xi=
"http://www.w3.org/2003/XInclude"/>