The ovsdb-client program is a command-line client for interacting
with a running ovsdb-server process. Each command connects to
the specified OVSDB server, which may be an OVSDB active or
passive connection method, as described in ovsdb(7). The default
server is unix:/usr/local/var/run/openvswitch/db.sock and the
default database is Open_vSwitch.
ovsdb-client supports the method1,method2,...,methodN syntax
described in ovsdb(7) for connecting to a cluster. When this
syntax is used, ovsdb-client tries the cluster members in random
order until it finds the cluster leader. Specify the
--no-leader-only option to instead accept any server that is
connected to the cluster.
For an introduction to OVSDB and its implementation in Open
vSwitch, see ovsdb(7).
The following sections describe the commands that ovsdb-client
supports.
Server-Level Commands
Most ovsdb-client commands work with an individual database, but
these commands apply to an entire database server.
list-dbs [server]
Connects to server, retrieves the list of known databases,
and prints them one per line. These database names are
the ones that other commands may use for database.
Database Schema Commands
These commands obtain the schema from a database and print it or
part of it.
get-schema [server] [database]
Connects to server, retrieves the schema for database, and
prints it in JSON format.
list-tables [server] [database]
Connects to server, retrieves the schema for database, and
prints a table listing the name of each table within the
database.
list-columns [server] [database] table
Connects to server, retrieves the schema for database, and
prints a table listing the name and type of each column.
If table is specified, only columns in that table are
listed; otherwise, the tables include columns in all
tables.
Database 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 [server] schema
Reads an OVSDB schema in JSON format, as specified in the
OVSDB specification, from schema, then connects to server
and requests the server to convert the database whose name
is specified in schema to the schema also specified in
schema.
The conversion is atomic, consistent, isolated, and
durable. Following the schema change, the server notifies
clients that use the set_db_change_aware RPC introduced in
Open vSwitch 2.9 and cancels their outstanding
transactions and monitors. The server disconnects other
clients, enabling them to notice the change when they
reconnect.
This command can do simple ``upgrades'' and ``downgrades''
on a database's schema. The data in the database must be
valid when interpreted under schema, with only one
exception: data for tables and columns that do not exist
in schema are ignored. Columns that exist in schema but
not in the database 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 works with clustered and standalone
databases. Standalone databases may also be converted
(offline) with ovsdb-tool's convert command.
needs-conversion [server] schema
Reads the schema from schema, then connects to server and
requests the schema from the database whose name is
specified in schema. If the two schemas are the same,
prints no on stdout; if they differ, prints yes.
get-schema-version [server] [database]
Connects to server, retrieves the schema for database, and
prints its version number on stdout. If database was
created before schema versioning was introduced, then it
will not have a version number and this command will print
a blank line.
get-schema-cksum [server] [database]
Connects to server, retrieves the schema for database, and
prints its checksum on stdout. If database does not
include a checksum, prints a blank line.
Data Management Commands
These commands read or modify the data in a database.
transact [server] transaction
Connects to server, sends it the specified transaction,
which must be a JSON array appropriate for use as the
params to a JSON-RPC transact request, and prints the
received reply on stdout.
query [server] transaction
This commands acts like a read-only version of transact.
It connects to server, sends it the specified transaction,
which must be a JSON array appropriate for use as the
params to a JSON-RPC transact request, and prints the
received reply on stdout. To ensure that the transaction
does not modify the database, this command appends an
abort operation to the set of operations included in
transaction before sending it to the database, and then
removes the abort result from the reply (if it is
present).
dump [server] [database] [table [column...]]
Connects to server, retrieves all of the data in database,
and prints it on stdout as a series of tables. If table is
specified, only that table is retrieved. If at least one
column is specified, only those columns are retrieved.
backup [server] [database] > snapshot
Connects to server, retrieves a snapshot of the schema and
data in database, and prints it on stdout in the format
used for OVSDB standalone and active-backup databases.
This is an appropriate way to back up any remote database.
The database snapshot that it outputs is suitable to be
served up directly by ovsdb-server or used as the input to
ovsdb-client restore.
Another way to back up a standalone or active-backup
database is to copy its database file, e.g. with cp. This
is safe even if the database is in use.
The output does not include ephemeral columns, which by
design do not survive across restarts of ovsdb-server.
[--force] restore [server] [database] < snapshot
Reads snapshot, which must be a OVSDB standalone or
active-backup database (possibly but not necessarily
created by ovsdb-client backup). Then, connects to
server, verifies that database and snapshot have the same
schema, then deletes all of the data in database and
replaces it by snapshot. The replacement happens
atomically, in a single transaction.
UUIDs for rows in the restored database will differ from
those in snapshot, because the OVSDB protocol does not
allow clients to specify row UUIDs. Another way to
restore a standalone or active-backup database, which does
also restore row UUIDs, is to stop the server or servers,
replace the database file by the snapshot, then restart
the database. Either way, ephemeral columns are not
restored, since by design they do not survive across
restarts of ovsdb-server.
Normally restore exits with a failure if snapshot and the
server's database have different schemas. In such a case,
it is a good idea to convert the database to the new
schema before restoring, e.g. with ovsdb-client convert.
Use --force to proceed regardless of schema differences
even though the restore might fail with an error or
succeed with surprising results.
monitor [server] [database] table [column[,column]...]...
monitor-cond [server] [database] conditions table
[column[,column]...]...
monitor-cond-since [server] [database] [last-id] conditions table
[column[,column]...]...
Connects to server and monitors the contents of rows that
match conditions in table in database. By default, the
initial contents of table are printed, followed by each
change as it occurs. If conditions empty, all rows will
be monitored. If at least one column is specified, only
those columns are monitored. The following column names
have special meanings:
!initial
Do not print the initial contents of the specified
columns.
!insert
Do not print newly inserted rows.
!delete
Do not print deleted rows.
!modify
Do not print modifications to existing rows.
Multiple [column[,column]...] groups may be specified as
separate arguments, e.g. to apply different reporting
parameters to each group. Whether multiple groups or only
a single group is specified, any given column may only be
mentioned once on the command line.
conditions is a JSON array of <condition> as defined in
RFC 7047 5.1 with the following change: A condition can be
either a 3-element JSON array as described in the RFC or a
boolean value.
If --detach is used with monitor, monitor-cond or
monitor-cond-since, then ovsdb-client detaches after it
has successfully received and printed the initial contents
of table.
The monitor command uses RFC 7047 "monitor" method to open
a monitor session with the server. The monitor-cond and
monitor-cond-since commandls uses RFC 7047 extension
"monitor_cond" and "monitor_cond_since" methods. See
ovsdb-server(1) for details.
monitor [server] [database] ALL
Connects to server and monitors the contents of all tables
in database. Prints initial values and all kinds of
changes to all columns in the database. The --detach
option causes ovsdb-client to detach after it successfully
receives and prints the initial database contents.
The monitor command uses RFC 7047 "monitor" method to open
a monitor session with the server.
wait [server] database state
Waits for database on server to enter a desired state,
which may be one of:
added Waits until a database with the given name has been
added to server.
connected
Waits until a database with the given name has been
added to server. Then, if database is clustered,
additionally waits until it has joined and
connected to its cluster.
removed
Waits until database has been removed from the
database server. This can also be used to wait for
a database to complete leaving its cluster, because
ovsdb-server removes a database at that point.
database is mandatory for this command because it is often
used to check for databases that have not yet been added
to the server, so that the ovsdb-client semantics of
acting on a default database do not work.
This command acts on a particular database server, not on
a cluster, so server must name a single server, not a
comma-delimited list of servers.
Testing commands
These commands are mostly of interest for testing the correctness
of the OVSDB server.
lock [server] lock
steal [server] lock
unlock [server] lock
Connects to server and issues corresponding RFC 7047 lock
operations on lock. Prints json reply or subsequent update
messages. The --detach option causes ovsdb-client to
detach after it successfully receives and prints the
initial reply.
When running with the --detach option, lock, steal, unlock
and exit commands can be issued by using ovs-appctl. exit
command causes the ovsdb-client to close its ovsdb-server
connection before exit. The lock, steal and unlock
commands can be used to issue additional lock operations
over the same ovsdb-server connection. All above commands
take a single lock argument, which does not have to be the
same as the lock that ovsdb-client started with.
