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