Provided by: openvswitch-common_3.3.0-1ubuntu3_amd64 bug

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 remote...

       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] transaction
              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 introduction 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 /etc/openvswitch/conf.db.  The default schema is
       /usr/share/openvswitch/vswitch.ovsschema.

       This OVSDB implementation supports standalone and active-backup  database  service  models
       with  one  on-disk  format and a clustered database service model with a different format.
       ovsdb-tool supports both formats, but some commands are appropriate for only  one  format,
       as  documented  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 overwrite 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-availability 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
              configures   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,
              ordinarily  the one for the server running create-cluster.  The address is used for
              communication within the cluster, not for communicating  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 milliseconds. 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.  local and
              remote use the same protocol:ip:port syntax as create-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 clustered 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 clustered 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 embeds 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 enforce 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 independent.

       These commands work with different versions of OVSDB schemas and databases.

       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  interpreted  under  schema, with only one
              exception: data in db for tables and columns  that  do  not  exist  in  schema  are
              ignored.   Columns  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 converting 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 databases 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 databases 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 comparison 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 comparison operator.)

   Other Commands
       compact [db [target]]
              Reads db and writes a compacted version.  If target  is  specified,  the  compacted
              version  is  written  as a new file named target, 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 another process.  This command also does  not
              work   with   clustered   databases.    Instead,   in   either   case,   send   the
              ovsdb-server/compact 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 another 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 associated 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 different.

       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  content,  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 cluster, 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 databases.  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 command 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 below).

              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 --verbose=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
              /var/log/openvswitch/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  daemon.   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 possible 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 possible 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 example, 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    /etc/openvswitch/conf.db.     The    default    schema    is
       /usr/share/openvswitch/vswitch.ovsschema.  The help command also displays these defaults.

SEE ALSO

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