X-Git-Url: http://git.cascardo.eti.br/?a=blobdiff_plain;f=utilities%2Fovs-vsctl.8.in;h=972fc26375462b6544cfb1f7db3cac9fc3c6fdc7;hb=2bb0bea82711750311974c291e98bec6fc0e077f;hp=1702aacca5cfaad3020b4db5d3301b68a149552d;hpb=ae9a3235bfa607fdcccd5e12d2052252e67fb914;p=cascardo%2Fovs.git diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index 1702aacca..972fc2637 100644 --- a/utilities/ovs-vsctl.8.in +++ b/utilities/ovs-vsctl.8.in @@ -10,11 +10,9 @@ . 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 @@ -25,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. @@ -45,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. @@ -69,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 . @@ -128,6 +125,20 @@ to approximately \fIsecs\fR seconds. If the timeout expires, 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. @@ -138,6 +149,7 @@ These options control the format of output from the \fBlist\fR and .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 @@ -153,13 +165,17 @@ 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, 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. @@ -169,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 @@ -193,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, @@ -258,13 +276,15 @@ 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\&... [\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 @@ -275,9 +295,9 @@ 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 @@ -321,8 +341,13 @@ 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 one or -more external OpenFlow controllers, such as NOX. +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. @@ -336,6 +361,7 @@ use any of the following forms: . .RS .so lib/vconn-active.man +.so lib/vconn-passive.man .RE . .ST "Controller Failure Settings" @@ -350,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, @@ -370,11 +396,11 @@ Sets the configured failure mode. . .SS "Manager Connectivity" . -These commands manipulate the \fBmanagers\fR and \fBmanager_options\fR columns -in the \fBOpen_vSwitch\fR table and rows in the \fBManagers\fR table. When -\fBovsdb\-server\fR is configured to use those rows and columns for OVSDB -connections, as described in \fBINSTALL.Linux\fR and in the startup scripts -provided with Open vSwitch, this allows the administrator to use +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" @@ -423,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 @@ -443,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 -\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 "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" . @@ -476,6 +522,15 @@ 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 "\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. @@ -493,13 +548,16 @@ 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 +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 "\fBMonitor\fR" -Connectivity Monitoring attached to an interface. Records may be -identified by interface name. -.IP "\fBMaintenance_Point\fR" -Maintenance Point managed by a Monitor. +.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 Record names must be specified in full and with correct capitalization. Names of tables and columns are not case-sensitive, @@ -507,162 +565,7 @@ 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" -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 a \fBget\fR or \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 -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 "[\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 "[\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 -\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 \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 -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]]..." -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 -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 -invocation in contexts where a UUID is expected. -. -.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 "[\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 -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 "\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 -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. +.so lib/db-ctl-base.man .SH "EXAMPLES" Create a new bridge named br0 and add port eth0 to it: .IP @@ -671,17 +574,16 @@ Create a new bridge named br0 and add port eth0 to it: .B "ovs\-vsctl add\-port br0 eth0" .PP Alternatively, perform both operations in a single atomic transaction: -.IP +.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" +.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 @@ -698,6 +600,12 @@ access port for VLAN 10, and configure it with an IP address: .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 @@ -715,10 +623,16 @@ ignored): .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 and destroy the Mirror -record (to avoid having an unreferenced record in the database): +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 destroy Mirror mymirror \-\- clear Bridge br0 mirrors" +.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 @@ -739,29 +653,25 @@ Deconfigure the QoS record above from \fBeth1\fR only: .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: +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.) +\fIuuid2\fR" to destroy each of them or use +"\fBovs\-vsctl -- --all destroy Queue\fR" to delete all records.) .SS "Connectivity Monitoring" .PP -Create a Monitor which manages a couple of remote Maintenance Points on eth0. -.IP -.B "ovs\-vsctl \-\- set Interface eth0 Monitor=@newmon \(rs" -.IP -.B "\-\- \-\-id=@newmon create Monitor mpid=1 remote_mps=@mp2,@mp3 \(rs" +Monitor connectivity to a remote maintenance point on eth0. .IP -.B "\-\- \-\-id=@mp2 create Maintenance_Point mpid=2 \(rs" -.IP -.B "\-\- \-\-id=@mp3 create Maintenance_Point mpid=3" +.B "ovs\-vsctl set Interface eth0 cfm_mpid=1" .PP -Deconfigure the Monitor record from above: +Deconfigure connectivity monitoring from above: .IP -.B "ovs\-vsctl clear Interface eth0 Monitor" +.B "ovs\-vsctl clear Interface eth0 cfm_mpid" .SS "NetFlow" .PP Configure bridge \fBbr0\fR to send NetFlow records to UDP port 5566 on @@ -776,10 +686,10 @@ 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 and delete the NetFlow -record (to avoid having an unreferenced record in the database): +Deconfigure the NetFlow settings from \fBbr0\fR, which also destroys +the NetFlow record (since it is now unreferenced): .IP -.B "ovs\-vsctl destroy NetFlow br0 \-\- clear Bridge br0 netflow" +.B "ovs\-vsctl clear Bridge br0 netflow" .SS "sFlow" .PP Configure bridge \fBbr0\fR to send sFlow records to a collector on @@ -790,10 +700,184 @@ with specific sampling parameters: .IP .B "\-\- set Bridge br0 sflow=@s" .PP -Deconfigure sFlow from br0 and destroy the sFlow record (to avoid -having an unreferenced record in the database): +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 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 \-\- destroy sFlow br0 \-\- clear Bridge br0 sflow" +.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. @@ -805,5 +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).