1ovsdb-tool(1) Open vSwitch Manual ovsdb-tool(1)
2
6 ovsdb-tool - Open vSwitch database management utility
7
9 Database Creation Commands:
10 ovsdb-tool [options] create [db [schema]]
11 ovsdb-tool [options] create-cluster db contents address
12 ovsdb-tool [options] [--cid=uuid] join-cluster db name local
13 remote...
14 Version Management Commands:
16 ovsdb-tool [options] convert [db [schema [target]]]
17 ovsdb-tool [options] needs-conversion [db [schema]]
18 ovsdb-tool [options] db-version [db]
19 ovsdb-tool [options] schema-version [schema]
20 ovsdb-tool [options] db-cksum [db]
21 ovsdb-tool [options] schema-cksum [schema]
22 ovsdb-tool [options] compare-versions a op b
23 Other commands:
25 ovsdb-tool [options] compact [db [target]]
26 ovsdb-tool [options] [--rbac-role=role] query [db] transaction
27 ovsdb-tool [options] [--rbac-role=role] transact [db] transac‐
28 tion
29 ovsdb-tool [options] [-m | --more]... show-log [db]
30 ovsdb-tool [options] check-cluster db...
31 ovsdb-tool [options] db-name [db]
32 ovsdb-tool [options] schema-name [schema]
33 ovsdb-tool [options] db-cid db
34 ovsdb-tool [options] db-sid db
35 ovsdb-tool [options] db-local-address db
36 ovsdb-tool help
37 Logging options:
39 [-v[module[:destination[:level]]]]...
40 [--verbose[=module[:destination[:level]]]]...
41 [--log-file[=file]]
42 Common options:
44 [-h | --help] [-V | --version]
45
48 The ovsdb-tool program is a command-line tool for managing Open vSwitch
49 database (OVSDB) files. It does not interact directly with running
50 Open vSwitch database servers (instead, use ovsdb-client). For an
51 introduction to OVSDB and its implementation in Open vSwitch, see
52 ovsdb(7).
53 Each command that takes an optional db or schema argument has a default
55 file location if it is not specified.. The default db is /etc/open‐
56 vswitch/conf.db. The default schema is /usr/share/open‐
57 vswitch/vswitch.ovsschema.
58 This OVSDB implementation supports standalone and active-backup data‐
60 base service models with one on-disk format and a clustered database
61 service model with a different format. ovsdb-tool supports both for‐
62 mats, but some commands are appropriate for only one format, as docu‐
63 mented for individual commands below. For a specification of these
64 formats, see ovsdb(5). For more information on OVSDB service models,
65 see the Service Models section in ovsdb(7).
66 Database Creation Commands
68 These commands create a new OVSDB database file. They will not over‐
69 write an existing database file. To replace an existing database with
70 a new one, first delete the old one.
71 create [db [schema]]
73 Use this command to create the database for controlling
74 ovs-vswitchd or another standalone or active-backup database.
75 It creates database file db with the given schema, which must be
76 the name of a file that contains an OVSDB schema in JSON format,
77 as specified in the OVSDB specification. The new database is
78 initially empty. (You can use cp to copy a database including
79 both its schema and data.)
80 create-cluster db contents local
82 Use this command to initialize the first server in a high-avail‐
83 ability cluster of 3 (or more) database servers, e.g. for a
84 database in an environment that cannot tolerate a single point
85 of failure. It creates clustered database file db and config‐
86 ures the server to listen on local, which must take the form
87 protocol:ip:port, where protocol is tcp or ssl, ip is the
88 server's IP (either an IPv4 address or an IPv6 address enclosed
89 in square brackets), and port is a TCP port number. Only one
90 address is specified, for the first server in the cluster, ordi‐
91 narily the one for the server running create-cluster. The
92 address is used for communication within the cluster, not for
93 communicating with OVSDB clients, and must not use the same port
94 used for the OVSDB protocol.
95 The new database is initialized with contents, which must name a
97 file that contains either an OVSDB schema in JSON format or a
98 standalone OVSDB database. If it is a schema file, the new
99 database will initially be empty, with the given schema. If it
100 is a database file, the new database will have the same schema
101 and contents.
102 [--cid=uuid] join-cluster db name local remote...
104 Use this command to initialize each server after the first one
105 in an OVSDB high-availability cluster. It creates clustered
106 database file db for a database named name, and configures the
107 server to listen on local and to initially connect to remote,
108 which must be a server that already belongs to the cluster.
109 local and remote use the same protocol:ip:port syntax as cre‐
110 ate-cluster.
111 The name must be the name of the schema or database passed to
113 create-cluster. For example, the name of the OVN Southbound
114 database schema is OVN_Southbound. Use ovsdb-tool's schema-name
115 or db-name command to find out the name of a schema or database,
116 respectively.
117 This command does not do any network access, which means that it
119 cannot actually join the new server to the cluster. Instead,
120 the db file that it creates prepares the server to join the
121 cluster the first time that ovsdb-server serves it. As part of
122 joining the cluster, the new server retrieves the database
123 schema and obtains the list of all cluster members. Only after
124 that does it become a full member of the cluster.
125 Optionally, more than one remote may be specified; for example,
127 in a cluster that already contains multiple servers, one could
128 specify all the existing servers. This is beneficial if some of
129 the existing servers are down while the new server joins, but it
130 is not otherwise needed.
131 By default, the db created by join-cluster will join any clus‐
133 tered database named name that is available at a remote. In
134 theory, if machines go up and down and IP addresses change in
135 the right way, it could join the wrong database cluster. To
136 avoid this possibility, specify --cid=uuid, where uuid is the
137 cluster ID of the cluster to join, as printed by ovsdb-tool
138 get-cid.
139 Database Migration Commands
141 This commands will convert cluster database to standalone database.
142 cluster-to-standalone db clusterdb
144 Use this command to convert to standalone database from clus‐
145 tered database when the cluster is down and cannot be revived.
146 It creates new standalone db file from the given cluster db
147 file.
148 Version Management Commands
150 An OVSDB schema has a schema version number, and an OVSDB database
151 embeds a particular version of an OVSDB schema. These version numbers
152 take the form x.y.z, e.g. 1.2.3. The OVSDB implementation does not
153 enforce a particular version numbering scheme, but schemas managed
154 within the Open vSwitch project use the following approach. Whenever
155 the database schema is changed in a non-backward compatible way (e.g.
156 deleting a column or a table), x is incremented (and y and z are reset
157 to 0). When the database schema is changed in a backward compatible
158 way (e.g. adding a new column), y is incremented (and z is reset to 0).
159 When the database schema is changed cosmetically (e.g. reindenting its
160 syntax), z is incremented.
161 Some OVSDB databases and schemas, especially very old ones, do not have
163 a version number.
164 Schema version numbers and Open vSwitch version numbers are indepen‐
166 dent.
167 These commands work with different versions of OVSDB schemas and data‐
169 bases.
170 convert [db [schema [target]]]
172 Reads db, translating it into to the schema specified in schema,
173 and writes out the new interpretation. If target is specified,
174 the translated version is written as a new file named target,
175 which must not already exist. If target is omitted, then the
176 translated version of the database replaces db in-place. In-
177 place conversion cannot take place if the database is currently
178 being served by ovsdb-server (instead, either stop ovsdb-server
179 first or use ovsdb-client's convert command).
180 This command can do simple ``upgrades'' and ``downgrades'' on a
182 database's schema. The data in db must be valid when inter‐
183 preted under schema, with only one exception: data in db for
184 tables and columns that do not exist in schema are ignored.
185 Columns that exist in schema but not in db are set to their
186 default values. All of schema's constraints apply in full.
187 Some uses of this command can cause unrecoverable data loss.
189 For example, converting a database from a schema that has a
190 given column or table to one that does not will delete all data
191 in that column or table. Back up critical databases before con‐
192 verting them.
193 This command is for standalone and active-backup databases only.
195 For clustered databases, use ovsdb-client's convert command to
196 convert them online.
197 needs-conversion [db [schema]]
199 Reads the schema embedded in db and the JSON schema from schema
200 and compares them. If the schemas are the same, prints no on
201 stdout; if they differ, prints yes.
202 This command is for standalone and active-backup databases only.
204 For clustered databases, use ovsdb-client's needs-conversion
205 command instead.
206 db-version [db]
208 schema-version [schema]
209 Prints the version number in the schema embedded within the
210 database db or in the JSON schema schema on stdout. If schema
211 or db was created before schema versioning was introduced, then
212 it will not have a version number and this command will print a
213 blank line.
214 The db-version command is for standalone and active-backup data‐
216 bases only. For clustered databases, use ovsdb-client's
217 schema-version command instead.
218 db-cksum [db]
220 schema-cksum [schema]
221 Prints the checksum in the schema embedded within the database
222 db or of the JSON schema schema on stdout. If schema or db was
223 created before schema checksums were introduced, then it will
224 not have a checksum and this command will print a blank line.
225 The db-cksum command is for standalone and active-backup data‐
227 bases only. For clustered databases, use ovsdb-client's
228 schema-cksum command instead.
229 compare-versions a op b
231 Compares a and b according to op. Both a and b must be OVSDB
232 schema version numbers in the form x.y.z, as described in
233 ovsdb(7), and op must be one of < <= == >= > !=. If the compar‐
234 ison is true, exits with status 0; if it is false, exits with
235 status 2. (Exit status 1 indicates an error, e.g. a or b is the
236 wrong syntax for an OVSDB version or op is not a valid compari‐
237 son operator.)
238 Other Commands
240 compact [db [target]]
241 Reads db and writes a compacted version. If target is speci‐
242 fied, the compacted version is written as a new file named tar‐
243 get, which must not already exist. If target is omitted, then
244 the compacted version of the database replaces db in-place.
245 This command is not needed in normal operation because
246 ovsdb-server from time to time automatically compacts a database
247 that grows much larger than its minimum size.
248 This command does not work if db is currently being served by
250 ovsdb-server, or if it is otherwise locked for writing by
251 another process. This command also does not work with clustered
252 databases. Instead, in either case, send the ovsdb-server/com‐
253 pact command to ovsdb-server, via ovs-appctl).
254 [--rbac-role=role] query [db] transaction
256 Opens db, executes transaction on it, and prints the results.
257 The transaction must be a JSON array in the format of the params
258 array for the JSON-RPC transact method, as described in the
259 OVSDB specification.
260 This command opens db for read-only access, so it may safely run
262 concurrently with other database activity, including
263 ovsdb-server and other database writers. The transaction may
264 specify database modifications, but these will have no effect on
265 db.
266 By default, the transaction is executed using the ``superuser''
268 RBAC role. Use --rbac-role to specify a different role.
269 This command does not work with clustered databases. Instead,
271 use ovsdb-client's query command to send the query to
272 ovsdb-server.
273 [--rbac-role=role] transact [db] transaction
275 Opens db, executes transaction on it, prints the results, and
276 commits any changes to db. The transaction must be a JSON array
277 in the format of the params array for the JSON-RPC transact
278 method, as described in the OVSDB specification.
279 This command does not work if db is currently being served by
281 ovsdb-server, or if it is otherwise locked for writing by
282 another process. This command also does not work with clustered
283 databases. Instead, in either case, use ovsdb-client's transact
284 command to send the query to ovsdb-server.
285 By default, the transaction is executed using the ``superuser''
287 RBAC role. Use --rbac-role to specify a different role.
288 [-m | --more]... show-log [db]
290 Prints a summary of the records in db's log, including the time
291 and date at which each database change occurred and any associ‐
292 ated comment. This may be useful for debugging.
293 To increase the verbosity of output, add -m (or --more) one or
295 more times to the command line. With one -m, show-log prints a
296 summary of the records added, deleted, or modified by each
297 transaction. With two -ms, show-log also prints the values of
298 the columns modified by each change to a record.
299 This command works with standalone and active-backup databases
301 and with clustered databases, but the output formats are differ‐
302 ent.
303 check-cluster db...
305 Reads all of the records in the supplied databases, which must
306 be collected from different servers (and ideally all the
307 servers) in a single cluster. Checks each database for self-
308 consistency and the set together for cross-consistency. If
309 ovsdb-tool detects unusual but not necessarily incorrect con‐
310 tent, it prints a warning or warnings on stdout. If ovsdb-tool
311 find consistency errors, it prints an error on stderr and exits
312 with status 1. Errors typically indicate bugs in ovsdb-server;
313 please consider reporting them to the Open vSwitch developers.
314 db-name [db]
316 schema-name [schema]
317 Prints the name of the schema embedded within the database db or
318 in the JSON schema schema on stdout.
319 db-cid db
321 Prints the cluster ID, which is a UUID that identifies the clus‐
322 ter, for db. If db is a database newly created by ovsdb-tool
323 cluster-join that has not yet successfully joined its cluster,
324 and --cid was not specified on the cluster-join command line,
325 then this command will output an error, and exit with status 2,
326 because the cluster ID is not yet known. This command works
327 only with clustered databases.
328 The all-zeros UUID is not a valid cluster ID.
330 db-sid db
332 Prints the server ID, which is a UUID that identifies the
333 server, for db. This command works only with clustered data‐
334 bases. It works even if db is a database newly created by
335 ovsdb-tool cluster-join that has not yet successfully joined its
336 cluster.
337 db-local-address db
339 Prints the local address used for database clustering for db, in
340 the same protocol:ip:port form used on create-cluster and
341 join-cluster.
342 db-is-clustered db
344 db-is-standalone db
345 Tests whether db is a database file in clustered or standalone
346 format, respectively. If so, exits with status 0; if not, exits
347 with status 2. (Exit status 1 indicates an error, e.g. db is
348 not an OVSDB database or does not exist.)
349
351 Logging Options
352 -v[spec]
353 --verbose=[spec]
354 Sets logging levels. Without any spec, sets the log level for
355 every module and destination to dbg. Otherwise, spec is a list
356 of words separated by spaces or commas or colons, up to one from
357 each category below:
358 · A valid module name, as displayed by the vlog/list com‐
360 mand on ovs-appctl(8), limits the log level change to the
361 specified module.
362 · syslog, console, or file, to limit the log level change
364 to only to the system log, to the console, or to a file,
365 respectively. (If --detach is specified, ovsdb-tool
366 closes its standard file descriptors, so logging to the
367 console will have no effect.)
368 On Windows platform, syslog is accepted as a word and is
370 only useful along with the --syslog-target option (the
371 word has no effect otherwise).
372 · off, emer, err, warn, info, or dbg, to control the log
374 level. Messages of the given severity or higher will be
375 logged, and messages of lower severity will be filtered
376 out. off filters out all messages. See ovs-appctl(8)
377 for a definition of each log level.
378 Case is not significant within spec.
380 Regardless of the log levels set for file, logging to a file
382 will not take place unless --log-file is also specified (see
383 below).
384 For compatibility with older versions of OVS, any is accepted as
386 a word but has no effect.
387 -v
389 --verbose
390 Sets the maximum logging verbosity level, equivalent to --ver‐
391 bose=dbg.
392 -vPATTERN:destination:pattern
394 --verbose=PATTERN:destination:pattern
395 Sets the log pattern for destination to pattern. Refer to
396 ovs-appctl(8) for a description of the valid syntax for pattern.
397 -vFACILITY:facility
399 --verbose=FACILITY:facility
400 Sets the RFC5424 facility of the log message. facility can be
401 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
402 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
403 local3, local4, local5, local6 or local7. If this option is not
404 specified, daemon is used as the default for the local system
405 syslog and local0 is used while sending a message to the target
406 provided via the --syslog-target option.
407 --log-file[=file]
409 Enables logging to a file. If file is specified, then it is
410 used as the exact name for the log file. The default log file
411 name used if file is omitted is /var/log/open‐
412 vswitch/ovsdb-tool.log.
413 --syslog-target=host:port
415 Send syslog messages to UDP port on host, in addition to the
416 system syslog. The host must be a numerical IP address, not a
417 hostname.
418 --syslog-method=method
420 Specify method how syslog messages should be sent to syslog dae‐
421 mon. Following forms are supported:
422 · libc, use libc syslog() function. Downside of using this
424 options is that libc adds fixed prefix to every message
425 before it is actually sent to the syslog daemon over
426 /dev/log UNIX domain socket.
427 · unix:file, use UNIX domain socket directly. It is possi‐
429 ble to specify arbitrary message format with this option.
430 However, rsyslogd 8.9 and older versions use hard coded
431 parser function anyway that limits UNIX domain socket
432 use. If you want to use arbitrary message format with
433 older rsyslogd versions, then use UDP socket to localhost
434 IP address instead.
435 · udp:ip:port, use UDP socket. With this method it is pos‐
437 sible to use arbitrary message format also with older
438 rsyslogd. When sending syslog messages over UDP socket
439 extra precaution needs to be taken into account, for
440 example, syslog daemon needs to be configured to listen
441 on the specified UDP port, accidental iptables rules
442 could be interfering with local syslog traffic and there
443 are some security considerations that apply to UDP sock‐
444 ets, but do not apply to UNIX domain sockets.
445 · null, discards all messages logged to syslog.
447 The default is taken from the OVS_SYSLOG_METHOD environment
449 variable; if it is unset, the default is libc.
450 Other Options
452 -h
453 --help Prints a brief help message to the console.
454 -V
456 --version
457 Prints version information to the console.
458
460 The default db is /etc/openvswitch/conf.db. The default schema is
461 /usr/share/openvswitch/vswitch.ovsschema. The help command also dis‐
462 plays these defaults.
463
465 ovsdb(7), ovsdb-server(1), ovsdb-client(1).
466Open vSwitch 2.15.0 ovsdb-tool(1)