. RS -0.15in
. I "\\$1"
. RE
-. PP
..
.TH ovs\-vsctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual"
.ds PN ovs\-vsctl
ovs\-vsctl \- utility for querying and configuring \fBovs\-vswitchd\fR
.
.SH SYNOPSIS
-\fBovs\-vsctl\fR [\fIoptions\fR] [\fB\-\-\fR] \fIcommand \fR[\fIargs\fR\&...]
-[\fB\-\-\fR \fIcommand \fR[\fIargs\fR\&...]]
+\fBovs\-vsctl\fR [\fIoptions\fR] \fB\-\-\fR [\fIoptions\fR] \fIcommand
+\fR[\fIargs\fR] [\fB\-\-\fR [\fIoptions\fR] \fIcommand \fR[\fIargs\fR]]...
.
.SH DESCRIPTION
The \fBovs\-vsctl\fR program configures \fBovs\-vswitchd\fR(8) by
-providing a high\-level interface to editing its configuration
+providing a high\-level interface to its configuration
database. This program is mainly intended for use when
\fBovs\-vswitchd\fR is running. If it is used when
\fBovs\-vswitchd\fR is not running, then \fB\-\-no\-wait\fR should be
.PP
\fBovs\-vsctl\fR can perform any number of commands in a single run,
implemented as a single atomic transaction against the database.
-Commands are separated on the command line by \fB\-\-\fR arguments.
+.PP
+The \fBovs\-vsctl\fR command line begins with global options (see
+\fBOPTIONS\fR below for details). The global options are followed by
+one or more commands. Each command should begin with \fB\-\-\fR by
+itself as a command-line argument, to separate it from the global
+options and following commands. (If the first command does not have
+any options, then the first \fB\-\-\fR may be omitted.) The command
+itself starts with command-specific options, if any, followed by the
+command name and any arguments. See \fBEXAMPLES\fR below for syntax
+examples.
.
.SS "Linux VLAN Bridging Compatibility"
The \fBovs\-vsctl\fR program supports the model of a bridge
.IP "\fB\-\-db=\fIserver\fR"
Sets \fIserver\fR as the database server that \fBovs\-vsctl\fR
contacts to query or modify configuration. The default is
-\fBunix:@RUNDIR@/ovsdb\-server\fR. \fIserver\fR must take one of the
+\fBunix:@RUNDIR@/db.sock\fR. \fIserver\fR must take one of the
following forms:
.RS
.so ovsdb/remote-active.man
+.so ovsdb/remote-passive.man
.RE
.
.IP "\fB\-\-no\-wait\fR"
not used, \fBovs\-vsctl\fR uses a timeout of five seconds.
(A timeout would normally happen only if the database cannot be contacted.)
.
+.SS "Public Key Infrastructure Options"
.so lib/ssl.man
.so lib/vlog.man
.
.SS "Bridge Commands"
These commands examine and manipulate Open vSwitch bridges.
.
-.IP "\fBadd\-br \fIbridge\fR"
+.IP "[\fB\-\-may\-exist\fR] \fBadd\-br \fIbridge\fR"
Creates a new bridge named \fIbridge\fR. Initially the bridge will
have no ports (other than \fIbridge\fR itself).
+.IP
+Without \fB\-\-may\-exist\fR, attempting to create a bridge that
+exists is an error. With \fB\-\-may\-exist\fR, \fIbridge\fR may
+already exist (but it must be a real bridge, not a VLAN bridge).
.
-.IP "\fBadd\-br \fIbridge parent vlan\fR"
+.IP "[\fB\-\-may\-exist\fR] \fBadd\-br \fIbridge parent vlan\fR"
Creates a ``fake bridge'' named \fIbridge\fR within the existing Open
vSwitch bridge \fIparent\fR, which must already exist and must not
itself be a fake bridge. The new fake bridge will be on 802.1Q VLAN
\fIvlan\fR, which must be an integer between 1 and 4095. Initially
\fIbridge\fR will have no ports (other than \fIbridge\fR itself).
+.IP
+Without \fB\-\-may\-exist\fR, attempting to create a bridge that
+exists is an error. With \fB\-\-may\-exist\fR, \fIbridge\fR may
+already exist (but it must have the specified \fIvlan\fR and
+\fIparent\fR).
.
.IP "[\fB\-\-if\-exists\fR] \fBdel\-br \fIbridge\fR"
Deletes \fIbridge\fR and all of its ports. If \fIbridge\fR is a real
\fIbridge\fR, overwriting any previous value. If \fIvalue\fR is
omitted, then \fIkey\fR is removed from \fIbridge\fR's set of external
IDs (if it was present).
+.IP
+For real bridges, the effect of this command is similar to that of a
+\fBset\fR or \fBremove\fR command in the \fBexternal\-ids\fR column of
+the \fBBridge\fR table. For fake bridges, it actually modifies keys
+with names prefixed by \fBfake\-bridge\-\fR in the \fBPort\fR table.
.
.IP "\fBbr\-get\-external\-id \fIbridge\fR [\fIkey\fR]"
Queries the external IDs on \fIbridge\fR. If \fIkey\fR is specified,
the output is the value for that \fIkey\fR or the empty string if
\fIkey\fR is unset. If \fIkey\fR is omitted, the output is
\fIkey\fB=\fIvalue\fR, one per line, for each key-value pair.
+.IP
+For real bridges, the effect of this command is similar to that of a
+\fBget\fR command in the \fBexternal\-ids\fR column of the
+\fBBridge\fR table. For fake bridges, it queries keys with names
+prefixed by \fBfake\-bridge\-\fR in the \fBPort\fR table.
.
.SS "Port Commands"
.
Lists all of the ports within \fIbridge\fR on standard output, one per
line. The local port \fIbridge\fR is not included in the list.
.
-.IP "\fBadd\-port \fIbridge port\fR"
+.IP "[\fB\-\-may\-exist\fR] \fBadd\-port \fIbridge port \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fR=\fIvalue\fR]\&...\fR"
Creates on \fIbridge\fR a new port named \fIport\fR from the network
device of the same name.
+.IP
+Optional arguments set values of column in the Port record created by
+the command. For example, \fBtag=9\fR would make the port an access
+port for VLAN 9. The syntax is the same as that for the \fBset\fR
+command (see \fBDatabase Commands\fR below).
+.IP
+Without \fB\-\-may\-exist\fR, attempting to create a port that exists
+is an error. With \fB\-\-may\-exist\fR, \fIport\fR may already exist
+(but it must be on \fIbridge\fR and not be a bonded port).
.
-.IP "[\fB\-\-fake\-iface\fR] \fBadd\-bond \fIbridge port iface\fR\&..."
+.IP "[\fB\-\-fake\-iface\fR] \fBadd\-bond \fIbridge port iface\fR\&... [\fIcolumn\fR[\fB:\fIkey\fR]\fR=\fIvalue\fR]\&...\fR"
Creates on \fIbridge\fR a new port named \fIport\fR that bonds
together the network devices given as each \fIiface\fR. At least two
interfaces must be named.
.IP
+Optional arguments set values of column in the Port record created by
+the command. The syntax is the same as that for the \fBset\fR command
+(see \fBDatabase Commands\fR below).
+.IP
With \fB\-\-fake\-iface\fR, a fake interface with the name \fIport\fR is
created. This should only be used for compatibility with legacy
software that requires it.
+.IP
+Without \fB\-\-may\-exist\fR, attempting to create a port that exists
+is an error. With \fB\-\-may\-exist\fR, \fIport\fR may already exist
+(but it must be on \fIbridge\fR and bond together exactly the
+specified interface).
.
.IP "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIbridge\fR] \fIport\fR"
Deletes \fIport\fR. If \fIbridge\fR is omitted, \fIport\fR is removed
not exist is an error. With \fB\-\-if\-exists\fR, attempting to
delete a port that does not exist has no effect.
.
+.IP "[\fB\-\-if\-exists\fR] \fB\-\-with\-iface del\-port \fR[\fIbridge\fR] \fIiface\fR"
+Deletes the port named \fIiface\fR or that has an interface named
+\fIiface\fR. If \fIbridge\fR is omitted, the port is removed from
+whatever bridge contains it; if \fIbridge\fR is specified, it must be
+the real or fake bridge that contains the port.
+.IP
+Without \fB\-\-if\-exists\fR, attempting to delete the port for an
+interface that does not exist is an error. With \fB\-\-if\-exists\fR,
+attempting to delete the port for an interface that does not exist has
+no effect.
+.
.IP "\fBport\-to\-br \fIport\fR"
Prints the name of the bridge that contains \fIport\fR on standard
output.
.
-.IP "\fBport\-set\-external\-id \fIport key\fR [\fIvalue\fR]"
-Sets or clears an ``external ID'' value on \fIport\fR. These value
-are intended to identify entities external to Open vSwitch with which
-\fIport\fR is associated, e.g. the port's identifier in a
-virtualization management platform. The Open vSwitch database schema
-specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR
-are otherwise arbitrary strings.
-.IP
-If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for
-\fIport\fR, overwriting any previous value. If \fIvalue\fR is
-omitted, then \fIkey\fR is removed from \fIport\fR's set of external
-IDs (if it was present).
-.
-.IP "\fBbr\-get\-external\-id \fIport\fR [\fIkey\fR]"
-Queries the external IDs on \fIport\fR. If \fIkey\fR is specified,
-the output is the value for that \fIkey\fR or the empty string if
-\fIkey\fR is unset. If \fIkey\fR is omitted, the output is
-\fIkey\fB=\fIvalue\fR, one per line, for each key-value pair.
-.
.SS "Interface Commands"
.
These commands examine the interfaces attached to an Open vSwitch
Prints the name of the bridge that contains \fIiface\fR on standard
output.
.
-.IP "\fBiface\-set\-external\-id \fIiface key\fR [\fIvalue\fR]"
-Sets or clears an ``external ID'' value on \fIiface\fR. These value
-are intended to identify entities external to Open vSwitch with which
-\fIiface\fR is associated, e.g. the interface's identifier in a
-virtualization management platform. The Open vSwitch database schema
-specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR
-are otherwise arbitrary strings.
-.IP
-If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for
-\fIiface\fR, overwriting any previous value. If \fIvalue\fR is
-omitted, then \fIkey\fR is removed from \fIiface\fR's set of external
-IDs (if it was present).
-.
-.IP "\fBbr\-get\-external\-id \fIiface\fR [\fIkey\fR]"
-Queries the external IDs on \fIiface\fR. If \fIkey\fR is specified,
-the output is the value for that \fIkey\fR or the empty string if
-\fIkey\fR is unset. If \fIkey\fR is omitted, the output is
-\fIkey\fB=\fIvalue\fR, one per line, for each key-value pair.
-.
.SS "OpenFlow Controller Connectivity"
.
\fBovs\-vswitchd\fR can perform all configured bridging and switching
.RE
.
.ST "Controller Failure Settings"
-.
+.PP
When a controller is configured, it is, ordinarily, responsible for
setting up all flows on the switch. Thus, if the connection to
the controller fails, no new network connections can be set up. If
below.
.
.ST "CA Certificate Bootstrap"
+.PP
Ordinarily, all of the files named in the SSL configuration must exist
when \fBovs\-vswitchd\fR starts. However, if the \fB\-\-bootstrap\fR
option is given, then \fBovs\-vswitchd\fR will attempt to obtain the
to identify the \fBNetFlow\fR table.
.
.ST "Database Values"
+.PP
Each column in the database accepts a fixed type of data. The
currently defined basic types, and their representations, are:
.IP "integer"
as well.
.
.ST "Database Command Syntax"
-.
.IP "\fBlist \fItable \fR[\fIrecord\fR]..."
List the values of all columns of each specified \fIrecord\fR. If no
records are specified, lists all the records in \fItable\fR.
+.IP
+The UUIDs shown for rows created in the same \fBovs\-vsctl\fR
+invocation will be wrong.
.
-.IP "\fBget \fItable record column\fR[\fB:\fIkey\fR]..."
+.IP "[\fB\-\-if\-exists\fR] \fBget \fItable record column\fR[\fB:\fIkey\fR]..."
Prints the value of each specified \fIcolumn\fR in the given
\fIrecord\fR in \fItable\fR. For map columns, a \fIkey\fR may
optionally be specified, in which case the value associated with
\fIkey\fR in the column is printed, instead of the entire map.
+.IP
+For a map column, without \fB\-\-if\-exists\fR it is an error if
+\fIkey\fR does not exist; with it, a blank line is printed. If
+\fIcolumn\fR is not a map column or if \fIkey\fR is not specified,
+\fB\-\-if\-exists\fR has no effect.
.
.IP "\fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
Sets the value of each specified \fIcolumn\fR in the given
It is not an error if the column does not contain the specified key or
value or pair.
.
-.IP "\fBclear \fItable record column\fR..."
+.IP "\fBclear\fR \fItable record column\fR..."
Sets each \fIcolumn\fR in \fIrecord\fR in \fItable\fR to the empty set
or empty map, as appropriate. This command applies only to columns
that are allowed to be empty.
.
+.IP "create \fItable column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
+Creates a new record in \fItable\fR and sets the initial values of
+each \fIcolumn\fR. Columns not explicitly set will receive their
+default values. Outputs the UUID of the new row.
+.
+.IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..."
+Deletes each specified \fIrecord\fR from \fItable\fR. Unless
+\fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist.
.SH "EXAMPLES"
Create a new bridge named br0 and add port eth0 to it:
.IP
projects / openvswitch / blobdiff