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 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
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   Database Migration Commands
141       This commands will convert cluster database to standalone database.
142
143       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
149   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
162       Some OVSDB databases and schemas, especially very old ones, do not have
163       a version number.
164
165       Schema  version  numbers  and Open vSwitch version numbers are indepen‐
166       dent.
167
168       These commands work with different versions of OVSDB schemas and  data‐
169       bases.
170
171       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
181              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
188              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
194              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
198       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
203              This command is for standalone and active-backup databases only.
204              For clustered  databases,  use  ovsdb-client's  needs-conversion
205              command instead.
206
207       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
215              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
219       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
226              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
230       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
239   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
249              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
255       [--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
261              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
267              By  default, the transaction is executed using the ``superuser''
268              RBAC role.  Use --rbac-role to specify a different role.
269
270              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
274       [--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
280              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
286              By  default, the transaction is executed using the ``superuser''
287              RBAC role.  Use --rbac-role to specify a different role.
288
289       [-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
294              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
300              This command works with standalone and  active-backup  databases
301              and with clustered databases, but the output formats are differ‐
302              ent.
303
304       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
315       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
320       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
329              The all-zeros UUID is not a valid cluster ID.
330
331       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
338       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
343       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

OPTIONS

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
359              ·      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
363              ·      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
369                     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
373              ·      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
379              Case is not significant within spec.
380
381              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
385              For compatibility with older versions of OVS, any is accepted as
386              a word but has no effect.
387
388       -v
389       --verbose
390              Sets the maximum logging verbosity level, equivalent  to  --ver‐
391              bose=dbg.
392
393       -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
398       -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
408       --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
414       --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
419       --syslog-method=method
420              Specify method how syslog messages should be sent to syslog dae‐
421              mon.  Following forms are supported:
422
423              ·      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
428              ·      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
436              ·      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
446              ·      null, discards all messages logged to syslog.
447
448              The  default  is  taken  from  the OVS_SYSLOG_METHOD environment
449              variable; if it is unset, the default is libc.
450
451   Other Options
452       -h
453       --help Prints a brief help message to the console.
454
455       -V
456       --version
457              Prints version information to the console.
458

FILES

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

SEE ALSO

465       ovsdb(7), ovsdb-server(1), ovsdb-client(1).
466
467
468
469Open vSwitch                        2.15.0                       ovsdb-tool(1)
Impressum