. ns
. IP "\\$1"
..
+.de ST
+. PP
+. RS -0.15in
+. I "\\$1"
+. RE
+. PP
+..
.TH ovs\-vsctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual"
.ds PN ovs\-vsctl
.
\fBunix:@RUNDIR@/ovsdb\-server\fR. \fIserver\fR must take one of the
following forms:
.RS
-.IP "\fBtcp:\fIip\fB:\fIport\fR"
-Connect to the given TCP \fIport\fR on \fIip\fR.
-.IP "\fBunix:\fIfile\fR"
-Connect to the Unix domain server socket named \fIfile\fR.
+.so ovsdb/remote-active.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
.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.)
+.
+.so lib/ssl.man
.so lib/vlog.man
.
.SH COMMANDS
Creates on \fIbridge\fR a new port named \fIport\fR from the network
device of the same name.
.
-.IP "\fBadd\-bond \fIbridge port iface\fR\&..."
+.IP "[\fB\-\-fake\-iface\fR] \fBadd\-bond \fIbridge port iface\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
+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 "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIbridge\fR] \fIport\fR"
Deletes \fIport\fR. If \fIbridge\fR is omitted, \fIport\fR is removed
\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
+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.
+.
+.IP "\fBget\-controller\fR [\fIbridge\fR]"
+Prints the configured controller target.
+.
+.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:
+.
+.RS
+.so lib/vconn-active.man
+.RE
+.
+.ST "Controller Failure Settings"
+.
+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
+the connection to the controller stays down long enough, no packets
+can pass through the switch at all.
+.PP
+If the value is \fBstandalone\fR, or if neither of these settings
+is set, \fBovs\-vswitchd\fR will take over
+responsibility for setting up
+flows when no message has been received from the controller for three
+times the inactivity probe interval (xxx needs to be exposed). In this mode,
+\fBovs\-vswitchd\fR causes the datapath to act like an ordinary
+MAC-learning switch. \fBovs\-vswitchd\fR will continue to retry connecting
+to the controller in the background and, when the connection succeeds,
+it discontinues its standalone behavior.
+.PP
+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]"
+Prints the configured failure mode.
+.
+.IP "\fBdel\-fail\-mode\fR [\fIbridge\fR]"
+Deletes the configured failure mode.
+.
+.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
+Specifies a PEM file containing the private key used as the virtual
+switch's identity for SSL connections to the controller.
+.TP
+\fBcertificate\fR
+Specifies a PEM file containing a certificate, signed by the
+certificate authority (CA) used by the controller and manager, that
+certifies the virtual switch's private key, identifying a trustworthy
+switch.
+.TP
+\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
+These files are read only once, at \fBovs\-vswitchd\fR startup time. If
+their contents change, \fBovs\-vswitchd\fR must be killed and restarted.
+.PP
+These SSL settings apply to all SSL connections made by the virtual
+switch.
+.
+.IP "\fBget\-ssl\fR"
+Prints the SSL configuration.
+.
+.IP "\fBdel\-ssl\fR"
+Deletes the current SSL configuration.
+.
+.IP "[\fB\-\-bootstrap\fR] \fBset\-ssl\fR \fIprivate-key\fR \fIcertificate\fR \fIca-cert\fR"
+Sets the SSL configuration. The \fB\-\-bootstrap\fR option is described
+below.
+.
+.ST "CA Certificate Bootstrap"
+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
+CA certificate from the controller 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.
+.PP
+\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.
+.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
+\fBcontroller\fR(8) can be configured to do so with the
+\fB--peer-ca-cert\fR option.
+.
+.SS "Database Commands"
+.
+These commands query and modify the contents of \fBovsdb\fR tables.
+They are a slight abstraction of the \fBovsdb\fR interface and as such
+they operate at a lower level than other \fBovs\-vsctl\fR commands.
+.PP
+.ST "Identifying Tables, Records, and Columns"
+.PP
+Each of these commands has a \fItable\fR parameter to identify a table
+within the database. Many of them also take a \fIrecord\fR parameter
+that identifies a particular record within a table. The \fIrecord\fR
+parameter may be the UUID for a record, and many tables offer
+additional ways to identify records. Some commands also take
+\fIcolumn\fR parameters that identify a particular field within the
+records in a table.
+.PP
+The following tables are currently defined:
+.IP "\fBOpen_vSwitch\fR"
+Global configuration for an \fBovs\-vswitchd\fR. This table contains
+exactly one record, identified by specifying \fB.\fR as the record
+name.
+.IP "\fBBridge\fR"
+Configuration for a bridge within an Open vSwitch. Records may be
+identified by bridge name.
+.IP "\fBPort\fR"
+A bridge port. Records may be identified by port name.
+.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 "\fBNetFlow\fR"
+A NetFlow 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
+to identify the \fBNetFlow\fR table.
+.
+.ST "Database Values"
+Each column in the database accepts a fixed type of data. The
+currently defined basic types, and their representations, are:
+.IP "integer"
+A decimal integer in the range \-2**63 to 2**63\-1, inclusive.
+.IP "real"
+A floating-point number.
+.IP "Boolean"
+True or false, written \fBtrue\fR or \fBfalse\fR, respectively.
+.IP "string"
+An arbitrary Unicode string, except that null bytes are not allowed.
+Quotes are optional for most strings that begin with an English letter
+or underscore and consist only of letters, underscores, hyphens, and
+periods. However, \fBtrue\fR and \fBfalse\fR and strings that match
+the syntax of UUIDs (see below) must be enclosed in double quotes to
+distinguish them from other basic types. When double quotes are used,
+the syntax is that of strings in JSON, e.g. backslashes may be used to
+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.
+.PP
+Multiple values in a single column may be separated by spaces or a
+single comma. When multiple values are present, duplicates are not
+allowed, and order is not important. Conversely, some database
+columns can have an empty set of values, represented as \fB[]\fR, and
+square brackets may optionally enclose other non-empty sets or single
+values as well.
+.PP
+A few database columns are ``maps'' of key-value pairs, where the key
+and the value are each some fixed database type. These are specified
+in the form \fIkey\fB=\fIvalue\fR, where \fIkey\fR and \fIvalue\fR
+follow the syntax for the column's key type and value type,
+respectively. When multiple pairs are present (separated by spaces or
+a comma), duplicate keys are not allowed, and again the order is not
+important. Duplicate values are allowed. An empty map is represented
+as \fB{}\fR, and curly braces may be optionally enclose non-empty maps
+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.
+.
+.IP "\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 "[\fB\-\-force\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 "[\fB\-\-force\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 "[\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..."
+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.
+The second and third forms apply to map columns: if only a \fIkey\fR
+is specified, then any key-value pair with the given \fIkey\fR is
+removed, regardless of its value; if a \fIvalue\fR is given then a
+pair is removed only if both key and value match.
+.IP
+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..."
+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.
+.
.SH "EXAMPLES"
Create a new bridge named br0 and add port eth0 to it:
.IP
git://git.onelab.eu / sliver-openvswitch.git / blobdiff