. RS -0.15in
. I "\\$1"
. RE
-. PP
..
.TH ovs\-vsctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual"
+.\" This program's name:
.ds PN ovs\-vsctl
+.\" SSL peer program's name:
+.ds SN ovsdb\-server
.
.SH NAME
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"
Prevents \fBovs\-vsctl\fR from waiting for \fBovs\-vswitchd\fR to
reconfigure itself according to the the modified database. This
option should be used if \fBovs\-vswitchd\fR is not running;
-otherwise, \fBovs-vsctl\fR will not exit until \fBovs-vswitchd\fR
+otherwise, \fBovs\-vsctl\fR will not exit until \fBovs\-vswitchd\fR
starts.
.IP
This option has no effect if the commands specified do not change the
.IP "\fB\-\-dry\-run\fR"
Prevents \fBovs\-vsctl\fR from actually modifying the database.
.
-.IP "\fB-t \fIsecs\fR"
-.IQ "\fB--timeout=\fIsecs\fR"
-Limits runtime to approximately \fIsecs\fR seconds. A value of
-zero will cause \fBovs\-vsctl\fR to wait forever. If the timeout expires,
-\fBovs\-vsctl\fR will exit with a \fBSIGALRM\fR signal. If this option is
-not used, \fBovs\-vsctl\fR uses a timeout of five seconds.
-(A timeout would normally happen only if the database cannot be contacted.)
+.IP "\fB\-t \fIsecs\fR"
+.IQ "\fB\-\-timeout=\fIsecs\fR"
+By default, or with a \fIsecs\fR of \fB0\fR, \fBovs\-vsctl\fR waits
+forever for a response from the database. This option limits runtime
+to approximately \fIsecs\fR seconds. If the timeout expires,
+\fBovs\-vsctl\fR will exit with a \fBSIGALRM\fR signal. (A timeout
+would normally happen only if the database cannot be contacted, or if
+the system is overloaded.)
.
+.SS "Public Key Infrastructure Options"
.so lib/ssl.man
+.so lib/ssl-bootstrap.man
+.so lib/ssl-peer-ca-cert.man
.so lib/vlog.man
.
.SH COMMANDS
Open vSwitch database if it is empty. This command is provided to
initialize the database without executing any other command.
.
+.IP "\fBemer\-reset\fR"
+Reset the configuration into a clean state. It deconfigures OpenFlow
+controllers, OVSDB servers, and SSL, and deletes port mirroring,
+NetFlow, and sFlow configuration. This command also removes all
+\fBother\-config\fR keys from all database records, except that
+\fBother\-config:hwaddr\fR is preserved if it is present in a Bridge
+record. Other networking configuration is left as-is.
+.
.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
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.
.SS "OpenFlow Controller Connectivity"
.
\fBovs\-vswitchd\fR can perform all configured bridging and switching
-locally, or it can be configured to connect a given bridge to an
-external OpenFlow controller, such as NOX.
-.
-If a \fIbridge\fR argument is given, the settings apply only to the
-specified bridge. Otherwise, they apply to the Open vSwitch instance,
-and its configuration applies to any bridge that has not been explicitly
-configured through a \fIbridge\fR argument.
+locally, or it can be configured to connect a given bridge to one or
+more external OpenFlow controllers, such as NOX.
.
-.IP "\fBget\-controller\fR [\fIbridge\fR]"
+.IP "\fBget\-controller\fR \fIbridge\fR"
Prints the configured controller target.
.
-.IP "\fBdel\-controller\fR [\fIbridge\fR]"
+.IP "\fBdel\-controller\fR \fIbridge\fR"
Deletes the configured controller target.
.
-.IP "\fBset\-controller\fR [\fIbridge\fR] \fItarget\fR"
-Sets the configured controller target. The \fItarget\fR may use any of
-the following forms:
+.IP "\fBset\-controller\fR \fIbridge\fR \fItarget\fR\&..."
+Sets the configured controller target or targets. Each \fItarget\fR may
+use any of the following forms:
.
.RS
.so lib/vconn-active.man
.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
If this option is set to \fBsecure\fR, \fBovs\-vswitchd\fR will not
set up flows on its own when the controller connection fails.
.
-.IP "\fBget\-fail\-mode\fR [\fIbridge\fR]"
+.IP "\fBget\-fail\-mode\fR \fIbridge\fR"
Prints the configured failure mode.
.
-.IP "\fBdel\-fail\-mode\fR [\fIbridge\fR]"
+.IP "\fBdel\-fail\-mode\fR \fIbridge\fR"
Deletes the configured failure mode.
.
-.IP "\fBset\-fail\-mode\fR [\fIbridge\fR] \fBstandalone\fR|\fBsecure\fR"
+.IP "\fBset\-fail\-mode\fR \fIbridge\fR \fBstandalone\fR|\fBsecure\fR"
Sets the configured failure mode.
.
.SS "SSL Configuration"
When \fBovs\-vswitchd\fR is configured to connect over SSL for management or
controller connectivity, the following parameters are required:
.TP
-\fBprivate-key\fR
+\fBprivate\-key\fR
Specifies a PEM file containing the private key used as the virtual
switch's identity for SSL connections to the controller.
.TP
certifies the virtual switch's private key, identifying a trustworthy
switch.
.TP
-\fBca-cert\fR
+\fBca\-cert\fR
Specifies a PEM file containing the CA certificate used to verify that
the virtual switch is connected to a trustworthy controller.
.PP
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
This option is only useful if the controller sends its CA certificate
as part of the SSL certificate chain. The SSL protocol does not
require the controller to send the CA certificate, but
-\fBcontroller\fR(8) can be configured to do so with the
-\fB--peer-ca-cert\fR option.
+\fBovs\-controller\fR(8) can be configured to do so with the
+\fB\-\-peer\-ca\-cert\fR option.
.
.SS "Database Commands"
.
.IP "\fBInterface\fR"
A network device attached to a port. Records may be identified by
name.
-.IP "\fBController\fR"
-Configuration for an OpenFlow controller. A controller attached to a
-particular bridge may be identified by the bridge's name. The default
-controller controller for an Open vSwitch may be identified by
-specifying \fB.\fR as the record name.
.IP "\fBMirror\fR"
A port mirroring configuration attached to a bridge. Records may be
identified by mirror name.
+.IP "\fBController\fR"
+Configuration for an OpenFlow controller. A controller attached to a
+particular bridge may be identified by the bridge's name.
.IP "\fBNetFlow\fR"
A NetFlow configuration attached to a bridge. Records may be
identified by bridge name.
+.IP "\fBSSL\fR"
+The global SSL configuration for \fBovs\-vswitchd\fR. The record
+attached to the \fBOpen_vSwitch\fR table may be identified by
+specifying \fB.\fR as the record name.
+.IP "\fBsFlow\fR"
+An sFlow configuration attached to a bridge. Records may be
+identified by bridge name.
.PP
-Names of tables, records, and columns are not case-sensitive, and
-\fB--\fR and \fB_\fR are treated interchangeably. Unique
-abbreviations are acceptable, e.g. \fBnet\fR or \fRn\fR is sufficient
+Record names must be specified in full and with correct
+capitalization. Names of tables and columns are not case-sensitive,
+and \fB\-\-\fR and \fB_\fR are treated interchangeably. Unique
+abbreviations are acceptable, e.g. \fBnet\fR or \fBn\fR is sufficient
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"
escape special characters. The empty string must be represented as a
pair of double quotes (\fB""\fR).
.IP "UUID"
-A universally unique identifier in the style of RFC 4122,
-e.g. \fBf81d4fae-7dec-11d0-a765-00a0c91e6bf6\fR.
+Either a universally unique identifier in the style of RFC 4122,
+e.g. \fBf81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\fR, or an \fB@\fIname\fR
+defined by the \fBcreate\fR command within the same \fBovs\-vsctl\fR
+invocation.
.PP
Multiple values in a single column may be separated by spaces or a
single comma. When multiple values are present, duplicates are not
as well.
.
.ST "Database Command Syntax"
-.PP
-By default, database commands refuse to make some kinds of
-modifications that could violate database structuring constraints. If
-you are sure that you know what you are doing, use \fB\-\-force\fR to
-override this safety measure. Constraints that are enforced by the
-database server itself, instead of by \fBovs\-vsctl\fR, cannot be
-overridden this way.
-.
.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.
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 "[\fB\-\-force\fR] \fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
+.IP "\fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
Sets the value of each specified \fIcolumn\fR in the given
\fIrecord\fR in \fItable\fR to \fIvalue\fR. For map columns, a
\fIkey\fR may optionally be specified, in which case the value
associated with \fIkey\fR in that column is changed (or added, if none
exists), instead of the entire map.
.
-.IP "[\fB\-\-force\fR] \fBadd \fItable record column \fR[\fIkey\fB=\fR]\fIvalue\fR..."
+.IP "\fBadd \fItable record column \fR[\fIkey\fB=\fR]\fIvalue\fR..."
Adds the specified value or key-value pair to \fIcolumn\fR in
\fIrecord\fR in \fItable\fR. If \fIcolumn\fR is a map, then \fIkey\fR
is required, otherwise it is prohibited. If \fIkey\fR already exists
in a map column, then the current \fIvalue\fR is not replaced (use the
\fBset\fR command to replace an existing value).
.
-.IP "[\fB\-\-force\fR] \fBremove \fItable record column \fR\fIvalue\fR..."
-.IQ "[\fB\-\-force\fR] \fBremove \fItable record column \fR\fIkey\fR..."
-.IQ "[\fB\-\-force\fR] \fBremove \fItable record column \fR\fIkey\fB=\fR\fIvalue\fR..."
+.IP "\fBremove \fItable record column \fR\fIvalue\fR..."
+.IQ "\fBremove \fItable record column \fR\fIkey\fR..."
+.IQ "\fBremove \fItable record column \fR\fIkey\fB=\fR\fIvalue\fR..."
Removes the specified values or key-value pairs from \fIcolumn\fR in
\fIrecord\fR in \fItable\fR. The first form applies to columns that
are not maps: each specified \fIvalue\fR is removed from the column.
It is not an error if the column does not contain the specified key or
value or pair.
.
-.IP "\fB[\fB\-\-force\fR] \fBclear\fR \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 "\fB\-\-force create \fItable column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
+.IP "[\fB\-\-id=@\fIname\fR] \fBcreate\fR \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
-This command requires the \fB\-\-force\fR option.
+If \fB@\fIname\fR is specified, then the UUID for the new row may be
+referred to by that name elsewhere in the same \fBovs\-vsctl\fR
+invocation in contexts where a UUID is expected. Such references may
+precede or follow the \fBcreate\fR command.
.
-.IP "\fB\-\-force \fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..."
+.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.
+.
+.IP "\fBwait\-until \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..."
+Waits until \fItable\fR contains a record named \fIrecord\fR whose
+\fIcolumn\fR equals \fIvalue\fR or, if \fIkey\fR is specified, whose
+\fIcolumn\fR contains a \fIkey\fR with the specified \fIvalue\fR. Any
+of the operators \fB!=\fR, \fB<\fR, \fB>\fR, \fB<=\fR, or \fB>=\fR may
+be substituted for \fB=\fR to test for inequality, less than, greater
+than, less than or equal to, or greater than or equal to,
+respectively. (Don't forget to escape \fB<\fR or \fB>\fR from
+interpretation by the shell.)
+.IP
+If no \fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR arguments are given,
+this command waits only until \fIrecord\fR exists. If more than one
+such argument is given, the command waits until all of them are
+satisfied.
.IP
-This command requires the \fB\-\-force\fR option.
+Usually \fBwait\-until\fR should be placed at the beginning of a set
+of \fBovs\-vsctl\fR commands. For example, \fBwait\-until bridge br0
+\-\- get bridge br0 datapath_id\fR waits until a bridge named
+\fBbr0\fR is created, then prints its \fBdatapath_id\fR column,
+whereas \fBget bridge br0 datapath_id \-\- wait\-until bridge br0\fR
+will abort if no bridge named \fBbr0\fR exists when \fBovs\-vsctl\fR
+initially connects to the database.
+.IP
+Consider specifying \fB\-\-timeout=0\fR along with
+\fB\-\-wait\-until\fR, to prevent \fBovs\-vsctl\fR from terminating
+after waiting only at most 5 seconds.
.SH "EXAMPLES"
Create a new bridge named br0 and add port eth0 to it:
.IP
-.B "ovs-vsctl add\-br br0"
+.B "ovs\-vsctl add\-br br0"
.br
-.B "ovs-vsctl add\-port br0 eth0"
+.B "ovs\-vsctl add\-port br0 eth0"
.PP
Alternatively, perform both operations in a single atomic transaction:
.IP
-.B "ovs-vsctl add\-br br0 \-\- add\-port br0 eth0"
+.B "ovs\-vsctl add\-br br0 \-\- add\-port br0 eth0"
.PP
Delete bridge \fBbr0\fR, reporting an error if it does not exist:
.IP
separate \fBdel\-br\fR's options from the global options):
.IP
.B "ovs\-vsctl \-\- \-\-if\-exists del\-br br0"
+.PP
+Set the \fBqos\fR column of the \fBPort\fR record for \fBeth0\fR to
+point to a new \fBQoS\fR record, which in turn points with its queue 0
+to a new \fBQueue\fR record:
+.IP
+.B "ovs\-vsctl \-\- set port eth0 qos=@newqos \-\- \-\-id=@newqos create qos type=linux\-htb other\-config:max\-rate=1000000 queues:0=@newqueue \-\- \-\-id=@newqueue create queue other\-config:min\-rate=1000000 other\-config:max\-rate=1000000"
.
.SH "EXIT STATUS"
.IP "0"
.
.BR ovsdb\-server (1),
.BR ovs\-vswitchd (8).
+\
git://git.onelab.eu / sliver-openvswitch.git / blobdiff