Ubuntu Manpage: ovsdb-tool - Open vSwitch database management utility

Provided by: openvswitch-common_3.5.0-1build1_amd64

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.

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

FILES

SEE ALSO