1ovn-sbctl(8) OVN Manual ovn-sbctl(8)
2
6 ovn-sbctl - Open Virtual Network southbound db management utility
7
9 ovn-sbctl [options] command [arg...]
10
12 The ovn-sbctl program configures the OVN_Southbound database by provid‐
13 ing a high-level interface to its configuration database. See ovn-sb(5)
14 for comprehensive documentation of the database schema.
15 ovn-sbctl connects to an ovsdb-server process that maintains an
17 OVN_Southbound configuration database. Using this connection, it
18 queries and possibly applies changes to the database, depending on the
19 supplied commands.
20 ovn-sbctl can perform any number of commands in a single run, imple‐
22 mented as a single atomic transaction against the database.
23 The ovn-sbctl command line begins with global options (see OPTIONS be‐
25 low for details). The global options are followed by one or more com‐
26 mands. Each command should begin with -- by itself as a command-line
27 argument, to separate it from the following commands. (The -- before
28 the first command is optional.) The command itself starts with command-
29 specific options, if any, followed by the command name and any argu‐
30 ments.
31
33 When it is invoked in the most ordinary way, ovn-sbctl connects to an
34 OVSDB server that hosts the southbound database, retrieves a partial
35 copy of the database that is complete enough to do its work, sends a
36 transaction request to the server, and receives and processes the
37 server’s reply. In common interactive use, this is fine, but if the
38 database is large, the step in which ovn-sbctl retrieves a partial copy
39 of the database can take a long time, which yields poor performance
40 overall.
41 To improve performance in such a case, ovn-sbctl offers a "daemon
43 mode," in which the user first starts ovn-sbctl running in the back‐
44 ground and afterward uses the daemon to execute operations. Over sev‐
45 eral ovn-sbctl command invocations, this performs better overall be‐
46 cause it retrieves a copy of the database only once at the beginning,
47 not once per program run.
48 Use the --detach option to start an ovn-sbctl daemon. With this option,
50 ovn-sbctl prints the name of a control socket to stdout. The client
51 should save this name in environment variable OVN_SB_DAEMON. Under the
52 Bourne shell this might be done like this:
53 export OVN_SB_DAEMON=$(ovn-sbctl --pidfile --detach)
55 When OVN_SB_DAEMON is set, ovn-sbctl automatically and transparently
58 uses the daemon to execute its commands.
59 When the daemon is no longer needed, kill it and unset the environment
61 variable, e.g.:
62 kill $(cat $OVN_RUNDIR/ovn-sbctl.pid)
64 unset OVN_SB_DAEMON
65 When using daemon mode, an alternative to the OVN_SB_DAEMON environment
68 variable is to specify a path for the Unix socket. When starting the
69 ovn-sbctl daemon, specify the -u option with a full path to the loca‐
70 tion of the socket file. Here is an exmple:
71 ovn-sbctl --detach -u /tmp/mysock.ctl
73 Then to connect to the running daemon, use the -u option with the full
76 path to the socket created when the daemon was started:
77 ovn-sbctl -u /tmp/mysock.ctl show
79 Daemon Commands
82 Daemon mode is internally implemented using the same mechanism used by
84 ovn-appctl. One may also use ovn-appctl directly with the following
85 commands:
86 run [options] command [arg...] [-- [options] command [arg...]
88 ...]
89 Instructs the daemon process to run one or more ovn-sbctl
90 commands described above and reply with the results of
91 running these commands. Accepts the --no-wait, --wait,
92 --timeout, --dry-run, --oneline, and the options de‐
93 scribed under Table Formatting Options in addition to the
94 the command-specific options.
95 exit Causes ovn-sbctl to gracefully terminate.
97
99 The options listed below affect the behavior of ovn-sbctl as a whole.
100 Some individual commands also accept their own options, which are given
101 just before the command name. If the first command on the command line
102 has options, then those options must be separated from the global op‐
103 tions by --.
104 ovn-sbctl also accepts options from the OVN_SBCTL_OPTIONS environment
106 variable, in the same format as on the command line. Options from the
107 command line override those in the environment.
108 --db database
110 The OVSDB database remote to contact. If the OVN_SB_DB
111 environment variable is set, its value is used as the de‐
112 fault. Otherwise, the default is unix:/ovnsb_db.sock, but
113 this default is unlikely to be useful outside of single-
114 machine OVN test environments.
115 --leader-only
117 --no-leader-only
118 By default, or with --leader-only, when the database server
119 is a clustered database, ovn-sbctl will avoid servers other
120 than the cluster leader. This ensures that any data that
121 ovn-sbctl reads and reports is up-to-date. With
122 --no-leader-only, ovn-sbctl will use any server in the
123 cluster, which means that for read-only transactions it can
124 report and act on stale data (transactions that modify the
125 database are always serialized even with --no-leader-only).
126 Refer to Understanding Cluster Consistency in ovsdb(7) for
127 more information.
128 --shuffle-remotes
130 --no-shuffle-remotes
131 By default, or with --shuffle-remotes, when there are mul‐
132 tiple remotes specified in the OVSDB connection string
133 specified by --db or the OVN_SB_DB environment variable,
134 the order of the remotes will be shuffled before the client
135 tries to connect. The remotes will be shuffled only once to
136 a new order before the first connection attempt. The fol‐
137 lowing retries, if any, will follow the same new order. The
138 default behavior is to make sure clients of a clustered
139 database can distribute evenly to all members of the clus‐
140 ter. With --no-shuffle-remotes, ovn-sbctl will use the
141 original order specified in the connection string to con‐
142 nect. This allows user to specify the preferred order,
143 which is particularly useful for testing.
144 --no-syslog
146 By default, ovn-sbctl logs its arguments and the details of
147 any changes that it makes to the system log. This option
148 disables this logging.
149 This option is equivalent to --verbose=sbctl:syslog:warn.
151 --oneline
153 Modifies the output format so that the output for each com‐
154 mand is printed on a single line. New-line characters that
155 would otherwise separate lines are printed as \fB\\n\fR,
156 and any instances of \fB\\\fR that would otherwise appear
157 in the output are doubled. Prints a blank line for each
158 command that has no output. This option does not affect the
159 formatting of output from the list or find commands; see
160 Table Formatting Options below.
161 --dry-run
163 Prevents ovn-sbctl from actually modifying the database.
164 -t secs
166 --timeout=secs
167 By default, or with a secs of 0, ovn-sbctl waits forever
168 for a response from the database. This option limits run‐
169 time to approximately secs seconds. If the timeout expires,
170 ovn-sbctl will exit with a SIGALRM signal. (A timeout would
171 normally happen only if the database cannot be contacted,
172 or if the system is overloaded.)
173 Daemon Options
175 --pidfile[=pidfile]
176 Causes a file (by default, program.pid) to be created indicating
177 the PID of the running process. If the pidfile argument is not
178 specified, or if it does not begin with /, then it is created in
179 .
180 If --pidfile is not specified, no pidfile is created.
182 --overwrite-pidfile
184 By default, when --pidfile is specified and the specified pid‐
185 file already exists and is locked by a running process, the dae‐
186 mon refuses to start. Specify --overwrite-pidfile to cause it to
187 instead overwrite the pidfile.
188 When --pidfile is not specified, this option has no effect.
190 --detach
192 Runs this program as a background process. The process forks,
193 and in the child it starts a new session, closes the standard
194 file descriptors (which has the side effect of disabling logging
195 to the console), and changes its current directory to the root
196 (unless --no-chdir is specified). After the child completes its
197 initialization, the parent exits.
198 --monitor
200 Creates an additional process to monitor this program. If it
201 dies due to a signal that indicates a programming error (SIGA‐
202 BRT, SIGALRM, SIGBUS, SIGFPE, SIGILL, SIGPIPE, SIGSEGV, SIGXCPU,
203 or SIGXFSZ) then the monitor process starts a new copy of it. If
204 the daemon dies or exits for another reason, the monitor process
205 exits.
206 This option is normally used with --detach, but it also func‐
208 tions without it.
209 --no-chdir
211 By default, when --detach is specified, the daemon changes its
212 current working directory to the root directory after it de‐
213 taches. Otherwise, invoking the daemon from a carelessly chosen
214 directory would prevent the administrator from unmounting the
215 file system that holds that directory.
216 Specifying --no-chdir suppresses this behavior, preventing the
218 daemon from changing its current working directory. This may be
219 useful for collecting core files, since it is common behavior to
220 write core dumps into the current working directory and the root
221 directory is not a good directory to use.
222 This option has no effect when --detach is not specified.
224 --no-self-confinement
226 By default this daemon will try to self-confine itself to work
227 with files under well-known directories determined at build
228 time. It is better to stick with this default behavior and not
229 to use this flag unless some other Access Control is used to
230 confine daemon. Note that in contrast to other access control
231 implementations that are typically enforced from kernel-space
232 (e.g. DAC or MAC), self-confinement is imposed from the user-
233 space daemon itself and hence should not be considered as a full
234 confinement strategy, but instead should be viewed as an addi‐
235 tional layer of security.
236 --user=user:group
238 Causes this program to run as a different user specified in
239 user:group, thus dropping most of the root privileges. Short
240 forms user and :group are also allowed, with current user or
241 group assumed, respectively. Only daemons started by the root
242 user accepts this argument.
243 On Linux, daemons will be granted CAP_IPC_LOCK and
245 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
246 that interact with a datapath, such as ovs-vswitchd, will be
247 granted three additional capabilities, namely CAP_NET_ADMIN,
248 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
249 apply even if the new user is root.
250 On Windows, this option is not currently supported. For security
252 reasons, specifying this option will cause the daemon process
253 not to start.
254 Logging options
256 -v[spec]
257 --verbose=[spec]
258 Sets logging levels. Without any spec, sets the log level for ev‐
259 ery module and destination to dbg. Otherwise, spec is a list of
260 words separated by spaces or commas or colons, up to one from each
261 category below:
262 • A valid module name, as displayed by the vlog/list command
264 on ovs-appctl(8), limits the log level change to the speci‐
265 fied module.
266 • syslog, console, or file, to limit the log level change to
268 only to the system log, to the console, or to a file, re‐
269 spectively. (If --detach is specified, the daemon closes
270 its standard file descriptors, so logging to the console
271 will have no effect.)
272 On Windows platform, syslog is accepted as a word and is
274 only useful along with the --syslog-target option (the word
275 has no effect otherwise).
276 • off, emer, err, warn, info, or dbg, to control the log
278 level. Messages of the given severity or higher will be
279 logged, and messages of lower severity will be filtered
280 out. off filters out all messages. See ovs-appctl(8) for a
281 definition of each log level.
282 Case is not significant within spec.
284 Regardless of the log levels set for file, logging to a file will
286 not take place unless --log-file is also specified (see below).
287 For compatibility with older versions of OVS, any is accepted as a
289 word but has no effect.
290 -v
292 --verbose
293 Sets the maximum logging verbosity level, equivalent to --ver‐
294 bose=dbg.
295 -vPATTERN:destination:pattern
297 --verbose=PATTERN:destination:pattern
298 Sets the log pattern for destination to pattern. Refer to ovs-ap‐
299 pctl(8) for a description of the valid syntax for pattern.
300 -vFACILITY:facility
302 --verbose=FACILITY:facility
303 Sets the RFC5424 facility of the log message. facility can be one
304 of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, clock,
305 ftp, ntp, audit, alert, clock2, local0, local1, local2, local3,
306 local4, local5, local6 or local7. If this option is not specified,
307 daemon is used as the default for the local system syslog and lo‐
308 cal0 is used while sending a message to the target provided via
309 the --syslog-target option.
310 --log-file[=file]
312 Enables logging to a file. If file is specified, then it is used
313 as the exact name for the log file. The default log file name used
314 if file is omitted is /var/log/ovn/program.log.
315 --syslog-target=host:port
317 Send syslog messages to UDP port on host, in addition to the sys‐
318 tem syslog. The host must be a numerical IP address, not a host‐
319 name.
320 --syslog-method=method
322 Specify method as how syslog messages should be sent to syslog
323 daemon. The following forms are supported:
324 • libc, to use the libc syslog() function. Downside of using
326 this options is that libc adds fixed prefix to every mes‐
327 sage before it is actually sent to the syslog daemon over
328 /dev/log UNIX domain socket.
329 • unix:file, to use a UNIX domain socket directly. It is pos‐
331 sible to specify arbitrary message format with this option.
332 However, rsyslogd 8.9 and older versions use hard coded
333 parser function anyway that limits UNIX domain socket use.
334 If you want to use arbitrary message format with older
335 rsyslogd versions, then use UDP socket to localhost IP ad‐
336 dress instead.
337 • udp:ip:port, to use a UDP socket. With this method it is
339 possible to use arbitrary message format also with older
340 rsyslogd. When sending syslog messages over UDP socket ex‐
341 tra precaution needs to be taken into account, for example,
342 syslog daemon needs to be configured to listen on the spec‐
343 ified UDP port, accidental iptables rules could be inter‐
344 fering with local syslog traffic and there are some secu‐
345 rity considerations that apply to UDP sockets, but do not
346 apply to UNIX domain sockets.
347 • null, to discard all messages logged to syslog.
349 The default is taken from the OVS_SYSLOG_METHOD environment vari‐
351 able; if it is unset, the default is libc.
352 Table Formatting Options
354 These options control the format of output from the list and find com‐
355 mands.
356 -f format
358 --format=format
359 Sets the type of table formatting. The following types of
360 format are available:
361 table 2-D text tables with aligned columns.
363 list (default)
365 A list with one column per line and rows separated
366 by a blank line.
367 html HTML tables.
369 csv Comma-separated values as defined in RFC 4180.
371 json JSON format as defined in RFC 4627. The output is a
373 sequence of JSON objects, each of which corresponds
374 to one table. Each JSON object has the following
375 members with the noted values:
376 caption
378 The table’s caption. This member is omitted
379 if the table has no caption.
380 headings
382 An array with one element per table column.
383 Each array element is a string giving the
384 corresponding column’s heading.
385 data An array with one element per table row. Each
387 element is also an array with one element per
388 table column. The elements of this second-
389 level array are the cells that constitute the
390 table. Cells that represent OVSDB data or
391 data types are expressed in the format de‐
392 scribed in the OVSDB specification; other
393 cells are simply expressed as text strings.
394 -d format
396 --data=format
397 Sets the formatting for cells within output tables unless
398 the table format is set to json, in which case json format‐
399 ting is always used when formatting cells. The following
400 types of format are available:
401 string (default)
403 The simple format described in the Database Values
404 section of ovs-vsctl(8).
405 bare The simple format with punctuation stripped off: []
407 and {} are omitted around sets, maps, and empty col‐
408 umns, items within sets and maps are space-sepa‐
409 rated, and strings are never quoted. This format may
410 be easier for scripts to parse.
411 json The RFC 4627 JSON format as described above.
413 --no-headings
415 This option suppresses the heading row that otherwise ap‐
416 pears in the first row of table output.
417 --pretty
419 By default, JSON in output is printed as compactly as pos‐
420 sible. This option causes JSON in output to be printed in a
421 more readable fashion. Members of objects and elements of
422 arrays are printed one per line, with indentation.
423 This option does not affect JSON in tables, which is always
425 printed compactly.
426 --bare
428 Equivalent to --format=list --data=bare --no-headings.
429 PKI Options
431 PKI configuration is required to use SSL for the connection to the
432 database.
433 -p privkey.pem
435 --private-key=privkey.pem
436 Specifies a PEM file containing the private key used as
437 identity for outgoing SSL connections.
438 -c cert.pem
440 --certificate=cert.pem
441 Specifies a PEM file containing a certificate that certi‐
442 fies the private key specified on -p or --private-key to be
443 trustworthy. The certificate must be signed by the certifi‐
444 cate authority (CA) that the peer in SSL connections will
445 use to verify it.
446 -C cacert.pem
448 --ca-cert=cacert.pem
449 Specifies a PEM file containing the CA certificate for ver‐
450 ifying certificates presented to this program by SSL peers.
451 (This may be the same certificate that SSL peers use to
452 verify the certificate specified on -c or --certificate, or
453 it may be a different one, depending on the PKI design in
454 use.)
455 -C none
457 --ca-cert=none
458 Disables verification of certificates presented by SSL
459 peers. This introduces a security risk, because it means
460 that certificates cannot be verified to be those of known
461 trusted hosts.
462 --bootstrap-ca-cert=cacert.pem
464 When cacert.pem exists, this option has the same effect
465 as -C or --ca-cert. If it does not exist, then the exe‐
466 cutable will attempt to obtain the CA certificate from
467 the SSL peer on its first SSL connection and save it to
468 the named PEM file. If it is successful, it will immedi‐
469 ately drop the connection and reconnect, and from then on
470 all SSL connections must be authenticated by a certifi‐
471 cate signed by the CA certificate thus obtained.
472 This option exposes the SSL connection to a man-in-the-
474 middle attack obtaining the initial CA certificate, but
475 it may be useful for bootstrapping.
476 This option is only useful if the SSL peer sends its CA
478 certificate as part of the SSL certificate chain. The SSL
479 protocol does not require the server to send the CA cer‐
480 tificate.
481 This option is mutually exclusive with -C and --ca-cert.
483 Other Options
485 -h
486 --help
487 Prints a brief help message to the console.
488 -V
490 --version
491 Prints version information to the console.
492
494 The following sections describe the commands that ovn-sbctl supports.
495 OVN_Southbound Commands
497 These commands work with an OVN_Southbound database as a whole.
498 init Initializes the database, if it is empty. If the database
500 has already been initialized, this command has no effect.
501 show Prints a brief overview of the database contents.
503 Chassis Commands
505 These commands manipulate OVN_Southbound chassis.
506 [--may-exist] chassis-add chassis encap-type encap-ip
508 Creates a new chassis named chassis. encap-type is a
509 comma-separated list of tunnel types. The chassis will
510 have one encap entry for each specified tunnel type with
511 encap-ip as the destination IP for each.
512 Without --may-exist, attempting to create a chassis that
514 exists is an error. With --may-exist, this command does
515 nothing if chassis already exists.
516 [--if-exists] chassis-del chassis
518 Deletes chassis and its encaps and gateway_ports.
519 Without --if-exists, attempting to delete a chassis that
521 does not exist is an error. With --if-exists attempting
522 to delete a chassis that does not exist has no effect.
523 Port Binding Commands
525 These commands manipulate OVN_Southbound port bindings.
526 [--may-exist] lsp-bind logical-port chassis
528 Binds the logical port named logical-port to chassis.
529 Without --may-exist, attempting to bind a logical port
531 that has already been bound is an error. With --may-ex‐
532 ist, this command does nothing if logical-port has al‐
533 ready been bound to a chassis.
534 [--if-exists] lsp-unbind logical-port
536 Removes the binding of logical-port.
537 Without --if-exists, attempting to unbind a logical port
539 that is not bound is an error. With --if-exists, attempt‐
540 ing to unbind logical port that is not bound has no ef‐
541 fect.
542 Logical Flow Commands
544 [--uuid] [--ovs[=remote]] [--stats] [--vflows] lflow-list [logical-
545 datapath] [lflow...]
546 List logical flows. If logical-datapath is specified, only list
547 flows for that logical datapath. The logical-datapath may be
548 given as a UUID or as a datapath name (reporting an error if
549 multiple datapaths have the same name).
550 If at least one lflow is given, only matching logical flows, if
552 any, are listed. Each lflow may be specified as a UUID or the
553 first few characters of a UUID, optionally prefixed by 0x. (Be‐
554 cause ovn-controller sets OpenFlow flow cookies to the first 32
555 bits of the corresponding logical flow’s UUID, this makes it
556 easy to look up the logical flow that generated a particular
557 OpenFlow flow.)
558 If --uuid is specified, the output includes the first 32 bits of
560 each logical flow’s UUID. This makes it easier to find the Open‐
561 Flow flows that correspond to a given logical flow.
562 If --ovs is included, ovn-sbctl attempts to obtain and display
564 the OpenFlow flows that correspond to each OVN logical flow. To
565 do so, ovn-sbctl connects to remote (by default,
566 unix:/br-int.mgmt) over OpenFlow and retrieves the flows. If re‐
567 mote is specified, it must be an active OpenFlow connection
568 method described in ovsdb(7). Please see the discussion of the
569 similar --ovs option in ovn-trace(8) for more information about
570 the OpenFlow flow output.
571 By default, OpenFlow flow output includes only match and ac‐
573 tions. Add --stats to include all OpenFlow information, such as
574 packet and byte counters, duration, and timeouts.
575 If --vflows is included, other southbound database records di‐
577 rectly used for generating OpenFlow flows are also listed. This
578 includes: port-bindings, mac-bindings, multicast-groups, chas‐
579 sis. The --ovs and --stats can also be used in conjunction with
580 --vflows.
581 [--uuid] dump-flows [logical-datapath]
583 Alias for lflow-list.
584 count-flows [logical-datapath]
586 prints numbers of logical flows per table and per datapath.
587 Remote Connectivity Commands
589 These commands manipulate the connections column in the SB_Global table
590 and rows in the Connection table. When ovsdb-server is configured to
591 use the connections column for OVSDB connections, this allows the ad‐
592 ministrator to use \fBovn\-sbctl\fR to configure database connections.
593 get-connection
595 Prints the configured connection(s).
596 del-connection
598 Deletes the configured connection(s).
599 [--inactivity-probe=msecs] set-connection target...
601 Sets the configured manager target or targets. Use --in‐
602 activity-probe=msecs to override the default idle connec‐
603 tion inactivity probe time. Use 0 to disable inactivity
604 probes.
605 SSL Configuration Commands
607 When ovsdb-server is configured to connect using SSL, the following pa‐
608 rameters are required:
609 private-key
611 Specifies a PEM file containing the private key used for
612 SSL connections.
613 certificate
615 Specifies a PEM file containing a certificate, signed by
616 the certificate authority (CA) used by the connection
617 peers, that certifies the private key, identifying a
618 trustworthy peer.
619 ca-cert
621 Specifies a PEM file containing the CA certificate used
622 to verify that the connection peers are trustworthy.
623 These SSL settings apply to all SSL connections made by the southbound
625 database server.
626 get-ssl
628 Prints the SSL configuration.
629 del-ssl
631 Deletes the current SSL configuration.
632 [--bootstrap] set-ssl private-key certificate ca-cert [ssl-pro‐
634 tocol-list [ssl-cipher-list]]
635 Sets the SSL configuration.
636 Database Commands
638 These commands query and modify the contents of ovsdb tables. They are
639 a slight abstraction of the ovsdb interface and as such they operate at
640 a lower level than other ovn-sbctl commands.
641 Identifying Tables, Records, and Columns
643 Each of these commands has a table parameter to identify a table within
645 the database. Many of them also take a record parameter that identifies
646 a particular record within a table. The record parameter may be the
647 UUID for a record, which may be abbreviated to its first 4 (or more)
648 hex digits, as long as that is unique. Many tables offer additional
649 ways to identify records. Some commands also take column parameters
650 that identify a particular field within the records in a table.
651 For a list of tables and their columns, see ovn-sb(5) or see the table
653 listing from the --help option.
654 Record names must be specified in full and with correct capitalization,
656 except that UUIDs may be abbreviated to their first 4 (or more) hex
657 digits, as long as that is unique within the table. Names of tables and
658 columns are not case-sensitive, and - and _ are treated interchange‐
659 ably. Unique abbreviations of table and column names are acceptable,
660 e.g. d or dhcp is sufficient to identify the DHCP_Options table.
661 Database Values
663 Each column in the database accepts a fixed type of data. The currently
665 defined basic types, and their representations, are:
666 integer
668 A decimal integer in the range -2**63 to 2**63-1, inclu‐
669 sive.
670 real A floating-point number.
672 Boolean
674 True or false, written true or false, respectively.
675 string An arbitrary Unicode string, except that null bytes are
677 not allowed. Quotes are optional for most strings that
678 begin with an English letter or underscore and consist
679 only of letters, underscores, hyphens, and periods. How‐
680 ever, true and false and strings that match the syntax of
681 UUIDs (see below) must be enclosed in double quotes to
682 distinguish them from other basic types. When double
683 quotes are used, the syntax is that of strings in JSON,
684 e.g. backslashes may be used to escape special charac‐
685 ters. The empty string must be represented as a pair of
686 double quotes ("").
687 UUID Either a universally unique identifier in the style of
689 RFC 4122, e.g. f81d4fae-7dec-11d0-a765-00a0c91e6bf6, or
690 an @name defined by a get or create command within the
691 same ovs-vsctl invocation.
692 Multiple values in a single column may be separated by spaces or a sin‐
694 gle comma. When multiple values are present, duplicates are not al‐
695 lowed, and order is not important. Conversely, some database columns
696 can have an empty set of values, represented as [], and square brackets
697 may optionally enclose other non-empty sets or single values as well.
698 A few database columns are ``maps’’ of key-value pairs, where the key
700 and the value are each some fixed database type. These are specified in
701 the form key=value, where key and value follow the syntax for the col‐
702 umn’s key type and value type, respectively. When multiple pairs are
703 present (separated by spaces or a comma), duplicate keys are not al‐
704 lowed, and again the order is not important. Duplicate values are al‐
705 lowed. An empty map is represented as {}. Curly braces may optionally
706 enclose non-empty maps as well (but use quotes to prevent the shell
707 from expanding other-config={0=x,1=y} into other-config=0=x other-con‐
708 fig=1=y, which may not have the desired effect).
709 Database Command Syntax
711 [--if-exists] [--columns=column[,column]...] list table
713 [record]...
714 Lists the data in each specified record. If no records
715 are specified, lists all the records in table.
716 If --columns is specified, only the requested columns are
718 listed, in the specified order. Otherwise, all columns
719 are listed, in alphabetical order by column name.
720 Without --if-exists, it is an error if any specified
722 record does not exist. With --if-exists, the command ig‐
723 nores any record that does not exist, without producing
724 any output.
725 [--columns=column[,column]...] find table [col‐
727 umn[:key]=value]...
728 Lists the data in each record in table whose column
729 equals value or, if key is specified, whose column con‐
730 tains a key with the specified value. The following oper‐
731 ators may be used where = is written in the syntax sum‐
732 mary:
733 = != < > <= >=
735 Selects records in which column[:key] equals, does
736 not equal, is less than, is greater than, is less
737 than or equal to, or is greater than or equal to
738 value, respectively.
739 Consider column[:key] and value as sets of ele‐
741 ments. Identical sets are considered equal. Other‐
742 wise, if the sets have different numbers of ele‐
743 ments, then the set with more elements is consid‐
744 ered to be larger. Otherwise, consider a element
745 from each set pairwise, in increasing order within
746 each set. The first pair that differs determines
747 the result. (For a column that contains key-value
748 pairs, first all the keys are compared, and values
749 are considered only if the two sets contain iden‐
750 tical keys.)
751 {=} {!=}
753 Test for set equality or inequality, respectively.
754 {<=} Selects records in which column[:key] is a subset
756 of value. For example, flood-vlans{<=}1,2 selects
757 records in which the flood-vlans column is the
758 empty set or contains 1 or 2 or both.
759 {<} Selects records in which column[:key] is a proper
761 subset of value. For example, flood-vlans{<}1,2
762 selects records in which the flood-vlans column is
763 the empty set or contains 1 or 2 but not both.
764 {>=} {>}
766 Same as {<=} and {<}, respectively, except that
767 the relationship is reversed. For example,
768 flood-vlans{>=}1,2 selects records in which the
769 flood-vlans column contains both 1 and 2.
770 The following operators are available only in Open
772 vSwitch 2.16 and later:
773 {in} Selects records in which every element in col‐
775 umn[:key] is also in value. (This is the same as
776 {<=}.)
777 {not-in}
779 Selects records in which every element in col‐
780 umn[:key] is not in value.
781 For arithmetic operators (= != < > <= >=), when key is
783 specified but a particular record’s column does not con‐
784 tain key, the record is always omitted from the results.
785 Thus, the condition other-config:mtu!=1500 matches
786 records that have a mtu key whose value is not 1500, but
787 not those that lack an mtu key.
788 For the set operators, when key is specified but a par‐
790 ticular record’s column does not contain key, the compar‐
791 ison is done against an empty set. Thus, the condition
792 other-config:mtu{!=}1500 matches records that have a mtu
793 key whose value is not 1500 and those that lack an mtu
794 key.
795 Don’t forget to escape < or > from interpretation by the
797 shell.
798 If --columns is specified, only the requested columns are
800 listed, in the specified order. Otherwise all columns are
801 listed, in alphabetical order by column name.
802 The UUIDs shown for rows created in the same ovs-vsctl
804 invocation will be wrong.
805 [--if-exists] [--id=@name] get table record [column[:key]]...
807 Prints the value of each specified column in the given
808 record in table. For map columns, a key may optionally be
809 specified, in which case the value associated with key in
810 the column is printed, instead of the entire map.
811 Without --if-exists, it is an error if record does not
813 exist or key is specified, if key does not exist in
814 record. With --if-exists, a missing record yields no out‐
815 put and a missing key prints a blank line.
816 If @name is specified, then the UUID for record may be
818 referred to by that name later in the same ovs-vsctl in‐
819 vocation in contexts where a UUID is expected.
820 Both --id and the column arguments are optional, but usu‐
822 ally at least one or the other should be specified. If
823 both are omitted, then get has no effect except to verify
824 that record exists in table.
825 --id and --if-exists cannot be used together.
827 [--if-exists] set table record column[:key]=value...
829 Sets the value of each specified column in the given
830 record in table to value. For map columns, a key may op‐
831 tionally be specified, in which case the value associated
832 with key in that column is changed (or added, if none ex‐
833 ists), instead of the entire map.
834 Without --if-exists, it is an error if record does not
836 exist. With --if-exists, this command does nothing if
837 record does not exist.
838 [--if-exists] add table record column [key=]value...
840 Adds the specified value or key-value pair to column in
841 record in table. If column is a map, then key is re‐
842 quired, otherwise it is prohibited. If key already exists
843 in a map column, then the current value is not replaced
844 (use the set command to replace an existing value).
845 Without --if-exists, it is an error if record does not
847 exist. With --if-exists, this command does nothing if
848 record does not exist.
849 [--if-exists] remove table record column value...
851 [--if-exists] remove table record column key...
853 [--if-exists] remove table record column key=value...
855 Removes the specified values or key-value pairs from col‐
856 umn in record in table. The first form applies to columns
857 that are not maps: each specified value is removed from
858 the column. The second and third forms apply to map col‐
859 umns: if only a key is specified, then any key-value pair
860 with the given key is removed, regardless of its value;
861 if a value is given then a pair is removed only if both
862 key and value match.
863 It is not an error if the column does not contain the
865 specified key or value or pair.
866 Without --if-exists, it is an error if record does not
868 exist. With --if-exists, this command does nothing if
869 record does not exist.
870 [--if-exists] clear table record column...
872 Sets each column in record in table to the empty set or
873 empty map, as appropriate. This command applies only to
874 columns that are allowed to be empty.
875 Without --if-exists, it is an error if record does not
877 exist. With --if-exists, this command does nothing if
878 record does not exist.
879 [--id=(@name|uuid)] create table column[:key]=value...
881 Creates a new record in table and sets the initial values
882 of each column. Columns not explicitly set will receive
883 their default values. Outputs the UUID of the new row.
884 If @name is specified, then the UUID for the new row may
886 be referred to by that name elsewhere in the same \*(PN
887 invocation in contexts where a UUID is expected. Such
888 references may precede or follow the create command.
889 If a valid uuid is specified, then it is used as the UUID
891 of the new row.
892 Caution (ovs-vsctl as example)
894 Records in the Open vSwitch database are signifi‐
895 cant only when they can be reached directly or in‐
896 directly from the Open_vSwitch table. Except for
897 records in the QoS or Queue tables, records that
898 are not reachable from the Open_vSwitch table are
899 automatically deleted from the database. This
900 deletion happens immediately, without waiting for
901 additional ovs-vsctl commands or other database
902 activity. Thus, a create command must generally be
903 accompanied by additional commands within the same
904 ovs-vsctl invocation to add a chain of references
905 to the newly created record from the top-level
906 Open_vSwitch record. The EXAMPLES section gives
907 some examples that show how to do this.
908 [--if-exists] destroy table record...
910 Deletes each specified record from table. Unless --if-ex‐
911 ists is specified, each records must exist.
912 --all destroy table
914 Deletes all records from the table.
915 Caution (ovs-vsctl as example)
917 The destroy command is only useful for records in
918 the QoS or Queue tables. Records in other tables
919 are automatically deleted from the database when
920 they become unreachable from the Open_vSwitch ta‐
921 ble. This means that deleting the last reference
922 to a record is sufficient for deleting the record
923 itself. For records in these tables, destroy is
924 silently ignored. See the EXAMPLES section below
925 for more information.
926 wait-until table record [column[:key]=value]...
928 Waits until table contains a record named record whose
929 column equals value or, if key is specified, whose column
930 contains a key with the specified value. This command
931 supports the same operators and semantics described for
932 the find command above.
933 If no column[:key]=value arguments are given, this com‐
935 mand waits only until record exists. If more than one
936 such argument is given, the command waits until all of
937 them are satisfied.
938 Caution (ovs-vsctl as example)
940 Usually wait-until should be placed at the begin‐
941 ning of a set of ovs-vsctl commands. For example,
942 wait-until bridge br0 -- get bridge br0 data‐
943 path_id waits until a bridge named br0 is created,
944 then prints its datapath_id column, whereas get
945 bridge br0 datapath_id -- wait-until bridge br0
946 will abort if no bridge named br0 exists when
947 ovs-vsctl initially connects to the database.
948 Consider specifying --timeout=0 along with --wait-until,
950 to prevent ovs-vsctl from terminating after waiting only
951 at most 5 seconds.
952 comment [arg]...
954 This command has no effect on behavior, but any database
955 log record created by the command will include the com‐
956 mand and its arguments.
957
959 OVN_SB_DAEMON
960 If set, this should name the Unix domain socket for an ovn-sbctl
961 server process. See Daemon Mode, above, for more information.
962 OVN_SBCTL_OPTIONS
964 If set, a set of options for ovn-sbctl to apply automatically,
965 in the same form as on the command line.
966 OVN_SB_DB
968 If set, the default database to contact when the --db option is
969 not used.
970
972 0 Successful program execution.
973 1 Usage, syntax, or network error.
975
977 ovn-sb(5), ovn-appctl(8).
978OVN 23.09.2 ovn-sbctl ovn-sbctl(8)