1ovsdb-tool(1)                 Open vSwitch Manual                ovsdb-tool(1)
2
3
4

NAME

6       ovsdb-tool - Open vSwitch database management utility
7

SYNOPSIS

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
15       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
24       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
38       Logging options:
39              [-v[module[:destination[:level]]]]...
40              [--verbose[=module[:destination[:level]]]]...
41              [--log-file[=file]]
42
43       Common options:
44              [-h | --help] [-V | --version]
45
46

DESCRIPTION

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
54       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
59       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
67   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
72       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
81       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
96              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
103       [--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
112              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
118              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
126              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
132              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
140   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
153       Some OVSDB databases and schemas, especially very old ones, do not have
154       a version number.
155
156       Schema version numbers and Open vSwitch version  numbers  are  indepen‐
157       dent.
158
159       These  commands work with different versions of OVSDB schemas and data‐
160       bases.
161
162       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
172              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
179              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
185              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
189       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
194              This command is for standalone and active-backup databases only.
195              For  clustered  databases,  use  ovsdb-client's needs-conversion
196              command instead.
197
198       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
206              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
210       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
217              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
221       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
230   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
240              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
246       [--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
252              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
258              By default, the transaction is executed using the  ``superuser''
259              RBAC role.  Use --rbac-role to specify a different role.
260
261              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
265       [--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
271              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
277              By default, the transaction is executed using the  ``superuser''
278              RBAC role.  Use --rbac-role to specify a different role.
279
280       [-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
285              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
291              This  command  works with standalone and active-backup databases
292              and with clustered databases, but the output formats are differ‐
293              ent.
294
295       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
306       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
311       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
320              The all-zeros UUID is not a valid cluster ID.
321
322       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
329       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
334       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

OPTIONS

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
350              ·      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
354              ·      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
360                     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
364              ·      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
370              Case is not significant within spec.
371
372              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
376              For compatibility with older versions of OVS, any is accepted as
377              a word but has no effect.
378
379       -v
380       --verbose
381              Sets  the  maximum logging verbosity level, equivalent to --ver‐
382              bose=dbg.
383
384       -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
389       -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
399       --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
405       --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
410       --syslog-method=method
411              Specify method how syslog messages should be sent to syslog dae‐
412              mon.  Following forms are supported:
413
414              ·      libc,  use  libc  syslog() function.  This is the default
415                     behavior.  Downside of using this options  is  that  libc
416                     adds  fixed prefix to every message before it is actually
417                     sent to the  syslog  daemon  over  /dev/log  UNIX  domain
418                     socket.
419
420              ·      unix:file, use UNIX domain socket directly.  It is possi‐
421                     ble to specify arbitrary message format with this option.
422                     However,  rsyslogd  8.9 and older versions use hard coded
423                     parser function anyway that  limits  UNIX  domain  socket
424                     use.   If  you  want to use arbitrary message format with
425                     older rsyslogd versions, then use UDP socket to localhost
426                     IP address instead.
427
428              ·      udp:ip:port, use UDP socket.  With this method it is pos‐
429                     sible to use arbitrary message  format  also  with  older
430                     rsyslogd.   When  sending syslog messages over UDP socket
431                     extra precaution needs to  be  taken  into  account,  for
432                     example,  syslog  daemon needs to be configured to listen
433                     on the specified  UDP  port,  accidental  iptables  rules
434                     could  be interfering with local syslog traffic and there
435                     are some security considerations that apply to UDP  sock‐
436                     ets, but do not apply to UNIX domain sockets.
437
438   Other Options
439       -h
440       --help Prints a brief help message to the console.
441
442       -V
443       --version
444              Prints version information to the console.
445

FILES

447       The  default  db  is  /etc/openvswitch/conf.db.   The default schema is
448       /usr/share/openvswitch/vswitch.ovsschema.  The help command  also  dis‐
449       plays these defaults.
450

SEE ALSO

452       ovsdb(7), ovsdb-server(1), ovsdb-client(1).
453
454
455
456Open vSwitch                        2.10.1                       ovsdb-tool(1)
Impressum