ovsdb-tool(1)                 Open vSwitch Manual                ovsdb-tool(1)



NAME
       ovsdb-tool - Open vSwitch database management utility

SYNOPSIS
       Database Creation Commands:
              ovsdb-tool [options] create [db [schema]]
              ovsdb-tool  [options]  [--election-timer=ms]  create-cluster  db
              contents address
              ovsdb-tool [options] [--cid=uuid] join-cluster db name local re‐
              mote...

       Version Management Commands:
              ovsdb-tool [options] convert [db [schema [target]]]
              ovsdb-tool [options] needs-conversion [db [schema]]
              ovsdb-tool [options] db-version [db]
              ovsdb-tool [options] schema-version [schema]
              ovsdb-tool [options] db-cksum [db]
              ovsdb-tool [options] schema-cksum [schema]
              ovsdb-tool [options] compare-versions a op b

       Other commands:
              ovsdb-tool [options] compact [db [target]]
              ovsdb-tool [options] [--rbac-role=role] query [db] transaction
              ovsdb-tool  [options]  [--rbac-role=role] transact [db] transac‐
              tion
              ovsdb-tool [options] [-m | --more]... show-log [db]
              ovsdb-tool [options] check-cluster db...
              ovsdb-tool [options] db-name [db]
              ovsdb-tool [options] schema-name [schema]
              ovsdb-tool [options] db-cid db
              ovsdb-tool [options] db-sid db
              ovsdb-tool [options] db-local-address db
              ovsdb-tool help

       Logging options:
              [-v[module[:destination[:level]]]]...
              [--verbose[=module[:destination[:level]]]]...
              [--log-file[=file]]

       Common options:
              [-h | --help] [-V | --version]


