]>
Commit | Line | Data |
---|---|---|
7d9809ef | 1 | .\" -*- nroff -*- |
6794be1d | 2 | .so lib/ovs.tmac |
d2cb6c95 | 3 | .TH ovs\-vswitchd 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" |
812560d7 | 4 | .\" This program's name: |
064af421 BP |
5 | .ds PN ovs\-vswitchd |
6 | . | |
7 | .SH NAME | |
f30f26be | 8 | ovs\-vswitchd \- Open vSwitch daemon |
064af421 BP |
9 | . |
10 | .SH SYNOPSIS | |
80df177a | 11 | \fBovs\-vswitchd \fR[\fIdatabase\fR] |
064af421 BP |
12 | . |
13 | .SH DESCRIPTION | |
299a244b | 14 | A daemon that manages and controls any number of Open vSwitch switches |
f30f26be | 15 | on the local machine. |
064af421 | 16 | .PP |
80df177a | 17 | The \fIdatabase\fR argument specifies how \fBovs\-vswitchd\fR connects |
12b84d50 BP |
18 | to \fBovsdb\-server\fR. \fIdatabase\fR may be an OVSDB active or |
19 | passive connection method, as described in \fBovsdb\fR(7). The | |
20 | default is \fBunix:@RUNDIR@/db.sock\fR. | |
064af421 | 21 | .PP |
76343538 BP |
22 | \fBovs\-vswitchd\fR retrieves its configuration from \fIdatabase\fR at |
23 | startup. It sets up Open vSwitch datapaths and then operates | |
24 | switching across each bridge described in its configuration files. As | |
25 | the database changes, \fBovs\-vswitchd\fR automatically updates its | |
26 | configuration to match. | |
27 | .PP | |
299a244b | 28 | \fBovs\-vswitchd\fR switches may be configured with any of the following |
f30f26be | 29 | features: |
064af421 BP |
30 | . |
31 | .IP \(bu | |
32 | L2 switching with MAC learning. | |
33 | . | |
34 | .IP \(bu | |
35 | NIC bonding with automatic fail-over and source MAC-based TX load | |
36 | balancing ("SLB"). | |
37 | . | |
38 | .IP \(bu | |
39 | 802.1Q VLAN support. | |
40 | . | |
41 | .IP \(bu | |
42 | Port mirroring, with optional VLAN tagging. | |
43 | . | |
44 | .IP \(bu | |
45 | NetFlow v5 flow logging. | |
46 | . | |
47 | .IP \(bu | |
d1ae8299 | 48 | sFlow(R) monitoring. |
72b06300 BP |
49 | . |
50 | .IP \(bu | |
064af421 BP |
51 | Connectivity to an external OpenFlow controller, such as NOX. |
52 | . | |
53 | .PP | |
54 | Only a single instance of \fBovs\-vswitchd\fR is intended to run at a time. | |
f30f26be | 55 | A single \fBovs\-vswitchd\fR can manage any number of switch instances, up |
064af421 BP |
56 | to the maximum number of supported Open vSwitch datapaths. |
57 | .PP | |
f4b72cb4 BP |
58 | \fBovs\-vswitchd\fR does all the necessary management of Open vSwitch |
59 | datapaths itself. Thus, \fBovs\-dpctl\fR(8) (and its userspace | |
60 | datapath counterparts accessible via \fBovs\-appctl | |
61 | dpctl/\fIcommand\fR) are not needed with \fBovs\-vswitchd\fR and should | |
62 | not be used because they can interfere with its operation. These | |
63 | tools are still useful for diagnostics. | |
064af421 BP |
64 | .PP |
65 | An Open vSwitch datapath kernel module must be loaded for \fBovs\-vswitchd\fR | |
795752a3 SF |
66 | to be useful. Refer to the documentation for instructions on how to build and |
67 | load the Open vSwitch kernel module. | |
064af421 BP |
68 | .PP |
69 | .SH OPTIONS | |
4e312e69 | 70 | .IP "\fB\-\-mlockall\fR" |
86a06318 BP |
71 | Causes \fBovs\-vswitchd\fR to call the \fBmlockall()\fR function, to |
72 | attempt to lock all of its process memory into physical RAM, | |
73 | preventing the kernel from paging any of its memory to disk. This | |
74 | helps to avoid networking interruptions due to system memory pressure. | |
75 | .IP | |
76 | Some systems do not support \fBmlockall()\fR at all, and other systems | |
77 | only allow privileged users, such as the superuser, to use it. | |
78 | \fBovs\-vswitchd\fR emits a log message if \fBmlockall()\fR is | |
79 | unavailable or unsuccessful. | |
80 | . | |
d1279464 | 81 | .SS "DPDK Options" |
49df3c0f BP |
82 | For details on initializing \fBovs\-vswitchd\fR to use DPDK ports, |
83 | refer to the documentation or \fBovs\-vswitchd.conf.db\fR(5). | |
42dd41ef | 84 | .SS "Daemon Options" |
a7ff9bd7 BP |
85 | .ds DD \ |
86 | \fBovs\-vswitchd\fR detaches only after it has connected to the \ | |
87 | database, retrieved the initial configuration, and set up that \ | |
88 | configuration. | |
064af421 | 89 | .so lib/daemon.man |
42dd41ef GS |
90 | .SS "Service Options" |
91 | .so lib/service.man | |
ac300505 | 92 | .SS "Public Key Infrastructure Options" |
6f61c75b BP |
93 | .so lib/ssl.man |
94 | .so lib/ssl-bootstrap.man | |
c33fa581 | 95 | .so lib/ssl-peer-ca-cert.man |
b3fca241 | 96 | .SS "Logging Options" |
064af421 | 97 | .so lib/vlog.man |
8a986a0a GS |
98 | .SS "Other Options" |
99 | .so lib/unixctl.man | |
064af421 | 100 | .so lib/common.man |
064af421 | 101 | . |
b16fdafe BP |
102 | .SH "RUNTIME MANAGEMENT COMMANDS" |
103 | \fBovs\-appctl\fR(8) can send commands to a running | |
104 | \fBovs\-vswitchd\fR process. The currently supported commands are | |
105 | described below. The command descriptions assume an understanding of | |
76343538 | 106 | how to configure Open vSwitch. |
9e15c889 | 107 | .SS "GENERAL COMMANDS" |
fe13ccdc AZ |
108 | .IP "\fBexit\fR \fI--cleanup\fR" |
109 | Causes \fBovs\-vswitchd\fR to gracefully terminate. If \fI--cleanup\fR | |
bae24b4e | 110 | is specified, deletes flows from datapaths and releases other datapath |
79eadafe BP |
111 | resources configured by \fBovs\-vswitchd\fR. Otherwise, datapath |
112 | flows and other resources remains undeleted. Resources of datapaths | |
113 | that are integrated into \fBovs\-vswitchd\fR (e.g. the \fBnetdev\fR | |
114 | datapath type) are always released regardless of \fI--cleanup\fR | |
115 | except for ports with \fBinternal\fR type. Use \fI--cleanup\fR to | |
116 | release \fBinternal\fR ports too. | |
fe13ccdc | 117 | . |
3d657a0a IS |
118 | .IP "\fBqos/show-types\fR \fIinterface\fR" |
119 | Queries the interface for a list of Quality of Service types that are | |
120 | configurable via Open vSwitch for the given \fIinterface\fR. | |
e8fe3026 EJ |
121 | .IP "\fBqos/show\fR \fIinterface\fR" |
122 | Queries the kernel for Quality of Service configuration and statistics | |
123 | associated with the given \fIinterface\fR. | |
6d13e6dd PR |
124 | .IP "\fBbfd/show\fR [\fIinterface\fR]" |
125 | Displays detailed information about Bidirectional Forwarding Detection | |
126 | configured on \fIinterface\fR. If \fIinterface\fR is not specified, | |
127 | then displays detailed information about all interfaces with BFD | |
128 | enabled. | |
129 | .IP "\fBbfd/set-forwarding\fR [\fIinterface\fR] \fIstatus\fR" | |
130 | Force the fault status of the BFD module on \fIinterface\fR (or all | |
131 | interfaces if none is given) to be \fIstatus\fR. \fIstatus\fR can be | |
132 | "true", "false", or "normal" which reverts to the standard behavior. | |
ae75dae3 | 133 | .IP "\fBcfm/show\fR [\fIinterface\fR]" |
20c8e971 | 134 | Displays detailed information about Connectivity Fault Management |
ae75dae3 JP |
135 | configured on \fIinterface\fR. If \fIinterface\fR is not specified, |
136 | then displays detailed information about all interfaces with CFM | |
137 | enabled. | |
d7243b93 EJ |
138 | .IP "\fBcfm/set-fault\fR [\fIinterface\fR] \fIstatus\fR" |
139 | Force the fault status of the CFM module on \fIinterface\fR (or all | |
140 | interfaces if none is given) to be \fIstatus\fR. \fIstatus\fR can be | |
141 | "true", "false", or "normal" which reverts to the standard behavior. | |
fe4a02e4 EJ |
142 | .IP "\fBstp/tcn\fR [\fIbridge\fR]" |
143 | Forces a topology change event on \fIbridge\fR if it's running STP. This | |
144 | may cause it to send Topology Change Notifications to its peers and flush | |
cc3a32f3 | 145 | its MAC table. If no \fIbridge\fR is given, forces a topology change |
fe4a02e4 | 146 | event on all bridges. |
5f206eb6 | 147 | .IP "\fBstp/show\fR [\fIbridge\fR]" |
148 | Displays detailed information about spanning tree on the \fIbridge\fR. If | |
149 | \fIbridge\fR is not specified, then displays detailed information about all | |
150 | bridges with STP enabled. | |
cc3a32f3 | 151 | .IP "\fBrstp/tcn\fR [\fIbridge\fR]" |
152 | Forces a topology change event on \fIbridge\fR if it's running RSTP. This | |
153 | may cause it to send Topology Change Notifications to its peers and flush | |
154 | its MAC table. If no \fIbridge\fR is given, forces a topology change | |
155 | event on all bridges. | |
156 | .IP "\fBrstp/show\fR [\fIbridge\fR]" | |
157 | Displays detailed information about rapid spanning tree on the \fIbridge\fR. | |
158 | If \fIbridge\fR is not specified, then displays detailed information about all | |
159 | bridges with RSTP enabled. | |
b16fdafe BP |
160 | .SS "BRIDGE COMMANDS" |
161 | These commands manage bridges. | |
96e466a3 EJ |
162 | .IP "\fBfdb/flush\fR [\fIbridge\fR]" |
163 | Flushes \fIbridge\fR MAC address learning table, or all learning tables | |
164 | if no \fIbridge\fR is given. | |
b16fdafe BP |
165 | .IP "\fBfdb/show\fR \fIbridge\fR" |
166 | Lists each MAC address/VLAN pair learned by the specified \fIbridge\fR, | |
08fdcc12 FL |
167 | along with the port on which it was learned and the age of the entry, |
168 | in seconds. | |
6433e2c7 EC |
169 | .IP "\fBfdb/stats-clear\fR [\fIbridge\fR]" |
170 | Clear \fIbridge\fR MAC address learning table statistics, or all | |
171 | statistics if no \fIbridge\fR is given. | |
172 | .IP "\fBfdb/stats-show\fR \fIbridge\fR" | |
173 | Show MAC address learning table statistics for the specified \fIbridge\fR. | |
08fdcc12 FL |
174 | .IP "\fBmdb/flush\fR [\fIbridge\fR]" |
175 | Flushes \fIbridge\fR multicast snooping table, or all snooping tables | |
176 | if no \fIbridge\fR is given. | |
177 | .IP "\fBmdb/show\fR \fIbridge\fR" | |
178 | Lists each multicast group/VLAN pair learned by the specified \fIbridge\fR, | |
b16fdafe BP |
179 | along with the port on which it was learned and the age of the entry, |
180 | in seconds. | |
fa05809b BP |
181 | .IP "\fBbridge/reconnect\fR [\fIbridge\fR]" |
182 | Makes \fIbridge\fR drop all of its OpenFlow controller connections and | |
183 | reconnect. If \fIbridge\fR is not specified, then all bridges drop | |
184 | their controller connections and reconnect. | |
185 | .IP | |
186 | This command might be useful for debugging OpenFlow controller issues. | |
cdd35cff | 187 | . |
16441315 | 188 | .IP "\fBbridge/dump\-flows\fR [\fB\-\-offload-stats\fR] \fIbridge\fR" |
cdd35cff | 189 | Lists all flows in \fIbridge\fR, including those normally hidden to |
4e312e69 | 190 | commands such as \fBovs\-ofctl dump\-flows\fR. Flows set up by mechanisms |
cdd35cff JP |
191 | such as in-band control and fail-open are hidden from the controller |
192 | since it is not allowed to modify or override them. | |
16441315 | 193 | If \fB\-\-offload-stats\fR are specified then also list statistics for |
194 | offloaded packets and bytes, which are a subset of the total packets and | |
195 | bytes. | |
b16fdafe BP |
196 | .SS "BOND COMMANDS" |
197 | These commands manage bonded ports on an Open vSwitch's bridges. To | |
198 | understand some of these commands, it is important to understand a | |
be02e7c3 EJ |
199 | detail of the bonding implementation called ``source load balancing'' |
200 | (SLB). Instead of directly assigning Ethernet source addresses to | |
91fc374a | 201 | members, the bonding implementation computes a function that maps an |
be02e7c3 EJ |
202 | 48-bit Ethernet source addresses into an 8-bit value (a ``MAC hash'' |
203 | value). All of the Ethernet addresses that map to a single 8-bit | |
91fc374a | 204 | value are then assigned to a single member. |
b16fdafe | 205 | .IP "\fBbond/list\fR" |
91fc374a | 206 | Lists all of the bonds, and their members, on each bridge. |
064af421 | 207 | . |
c33a8a25 EJ |
208 | .IP "\fBbond/show\fR [\fIport\fR]" |
209 | Lists all of the bond-specific information (updelay, downdelay, time | |
210 | until the next rebalance) about the given bonded \fIport\fR, or all | |
211 | bonded ports if no \fIport\fR is given. Also lists information about | |
91fc374a | 212 | each members: whether it is enabled or disabled, the time to completion |
c33a8a25 | 213 | of an updelay or downdelay if one is in progress, whether it is the |
91fc374a | 214 | active member, the hashes assigned to the member. Any LACP information |
c33a8a25 EJ |
215 | related to this bond may be found using the \fBlacp/show\fR command. |
216 | . | |
91fc374a BP |
217 | .IP "\fBbond/migrate\fR \fIport\fR \fIhash\fR \fImember\fR" |
218 | Only valid for SLB bonds. Assigns a given MAC hash to a new member. | |
be02e7c3 | 219 | \fIport\fR specifies the bond port, \fIhash\fR the MAC hash to be |
91fc374a BP |
220 | migrated (as a decimal number between 0 and 255), and \fImember\fR the |
221 | new member to be assigned. | |
b16fdafe BP |
222 | .IP |
223 | The reassignment is not permanent: rebalancing or fail-over will | |
91fc374a | 224 | cause the MAC hash to be shifted to a new member in the usual |
b16fdafe BP |
225 | manner. |
226 | .IP | |
91fc374a BP |
227 | A MAC hash cannot be migrated to a disabled member. |
228 | .IP "\fBbond/set\-active\-member\fR \fIport\fR \fImember\fR" | |
229 | Sets \fImember\fR as the active member on \fIport\fR. \fImember\fR must | |
b16fdafe BP |
230 | currently be enabled. |
231 | .IP | |
91fc374a BP |
232 | The setting is not permanent: a new active member will be selected |
233 | if \fImember\fR becomes disabled. | |
234 | .IP "\fBbond/enable\-member\fR \fIport\fR \fImember\fR" | |
235 | .IQ "\fBbond/disable\-member\fR \fIport\fR \fImember\fR" | |
236 | Enables (or disables) \fImember\fR on the given bond \fIport\fR, skipping any | |
b16fdafe BP |
237 | updelay (or downdelay). |
238 | .IP | |
239 | This setting is not permanent: it persists only until the carrier | |
91fc374a | 240 | status of \fImember\fR changes. |
672d18b2 | 241 | .IP "\fBbond/hash\fR \fImac\fR [\fIvlan\fR] [\fIbasis\fR]" |
e58de0e3 | 242 | Returns the hash value which would be used for \fImac\fR with \fIvlan\fR |
672d18b2 | 243 | and \fIbasis\fR if specified. |
064af421 | 244 | . |
5dab8ece | 245 | .IP "\fBlacp/show\fR [\fIport\fR]" |
6aa74308 EJ |
246 | Lists all of the LACP related information about the given \fIport\fR: |
247 | active or passive, aggregation key, system id, and system priority. Also | |
91fc374a | 248 | lists information about each member: whether it is enabled or disabled, |
6aa74308 | 249 | whether it is attached or detached, port id and priority, actor |
5dab8ece JP |
250 | information, and partner information. If \fIport\fR is not specified, |
251 | then displays detailed information about all interfaces with CFM | |
252 | enabled. | |
49b9cad3 NK |
253 | . |
254 | .IP "\fBlacp/stats-show\fR [\fIport\fR]" | |
255 | Lists various stats about LACP PDUs (number of RX/TX PDUs, bad PDUs received) | |
91fc374a | 256 | and member state (number of times its state expired/defaulted and carrier |
49b9cad3 NK |
257 | status changed) for the given \fIport\fR. If \fIport\fR is not specified, |
258 | then displays stats of all interfaces with LACP enabled. | |
fceef209 DDP |
259 | .SS "DPCTL DATAPATH DEBUGGING COMMANDS" |
260 | The primary way to configure \fBovs\-vswitchd\fR is through the Open | |
261 | vSwitch database, e.g. using \fBovs\-vsctl\fR(8). These commands | |
262 | provide a debugging interface for managing datapaths. They implement | |
263 | the same features (and syntax) as \fBovs\-dpctl\fR(8). Unlike | |
264 | \fBovs\-dpctl\fR(8), these commands work with datapaths that are | |
265 | integrated into \fBovs\-vswitchd\fR (e.g. the \fBnetdev\fR datapath | |
266 | type). | |
267 | .PP | |
268 | . | |
269 | .ds DX \fBdpctl/\fR | |
270 | .de DO | |
271 | \\$2 \\$1 \\$3 | |
272 | .. | |
273 | .so lib/dpctl.man | |
6aa74308 | 274 | . |
9af9dbce | 275 | .so lib/dpdk-unixctl.man |
79f36875 | 276 | .so lib/dpif-netdev-unixctl.man |
40f185ac | 277 | .so lib/netdev-dpdk-unixctl.man |
27022416 | 278 | .so ofproto/ofproto-dpif-unixctl.man |
7aa697dd | 279 | .so ofproto/ofproto-unixctl.man |
b16fdafe | 280 | .so lib/vlog-unixctl.man |
149ff68a | 281 | .so lib/memory-unixctl.man |
6901e5e2 | 282 | .so lib/coverage-unixctl.man |
a36de779 | 283 | .so ofproto/ofproto-tnl-unixctl.man |
7a7708a0 | 284 | . |
42ed0063 BP |
285 | .SH "OPENFLOW IMPLEMENTATION" |
286 | . | |
287 | .PP | |
288 | This section documents aspects of OpenFlow for which the OpenFlow | |
289 | specification requires documentation. | |
290 | . | |
291 | .SS "Packet buffering." | |
292 | The OpenFlow specification, version 1.2, says: | |
293 | . | |
294 | .IP | |
295 | Switches that implement buffering are expected to expose, through | |
296 | documentation, both the amount of available buffering, and the length | |
297 | of time before buffers may be reused. | |
298 | . | |
299 | .PP | |
c184807c | 300 | Open vSwitch does not maintains any packet buffers. |
42ed0063 | 301 | . |
51bb26fa JR |
302 | .SS "Bundle lifetime" |
303 | The OpenFlow specification, version 1.4, says: | |
304 | . | |
305 | .IP | |
306 | If the switch does not receive any OFPT_BUNDLE_CONTROL or | |
307 | OFPT_BUNDLE_ADD_MESSAGE message for an opened bundle_id for a switch | |
308 | defined time greater than 1s, it may send an ofp_error_msg with | |
309 | OFPET_BUNDLE_FAILED type and OFPBFC_TIMEOUT code. If the switch does | |
310 | not receive any new message in a bundle apart from echo request and | |
311 | replies for a switch defined time greater than 1s, it may send an | |
312 | ofp_error_msg with OFPET_BUNDLE_FAILED type and OFPBFC_TIMEOUT code. | |
313 | . | |
314 | .PP | |
7fdd2082 FL |
315 | Open vSwitch implements default idle bundle lifetime of 10 seconds. |
316 | (This is configurable via \fBother-config:bundle-idle-timeout\fR in | |
317 | the \fBOpen_vSwitch\fR table. See \fBovs-vswitchd.conf.db\fR(5) | |
318 | for details.) | |
51bb26fa | 319 | . |
7a7708a0 BP |
320 | .SH "LIMITS" |
321 | . | |
322 | .PP | |
323 | We believe these limits to be accurate as of this writing. These | |
324 | limits assume the use of the Linux kernel datapath. | |
325 | . | |
326 | .IP \(bu | |
6e587965 | 327 | \fBovs\-vswitchd\fR started through \fBovs\-ctl\fR(8) provides a limit of 65535 |
8ed70321 GS |
328 | file descriptors. The limits on the number of bridges and ports is decided by |
329 | the availability of file descriptors. With the Linux kernel datapath, creation | |
4224b9cf BP |
330 | of a single bridge consumes three file descriptors and each port |
331 | consumes one additional file descriptor. Other platforms | |
6e587965 | 332 | may have different limitations. |
7a7708a0 BP |
333 | . |
334 | .IP \(bu | |
4224b9cf | 335 | 8,192 MAC learning entries per bridge, by default. (This is |
2be9d4f0 BP |
336 | configurable via \fBother\-config:mac\-table\-size\fR in the |
337 | \fBBridge\fR table. See \fBovs\-vswitchd.conf.db\fR(5) for details.) | |
7a7708a0 BP |
338 | . |
339 | .IP \(bu | |
340 | Kernel flows are limited only by memory available to the kernel. | |
341 | Performance will degrade beyond 1,048,576 kernel flows per bridge with | |
342 | a 32-bit kernel, beyond 262,144 with a 64-bit kernel. | |
343 | (\fBovs\-vswitchd\fR should never install anywhere near that many | |
344 | flows.) | |
345 | . | |
346 | .IP \(bu | |
347 | OpenFlow flows are limited only by available memory. Performance is | |
348 | linear in the number of unique wildcard patterns. That is, an | |
349 | OpenFlow table that contains many flows that all match on the same | |
350 | fields in the same way has a constant-time lookup, but a table that | |
351 | contains many flows that match on different fields requires lookup | |
352 | time linear in the number of flows. | |
353 | . | |
354 | .IP \(bu | |
355 | 255 ports per bridge participating in 802.1D Spanning Tree Protocol. | |
356 | . | |
357 | .IP \(bu | |
358 | 32 mirrors per bridge. | |
359 | . | |
360 | .IP \(bu | |
4224b9cf BP |
361 | 15 bytes for the name of a port, for ports implemented in the Linux |
362 | kernel. Ports implemented in userspace, such as patch ports, do not | |
363 | have an arbitrary length limitation. OpenFlow also limit port names | |
364 | to 15 bytes. | |
7a7708a0 | 365 | . |
064af421 BP |
366 | .SH "SEE ALSO" |
367 | .BR ovs\-appctl (8), | |
795752a3 | 368 | .BR ovsdb\-server (1). |