1ovn-nbctl(8) OVN Manual ovn-nbctl(8)
2
3
4
5build/.PP
6
8 ovn-nbctl - Open Virtual Network northbound db management utility
9
11 ovn-nbctl [options] command [arg...]
12
14 This utility can be used to manage the OVN northbound database.
15
17 init Initializes the database, if it is empty. If the database has
18 already been initialized, this command has no effect.
19
20 show [switch | router]
21 Prints a brief overview of the database contents. If switch is
22 provided, only records related to that logical switch are shown.
23 If router is provided, only records related to that logical
24 router are shown.
25
27 ls-add Creates a new, unnamed logical switch, which initially has no
28 ports. The switch does not have a name, other commands must re‐
29 fer to this switch by its UUID.
30
31 [--may-exist | --add-duplicate] ls-add switch
32 Creates a new logical switch named switch, which initially has
33 no ports.
34
35 The OVN northbound database schema does not require logical
36 switch names to be unique, but the whole point to the names is
37 to provide an easy way for humans to refer to the switches, mak‐
38 ing duplicate names unhelpful. Thus, without any options, this
39 command regards it as an error if switch is a duplicate name.
40 With --may-exist, adding a duplicate name succeeds but does not
41 create a new logical switch. With --add-duplicate, the command
42 really creates a new logical switch with a duplicate name. It is
43 an error to specify both options. If there are multiple logical
44 switches with a duplicate name, configure the logical switches
45 using the UUID instead of the switch name.
46
47 [--if-exists] ls-del switch
48 Deletes switch. It is an error if switch does not exist, unless
49 --if-exists is specified.
50
51 ls-list
52 Lists all existing switches on standard output, one per line.
53
55 These commands operates on ACL objects for a given entity. The entity
56 can be either a logical switch or a port group. The entity can be spec‐
57 ified as uuid or name. The --type option can be used to specify the
58 type of the entity, in case both a logical switch and a port groups ex‐
59 ist with the same name specified for entity. type must be either switch
60 or port-group.
61
62 [--type={switch | port-group}] [--log] [--meter=meter] [--sever‐
63 ity=severity] [--name=name] [--may-exist] acl-add entity direc‐
64 tion priority match verdict
65 Adds the specified ACL to entity. direction must be ei‐
66 ther from-lport or to-lport. priority must be between 0
67 and 32767, inclusive. A full description of the fields
68 are in ovn-nb(5). If --may-exist is specified, adding a
69 duplicated ACL succeeds but the ACL is not really cre‐
70 ated. Without --may-exist, adding a duplicated ACL re‐
71 sults in error.
72
73 The --log option enables packet logging for the ACL. The
74 options --severity and --name specify a severity and
75 name, respectively, for log entries (and also enable log‐
76 ging). The severity must be one of alert, warning, no‐
77 tice, info, or debug. If a severity is not specified, the
78 default is info. The --meter=meter option is used to
79 rate-limit packet logging. The meter argument names a me‐
80 ter configured by meter-add.
81
82 [--type={switch | port-group}] acl-del entity [direction [prior‐
83 ity match]]
84 Deletes ACLs from entity. If only entity is supplied, all
85 the ACLs from the entity are deleted. If direction is
86 also specified, then all the flows in that direction will
87 be deleted from the entity. If all the fields are given,
88 then a single flow that matches all the fields will be
89 deleted.
90
91 [--type={switch | port-group}] acl-list entity
92 Lists the ACLs on entity.
93
95 [--may-exist] qos-add switch direction priority match [dscp=dscp]
96 [rate=rate [burst=burst]]
97 Adds QoS marking and metering rules to switch. direction must be
98 either from-lport or to-lport. priority must be between 0 and
99 32767, inclusive.
100
101 If dscp=dscp is specified, then matching packets will have DSCP
102 marking applied. dscp must be between 0 and 63, inclusive. If
103 rate=rate is specified then matching packets will have metering
104 applied at rate kbps. If metering is configured, then
105 burst=burst specifies the burst rate limit in kilobits. dscp
106 and/or rate are required arguments.
107
108 If --may-exist is specified, adding a duplicated QoS rule suc‐
109 ceeds but the QoS rule is not really created. Without --may-ex‐
110 ist, adding a duplicated QoS rule results in error.
111
112 qos-del switch [direction [priority match]]
113 Deletes QoS rules from switch. If only switch is supplied, all
114 the QoS rules from the logical switch are deleted. If direction
115 is also specified, then all the flows in that direction will be
116 deleted from the logical switch. If all the fields are supplied,
117 then a single flow that matches the given fields will be
118 deleted.
119
120 If switch and uuid are supplied, then the QoS rule with sepci‐
121 fied uuid is deleted.
122
123 qos-list switch
124 Lists the QoS rules on switch.
125
127 meter-add name action rate unit [burst]
128 Adds the specified meter. name must be a unique name to identify
129 this meter. The action argument specifies what should happen
130 when this meter is exceeded. The only supported action is drop.
131
132 The unit specifies the unit for the rate argument; valid values
133 are kbps and pktps for kilobits per second and packets per sec‐
134 ond, respectively. The burst option configures the maximum burst
135 allowed for the band in kilobits or packets depending on whether
136 the unit chosen was kbps or pktps, respectively. If a burst is
137 not supplied, the switch is free to select some reasonable value
138 depending on its configuration.
139
140 ovn-nbctl only supports adding a meter with a single band, but
141 the other commands support meters with multiple bands.
142
143 Names that start with "__" (two underscores) are reserved for
144 internal use by OVN, so ovn-nbctl does not allow adding them.
145
146 meter-del [name]
147 Deletes meters. By default, all meters are deleted. If name is
148 supplied, only the meter with that name will be deleted.
149
150 meter-list
151 Lists all meters.
152
154 [--may-exist] lsp-add switch port
155 Creates on lswitch a new logical switch port named port.
156
157 It is an error if a logical port named port already exists, un‐
158 less --may-exist is specified. Regardless of --may-exist, it is
159 an error if the existing port is in some logical switch other
160 than switch or if it has a parent port.
161
162 [--may-exist] lsp-add switch port parent tag_request
163 Creates on switch a logical switch port named port that is a
164 child of parent that is identified with VLAN ID tag_request,
165 which must be between 0 and 4095, inclusive. If tag_request is
166 0, ovn-northd generates a tag that is unique in the scope of
167 parent. This is useful in cases such as virtualized container
168 environments where Open vSwitch does not have a direct connec‐
169 tion to the container’s port and it must be shared with the vir‐
170 tual machine’s port.
171
172 It is an error if a logical port named port already exists, un‐
173 less --may-exist is specified. Regardless of --may-exist, it is
174 an error if the existing port is not in switch or if it does not
175 have the specified parent and tag_request.
176
177 [--if-exists] lsp-del port
178 Deletes port. It is an error if port does not exist, unless
179 --if-exists is specified.
180
181 lsp-list switch
182 Lists all the logical switch ports within switch on standard
183 output, one per line.
184
185 lsp-get-parent port
186 If set, get the parent port of port. If not set, print nothing.
187
188 lsp-get-tag port
189 If set, get the tag for port traffic. If not set, print nothing.
190
191 lsp-set-addresses port [address]...
192 Sets the addresses associated with port to address. Each address
193 should be one of the following:
194
195 an Ethernet address, optionally followed by a space and one or
196 more IP addresses
197 OVN delivers packets for the Ethernet address to this
198 port.
199
200 unknown
201 OVN delivers unicast Ethernet packets whose destination
202 MAC address is not in any logical port’s addresses column
203 to ports with address unknown.
204
205 dynamic
206 Use this keyword to make ovn-northd generate a globally
207 unique MAC address and choose an unused IPv4 address with
208 the logical port’s subnet and store them in the port’s
209 dynamic_addresses column.
210
211 router Accepted only when the type of the logical switch port is
212 router. This indicates that the Ethernet, IPv4, and IPv6
213 addresses for this logical switch port should be obtained
214 from the connected logical router port, as specified by
215 router-port in lsp-set-options.
216
217 Multiple addresses may be set. If no address argument is given,
218 port will have no addresses associated with it.
219
220 lsp-get-addresses port
221 Lists all the addresses associated with port on standard output,
222 one per line.
223
224 lsp-set-port-security port [addrs]...
225 Sets the port security addresses associated with port to addrs.
226 Multiple sets of addresses may be set by using multiple addrs
227 arguments. If no addrs argument is given, port will not have
228 port security enabled.
229
230 Port security limits the addresses from which a logical port may
231 send packets and to which it may receive packets. See the
232 ovn-nb(5) documentation for the port_security column in the Log‐
233 ical_Switch_Port table for details.
234
235 lsp-get-port-security port
236 Lists all the port security addresses associated with port on
237 standard output, one per line.
238
239 lsp-get-up port
240 Prints the state of port, either up or down.
241
242 lsp-set-enabled port state
243 Set the administrative state of port, either enabled or dis‐
244 abled. When a port is disabled, no traffic is allowed into or
245 out of the port.
246
247 lsp-get-enabled port
248 Prints the administrative state of port, either enabled or dis‐
249 abled.
250
251 lsp-set-type port type
252 Set the type for the logical port. The type must be one of the
253 following:
254
255 (empty string)
256 A VM (or VIF) interface.
257
258 router A connection to a logical router.
259
260 localnet
261 A connection to a locally accessible network from each
262 ovn-controller instance. A logical switch can only have a
263 single localnet port attached. This is used to model di‐
264 rect connectivity to an existing network.
265
266 localport
267 A connection to a local VIF. Traffic that arrives on a
268 localport is never forwarded over a tunnel to another
269 chassis. These ports are present on every chassis and
270 have the same address in all of them. This is used to
271 model connectivity to local services that run on every
272 hypervisor.
273
274 l2gateway
275 A connection to a physical network.
276
277 vtep A port to a logical switch on a VTEP gateway.
278
279 lsp-get-type port
280 Get the type for the logical port.
281
282 lsp-set-options port [key=value]...
283 Set type-specific key-value options for the logical port.
284
285 lsp-get-options port
286 Get the type-specific options for the logical port.
287
288 lsp-set-dhcpv4-options port dhcp_options
289 Set the DHCPv4 options for the logical port. The dhcp_options is
290 a UUID referring to a set of DHCP options in the DHCP_Options
291 table.
292
293 lsp-get-dhcpv4-options port
294 Get the configured DHCPv4 options for the logical port.
295
296 lsp-set-dhcpv6-options port dhcp_options
297 Set the DHCPv6 options for the logical port. The dhcp_options is
298 a UUID referring to a set of DHCP options in the DHCP_Options
299 table.
300
301 lsp-get-dhcpv6-options port
302 Get the configured DHCPv6 options for the logical port.
303
304 lsp-get-ls port
305 Get the logical switch which the port belongs to.
306
308 [--liveness]fwd-group-add group switch vip vmac ports
309 Creates a new forwarding group named group as the name with the
310 provided vip and vmac. vip should be a virtual IP address and
311 vmac should be a virtual MAC address to access the forwarding
312 group. ports are the logical switch port names that are put in
313 the forwarding group. Example for ports is lsp1 lsp2 ... Traffic
314 destined to virtual IP of the forwarding group will be load bal‐
315 anced to all the child ports.
316
317 When --liveness is specified then child ports are expected to be
318 bound to external devices like routers. BFD should be configured
319 between hypervisors and the external devices. The child port se‐
320 lection will become dependent on BFD status with its external
321 device.
322
323 [--if-exists] fwd-group-del group
324 Deletes group. It is an error if group does not exist, unless
325 --if-exists is specified.
326
327 fwd-group-list [switch]
328 Lists all existing forwarding groups, If switch is specified
329 then only the forwarding groups configured for switch will be
330 listed.
331
333 lr-add Creates a new, unnamed logical router, which initially has no
334 ports. The router does not have a name, other commands must re‐
335 fer to this router by its UUID.
336
337 [--may-exist | --add-duplicate] lr-add router
338 Creates a new logical router named router, which initially has
339 no ports.
340
341 The OVN northbound database schema does not require logical
342 router names to be unique, but the whole point to the names is
343 to provide an easy way for humans to refer to the routers, mak‐
344 ing duplicate names unhelpful. Thus, without any options, this
345 command regards it as an error if router is a duplicate name.
346 With --may-exist, adding a duplicate name succeeds but does not
347 create a new logical router. With --add-duplicate, the command
348 really creates a new logical router with a duplicate name. It is
349 an error to specify both options. If there are multiple logical
350 routers with a duplicate name, configure the logical routers us‐
351 ing the UUID instead of the router name.
352
353 [--if-exists] lr-del router
354 Deletes router. It is an error if router does not exist, unless
355 --if-exists is specified.
356
357 lr-list
358 Lists all existing routers on standard output, one per line.
359
361 [--may-exist] lrp-add router port mac network... [peer=peer]
362 Creates on router a new logical router port named port with Eth‐
363 ernet address mac and one or more IP address/netmask for each
364 network.
365
366 The optional argument peer identifies a logical router port that
367 connects to this one. The following example adds a router port
368 with an IPv4 and IPv6 address with peer lr1:
369
370 lrp-add lr0 lrp0 00:11:22:33:44:55 192.168.0.1/24 2001:db8::1/64
371 peer=lr1
372
373 It is an error if a logical router port named port already ex‐
374 ists, unless --may-exist is specified. Regardless of --may-ex‐
375 ist, it is an error if the existing router port is in some logi‐
376 cal router other than router.
377
378 [--if-exists] lrp-del port
379 Deletes port. It is an error if port does not exist, unless
380 --if-exists is specified.
381
382 lrp-list router
383 Lists all the logical router ports within router on standard
384 output, one per line.
385
386 lrp-set-enabled port state
387 Set the administrative state of port, either enabled or dis‐
388 abled. When a port is disabled, no traffic is allowed into or
389 out of the port.
390
391 lrp-get-enabled port
392 Prints the administrative state of port, either enabled or dis‐
393 abled.
394
395 lrp-set-gateway-chassis port chassis [priority]
396 Set gateway chassis for port. chassis is the name of the chas‐
397 sis. This creates a gateway chassis entry in Gateway_Chassis ta‐
398 ble. It won’t check if chassis really exists in OVN_Southbound
399 database. Priority will be set to 0 if priority is not provided
400 by user. priority must be between 0 and 32767, inclusive.
401
402 lrp-del-gateway-chassis port chassis
403 Deletes gateway chassis from port. It is an error if gateway
404 chassis with chassis for port does not exist.
405
406 lrp-get-gateway-chassis port
407 Lists all the gateway chassis with priority within port on stan‐
408 dard output, one per line, ordered based on priority.
409
411 [--may-exist] [--policy=POLICY] [--ecmp] [--ecmp-symmetric-reply]
412 [--bfd[=UUID]] lr-route-add router prefix nexthop [port]
413 Adds the specified route to router. prefix describes an IPv4 or
414 IPv6 prefix for this route, such as 192.168.100.0/24. nexthop
415 specifies the gateway to use for this route, which should be the
416 IP address of one of router logical router ports or the IP ad‐
417 dress of a logical port. If port is specified, packets that
418 match this route will be sent out that port. When port is omit‐
419 ted, OVN infers the output port based on nexthop.
420
421 --policy describes the policy used to make routing decisions.
422 This should be one of "dst-ip" or "src-ip". If not specified,
423 the default is "dst-ip".
424
425 The --ecmp option allows for multiple routes with the same pre‐
426 fix POLICY but different nexthop and port to be added.
427
428 The --ecmp-symmetric-reply option makes it so that traffic that
429 arrives over an ECMP route will have its reply traffic sent out
430 over that same route. Setting --ecmp-symmetric-reply implies
431 --ecmp so it is not necessary to set both.
432
433 --bfd option is used to link a BFD session to the OVN route. If
434 the BFD session UUID is provided, it will be used for the OVN
435 route otherwise the next-hop will be used to perform a lookup in
436 the OVN BFD table. If the lookup fails and port is specified, a
437 new entry in the BFD table will be created using the nexthop as
438 dst_ip and port as logical_port.
439
440 It is an error if a route with prefix and POLICY already exists,
441 unless --may-exist, --ecmp, or --ecmp-symmetric-reply is speci‐
442 fied. If --may-exist is specified but not --ecmp or --ecmp-sym‐
443 metric-reply, the existed route will be updated with the new
444 nexthop and port. If --ecmp or --ecmp-symmetric-reply is speci‐
445 fied, a new route will be added, regardless of the existed
446 route., which is useful when adding ECMP routes, i.e. routes
447 with same POLICY and prefix but different nexthop and port.
448
449 [--if-exists] [--policy=POLICY] lr-route-del router [prefix [nexthop
450 [port]]]
451 Deletes routes from router. If only router is supplied, all the
452 routes from the logical router are deleted. If POLICY, prefix,
453 nexthop and/or port are also specified, then all the routes that
454 match the conditions will be deleted from the logical router.
455
456 It is an error if there is no matching route entry, unless
457 --if-exists is specified.
458
459 lr-route-list router
460 Lists the routes on router.
461
463 [--may-exist]lr-policy-add router priority match action [nexthop[,nex‐
464 thop,...]] [options key=value]]
465 Add Policy to router which provides a way to configure per‐
466 mit/deny and reroute policies on the router. Permit/deny poli‐
467 cies are similar to OVN ACLs, but exist on the logical-router.
468 Reroute policies are needed for service-insertion and service-
469 chaining. nexthop is an optional parameter. It needs to be pro‐
470 vided only when action is reroute. Multiple nexthops can be
471 specified for ECMP routing. A policy is uniquely identified by
472 priority and match. Multiple policies can have the same prior‐
473 ity. options sets the router policy options as key-value pair.
474 The supported option is : pkt_mark.
475
476 If --may-exist is specified, adding a duplicated routing policy
477 with the same priority and match string is not really created.
478 Without --may-exist, adding a duplicated routing policy results
479 in error.
480
481 The following example shows a policy to lr1, which will drop
482 packets from192.168.100.0/24.
483
484 lr-policy-add lr1 100 ip4.src == 192.168.100.0/24 drop.
485
486 lr-policy-add lr1 100 ip4.src == 192.168.100.0/24 allow
487 pkt_mark=100 .
488
489 [--if-exists] lr-policy-del router [{priority | uuid} [match]]
490 Deletes polices from router. If only router is supplied, all the
491 polices from the logical router are deleted. If priority and/or
492 match are also specified, then all the polices that match the
493 conditions will be deleted from the logical router.
494
495 If router and uuid are supplied, then the policy with sepcified
496 uuid is deleted. It is an error if uuid does not exist, unless
497 --if-exists is specified.
498
499 lr-policy-list router
500 Lists the polices on router.
501
503 [--may-exist] [--stateless]lr-nat-add router type external_ip logi‐
504 cal_ip [logical_port external_mac]
505 Adds the specified NAT to router. The type must be one of snat,
506 dnat, or dnat_and_snat. The external_ip is an IPv4 address. The
507 logical_ip is an IPv4 network (e.g 192.168.1.0/24) or an IPv4
508 address. The logical_port and external_mac are only accepted
509 when router is a distributed router (rather than a gateway
510 router) and type is dnat_and_snat. The logical_port is the name
511 of an existing logical switch port where the logical_ip resides.
512 The external_mac is an Ethernet address. The --stateless
513
514 When --stateless is specified then it implies that we will be
515 not use connection tracker, i.e internal ip and external ip are
516 1:1 mapped. This implies that --stateless is applicable only to
517 dnat_and_snat type NAT rules. An external ip with --stateless
518 NAT cannot be shared with any other NAT rule.
519
520 When type is dnat, the externally visible IP address external_ip
521 is DNATted to the IP address logical_ip in the logical space.
522
523 When type is snat, IP packets with their source IP address that
524 either matches the IP address in logical_ip or is in the network
525 provided by logical_ip is SNATed into the IP address in exter‐
526 nal_ip.
527
528 When type is dnat_and_snat, the externally visible IP address
529 external_ip is DNATted to the IP address logical_ip in the logi‐
530 cal space. In addition, IP packets with the source IP address
531 that matches logical_ip is SNATed into the IP address in exter‐
532 nal_ip.
533
534 When the logical_port and external_mac are specified, the NAT
535 rule will be programmed on the chassis where the logical_port
536 resides. This includes ARP replies for the external_ip, which
537 return the value of external_mac. All packets transmitted with
538 source IP address equal to external_ip will be sent using the
539 external_mac.
540
541 It is an error if a NAT already exists with the same values of
542 router, type, external_ip, and logical_ip, unless --may-exist is
543 specified. When --may-exist, logical_port, and external_mac are
544 all specified, the existing values of logical_port and exter‐
545 nal_mac are overwritten.
546
547 [--if-exists] lr-nat-del router [type [ip]]
548 Deletes NATs from router. If only router is supplied, all the
549 NATs from the logical router are deleted. If type is also speci‐
550 fied, then all the NATs that match the type will be deleted from
551 the logical router. If all the fields are given, then a single
552 NAT rule that matches all the fields will be deleted. When type
553 is snat, the ip should be logical_ip. When type is dnat or
554 dnat_and_snat, the ip shoud be external_ip.
555
556 It is an error if ip is specified and there is no matching NAT
557 entry, unless --if-exists is specified.
558
559 lr-nat-list router
560 Lists the NATs on router.
561
563 [--may-exist | --add-duplicate | --reject | --event] lb-add lb vip ips
564 [protocol]
565 Creates a new load balancer named lb with the provided vip and
566 ips or adds the vip to an existing lb. vip should be a virtual
567 IP address (or an IP address and a port number with : as a sepa‐
568 rator). Examples for vip are 192.168.1.4, fd0f::1, and
569 192.168.1.5:8080. ips should be comma separated IP endpoints (or
570 comma separated IP addresses and port numbers with : as a sepa‐
571 rator). ips must be the same address family as vip. Examples for
572 ips are 10.0.0.1,10.0.0.2or [fdef::1]:8800,[fdef::2]:8800.
573
574 The optional argument protocol must be either tcp or udp. This
575 argument is useful when a port number is provided as part of the
576 vip. If the protocol is unspecified and a port number is pro‐
577 vided as part of the vip, OVN assumes the protocol to be tcp.
578
579 It is an error if the vip already exists in the load balancer
580 named lb, unless --may-exist is specified. With --add-duplicate,
581 the command really creates a new load balancer with a duplicate
582 name.
583
584 If the load balancer is created with --reject option and it has
585 no active backends, a TCP reset segment (for tcp) or an ICMP
586 port unreachable packet (for all other kind of traffic) will be
587 sent whenever an incoming packet is received for this load-bal‐
588 ancer. Please note using --reject option will disable empty_lb
589 SB controller event for this load balancer.
590
591 If the load balancer is created with --event option and it has
592 no active backends, whenever the lb receives traffic, the event
593 is reported in the Controller_Event table in the SB db. Please
594 note --event option can’t be specified with --reject one.
595
596 The following example adds a load balancer.
597
598 lb-add lb0 30.0.0.10:80
599 192.168.10.10:80,192.168.10.20:80,192.168.10.30:80 udp
600
601 [--if-exists] lb-del lb [vip]
602 Deletes lb or the vip from lb. If vip is supplied, only the vip
603 will be deleted from the lb. If only the lb is supplied, the lb
604 will be deleted. It is an error if vip does not already exist in
605 lb, unless --if-exists is specified.
606
607 lb-list [lb]
608 Lists the LBs. If lb is also specified, then only the specified
609 lb will be listed.
610
611 [--may-exist] ls-lb-add switch lb
612 Adds the specified lb to switch. It is an error if a load bal‐
613 ancer named lb already exists in the switch, unless --may-exist
614 is specified.
615
616 [--if-exists] ls-lb-del switch [lb]
617 Removes lb from switch. If only switch is supplied, all the LBs
618 from the logical switch are removed. If lb is also specified,
619 then only the lb will be removed from the logical switch. It is
620 an error if lb does not exist in the switch, unless --if-exists
621 is specified.
622
623 ls-lb-list switch
624 Lists the LBs for the given switch.
625
626 [--may-exist] lr-lb-add router lb
627 Adds the specified lb to router. It is an error if a load bal‐
628 ancer named lb already exists in the router, unless --may-exist
629 is specified.
630
631 [--if-exists] lr-lb-del router [lb]
632 Removes lb from router. If only router is supplied, all the LBs
633 from the logical router are removed. If lb is also specified,
634 then only the lb will be removed from the logical router. It is
635 an error if lb does not exist in the router, unless --if-exists
636 is specified.
637
638 lr-lb-list router
639 Lists the LBs for the given router.
640
642 dhcp-options-create cidr [key=value]
643 Creates a new DHCP Options entry in the DHCP_Options table with
644 the specified cidr and optional external-ids.
645
646 dhcp-options-list
647 Lists the DHCP Options entries.
648
649 dhcp-options-del dhcp-option
650 Deletes the DHCP Options entry referred by dhcp-option UUID.
651
652 dhcp-options-set-options dhcp-option [key=value]...
653 Set the DHCP Options for the dhcp-option UUID.
654
655 dhcp-options-get-options dhcp-option
656 Lists the DHCP Options for the dhcp-option UUID.
657
659 pg-add group [port]...
660 Creates a new port group in the Port_Group table named group
661 with optional ports added to the group.
662
663 pg-set-ports group port...
664 Sets ports on the port group named group. It is an error if
665 group does not exist.
666
667 pg-del group
668 Deletes port group group. It is an error if group does not ex‐
669 ist.
670
672 ha-chassis-group-add group
673 Creates a new HA chassis group in the HA_Chassis_Group table
674 named group.
675
676 ha-chassis-group-del group
677 Deletes the HA chassis group group. It is an error if group does
678 not exist.
679
680 ha-chassis-group-list
681 Lists the HA chassis group group along with the HA chassis if
682 any associated with it.
683
684 ha-chassis-group-add-chassis group chassis priority
685 Adds a new HA chassis chassis to the HA Chassis group group with
686 the specified priority. If the chassis already exists, then the
687 priority is updated. The chassis should be the name of the chas‐
688 sis in the OVN_Southbound.
689
690 ha-chassis-group-remove-chassis group chassis
691 Removes the HA chassis chassis from the HA chassis group group.
692 It is an error if chassis does not exist.
693
695 These commands query and modify the contents of ovsdb tables. They are
696 a slight abstraction of the ovsdb interface and as such they operate at
697 a lower level than other ovn-nbctl commands.
698
699 Identifying Tables, Records, and Columns
700
701 Each of these commands has a table parameter to identify a table within
702 the database. Many of them also take a record parameter that identifies
703 a particular record within a table. The record parameter may be the
704 UUID for a record, which may be abbreviated to its first 4 (or more)
705 hex digits, as long as that is unique. Many tables offer additional
706 ways to identify records. Some commands also take column parameters
707 that identify a particular field within the records in a table.
708
709 For a list of tables and their columns, see ovn-nb(5) or see the table
710 listing from the --help option.
711
712 Record names must be specified in full and with correct capitalization,
713 except that UUIDs may be abbreviated to their first 4 (or more) hex
714 digits, as long as that is unique within the table. Names of tables and
715 columns are not case-sensitive, and - and _ are treated interchange‐
716 ably. Unique abbreviations of table and column names are acceptable,
717 e.g. d or dhcp is sufficient to identify the DHCP_Options table.
718
719 Database Values
720
721 Each column in the database accepts a fixed type of data. The currently
722 defined basic types, and their representations, are:
723
724 integer
725 A decimal integer in the range -2**63 to 2**63-1, inclu‐
726 sive.
727
728 real A floating-point number.
729
730 Boolean
731 True or false, written true or false, respectively.
732
733 string An arbitrary Unicode string, except that null bytes are
734 not allowed. Quotes are optional for most strings that
735 begin with an English letter or underscore and consist
736 only of letters, underscores, hyphens, and periods. How‐
737 ever, true and false and strings that match the syntax of
738 UUIDs (see below) must be enclosed in double quotes to
739 distinguish them from other basic types. When double
740 quotes are used, the syntax is that of strings in JSON,
741 e.g. backslashes may be used to escape special charac‐
742 ters. The empty string must be represented as a pair of
743 double quotes ("").
744
745 UUID Either a universally unique identifier in the style of
746 RFC 4122, e.g. f81d4fae-7dec-11d0-a765-00a0c91e6bf6, or
747 an @name defined by a get or create command within the
748 same ovs-vsctl invocation.
749
750 Multiple values in a single column may be separated by spaces or a sin‐
751 gle comma. When multiple values are present, duplicates are not al‐
752 lowed, and order is not important. Conversely, some database columns
753 can have an empty set of values, represented as [], and square brackets
754 may optionally enclose other non-empty sets or single values as well.
755
756 A few database columns are ``maps’’ of key-value pairs, where the key
757 and the value are each some fixed database type. These are specified in
758 the form key=value, where key and value follow the syntax for the col‐
759 umn’s key type and value type, respectively. When multiple pairs are
760 present (separated by spaces or a comma), duplicate keys are not al‐
761 lowed, and again the order is not important. Duplicate values are al‐
762 lowed. An empty map is represented as {}. Curly braces may optionally
763 enclose non-empty maps as well (but use quotes to prevent the shell
764 from expanding other-config={0=x,1=y} into other-config=0=x other-con‐
765 fig=1=y, which may not have the desired effect).
766
767 Database Command Syntax
768
769 [--if-exists] [--columns=column[,column]...] list table
770 [record]...
771 Lists the data in each specified record. If no records
772 are specified, lists all the records in table.
773
774 If --columns is specified, only the requested columns are
775 listed, in the specified order. Otherwise, all columns
776 are listed, in alphabetical order by column name.
777
778 Without --if-exists, it is an error if any specified
779 record does not exist. With --if-exists, the command ig‐
780 nores any record that does not exist, without producing
781 any output.
782
783 [--columns=column[,column]...] find table [col‐
784 umn[:key]=value]...
785 Lists the data in each record in table whose column
786 equals value or, if key is specified, whose column con‐
787 tains a key with the specified value. The following oper‐
788 ators may be used where = is written in the syntax sum‐
789 mary:
790
791 = != < > <= >=
792 Selects records in which column[:key] equals, does
793 not equal, is less than, is greater than, is less
794 than or equal to, or is greater than or equal to
795 value, respectively.
796
797 Consider column[:key] and value as sets of ele‐
798 ments. Identical sets are considered equal. Other‐
799 wise, if the sets have different numbers of ele‐
800 ments, then the set with more elements is consid‐
801 ered to be larger. Otherwise, consider a element
802 from each set pairwise, in increasing order within
803 each set. The first pair that differs determines
804 the result. (For a column that contains key-value
805 pairs, first all the keys are compared, and values
806 are considered only if the two sets contain iden‐
807 tical keys.)
808
809 {=} {!=}
810 Test for set equality or inequality, respectively.
811
812 {<=} Selects records in which column[:key] is a subset
813 of value. For example, flood-vlans{<=}1,2 selects
814 records in which the flood-vlans column is the
815 empty set or contains 1 or 2 or both.
816
817 {<} Selects records in which column[:key] is a proper
818 subset of value. For example, flood-vlans{<}1,2
819 selects records in which the flood-vlans column is
820 the empty set or contains 1 or 2 but not both.
821
822 {>=} {>}
823 Same as {<=} and {<}, respectively, except that
824 the relationship is reversed. For example,
825 flood-vlans{>=}1,2 selects records in which the
826 flood-vlans column contains both 1 and 2.
827
828 The following operators are available only in Open
829 vSwitch 2.16 and later:
830
831 {in} Selects records in which every element in col‐
832 umn[:key] is also in value. (This is the same as
833 {<=}.)
834
835 {not-in}
836 Selects records in which every element in col‐
837 umn[:key] is not in value.
838
839 For arithmetic operators (= != < > <= >=), when key is
840 specified but a particular record’s column does not con‐
841 tain key, the record is always omitted from the results.
842 Thus, the condition other-config:mtu!=1500 matches
843 records that have a mtu key whose value is not 1500, but
844 not those that lack an mtu key.
845
846 For the set operators, when key is specified but a par‐
847 ticular record’s column does not contain key, the compar‐
848 ison is done against an empty set. Thus, the condition
849 other-config:mtu{!=}1500 matches records that have a mtu
850 key whose value is not 1500 and those that lack an mtu
851 key.
852
853 Don’t forget to escape < or > from interpretation by the
854 shell.
855
856 If --columns is specified, only the requested columns are
857 listed, in the specified order. Otherwise all columns are
858 listed, in alphabetical order by column name.
859
860 The UUIDs shown for rows created in the same ovs-vsctl
861 invocation will be wrong.
862
863 [--if-exists] [--id=@name] get table record [column[:key]]...
864 Prints the value of each specified column in the given
865 record in table. For map columns, a key may optionally be
866 specified, in which case the value associated with key in
867 the column is printed, instead of the entire map.
868
869 Without --if-exists, it is an error if record does not
870 exist or key is specified, if key does not exist in
871 record. With --if-exists, a missing record yields no out‐
872 put and a missing key prints a blank line.
873
874 If @name is specified, then the UUID for record may be
875 referred to by that name later in the same ovs-vsctl in‐
876 vocation in contexts where a UUID is expected.
877
878 Both --id and the column arguments are optional, but usu‐
879 ally at least one or the other should be specified. If
880 both are omitted, then get has no effect except to verify
881 that record exists in table.
882
883 --id and --if-exists cannot be used together.
884
885 [--if-exists] set table record column[:key]=value...
886 Sets the value of each specified column in the given
887 record in table to value. For map columns, a key may op‐
888 tionally be specified, in which case the value associated
889 with key in that column is changed (or added, if none ex‐
890 ists), instead of the entire map.
891
892 Without --if-exists, it is an error if record does not
893 exist. With --if-exists, this command does nothing if
894 record does not exist.
895
896 [--if-exists] add table record column [key=]value...
897 Adds the specified value or key-value pair to column in
898 record in table. If column is a map, then key is re‐
899 quired, otherwise it is prohibited. If key already exists
900 in a map column, then the current value is not replaced
901 (use the set command to replace an existing value).
902
903 Without --if-exists, it is an error if record does not
904 exist. With --if-exists, this command does nothing if
905 record does not exist.
906
907 [--if-exists] remove table record column value...
908
909 [--if-exists] remove table record column key...
910
911 [--if-exists] remove table record column key=value...
912 Removes the specified values or key-value pairs from col‐
913 umn in record in table. The first form applies to columns
914 that are not maps: each specified value is removed from
915 the column. The second and third forms apply to map col‐
916 umns: if only a key is specified, then any key-value pair
917 with the given key is removed, regardless of its value;
918 if a value is given then a pair is removed only if both
919 key and value match.
920
921 It is not an error if the column does not contain the
922 specified key or value or pair.
923
924 Without --if-exists, it is an error if record does not
925 exist. With --if-exists, this command does nothing if
926 record does not exist.
927
928 [--if-exists] clear table record column...
929 Sets each column in record in table to the empty set or
930 empty map, as appropriate. This command applies only to
931 columns that are allowed to be empty.
932
933 Without --if-exists, it is an error if record does not
934 exist. With --if-exists, this command does nothing if
935 record does not exist.
936
937 [--id=@name] create table column[:key]=value...
938 Creates a new record in table and sets the initial values
939 of each column. Columns not explicitly set will receive
940 their default values. Outputs the UUID of the new row.
941
942 If @name is specified, then the UUID for the new row may
943 be referred to by that name elsewhere in the same \*(PN
944 invocation in contexts where a UUID is expected. Such
945 references may precede or follow the create command.
946
947 Caution (ovs-vsctl as example)
948 Records in the Open vSwitch database are signifi‐
949 cant only when they can be reached directly or in‐
950 directly from the Open_vSwitch table. Except for
951 records in the QoS or Queue tables, records that
952 are not reachable from the Open_vSwitch table are
953 automatically deleted from the database. This
954 deletion happens immediately, without waiting for
955 additional ovs-vsctl commands or other database
956 activity. Thus, a create command must generally be
957 accompanied by additional commands within the same
958 ovs-vsctl invocation to add a chain of references
959 to the newly created record from the top-level
960 Open_vSwitch record. The EXAMPLES section gives
961 some examples that show how to do this.
962
963 [--if-exists] destroy table record...
964 Deletes each specified record from table. Unless --if-ex‐
965 ists is specified, each records must exist.
966
967 --all destroy table
968 Deletes all records from the table.
969
970 Caution (ovs-vsctl as example)
971 The destroy command is only useful for records in
972 the QoS or Queue tables. Records in other tables
973 are automatically deleted from the database when
974 they become unreachable from the Open_vSwitch ta‐
975 ble. This means that deleting the last reference
976 to a record is sufficient for deleting the record
977 itself. For records in these tables, destroy is
978 silently ignored. See the EXAMPLES section below
979 for more information.
980
981 wait-until table record [column[:key]=value]...
982 Waits until table contains a record named record whose
983 column equals value or, if key is specified, whose column
984 contains a key with the specified value. This command
985 supports the same operators and semantics described for
986 the find command above.
987
988 If no column[:key]=value arguments are given, this com‐
989 mand waits only until record exists. If more than one
990 such argument is given, the command waits until all of
991 them are satisfied.
992
993 Caution (ovs-vsctl as example)
994 Usually wait-until should be placed at the begin‐
995 ning of a set of ovs-vsctl commands. For example,
996 wait-until bridge br0 -- get bridge br0 data‐
997 path_id waits until a bridge named br0 is created,
998 then prints its datapath_id column, whereas get
999 bridge br0 datapath_id -- wait-until bridge br0
1000 will abort if no bridge named br0 exists when
1001 ovs-vsctl initially connects to the database.
1002
1003 Consider specifying --timeout=0 along with --wait-until,
1004 to prevent ovs-vsctl from terminating after waiting only
1005 at most 5 seconds.
1006
1007 comment [arg]...
1008 This command has no effect on behavior, but any database
1009 log record created by the command will include the com‐
1010 mand and its arguments.
1011
1013 sync Ordinarily, --wait=sb or --wait=hv only waits for changes by the
1014 current ovn-nbctl invocation to take effect. This means that, if
1015 none of the commands supplied to ovn-nbctl change the database,
1016 then the command does not wait at all. With the sync command,
1017 however, ovn-nbctl waits even for earlier changes to the data‐
1018 base to propagate down to the southbound database or all of the
1019 OVN chassis, according to the argument to --wait.
1020
1022 get-connection
1023 Prints the configured connection(s).
1024
1025 del-connection
1026 Deletes the configured connection(s).
1027
1028 [--inactivity-probe=msecs] set-connection target...
1029 Sets the configured manager target or targets. Use --inactiv‐
1030 ity-probe=msecs to override the default idle connection inactiv‐
1031 ity probe time. Use 0 to disable inactivity probes.
1032
1034 get-ssl
1035 Prints the SSL configuration.
1036
1037 del-ssl
1038 Deletes the current SSL configuration.
1039
1040 [--bootstrap] set-ssl private-key certificate ca-cert [ssl-protocol-
1041 list [ssl-cipher-list]]
1042 Sets the SSL configuration.
1043
1045 When it is invoked in the most ordinary way, ovn-nbctl connects to an
1046 OVSDB server that hosts the northbound database, retrieves a partial
1047 copy of the database that is complete enough to do its work, sends a
1048 transaction request to the server, and receives and processes the
1049 server’s reply. In common interactive use, this is fine, but if the
1050 database is large, the step in which ovn-nbctl retrieves a partial copy
1051 of the database can take a long time, which yields poor performance
1052 overall.
1053
1054 To improve performance in such a case, ovn-nbctl offers a "daemon
1055 mode," in which the user first starts ovn-nbctl running in the back‐
1056 ground and afterward uses the daemon to execute operations. Over sev‐
1057 eral ovn-nbctl command invocations, this performs better overall be‐
1058 cause it retrieves a copy of the database only once at the beginning,
1059 not once per program run.
1060
1061 Use the --detach option to start an ovn-nbctl daemon. With this option,
1062 ovn-nbctl prints the name of a control socket to stdout. The client
1063 should save this name in environment variable OVN_NB_DAEMON. Under the
1064 Bourne shell this might be done like this:
1065
1066 export OVN_NB_DAEMON=$(ovn-nbctl --pidfile --detach)
1067
1068
1069 When OVN_NB_DAEMON is set, ovn-nbctl automatically and transparently
1070 uses the daemon to execute its commands.
1071
1072 When the daemon is no longer needed, kill it and unset the environment
1073 variable, e.g.:
1074
1075 kill $(cat $OVN_RUNDIR/ovn-nbctl.pid)
1076 unset OVN_NB_DAEMON
1077
1078
1079 When using daemon mode, an alternative to the OVN_NB_DAEMON environment
1080 variable is to specify a path for the Unix socket. When starting the
1081 ovn-nbctl daemon, specify the -u option with a full path to the loca‐
1082 tion of the socket file. Here is an exmple:
1083
1084 ovn-nbctl --detach -u /tmp/mysock.ctl
1085
1086
1087 Then to connect to the running daemon, use the -u option with the full
1088 path to the socket created when the daemon was started:
1089
1090 ovn-nbctl -u /tmp/mysock.ctl show
1091
1092
1093 Daemon mode is experimental.
1094
1095 Daemon Commands
1096 Daemon mode is internally implemented using the same mechanism used by
1097 ovs-appctl. One may also use ovs-appctl directly with the following
1098 commands:
1099
1100 run [options] command [arg...] [-- [options] command [arg...]
1101 ...]
1102 Instructs the daemon process to run one or more ovn-nbctl
1103 commands described above and reply with the results of
1104 running these commands. Accepts the --no-wait, --wait,
1105 --timeout, --dry-run, --oneline, and the options de‐
1106 scribed under Table Formatting Options in addition to the
1107 the command-specific options.
1108
1109 exit Causes ovn-nbctl to gracefully terminate.
1110
1112 --no-wait | --wait=none
1113 --wait=sb
1114 --wait=hv
1115 These options control whether and how ovn-nbctl waits for the OVN
1116 system to become up-to-date with changes made in an ovn-nbctl in‐
1117 vocation.
1118
1119 By default, or if --no-wait or --wait=none, ovn-nbctl exits imme‐
1120 diately after confirming that changes have been committed to the
1121 northbound database, without waiting.
1122
1123 With --wait=sb, before ovn-nbctl exits, it waits for ovn-northd to
1124 bring the southbound database up-to-date with the northbound data‐
1125 base updates.
1126
1127 With --wait=hv, before ovn-nbctl exits, it additionally waits for
1128 all OVN chassis (hypervisors and gateways) to become up-to-date
1129 with the northbound database updates. (This can become an indefi‐
1130 nite wait if any chassis is malfunctioning.)
1131
1132 Ordinarily, --wait=sb or --wait=hv only waits for changes by the
1133 current ovn-nbctl invocation to take effect. This means that, if
1134 none of the commands supplied to ovn-nbctl change the database,
1135 then the command does not wait at all. Use the sync command to
1136 override this behavior.
1137
1138 --print-wait-time
1139 When --wait is specified, the option --print-wait-time can be used
1140 to print the time spent on waiting, depending on the value speci‐
1141 fied in --wait option. If --wait=sb is specified, it prints "ovn-
1142 northd delay before processing", which is the time between the
1143 Northbound DB update by the command and the moment when
1144 ovn-northd starts processing the update, and "ovn-northd comple‐
1145 tion", which is the time between the Northbound DB update and the
1146 moment when ovn-northd completes the Southbound DB updating suc‐
1147 cessfully. If --wait=hv is specified, in addition to the above in‐
1148 formation, it also prints "ovn-controller(s) completion", which is
1149 the time between the Northbound DB update and the moment when the
1150 slowest hypervisor finishes processing the update.
1151
1152 --db database
1153 The OVSDB database remote to contact. If the OVN_NB_DB environment
1154 variable is set, its value is used as the default. Otherwise, the
1155 default is unix:/ovnnb_db.sock, but this default is unlikely to be
1156 useful outside of single-machine OVN test environments.
1157
1158 --leader-only
1159 --no-leader-only
1160 By default, or with --leader-only, when the database server is a
1161 clustered database, ovn-nbctl will avoid servers other than the
1162 cluster leader. This ensures that any data that ovn-nbctl reads
1163 and reports is up-to-date. With --no-leader-only, ovn-nbctl will
1164 use any server in the cluster, which means that for read-only
1165 transactions it can report and act on stale data (transactions
1166 that modify the database are always serialized even with
1167 --no-leader-only). Refer to Understanding Cluster Consistency in
1168 ovsdb(7) for more information.
1169
1170 --shuffle-remotes
1171 --no-shuffle-remotes
1172 By default, or with --shuffle-remotes, when there are multiple re‐
1173 motes specified in the OVSDB connection string specified by --db
1174 or the OVN_NB_DB environment variable, the order of the remotes
1175 will be shuffled before the client tries to connect. The remotes
1176 will be shuffled only once to a new order before the first connec‐
1177 tion attempt. The following retries, if any, will follow the same
1178 new order. The default behavior is to make sure clients of a clus‐
1179 tered database can distribute evenly to all memembers of the clus‐
1180 ter. With --no-shuffle-remotes, ovn-nbctl will use the original
1181 order specified in the connection string to connect. This allows
1182 user to specify the preferred order, which is particularly useful
1183 for testing.
1184
1185 OVN_NBCTL_OPTIONS
1186 User can set one or more OVN_NBCTL_OPTIONS options in environment
1187 variable. Under the Bourne shell this might be done like this:
1188
1189 OVN_NBCTL_OPTIONS="--db=unix:nb1.ovsdb --no-leader-only"
1190
1191
1192 When OVN_NBCTL_OPTIONS is set, ovn-nbctl automatically and trans‐
1193 parently uses the environment variable to execute its commands.
1194 However user can still over-ride environment options by passing
1195 different in cli.
1196
1197 When the environment variable is no longer needed, unset it, e.g.:
1198
1199 unset OVN_NBCTL_OPTIONS
1200
1201
1202 Daemon Options
1203 --pidfile[=pidfile]
1204 Causes a file (by default, program.pid) to be created indicating
1205 the PID of the running process. If the pidfile argument is not
1206 specified, or if it does not begin with /, then it is created in
1207 .
1208
1209 If --pidfile is not specified, no pidfile is created.
1210
1211 --overwrite-pidfile
1212 By default, when --pidfile is specified and the specified pid‐
1213 file already exists and is locked by a running process, the dae‐
1214 mon refuses to start. Specify --overwrite-pidfile to cause it to
1215 instead overwrite the pidfile.
1216
1217 When --pidfile is not specified, this option has no effect.
1218
1219 --detach
1220 Runs this program as a background process. The process forks,
1221 and in the child it starts a new session, closes the standard
1222 file descriptors (which has the side effect of disabling logging
1223 to the console), and changes its current directory to the root
1224 (unless --no-chdir is specified). After the child completes its
1225 initialization, the parent exits.
1226
1227 --monitor
1228 Creates an additional process to monitor this program. If it
1229 dies due to a signal that indicates a programming error (SIGA‐
1230 BRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE, SIGSEGV, SIGXCPU,
1231 or SIGXFSZ) then the monitor process starts a new copy of it. If
1232 the daemon dies or exits for another reason, the monitor process
1233 exits.
1234
1235 This option is normally used with --detach, but it also func‐
1236 tions without it.
1237
1238 --no-chdir
1239 By default, when --detach is specified, the daemon changes its
1240 current working directory to the root directory after it de‐
1241 taches. Otherwise, invoking the daemon from a carelessly chosen
1242 directory would prevent the administrator from unmounting the
1243 file system that holds that directory.
1244
1245 Specifying --no-chdir suppresses this behavior, preventing the
1246 daemon from changing its current working directory. This may be
1247 useful for collecting core files, since it is common behavior to
1248 write core dumps into the current working directory and the root
1249 directory is not a good directory to use.
1250
1251 This option has no effect when --detach is not specified.
1252
1253 --no-self-confinement
1254 By default this daemon will try to self-confine itself to work
1255 with files under well-known directories determined at build
1256 time. It is better to stick with this default behavior and not
1257 to use this flag unless some other Access Control is used to
1258 confine daemon. Note that in contrast to other access control
1259 implementations that are typically enforced from kernel-space
1260 (e.g. DAC or MAC), self-confinement is imposed from the user-
1261 space daemon itself and hence should not be considered as a full
1262 confinement strategy, but instead should be viewed as an addi‐
1263 tional layer of security.
1264
1265 --user=user:group
1266 Causes this program to run as a different user specified in
1267 user:group, thus dropping most of the root privileges. Short
1268 forms user and :group are also allowed, with current user or
1269 group assumed, respectively. Only daemons started by the root
1270 user accepts this argument.
1271
1272 On Linux, daemons will be granted CAP_IPC_LOCK and
1273 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
1274 that interact with a datapath, such as ovs-vswitchd, will be
1275 granted three additional capabilities, namely CAP_NET_ADMIN,
1276 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
1277 apply even if the new user is root.
1278
1279 On Windows, this option is not currently supported. For security
1280 reasons, specifying this option will cause the daemon process
1281 not to start.
1282
1284 -v[spec]
1285 --verbose=[spec]
1286 Sets logging levels. Without any spec, sets the log level for ev‐
1287 ery module and destination to dbg. Otherwise, spec is a list of
1288 words separated by spaces or commas or colons, up to one from each
1289 category below:
1290
1291 • A valid module name, as displayed by the vlog/list command
1292 on ovs-appctl(8), limits the log level change to the speci‐
1293 fied module.
1294
1295 • syslog, console, or file, to limit the log level change to
1296 only to the system log, to the console, or to a file, re‐
1297 spectively. (If --detach is specified, the daemon closes
1298 its standard file descriptors, so logging to the console
1299 will have no effect.)
1300
1301 On Windows platform, syslog is accepted as a word and is
1302 only useful along with the --syslog-target option (the word
1303 has no effect otherwise).
1304
1305 • off, emer, err, warn, info, or dbg, to control the log
1306 level. Messages of the given severity or higher will be
1307 logged, and messages of lower severity will be filtered
1308 out. off filters out all messages. See ovs-appctl(8) for a
1309 definition of each log level.
1310
1311 Case is not significant within spec.
1312
1313 Regardless of the log levels set for file, logging to a file will
1314 not take place unless --log-file is also specified (see below).
1315
1316 For compatibility with older versions of OVS, any is accepted as a
1317 word but has no effect.
1318
1319 -v
1320 --verbose
1321 Sets the maximum logging verbosity level, equivalent to --ver‐
1322 bose=dbg.
1323
1324 -vPATTERN:destination:pattern
1325 --verbose=PATTERN:destination:pattern
1326 Sets the log pattern for destination to pattern. Refer to ovs-ap‐
1327 pctl(8) for a description of the valid syntax for pattern.
1328
1329 -vFACILITY:facility
1330 --verbose=FACILITY:facility
1331 Sets the RFC5424 facility of the log message. facility can be one
1332 of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
1333 ftp, ntp, audit, alert, clock2, local0, local1, local2, local3,
1334 local4, local5, local6 or local7. If this option is not specified,
1335 daemon is used as the default for the local system syslog and lo‐
1336 cal0 is used while sending a message to the target provided via
1337 the --syslog-target option.
1338
1339 --log-file[=file]
1340 Enables logging to a file. If file is specified, then it is used
1341 as the exact name for the log file. The default log file name used
1342 if file is omitted is /var/log/ovn/program.log.
1343
1344 --syslog-target=host:port
1345 Send syslog messages to UDP port on host, in addition to the sys‐
1346 tem syslog. The host must be a numerical IP address, not a host‐
1347 name.
1348
1349 --syslog-method=method
1350 Specify method as how syslog messages should be sent to syslog
1351 daemon. The following forms are supported:
1352
1353 • libc, to use the libc syslog() function. Downside of using
1354 this options is that libc adds fixed prefix to every mes‐
1355 sage before it is actually sent to the syslog daemon over
1356 /dev/log UNIX domain socket.
1357
1358 • unix:file, to use a UNIX domain socket directly. It is pos‐
1359 sible to specify arbitrary message format with this option.
1360 However, rsyslogd 8.9 and older versions use hard coded
1361 parser function anyway that limits UNIX domain socket use.
1362 If you want to use arbitrary message format with older
1363 rsyslogd versions, then use UDP socket to localhost IP ad‐
1364 dress instead.
1365
1366 • udp:ip:port, to use a UDP socket. With this method it is
1367 possible to use arbitrary message format also with older
1368 rsyslogd. When sending syslog messages over UDP socket ex‐
1369 tra precaution needs to be taken into account, for example,
1370 syslog daemon needs to be configured to listen on the spec‐
1371 ified UDP port, accidental iptables rules could be inter‐
1372 fering with local syslog traffic and there are some secu‐
1373 rity considerations that apply to UDP sockets, but do not
1374 apply to UNIX domain sockets.
1375
1376 • null, to discard all messages logged to syslog.
1377
1378 The default is taken from the OVS_SYSLOG_METHOD environment vari‐
1379 able; if it is unset, the default is libc.
1380
1382 These options control the format of output from the list and find com‐
1383 mands.
1384
1385 -f format
1386 --format=format
1387 Sets the type of table formatting. The following types of
1388 format are available:
1389
1390 table 2-D text tables with aligned columns.
1391
1392 list (default)
1393 A list with one column per line and rows separated
1394 by a blank line.
1395
1396 html HTML tables.
1397
1398 csv Comma-separated values as defined in RFC 4180.
1399
1400 json JSON format as defined in RFC 4627. The output is a
1401 sequence of JSON objects, each of which corresponds
1402 to one table. Each JSON object has the following
1403 members with the noted values:
1404
1405 caption
1406 The table’s caption. This member is omitted
1407 if the table has no caption.
1408
1409 headings
1410 An array with one element per table column.
1411 Each array element is a string giving the
1412 corresponding column’s heading.
1413
1414 data An array with one element per table row. Each
1415 element is also an array with one element per
1416 table column. The elements of this second-
1417 level array are the cells that constitute the
1418 table. Cells that represent OVSDB data or
1419 data types are expressed in the format de‐
1420 scribed in the OVSDB specification; other
1421 cells are simply expressed as text strings.
1422
1423 -d format
1424 --data=format
1425 Sets the formatting for cells within output tables unless
1426 the table format is set to json, in which case json format‐
1427 ting is always used when formatting cells. The following
1428 types of format are available:
1429
1430 string (default)
1431 The simple format described in the Database Values
1432 section of ovs-vsctl(8).
1433
1434 bare The simple format with punctuation stripped off: []
1435 and {} are omitted around sets, maps, and empty col‐
1436 umns, items within sets and maps are space-sepa‐
1437 rated, and strings are never quoted. This format may
1438 be easier for scripts to parse.
1439
1440 json The RFC 4627 JSON format as described above.
1441
1442 --no-headings
1443 This option suppresses the heading row that otherwise ap‐
1444 pears in the first row of table output.
1445
1446 --pretty
1447 By default, JSON in output is printed as compactly as pos‐
1448 sible. This option causes JSON in output to be printed in a
1449 more readable fashion. Members of objects and elements of
1450 arrays are printed one per line, with indentation.
1451
1452 This option does not affect JSON in tables, which is always
1453 printed compactly.
1454
1455 --bare
1456 Equivalent to --format=list --data=bare --no-headings.
1457
1458 PKI Options
1459 PKI configuration is required to use SSL for the connection to the
1460 database.
1461
1462 -p privkey.pem
1463 --private-key=privkey.pem
1464 Specifies a PEM file containing the private key used as
1465 identity for outgoing SSL connections.
1466
1467 -c cert.pem
1468 --certificate=cert.pem
1469 Specifies a PEM file containing a certificate that certi‐
1470 fies the private key specified on -p or --private-key to be
1471 trustworthy. The certificate must be signed by the certifi‐
1472 cate authority (CA) that the peer in SSL connections will
1473 use to verify it.
1474
1475 -C cacert.pem
1476 --ca-cert=cacert.pem
1477 Specifies a PEM file containing the CA certificate for ver‐
1478 ifying certificates presented to this program by SSL peers.
1479 (This may be the same certificate that SSL peers use to
1480 verify the certificate specified on -c or --certificate, or
1481 it may be a different one, depending on the PKI design in
1482 use.)
1483
1484 -C none
1485 --ca-cert=none
1486 Disables verification of certificates presented by SSL
1487 peers. This introduces a security risk, because it means
1488 that certificates cannot be verified to be those of known
1489 trusted hosts.
1490
1491 --bootstrap-ca-cert=cacert.pem
1492 When cacert.pem exists, this option has the same effect
1493 as -C or --ca-cert. If it does not exist, then the exe‐
1494 cutable will attempt to obtain the CA certificate from
1495 the SSL peer on its first SSL connection and save it to
1496 the named PEM file. If it is successful, it will immedi‐
1497 ately drop the connection and reconnect, and from then on
1498 all SSL connections must be authenticated by a certifi‐
1499 cate signed by the CA certificate thus obtained.
1500
1501 This option exposes the SSL connection to a man-in-the-
1502 middle attack obtaining the initial CA certificate, but
1503 it may be useful for bootstrapping.
1504
1505 This option is only useful if the SSL peer sends its CA
1506 certificate as part of the SSL certificate chain. The SSL
1507 protocol does not require the server to send the CA cer‐
1508 tificate.
1509
1510 This option is mutually exclusive with -C and --ca-cert.
1511
1512 Other Options
1513 -h
1514 --help
1515 Prints a brief help message to the console.
1516
1517 -V
1518 --version
1519 Prints version information to the console.
1520
1521
1522
1523OVN 21.03.1 ovn-nbctl ovn-nbctl(8)