DESCRIPTION
       The ovsdb-tool program is a command-line tool for managing Open vSwitch
       database  (OVSDB)  files.   It  does not interact directly with running
       Open vSwitch database servers (instead, use ovsdb-client).  For an  in‐
       troduction  to  OVSDB  and  its  implementation  in  Open  vSwitch, see
       ovsdb(7).

       Each command that takes an optional db or schema argument has a default
       file  location  if  it  is  not specified..  The default db is /usr/lo‐
       cal/etc/openvswitch/conf.db.    The   default   schema   is    /usr/lo‐
       cal/share/openvswitch/vswitch.ovsschema.

       This  OVSDB  implementation supports standalone and active-backup data‐
       base service models with one on-disk format and  a  clustered  database
       service  model  with a different format.  ovsdb-tool supports both for‐
       mats, but some commands are appropriate for only one format,  as  docu‐
       mented  for  individual  commands  below.  For a specification of these
       formats, see ovsdb(5).  For more information on OVSDB  service  models,
       see the Service Models section in ovsdb(7).

   Database Creation Commands
       These  commands  create a new OVSDB database file.  They will not over‐
       write an existing database file.  To replace an existing database  with
       a new one, first delete the old one.

       create [db [schema]]
              Use   this  command  to  create  the  database  for  controlling
              ovs-vswitchd or another standalone  or  active-backup  database.
              It creates database file db with the given schema, which must be
              the name of a file that contains an OVSDB schema in JSON format,
              as  specified  in  the OVSDB specification.  The new database is
              initially empty.  (You can use cp to copy a  database  including
              both its schema and data.)

       [--election-timer=ms] create-cluster db contents local
              Use this command to initialize the first server in a high-avail‐
              ability cluster of 3 (or more)  database  servers,  e.g.  for  a
              database  in  an environment that cannot tolerate a single point
              of failure.  It creates clustered database file db  and  config‐
              ures  the  server  to  listen on local, which must take the form
              protocol:ip:port, where protocol  is  tcp  or  ssl,  ip  is  the
              server's  IP (either an IPv4 address or an IPv6 address enclosed
              in square brackets), and port is a TCP port  number.   Only  one
              address is specified, for the first server in the cluster, ordi‐
              narily the one for the server running create-cluster.   The  ad‐
              dress is used for communication within the cluster, not for com‐
              municating with OVSDB clients, and must not use  the  same  port
              used for the OVSDB protocol.

              The new database is initialized with contents, which must name a
              file that contains either an OVSDB schema in JSON  format  or  a
              standalone  OVSDB  database.   If  it  is a schema file, the new
              database will initially be empty, with the given schema.  If  it
              is  a  database file, the new database will have the same schema
              and contents.

              Leader election will be initiated by a follower if there  is  no
              heartbeat  received from the cluster leader within the specified
              election timer.  The default leader election timer is 1000  mil‐
              liseconds.  To use a different value when creating the database,
              specify --election-timer=ms, where ms is a value in milliseconds
              between 100 and 600000 inclusive.

       [--cid=uuid] join-cluster db name local remote...
              Use  this  command to initialize each server after the first one
              in an OVSDB high-availability  cluster.   It  creates  clustered
              database  file  db for a database named name, and configures the
              server to listen on local and to initially  connect  to  remote,
              which must be a server that already belongs to the cluster.  lo‐
              cal and remote use the  same  protocol:ip:port  syntax  as  cre‐
              ate-cluster.

              The  name  must  be the name of the schema or database passed to
              create-cluster.  For example, the name  of  the  OVN  Southbound
              database schema is OVN_Southbound.  Use ovsdb-tool's schema-name
              or db-name command to find out the name of a schema or database,
              respectively.

              This command does not do any network access, which means that it
              cannot actually join the new server to  the  cluster.   Instead,
              the  db  file  that  it  creates prepares the server to join the
              cluster the first time that ovsdb-server serves it.  As part  of
              joining  the  cluster,  the  new  server  retrieves the database
              schema and obtains the list of all cluster members.  Only  after
              that does it become a full member of the cluster.

              Optionally,  more than one remote may be specified; for example,
              in a cluster that already contains multiple servers,  one  could
              specify all the existing servers.  This is beneficial if some of
              the existing servers are down while the new server joins, but it
              is not otherwise needed.

              By  default,  the db created by join-cluster will join any clus‐
              tered database named name that is available  at  a  remote.   In
              theory,  if  machines  go up and down and IP addresses change in
              the right way, it could join the  wrong  database  cluster.   To
              avoid  this  possibility,  specify --cid=uuid, where uuid is the
              cluster ID of the cluster to  join,  as  printed  by  ovsdb-tool
              get-cid.

   Database Migration Commands
       This commands will convert cluster database to standalone database.

       cluster-to-standalone db clusterdb
              Use  this  command  to convert to standalone database from clus‐
              tered database when the cluster is down and cannot  be  revived.
              It  creates  new  standalone  db  file from the given cluster db
              file.

   Version Management Commands
       An OVSDB schema has a schema version number, and an OVSDB database  em‐
       beds  a  particular  version of an OVSDB schema.  These version numbers
       take the form x.y.z, e.g. 1.2.3.  The OVSDB implementation does not en‐
       force a particular version numbering scheme, but schemas managed within
       the Open vSwitch project use  the  following  approach.   Whenever  the
       database  schema  is  changed  in  a  non-backward compatible way (e.g.
       deleting a column or a table), x is incremented (and y and z are  reset
       to  0).   When  the database schema is changed in a backward compatible
       way (e.g. adding a new column), y is incremented (and z is reset to 0).
       When  the database schema is changed cosmetically (e.g. reindenting its
       syntax), z is incremented.

       Some OVSDB databases and schemas, especially very old ones, do not have
       a version number.

       Schema  version  numbers  and Open vSwitch version numbers are indepen‐
       dent.

       These commands work with different versions of OVSDB schemas and  data‐
       bases.

       convert [db [schema [target]]]
              Reads db, translating it into to the schema specified in schema,
              and writes out the new interpretation.  If target is  specified,
              the  translated  version  is written as a new file named target,
              which must not already exist.  If target is  omitted,  then  the
              translated  version  of  the database replaces db in-place.  In-
              place conversion cannot take place if the database is  currently
              being  served by ovsdb-server (instead, either stop ovsdb-server
              first or use ovsdb-client's convert command).

              This command can do simple ``upgrades'' and ``downgrades'' on  a
              database's  schema.   The  data  in db must be valid when inter‐
              preted under schema, with only one exception: data in db for ta‐
              bles  and columns that do not exist in schema are ignored.  Col‐
              umns that exist in schema but not in db are set to their default
              values.  All of schema's constraints apply in full.

              Some  uses  of  this  command can cause unrecoverable data loss.
              For example, converting a database from  a  schema  that  has  a
              given  column or table to one that does not will delete all data
              in that column or table.  Back up critical databases before con‐
              verting them.

              This command is for standalone and active-backup databases only.
              For clustered databases, use ovsdb-client's convert  command  to
              convert them online.

       needs-conversion [db [schema]]
              Reads  the schema embedded in db and the JSON schema from schema
              and compares them.  If the schemas are the same,  prints  no  on
              stdout; if they differ, prints yes.

              This command is for standalone and active-backup databases only.
              For clustered  databases,  use  ovsdb-client's  needs-conversion
              command instead.

       db-version [db]
       schema-version [schema]
              Prints  the  version  number  in  the schema embedded within the
              database db or in the JSON schema schema on stdout.   If  schema
              or  db was created before schema versioning was introduced, then
              it will not have a version number and this command will print  a
              blank line.

              The db-version command is for standalone and active-backup data‐
              bases  only.   For  clustered  databases,   use   ovsdb-client's
              schema-version command instead.

       db-cksum [db]
       schema-cksum [schema]
              Prints  the  checksum in the schema embedded within the database
              db or of the JSON schema schema on stdout.  If schema or db  was
              created  before  schema  checksums were introduced, then it will
              not have a checksum and this command will print a blank line.

              The db-cksum command is for standalone and  active-backup  data‐
              bases   only.    For  clustered  databases,  use  ovsdb-client's
              schema-cksum command instead.

       compare-versions a op b
              Compares a and b according to op.  Both a and b  must  be  OVSDB
              schema  version  numbers  in  the  form  x.y.z,  as described in
              ovsdb(7), and op must be one of < <= == >= > !=.  If the compar‐
              ison  is  true,  exits with status 0; if it is false, exits with
              status 2.  (Exit status 1 indicates an error, e.g. a or b is the
              wrong  syntax for an OVSDB version or op is not a valid compari‐
              son operator.)

   Other Commands
       compact [db [target]]
              Reads db and writes a compacted version.  If  target  is  speci‐
              fied,  the compacted version is written as a new file named tar‐
              get, which must not already exist.  If target is  omitted,  then
              the  compacted  version  of  the  database replaces db in-place.
              This  command  is  not  needed  in  normal   operation   because
              ovsdb-server from time to time automatically compacts a database
              that grows much larger than its minimum size.

              This command does not work if db is currently  being  served  by
              ovsdb-server,  or  if  it is otherwise locked for writing by an‐
              other process.  This command also does not work  with  clustered
              databases.   Instead, in either case, send the ovsdb-server/com‐
              pact command to ovsdb-server, via ovs-appctl).

       [--rbac-role=role] query [db] transaction
              Opens db, executes transaction on it, and  prints  the  results.
              The transaction must be a JSON array in the format of the params
              array for the JSON-RPC transact  method,  as  described  in  the
              OVSDB specification.

              This command opens db for read-only access, so it may safely run
              concurrently   with   other   database    activity,    including
              ovsdb-server  and  other  database writers.  The transaction may
              specify database modifications, but these will have no effect on
              db.

              By  default, the transaction is executed using the ``superuser''
              RBAC role.  Use --rbac-role to specify a different role.

              This command does not work with clustered  databases.   Instead,
              use   ovsdb-client's   query   command  to  send  the  query  to
              ovsdb-server.

       [--rbac-role=role] transact [db] transaction
              Opens db, executes transaction on it, prints  the  results,  and
              commits any changes to db.  The transaction must be a JSON array
              in the format of the params  array  for  the  JSON-RPC  transact
              method, as described in the OVSDB specification.

              This  command  does  not work if db is currently being served by
              ovsdb-server, or if it is otherwise locked for  writing  by  an‐
              other  process.   This command also does not work with clustered
              databases.  Instead, in either case, use ovsdb-client's transact
              command to send the query to ovsdb-server.

              By  default, the transaction is executed using the ``superuser''
              RBAC role.  Use --rbac-role to specify a different role.

       [-m | --more]... show-log [db]
              Prints a summary of the records in db's log, including the  time
              and  date at which each database change occurred and any associ‐
              ated comment.  This may be useful for debugging.

              To increase the verbosity of output, add -m (or --more)  one  or
              more  times to the command line.  With one -m, show-log prints a
              summary of the records  added,  deleted,  or  modified  by  each
              transaction.   With  two -ms, show-log also prints the values of
              the columns modified by each change to a record.

              This command works with standalone and  active-backup  databases
              and with clustered databases, but the output formats are differ‐
              ent.

       check-cluster db...
              Reads all of the records in the supplied databases,  which  must
              be  collected  from  different  servers  (and  ideally  all  the
              servers) in a single cluster.  Checks each  database  for  self-
              consistency  and  the  set  together  for cross-consistency.  If
              ovsdb-tool detects unusual but not  necessarily  incorrect  con‐
              tent,  it prints a warning or warnings on stdout.  If ovsdb-tool
              find consistency errors, it prints an error on stderr and  exits
              with  status 1.  Errors typically indicate bugs in ovsdb-server;
              please consider reporting them to the Open vSwitch developers.

       db-name [db]
       schema-name [schema]
              Prints the name of the schema embedded within the database db or
              in the JSON schema schema on stdout.

       db-cid db
              Prints the cluster ID, which is a UUID that identifies the clus‐
              ter, for db.  If db is a database newly  created  by  ovsdb-tool
              cluster-join  that  has not yet successfully joined its cluster,
              and --cid was not specified on the  cluster-join  command  line,
              then  this command will output an error, and exit with status 2,
              because the cluster ID is not yet  known.   This  command  works
              only with clustered databases.

              The all-zeros UUID is not a valid cluster ID.

       db-sid db
              Prints  the  server  ID,  which  is  a  UUID that identifies the
              server, for db.  This command works only  with  clustered  data‐
              bases.   It  works  even  if  db  is a database newly created by
              ovsdb-tool cluster-join that has not yet successfully joined its
              cluster.

       db-local-address db
              Prints the local address used for database clustering for db, in
              the  same  protocol:ip:port  form  used  on  create-cluster  and
              join-cluster.

       db-is-clustered db
       db-is-standalone db
              Tests  whether  db is a database file in clustered or standalone
              format, respectively.  If so, exits with status 0; if not, exits
              with  status  2.   (Exit status 1 indicates an error, e.g. db is
              not an OVSDB database or does not exist.)

