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.
Columns that exist in schema but not in db are set to their de‐
fault 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.4.1 ovsdb-tool(1)