1ovn-nbctl(8) Open vSwitch Manual ovn-nbctl(8)
2
6 ovn-nbctl - Open Virtual Network northbound db management utility
7
9 ovn-nbctl [options] command [arg...]
10
12 This utility can be used to manage the OVN northbound database.
13
15 init Initializes the database, if it is empty. If the database has
16 already been initialized, this command has no effect.
17 show [switch | router]
19 Prints a brief overview of the database contents. If switch is
20 provided, only records related to that logical switch are shown.
21 If router is provided, only records related to that logical
22 router are shown.
23
25 ls-add Creates a new, unnamed logical switch, which initially has no
26 ports. The switch does not have a name, other commands must
27 refer to this switch by its UUID.
28 [--may-exist | --add-duplicate] ls-add switch
30 Creates a new logical switch named switch, which initially has
31 no ports.
32 The OVN northbound database schema does not require logical
34 switch names to be unique, but the whole point to the names is
35 to provide an easy way for humans to refer to the switches, mak‐
36 ing duplicate names unhelpful. Thus, without any options, this
37 command regards it as an error if switch is a duplicate name.
38 With --may-exist, adding a duplicate name succeeds but does not
39 create a new logical switch. With --add-duplicate, the command
40 really creates a new logical switch with a duplicate name. It is
41 an error to specify both options. If there are multiple logical
42 switches with a duplicate name, configure the logical switches
43 using the UUID instead of the switch name.
44 [--if-exists] ls-del switch
46 Deletes switch. It is an error if switch does not exist, unless
47 --if-exists is specified.
48 ls-list
50 Lists all existing switches on standard output, one per line.
51
53 These commands operates on ACL objects for a given entity. The entity
54 can be either a logical switch or a port group. The entity can be spec‐
55 ified as uuid or name. The --type option can be used to specify the
56 type of the entity, in case both a logical switch and a port groups
57 exist with the same name specified for entity. type must be either
58 switch or port-group.
59 [--type={switch | port-group}] [--log] [--meter=meter] [--sever‐
61 ity=severity] [--name=name] [--may-exist] acl-add entity direc‐
62 tion priority match verdict
63 Adds the specified ACL to entity. direction must be
64 either from-lport or to-lport. priority must be between 0
65 and 32767, inclusive. A full description of the fields
66 are in ovn-nb(5). If --may-exist is specified, adding a
67 duplicated ACL succeeds but the ACL is not really cre‐
68 ated. Without --may-exist, adding a duplicated ACL
69 results in error.
70 The --log option enables packet logging for the ACL. The
72 options --severity and --name specify a severity and
73 name, respectively, for log entries (and also enable log‐
74 ging). The severity must be one of alert, warning,
75 notice, info, or debug. If a severity is not specified,
76 the default is info. The --meter=meter option is used to
77 rate-limit packet logging. The meter argument names a
78 meter configured by meter-add.
79 [--type={switch | port-group}] acl-del entity [direction [prior‐
81 ity match]]
82 Deletes ACLs from entity. If only entity is supplied, all
83 the ACLs from the entity are deleted. If direction is
84 also specified, then all the flows in that direction will
85 be deleted from the entity. If all the fields are given,
86 then a single flow that matches all the fields will be
87 deleted.
88 [--type={switch | port-group}] acl-list entity
90 Lists the ACLs on entity.
91
93 [--may-exist] qos-add switch direction priority match [dscp=dscp]
94 [rate=rate [burst=burst]]
95 Adds QoS marking and metering rules to switch. direction must be
96 either from-lport or to-lport. priority must be between 0 and
97 32767, inclusive.
98 If dscp=dscp is specified, then matching packets will have DSCP
100 marking applied. dscp must be between 0 and 63, inclusive. If
101 rate=rate is specified then matching packets will have metering
102 applied at rate kbps. If metering is configured, then
103 burst=burst specifies the burst rate limit in kilobits. dscp
104 and/or rate are required arguments.
105 If --may-exist is specified, adding a duplicated QoS rule suc‐
107 ceeds but the QoS rule is not really created. Without
108 --may-exist, adding a duplicated QoS rule results in error.
109 qos-del switch [direction [priority match]]
111 Deletes QoS rules from switch. If only switch is supplied, all
112 the QoS rules from the logical switch are deleted. If direction
113 is also specified, then all the flows in that direction will be
114 deleted from the logical switch. If all the fields are supplied,
115 then a single flow that matches the given fields will be
116 deleted.
117 qos-list switch
119 Lists the QoS rules on switch.
120
122 meter-add name action rate unit [burst]
123 Adds the specified meter. name must be a unique name to identify
124 this meter. The action argument specifies what should happen
125 when this meter is exceeded. The only supported action is drop.
126 The unit specifies the unit for the rate argument; valid values
128 are kbps and pktps for kilobits per second and packets per sec‐
129 ond, respectively. The burst option configures the maximum burst
130 allowed for the band in kilobits or packets depending on whether
131 the unit chosen was kbps or pktps, respectively. If a burst is
132 not supplied, the switch is free to select some reasonable value
133 depending on its configuration.
134 ovn-nbctl only supports adding a meter with a single band, but
136 the other commands support meters with multiple bands.
137 Names that start with "__" (two underscores) are reserved for
139 internal use by OVN, so ovn-nbctl does not allow adding them.
140 meter-del [name]
142 Deletes meters. By default, all meters are deleted. If name is
143 supplied, only the meter with that name will be deleted.
144 meter-list
146 Lists all meters.
147
149 [--may-exist] lsp-add switch port
150 Creates on lswitch a new logical switch port named port.
151 It is an error if a logical port named port already exists,
153 unless --may-exist is specified. Regardless of --may-exist, it
154 is an error if the existing port is in some logical switch other
155 than switch or if it has a parent port.
156 [--may-exist] lsp-add switch port parent tag_request
158 Creates on switch a logical switch port named port that is a
159 child of parent that is identified with VLAN ID tag_request,
160 which must be between 0 and 4095, inclusive. If tag_request is
161 0, ovn-northd generates a tag that is unique in the scope of
162 parent. This is useful in cases such as virtualized container
163 environments where Open vSwitch does not have a direct connec‐
164 tion to the container’s port and it must be shared with the vir‐
165 tual machine’s port.
166 It is an error if a logical port named port already exists,
168 unless --may-exist is specified. Regardless of --may-exist, it
169 is an error if the existing port is not in switch or if it does
170 not have the specified parent and tag_request.
171 [--if-exists] lsp-del port
173 Deletes port. It is an error if port does not exist, unless
174 --if-exists is specified.
175 lsp-list switch
177 Lists all the logical switch ports within switch on standard
178 output, one per line.
179 lsp-get-parent port
181 If set, get the parent port of port. If not set, print nothing.
182 lsp-get-tag port
184 If set, get the tag for port traffic. If not set, print nothing.
185 lsp-set-addresses port [address]...
187 Sets the addresses associated with port to address. Each address
188 should be one of the following:
189 an Ethernet address, optionally followed by a space and one or
191 more IP addresses
192 OVN delivers packets for the Ethernet address to this
193 port.
194 unknown
196 OVN delivers unicast Ethernet packets whose destination
197 MAC address is not in any logical port’s addresses column
198 to ports with address unknown.
199 dynamic
201 Use this keyword to make ovn-northd generate a globally
202 unique MAC address and choose an unused IPv4 address with
203 the logical port’s subnet and store them in the port’s
204 dynamic_addresses column.
205 router Accepted only when the type of the logical switch port is
207 router. This indicates that the Ethernet, IPv4, and IPv6
208 addresses for this logical switch port should be obtained
209 from the connected logical router port, as specified by
210 router-port in lsp-set-options.
211 Multiple addresses may be set. If no address argument is given,
213 port will have no addresses associated with it.
214 lsp-get-addresses port
216 Lists all the addresses associated with port on standard output,
217 one per line.
218 lsp-set-port-security port [addrs]...
220 Sets the port security addresses associated with port to addrs.
221 Multiple sets of addresses may be set by using multiple addrs
222 arguments. If no addrs argument is given, port will not have
223 port security enabled.
224 Port security limits the addresses from which a logical port may
226 send packets and to which it may receive packets. See the
227 ovn-nb(5) documentation for the port_security column in the Log‐
228 ical_Switch_Port table for details.
229 lsp-get-port-security port
231 Lists all the port security addresses associated with port on
232 standard output, one per line.
233 lsp-get-up port
235 Prints the state of port, either up or down.
236 lsp-set-enabled port state
238 Set the administrative state of port, either enabled or dis‐
239 abled. When a port is disabled, no traffic is allowed into or
240 out of the port.
241 lsp-get-enabled port
243 Prints the administrative state of port, either enabled or dis‐
244 abled.
245 lsp-set-type port type
247 Set the type for the logical port. The type must be one of the
248 following:
249 (empty string)
251 A VM (or VIF) interface.
252 router A connection to a logical router.
254 localnet
256 A connection to a locally accessible network from each
257 ovn-controller instance. A logical switch can only have a
258 single localnet port attached. This is used to model
259 direct connectivity to an existing network.
260 localport
262 A connection to a local VIF. Traffic that arrives on a
263 localport is never forwarded over a tunnel to another
264 chassis. These ports are present on every chassis and
265 have the same address in all of them. This is used to
266 model connectivity to local services that run on every
267 hypervisor.
268 l2gateway
270 A connection to a physical network.
271 vtep A port to a logical switch on a VTEP gateway.
273 lsp-get-type port
275 Get the type for the logical port.
276 lsp-set-options port [key=value]...
278 Set type-specific key-value options for the logical port.
279 lsp-get-options port
281 Get the type-specific options for the logical port.
282 lsp-set-dhcpv4-options port dhcp_options
284 Set the DHCPv4 options for the logical port. The dhcp_options is
285 a UUID referring to a set of DHCP options in the DHCP_Options
286 table.
287 lsp-get-dhcpv4-optoins port
289 Get the configured DHCPv4 options for the logical port.
290 lsp-set-dhcpv6-options port dhcp_options
292 Set the DHCPv6 options for the logical port. The dhcp_options is
293 a UUID referring to a set of DHCP options in the DHCP_Options
294 table.
295 lsp-get-dhcpv6-optoins port
297 Get the configured DHCPv6 options for the logical port.
298 lsp-get-ls port
300 Get the logical switch which the port belongs to.
301
303 lr-add Creates a new, unnamed logical router, which initially has no
304 ports. The router does not have a name, other commands must
305 refer to this router by its UUID.
306 [--may-exist | --add-duplicate] lr-add router
308 Creates a new logical router named router, which initially has
309 no ports.
310 The OVN northbound database schema does not require logical
312 router names to be unique, but the whole point to the names is
313 to provide an easy way for humans to refer to the routers, mak‐
314 ing duplicate names unhelpful. Thus, without any options, this
315 command regards it as an error if router is a duplicate name.
316 With --may-exist, adding a duplicate name succeeds but does not
317 create a new logical router. With --add-duplicate, the command
318 really creates a new logical router with a duplicate name. It is
319 an error to specify both options. If there are multiple logical
320 routers with a duplicate name, configure the logical routers
321 using the UUID instead of the router name.
322 [--if-exists] lr-del router
324 Deletes router. It is an error if router does not exist, unless
325 --if-exists is specified.
326 lr-list
328 Lists all existing routers on standard output, one per line.
329
331 [--may-exist] lrp-add router port mac network... [peer=peer]
332 Creates on router a new logical router port named port with Eth‐
333 ernet address mac and one or more IP address/netmask for each
334 network.
335 The optional argument peer identifies a logical router port that
337 connects to this one. The following example adds a router port
338 with an IPv4 and IPv6 address with peer lr1:
339 lrp-add lr0 lrp0 00:11:22:33:44:55 192.168.0.1/24 2001:db8::1/64
341 peer=lr1
342 It is an error if a logical router port named port already
344 exists, unless --may-exist is specified. Regardless of
345 --may-exist, it is an error if the existing router port is in
346 some logical router other than router.
347 [--if-exists] lrp-del port
349 Deletes port. It is an error if port does not exist, unless
350 --if-exists is specified.
351 lrp-list router
353 Lists all the logical router ports within router on standard
354 output, one per line.
355 lrp-set-enabled port state
357 Set the administrative state of port, either enabled or dis‐
358 abled. When a port is disabled, no traffic is allowed into or
359 out of the port.
360 lrp-get-enabled port
362 Prints the administrative state of port, either enabled or dis‐
363 abled.
364 lrp-set-gateway-chassis port chassis [priority]
366 Set gateway chassis for port. chassis is the name of the chas‐
367 sis. This creates a gateway chassis entry in Gateway_Chassis ta‐
368 ble. It won’t check if chassis really exists in OVN_Southbound
369 database. Priority will be set to 0 if priority is not provided
370 by user. priority must be between 0 and 32767, inclusive.
371 lrp-del-gateway-chassis port chassis
373 Deletes gateway chassis from port. It is an error if gateway
374 chassis with chassis for port does not exist.
375 lrp-get-gateway-chassis port
377 Lists all the gateway chassis with priority within port on stan‐
378 dard output, one per line, ordered based on priority.
379
381 [--may-exist] [--policy=POLICY] lr-route-add router prefix nexthop
382 [port]
383 Adds the specified route to router. prefix describes an IPv4 or
384 IPv6 prefix for this route, such as 192.168.100.0/24. nexthop
385 specifies the gateway to use for this route, which should be the
386 IP address of one of router logical router ports or the IP
387 address of a logical port. If port is specified, packets that
388 match this route will be sent out that port. When port is omit‐
389 ted, OVN infers the output port based on nexthop.
390 --policy describes the policy used to make routing decisions.
392 This should be one of "dst-ip" or "src-ip". If not specified,
393 the default is "dst-ip".
394 It is an error if a route with prefix already exists, unless
396 --may-exist is specified.
397 [--if-exists] lr-route-del router [prefix]
399 Deletes routes from router. If only router is supplied, all the
400 routes from the logical router are deleted. If prefix is also
401 specified, then all the routes that match the prefix will be
402 deleted from the logical router.
403 It is an error if prefix is specified and there is no matching
405 route entry, unless --if-exists is specified.
406 lr-route-list router
408 Lists the routes on router.
409
411 [--may-exist] lr-nat-add router type external_ip logical_ip [logi‐
412 cal_port external_mac]
413 Adds the specified NAT to router. The type must be one of snat,
414 dnat, or dnat_and_snat. The external_ip is an IPv4 address. The
415 logical_ip is an IPv4 network (e.g 192.168.1.0/24) or an IPv4
416 address. The logical_port and external_mac are only accepted
417 when router is a distributed router (rather than a gateway
418 router) and type is dnat_and_snat. The logical_port is the name
419 of an existing logical switch port where the logical_ip resides.
420 The external_mac is an Ethernet address.
421 When type is dnat, the externally visible IP address external_ip
423 is DNATted to the IP address logical_ip in the logical space.
424 When type is snat, IP packets with their source IP address that
426 either matches the IP address in logical_ip or is in the network
427 provided by logical_ip is SNATed into the IP address in exter‐
428 nal_ip.
429 When type is dnat_and_snat, the externally visible IP address
431 external_ip is DNATted to the IP address logical_ip in the logi‐
432 cal space. In addition, IP packets with the source IP address
433 that matches logical_ip is SNATed into the IP address in exter‐
434 nal_ip.
435 When the logical_port and external_mac are specified, the NAT
437 rule will be programmed on the chassis where the logical_port
438 resides. This includes ARP replies for the external_ip, which
439 return the value of external_mac. All packets transmitted with
440 source IP address equal to external_ip will be sent using the
441 external_mac.
442 It is an error if a NAT already exists with the same values of
444 router, type, external_ip, and logical_ip, unless --may-exist is
445 specified. When --may-exist, logical_port, and external_mac are
446 all specified, the existing values of logical_port and exter‐
447 nal_mac are overwritten.
448 [--if-exists] lr-nat-del router [type [ip]]
450 Deletes NATs from router. If only router is supplied, all the
451 NATs from the logical router are deleted. If type is also speci‐
452 fied, then all the NATs that match the type will be deleted from
453 the logical router. If all the fields are given, then a single
454 NAT rule that matches all the fields will be deleted. When type
455 is snat, the ip should be logical_ip. When type is dnat or
456 dnat_and_snat, the ip shoud be external_ip.
457 It is an error if ip is specified and there is no matching NAT
459 entry, unless --if-exists is specified.
460 lr-nat-list router
462 Lists the NATs on router.
463
465 [--may-exist | --add-duplicate] lb-add lb vip ips [protocol]
466 Creates a new load balancer named lb with the provided vip and
467 ips or adds the vip to an existing lb. vip should be a virtual
468 IP address (or an IP address and a port number with : as a sepa‐
469 rator). Examples for vip are 192.168.1.4, fd0f::1, and
470 192.168.1.5:8080. ips should be comma separated IP endpoints (or
471 comma separated IP addresses and port numbers with : as a sepa‐
472 rator). ips must be the same address family as vip. Examples for
473 ips are 10.0.0.1,10.0.0.2or [fdef::1]:8800,[fdef::2]:8800.
474 The optional argument protocol must be either tcp or udp. This
476 argument is useful when a port number is provided as part of the
477 vip. If the protocol is unspecified and a port number is pro‐
478 vided as part of the vip, OVN assumes the protocol to be tcp.
479 It is an error if the vip already exists in the load balancer
481 named lb, unless --may-exist is specified. With --add-duplicate,
482 the command really creates a new load balancer with a duplicate
483 name.
484 The following example adds a load balancer.
486 lb-add lb0 30.0.0.10:80
488 192.168.10.10:80,192.168.10.20:80,192.168.10.30:80 udp
489 [--if-exists] lb-del lb [vip]
491 Deletes lb or the vip from lb. If vip is supplied, only the vip
492 will be deleted from the lb. If only the lb is supplied, the lb
493 will be deleted. It is an error if vip does not already exist in
494 lb, unless --if-exists is specified.
495 lb-list [lb]
497 Lists the LBs. If lb is also specified, then only the specified
498 lb will be listed.
499 [--may-exist] ls-lb-add switch lb
501 Adds the specified lb to switch. It is an error if a load bal‐
502 ancer named lb already exists in the switch, unless --may-exist
503 is specified.
504 [--if-exists] ls-lb-del switch [lb]
506 Removes lb from switch. If only switch is supplied, all the LBs
507 from the logical switch are removed. If lb is also specified,
508 then only the lb will be removed from the logical switch. It is
509 an error if lb does not exist in the switch, unless --if-exists
510 is specified.
511 ls-lb-list switch
513 Lists the LBs for the given switch.
514 [--may-exist] lr-lb-add router lb
516 Adds the specified lb to router. It is an error if a load bal‐
517 ancer named lb already exists in the router, unless --may-exist
518 is specified.
519 [--if-exists] lr-lb-del router [lb]
521 Removes lb from router. If only router is supplied, all the LBs
522 from the logical router are removed. If lb is also specified,
523 then only the lb will be removed from the logical router. It is
524 an error if lb does not exist in the router, unless --if-exists
525 is specified.
526 lr-lb-list router
528 Lists the LBs for the given router.
529
531 dhcp-options-create cidr [key=value]
532 Creates a new DHCP Options entry in the DHCP_Options table with
533 the specified cidr and optional external-ids.
534 dhcp-options-list
536 Lists the DHCP Options entries.
537 dhcp-options-del dhcp-option
539 Deletes the DHCP Options entry referred by dhcp-option UUID.
540 dhcp-options-set-options dhcp-option [key=value]...
542 Set the DHCP Options for the dhcp-option UUID.
543 dhcp-options-get-options dhcp-option
545 Lists the DHCP Options for the dhcp-option UUID.
546
548 pg-add group [port]...
549 Creates a new port group in the Port_Group table named group
550 with optional ports added to the group.
551 pg-set-ports group port...
553 Sets ports on the port group named group. It is an error if
554 group does not exist.
555 pg-del group
557 Deletes port group group. It is an error if group does not
558 exist.
559 HA CHASSIS GROUP COMMANDS
561 ha-chassis-group-add group
562 Creates a new HA chassis group in the HA_Chassis_Group table
563 named group.
564 ha-chassis-group-del group
566 Deletes the HA chassis group group. It is an error if group does
567 not exist.
568 ha-chassis-group-list
570 Lists the HA chassis group group along with the HA chassis if
571 any associated with it.
572 ha-chassis-group-add-chassis group chassis priority
574 Adds a new HA chassis chassis to the HA Chassis group group with
575 the specified priority. If the chassis already exists, then the
576 priority is updated. The chassis should be the name of the chas‐
577 sis in the OVN_Southbound.
578 ha-chassis-group-remove-chassis group chassis
580 Removes the HA chassis chassis from the HA chassis group group.
581 It is an error if chassis does not exist.
582
584 These commands query and modify the contents of ovsdb tables. They are
585 a slight abstraction of the ovsdb interface and as such they operate at
586 a lower level than other ovn-nbctl commands.
587 Identifying Tables, Records, and Columns
589 Each of these commands has a table parameter to identify a table within
591 the database. Many of them also take a record parameter that identifies
592 a particular record within a table. The record parameter may be the
593 UUID for a record, which may be abbreviated to its first 4 (or more)
594 hex digits, as long as that is unique. Many tables offer additional
595 ways to identify records. Some commands also take column parameters
596 that identify a particular field within the records in a table.
597 For a list of tables and their columns, see ovn-nb(5) or see the table
599 listing from the --help option.
600 Record names must be specified in full and with correct capitalization,
602 except that UUIDs may be abbreviated to their first 4 (or more) hex
603 digits, as long as that is unique within the table. Names of tables and
604 columns are not case-sensitive, and - and _ are treated interchange‐
605 ably. Unique abbreviations of table and column names are acceptable,
606 e.g. d or dhcp is sufficient to identify the DHCP_Options table.
607 Database Values
609 Each column in the database accepts a fixed type of data. The currently
611 defined basic types, and their representations, are:
612 integer
614 A decimal integer in the range -2**63 to 2**63-1, inclu‐
615 sive.
616 real A floating-point number.
618 Boolean
620 True or false, written true or false, respectively.
621 string An arbitrary Unicode string, except that null bytes are
623 not allowed. Quotes are optional for most strings that
624 begin with an English letter or underscore and consist
625 only of letters, underscores, hyphens, and periods. How‐
626 ever, true and false and strings that match the syntax of
627 UUIDs (see below) must be enclosed in double quotes to
628 distinguish them from other basic types. When double
629 quotes are used, the syntax is that of strings in JSON,
630 e.g. backslashes may be used to escape special charac‐
631 ters. The empty string must be represented as a pair of
632 double quotes ("").
633 UUID Either a universally unique identifier in the style of
635 RFC 4122, e.g. f81d4fae-7dec-11d0-a765-00a0c91e6bf6, or
636 an @name defined by a get or create command within the
637 same ovn-nbctl invocation.
638 Multiple values in a single column may be separated by spaces or a sin‐
640 gle comma. When multiple values are present, duplicates are not
641 allowed, and order is not important. Conversely, some database columns
642 can have an empty set of values, represented as [], and square brackets
643 may optionally enclose other non-empty sets or single values as well.
644 A few database columns are ``maps’’ of key-value pairs, where the key
646 and the value are each some fixed database type. These are specified in
647 the form key=value, where key and value follow the syntax for the col‐
648 umn’s key type and value type, respectively. When multiple pairs are
649 present (separated by spaces or a comma), duplicate keys are not
650 allowed, and again the order is not important. Duplicate values are
651 allowed. An empty map is represented as {}. Curly braces may optionally
652 enclose non-empty maps as well (but use quotes to prevent the shell
653 from expanding other-config={0=x,1=y} into other-config=0=x other-con‐
654 fig=1=y, which may not have the desired effect).
655 Database Command Syntax
657 [--if-exists] [--columns=column[,column]...] list table
659 [record]...
660 Lists the data in each specified record. If no records
661 are specified, lists all the records in table.
662 If --columns is specified, only the requested columns are
664 listed, in the specified order. Otherwise, all columns
665 are listed, in alphabetical order by column name.
666 Without --if-exists, it is an error if any specified
668 record does not exist. With --if-exists, the command
669 ignores any record that does not exist, without producing
670 any output.
671 [--columns=column[,column]...] find table [col‐
673 umn[:key]=value]...
674 Lists the data in each record in table whose column
675 equals value or, if key is specified, whose column con‐
676 tains a key with the specified value. The following oper‐
677 ators may be used where = is written in the syntax sum‐
678 mary:
679 = != < > <= >=
681 Selects records in which column[:key] equals, does
682 not equal, is less than, is greater than, is less
683 than or equal to, or is greater than or equal to
684 value, respectively.
685 Consider column[:key] and value as sets of ele‐
687 ments. Identical sets are considered equal. Other‐
688 wise, if the sets have different numbers of ele‐
689 ments, then the set with more elements is consid‐
690 ered to be larger. Otherwise, consider a element
691 from each set pairwise, in increasing order within
692 each set. The first pair that differs determines
693 the result. (For a column that contains key-value
694 pairs, first all the keys are compared, and values
695 are considered only if the two sets contain iden‐
696 tical keys.)
697 {=} {!=}
699 Test for set equality or inequality, respectively.
700 {<=} Selects records in which column[:key] is a subset
702 of value. For example, flood-vlans{<=}1,2 selects
703 records in which the flood-vlans column is the
704 empty set or contains 1 or 2 or both.
705 {<} Selects records in which column[:key] is a proper
707 subset of value. For example, flood-vlans{<}1,2
708 selects records in which the flood-vlans column is
709 the empty set or contains 1 or 2 but not both.
710 {>=} {>}
712 Same as {<=} and {<}, respectively, except that
713 the relationship is reversed. For example,
714 flood-vlans{>=}1,2 selects records in which the
715 flood-vlans column contains both 1 and 2.
716 For arithmetic operators (= != < > <= >=), when key is
718 specified but a particular record’s column does not con‐
719 tain key, the record is always omitted from the results.
720 Thus, the condition other-config:mtu!=1500 matches
721 records that have a mtu key whose value is not 1500, but
722 not those that lack an mtu key.
723 For the set operators, when key is specified but a par‐
725 ticular record’s column does not contain key, the compar‐
726 ison is done against an empty set. Thus, the condition
727 other-config:mtu{!=}1500 matches records that have a mtu
728 key whose value is not 1500 and those that lack an mtu
729 key.
730 Don’t forget to escape < or > from interpretation by the
732 shell.
733 If --columns is specified, only the requested columns are
735 listed, in the specified order. Otherwise all columns are
736 listed, in alphabetical order by column name.
737 The UUIDs shown for rows created in the same ovn-nbctl
739 invocation will be wrong.
740 [--if-exists] [--id=@name] get table record [column[:key]]...
742 Prints the value of each specified column in the given
743 record in table. For map columns, a key may optionally be
744 specified, in which case the value associated with key in
745 the column is printed, instead of the entire map.
746 Without --if-exists, it is an error if record does not
748 exist or key is specified, if key does not exist in
749 record. With --if-exists, a missing record yields no out‐
750 put and a missing key prints a blank line.
751 If @name is specified, then the UUID for record may be
753 referred to by that name later in the same ovn-nbctl
754 invocation in contexts where a UUID is expected.
755 Both --id and the column arguments are optional, but usu‐
757 ally at least one or the other should be specified. If
758 both are omitted, then get has no effect except to verify
759 that record exists in table.
760 --id and --if-exists cannot be used together.
762 [--if-exists] set table record column[:key]=value...
764 Sets the value of each specified column in the given
765 record in table to value. For map columns, a key may
766 optionally be specified, in which case the value associ‐
767 ated with key in that column is changed (or added, if
768 none exists), instead of the entire map.
769 Without --if-exists, it is an error if record does not
771 exist. With --if-exists, this command does nothing if
772 record does not exist.
773 [--if-exists] add table record column [key=]value...
775 Adds the specified value or key-value pair to column in
776 record in table. If column is a map, then key is
777 required, otherwise it is prohibited. If key already
778 exists in a map column, then the current value is not
779 replaced (use the set command to replace an existing
780 value).
781 Without --if-exists, it is an error if record does not
783 exist. With --if-exists, this command does nothing if
784 record does not exist.
785 [--if-exists] remove table record column value...
787 [--if-exists] remove table record column key...
789 [--if-exists] remove table record column key=value...
791 Removes the specified values or key-value pairs from col‐
792 umn in record in table. The first form applies to columns
793 that are not maps: each specified value is removed from
794 the column. The second and third forms apply to map col‐
795 umns: if only a key is specified, then any key-value pair
796 with the given key is removed, regardless of its value;
797 if a value is given then a pair is removed only if both
798 key and value match.
799 It is not an error if the column does not contain the
801 specified key or value or pair.
802 Without --if-exists, it is an error if record does not
804 exist. With --if-exists, this command does nothing if
805 record does not exist.
806 [--if-exists] clear table record column...
808 Sets each column in record in table to the empty set or
809 empty map, as appropriate. This command applies only to
810 columns that are allowed to be empty.
811 Without --if-exists, it is an error if record does not
813 exist. With --if-exists, this command does nothing if
814 record does not exist.
815 [--id=@name] create table column[:key]=value...
817 Creates a new record in table and sets the initial values
818 of each column. Columns not explicitly set will receive
819 their default values. Outputs the UUID of the new row.
820 If @name is specified, then the UUID for the new row may
822 be referred to by that name elsewhere in the same \*(PN
823 invocation in contexts where a UUID is expected. Such
824 references may precede or follow the create command.
825 Caution (ovs-vsctl as example)
827 Records in the Open vSwitch database are signifi‐
828 cant only when they can be reached directly or
829 indirectly from the Open_vSwitch table. Except for
830 records in the QoS or Queue tables, records that
831 are not reachable from the Open_vSwitch table are
832 automatically deleted from the database. This
833 deletion happens immediately, without waiting for
834 additional ovs-vsctl commands or other database
835 activity. Thus, a create command must generally be
836 accompanied by additional commands within the same
837 ovs-vsctl invocation to add a chain of references
838 to the newly created record from the top-level
839 Open_vSwitch record. The EXAMPLES section gives
840 some examples that show how to do this.
841 [--if-exists] destroy table record...
843 Deletes each specified record from table. Unless
844 --if-exists is specified, each records must exist.
845 --all destroy table
847 Deletes all records from the table.
848 Caution (ovs-vsctl as example)
850 The destroy command is only useful for records in
851 the QoS or Queue tables. Records in other tables
852 are automatically deleted from the database when
853 they become unreachable from the Open_vSwitch ta‐
854 ble. This means that deleting the last reference
855 to a record is sufficient for deleting the record
856 itself. For records in these tables, destroy is
857 silently ignored. See the EXAMPLES section below
858 for more information.
859 wait-until table record [column[:key]=value]...
861 Waits until table contains a record named record whose
862 column equals value or, if key is specified, whose column
863 contains a key with the specified value. Any of the oper‐
864 ators !=, <, >, <=, or >= may be substituted for = to
865 test for inequality, less than, greater than, less than
866 or equal to, or greater than or equal to, respectively.
867 (Don’t forget to escape < or > from interpretation by the
868 shell.)
869 If no column[:key]=value arguments are given, this com‐
871 mand waits only until record exists. If more than one
872 such argument is given, the command waits until all of
873 them are satisfied.
874 Caution (ovs-vsctl as example)
876 Usually wait-until should be placed at the begin‐
877 ning of a set of ovs-vsctl commands. For example,
878 wait-until bridge br0 -- get bridge br0 data‐
879 path_id waits until a bridge named br0 is created,
880 then prints its datapath_id column, whereas get
881 bridge br0 datapath_id -- wait-until bridge br0
882 will abort if no bridge named br0 exists when
883 ovs-vsctl initially connects to the database.
884 Consider specifying --timeout=0 along with --wait-until,
886 to prevent ovn-nbctl from terminating after waiting only
887 at most 5 seconds.
888 comment [arg]...
890 This command has no effect on behavior, but any database
891 log record created by the command will include the com‐
892 mand and its arguments.
893
895 sync Ordinarily, --wait=sb or --wait=hv only waits for changes by the
896 current ovn-nbctl invocation to take effect. This means that, if
897 none of the commands supplied to ovn-nbctl change the database,
898 then the command does not wait at all. With the sync command,
899 however, ovn-nbctl waits even for earlier changes to the data‐
900 base to propagate down to the southbound database or all of the
901 OVN chassis, according to the argument to --wait.
902
904 get-connection
905 Prints the configured connection(s).
906 del-connection
908 Deletes the configured connection(s).
909 [--inactivity-probe=msecs] set-connection target...
911 Sets the configured manager target or targets. Use --inactiv‐
912 ity-probe=msecs to override the default idle connection inactiv‐
913 ity probe time. Use 0 to disable inactivity probes.
914
916 get-ssl
917 Prints the SSL configuration.
918 del-ssl
920 Deletes the current SSL configuration.
921 [--bootstrap] set-ssl private-key certificate ca-cert [ssl-protocol-
923 list [ssl-cipher-list]]
924 Sets the SSL configuration.
925
927 When it is invoked in the most ordinary way, ovn-nbctl connects to an
928 OVSDB server that hosts the northbound database, retrieves a partial
929 copy of the database that is complete enough to do its work, sends a
930 transaction request to the server, and receives and processes the
931 server’s reply. In common interactive use, this is fine, but if the
932 database is large, the step in which ovn-nbctl retrieves a partial copy
933 of the database can take a long time, which yields poor performance
934 overall.
935 To improve performance in such a case, ovn-nbctl offers a "daemon
937 mode," in which the user first starts ovn-nbctl running in the back‐
938 ground and afterward uses the daemon to execute operations. Over sev‐
939 eral ovn-nbctl command invocations, this performs better overall
940 because it retrieves a copy of the database only once at the beginning,
941 not once per program run.
942 Use the --detach option to start an ovn-nbctl daemon. With this option,
944 ovn-nbctl prints the name of a control socket to stdout. The client
945 should save this name in environment variable OVN_NB_DAEMON. Under the
946 Bourne shell this might be done like this:
947 export OVN_NB_DAEMON=$(ovn-nbctl --pidfile --detach)
949 When OVN_NB_DAEMON is set, ovn-nbctl automatically and transparently
952 uses the daemon to execute its commands.
953 When the daemon is no longer needed, kill it and unset the environment
955 variable, e.g.:
956 kill $(cat /var/run/ovn-nbctl.pid)
958 unset OVN_NB_DAEMON
959 Daemon mode is experimental.
962 Daemon Commands
964 Daemon mode is internally implemented using the same mechanism used by
965 ovs-appctl. One may also use ovs-appctl directly with the following
966 commands:
967 run [options] command [arg...] [-- [options] command [arg...]
969 ...]
970 Instructs the daemon process to run one or more ovn-nbctl
971 commands described above and reply with the results of
972 running these commands. Accepts the --no-wait, --wait,
973 --timeout, --dry-run, --oneline, and the options
974 described under Table Formatting Options in addition to
975 the the command-specific options.
976 exit Causes ovn-nbctl to gracefully terminate.
978
980 --no-wait | --wait=none
981 --wait=sb
982 --wait=hv
983 These options control whether and how ovn-nbctl waits for the OVN
984 system to become up-to-date with changes made in an ovn-nbctl
985 invocation.
986 By default, or if --no-wait or --wait=none, ovn-nbctl exits imme‐
988 diately after confirming that changes have been committed to the
989 northbound database, without waiting.
990 With --wait=sb, before ovn-nbctl exits, it waits for ovn-northd to
992 bring the southbound database up-to-date with the northbound data‐
993 base updates.
994 With --wait=hv, before ovn-nbctl exits, it additionally waits for
996 all OVN chassis (hypervisors and gateways) to become up-to-date
997 with the northbound database updates. (This can become an indefi‐
998 nite wait if any chassis is malfunctioning.)
999 Ordinarily, --wait=sb or --wait=hv only waits for changes by the
1001 current ovn-nbctl invocation to take effect. This means that, if
1002 none of the commands supplied to ovn-nbctl change the database,
1003 then the command does not wait at all. Use the sync command to
1004 override this behavior.
1005 --db database
1007 The OVSDB database remote to contact. If the OVN_NB_DB environment
1008 variable is set, its value is used as the default. Otherwise, the
1009 default is unix:/var/run/openvswitch/ovnnb_db.sock, but this
1010 default is unlikely to be useful outside of single-machine OVN
1011 test environments.
1012 --leader-only
1014 --no-leader-only
1015 By default, or with --leader-only, when the database server is a
1016 clustered database, ovn-nbctl will avoid servers other than the
1017 cluster leader. This ensures that any data that ovn-nbctl reads
1018 and reports is up-to-date. With --no-leader-only, ovn-nbctl will
1019 use any server in the cluster, which means that for read-only
1020 transactions it can report and act on stale data (transactions
1021 that modify the database are always serialized even with
1022 --no-leader-only). Refer to Understanding Cluster Consistency in
1023 ovsdb(7) for more information.
1024 --shuffle-remotes
1026 --no-shuffle-remotes
1027 By default, or with --shuffle-remotes, when there are multiple
1028 remotes specified in the OVSDB connection string specified by --db
1029 or the OVN_NB_DB environment variable, the order of the remotes
1030 will be shuffled before the client tries to connect. The remotes
1031 will be shuffled only once to a new order before the first connec‐
1032 tion attempt. The following retries, if any, will follow the same
1033 new order. The default behavior is to make sure clients of a clus‐
1034 tered database can distribute evenly to all memembers of the clus‐
1035 ter. With --no-shuffle-remotes, ovn-nbctl will use the original
1036 order specified in the connection string to connect. This allows
1037 user to specify the preferred order, which is particularly useful
1038 for testing.
1039 Daemon Options
1041 --pidfile[=pidfile]
1042 Causes a file (by default, program.pid) to be created indicating
1043 the PID of the running process. If the pidfile argument is not
1044 specified, or if it does not begin with /, then it is created in
1045 /var/run/openvswitch.
1046 If --pidfile is not specified, no pidfile is created.
1048 --overwrite-pidfile
1050 By default, when --pidfile is specified and the specified pid‐
1051 file already exists and is locked by a running process, the dae‐
1052 mon refuses to start. Specify --overwrite-pidfile to cause it to
1053 instead overwrite the pidfile.
1054 When --pidfile is not specified, this option has no effect.
1056 --detach
1058 Runs this program as a background process. The process forks,
1059 and in the child it starts a new session, closes the standard
1060 file descriptors (which has the side effect of disabling logging
1061 to the console), and changes its current directory to the root
1062 (unless --no-chdir is specified). After the child completes its
1063 initialization, the parent exits.
1064 --monitor
1066 Creates an additional process to monitor this program. If it
1067 dies due to a signal that indicates a programming error (SIGA‐
1068 BRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE, SIGSEGV, SIGXCPU,
1069 or SIGXFSZ) then the monitor process starts a new copy of it. If
1070 the daemon dies or exits for another reason, the monitor process
1071 exits.
1072 This option is normally used with --detach, but it also func‐
1074 tions without it.
1075 --no-chdir
1077 By default, when --detach is specified, the daemon changes its
1078 current working directory to the root directory after it
1079 detaches. Otherwise, invoking the daemon from a carelessly cho‐
1080 sen directory would prevent the administrator from unmounting
1081 the file system that holds that directory.
1082 Specifying --no-chdir suppresses this behavior, preventing the
1084 daemon from changing its current working directory. This may be
1085 useful for collecting core files, since it is common behavior to
1086 write core dumps into the current working directory and the root
1087 directory is not a good directory to use.
1088 This option has no effect when --detach is not specified.
1090 --no-self-confinement
1092 By default this daemon will try to self-confine itself to work
1093 with files under well-known directories whitelisted at build
1094 time. It is better to stick with this default behavior and not
1095 to use this flag unless some other Access Control is used to
1096 confine daemon. Note that in contrast to other access control
1097 implementations that are typically enforced from kernel-space
1098 (e.g. DAC or MAC), self-confinement is imposed from the user-
1099 space daemon itself and hence should not be considered as a full
1100 confinement strategy, but instead should be viewed as an addi‐
1101 tional layer of security.
1102 --user=user:group
1104 Causes this program to run as a different user specified in
1105 user:group, thus dropping most of the root privileges. Short
1106 forms user and :group are also allowed, with current user or
1107 group assumed, respectively. Only daemons started by the root
1108 user accepts this argument.
1109 On Linux, daemons will be granted CAP_IPC_LOCK and
1111 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
1112 that interact with a datapath, such as ovs-vswitchd, will be
1113 granted three additional capabilities, namely CAP_NET_ADMIN,
1114 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
1115 apply even if the new user is root.
1116 On Windows, this option is not currently supported. For security
1118 reasons, specifying this option will cause the daemon process
1119 not to start.
1120
1122 -v[spec]
1123 --verbose=[spec]
1124 Sets logging levels. Without any spec, sets the log level for
1125 every module and destination to dbg. Otherwise, spec is a list of
1126 words separated by spaces or commas or colons, up to one from each
1127 category below:
1128 · A valid module name, as displayed by the vlog/list command
1130 on ovs-appctl(8), limits the log level change to the speci‐
1131 fied module.
1132 · syslog, console, or file, to limit the log level change to
1134 only to the system log, to the console, or to a file,
1135 respectively. (If --detach is specified, the daemon closes
1136 its standard file descriptors, so logging to the console
1137 will have no effect.)
1138 On Windows platform, syslog is accepted as a word and is
1140 only useful along with the --syslog-target option (the word
1141 has no effect otherwise).
1142 · off, emer, err, warn, info, or dbg, to control the log
1144 level. Messages of the given severity or higher will be
1145 logged, and messages of lower severity will be filtered
1146 out. off filters out all messages. See ovs-appctl(8) for a
1147 definition of each log level.
1148 Case is not significant within spec.
1150 Regardless of the log levels set for file, logging to a file will
1152 not take place unless --log-file is also specified (see below).
1153 For compatibility with older versions of OVS, any is accepted as a
1155 word but has no effect.
1156 -v
1158 --verbose
1159 Sets the maximum logging verbosity level, equivalent to --ver‐
1160 bose=dbg.
1161 -vPATTERN:destination:pattern
1163 --verbose=PATTERN:destination:pattern
1164 Sets the log pattern for destination to pattern. Refer to
1165 ovs-appctl(8) for a description of the valid syntax for pattern.
1166 -vFACILITY:facility
1168 --verbose=FACILITY:facility
1169 Sets the RFC5424 facility of the log message. facility can be one
1170 of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
1171 ftp, ntp, audit, alert, clock2, local0, local1, local2, local3,
1172 local4, local5, local6 or local7. If this option is not specified,
1173 daemon is used as the default for the local system syslog and
1174 local0 is used while sending a message to the target provided via
1175 the --syslog-target option.
1176 --log-file[=file]
1178 Enables logging to a file. If file is specified, then it is used
1179 as the exact name for the log file. The default log file name used
1180 if file is omitted is /var/log/openvswitch/program.log.
1181 --syslog-target=host:port
1183 Send syslog messages to UDP port on host, in addition to the sys‐
1184 tem syslog. The host must be a numerical IP address, not a host‐
1185 name.
1186 --syslog-method=method
1188 Specify method as how syslog messages should be sent to syslog
1189 daemon. The following forms are supported:
1190 · libc, to use the libc syslog() function. Downside of using
1192 this options is that libc adds fixed prefix to every mes‐
1193 sage before it is actually sent to the syslog daemon over
1194 /dev/log UNIX domain socket.
1195 · unix:file, to use a UNIX domain socket directly. It is pos‐
1197 sible to specify arbitrary message format with this option.
1198 However, rsyslogd 8.9 and older versions use hard coded
1199 parser function anyway that limits UNIX domain socket use.
1200 If you want to use arbitrary message format with older
1201 rsyslogd versions, then use UDP socket to localhost IP
1202 address instead.
1203 · udp:ip:port, to use a UDP socket. With this method it is
1205 possible to use arbitrary message format also with older
1206 rsyslogd. When sending syslog messages over UDP socket
1207 extra precaution needs to be taken into account, for exam‐
1208 ple, syslog daemon needs to be configured to listen on the
1209 specified UDP port, accidental iptables rules could be
1210 interfering with local syslog traffic and there are some
1211 security considerations that apply to UDP sockets, but do
1212 not apply to UNIX domain sockets.
1213 · null, to discard all messages logged to syslog.
1215 The default is taken from the OVS_SYSLOG_METHOD environment vari‐
1217 able; if it is unset, the default is libc.
1218
1220 These options control the format of output from the list and find com‐
1221 mands.
1222 -f format
1224 --format=format
1225 Sets the type of table formatting. The following types of
1226 format are available:
1227 table 2-D text tables with aligned columns.
1229 list (default)
1231 A list with one column per line and rows separated
1232 by a blank line.
1233 html HTML tables.
1235 csv Comma-separated values as defined in RFC 4180.
1237 json JSON format as defined in RFC 4627. The output is a
1239 sequence of JSON objects, each of which corresponds
1240 to one table. Each JSON object has the following
1241 members with the noted values:
1242 caption
1244 The table’s caption. This member is omitted
1245 if the table has no caption.
1246 headings
1248 An array with one element per table column.
1249 Each array element is a string giving the
1250 corresponding column’s heading.
1251 data An array with one element per table row. Each
1253 element is also an array with one element per
1254 table column. The elements of this second-
1255 level array are the cells that constitute the
1256 table. Cells that represent OVSDB data or
1257 data types are expressed in the format
1258 described in the OVSDB specification; other
1259 cells are simply expressed as text strings.
1260 -d format
1262 --data=format
1263 Sets the formatting for cells within output tables unless
1264 the table format is set to json, in which case json format‐
1265 ting is always used when formatting cells. The following
1266 types of format are available:
1267 string (default)
1269 The simple format described in the Database Values
1270 section of ovs-vsctl(8).
1271 bare The simple format with punctuation stripped off: []
1273 and {} are omitted around sets, maps, and empty col‐
1274 umns, items within sets and maps are space-sepa‐
1275 rated, and strings are never quoted. This format may
1276 be easier for scripts to parse.
1277 json The RFC 4627 JSON format as described above.
1279 --no-headings
1281 This option suppresses the heading row that otherwise
1282 appears in the first row of table output.
1283 --pretty
1285 By default, JSON in output is printed as compactly as pos‐
1286 sible. This option causes JSON in output to be printed in a
1287 more readable fashion. Members of objects and elements of
1288 arrays are printed one per line, with indentation.
1289 This option does not affect JSON in tables, which is always
1291 printed compactly.
1292 --bare
1294 Equivalent to --format=list --data=bare --no-headings.
1295 PKI Options
1297 PKI configuration is required to use SSL for the connection to the
1298 database.
1299 -p privkey.pem
1301 --private-key=privkey.pem
1302 Specifies a PEM file containing the private key used as
1303 identity for outgoing SSL connections.
1304 -c cert.pem
1306 --certificate=cert.pem
1307 Specifies a PEM file containing a certificate that certi‐
1308 fies the private key specified on -p or --private-key to be
1309 trustworthy. The certificate must be signed by the certifi‐
1310 cate authority (CA) that the peer in SSL connections will
1311 use to verify it.
1312 -C cacert.pem
1314 --ca-cert=cacert.pem
1315 Specifies a PEM file containing the CA certificate for ver‐
1316 ifying certificates presented to this program by SSL peers.
1317 (This may be the same certificate that SSL peers use to
1318 verify the certificate specified on -c or --certificate, or
1319 it may be a different one, depending on the PKI design in
1320 use.)
1321 -C none
1323 --ca-cert=none
1324 Disables verification of certificates presented by SSL
1325 peers. This introduces a security risk, because it means
1326 that certificates cannot be verified to be those of known
1327 trusted hosts.
1328 --bootstrap-ca-cert=cacert.pem
1330 When cacert.pem exists, this option has the same effect
1331 as -C or --ca-cert. If it does not exist, then the exe‐
1332 cutable will attempt to obtain the CA certificate from
1333 the SSL peer on its first SSL connection and save it to
1334 the named PEM file. If it is successful, it will immedi‐
1335 ately drop the connection and reconnect, and from then on
1336 all SSL connections must be authenticated by a certifi‐
1337 cate signed by the CA certificate thus obtained.
1338 This option exposes the SSL connection to a man-in-the-
1340 middle attack obtaining the initial CA certificate, but
1341 it may be useful for bootstrapping.
1342 This option is only useful if the SSL peer sends its CA
1344 certificate as part of the SSL certificate chain. The SSL
1345 protocol does not require the server to send the CA cer‐
1346 tificate.
1347 This option is mutually exclusive with -C and --ca-cert.
1349 Other Options
1351 -h
1352 --help
1353 Prints a brief help message to the console.
1354 -V
1356 --version
1357 Prints version information to the console.
1358Open vSwitch 2.11.1 ovn-nbctl ovn-nbctl(8)