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 .SH COMMANDS
  98 The commands implemented by \fBovs\-vsctl\fR are described in the
  99 sections below.
 100 .
 101 .SS "Bridge Commands"
 102 These commands examine and manipulate Open vSwitch bridges.
 103 .
 104 .IP "\fBadd\-br \fIbridge\fR"
 105 Creates a new bridge named \fIbridge\fR.  Initially the bridge will
 106 have no ports (other than \fIbridge\fR itself).
 107 .
 108 .IP "\fBadd\-br \fIbridge parent vlan\fR"
 109 Creates a ``fake bridge'' named \fIbridge\fR within the existing Open
 110 vSwitch bridge \fIparent\fR, which must already exist and must not
 111 itself be a fake bridge.  The new fake bridge will be on 802.1Q VLAN
 112 \fIvlan\fR, which must be an integer between 1 and 4095.  Initially
 113 \fIbridge\fR will have no ports (other than \fIbridge\fR itself).
 114 .
 115 .IP "\fBdel\-br \fIbridge\fR"
 116 Deletes \fIbridge\fR and all of its ports.  If \fIbridge\fR is a real
 117 bridge, this command also deletes any fake bridges that were created
 118 with \fIbridge\fR as parent, including all of their ports.
 119 .
 120 .IP "\fBlist\-br\fR"
 121 Lists all existing real and fake bridges on standard output, one per
 122 line.
 123 .
 124 .IP "\fBbr\-exists \fIbridge\fR"
 125 Tests whether \fIbridge\fR exists as a real or fake bridge.  If so,
 126 \fBovs\-vsctl\fR exits successfully with exit code 0.  If not,
 127 \fBovs\-vsctl\fR exits unsuccessfully with exit code 2.
 128 .
 129 .SS "Port Commands"
 130 .
 131 These commands examine and manipulate Open vSwitch ports.  These
 132 commands treat a bonded port as a single entity.
 133 .
 134 .IP "\fBlist\-ports \fIbridge\fR"
 135 Lists all of the ports within \fIbridge\fR on standard output, one per
 136 line.  The local port \fIbridge\fR is not included in the list.
 137 .
 138 .IP "\fBadd\-port \fIbridge port\fR"
 139 Creates on \fIbridge\fR a new port named \fIport\fR from the network
 140 device of the same name.
 141 .
 142 .IP "\fBadd\-bond \fIbridge port iface\fR\&..."
 143 Creates on \fIbridge\fR a new port named \fIport\fR that bonds
 144 together the network devices given as each \fIiface\fR.  At least two
 145 interfaces must be named.
 146 .
 147 .IP "\fBdel\-port \fIbridge port\fR"
 148 Deletes \fBport\fR from \fIbridge\fR.
 149 .
 150 .IP "\fBport\-to\-br \fIport\fR"
 151 Prints the name of the bridge that contains \fIport\fR on standard
 152 output.
 153 .
 154 .SS "Interface Commands"
 155 .
 156 These commands examine the interfaces attached to an Open vSwitch
 157 bridge.  These commands treat a bonded port as a collection of two or
 158 more interfaces, rather than as a single port.
 159 .
 160 .IP "\fBlist\-ifaces \fIbridge\fR"
 161 Lists all of the interfaces within \fIbridge\fR on standard output,
 162 one per line.  The local port \fIbridge\fR is not included in the
 163 list.
 164 .
 165 .IP "\fBiface\-to\-br \fIiface\fR"
 166 Prints the name of the bridge that contains \fIiface\fR on standard
 167 output.
 168 .
 169 .SH "EXIT STATUS"
 170 .IP "0"
 171 Successful program execution.
 172 .IP "1"
 173 Usage, syntax, or configuration file error.
 174 .IP "2"
 175 The \fIbridge\fR argument to \fBbr\-exists\fR specified the name of a
 176 bridge that does not exist.
 177 .SH "SEE ALSO"
 178 .
 179 .BR ovs\-vswitchd.conf (5),
 180 .BR ovs\-vswitchd (8).