utilities/ovs-vsctl.8.in

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .TH ovs\-vsctl 8 "September 2009" "Open vSwitch" "Open vSwitch Manual"
   8 .ds PN ovs\-vsctl
   9 .
  10 .SH NAME
  11 ovs\-vsctl \- utility for querying and configuring \fBovs\-vswitchd\fR
  12 .
  13 .SH SYNOPSIS
  14 \fBovs\-vsctl\fR [\fIoptions\fR] \fIcommand \fR[\fIargs\fR\&...]
  15 .
  16 .SH DESCRIPTION
  17 The \fBovs\-vsctl\fR program configures \fBovs\-vswitchd\fR(8), mainly
  18 by providing a high\-level interface to editing its configuration file
  19 \fBovs\-vswitchd.conf\fR(5).  This program is mainly intended for use
  20 when \fBovs\-vswitchd\fR is running, but it can also be used when
  21 \fBovs\-vswitchd\fR is not running.  In the latter case configuration
  22 changes will only take effect when \fBovs\-vswitchd\fR is started.
  23 .PP
  24 By default, each time \fBovs\-vsctl\fR runs, it examines and,
  25 depending on the requested command, possibly applies changes to an
  26 \fBovs\-vswitchd.conf\fR file.  Then, if it applied any changes and if
  27 \fBovs\-vswitchd\fR is running, it tells \fBovs\-vswitchd\fR to reload
  28 the modified configuration file and waits for the reload to complete
  29 before exiting.
  30 .
  31 .SS "Linux VLAN Bridging Compatibility"
  32 The \fBovs\-vsctl\fR program supports the model of a bridge
  33 implemented by Open vSwitch, in which a single bridge supports ports
  34 on multiple VLANs.  In this model, each port on a bridge is either a
  35 trunk port that potentially passes packets tagged with 802.1Q headers
  36 that designate VLANs or it is assigned a single implicit VLAN that is
  37 never tagged with an 802.1Q header.
  38 .PP
  39 For compatibility with software designed for the Linux bridge,
  40 \fBovs\-vsctl\fR also supports a model in which traffic associated
  41 with a given 802.1Q VLAN is segregated into a separate bridge.  A
  42 special form of the \fBadd\-br\fR command (see below) creates a ``fake
  43 bridge'' within an Open vSwitch bridge to simulate this behavior.
  44 When such a ``fake bridge'' is active, \fBovs\-vsctl\fR will treat it
  45 much like a bridge separate from its ``parent bridge,'' but the actual
  46 implementation in Open vSwitch uses only a single bridge, with ports on
  47 the fake bridge assigned the implicit VLAN of the fake bridge of which
  48 they are members.
  49 .
  50 .SH OPTIONS
  51 .
  52 The following options affect the general outline of \fBovs\-vsctl\fR's
  53 activities:
  54 .
  55 .IP "\fB\-c \fIfile\fR"
  56 .IQ "\fB\-\-config=\fIfile\fR"
  57 Sets the configuration file that \fBovs\-vsctl\fR reads and possibly
  58 modifies.  The default is \fB@localstatedir@/ovs\-vswitchd.conf\fR.
  59 .IP
  60 If \fIfile\fR is specified as \fB\-\fR, then \fBovs\-vsctl\fR reads
  61 the configuration file from standard input and, for commands that
  62 modify the configuration, writes the new one to standard output.  This
  63 is useful for testing but it should not be used in production because
  64 it bypasses the Open vSwitch configuration file locking protocol.
  65 .
  66 .IP "\fB\-t \fItarget\fR"
  67 .IQ "\fB\-\-target=\fItarget\fR"
  68 Configures how \fBovs\-vsctl\fR contacts \fBovs\-vswitchd\fR to
  69 instruct it to reload its configuration file.  The \fItarget\fR takes
  70 one of two forms:
  71 .RS
  72 .IP \(bu
  73 The name of a Unix domain socket on which \fBovs\-vswitchd\fR is
  74 listening for control channel connections.  By default,
  75 \fBovs\-vswitchd\fR listens on a Unix domain socket named
  76 \fB@RUNDIR@/ovs\-vswitchd.\fIpid\fR.ctl\fR, where \fIpid\fR is the
  77 \fBovs\-vswitchd\fR process's process ID.
  78 .IP \(bu
  79 The name of a pidfile, that is, a file whose contents are the process
  80 ID of a running process as a decimal number.  \fBovs\-vswitchd\fR
  81 creates a pidfile if it is invoked with the \fB\-\-pidfile\fR option.
  82 \fBovs\-vsctl\fR reads the pidfile, then looks for a Unix socket named
  83 \fB@RUNDIR@/ovs\-vswitchd.\fIpid\fR.ctl\fR, where \fIpid\fR is
  84 replaced by the process ID read from \fItarget\fR, and uses that file
  85 as if it had been specified directly as the target.
  86 .RE
  87 .IP
  88 If \fItarget\fR does not begin with \fB/\fR, then \fB@RUNDIR@/\fR is
  89 implicitly prefixed to it.
  90 .IP
  91 If neither \fB\-t\fR nor \fB\-\-target\fR is specified, the default target is
  92 \fB@RUNDIR@/ovs\-vswitchd.pid\fR.
  93 .IP "\fB\-\-no\-reload\fR"
  94 Prevents \fBovs\-vsctl\fR from telling \fBovs\-vswitchd\fR to reload
  95 its configuration file.
  96 .
  97 .IP "\fB\-\-no\-syslog\fR"
  98 By default, \fBovs\-vsctl\fR logs its arguments and the details of any
  99 changes that it makes to the system log.  This option disables this
 100 logging.
 101 .
 102 .SH COMMANDS
 103 The commands implemented by \fBovs\-vsctl\fR are described in the
 104 sections below.
 105 .
 106 .SS "Bridge Commands"
 107 These commands examine and manipulate Open vSwitch bridges.
 108 .
 109 .IP "\fBadd\-br \fIbridge\fR"
 110 Creates a new bridge named \fIbridge\fR.  Initially the bridge will
 111 have no ports (other than \fIbridge\fR itself).
 112 .
 113 .IP "\fBadd\-br \fIbridge parent vlan\fR"
 114 Creates a ``fake bridge'' named \fIbridge\fR within the existing Open
 115 vSwitch bridge \fIparent\fR, which must already exist and must not
 116 itself be a fake bridge.  The new fake bridge will be on 802.1Q VLAN
 117 \fIvlan\fR, which must be an integer between 1 and 4095.  Initially
 118 \fIbridge\fR will have no ports (other than \fIbridge\fR itself).
 119 .
 120 .IP "\fBdel\-br \fIbridge\fR"
 121 Deletes \fIbridge\fR and all of its ports.  If \fIbridge\fR is a real
 122 bridge, this command also deletes any fake bridges that were created
 123 with \fIbridge\fR as parent, including all of their ports.
 124 .
 125 .IP "\fBlist\-br\fR"
 126 Lists all existing real and fake bridges on standard output, one per
 127 line.
 128 .
 129 .IP "\fBbr\-exists \fIbridge\fR"
 130 Tests whether \fIbridge\fR exists as a real or fake bridge.  If so,
 131 \fBovs\-vsctl\fR exits successfully with exit code 0.  If not,
 132 \fBovs\-vsctl\fR exits unsuccessfully with exit code 2.
 133 .
 134 .IP "\fBbr\-to\-vlan \fIbridge\fR"
 135 If \fIbridge\fR is a fake bridge, prints the bridge's 802.1Q VLAN as a
 136 decimal integer.  If \fIbridge\fR is a real bridge, prints 0.
 137 .
 138 .IP "\fBbr\-to\-parent \fIbridge\fR"
 139 If \fIbridge\fR is a fake bridge, prints the name of its parent
 140 bridge.  If \fIbridge\fR is a real bridge, print \fIbridge\fR.
 141 .
 142 .SS "Port Commands"
 143 .
 144 These commands examine and manipulate Open vSwitch ports.  These
 145 commands treat a bonded port as a single entity.
 146 .
 147 .IP "\fBlist\-ports \fIbridge\fR"
 148 Lists all of the ports within \fIbridge\fR on standard output, one per
 149 line.  The local port \fIbridge\fR is not included in the list.
 150 .
 151 .IP "\fBadd\-port \fIbridge port\fR"
 152 Creates on \fIbridge\fR a new port named \fIport\fR from the network
 153 device of the same name.
 154 .
 155 .IP "\fBadd\-bond \fIbridge port iface\fR\&..."
 156 Creates on \fIbridge\fR a new port named \fIport\fR that bonds
 157 together the network devices given as each \fIiface\fR.  At least two
 158 interfaces must be named.
 159 .
 160 .IP "\fBdel\-port \fR[\fIbridge\fR] \fIport\fR"
 161 Deletes \fIport\fR.  If \fIbridge\fR is omitted, \fIport\fR is removed
 162 from whatever bridge contains it; if \fIbridge\fR is specified, it
 163 must be the real or fake bridge that contains \fIport\fR.
 164 .
 165 .IP "\fBport\-to\-br \fIport\fR"
 166 Prints the name of the bridge that contains \fIport\fR on standard
 167 output.
 168 .
 169 .SS "Interface Commands"
 170 .
 171 These commands examine the interfaces attached to an Open vSwitch
 172 bridge.  These commands treat a bonded port as a collection of two or
 173 more interfaces, rather than as a single port.
 174 .
 175 .IP "\fBlist\-ifaces \fIbridge\fR"
 176 Lists all of the interfaces within \fIbridge\fR on standard output,
 177 one per line.  The local port \fIbridge\fR is not included in the
 178 list.
 179 .
 180 .IP "\fBiface\-to\-br \fIiface\fR"
 181 Prints the name of the bridge that contains \fIiface\fR on standard
 182 output.
 183 .
 184 .SH "EXIT STATUS"
 185 .IP "0"
 186 Successful program execution.
 187 .IP "1"
 188 Usage, syntax, or configuration file error.
 189 .IP "2"
 190 The \fIbridge\fR argument to \fBbr\-exists\fR specified the name of a
 191 bridge that does not exist.
 192 .SH "SEE ALSO"
 193 .
 194 .BR ovs\-vswitchd.conf (5),
 195 .BR ovs\-vswitchd (8).