.\" -*- nroff -*-
.\" -*- nroff -*-
.\" ovs.tmac
.\"
.\" Open vSwitch troff macro library
.
.
.\" Continuation line for .IP.
.de IQ
.  br
.  ns
.  IP "\\$1"
..
.
.\" Introduces a sub-subsection
.de ST
.  PP
.  RS -0.15in
.  I "\\$1"
.  RE
..
.
.\" The content between the lines below is from an-ext.tmac in groff
.\" 1.21, with some modifications.
.\" ----------------------------------------------------------------------
.\" an-ext.tmac
.\"
.\" Written by Eric S. Raymond <esr@thyrsus.com>
.\"            Werner Lemberg <wl@gnu.org>
.\"
.\" Version 2007-Feb-02
.\"
.\" Copyright (C) 2007, 2009, 2011 Free Software Foundation, Inc.
.\" You may freely use, modify and/or distribute this file.
.\"
.\"
.\" The code below provides extension macros for the `man' macro package.
.\" Care has been taken to make the code portable; groff extensions are
.\" properly hidden so that all troff implementations can use it without
.\" changes.
.\"
.\" With groff, this file is sourced by the `man' macro package itself.
.\" Man page authors who are concerned about portability might add the
.\" used macros directly to the prologue of the man page(s).
.
.
.\" Convention: Auxiliary macros and registers start with `m' followed
.\"             by an uppercase letter or digit.
.
.
.\" Declare start of command synopsis.  Sets up hanging indentation.
.de SY
.  ie !\\n(mS \{\
.    nh
.    nr mS 1
.    nr mA \\n(.j
.    ad l
.    nr mI \\n(.i
.  \}
.  el \{\
.    br
.    ns
.  \}
.
.  HP \w'\fB\\$1\fP\ 'u
.  B "\\$1"
..
.
.
.\" End of command synopsis.  Restores adjustment.
.de YS
.  in \\n(mIu
.  ad \\n(mA
.  hy \\n(HY
.  nr mS 0
..
.
.
.\" Declare optional option.
.de OP
.  ie \\n(.$-1 \
.    RI "[\fB\\$1\fP" "\ \\$2" "]"
.  el \
.    RB "[" "\\$1" "]"
..
.
.
.\" Start URL.
.de UR
.  ds m1 \\$1\"
.  nh
.  if \\n(mH \{\
.    \" Start diversion in a new environment.
.    do ev URL-div
.    do di URL-div
.  \}
..
.
.
.\" End URL.
.de UE
.  ie \\n(mH \{\
.    br
.    di
.    ev
.
.    \" Has there been one or more input lines for the link text?
.    ie \\n(dn \{\
.      do HTML-NS "<a href=""\\*(m1"">"
.      \" Yes, strip off final newline of diversion and emit it.
.      do chop URL-div
.      do URL-div
\c
.      do HTML-NS </a>
.    \}
.    el \
.      do HTML-NS "<a href=""\\*(m1"">\\*(m1</a>"
\&\\$*\"
.  \}
.  el \
\\*(la\\*(m1\\*(ra\\$*\"
.
.  hy \\n(HY
..
.
.
.\" Start email address.
.de MT
.  ds m1 \\$1\"
.  nh
.  if \\n(mH \{\
.    \" Start diversion in a new environment.
.    do ev URL-div
.    do di URL-div
.  \}
..
.
.
.\" End email address.
.de ME
.  ie \\n(mH \{\
.    br
.    di
.    ev
.
.    \" Has there been one or more input lines for the link text?
.    ie \\n(dn \{\
.      do HTML-NS "<a href=""mailto:\\*(m1"">"
.      \" Yes, strip off final newline of diversion and emit it.
.      do chop URL-div
.      do URL-div
\c
.      do HTML-NS </a>
.    \}
.    el \
.      do HTML-NS "<a href=""mailto:\\*(m1"">\\*(m1</a>"
\&\\$*\"
.  \}
.  el \
\\*(la\\*(m1\\*(ra\\$*\"
.
.  hy \\n(HY
..
.
.
.\" Continuation line for .TP header.
.de TQ
.  br
.  ns
.  TP \\$1\" no doublequotes around argument!
..
.
.
.\" Start example.
.de EX
.  nr mE \\n(.f
.  nf
.  nh
.  ft CW
..
.
.
.\" End example.
.de EE
.  ft \\n(mE
.  fi
.  hy \\n(HY
..
.
.\" EOF
.\" ----------------------------------------------------------------------
.TH ovsdb\-client 1 "2.15.0" "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] \fBmonitor\-cond\-since\fR [\fIserver\fR] [\fIdatabase\fR]
[\fIlast-id\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]
.IP "Daemon options:"
[\fB\-\-pidfile\fR[\fB=\fIpidfile\fR]]
[\fB\-\-overwrite\-pidfile\fR]
[\fB\-\-detach\fR]
[\fB\-\-no\-chdir\fR]
[\fB\-\-no\-self\-confinement\fR]
.IP "Logging options:"
[\fB\-v\fR[\fImodule\fR[\fB:\fIdestination\fR[\fB:\fIlevel\fR]]]]\&...
.br
[\fB\-\-verbose[=\fImodule\fR[\fB:\fIdestination\fR[\fB:\fIlevel\fR]]]]\&...
.br
[\fB\-\-log\-file\fR[\fB=\fIfile\fR]]
.IP "Public key infrastructure options:"
[\fB\-\-private\-key=\fIprivkey.pem\fR]
.br
[\fB\-\-certificate=\fIcert.pem\fR]
.br
[\fB\-\-ca\-cert=\fIcacert.pem\fR]
.br
[\fB\-\-bootstrap\-ca\-cert=\fIcacert.pem\fR]
.IP "SSL connection options:"
[\fB\-\-ssl\-protocols=\fIprotocols\fR]
.br
[\fB\-\-ssl\-ciphers=\fIciphers\fR]
.br
.IP "Common options:"
[\fB\-h\fR | \fB\-\-help\fR]
[\fB\-V\fR | \fB\-\-version\fR]

.
.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:/var/run/openvswitch/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"
.PP
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 \fIx\fB.\fIy\fB.\fIz\fR, e.g. \fB1.2.3\fR.  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), \fIx\fR is
incremented (and \fIy\fR and \fIz\fR are reset to 0).  When the
database schema is changed in a backward compatible way (e.g. adding a
new column), \fIy\fR is incremented (and \fIz\fR is reset to 0).  When
the database schema is changed cosmetically (e.g. reindenting its
syntax), \fIz\fR is incremented.
.PP
Some OVSDB databases and schemas, especially very old ones, do not
have a version number.
.PP
Schema version numbers and Open vSwitch version numbers are
independent.
.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]...]..."
.IQ "\fBmonitor\-cond\-since\fR [\fIserver\fR] [\fIdatabase\fR] [\fIlast-id\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 described in the RFC or a boolean value.
.IP
If \fB\-\-detach\fR is used with \fBmonitor\fR, \fBmonitor\-cond\fR or
\fBmonitor\-cond\-since\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 and \fBmonitor\-cond\-since\fR
commandls uses RFC 7047 extension "monitor_cond" and "monitor_cond_since"
methods. 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)
.IP "\fB\-f \fIformat\fR"
.IQ "\fB\-\-format=\fIformat\fR"
Sets the type of table formatting.  The following types of
\fIformat\fR are available:
.RS
.ie '\*(PN'ovsdb\-client' .IP "\fBtable\fR (default)"
.el                       .IP "\fBtable\fR"
2-D text tables with aligned columns.
.ie '\*(PN'ovsdb\-client' .IP "\fBlist\fR"
.el                       .IP "\fBlist\fR (default)"
A list with one column per line and rows separated by a blank line.
.IP "\fBhtml\fR"
HTML tables.
.IP "\fBcsv\fR"
Comma-separated values as defined in RFC 4180.
.IP "\fBjson\fR"
JSON format as defined in RFC 4627.  The output is a sequence of JSON
objects, each of which corresponds to one table.  Each JSON object has
the following members with the noted values:
.RS
.IP "\fBcaption\fR"
The table's caption.  This member is omitted if the table has no
caption.
.IP "\fBheadings\fR"
An array with one element per table column.  Each array element is a
string giving the corresponding column's heading.
.IP "\fBdata\fR"
An array with one element per table row.  Each element is also an
array with one element per table column.  The elements of this
second-level array are the cells that constitute the table.  Cells
that represent OVSDB data or data types are expressed in the format
described in the OVSDB specification; other cells are simply expressed
as text strings.
.RE
.RE
.
.IP "\fB\-d \fIformat\fR"
.IQ "\fB\-\-data=\fIformat\fR"
Sets the formatting for cells within output tables unless the table
format is set to \fBjson\fR, in which case \fBjson\fR formatting is
always used when formatting cells.  The following types of \fIformat\fR
are available:
.RS
.IP "\fBstring\fR (default)"
The simple format described in the \fBDatabase Values\fR
.ie '\*(PN'ovs\-vsctl' section below.
.el                    section of \fBovs\-vsctl\fR(8).
.IP "\fBbare\fR"
The simple format with punctuation stripped off: \fB[]\fR and \fB{}\fR
are omitted around sets, maps, and empty columns, items within sets
and maps are space-separated, and strings are never quoted.  This
format may be easier for scripts to parse.
.IP "\fBjson\fR"
The RFC 4627 JSON format as described above.
.RE
.IP
.
.IP "\fB\-\-no\-headings\fR"
This option suppresses the heading row that otherwise appears in the
first row of table output.
.
.IP "\fB\-\-pretty\fR"
By default, JSON in output is printed as compactly as possible.  This
option causes JSON in output to be printed in a more readable
fashion.  Members of objects and elements of arrays are printed one
per line, with indentation.
.IP
This option does not affect JSON in tables, which is always printed
compactly.
.IP "\fB\-\-bare\fR"
Equivalent to \fB\-\-format=list \-\-data=bare \-\-no\-headings\fR.
.IP "\fB\-\-max\-column-width=\fIn\fR"
For table output only, limits the width of any column in the output to
\fIn\fR columns.  Longer cell data is truncated to fit, as necessary.
Columns are always wide enough to display the column names, if the
heading row is printed.
.
.IP "\fB\-\-timestamp\fR"
For the \fBmonitor\fR, \fBmonitor\-cond\fR and \fBmonitor\-cond\-since\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, \fBmonitor\-cond\fR and
\fBmonitor\-cond\-since\fR commands.  With any other command, they have no
effect.
.ds DD
.PP
The following options are valid on POSIX based platforms.
.TP
\fB\-\-pidfile\fR[\fB=\fIpidfile\fR]
Causes a file (by default, \fB\*(PN.pid\fR) to be created indicating
the PID of the running process.  If the \fIpidfile\fR argument is not
specified, or
if it does not begin with \fB/\fR, then it is created in
\fB/var/run/openvswitch\fR.
.IP
If \fB\-\-pidfile\fR is not specified, no pidfile is created.
.
.TP
\fB\-\-overwrite\-pidfile\fR
By default, when \fB\-\-pidfile\fR is specified and the specified pidfile 
already exists and is locked by a running process, \fB\*(PN\fR refuses 
to start.  Specify \fB\-\-overwrite\-pidfile\fR to cause it to instead 
overwrite the pidfile.
.IP
When \fB\-\-pidfile\fR is not specified, this option has no effect.
.
.IP \fB\-\-detach\fR
Runs \fB\*(PN\fR as a background process.  The process forks, and in
the child it starts a new session, closes the standard file
descriptors (which has the side effect of disabling logging to the
console), and changes its current directory to the root (unless
\fB\-\-no\-chdir\fR is specified).  After the child completes its
initialization, the parent exits.  \*(DD
.
.TP
\fB\-\-monitor\fR
Creates an additional process to monitor the \fB\*(PN\fR daemon.  If
the daemon dies due to a signal that indicates a programming error
(\fBSIGABRT\fR, \fBSIGALRM\fR, \fBSIGBUS\fR, \fBSIGFPE\fR,
\fBSIGILL\fR, \fBSIGPIPE\fR, \fBSIGSEGV\fR, \fBSIGXCPU\fR, or
\fBSIGXFSZ\fR) then the monitor process starts a new copy of it.  If
the daemon dies or exits for another reason, the monitor process exits.
.IP
This option is normally used with \fB\-\-detach\fR, but it also
functions without it.
.
.TP
\fB\-\-no\-chdir\fR
By default, when \fB\-\-detach\fR is specified, \fB\*(PN\fR 
changes its current working directory to the root directory after it 
detaches.  Otherwise, invoking \fB\*(PN\fR from a carelessly chosen 
directory would prevent the administrator from unmounting the file 
system that holds that directory.
.IP
Specifying \fB\-\-no\-chdir\fR suppresses this behavior, preventing
\fB\*(PN\fR from changing its current working directory.  This may be 
useful for collecting core files, since it is common behavior to write 
core dumps into the current working directory and the root directory 
is not a good directory to use.
.IP
This option has no effect when \fB\-\-detach\fR is not specified.
.
.TP
\fB\-\-no\-self\-confinement\fR
By default daemon will try to self-confine itself to work with
files under well-known directories determined during build.  It
is better to stick with this default behavior and not to use this
flag unless some other Access Control is used to confine daemon.
Note that in contrast to other access control implementations that
are typically enforced from kernel-space (e.g. DAC or MAC),
self-confinement is imposed from the user-space daemon itself and
hence should not be considered as a full confinement strategy, but
instead should be viewed as an additional layer of security.
.
.TP
\fB\-\-user\fR
Causes \fB\*(PN\fR to run as a different user specified in "user:group", thus
dropping most of the root privileges. Short forms "user" and ":group" are also
allowed, with current user or group are assumed respectively. Only daemons
started by the root user accepts this argument.
.IP
On Linux, daemons will be granted CAP_IPC_LOCK and CAP_NET_BIND_SERVICES
before dropping root privileges. Daemons that interact with a datapath,
such as \fBovs\-vswitchd\fR, will be granted three additional capabilities,
namely CAP_NET_ADMIN, CAP_NET_BROADCAST and CAP_NET_RAW.  The capability
change will apply even if the new user is root.
.IP
On Windows, this option is not currently supported. For security reasons,
specifying this option will cause the daemon process not to start.
.SS "Logging Options"
.IP "\fB\-v\fR[\fIspec\fR]
.IQ "\fB\-\-verbose=\fR[\fIspec\fR]
.
Sets logging levels.  Without any \fIspec\fR, sets the log level for
every module and destination to \fBdbg\fR.  Otherwise, \fIspec\fR is a
list of words separated by spaces or commas or colons, up to one from
each category below:
.
.RS
.IP \(bu
A valid module name, as displayed by the \fBvlog/list\fR command on
\fBovs\-appctl\fR(8), limits the log level change to the specified
module.
.
.IP \(bu
\fBsyslog\fR, \fBconsole\fR, or \fBfile\fR, to limit the log level
change to only to the system log, to the console, or to a file,
respectively.  (If \fB\-\-detach\fR is specified, \fB\*(PN\fR closes
its standard file descriptors, so logging to the console will have no
effect.)
.IP
On Windows platform, \fBsyslog\fR is accepted as a word and is only
useful along with the \fB\-\-syslog\-target\fR option (the word has no
effect otherwise).
.
.IP \(bu
\fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or
\fBdbg\fR, to control the log level.  Messages of the given severity
or higher will be logged, and messages of lower severity will be
filtered out.  \fBoff\fR filters out all messages.  See
\fBovs\-appctl\fR(8) for a definition of each log level.
.RE
.
.IP
Case is not significant within \fIspec\fR.
.IP
Regardless of the log levels set for \fBfile\fR, logging to a file
will not take place unless \fB\-\-log\-file\fR is also specified (see
below).
.IP
For compatibility with older versions of OVS, \fBany\fR is accepted as
a word but has no effect.
.
.IP "\fB\-v\fR"
.IQ "\fB\-\-verbose\fR"
Sets the maximum logging verbosity level, equivalent to
\fB\-\-verbose=dbg\fR.
.
.IP "\fB\-vPATTERN:\fIdestination\fB:\fIpattern\fR"
.IQ "\fB\-\-verbose=PATTERN:\fIdestination\fB:\fIpattern\fR"
Sets the log pattern for \fIdestination\fR to \fIpattern\fR.  Refer to
\fBovs\-appctl\fR(8) for a description of the valid syntax for \fIpattern\fR.
.
.IP "\fB\-vFACILITY:\fIfacility\fR"
.IQ "\fB\-\-verbose=FACILITY:\fIfacility\fR"
Sets the RFC5424 facility of the log message. \fIfacility\fR can be one of
\fBkern\fR, \fBuser\fR, \fBmail\fR, \fBdaemon\fR, \fBauth\fR, \fBsyslog\fR,
\fBlpr\fR, \fBnews\fR, \fBuucp\fR, \fBclock\fR, \fBftp\fR, \fBntp\fR,
\fBaudit\fR, \fBalert\fR, \fBclock2\fR, \fBlocal0\fR, \fBlocal1\fR,
\fBlocal2\fR, \fBlocal3\fR, \fBlocal4\fR, \fBlocal5\fR, \fBlocal6\fR or
\fBlocal7\fR. If this option is not specified, \fBdaemon\fR is used as
the default for the local system syslog and \fBlocal0\fR is used while sending
a message to the target provided via the \fB\-\-syslog\-target\fR option.
.
.TP
\fB\-\-log\-file\fR[\fB=\fIfile\fR]
Enables logging to a file.  If \fIfile\fR is specified, then it is
used as the exact name for the log file.  The default log file name
used if \fIfile\fR is omitted is \fB/var/log/openvswitch/\*(PN.log\fR.
.
.IP "\fB\-\-syslog\-target=\fIhost\fB:\fIport\fR"
Send syslog messages to UDP \fIport\fR on \fIhost\fR, in addition to
the system syslog.  The \fIhost\fR must be a numerical IP address, not
a hostname.
.
.IP "\fB\-\-syslog\-method=\fImethod\fR"
Specify \fImethod\fR how syslog messages should be sent to syslog daemon.
Following forms are supported:
.RS
.IP \(bu
\fBlibc\fR, use libc \fBsyslog()\fR 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 \fB/dev/log\fR
UNIX domain socket.
.IP \(bu
\fBunix:\fIfile\fR\fR, use UNIX domain socket directly.  It is possible to
specify arbitrary message format with this option.  However,
\fBrsyslogd 8.9\fR 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 \fBrsyslogd\fR versions, then use UDP socket to localhost
IP address instead.
.IP \(bu
\fBudp:\fIip\fR:\fIport\fR\fR, use UDP socket.  With this method it is
possible to use arbitrary message format also with older \fBrsyslogd\fR.
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.
.IP \(bu
\fBnull\fR, discards all messages logged to syslog.
.RE
.IP
The default is taken from the \fBOVS_SYSLOG_METHOD\fR environment
variable; if it is unset, the default is \fBlibc\fR.
.SS "Public Key Infrastructure Options"
.IP "\fB\-p\fR \fIprivkey.pem\fR"
.IQ "\fB\-\-private\-key=\fIprivkey.pem\fR"
Specifies a PEM file containing the private key used as \fB\*(PN\fR's
identity for outgoing SSL connections.
.
.IP "\fB\-c\fR \fIcert.pem\fR"
.IQ "\fB\-\-certificate=\fIcert.pem\fR"
Specifies a PEM file containing a certificate that certifies the
private key specified on \fB\-p\fR or \fB\-\-private\-key\fR to be
trustworthy.  The certificate must be signed by the certificate
authority (CA) that the peer in SSL connections will use to verify it.
.
.IP "\fB\-C\fR \fIcacert.pem\fR"
.IQ "\fB\-\-ca\-cert=\fIcacert.pem\fR"
Specifies a PEM file containing the CA certificate that \fB\*(PN\fR
should use to verify certificates presented to it by SSL peers.  (This
may be the same certificate that SSL peers use to verify the
certificate specified on \fB\-c\fR or \fB\-\-certificate\fR, or it may
be a different one, depending on the PKI design in use.)
.
.IP "\fB\-C none\fR"
.IQ "\fB\-\-ca\-cert=none\fR"
Disables verification of certificates presented by SSL peers.  This
introduces a security risk, because it means that certificates cannot
be verified to be those of known trusted hosts.
.IP "\fB\-\-bootstrap\-ca\-cert=\fIcacert.pem\fR"
When \fIcacert.pem\fR exists, this option has the same effect as
\fB\-C\fR or \fB\-\-ca\-cert\fR.  If it does not exist, then
\fB\*(PN\fR will attempt to obtain the CA certificate from the
SSL peer on its first SSL connection and save it to the named PEM
file.  If it is successful, it will immediately drop the connection
and reconnect, and from then on all SSL connections must be
authenticated by a certificate signed by the CA certificate thus
obtained.
.IP
\fBThis option exposes the SSL connection to a man-in-the-middle
attack obtaining the initial CA certificate\fR, but it may be useful
for bootstrapping.
.IP
This option is only useful if the SSL peer sends its CA certificate as
part of the SSL certificate chain.  The SSL protocol does not require
the server to send the CA certificate.
.IP
This option is mutually exclusive with \fB\-C\fR and
\fB\-\-ca\-cert\fR.
.SS "SSL Connection Options"
.IP "\fB\-\-ssl\-protocols=\fIprotocols\fR"
Specifies, in a comma- or space-delimited list, the SSL protocols
\fB\*(PN\fR will enable for SSL connections.  Supported
\fIprotocols\fR include \fBTLSv1\fR, \fBTLSv1.1\fR, and \fBTLSv1.2\fR.
Regardless of order, the highest protocol supported by both sides will
be chosen when making the connection.  The default when this option is
omitted is \fBTLSv1,TLSv1.1,TLSv1.2\fR.
.
.IP "\fB\-\-ssl\-ciphers=\fIciphers\fR"
Specifies, in OpenSSL cipher string format, the ciphers \fB\*(PN\fR will 
support for SSL connections.  The default when this option is omitted is
\fBHIGH:!aNULL:!MD5\fR.
.SS "Other Options"
.IP "\fB\-h\fR"
.IQ "\fB\-\-help\fR"
Prints a brief help message to the console.
.
.IP "\fB\-V\fR"
.IQ "\fB\-\-version\fR"
Prints version information to the console.
.SH "SEE ALSO"
.
\fBovsdb\fR(7),
\fBovsdb\-server\fR(1),
\fBovsdb\-client\fR(1).