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 an OVN
84 northbound or southbound database in an environment that cannot
85 tolerate a single point of failure. It creates clustered data‐
86 base file db and configures the server to listen on local, which
87 must take the form protocol:ip:port, where protocol is tcp or
88 ssl, ip is the server's IP (either an IPv4 address or an IPv6
89 address enclosed in square brackets), and port is a TCP port
90 number. Only one address is specified, for the first server in
91 the cluster, ordinarily the one for the server running cre‐
92 ate-cluster. The address is used for communication within the
93 cluster, not for communicating with OVSDB clients, and must not
94 use the same port 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 Version Management Commands
141 An OVSDB schema has a schema version number, and an OVSDB database
142 embeds a particular version of an OVSDB schema. These version numbers
143 take the form x.y.z, e.g. 1.2.3. The OVSDB implementation does not
144 enforce a particular version numbering scheme, but schemas managed
145 within the Open vSwitch project use the following approach. Whenever
146 the database schema is changed in a non-backward compatible way (e.g.
147 deleting a column or a table), x is incremented (and y and z are reset
148 to 0). When the database schema is changed in a backward compatible
149 way (e.g. adding a new column), y is incremented (and z is reset to 0).
150 When the database schema is changed cosmetically (e.g. reindenting its
151 syntax), z is incremented.
152 Some OVSDB databases and schemas, especially very old ones, do not have
154 a version number.
155 Schema version numbers and Open vSwitch version numbers are indepen‐
157 dent.
158 These commands work with different versions of OVSDB schemas and data‐
160 bases.
161 convert [db [schema [target]]]
163 Reads db, translating it into to the schema specified in schema,
164 and writes out the new interpretation. If target is specified,
165 the translated version is written as a new file named target,
166 which must not already exist. If target is omitted, then the
167 translated version of the database replaces db in-place. In-
168 place conversion cannot take place if the database is currently
169 being served by ovsdb-server (instead, either stop ovsdb-server
170 first or use ovsdb-client's convert command).
171 This command can do simple ``upgrades'' and ``downgrades'' on a
173 database's schema. The data in db must be valid when inter‐
174 preted under schema, with only one exception: data in db for
175 tables and columns that do not exist in schema are ignored.
176 Columns that exist in schema but not in db are set to their
177 default values. All of schema's constraints apply in full.
178 Some uses of this command can cause unrecoverable data loss.
180 For example, converting a database from a schema that has a
181 given column or table to one that does not will delete all data
182 in that column or table. Back up critical databases before con‐
183 verting them.
184 This command is for standalone and active-backup databases only.
186 For clustered databases, use ovsdb-client's convert command to
187 convert them online.
188 needs-conversion [db [schema]]
190 Reads the schema embedded in db and the JSON schema from schema
191 and compares them. If the schemas are the same, prints no on
192 stdout; if they differ, prints yes.
193 This command is for standalone and active-backup databases only.
195 For clustered databases, use ovsdb-client's needs-conversion
196 command instead.
197 db-version [db]
199 schema-version [schema]
200 Prints the version number in the schema embedded within the
201 database db or in the JSON schema schema on stdout. If schema
202 or db was created before schema versioning was introduced, then
203 it will not have a version number and this command will print a
204 blank line.
205 The db-version command is for standalone and active-backup data‐
207 bases only. For clustered databases, use ovsdb-client's
208 schema-version command instead.
209 db-cksum [db]
211 schema-cksum [schema]
212 Prints the checksum in the schema embedded within the database
213 db or of the JSON schema schema on stdout. If schema or db was
214 created before schema checksums were introduced, then it will
215 not have a checksum and this command will print a blank line.
216 The db-cksum command is for standalone and active-backup data‐
218 bases only. For clustered databases, use ovsdb-client's
219 schema-cksum command instead.
220 compare-versions a op b
222 Compares a and b according to op. Both a and b must be OVSDB
223 schema version numbers in the form x.y.z, as described in
224 ovsdb(7), and op must be one of < <= == >= > !=. If the compar‐
225 ison is true, exits with status 0; if it is false, exits with
226 status 2. (Exit status 1 indicates an error, e.g. a or b is the
227 wrong syntax for an OVSDB version or op is not a valid compari‐
228 son operator.)
229 Other Commands
231 compact [db [target]]
232 Reads db and writes a compacted version. If target is speci‐
233 fied, the compacted version is written as a new file named tar‐
234 get, which must not already exist. If target is omitted, then
235 the compacted version of the database replaces db in-place.
236 This command is not needed in normal operation because
237 ovsdb-server from time to time automatically compacts a database
238 that grows much larger than its minimum size.
239 This command does not work if db is currently being served by
241 ovsdb-server, or if it is otherwise locked for writing by
242 another process. This command also does not work with clustered
243 databases. Instead, in either case, send the ovsdb-server/com‐
244 pact command to ovsdb-server, via ovs-appctl).
245 [--rbac-role=role] query [db] transaction
247 Opens db, executes transaction on it, and prints the results.
248 The transaction must be a JSON array in the format of the params
249 array for the JSON-RPC transact method, as described in the
250 OVSDB specification.
251 This command opens db for read-only access, so it may safely run
253 concurrently with other database activity, including
254 ovsdb-server and other database writers. The transaction may
255 specify database modifications, but these will have no effect on
256 db.
257 By default, the transaction is executed using the ``superuser''
259 RBAC role. Use --rbac-role to specify a different role.
260 This command does not work with clustered databases. Instead,
262 use ovsdb-client's query command to send the query to
263 ovsdb-server.
264 [--rbac-role=role] transact [db] transaction
266 Opens db, executes transaction on it, prints the results, and
267 commits any changes to db. The transaction must be a JSON array
268 in the format of the params array for the JSON-RPC transact
269 method, as described in the OVSDB specification.
270 This command does not work if db is currently being served by
272 ovsdb-server, or if it is otherwise locked for writing by
273 another process. This command also does not work with clustered
274 databases. Instead, in either case, use ovsdb-client's transact
275 command to send the query to ovsdb-server.
276 By default, the transaction is executed using the ``superuser''
278 RBAC role. Use --rbac-role to specify a different role.
279 [-m | --more]... show-log [db]
281 Prints a summary of the records in db's log, including the time
282 and date at which each database change occurred and any associ‐
283 ated comment. This may be useful for debugging.
284 To increase the verbosity of output, add -m (or --more) one or
286 more times to the command line. With one -m, show-log prints a
287 summary of the records added, deleted, or modified by each
288 transaction. With two -ms, show-log also prints the values of
289 the columns modified by each change to a record.
290 This command works with standalone and active-backup databases
292 and with clustered databases, but the output formats are differ‐
293 ent.
294 check-cluster db...
296 Reads all of the records in the supplied databases, which must
297 be collected from different servers (and ideally all the
298 servers) in a single cluster. Checks each database for self-
299 consistency and the set together for cross-consistency. If
300 ovsdb-tool detects unusual but not necessarily incorrect con‐
301 tent, it prints a warning or warnings on stdout. If ovsdb-tool
302 find consistency errors, it prints an error on stderr and exits
303 with status 1. Errors typically indicate bugs in ovsdb-server;
304 please consider reporting them to the Open vSwitch developers.
305 db-name [db]
307 schema-name [schema]
308 Prints the name of the schema embedded within the database db or
309 in the JSON schema schema on stdout.
310 db-cid db
312 Prints the cluster ID, which is a UUID that identifies the clus‐
313 ter, for db. If db is a database newly created by ovsdb-tool
314 cluster-join that has not yet successfully joined its cluster,
315 and --cid was not specified on the cluster-join command line,
316 then this command will output an error, and exit with status 2,
317 because the cluster ID is not yet known. This command works
318 only with clustered databases.
319 The all-zeros UUID is not a valid cluster ID.
321 db-sid db
323 Prints the server ID, which is a UUID that identifies the
324 server, for db. This command works only with clustered data‐
325 bases. It works even if db is a database newly created by
326 ovsdb-tool cluster-join that has not yet successfully joined its
327 cluster.
328 db-local-address db
330 Prints the local address used for database clustering for db, in
331 the same protocol:ip:port form used on create-cluster and
332 join-cluster.
333 db-is-clustered db
335 db-is-standalone db
336 Tests whether db is a database file in clustered or standalone
337 format, respectively. If so, exits with status 0; if not, exits
338 with status 2. (Exit status 1 indicates an error, e.g. db is
339 not an OVSDB database or does not exist.)
340
342 Logging Options
343 -v[spec]
344 --verbose=[spec]
345 Sets logging levels. Without any spec, sets the log level for
346 every module and destination to dbg. Otherwise, spec is a list
347 of words separated by spaces or commas or colons, up to one from
348 each category below:
349 · A valid module name, as displayed by the vlog/list com‐
351 mand on ovs-appctl(8), limits the log level change to the
352 specified module.
353 · syslog, console, or file, to limit the log level change
355 to only to the system log, to the console, or to a file,
356 respectively. (If --detach is specified, ovsdb-tool
357 closes its standard file descriptors, so logging to the
358 console will have no effect.)
359 On Windows platform, syslog is accepted as a word and is
361 only useful along with the --syslog-target option (the
362 word has no effect otherwise).
363 · off, emer, err, warn, info, or dbg, to control the log
365 level. Messages of the given severity or higher will be
366 logged, and messages of lower severity will be filtered
367 out. off filters out all messages. See ovs-appctl(8)
368 for a definition of each log level.
369 Case is not significant within spec.
371 Regardless of the log levels set for file, logging to a file
373 will not take place unless --log-file is also specified (see
374 below).
375 For compatibility with older versions of OVS, any is accepted as
377 a word but has no effect.
378 -v
380 --verbose
381 Sets the maximum logging verbosity level, equivalent to --ver‐
382 bose=dbg.
383 -vPATTERN:destination:pattern
385 --verbose=PATTERN:destination:pattern
386 Sets the log pattern for destination to pattern. Refer to
387 ovs-appctl(8) for a description of the valid syntax for pattern.
388 -vFACILITY:facility
390 --verbose=FACILITY:facility
391 Sets the RFC5424 facility of the log message. facility can be
392 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
393 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
394 local3, local4, local5, local6 or local7. If this option is not
395 specified, daemon is used as the default for the local system
396 syslog and local0 is used while sending a message to the target
397 provided via the --syslog-target option.
398 --log-file[=file]
400 Enables logging to a file. If file is specified, then it is
401 used as the exact name for the log file. The default log file
402 name used if file is omitted is /var/log/open‐
403 vswitch/ovsdb-tool.log.
404 --syslog-target=host:port
406 Send syslog messages to UDP port on host, in addition to the
407 system syslog. The host must be a numerical IP address, not a
408 hostname.
409 --syslog-method=method
411 Specify method how syslog messages should be sent to syslog dae‐
412 mon. Following forms are supported:
413 · libc, use libc syslog() function. Downside of using this
415 options is that libc adds fixed prefix to every message
416 before it is actually sent to the syslog daemon over
417 /dev/log UNIX domain socket.
418 · unix:file, use UNIX domain socket directly. It is possi‐
420 ble to specify arbitrary message format with this option.
421 However, rsyslogd 8.9 and older versions use hard coded
422 parser function anyway that limits UNIX domain socket
423 use. If you want to use arbitrary message format with
424 older rsyslogd versions, then use UDP socket to localhost
425 IP address instead.
426 · udp:ip:port, use UDP socket. With this method it is pos‐
428 sible to use arbitrary message format also with older
429 rsyslogd. When sending syslog messages over UDP socket
430 extra precaution needs to be taken into account, for
431 example, syslog daemon needs to be configured to listen
432 on the specified UDP port, accidental iptables rules
433 could be interfering with local syslog traffic and there
434 are some security considerations that apply to UDP sock‐
435 ets, but do not apply to UNIX domain sockets.
436 · null, discards all messages logged to syslog.
438 The default is taken from the OVS_SYSLOG_METHOD environment
440 variable; if it is unset, the default is libc.
441 Other Options
443 -h
444 --help Prints a brief help message to the console.
445 -V
447 --version
448 Prints version information to the console.
449
451 The default db is /etc/openvswitch/conf.db. The default schema is
452 /usr/share/openvswitch/vswitch.ovsschema. The help command also dis‐
453 plays these defaults.
454
456 ovsdb(7), ovsdb-server(1), ovsdb-client(1).
457Open vSwitch 2.12.0 ovsdb-tool(1)