X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=utilities%2Fovs-vsctl.8.in;h=db0b9b91742f33536d20bcfd9a4808bb8823a6fb;hb=457e1eb040fa65fdefcf419e490340ec90b621e2;hp=7f6326e96e93545f492971ac014381cf65deea67;hpb=3f355f47f8e7343e909ccfa854454d667baf3c38;p=openvswitch diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index 7f6326e9..db0b9b91 100644 --- a/utilities/ovs-vsctl.8.in +++ b/utilities/ovs-vsctl.8.in @@ -4,7 +4,7 @@ . ns . IP "\\$1" .. -.TH ovs\-vsctl 8 "September 2009" "Open vSwitch" "Open vSwitch Manual" +.TH ovs\-vsctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual" .ds PN ovs\-vsctl . .SH NAME @@ -15,20 +15,20 @@ ovs\-vsctl \- utility for querying and configuring \fBovs\-vswitchd\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 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. +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. . .SS "Linux VLAN Bridging Compatibility" The \fBovs\-vsctl\fR program supports the model of a bridge @@ -54,52 +54,34 @@ they are members. The following options affect the general outline of \fBovs\-vsctl\fR's activities: . -.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. The \fItarget\fR takes -one of two forms: +.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 \(bu -The name of 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\fR.ctl\fR, where \fIpid\fR is the -\fBovs\-vswitchd\fR process's process ID. -.IP \(bu -The name of a pidfile, that is, a file whose contents are the process -ID of a running process as a decimal number. \fBovs\-vswitchd\fR -creates a pidfile if it is invoked with the \fB\-\-pidfile\fR option. -\fBovs\-vsctl\fR reads the pidfile, then looks for a Unix socket named -\fB@RUNDIR@/ovs\-vswitchd.\fIpid\fR.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 "\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 -If \fItarget\fR does not begin with \fB/\fR, then \fB@RUNDIR@/\fR is -implicitly prefixed to it. -.IP -If neither \fB\-t\fR nor \fB\-\-target\fR is specified, the default target is -\fB@RUNDIR@/ovs\-vswitchd.pid\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 @@ -107,6 +89,8 @@ 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. . +.so lib/vlog.man +. .SH COMMANDS The commands implemented by \fBovs\-vsctl\fR are described in the sections below. @@ -147,6 +131,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 @@ -174,6 +177,25 @@ must be the real or fake bridge that contains \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 @@ -188,6 +210,26 @@ 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. +. .SH "EXAMPLES" Create a new bridge named br0 and add port eth0 to it: .IP @@ -209,5 +251,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).