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]  [--election-timer=ms]  create-cluster  db
12              contents address
13              ovsdb-tool [options] [--cid=uuid] join-cluster db name local re‐
14              mote...
15
16       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
25       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
39       Logging options:
40              [-v[module[:destination[:level]]]]...
41              [--verbose[=module[:destination[:level]]]]...
42              [--log-file[=file]]
43
44       Common options:
45              [-h | --help] [-V | --version]
46
47

DESCRIPTION

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
55       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
60       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
68   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
73       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
82       [--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
97              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
104              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
111       [--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
120              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
126              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
134              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
140              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
148   Database Migration Commands
149       This commands will convert cluster database to standalone database.
150
151       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
157   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
170       Some OVSDB databases and schemas, especially very old ones, do not have
171       a version number.
172
173       Schema  version  numbers  and Open vSwitch version numbers are indepen‐
174       dent.
175
176       These commands work with different versions of OVSDB schemas and  data‐
177       bases.
178
179       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
189              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
196              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
202              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
206       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
211              This command is for standalone and active-backup databases only.
212              For clustered  databases,  use  ovsdb-client's  needs-conversion
213              command instead.
214
215       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
223              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
227       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
234              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
238       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
247   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
257              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
263       [--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
269              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
275              By  default, the transaction is executed using the ``superuser''
276              RBAC role.  Use --rbac-role to specify a different role.
277
278              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
282       [--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
288              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
294              By  default, the transaction is executed using the ``superuser''
295              RBAC role.  Use --rbac-role to specify a different role.
296
297       [-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
302              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
308              This command works with standalone and  active-backup  databases
309              and with clustered databases, but the output formats are differ‐
310              ent.
311
312       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
323       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
328       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
337              The all-zeros UUID is not a valid cluster ID.
338
339       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
346       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
351       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

OPTIONS

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
367              •      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
371syslog,  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
377                     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
381off,  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
387              Case is not significant within spec.
388
389              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
393              For compatibility with older versions of OVS, any is accepted as
394              a word but has no effect.
395
396       -v
397       --verbose
398              Sets the maximum logging verbosity level, equivalent  to  --ver‐
399              bose=dbg.
400
401       -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
406       -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
416       --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
422       --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
427       --syslog-method=method
428              Specify method how syslog messages should be sent to syslog dae‐
429              mon.  Following forms are supported:
430
431libc, 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
436unix: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
444udp: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
454null, discards all messages logged to syslog.
455
456              The  default  is  taken  from  the OVS_SYSLOG_METHOD environment
457              variable; if it is unset, the default is libc.
458
459   Other Options
460       -h
461       --help Prints a brief help message to the console.
462
463       -V
464       --version
465              Prints version information to the console.
466

FILES

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

SEE ALSO

473       ovsdb(7), ovsdb-server(1), ovsdb-client(1).
474
475
476
477Open vSwitch                         3.2.0                       ovsdb-tool(1)
Impressum