]>
Commit | Line | Data |
---|---|---|
3b135da3 BP |
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 | . | |
8e58fa9a BP |
129 | .IP "\fBbr\-to\-vlan \fIbridge\fR" |
130 | If \fIbridge\fR is a fake bridge, prints the bridge's 802.1Q VLAN as a | |
131 | decimal integer. If \fIbridge\fR is a real bridge, prints 0. | |
132 | . | |
133 | .IP "\fBbr\-to\-parent \fIbridge\fR" | |
134 | If \fIbridge\fR is a fake bridge, prints the name of its parent | |
135 | bridge. If \fIbridge\fR is a real bridge, print \fIbridge\fR. | |
136 | . | |
3b135da3 BP |
137 | .SS "Port Commands" |
138 | . | |
139 | These commands examine and manipulate Open vSwitch ports. These | |
140 | commands treat a bonded port as a single entity. | |
141 | . | |
142 | .IP "\fBlist\-ports \fIbridge\fR" | |
143 | Lists all of the ports within \fIbridge\fR on standard output, one per | |
144 | line. The local port \fIbridge\fR is not included in the list. | |
145 | . | |
146 | .IP "\fBadd\-port \fIbridge port\fR" | |
147 | Creates on \fIbridge\fR a new port named \fIport\fR from the network | |
148 | device of the same name. | |
149 | . | |
150 | .IP "\fBadd\-bond \fIbridge port iface\fR\&..." | |
151 | Creates on \fIbridge\fR a new port named \fIport\fR that bonds | |
152 | together the network devices given as each \fIiface\fR. At least two | |
153 | interfaces must be named. | |
154 | . | |
155 | .IP "\fBdel\-port \fIbridge port\fR" | |
156 | Deletes \fBport\fR from \fIbridge\fR. | |
157 | . | |
158 | .IP "\fBport\-to\-br \fIport\fR" | |
159 | Prints the name of the bridge that contains \fIport\fR on standard | |
160 | output. | |
161 | . | |
162 | .SS "Interface Commands" | |
163 | . | |
164 | These commands examine the interfaces attached to an Open vSwitch | |
165 | bridge. These commands treat a bonded port as a collection of two or | |
166 | more interfaces, rather than as a single port. | |
167 | . | |
168 | .IP "\fBlist\-ifaces \fIbridge\fR" | |
169 | Lists all of the interfaces within \fIbridge\fR on standard output, | |
170 | one per line. The local port \fIbridge\fR is not included in the | |
171 | list. | |
172 | . | |
173 | .IP "\fBiface\-to\-br \fIiface\fR" | |
174 | Prints the name of the bridge that contains \fIiface\fR on standard | |
175 | output. | |
176 | . | |
177 | .SH "EXIT STATUS" | |
178 | .IP "0" | |
179 | Successful program execution. | |
180 | .IP "1" | |
181 | Usage, syntax, or configuration file error. | |
182 | .IP "2" | |
183 | The \fIbridge\fR argument to \fBbr\-exists\fR specified the name of a | |
184 | bridge that does not exist. | |
185 | .SH "SEE ALSO" | |
186 | . | |
187 | .BR ovs\-vswitchd.conf (5), | |
188 | .BR ovs\-vswitchd (8). |