. I "\\$1"
. RE
..
-.TH ovs\-vsctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual"
+.TH ovs\-vsctl 8 "@VERSION@" "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 DESCRIPTION
The \fBovs\-vsctl\fR program configures \fBovs\-vswitchd\fR(8) by
-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
-specified and configuration changes will only take effect when
-\fBovs\-vswitchd\fR is started.
-.PP
-By default, each time \fBovs\-vsctl\fR runs, it connects to an
-\fBovsdb\-server\fR process that maintains an Open vSwitch
-configuration database. Using this connection, it queries and
-possibly applies changes to the database, depending on the supplied
-commands. Then, if it applied any changes, it waits until
-\fBovs\-vswitchd\fR has finished reconfiguring itself before it exits.
+providing a high\-level interface to its configuration database.
+See \fBovs\-vswitchd.conf.db\fR(5) for comprehensive documentation of
+the database schema.
+.PP
+\fBovs\-vsctl\fR connects to an \fBovsdb\-server\fR process that
+maintains an Open vSwitch configuration database. Using this
+connection, it queries and possibly applies changes to the database,
+depending on the supplied commands. Then, if it applied any changes,
+by default it waits until \fBovs\-vswitchd\fR has finished
+reconfiguring itself before it exits. (If you use \fBovs\-vsctl\fR
+when \fBovs\-vswitchd\fR is not running, use \fB\-\-no\-wait\fR.)
.PP
\fBovs\-vsctl\fR can perform any number of commands in a single run,
implemented as a single atomic transaction against the database.
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 as a command-line argument, to separate it from the following
+commands. (The \fB\-\-\fR before the first command is optional.) 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.
much like a bridge separate from its ``parent bridge,'' but the actual
implementation in Open vSwitch uses only a single bridge, with ports on
the fake bridge assigned the implicit VLAN of the fake bridge of which
-they are members.
+they are members. (A fake bridge for VLAN 0 receives packets that
+have no 802.1Q tag or a tag with VLAN 0.)
.
.SH OPTIONS
.
would normally happen only if the database cannot be contacted, or if
the system is overloaded.)
.
+.IP "\fB\-\-retry\fR"
+Without this option, if \fBovs\-vsctl\fR connects outward to the
+database server (the default) then \fBovs\-vsctl\fR will try to
+connect once and exit with an error if the connection fails (which
+usually means that \fBovsdb\-server\fR is not running).
+.IP
+With this option, or if \fB\-\-db\fR specifies that \fBovs\-vsctl\fR
+should listen for an incoming connection from the database server,
+then \fBovs\-vsctl\fR will wait for a connection to the database
+forever.
+.IP
+Regardless of this setting, \fB\-\-timeout\fR always limits how long
+\fBovs\-vsctl\fR will wait.
+.
.SS "Table Formatting Options"
These options control the format of output from the \fBlist\fR and
\fBfind\fR commands.
.so lib/ssl-bootstrap.man
.so lib/ssl-peer-ca-cert.man
.so lib/vlog.man
+.so lib/common.man
.
.SH COMMANDS
The commands implemented by \fBovs\-vsctl\fR are described in the
.IP "\fBemer\-reset\fR"
Reset the configuration into a clean state. It deconfigures OpenFlow
controllers, OVSDB servers, and SSL, and deletes port mirroring,
-\fBfail_mode\fR, 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.
+\fBfail_mode\fR, NetFlow, sFlow, and IPFIX 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.
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
+\fIvlan\fR, which must be an integer between 0 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
not exist is an error. With \fB\-\-if\-exists\fR, attempting to
delete a bridge that does not exist has no effect.
.
-.IP "\fBlist\-br\fR"
+.IP "[\fB\-\-real\fR|\fB\-\-fake\fR] \fBlist\-br\fR"
Lists all existing real and fake bridges on standard output, one per
-line.
+line. With \fB\-\-real\fR or \fB\-\-fake\fR, only bridges of that type
+are returned.
.
.IP "\fBbr\-exists \fIbridge\fR"
Tests whether \fIbridge\fR exists as a real or fake bridge. If so,
.PP
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
-\fBovs\-controller\fR(8) can be configured to do so with the
-\fB\-\-peer\-ca\-cert\fR option.
+require the controller to send the CA certificate.
.
.SS "Database Commands"
.
.IP "\fBInterface\fR"
A network device attached to a port. Records may be identified by
name.
+.IP "\fBFlow_Table\fR"
+Configuration for a particular OpenFlow flow table. Records may be
+identified by name.
.IP "\fBQoS\fR"
Quality-of-service configuration for a \fBPort\fR. Records may be
identified by port name.
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
+An sFlow exporter configuration attached to a bridge. Records may be
identified by bridge name.
+.IP "\fBIPFIX\fR"
+An IPFIX exporter configuration attached to a bridge. Records may be
+identified by bridge name.
+.IP "\fBFlow_Sample_Collector_Set\fR"
+An IPFIX exporter configuration attached to a bridge for sampling
+packets on a per-flow basis using OpenFlow \fBsample\fR actions.
.PP
Record names must be specified in full and with correct
capitalization. Names of tables and columns are not case-sensitive,
other-config=1=y\fR, which may not have the desired effect).
.
.ST "Database Command Syntax"
-.IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..."
+.
+.IP "[\fB\-\-if\-exists\fR] [\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..."
Lists the data in each specified \fIrecord\fR. If no
records are specified, lists all the records in \fItable\fR.
.IP
If \fB\-\-columns\fR is specified, only the requested columns are
listed, in the specified order. Otherwise, all columns are listed, in
alphabetical order by column name.
+.IP
+Without \fB\-\-if-exists\fR, it is an error if any specified
+\fIrecord\fR does not exist. With \fB\-\-if-exists\fR, the command
+ignores any \fIrecord\fR that does not exist, without producing any
+output.
.
.IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBfind \fItable \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..."
Lists the data in each record in \fItable\fR whose \fIcolumn\fR equals
The UUIDs shown for rows created in the same \fBovs\-vsctl\fR
invocation will be wrong.
.
-.IP "[\fB\-\-id=@\fIname\fR] [\fB\-\-if\-exists\fR] \fBget \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]]..."
+.IP "[\fB\-\-if\-exists\fR] [\fB\-\-id=@\fIname\fR] \fBget \fItable record \fR[\fIcolumn\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.
+Without \fB\-\-if\-exists\fR, it is an error if \fIrecord\fR does not
+exist or \fIkey\fR is specified, if \fIkey\fR does not exist in
+\fIrecord\fR. With \fB\-\-if\-exists\fR, a missing \fIrecord\fR
+yields no output and a missing \fIkey\fR prints a blank line.
.IP
If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be
referred to by that name later in the same \fBovs\-vsctl\fR
usually at least one or the other should be specified. If both are
omitted, then \fBget\fR has no effect except to verify that
\fIrecord\fR exists in \fItable\fR.
+.IP
+\fB\-\-id\fR and \fB\-\-if\-exists\fR cannot be used together.
.
-.IP "\fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
+.IP "[\fB\-\-if\-exists\fR] \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
+Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
+exist. With \fB\-\-if-exists\fR, this command does nothing if
+\fIrecord\fR does not exist.
.
-.IP "\fBadd \fItable record column \fR[\fIkey\fB=\fR]\fIvalue\fR..."
+.IP "[\fB\-\-if\-exists\fR] \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
+Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
+exist. With \fB\-\-if-exists\fR, this command does nothing if
+\fIrecord\fR does not exist.
.
-.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..."
+.IP "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIvalue\fR..."
+.IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIkey\fR..."
+.IQ "[\fB\-\-if\-exists\fR] \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.
.IP
It is not an error if the column does not contain the specified key or
value or pair.
+.IP
+Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
+exist. With \fB\-\-if-exists\fR, this command does nothing if
+\fIrecord\fR does not exist.
.
-.IP "\fBclear\fR \fItable record column\fR..."
+.IP "[\fB\-\-if\-exists\fR] \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
+Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
+exist. With \fB\-\-if-exists\fR, this command does nothing if
+\fIrecord\fR does not exist.
.
.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
.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 "\fB\-\-all destroy \fItable\fR"
+Deletes all records from the \fItable\fR.
.IP
The \fBdestroy\fR command is only useful for records in the \fBQoS\fR
or \fBQueue\fR tables. Records in other tables are automatically
.IP
.B "ovs\-vsctl del\-br br0"
.PP
-Delete bridge \fBbr0\fR if it exists (the \fB\-\-\fR is required to
-separate \fBdel\-br\fR's options from the global options):
+Delete bridge \fBbr0\fR if it exists:
.IP
-.B "ovs\-vsctl \-\- \-\-if\-exists del\-br br0"
+.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
Remove the mirror created above from \fBbr0\fR, which also destroys
the Mirror record (since it is now unreferenced):
.IP
-.B "remove Bridge br0 mirrors mymirror"
+.B "ovs\-vsctl \-\- \-\-id=@rec get Mirror mymirror \(rs"
+.IP
+.B "\-\- remove Bridge br0 mirrors @rec"
+.PP
+The following simpler command also works:
+.IP
+.B "ovs\-vsctl clear Bridge br0 mirrors"
.SS "Quality of Service (QoS)"
.PP
Create a \fBlinux\-htb\fR QoS record that points to a few queues and
(This command will leave two unreferenced Queue records in the
database. To delete them, use "\fBovs\-vsctl list Queue\fR" to find
their UUIDs, then "\fBovs\-vsctl destroy Queue \fIuuid1\fR
-\fIuuid2\fR" to destroy each of them.)
+\fIuuid2\fR" to destroy each of them or use
+"\fBovs\-vsctl -- --all destroy Queue\fR" to delete all records.)
.SS "Connectivity Monitoring"
.PP
Monitor connectivity to a remote maintenance point on eth0.
(since it is now unreferenced):
.IP
.B "ovs\-vsctl \-\- clear Bridge br0 sflow"
+.SS "IPFIX"
+.PP
+Configure bridge \fBbr0\fR to send one IPFIX flow record per packet
+sample to UDP port 4739 on host 192.168.0.34, with Observation Domain
+ID 123 and Observation Point ID 456, a flow cache active timeout of 1
+minute (60 seconds), and a maximum flow cache size of 13 flows:
+.IP
+.B "ovs\-vsctl \-\- set Bridge br0 ipfix=@i \(rs"
+.IP
+.B "\-\- \-\-id=@i create IPFIX targets=\(rs\(dq192.168.0.34:4739\(rs\(dq obs_domain_id=123 obs_point_id=456 cache_active_timeout=60 cache_max_flows=13"
+.PP
+Deconfigure the IPFIX settings from \fBbr0\fR, which also destroys the
+IPFIX record (since it is now unreferenced):
+.IP
+.B "ovs\-vsctl clear Bridge br0 ipfix"
.SS "802.1D Spanning Tree Protocol (STP)"
.PP
Configure bridge \fBbr0\fR to participate in an 802.1D spanning tree:
.PP
Deconfigure STP from above:
.IP
-.B "ovs\-vsctl clear Bridge br0 stp_enable"
+.B "ovs\-vsctl set Bridge br0 stp_enable=false"
+.PP
+.SS "OpenFlow Version"
.PP
+Configure bridge \fBbr0\fR to support OpenFlow versions 1.0, 1.2, and
+1.3:
+.IP
+.B "ovs\-vsctl set bridge br0 protocols=openflow10,openflow12,openflow13"
+.
.SH "EXIT STATUS"
.IP "0"
Successful program execution.
.SH "SEE ALSO"
.
.BR ovsdb\-server (1),
-.BR ovs\-vswitchd (8).
+.BR ovs\-vswitchd (8),
+.BR ovs\-vswitchd.conf.db (5).
git://git.onelab.eu / sliver-openvswitch.git / blobdiff