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