X-Git-Url: http://git.cascardo.eti.br/?a=blobdiff_plain;f=utilities%2Fovs-vsctl.8.in;h=265ffde38d8ecb2afed38a221d9cc736ff0eea33;hb=68dfc25b62e5edc2939bcae791a35fddfecb5d20;hp=6c362c3def6067d2f3028f6fcb2b2885e46f3a9a;hpb=8936565369410daa099708be4cd3fa7e0e39bade;p=cascardo%2Fovs.git diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index 6c362c3de..265ffde38 100644 --- a/utilities/ovs-vsctl.8.in +++ b/utilities/ovs-vsctl.8.in @@ -10,7 +10,8 @@ . 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 . .SH NAME @@ -22,19 +23,17 @@ 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. @@ -42,9 +41,9 @@ 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. @@ -66,7 +65,8 @@ When such a ``fake bridge'' is active, \fBovs\-vsctl\fR will treat it 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 . @@ -79,17 +79,18 @@ the global options by \fB\-\-\fR. .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 +reconfigure itself according to 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 @@ -100,7 +101,7 @@ By default, \fBovs\-vsctl\fR logs its arguments and the details of any changes that it makes to the system log. This option disables this logging. .IP -This option is equivalent to \fB\-\-verbose=vvsctl:syslog:warn\fR. +This option is equivalent to \fB\-\-verbose=vsctl:syslog:warn\fR. . .IP "\fB\-\-oneline\fR" Modifies the output format so that the output for each command is printed @@ -108,20 +109,47 @@ on a single line. New-line characters that would otherwise separate lines are printed as \fB\\n\fR, and any instances of \fB\\\fR that would otherwise appear in the output are doubled. Prints a blank line for each command that has no output. +This option does not affect the formatting of output from the +\fBlist\fR or \fBfind\fR commands; see \fBTable Formatting Options\fR +below. . .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.) +. +.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/table.man . +.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 +.so lib/common.man . .SH COMMANDS The commands implemented by \fBovs\-vsctl\fR are described in the @@ -137,6 +165,18 @@ Any successful \fBovs\-vsctl\fR command automatically initializes the Open vSwitch database if it is empty. This command is provided to initialize the database without executing any other command. . +.IP "\fBshow\fR" +Prints a brief overview of the database contents. +. +.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, 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. . @@ -145,20 +185,21 @@ 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). +exists is an error. With \fB\-\-may\-exist\fR, this command does +nothing if \fIbridge\fR already exists as a real bridge. . .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 +\fIvlan\fR, which must be an integer between 0 and 4095. The parent +bridge must not already have a fake bridge for \fIvlan\fR. 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). +exists is an error. With \fB\-\-may\-exist\fR, this command does +nothing if \fIbridge\fR already exists as a VLAN bridge under +\fIparent\fR for \fIvlan\fR. . .IP "[\fB\-\-if\-exists\fR] \fBdel\-br \fIbridge\fR" Deletes \fIbridge\fR and all of its ports. If \fIbridge\fR is a real @@ -169,9 +210,10 @@ Without \fB\-\-if\-exists\fR, attempting to delete a bridge that does 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, @@ -224,27 +266,38 @@ commands treat a bonded port as a single entity. 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 "[\fB\-\-may\-exist\fR] \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). +is an error. With \fB\-\-may\-exist\fR, this command does nothing if +\fIport\fR already exists on \fIbridge\fR and is not 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. +interfaces must be named. If the interfaces are DPDK enabled then +the transaction will need to include operations to explicitly set the +interface type to 'dpdk'. +.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). +is an error. With \fB\-\-may\-exist\fR, this command does nothing if +\fIport\fR already exists on \fIbridge\fR and bonds together exactly +the specified interfaces. . .IP "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIbridge\fR] \fIport\fR" Deletes \fIport\fR. If \fIbridge\fR is omitted, \fIport\fR is removed @@ -288,26 +341,27 @@ 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. -. -.IP "\fBget\-controller\fR [\fIbridge\fR]" +locally, or it can be configured to communicate with one or more +external OpenFlow controllers. The switch is typically configured to +connect to a primary controller that takes charge of the bridge's flow +table to implement a network policy. In addition, the switch can be +configured to listen to connections from service controllers. Service +controllers are typically used for occasional support and maintenance, +e.g. with \fBovs\-ofctl\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 +.so lib/vconn-passive.man .RE . .ST "Controller Failure Settings" @@ -322,7 +376,7 @@ 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, +times the inactivity probe interval. 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, @@ -331,30 +385,54 @@ it discontinues its standalone behavior. 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 "Manager Connectivity" +. +These commands manipulate the \fBmanager_options\fR column in the +\fBOpen_vSwitch\fR table and rows in the \fBManagers\fR table. When +\fBovsdb\-server\fR is configured to use the \fBmanager_options\fR column for +OVSDB connections (as described in \fBINSTALL.Linux\fR and in the startup +scripts provided with Open vSwitch), this allows the administrator to use +\fBovs\-vsctl\fR to configure database connections. +. +.IP "\fBget\-manager\fR" +Prints the configured manager(s). +. +.IP "\fBdel\-manager\fR" +Deletes the configured manager(s). +. +.IP "\fBset\-manager\fR \fItarget\fR\&..." +Sets the configured manager target or targets. Each \fItarget\fR may +use any of the following forms: +. +.RS +.so ovsdb/remote-active.man +.so ovsdb/remote-passive.man +.RE +. .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 +\fIprivate-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 +\fIcertificate\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 +\fIca-cert\fR Specifies a PEM file containing the CA certificate used to verify that the virtual switch is connected to a trustworthy controller. .PP @@ -371,13 +449,14 @@ Prints the SSL configuration. 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 +Sets the SSL configuration. The \fB\-\-bootstrap\fR option is described 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 +when \fBovs\-vswitchd\fR starts. However, if the \fIca-cert\fR file +does not exist and 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 @@ -391,9 +470,28 @@ 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. +require the controller to send the CA certificate. +. +.SS "Auto-Attach Commands" +. +The IETF Auto-Attach SPBM draft standard describes a compact method of using +IEEE 802.1AB Link Layer Discovery Protocol (LLDP) together with a IEEE 802.1aq +Shortest Path Bridging (SPB) network to automatically attach network devices to +individual services in a SPB network. The intent here is to allow network +applications and devices using OVS to be able to easily take advantage of +features offered by industry standard SPB networks. A fundamental element of +the Auto-Attach feature is to map traditional VLANs onto SPB I_SIDs. These +commands manage the Auto-Attach I-SID/VLAN mappings. +. +.IP "\fBadd\-aa\-mapping \fIbridge i-sid vlan\fR" +Creates a new Auto-Attach mapping on \fIbridge\fR for \fIi-sid\fR +and \fIvlan\fR. +. +.IP "\fBdel\-aa\-mapping \fIbridge i-sid vlan\fR" +Deletes an Auto-Attach mapping on \fIbridge\fR for \fIi-sid\fR +and \fIvlan\fR. +.IP "\fBget\-aa\-mapping \fIbridge\fR" +Lists all of the Auto-Attach mappings within \fIbridge\fR on standard output. . .SS "Database Commands" . @@ -424,144 +522,362 @@ 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 "\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. +.IP "\fBQueue\fR" +Configuration for one queue within a \fBQoS\fR configuration. Records +may only be identified by UUID. .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 "\fBManager\fR" +Configuration for an OVSDB connection. Records may be identified +by target (e.g. \fBtcp:1.2.3.4\fR). .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 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. +.IP "\fBAutoAttach\fR" +Configuration for Auto Attach within a bridge. .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" -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" -.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 "[\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 -\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 "\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 "\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. -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 "\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. +.so lib/db-ctl-base.man .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" +.IP +.B "ovs\-vsctl add\-br br0 \-\- add\-port br0 eth0" .PP Delete bridge \fBbr0\fR, reporting an error if it does not exist: .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" +.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 "CONFIGURATION COOKBOOK" +.SS "Port Configuration" +.PP +Add an ``internal port'' \fBvlan10\fR to bridge \fBbr0\fR as a VLAN +access port for VLAN 10, and configure it with an IP address: +.IP +.B "ovs\-vsctl add\-port br0 vlan10 tag=10 \-\- set Interface vlan10 type=internal" +.IP +.B "ifconfig vlan10 192.168.0.123" +. +.PP +Add a GRE tunnel port \fBgre0\fR to remote IP address 1.2.3.4 to +bridge \fBbr0\fR: +.IP +.B "ovs\-vsctl add\-port br0 gre0 \-\- set Interface gre0 type=gre options:remote_ip=1.2.3.4" +. +.SS "Port Mirroring" +.PP +Mirror all packets received or sent on \fBeth0\fR or \fBeth1\fR onto +\fBeth2\fR, assuming that all of those ports exist on bridge \fBbr0\fR +(as a side-effect this causes any packets received on \fBeth2\fR to be +ignored): +.IP +.B "ovs\-vsctl \-\- set Bridge br0 mirrors=@m \(rs" +.IP +.B "\-\- \-\-id=@eth0 get Port eth0 \(rs" +.IP +.B "\-\- \-\-id=@eth1 get Port eth1 \(rs" +.IP +.B "\-\- \-\-id=@eth2 get Port eth2 \(rs" +.IP +.B "\-\- \-\-id=@m create Mirror name=mymirror select-dst-port=@eth0,@eth1 select-src-port=@eth0,@eth1 output-port=@eth2" +.PP +Remove the mirror created above from \fBbr0\fR, which also destroys +the Mirror record (since it is now unreferenced): +.IP +.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 +use it on \fBeth0\fR and \fBeth1\fR: +.IP +.B "ovs\-vsctl \-\- set Port eth0 qos=@newqos \(rs" +.IP +.B "\-\- set Port eth1 qos=@newqos \(rs" +.IP +.B "\-\- \-\-id=@newqos create QoS type=linux\-htb other\-config:max\-rate=1000000000 queues=0=@q0,1=@q1 \(rs" +.IP +.B "\-\- \-\-id=@q0 create Queue other\-config:min\-rate=100000000 other\-config:max\-rate=100000000 \(rs" +.IP +.B "\-\- \-\-id=@q1 create Queue other\-config:min\-rate=500000000" +.PP +Deconfigure the QoS record above from \fBeth1\fR only: +.IP +.B "ovs\-vsctl clear Port eth1 qos" +.PP +To deconfigure the QoS record from both \fBeth0\fR and \fBeth1\fR and +then delete the QoS record (which must be done explicitly because +unreferenced QoS records are not automatically destroyed): +.IP +.B "ovs\-vsctl \-\- destroy QoS eth0 \-\- clear Port eth0 qos \-\- clear Port eth1 qos" +.PP +(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 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. +.IP +.B "ovs\-vsctl set Interface eth0 cfm_mpid=1" +.PP +Deconfigure connectivity monitoring from above: +.IP +.B "ovs\-vsctl clear Interface eth0 cfm_mpid" +.SS "NetFlow" +.PP +Configure bridge \fBbr0\fR to send NetFlow records to UDP port 5566 on +host 192.168.0.34, with an active timeout of 30 seconds: +.IP +.B "ovs\-vsctl \-\- set Bridge br0 netflow=@nf \(rs" +.IP +.B "\-\- \-\-id=@nf create NetFlow targets=\(rs\(dq192.168.0.34:5566\(rs\(dq active\-timeout=30" +.PP +Update the NetFlow configuration created by the previous command to +instead use an active timeout of 60 seconds: +.IP +.B "ovs\-vsctl set NetFlow br0 active_timeout=60" +.PP +Deconfigure the NetFlow settings from \fBbr0\fR, which also destroys +the NetFlow record (since it is now unreferenced): +.IP +.B "ovs\-vsctl clear Bridge br0 netflow" +.SS "sFlow" +.PP +Configure bridge \fBbr0\fR to send sFlow records to a collector on +10.0.0.1 at port 6343, using \fBeth1\fR\'s IP address as the source, +with specific sampling parameters: +.IP +.B "ovs\-vsctl \-\- \-\-id=@s create sFlow agent=eth1 target=\(rs\(dq10.0.0.1:6343\(rs\(dq header=128 sampling=64 polling=10 \(rs" +.IP +.B "\-\- set Bridge br0 sflow=@s" +.PP +Deconfigure sFlow from \fBbr0\fR, which also destroys the sFlow record +(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), maximum flow cache size of 13 flows, and flows +sampled on output port with tunnel info(sampling on input and output +port is enabled by default if not disabled) : +.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 \(rs" +.IP +.B "other_config:enable-input-sampling=false other_config:enable-tunnel-sampling=true" +.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: +.IP +.B "ovs\-vsctl set Bridge br0 stp_enable=true" +.PP +Set the bridge priority of \fBbr0\fR to 0x7800: +.IP +.B "ovs\-vsctl set Bridge br0 other_config:stp-priority=0x7800" +.PP +Set the path cost of port \fBeth0\fR to 10: +.IP +.B "ovs\-vsctl set Port eth0 other_config:stp-path-cost=10" +.PP +Deconfigure STP from above: +.IP +.B "ovs\-vsctl set Bridge br0 stp_enable=false" +.PP +.SS "Multicast Snooping" +.PP +Configure bridge \fBbr0\fR to enable multicast snooping: +.IP +.B "ovs\-vsctl set Bridge br0 mcast_snooping_enable=true" +.PP +Set the multicast snooping aging time \fBbr0\fR to 300 seconds: +.IP +.B "ovs\-vsctl set Bridge br0 other_config:mcast-snooping-aging-time=300" +.PP +Set the multicast snooping table size \fBbr0\fR to 2048 entries: +.IP +.B "ovs\-vsctl set Bridge br0 other_config:mcast-snooping-table-size=2048" +.PP +Disable flooding of unregistered multicast packets to all ports. When +set to \fBtrue\fR, the switch will send unregistered multicast packets only +to ports connected to multicast routers. When it is set to \fBfalse\fR, the +switch will send them to all ports. This command disables the flood of +unregistered packets on bridge \fBbr0\fR. +.IP +.B "ovs\-vsctl set Bridge br0 other_config:mcast-snooping-disable-flood-unregistered=true" +.PP +Enable flooding of multicast packets (except Reports) on a specific port. +.IP +.B "ovs\-vsctl set Port eth1 other_config:mcast-snooping-flood=true" +.PP +Enable flooding of Reports on a specific port. +.IP +.B "ovs\-vsctl set Port eth1 other_config:mcast-snooping-flood-reports=true" +.PP +Deconfigure multicasting snooping from above: +.IP +.B "ovs\-vsctl set Bridge br0 mcast_snooping_enable=false" +.PP +.SS "802.1D-2004 Rapid Spanning Tree Protocol (RSTP)" +.PP +Configure bridge \fBbr0\fR to participate in an 802.1D-2004 Rapid Spanning Tree: +.IP +.B "ovs\-vsctl set Bridge br0 rstp_enable=true" +.PP +Set the bridge address of \fBbr0\fR to 00:aa:aa:aa:aa:aa : .IP -.B "ovs\-vsctl \-\- \-\-if\-exists del\-br br0" +.B "ovs\-vsctl set Bridge br0 other_config:rstp-address=00:aa:aa:aa:aa:aa" +.PP +Set the bridge priority of \fBbr0\fR to 0x7000. The value must be specified in +decimal notation and should be a multiple of 4096 (if not, it is rounded down to +the nearest multiple of 4096). The default priority value is 0x800 (32768). +.IP +.B "ovs\-vsctl set Bridge br0 other_config:rstp-priority=28672" +.PP +Set the bridge ageing time of \fBbr0\fR to 1000 s. The ageing time value should be +between 10 s and 1000000 s. The default value is 300 s. +.IP +.B "ovs\-vsctl set Bridge br0 other_config:rstp-ageing-time=1000" +.PP +Set the bridge force protocol version of \fBbr0\fR to 0. The force protocol version +has two acceptable values: 0 (STP compatibility mode) and 2 (normal operation). +.IP +.B "ovs\-vsctl set Bridge br0 other_config:rstp-force-protocol-version=0" +.PP +Set the bridge max age of \fBbr0\fR to 10 s. The max age value should be between 6 s +and 40 s. The default value is 20 s. +.IP +.B "ovs\-vsctl set Bridge br0 other_config:rstp-max-age=10" +.PP +Set the bridge forward delay of \fBbr0\fR to 15 s. +This value should be between 4 s and 30 s. The default value is 15 s. +.IP +.B "ovs\-vsctl set Bridge br0 other_config:rstp-forward-delay=15" +.PP +Set the bridge transmit hold count of \fBbr0\fR to 7 s. This value should be between +1 s and 10 s. The default value is 6 s. +.IP +.B "ovs\-vsctl set Bridge br0 other_config:rstp-transmit-hold-count=7" +.PP +Enable RSTP on the Port \fBeth0\fR: +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-enable=true" +.PP +Disable RSTP on the Port \fBeth0\fR: +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-enable=false" +.PP +Set the priority of port \fBeth0\fR to 32. The value must be specified in +decimal notation and should be a multiple of 16 (if not, it is rounded down to the +nearest multiple of 16). The default priority value is 0x80 (128). +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-port-priority=32" +.PP +Set the port number of port \fBeth0\fR to 3: +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-port-num=3" +.PP +Set the path cost of port \fBeth0\fR to 150: +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-path-cost=150" +.PP +Set the admin edge value of port \fBeth0\fR: +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-port-admin-edge=true" +.PP +Set the auto edge value of port \fBeth0\fR: +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-port-auto-edge=true" +.PP +Set the admin point to point MAC value of port \fBeth0\fR. Acceptable +values are \fB0\fR (not point-to-point), \fB1\fR (point-to-point, the +default value) or \fB2\fR (automatic detection). The auto-detection +mode is not currently implemented, and the value \fB2\fR has the same +effect of \fB0\fR (not point-to-point). +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-admin-p2p-mac=1" +.PP +Set the admin port state value of port \fBeth0\fR. \fBtrue\fR is the +default value. +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-admin-port-state=false" +.PP +Set the mcheck value of port \fBeth0\fR: +.IP +.B "ovs\-vsctl set Port eth0 other_config:rstp-port-mcheck=true" +.PP +Deconfigure RSTP from above: +.IP +.B "ovs\-vsctl set Bridge br0 rstp_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" . +.SS "Flow Table Configuration" +Limit flow table 0 on bridge br0 to a maximum of 100 flows: +.IP +.B "ovs\-vsctl \-\- \-\-id=@ft create Flow_Table flow_limit=100 overflow_policy=refuse \-\- set Bridge br0 flow_tables=0=@ft" .SH "EXIT STATUS" .IP "0" Successful program execution. @@ -573,4 +889,5 @@ bridge that does not exist. .SH "SEE ALSO" . .BR ovsdb\-server (1), -.BR ovs\-vswitchd (8). +.BR ovs\-vswitchd (8), +.BR ovs\-vswitchd.conf.db (5).