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
300 lr-add Creates a new, unnamed logical router, which initially has no
301 ports. The router does not have a name, other commands must
302 refer to this router by its UUID.
303 [--may-exist | --add-duplicate] lr-add router
305 Creates a new logical router named router, which initially has
306 no ports.
307 The OVN northbound database schema does not require logical
309 router names to be unique, but the whole point to the names is
310 to provide an easy way for humans to refer to the routers, mak‐
311 ing duplicate names unhelpful. Thus, without any options, this
312 command regards it as an error if router is a duplicate name.
313 With --may-exist, adding a duplicate name succeeds but does not
314 create a new logical router. With --add-duplicate, the command
315 really creates a new logical router with a duplicate name. It is
316 an error to specify both options. If there are multiple logical
317 routers with a duplicate name, configure the logical routers
318 using the UUID instead of the router name.
319 [--if-exists] lr-del router
321 Deletes router. It is an error if router does not exist, unless
322 --if-exists is specified.
323 lr-list
325 Lists all existing routers on standard output, one per line.
326
328 [--may-exist] lrp-add router port mac network... [peer=peer]
329 Creates on router a new logical router port named port with Eth‐
330 ernet address mac and one or more IP address/netmask for each
331 network.
332 The optional argument peer identifies a logical router port that
334 connects to this one. The following example adds a router port
335 with an IPv4 and IPv6 address with peer lr1:
336 lrp-add lr0 lrp0 00:11:22:33:44:55 192.168.0.1/24 2001:db8::1/64
338 peer=lr1
339 It is an error if a logical router port named port already
341 exists, unless --may-exist is specified. Regardless of
342 --may-exist, it is an error if the existing router port is in
343 some logical router other than router.
344 [--if-exists] lrp-del port
346 Deletes port. It is an error if port does not exist, unless
347 --if-exists is specified.
348 lrp-list router
350 Lists all the logical router ports within router on standard
351 output, one per line.
352 lrp-set-enabled port state
354 Set the administrative state of port, either enabled or dis‐
355 abled. When a port is disabled, no traffic is allowed into or
356 out of the port.
357 lrp-get-enabled port
359 Prints the administrative state of port, either enabled or dis‐
360 abled.
361 lrp-set-gateway-chassis port chassis [priority]
363 Set gateway chassis for port. chassis is the name of the chas‐
364 sis. This creates a gateway chassis entry in Gateway_Chassis ta‐
365 ble. It won’t check if chassis really exists in OVN_Southbound
366 database. Priority will be set to 0 if priority is not provided
367 by user. priority must be between 0 and 32767, inclusive.
368 lrp-del-gateway-chassis port chassis
370 Deletes gateway chassis from port. It is an error if gateway
371 chassis with chassis for port does not exist.
372 lrp-get-gateway-chassis port
374 Lists all the gateway chassis with priority within port on stan‐
375 dard output, one per line, ordered based on priority.
376
378 [--may-exist] [--policy=POLICY] lr-route-add router prefix nexthop
379 [port]
380 Adds the specified route to router. prefix describes an IPv4 or
381 IPv6 prefix for this route, such as 192.168.100.0/24. nexthop
382 specifies the gateway to use for this route, which should be the
383 IP address of one of router logical router ports or the IP
384 address of a logical port. If port is specified, packets that
385 match this route will be sent out that port. When port is omit‐
386 ted, OVN infers the output port based on nexthop.
387 --policy describes the policy used to make routing decisions.
389 This should be one of "dst-ip" or "src-ip". If not specified,
390 the default is "dst-ip".
391 It is an error if a route with prefix already exists, unless
393 --may-exist is specified.
394 [--if-exists] lr-route-del router [prefix]
396 Deletes routes from router. If only router is supplied, all the
397 routes from the logical router are deleted. If prefix is also
398 specified, then all the routes that match the prefix will be
399 deleted from the logical router.
400 It is an error if prefix is specified and there is no matching
402 route entry, unless --if-exists is specified.
403 lr-route-list router
405 Lists the routes on router.
406
408 [--may-exist] lr-nat-add router type external_ip logical_ip [logi‐
409 cal_port external_mac]
410 Adds the specified NAT to router. The type must be one of snat,
411 dnat, or dnat_and_snat. The external_ip is an IPv4 address. The
412 logical_ip is an IPv4 network (e.g 192.168.1.0/24) or an IPv4
413 address. The logical_port and external_mac are only accepted
414 when router is a distributed router (rather than a gateway
415 router) and type is dnat_and_snat. The logical_port is the name
416 of an existing logical switch port where the logical_ip resides.
417 The external_mac is an Ethernet address.
418 When type is dnat, the externally visible IP address external_ip
420 is DNATted to the IP address logical_ip in the logical space.
421 When type is snat, IP packets with their source IP address that
423 either matches the IP address in logical_ip or is in the network
424 provided by logical_ip is SNATed into the IP address in exter‐
425 nal_ip.
426 When type is dnat_and_snat, the externally visible IP address
428 external_ip is DNATted to the IP address logical_ip in the logi‐
429 cal space. In addition, IP packets with the source IP address
430 that matches logical_ip is SNATed into the IP address in exter‐
431 nal_ip.
432 When the logical_port and external_mac are specified, the NAT
434 rule will be programmed on the chassis where the logical_port
435 resides. This includes ARP replies for the external_ip, which
436 return the value of external_mac. All packets transmitted with
437 source IP address equal to external_ip will be sent using the
438 external_mac.
439 It is an error if a NAT already exists with the same values of
441 router, type, external_ip, and logical_ip, unless --may-exist is
442 specified. When --may-exist, logical_port, and external_mac are
443 all specified, the existing values of logical_port and exter‐
444 nal_mac are overwritten.
445 [--if-exists] lr-nat-del router [type [ip]]
447 Deletes NATs from router. If only router is supplied, all the
448 NATs from the logical router are deleted. If type is also speci‐
449 fied, then all the NATs that match the type will be deleted from
450 the logical router. If all the fields are given, then a single
451 NAT rule that matches all the fields will be deleted. When type
452 is snat, the ip should be logical_ip. When type is dnat or
453 dnat_and_snat, the ip shoud be external_ip.
454 It is an error if ip is specified and there is no matching NAT
456 entry, unless --if-exists is specified.
457 lr-nat-list router
459 Lists the NATs on router.
460
462 [--may-exist | --add-duplicate] lb-add lb vip ips [protocol]
463 Creates a new load balancer named lb with the provided vip and
464 ips or adds the vip to an existing lb. vip should be a virtual
465 IP address (or an IP address and a port number with : as a sepa‐
466 rator). Examples for vip are 192.168.1.4, fd0f::1, and
467 192.168.1.5:8080. ips should be comma separated IP endpoints (or
468 comma separated IP addresses and port numbers with : as a sepa‐
469 rator). ips must be the same address family as vip. Examples for
470 ips are 10.0.0.1,10.0.0.2or [fdef::1]:8800,[fdef::2]:8800.
471 The optional argument protocol must be either tcp or udp. This
473 argument is useful when a port number is provided as part of the
474 vip. If the protocol is unspecified and a port number is pro‐
475 vided as part of the vip, OVN assumes the protocol to be tcp.
476 It is an error if the vip already exists in the load balancer
478 named lb, unless --may-exist is specified. With --add-duplicate,
479 the command really creates a new load balancer with a duplicate
480 name.
481 The following example adds a load balancer.
483 lb-add lb0 30.0.0.10:80
485 192.168.10.10:80,192.168.10.20:80,192.168.10.30:80 udp
486 [--if-exists] lb-del lb [vip]
488 Deletes lb or the vip from lb. If vip is supplied, only the vip
489 will be deleted from the lb. If only the lb is supplied, the lb
490 will be deleted. It is an error if vip does not already exist in
491 lb, unless --if-exists is specified.
492 lb-list [lb]
494 Lists the LBs. If lb is also specified, then only the specified
495 lb will be listed.
496 [--may-exist] ls-lb-add switch lb
498 Adds the specified lb to switch. It is an error if a load bal‐
499 ancer named lb already exists in the switch, unless --may-exist
500 is specified.
501 [--if-exists] ls-lb-del switch [lb]
503 Removes lb from switch. If only switch is supplied, all the LBs
504 from the logical switch are removed. If lb is also specified,
505 then only the lb will be removed from the logical switch. It is
506 an error if lb does not exist in the switch, unless --if-exists
507 is specified.
508 ls-lb-list switch
510 Lists the LBs for the given switch.
511 [--may-exist] lr-lb-add router lb
513 Adds the specified lb to router. It is an error if a load bal‐
514 ancer named lb already exists in the router, unless --may-exist
515 is specified.
516 [--if-exists] lr-lb-del router [lb]
518 Removes lb from router. If only router is supplied, all the LBs
519 from the logical router are removed. If lb is also specified,
520 then only the lb will be removed from the logical router. It is
521 an error if lb does not exist in the router, unless --if-exists
522 is specified.
523 lr-lb-list router
525 Lists the LBs for the given router.
526
528 dhcp-options-create cidr [key=value]
529 Creates a new DHCP Options entry in the DHCP_Options table with
530 the specified cidr and optional external-ids.
531 dhcp-options-list
533 Lists the DHCP Options entries.
534 dhcp-options-del dhcp-option
536 Deletes the DHCP Options entry referred by dhcp-option UUID.
537 dhcp-options-set-options dhcp-option [key=value]...
539 Set the DHCP Options for the dhcp-option UUID.
540 dhcp-options-get-options dhcp-option
542 Lists the DHCP Options for the dhcp-option UUID.
543
545 These commands query and modify the contents of ovsdb tables. They are
546 a slight abstraction of the ovsdb interface and as such they operate at
547 a lower level than other ovn-nbctl commands.
548 Identifying Tables, Records, and Columns
550 Each of these commands has a table parameter to identify a table within
552 the database. Many of them also take a record parameter that identifies
553 a particular record within a table. The record parameter may be the
554 UUID for a record, which may be abbreviated to its first 4 (or more)
555 hex digits, as long as that is unique. Many tables offer additional
556 ways to identify records. Some commands also take column parameters
557 that identify a particular field within the records in a table.
558 For a list of tables and their columns, see ovn-nb(5) or see the table
560 listing from the --help option.
561 Record names must be specified in full and with correct capitalization,
563 except that UUIDs may be abbreviated to their first 4 (or more) hex
564 digits, as long as that is unique within the table. Names of tables and
565 columns are not case-sensitive, and - and _ are treated interchange‐
566 ably. Unique abbreviations of table and column names are acceptable,
567 e.g. d or dhcp is sufficient to identify the DHCP_Options table.
568 Database Values
570 Each column in the database accepts a fixed type of data. The currently
572 defined basic types, and their representations, are:
573 integer
575 A decimal integer in the range -2**63 to 2**63-1, inclu‐
576 sive.
577 real A floating-point number.
579 Boolean
581 True or false, written true or false, respectively.
582 string An arbitrary Unicode string, except that null bytes are
584 not allowed. Quotes are optional for most strings that
585 begin with an English letter or underscore and consist
586 only of letters, underscores, hyphens, and periods. How‐
587 ever, true and false and strings that match the syntax of
588 UUIDs (see below) must be enclosed in double quotes to
589 distinguish them from other basic types. When double
590 quotes are used, the syntax is that of strings in JSON,
591 e.g. backslashes may be used to escape special charac‐
592 ters. The empty string must be represented as a pair of
593 double quotes ("").
594 UUID Either a universally unique identifier in the style of
596 RFC 4122, e.g. f81d4fae-7dec-11d0-a765-00a0c91e6bf6, or
597 an @name defined by a get or create command within the
598 same ovn-nbctl invocation.
599 Multiple values in a single column may be separated by spaces or a sin‐
601 gle comma. When multiple values are present, duplicates are not
602 allowed, and order is not important. Conversely, some database columns
603 can have an empty set of values, represented as [], and square brackets
604 may optionally enclose other non-empty sets or single values as well.
605 A few database columns are ``maps’’ of key-value pairs, where the key
607 and the value are each some fixed database type. These are specified in
608 the form key=value, where key and value follow the syntax for the col‐
609 umn’s key type and value type, respectively. When multiple pairs are
610 present (separated by spaces or a comma), duplicate keys are not
611 allowed, and again the order is not important. Duplicate values are
612 allowed. An empty map is represented as {}. Curly braces may optionally
613 enclose non-empty maps as well (but use quotes to prevent the shell
614 from expanding other-config={0=x,1=y} into other-config=0=x other-con‐
615 fig=1=y, which may not have the desired effect).
616 Database Command Syntax
618 [--if-exists] [--columns=column[,column]...] list table
620 [record]...
621 Lists the data in each specified record. If no records
622 are specified, lists all the records in table.
623 If --columns is specified, only the requested columns are
625 listed, in the specified order. Otherwise, all columns
626 are listed, in alphabetical order by column name.
627 Without --if-exists, it is an error if any specified
629 record does not exist. With --if-exists, the command
630 ignores any record that does not exist, without producing
631 any output.
632 [--columns=column[,column]...] find table [col‐
634 umn[:key]=value]...
635 Lists the data in each record in table whose column
636 equals value or, if key is specified, whose column con‐
637 tains a key with the specified value. The following oper‐
638 ators may be used where = is written in the syntax sum‐
639 mary:
640 = != < > <= >=
642 Selects records in which column[:key] equals, does
643 not equal, is less than, is greater than, is less
644 than or equal to, or is greater than or equal to
645 value, respectively.
646 Consider column[:key] and value as sets of ele‐
648 ments. Identical sets are considered equal. Other‐
649 wise, if the sets have different numbers of ele‐
650 ments, then the set with more elements is consid‐
651 ered to be larger. Otherwise, consider a element
652 from each set pairwise, in increasing order within
653 each set. The first pair that differs determines
654 the result. (For a column that contains key-value
655 pairs, first all the keys are compared, and values
656 are considered only if the two sets contain iden‐
657 tical keys.)
658 {=} {!=}
660 Test for set equality or inequality, respectively.
661 {<=} Selects records in which column[:key] is a subset
663 of value. For example, flood-vlans{<=}1,2 selects
664 records in which the flood-vlans column is the
665 empty set or contains 1 or 2 or both.
666 {<} Selects records in which column[:key] is a proper
668 subset of value. For example, flood-vlans{<}1,2
669 selects records in which the flood-vlans column is
670 the empty set or contains 1 or 2 but not both.
671 {>=} {>}
673 Same as {<=} and {<}, respectively, except that
674 the relationship is reversed. For example,
675 flood-vlans{>=}1,2 selects records in which the
676 flood-vlans column contains both 1 and 2.
677 For arithmetic operators (= != < > <= >=), when key is
679 specified but a particular record’s column does not con‐
680 tain key, the record is always omitted from the results.
681 Thus, the condition other-config:mtu!=1500 matches
682 records that have a mtu key whose value is not 1500, but
683 not those that lack an mtu key.
684 For the set operators, when key is specified but a par‐
686 ticular record’s column does not contain key, the compar‐
687 ison is done against an empty set. Thus, the condition
688 other-config:mtu{!=}1500 matches records that have a mtu
689 key whose value is not 1500 and those that lack an mtu
690 key.
691 Don’t forget to escape < or > from interpretation by the
693 shell.
694 If --columns is specified, only the requested columns are
696 listed, in the specified order. Otherwise all columns are
697 listed, in alphabetical order by column name.
698 The UUIDs shown for rows created in the same ovn-nbctl
700 invocation will be wrong.
701 [--if-exists] [--id=@name] get table record [column[:key]]...
703 Prints the value of each specified column in the given
704 record in table. For map columns, a key may optionally be
705 specified, in which case the value associated with key in
706 the column is printed, instead of the entire map.
707 Without --if-exists, it is an error if record does not
709 exist or key is specified, if key does not exist in
710 record. With --if-exists, a missing record yields no out‐
711 put and a missing key prints a blank line.
712 If @name is specified, then the UUID for record may be
714 referred to by that name later in the same ovn-nbctl
715 invocation in contexts where a UUID is expected.
716 Both --id and the column arguments are optional, but usu‐
718 ally at least one or the other should be specified. If
719 both are omitted, then get has no effect except to verify
720 that record exists in table.
721 --id and --if-exists cannot be used together.
723 [--if-exists] set table record column[:key]=value...
725 Sets the value of each specified column in the given
726 record in table to value. For map columns, a key may
727 optionally be specified, in which case the value associ‐
728 ated with key in that column is changed (or added, if
729 none exists), instead of the entire map.
730 Without --if-exists, it is an error if record does not
732 exist. With --if-exists, this command does nothing if
733 record does not exist.
734 [--if-exists] add table record column [key=]value...
736 Adds the specified value or key-value pair to column in
737 record in table. If column is a map, then key is
738 required, otherwise it is prohibited. If key already
739 exists in a map column, then the current value is not
740 replaced (use the set command to replace an existing
741 value).
742 Without --if-exists, it is an error if record does not
744 exist. With --if-exists, this command does nothing if
745 record does not exist.
746 [--if-exists] remove table record column value...
748 [--if-exists] remove table record column key...
750 [--if-exists] remove table record column key=value...
752 Removes the specified values or key-value pairs from col‐
753 umn in record in table. The first form applies to columns
754 that are not maps: each specified value is removed from
755 the column. The second and third forms apply to map col‐
756 umns: if only a key is specified, then any key-value pair
757 with the given key is removed, regardless of its value;
758 if a value is given then a pair is removed only if both
759 key and value match.
760 It is not an error if the column does not contain the
762 specified key or value or pair.
763 Without --if-exists, it is an error if record does not
765 exist. With --if-exists, this command does nothing if
766 record does not exist.
767 [--if-exists] clear table record column...
769 Sets each column in record in table to the empty set or
770 empty map, as appropriate. This command applies only to
771 columns that are allowed to be empty.
772 Without --if-exists, it is an error if record does not
774 exist. With --if-exists, this command does nothing if
775 record does not exist.
776 [--id=@name] create table column[:key]=value...
778 Creates a new record in table and sets the initial values
779 of each column. Columns not explicitly set will receive
780 their default values. Outputs the UUID of the new row.
781 If @name is specified, then the UUID for the new row may
783 be referred to by that name elsewhere in the same \*(PN
784 invocation in contexts where a UUID is expected. Such
785 references may precede or follow the create command.
786 Caution (ovs-vsctl as example)
788 Records in the Open vSwitch database are signifi‐
789 cant only when they can be reached directly or
790 indirectly from the Open_vSwitch table. Except for
791 records in the QoS or Queue tables, records that
792 are not reachable from the Open_vSwitch table are
793 automatically deleted from the database. This
794 deletion happens immediately, without waiting for
795 additional ovs-vsctl commands or other database
796 activity. Thus, a create command must generally be
797 accompanied by additional commands within the same
798 ovs-vsctl invocation to add a chain of references
799 to the newly created record from the top-level
800 Open_vSwitch record. The EXAMPLES section gives
801 some examples that show how to do this.
802 [--if-exists] destroy table record...
804 Deletes each specified record from table. Unless
805 --if-exists is specified, each records must exist.
806 --all destroy table
808 Deletes all records from the table.
809 Caution (ovs-vsctl as example)
811 The destroy command is only useful for records in
812 the QoS or Queue tables. Records in other tables
813 are automatically deleted from the database when
814 they become unreachable from the Open_vSwitch ta‐
815 ble. This means that deleting the last reference
816 to a record is sufficient for deleting the record
817 itself. For records in these tables, destroy is
818 silently ignored. See the EXAMPLES section below
819 for more information.
820 wait-until table record [column[:key]=value]...
822 Waits until table contains a record named record whose
823 column equals value or, if key is specified, whose column
824 contains a key with the specified value. Any of the oper‐
825 ators !=, <, >, <=, or >= may be substituted for = to
826 test for inequality, less than, greater than, less than
827 or equal to, or greater than or equal to, respectively.
828 (Don’t forget to escape < or > from interpretation by the
829 shell.)
830 If no column[:key]=value arguments are given, this com‐
832 mand waits only until record exists. If more than one
833 such argument is given, the command waits until all of
834 them are satisfied.
835 Caution (ovs-vsctl as example)
837 Usually wait-until should be placed at the begin‐
838 ning of a set of ovs-vsctl commands. For example,
839 wait-until bridge br0 -- get bridge br0 data‐
840 path_id waits until a bridge named br0 is created,
841 then prints its datapath_id column, whereas get
842 bridge br0 datapath_id -- wait-until bridge br0
843 will abort if no bridge named br0 exists when
844 ovs-vsctl initially connects to the database.
845 Consider specifying --timeout=0 along with --wait-until,
847 to prevent ovn-nbctl from terminating after waiting only
848 at most 5 seconds.
849 comment [arg]...
851 This command has no effect on behavior, but any database
852 log record created by the command will include the com‐
853 mand and its arguments.
854
856 sync Ordinarily, --wait=sb or --wait=hv only waits for changes by the
857 current ovn-nbctl invocation to take effect. This means that, if
858 none of the commands supplied to ovn-nbctl change the database,
859 then the command does not wait at all. With the sync command,
860 however, ovn-nbctl waits even for earlier changes to the data‐
861 base to propagate down to the southbound database or all of the
862 OVN chassis, according to the argument to --wait.
863
865 get-connection
866 Prints the configured connection(s).
867 del-connection
869 Deletes the configured connection(s).
870 [--inactivity-probe=msecs] set-connection target...
872 Sets the configured manager target or targets. Use --inactiv‐
873 ity-probe=msecs to override the default idle connection inactiv‐
874 ity probe time. Use 0 to disable inactivity probes.
875
877 get-ssl
878 Prints the SSL configuration.
879 del-ssl
881 Deletes the current SSL configuration.
882 [--bootstrap] set-ssl private-key certificate ca-cert [ssl-protocol-
884 list [ssl-cipher-list]]
885 Sets the SSL configuration.
886
888 When it is invoked in the most ordinary way, ovn-nbctl connects to an
889 OVSDB server that hosts the northbound database, retrieves a partial
890 copy of the database that is complete enough to do its work, sends a
891 transaction request to the server, and receives and processes the
892 server’s reply. In common interactive use, this is fine, but if the
893 database is large, the step in which ovn-nbctl retrieves a partial copy
894 of the database can take a long time, which yields poor performance
895 overall.
896 To improve performance in such a case, ovn-nbctl offers a "daemon
898 mode," in which the user first starts ovn-nbctl running in the back‐
899 ground and afterward uses the daemon to execute operations. Over sev‐
900 eral ovn-nbctl command invocations, this performs better overall
901 because it retrieves a copy of the database only once at the beginning,
902 not once per program run.
903 Use the --detach option to start an ovn-nbctl daemon. With this option,
905 ovn-nbctl prints the name of a control socket to stdout. The client
906 should save this name in environment variable OVN_NB_DAEMON. Under the
907 Bourne shell this might be done like this:
908 export OVN_NB_DAEMON=$(ovn-nbctl --pidfile --detach)
910 When OVN_NB_DAEMON is set, ovn-nbctl automatically and transparently
913 uses the daemon to execute its commands.
914 When the daemon is no longer needed, kill it and unset the environment
916 variable, e.g.:
917 kill $(cat /var/run/ovn-nbctl.pid)
919 unset OVN_NB_DAEMON
920 Daemon mode is experimental.
923 Daemon Commands
925 Daemon mode is internally implemented using the same mechanism used by
926 ovs-appctl. One may also use ovs-appctl directly with the following
927 commands:
928 run [options] command [arg...] [-- [options] command [arg...]
930 ...]
931 Instructs the daemon process to run one or more ovn-nbctl
932 commands described above and reply with the results of
933 running these commands. Accepts the --no-wait, --wait,
934 --timeout, --dry-run, --oneline, and the options
935 described under Table Formatting Options in addition to
936 the the command-specific options.
937 exit Causes ovn-nbctl to gracefully terminate.
939
941 --no-wait | --wait=none
942 --wait=sb
943 --wait=hv
944 These options control whether and how ovn-nbctl waits for the OVN
945 system to become up-to-date with changes made in an ovn-nbctl
946 invocation.
947 By default, or if --no-wait or --wait=none, ovn-nbctl exits imme‐
949 diately after confirming that changes have been committed to the
950 northbound database, without waiting.
951 With --wait=sb, before ovn-nbctl exits, it waits for ovn-northd to
953 bring the southbound database up-to-date with the northbound data‐
954 base updates.
955 With --wait=hv, before ovn-nbctl exits, it additionally waits for
957 all OVN chassis (hypervisors and gateways) to become up-to-date
958 with the northbound database updates. (This can become an indefi‐
959 nite wait if any chassis is malfunctioning.)
960 Ordinarily, --wait=sb or --wait=hv only waits for changes by the
962 current ovn-nbctl invocation to take effect. This means that, if
963 none of the commands supplied to ovn-nbctl change the database,
964 then the command does not wait at all. Use the sync command to
965 override this behavior.
966 --db database
968 The OVSDB database remote to contact. If the OVN_NB_DB environment
969 variable is set, its value is used as the default. Otherwise, the
970 default is unix:/var/run/openvswitch/ovnnb_db.sock, but this
971 default is unlikely to be useful outside of single-machine OVN
972 test environments.
973 --leader-only
975 --no-leader-only
976 By default, or with --leader-only, when the database server is a
977 clustered database, ovn-nbctl will avoid servers other than the
978 cluster leader. This ensures that any data that ovn-nbctl reads
979 and reports is up-to-date. With --no-leader-only, ovn-nbctl will
980 use any server in the cluster, which means that for read-only
981 transactions it can report and act on stale data (transactions
982 that modify the database are always serialized even with
983 --no-leader-only). Refer to Understanding Cluster Consistency in
984 ovsdb(7) for more information.
985 Daemon Options
987 --pidfile[=pidfile]
988 Causes a file (by default, program.pid) to be created indicating
989 the PID of the running process. If the pidfile argument is not
990 specified, or if it does not begin with /, then it is created in
991 /var/run/openvswitch.
992 If --pidfile is not specified, no pidfile is created.
994 --overwrite-pidfile
996 By default, when --pidfile is specified and the specified pid‐
997 file already exists and is locked by a running process, the dae‐
998 mon refuses to start. Specify --overwrite-pidfile to cause it to
999 instead overwrite the pidfile.
1000 When --pidfile is not specified, this option has no effect.
1002 --detach
1004 Runs this program as a background process. The process forks,
1005 and in the child it starts a new session, closes the standard
1006 file descriptors (which has the side effect of disabling logging
1007 to the console), and changes its current directory to the root
1008 (unless --no-chdir is specified). After the child completes its
1009 initialization, the parent exits.
1010 --monitor
1012 Creates an additional process to monitor this program. If it
1013 dies due to a signal that indicates a programming error (SIGA‐
1014 BRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE, SIGSEGV, SIGXCPU,
1015 or SIGXFSZ) then the monitor process starts a new copy of it. If
1016 the daemon dies or exits for another reason, the monitor process
1017 exits.
1018 This option is normally used with --detach, but it also func‐
1020 tions without it.
1021 --no-chdir
1023 By default, when --detach is specified, the daemon changes its
1024 current working directory to the root directory after it
1025 detaches. Otherwise, invoking the daemon from a carelessly cho‐
1026 sen directory would prevent the administrator from unmounting
1027 the file system that holds that directory.
1028 Specifying --no-chdir suppresses this behavior, preventing the
1030 daemon from changing its current working directory. This may be
1031 useful for collecting core files, since it is common behavior to
1032 write core dumps into the current working directory and the root
1033 directory is not a good directory to use.
1034 This option has no effect when --detach is not specified.
1036 --no-self-confinement
1038 By default this daemon will try to self-confine itself to work
1039 with files under well-known directories whitelisted at build
1040 time. It is better to stick with this default behavior and not
1041 to use this flag unless some other Access Control is used to
1042 confine daemon. Note that in contrast to other access control
1043 implementations that are typically enforced from kernel-space
1044 (e.g. DAC or MAC), self-confinement is imposed from the user-
1045 space daemon itself and hence should not be considered as a full
1046 confinement strategy, but instead should be viewed as an addi‐
1047 tional layer of security.
1048 --user=user:group
1050 Causes this program to run as a different user specified in
1051 user:group, thus dropping most of the root privileges. Short
1052 forms user and :group are also allowed, with current user or
1053 group assumed, respectively. Only daemons started by the root
1054 user accepts this argument.
1055 On Linux, daemons will be granted CAP_IPC_LOCK and
1057 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
1058 that interact with a datapath, such as ovs-vswitchd, will be
1059 granted three additional capabilities, namely CAP_NET_ADMIN,
1060 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
1061 apply even if the new user is root.
1062 On Windows, this option is not currently supported. For security
1064 reasons, specifying this option will cause the daemon process
1065 not to start.
1066
1068 -v[spec]
1069 --verbose=[spec]
1070 Sets logging levels. Without any spec, sets the log level for
1071 every module and destination to dbg. Otherwise, spec is a list of
1072 words separated by spaces or commas or colons, up to one from each
1073 category below:
1074 · A valid module name, as displayed by the vlog/list command
1076 on ovs-appctl(8), limits the log level change to the speci‐
1077 fied module.
1078 · syslog, console, or file, to limit the log level change to
1080 only to the system log, to the console, or to a file,
1081 respectively. (If --detach is specified, the daemon closes
1082 its standard file descriptors, so logging to the console
1083 will have no effect.)
1084 On Windows platform, syslog is accepted as a word and is
1086 only useful along with the --syslog-target option (the word
1087 has no effect otherwise).
1088 · off, emer, err, warn, info, or dbg, to control the log
1090 level. Messages of the given severity or higher will be
1091 logged, and messages of lower severity will be filtered
1092 out. off filters out all messages. See ovs-appctl(8) for a
1093 definition of each log level.
1094 Case is not significant within spec.
1096 Regardless of the log levels set for file, logging to a file will
1098 not take place unless --log-file is also specified (see below).
1099 For compatibility with older versions of OVS, any is accepted as a
1101 word but has no effect.
1102 -v
1104 --verbose
1105 Sets the maximum logging verbosity level, equivalent to --ver‐
1106 bose=dbg.
1107 -vPATTERN:destination:pattern
1109 --verbose=PATTERN:destination:pattern
1110 Sets the log pattern for destination to pattern. Refer to
1111 ovs-appctl(8) for a description of the valid syntax for pattern.
1112 -vFACILITY:facility
1114 --verbose=FACILITY:facility
1115 Sets the RFC5424 facility of the log message. facility can be one
1116 of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
1117 ftp, ntp, audit, alert, clock2, local0, local1, local2, local3,
1118 local4, local5, local6 or local7. If this option is not specified,
1119 daemon is used as the default for the local system syslog and
1120 local0 is used while sending a message to the target provided via
1121 the --syslog-target option.
1122 --log-file[=file]
1124 Enables logging to a file. If file is specified, then it is used
1125 as the exact name for the log file. The default log file name used
1126 if file is omitted is /var/log/openvswitch/program.log.
1127 --syslog-target=host:port
1129 Send syslog messages to UDP port on host, in addition to the sys‐
1130 tem syslog. The host must be a numerical IP address, not a host‐
1131 name.
1132 --syslog-method=method
1134 Specify method as how syslog messages should be sent to syslog
1135 daemon. The following forms are supported:
1136 · libc, to use the libc syslog() function. This is the
1138 default behavior. Downside of using this options is that
1139 libc adds fixed prefix to every message before it is actu‐
1140 ally sent to the syslog daemon over /dev/log UNIX domain
1141 socket.
1142 · unix:file, to use a UNIX domain socket directly. It is pos‐
1144 sible to specify arbitrary message format with this option.
1145 However, rsyslogd 8.9 and older versions use hard coded
1146 parser function anyway that limits UNIX domain socket use.
1147 If you want to use arbitrary message format with older
1148 rsyslogd versions, then use UDP socket to localhost IP
1149 address instead.
1150 · udp:ip:port, to use a UDP socket. With this method it is
1152 possible to use arbitrary message format also with older
1153 rsyslogd. When sending syslog messages over UDP socket
1154 extra precaution needs to be taken into account, for exam‐
1155 ple, syslog daemon needs to be configured to listen on the
1156 specified UDP port, accidental iptables rules could be
1157 interfering with local syslog traffic and there are some
1158 security considerations that apply to UDP sockets, but do
1159 not apply to UNIX domain sockets.
1160
1162 These options control the format of output from the list and find com‐
1163 mands.
1164 -f format
1166 --format=format
1167 Sets the type of table formatting. The following types of
1168 format are available:
1169 table 2-D text tables with aligned columns.
1171 list (default)
1173 A list with one column per line and rows separated
1174 by a blank line.
1175 html HTML tables.
1177 csv Comma-separated values as defined in RFC 4180.
1179 json JSON format as defined in RFC 4627. The output is a
1181 sequence of JSON objects, each of which corresponds
1182 to one table. Each JSON object has the following
1183 members with the noted values:
1184 caption
1186 The table’s caption. This member is omitted
1187 if the table has no caption.
1188 headings
1190 An array with one element per table column.
1191 Each array element is a string giving the
1192 corresponding column’s heading.
1193 data An array with one element per table row. Each
1195 element is also an array with one element per
1196 table column. The elements of this second-
1197 level array are the cells that constitute the
1198 table. Cells that represent OVSDB data or
1199 data types are expressed in the format
1200 described in the OVSDB specification; other
1201 cells are simply expressed as text strings.
1202 -d format
1204 --data=format
1205 Sets the formatting for cells within output tables unless
1206 the table format is set to json, in which case json format‐
1207 ting is always used when formatting cells. The following
1208 types of format are available:
1209 string (default)
1211 The simple format described in the Database Values
1212 section of ovs-vsctl(8).
1213 bare The simple format with punctuation stripped off: []
1215 and {} are omitted around sets, maps, and empty col‐
1216 umns, items within sets and maps are space-sepa‐
1217 rated, and strings are never quoted. This format may
1218 be easier for scripts to parse.
1219 json The RFC 4627 JSON format as described above.
1221 --no-headings
1223 This option suppresses the heading row that otherwise
1224 appears in the first row of table output.
1225 --pretty
1227 By default, JSON in output is printed as compactly as pos‐
1228 sible. This option causes JSON in output to be printed in a
1229 more readable fashion. Members of objects and elements of
1230 arrays are printed one per line, with indentation.
1231 This option does not affect JSON in tables, which is always
1233 printed compactly.
1234 --bare
1236 Equivalent to --format=list --data=bare --no-headings.
1237 PKI Options
1239 PKI configuration is required to use SSL for the connection to the
1240 database.
1241 -p privkey.pem
1243 --private-key=privkey.pem
1244 Specifies a PEM file containing the private key used as
1245 identity for outgoing SSL connections.
1246 -c cert.pem
1248 --certificate=cert.pem
1249 Specifies a PEM file containing a certificate that certi‐
1250 fies the private key specified on -p or --private-key to be
1251 trustworthy. The certificate must be signed by the certifi‐
1252 cate authority (CA) that the peer in SSL connections will
1253 use to verify it.
1254 -C cacert.pem
1256 --ca-cert=cacert.pem
1257 Specifies a PEM file containing the CA certificate for ver‐
1258 ifying certificates presented to this program by SSL peers.
1259 (This may be the same certificate that SSL peers use to
1260 verify the certificate specified on -c or --certificate, or
1261 it may be a different one, depending on the PKI design in
1262 use.)
1263 -C none
1265 --ca-cert=none
1266 Disables verification of certificates presented by SSL
1267 peers. This introduces a security risk, because it means
1268 that certificates cannot be verified to be those of known
1269 trusted hosts.
1270 --bootstrap-ca-cert=cacert.pem
1272 When cacert.pem exists, this option has the same effect
1273 as -C or --ca-cert. If it does not exist, then the exe‐
1274 cutable will attempt to obtain the CA certificate from
1275 the SSL peer on its first SSL connection and save it to
1276 the named PEM file. If it is successful, it will immedi‐
1277 ately drop the connection and reconnect, and from then on
1278 all SSL connections must be authenticated by a certifi‐
1279 cate signed by the CA certificate thus obtained.
1280 This option exposes the SSL connection to a man-in-the-
1282 middle attack obtaining the initial CA certificate, but
1283 it may be useful for bootstrapping.
1284 This option is only useful if the SSL peer sends its CA
1286 certificate as part of the SSL certificate chain. The SSL
1287 protocol does not require the server to send the CA cer‐
1288 tificate.
1289 This option is mutually exclusive with -C and --ca-cert.
1291 Other Options
1293 -h
1294 --help
1295 Prints a brief help message to the console.
1296 -V
1298 --version
1299 Prints version information to the console.
1300Open vSwitch 2.10.0 ovn-nbctl ovn-nbctl(8)