X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-vsctl.8.in;h=16fd8497438957539dba1688dfc54e3e15832270;hb=5aa006354872e40c227b601f0e0deb4fd72eb9f6;hp=2eea7fdb0e4526752ca140d7545011e89a7d1531;hpb=3fbe1d307e27ed99528d83cf866c7df497e58b77;p=sliver-openvswitch.git diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index 2eea7fdb0..16fd84974 100644 --- a/utilities/ovs-vsctl.8.in +++ b/utilities/ovs-vsctl.8.in @@ -4,6 +4,13 @@ . 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 . @@ -11,24 +18,28 @@ ovs\-vsctl \- utility for querying and configuring \fBovs\-vswitchd\fR . .SH SYNOPSIS -\fBovs\-vsctl\fR [\fIoptions\fR] \fIcommand \fR[\fIargs\fR\&...] +\fBovs\-vsctl\fR [\fIoptions\fR] [\fB\-\-\fR] \fIcommand \fR[\fIargs\fR\&...] [\fB\-\-\fR \fIcommand \fR[\fIargs\fR\&...]] . .SH DESCRIPTION -The \fBovs\-vsctl\fR program configures \fBovs\-vswitchd\fR(8), mainly -by providing a high\-level interface to editing its configuration file -\fBovs\-vswitchd.conf\fR(5). This program is mainly intended for use -when \fBovs\-vswitchd\fR is running, but it can also be used when -\fBovs\-vswitchd\fR is not running. In the latter case configuration -changes will only take effect when \fBovs\-vswitchd\fR is started. +The \fBovs\-vsctl\fR program configures \fBovs\-vswitchd\fR(8) by +providing a high\-level interface to editing 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. .PP -By default, each time \fBovs\-vsctl\fR runs, it examines and, -depending on the requested command or commands, possibly applies -changes to an -\fBovs\-vswitchd.conf\fR file. Then, if it applied any changes and if -\fBovs\-vswitchd\fR is running, it tells \fBovs\-vswitchd\fR to reload -the modified configuration file and waits for the reload to complete -before exiting. +\fBovs\-vsctl\fR can perform any number of commands in a single run, +implemented as a single atomic transaction against the database. +Commands are separated on the command line by \fB\-\-\fR arguments. . .SS "Linux VLAN Bridging Compatibility" The \fBovs\-vsctl\fR program supports the model of a bridge @@ -51,49 +62,40 @@ they are members. . .SH OPTIONS . -The following options affect the general outline of \fBovs\-vsctl\fR's -activities: +The following options affect the behavior \fBovs\-vsctl\fR as a whole. +Some individual commands also accept their own options, which are +given just before the command name. If the first command on the +command line has options, then those options must be separated from +the global options by \fB\-\-\fR. . -.IP "\fB\-c \fIfile\fR" -.IQ "\fB\-\-config=\fIfile\fR" -Sets the configuration file that \fBovs\-vsctl\fR reads and possibly -modifies. The default is \fB@localstatedir@/ovs\-vswitchd.conf\fR. -.IP -If \fIfile\fR is specified as \fB\-\fR, then \fBovs\-vsctl\fR reads -the configuration file from standard input and, for commands that -modify the configuration, writes the new one to standard output. This -is useful for testing but it should not be used in production because -it bypasses the Open vSwitch configuration file locking protocol. -. -.IP "\fB\-t \fItarget\fR" -.IQ "\fB\-\-target=\fItarget\fR" -Configures how \fBovs\-vsctl\fR contacts \fBovs\-vswitchd\fR to -instruct it to reload its configuration file. -.IP -If \fItarget\fR begins with \fB/\fR it must name a Unix domain socket -on which \fBovs\-vswitchd\fR is listening for control channel -connections. By default, \fBovs\-vswitchd\fR listens on a Unix domain -socket named \fB@RUNDIR@/ovs\-vswitchd.\fIpid\fB.ctl\fR, where -\fIpid\fR is \fBovs\-vswitchd\fR's process ID. -.IP -Otherwise, \fBovs\-appctl\fR looks for a pidfile, that is, a file -whose contents are the process ID of a running process as a decimal -number, named \fB@RUNDIR@/\fItarget\fB.pid\fR. (The \fB\-\-pidfile\fR -option makes an Open vSwitch daemon create a pidfile.) -\fBovs\-appctl\fR reads the pidfile, then looks for a Unix socket -named \fB@RUNDIR@/\fItarget\fB.\fIpid\fB.ctl\fR, where \fIpid\fR is -replaced by the process ID read from \fItarget\fR, and uses that file -as if it had been specified directly as the target. +.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 +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. +.RE +.IP "\fB\-\-no\-wait\fR" +Prevents \fBovs\-vsctl\fR from waiting for \fBovs\-vswitchd\fR to +reconfigure itself according to the the modified database. This +option should be used if \fBovs\-vswitchd\fR is not running; +otherwise, \fBovs-vsctl\fR will not exit until \fBovs-vswitchd\fR +starts. .IP -The default target is \fBovs\-vswitchd\fR. -.IP "\fB\-\-no\-reload\fR" -Prevents \fBovs\-vsctl\fR from telling \fBovs\-vswitchd\fR to reload -its configuration file. +This option has no effect if the commands specified do not change the +database. . .IP "\fB\-\-no\-syslog\fR" 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. +. .IP "\fB\-\-oneline\fR" Modifies the output format so that the output for each command is printed on a single line. New-line characters that would otherwise separate @@ -101,9 +103,32 @@ 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. . +.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/vlog.man +. .SH COMMANDS The commands implemented by \fBovs\-vsctl\fR are described in the sections below. +.SS "Open vSwitch Commands" +These commands work with an Open vSwitch as a whole. +. +.IP "\fBinit\fR" +Initializes the Open vSwitch database, if it is empty. If the +database has already been initialized, this command has no effect. +.IP +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. . .SS "Bridge Commands" These commands examine and manipulate Open vSwitch bridges. @@ -119,10 +144,14 @@ itself be a fake bridge. The new fake bridge will be on 802.1Q VLAN \fIvlan\fR, which must be an integer between 1 and 4095. Initially \fIbridge\fR will have no ports (other than \fIbridge\fR itself). . -.IP "\fBdel\-br \fIbridge\fR" +.IP "[\fB\-\-if\-exists\fR] \fBdel\-br \fIbridge\fR" Deletes \fIbridge\fR and all of its ports. If \fIbridge\fR is a real bridge, this command also deletes any fake bridges that were created with \fIbridge\fR as parent, including all of their ports. +.IP +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" Lists all existing real and fake bridges on standard output, one per @@ -141,6 +170,25 @@ decimal integer. If \fIbridge\fR is a real bridge, prints 0. If \fIbridge\fR is a fake bridge, prints the name of its parent bridge. If \fIbridge\fR is a real bridge, print \fIbridge\fR. . +.IP "\fBbr\-set\-external\-id \fIbridge key\fR [\fIvalue\fR]" +Sets or clears an ``external ID'' value on \fIbridge\fR. These values +are intended to identify entities external to Open vSwitch with which +\fIbridge\fR is associated, e.g. the bridge's identifier in a +virtualization management platform. The Open vSwitch database schema +specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR +are otherwise arbitrary strings. +.IP +If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for +\fIbridge\fR, overwriting any previous value. If \fIvalue\fR is +omitted, then \fIkey\fR is removed from \fIbridge\fR's set of external +IDs (if it was present). +. +.IP "\fBbr\-get\-external\-id \fIbridge\fR [\fIkey\fR]" +Queries the external IDs on \fIbridge\fR. If \fIkey\fR is specified, +the output is the value for that \fIkey\fR or the empty string if +\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 "Port Commands" . These commands examine and manipulate Open vSwitch ports. These @@ -159,15 +207,38 @@ 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 "\fBdel\-port \fR[\fIbridge\fR] \fIport\fR" +.IP "[\fB\-\-if\-exists\fR] \fBdel\-port \fR[\fIbridge\fR] \fIport\fR" Deletes \fIport\fR. If \fIbridge\fR is omitted, \fIport\fR is removed from whatever bridge contains it; if \fIbridge\fR is specified, it must be the real or fake bridge that contains \fIport\fR. +.IP +Without \fB\-\-if\-exists\fR, attempting to delete a port that does +not exist is an error. With \fB\-\-if\-exists\fR, attempting to +delete a port that does not exist has no effect. . .IP "\fBport\-to\-br \fIport\fR" Prints the name of the bridge that contains \fIport\fR on standard output. . +.IP "\fBport\-set\-external\-id \fIport key\fR [\fIvalue\fR]" +Sets or clears an ``external ID'' value on \fIport\fR. These value +are intended to identify entities external to Open vSwitch with which +\fIport\fR is associated, e.g. the port's identifier in a +virtualization management platform. The Open vSwitch database schema +specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR +are otherwise arbitrary strings. +.IP +If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for +\fIport\fR, overwriting any previous value. If \fIvalue\fR is +omitted, then \fIkey\fR is removed from \fIport\fR's set of external +IDs (if it was present). +. +.IP "\fBbr\-get\-external\-id \fIport\fR [\fIkey\fR]" +Queries the external IDs on \fIport\fR. If \fIkey\fR is specified, +the output is the value for that \fIkey\fR or the empty string if +\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 "Interface Commands" . These commands examine the interfaces attached to an Open vSwitch @@ -182,6 +253,93 @@ list. .IP "\fBiface\-to\-br \fIiface\fR" Prints the name of the bridge that contains \fIiface\fR on standard output. +. +.IP "\fBiface\-set\-external\-id \fIiface key\fR [\fIvalue\fR]" +Sets or clears an ``external ID'' value on \fIiface\fR. These value +are intended to identify entities external to Open vSwitch with which +\fIiface\fR is associated, e.g. the interface's identifier in a +virtualization management platform. The Open vSwitch database schema +specifies well-known \fIkey\fR values, but \fIkey\fR and \fIvalue\fR +are otherwise arbitrary strings. +.IP +If \fIvalue\fR is specified, then \fIkey\fR is set to \fIvalue\fR for +\fIiface\fR, overwriting any previous value. If \fIvalue\fR is +omitted, then \fIkey\fR is removed from \fIiface\fR's set of external +IDs (if it was present). +. +.IP "\fBbr\-get\-external\-id \fIiface\fR [\fIkey\fR]" +Queries the external IDs on \fIiface\fR. If \fIkey\fR is specified, +the output is the value for that \fIkey\fR or the empty string if +\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 +.TP +\fBssl:\fIip\fR[\fB:\fIport\fR] +The specified SSL \fIport\fR (default: 6633) on the host at the given +\fIip\fR, which must be expressed as an IP address (not a DNS name). +SSL must be configured when this form is used (see \fBSSL +Configuration\fR, below). +. +.TP +\fBtcp:\fIip\fR[\fB:\fIport\fR] +The specified TCP \fIport\fR (default: 6633) on the host at the given +\fIip\fR, which must be expressed as an IP address (not a DNS name). +.TP +\fBunix:\fIfile\fR +The Unix domain server socket named \fIfile\fR. +.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. +.ST +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. +.ST +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. +. .SH "EXAMPLES" Create a new bridge named br0 and add port eth0 to it: .IP @@ -192,6 +350,15 @@ Create a new bridge named br0 and add port eth0 to it: Alternatively, perform both operations in a single atomic transaction: .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): +.IP +.B "ovs\-vsctl \-\- \-\-if\-exists del\-br br0" . .SH "EXIT STATUS" .IP "0" @@ -203,5 +370,5 @@ The \fIbridge\fR argument to \fBbr\-exists\fR specified the name of a bridge that does not exist. .SH "SEE ALSO" . -.BR ovs\-vswitchd.conf (5), +.BR ovsdb\-server (1), .BR ovs\-vswitchd (8).