path: root/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:"
.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]...]...
.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 "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
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 "\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 database files.  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 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 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.
.
.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.
.
.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).