|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FILES | SEE ALSO | COLOPHON |
|
|
|
ovsdb-tool(1) Open vSwitch Manual ovsdb-tool(1)
ovsdb-tool - Open vSwitch database management utility
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]
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.)
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.
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.
ovsdb(7), ovsdb-server(1), ovsdb-client(1).
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 bugs@openvswitch.org. This page was
obtained from the project's upstream Git repository
⟨https://github.com/openvswitch/ovs.git⟩ on 2025-08-11. (At that
time, the date of the most recent commit that was found in the
repository was 2025-07-31.) 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
man-pages@man7.org
Open vSwitch 3.2.90 ovsdb-tool(1)
Pages that refer to this page: ovsdb-server(1), ovsdb(5), ovsdb(7)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|