OPTIONS
   Logging Options
       -v[spec]
       --verbose=[spec]
              Sets logging levels.  Without any spec, sets the log  level  for
              every  module and destination to dbg.  Otherwise, spec is a list
              of words separated by spaces or commas or colons, up to one from
              each category below:

              •      A  valid  module name, as displayed by the vlog/list com‐
                     mand on ovs-appctl(8), limits the log level change to the
                     specified module.

              •      syslog,  console,  or file, to limit the log level change
                     to only to the system log, to the console, or to a  file,
                     respectively.   (If  --detach  is  specified,  ovsdb-tool
                     closes its standard file descriptors, so logging  to  the
                     console will have no effect.)

                     On  Windows platform, syslog is accepted as a word and is
                     only useful along with the  --syslog-target  option  (the
                     word has no effect otherwise).

              •      off,  emer,  err,  warn, info, or dbg, to control the log
                     level.  Messages of the given severity or higher will  be
                     logged,  and  messages of lower severity will be filtered
                     out.  off filters out all  messages.   See  ovs-appctl(8)
                     for a definition of each log level.

              Case is not significant within spec.

              Regardless  of  the  log  levels set for file, logging to a file
              will not take place unless --log-file is also specified (see be‐
              low).

              For compatibility with older versions of OVS, any is accepted as
              a word but has no effect.

       -v
       --verbose
              Sets the maximum logging verbosity level, equivalent  to  --ver‐
              bose=dbg.

       -vPATTERN:destination:pattern
       --verbose=PATTERN:destination:pattern
              Sets  the  log  pattern  for  destination  to pattern.  Refer to
              ovs-appctl(8) for a description of the valid syntax for pattern.

       -vFACILITY:facility
       --verbose=FACILITY:facility
              Sets the RFC5424 facility of the log message.  facility  can  be
              one  of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
              clock, ftp, ntp, audit, alert, clock2, local0,  local1,  local2,
              local3,  local4, local5, local6 or local7. If this option is not
              specified, daemon is used as the default for  the  local  system
              syslog  and local0 is used while sending a message to the target
              provided via the --syslog-target option.

       --log-file[=file]
              Enables logging to a file.  If file is  specified,  then  it  is
              used  as  the exact name for the log file.  The default log file
              name  used  if  file  is  omitted  is   /usr/local/var/log/open‐
              vswitch/ovsdb-tool.log.

       --syslog-target=host:port
              Send  syslog  messages  to  UDP port on host, in addition to the
              system syslog.  The host must be a numerical IP address,  not  a
              hostname.

       --syslog-method=method
              Specify method how syslog messages should be sent to syslog dae‐
              mon.  Following forms are supported:

              •      libc, use libc syslog() function.  Downside of using this
                     options  is  that libc adds fixed prefix to every message
                     before it is actually sent  to  the  syslog  daemon  over
                     /dev/log UNIX domain socket.

              •      unix:file, use UNIX domain socket directly.  It is possi‐
                     ble to specify arbitrary message format with this option.
                     However,  rsyslogd  8.9 and older versions use hard coded
                     parser function anyway that  limits  UNIX  domain  socket
                     use.   If  you  want to use arbitrary message format with
                     older rsyslogd versions, then use UDP socket to localhost
                     IP address instead.

              •      udp:ip:port, use UDP socket.  With this method it is pos‐
                     sible to use arbitrary message  format  also  with  older
                     rsyslogd.   When  sending syslog messages over UDP socket
                     extra precaution needs to be taken into account, for  ex‐
                     ample,  syslog daemon needs to be configured to listen on
                     the specified UDP port, accidental iptables  rules  could
                     be  interfering  with  local syslog traffic and there are
                     some security considerations that apply to  UDP  sockets,
                     but do not apply to UNIX domain sockets.

              •      null, discards all messages logged to syslog.

              The  default  is  taken  from  the OVS_SYSLOG_METHOD environment
              variable; if it is unset, the default is libc.

   Other Options
       -h
       --help Prints a brief help message to the console.

       -V
       --version
              Prints version information to the console.

FILES
       The default  db  is  /usr/local/etc/openvswitch/conf.db.   The  default
       schema  is  /usr/local/share/openvswitch/vswitch.ovsschema.   The  help
       command also displays these defaults.

SEE ALSO
       ovsdb(7), ovsdb-server(1), ovsdb-client(1).



Open vSwitch                         3.3.0                       ovsdb-tool(1)