ovsdb-tool(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FILES | SEE ALSO | COLOPHON

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

NAME         top

       ovsdb-tool - Open vSwitch database management utility

SYNOPSIS         top

       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         top

       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
       /usr/local/etc/openvswitch/conf.db.  The default schema is
       /usr/local/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         top

   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
              /usr/local/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         top

       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         top

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

COLOPHON         top

       This page is part of the Open vSwitch (a distributed virtual
       multilayer switch) project.  Information about the project can be
       found at ⟨http://openvswitch.org/⟩.  If you have a bug report for
       this manual page, send it to [email protected].  This page was
       obtained from the project's upstream Git repository
       ⟨https://github.com/openvswitch/ovs.git⟩ on 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-07.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

Open vSwitch                     3.2.90                    ovsdb-tool(1)

Pages that refer to this page: ovsdb-server(1)ovsdb(5)ovsdb(7)