[mirror_ovs.git] / ovsdb / ovsdb-client.1.in

.\" -*- nroff -*-
.de IQ
.  br
.  ns
.  IP "\\$1"
..
.\" -*- nroff -*-
.TH ovsdb\-client 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
.\" This program's name:
.ds PN ovsdb\-client
.
.SH NAME
ovsdb\-client \- command-line interface to \fBovsdb-server\fR(1)
.
.SH SYNOPSIS
.IP "Server-Level Commands:"
\fBovsdb\-client\fR [\fIoptions\fR] \fBlist\-dbs\fR [\fIserver\fR]
.IP "Database Schema Commands:"
\fBovsdb\-client\fR [\fIoptions\fR] \fBget\-schema\fR [\fIserver\fR] [\fIdatabase\fR]
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBlist\-tables\fR [\fIserver\fR] [\fIdatabase\fR]
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBlist\-columns\fR [\fIserver\fR] [\fIdatabase\fR] [\fItable\fR]
.IP "Database Version Management Commands:"
\fBovsdb\-client \fR[\fIoptions\fR] \fBconvert \fR[\fIserver\fR] \fIschema\fR
.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBneeds\-conversion \fR[\fIserver\fR] \fIschema\fR
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBget\-schema\-version\fR [\fIserver\fR] [\fIdatabase\fR]
.IP "Data Management Commands:"
\fBovsdb\-client\fR [\fIoptions\fR] \fBtransact\fR [\fIserver\fR] \fItransaction\fR
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBquery\fR [\fIserver\fR] \fItransaction\fR
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBdump\fR [\fIserver\fR] [\fIdatabase\fR] [\fItable\fR
[\fIcolumn\fR...]]
.br
\fBovsdb\-client\fR [\fIoptions\fR]
\fBbackup\fR [\fIserver\fR] [\fIdatabase\fR] \fB> \fIsnapshot\fR
.br
\fBovsdb\-client\fR [\fIoptions\fR] [\fB\-\-force\fR]
\fBrestore\fR [\fIserver\fR] [\fIdatabase\fR] \fB< \fIsnapshot\fR
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBmonitor\fR [\fIserver\fR] [\fIdatabase\fR] \fItable\fR
[\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBmonitor\fR [\fIserver\fR] [\fIdatabase\fR] \fBALL\fR
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBmonitor\-cond\fR [\fIserver\fR] [\fIdatabase\fR] \fIconditions
\fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
.br
\fBovsdb\-client \fR[\fIoptions\fR] \fBwait\fR \fR[\fIserver\fR] \fIdatabase\fR \fIstate\fR
.IP "Testing Commands:"
\fBovsdb\-client\fR [\fIoptions\fR] \fBlock\fR [\fIserver\fR] \fIlock\fR
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBsteal\fR [\fIserver\fR] \fIlock\fR
.br
\fBovsdb\-client\fR [\fIoptions\fR] \fBunlock\fR [\fIserver\fR] \fIlock\fR
.br
.IP "Other Commands:"
\fBovsdb\-client help\fR
.IP "Cluster Options:"
[\fB\-\-no\-leader\-only\fR]
.IP "Output formatting options:"
[\fB\-\-format=\fIformat\fR]
[\fB\-\-data=\fIformat\fR]
[\fB\-\-no-headings\fR]
[\fB\-\-pretty\fR]
[\fB\-\-bare\fR]
[\fB\-\-timestamp\fR]
.so lib/daemon-syn.man
.so lib/vlog-syn.man
.so lib/ssl-syn.man
.so lib/ssl-bootstrap-syn.man
.so lib/ssl-connect-syn.man
.so lib/common-syn.man
.
.SH DESCRIPTION
The \fBovsdb\-client\fR program is a command-line client for
interacting with a running \fBovsdb\-server\fR process.
Each command connects to the specified OVSDB \fIserver\fR, which may
be an OVSDB active or passive connection method, as described in
\fBovsdb\fR(7).  The default server is \fBunix:@RUNDIR@/db.sock\fR
and
the default \fIdatabase\fR is \fBOpen_vSwitch\fR.
.PP
\fBovsdb\-client\fR supports the
\fImethod1\fB,\fImethod2\fB,\fR...\fB,\fImethodN\fR syntax described
in \fBovsdb\fR(7) for connecting to a cluster.  When this syntax is
used, \fBovsdb\-client\fR tries the cluster members in random order
until it finds the cluster leader.  Specify the
\fB\-\-no\-leader\-only\fR option to instead accept any server that is
connected to the cluster.
.PP
For an introduction to OVSDB and its implementation in Open vSwitch,
see \fBovsdb\fR(7).
.PP
The following sections describe the commands that \fBovsdb\-client\fR
supports.
.SS "Server-Level Commands"
Most \fBovsdb\-client\fR commands work with an individual database,
but these commands apply to an entire database server.
.
.IP "\fBlist\-dbs\fR [\fIserver\fR]"
Connects to \fIserver\fR, retrieves the list of known databases, and
prints them one per line.  These database names are the ones that
other commands may use for \fIdatabase\fR.
.
.SS "Database Schema Commands"
.PP
These commands obtain the schema from a database and print it or part
of it.
.
.IP "\fBget\-schema\fR [\fIserver\fR] [\fIdatabase\fR]"
Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
prints it in JSON format.
.
.IP "\fBlist\-tables\fR [\fIserver\fR] [\fIdatabase\fR]"
Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
prints a table listing the name of each table
within the database.
.
.IP "\fBlist\-columns\fR [\fIserver\fR] [\fIdatabase\fR] \fItable\fR"
Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
prints a table listing the name and type of each
column.  If \fItable\fR is specified, only columns in that table are
listed; otherwise, the tables include columns in all tables.
.
.SS "Database Version Management Commands"
.so ovsdb/ovsdb-schemas.man
.PP
These commands work with different versions of OVSDB schemas and
databases.
.
.IP "\fBconvert \fR[\fIserver\fR] \fIschema\fR"
Reads an OVSDB schema in JSON format, as specified in the OVSDB
specification, from \fIschema\fR, then connects to \fIserver\fR and
requests the server to convert the database whose name is specified in
\fIschema\fR to the schema also specified in \fIschema\fR.
.IP
The conversion is atomic, consistent, isolated, and durable.
Following the schema change, the server notifies clients that use the
\fBset_db_change_aware\fR 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.
.IP
This command can do simple ``upgrades'' and ``downgrades'' on a
database's schema.  The data in the database must be valid when
interpreted under \fIschema\fR, with only one exception: data for
tables and columns that do not exist in \fIschema\fR are ignored.
Columns that exist in \fIschema\fR but not in the database are set to
their default values.  All of \fIschema\fR's constraints apply in
full.
.IP
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.
.IP
This command works with clustered and standalone databases.
Standalone databases may also be converted (offline) with
\fBovsdb\-tool\fR's \fBconvert\fR command.
.
.IP "\fBneeds\-conversion \fR[\fIserver\fR] \fIschema\fR"
Reads the schema from \fIschema\fR, then connects to \fIserver\fR and
requests the schema from the database whose name is specified in
\fIschema\fR.  If the two schemas are the same, prints \fBno\fR on
stdout; if they differ, prints \fByes\fR.
.
.IP "\fBget\-schema\-version \fR[\fIserver\fR] [\fIdatabase\fR]"
Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
prints its version number on stdout.
If \fIdatabase\fR was created before schema versioning was introduced,
then it will not have a version number and this command will print a
blank line.
.
.IP "\fBget\-schema\-cksum\fR [\fIserver\fR] [\fIdatabase\fR]"
Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
prints its checksum on stdout.  If \fIdatabase\fR does not include a
checksum, prints a blank line.
.
.SS "Data Management Commands"
.PP
These commands read or modify the data in a database.
.
.IP "\fBtransact\fR [\fIserver\fR] \fItransaction\fR"
Connects to \fIserver\fR, sends it the specified \fItransaction\fR,
which must be a JSON array appropriate for use as the \fBparams\fR to
a JSON-RPC \fBtransact\fR request, and prints the received reply on
stdout.
.
.IP "\fBquery\fR [\fIserver\fR] \fItransaction\fR"
This commands acts like a read-only version of \fBtransact\fR.
It connects to \fIserver\fR, sends it the specified \fItransaction\fR,
which must be a JSON array appropriate for use as the \fBparams\fR to
a JSON-RPC \fBtransact\fR request, and prints the received reply on
stdout.  To ensure that the transaction does not modify the database,
this command appends an \fBabort\fR operation to the set of operations
included in \fItransaction\fR before sending it to the database, and
then removes the \fBabort\fR result from the reply (if it is present).
.
.IP "\fBdump\fR [\fIserver\fR] [\fIdatabase\fR] [\fItable\fR [\fIcolumn\fR...]]"
Connects to \fIserver\fR, retrieves all of the data in \fIdatabase\fR,
and prints it on stdout as a series of tables. If \fItable\fR is
specified, only that table is retrieved.  If at least one \fIcolumn\fR
is specified, only those columns are retrieved.
.
.IP "\fBbackup\fR [\fIserver\fR] [\fIdatabase\fR] \fB> \fIsnapshot\fR"
Connects to \fIserver\fR, retrieves a snapshot of the schema and data
in \fIdatabase\fR, 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 \fBovsdb\-server\fR or
used as the input to \fBovsdb\-client restore\fR.
.IP
Another way to back up a standalone or active-backup database is to
copy its database file, e.g. with \fBcp\fR.  This is safe even if the
database is in use.
.IP
The output does not include ephemeral columns, which by design do not
survive across restarts of \fBovsdb\-server\fR.
.
.IP "[\fB\-\-force\fR] \fBrestore\fR [\fIserver\fR] [\fIdatabase\fR] \fB< \fIsnapshot\fR"
Reads \fIsnapshot\fR, which must be a OVSDB standalone or
active-backup database (possibly but not necessarily created by
\fBovsdb\-client backup).  Then, connects to \fIserver\fR, verifies
that \fIdatabase\fR and \fIsnapshot\fR have the same schema, then
deletes all of the data in \fIdatabase\fR and replaces it by
\fIsnapshot\fR.  The replacement happens atomically, in a single
transaction.
.IP
UUIDs for rows in the restored database will differ from those in
\fIsnapshot\fR, 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
\fBovsdb\-server\fR.
.IP
Normally \fBrestore\fR exits with a failure if \fBsnapshot\fR 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 \fBovsdb\-client convert\fR.  Use \fB\-\-force\fR to proceed
regardless of schema differences even though the restore might fail
with an error or succeed with surprising results.
.
.IP "\fBmonitor\fR [\fIserver\fR] [\fIdatabase\fR] \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
.IQ "\fBmonitor\-cond\fR [\fIserver\fR] [\fIdatabase\fR] \fIconditions\fR \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
Connects to \fIserver\fR and monitors the contents of rows that match conditions in
\fItable\fR in \fIdatabase\fR. By default, the initial contents of \fItable\fR are
printed, followed by each change as it occurs.  If conditions empty,
all rows will be monitored. If at least one \fIcolumn\fR is specified, only those
columns are monitored.  The following \fIcolumn\fR names have special meanings:
.RS
.IP "\fB!initial\fR"
Do not print the initial contents of the specified columns.
.IP "\fB!insert\fR"
Do not print newly inserted rows.
.IP "\fB!delete\fR"
Do not print deleted rows.
.IP "\fB!modify\fR"
Do not print modifications to existing rows.
.RE
.IP
Multiple [\fIcolumn\fR[\fB,\fIcolumn\fR]...] 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.
.IP
\fBconditions\fR 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 deescribed in the RFC or a boolean value..
.IP
If \fB\-\-detach\fR is used with \fBmonitor\fR or \fBmonitor\-cond\fR, then
\fBovsdb\-client\fR detaches after it has successfully received and
printed the initial contents of \fItable\fR.
.IP
The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
session with the server. The \fBmonitor\-cond\fR command uses RFC 7047
extension "monitor_cond" method. See \fBovsdb\-server\fR(1) for details.
.IP "\fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fBALL\fR"
Connects to \fIserver\fR and monitors the contents of all tables in
\fIdatabase\fR.  Prints initial values and all kinds of changes to all
columns in the database.  The \fB\-\-detach\fR option causes
\fBovsdb\-client\fR to detach after it successfully receives and
prints the initial database contents.
.IP
The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
session with the server.
.
.IP "\fBwait\fR \fR[\fIserver\fR] \fIdatabase state\fR"
Waits for \fIdatabase\fR on \fIserver\fR to enter a desired \fIstate\fR,
which may be one of:
.RS
.IP "\fBadded\fR"
Waits until a database with the given name has been added to
\fIserver\fR.
.IP "\fBconnected\fR"
Waits until a database with the given name has been added to
\fIserver\fR.  Then, if \fIdatabase\fR is clustered, additionally
waits until it has joined and connected to its cluster.
.IP "\fBremoved\fR"
Waits until \fIdatabase\fR has been removed from the database server.
This can also be used to wait for a database to complete leaving its
cluster, because \fBovsdb\-server\fR removes a database at that point.
.RE
.IP
\fIdatabase\fR 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 \fBovsdb\-client\fR semantics of acting on a default database
do not work.
.IP
This command acts on a particular database server, not on a cluster,
so \fIserver\fR must name a single server, not a comma-delimited list
of servers.
.SS "Testing commands"
These commands are mostly of interest for testing the correctness
of the OVSDB server.
.
.IP "\fBlock\fR [\fIserver\fR] \fIlock\fR"
.IQ "\fBsteal\fR [\fIserver\fR] \fIlock\fR"
.IQ "\fBunlock\fR [\fIserver\fR] \fIlock\fR"
Connects to \fIserver\fR and issues corresponding RFC 7047 lock operations
on \fIlock\fR. Prints json reply or subsequent update messages.
The \fB\-\-detach\fR option causes \fBovsdb\-client\fR to detach after it
successfully receives and prints the initial reply.
.IP
When running with the \fB\-\-detach\fR option, \fBlock\fR, \fBsteal\fR,
\fBunlock\fR and \fBexit\fR commands can be issued by using
\fBovs-appctl\fR. \fBexit\fR command causes the \fBovsdb\-client\fR to
close its \fBovsdb\-server\fR connection before exit.
The \fBlock\fR, \fBsteal\fR and \fBunlock\fR commands can be used to
issue additional lock operations over the same \fBovsdb\-server\fR connection. All above commands take a single \fIlock\fR argument, which does not have
to be the same as the \fIlock\fR that \fBovsdb\-client\fR started with.
.
.SH OPTIONS
.SS "Output Formatting Options"
Much of the output from \fBovsdb\-client\fR is in the form of tables.
The following options controlling output formatting:
.
.ds TD (default)
.so lib/table.man
.
.IP "\fB\-\-timestamp\fR"
For the \fBmonitor\fR and \fBmonitor\-cond\fR commands, add a timestamp to each
table update.  Most output formats add the timestamp on a line of its own
just above the table.  The JSON output format puts the timestamp in a
member of the top-level JSON object named \fBtime\fR.
.
.IP "\fB\-t\fR"
.IQ "\fB\-\-timeout=\fIsecs\fR"
Limits \fBovsdb\-client\fR runtime to approximately \fIsecs\fR
seconds.  If the timeout expires, \fBovsdb\-client\fR will exit with a
\fBSIGALRM\fR signal.
.
.SS "Daemon Options"
The daemon options apply only to the \fBmonitor\fR and \fBmonitor\-cond\fR commands.
With any other command, they have no effect.
.ds DD
.so lib/daemon.man
.SS "Logging Options"
.so lib/vlog.man
.SS "Public Key Infrastructure Options"
.so lib/ssl.man
.so lib/ssl-bootstrap.man
.SS "SSL Connection Options"
.so lib/ssl-connect.man
.SS "Other Options"
.so lib/common.man
.SH "SEE ALSO"
.
\fBovsdb\fR(7),
\fBovsdb\-server\fR(1),
\fBovsdb\-client\fR(1).