]>
Commit | Line | Data |
---|---|---|
045b2e5c | 1 | .TH test\-openflowd 8 "March 2009" "Open vSwitch" "Open vSwitch Manual" |
812560d7 | 2 | .\" This program's name: |
045b2e5c | 3 | .ds PN test\-openflowd |
812560d7 BP |
4 | .\" SSL peer program's name: |
5 | .ds SN ovs\-controller | |
a9b4a41a | 6 | . |
064af421 | 7 | .SH NAME |
045b2e5c | 8 | test\-openflowd \- OpenFlow switch implementation |
a9b4a41a | 9 | . |
064af421 | 10 | .SH SYNOPSIS |
045b2e5c | 11 | .B test\-openflowd |
195c8086 | 12 | [\fIoptions\fR] \fIdatapath\fR \fIcontroller\fR\&... |
a9b4a41a | 13 | . |
064af421 | 14 | .SH DESCRIPTION |
045b2e5c BP |
15 | The \fBtest\-openflowd\fR program implements an OpenFlow switch using a |
16 | flow-based datapath. \fBtest\-openflowd\fR connects to one or more | |
76ce9432 | 17 | OpenFlow controllers over TCP or SSL. |
a9b4a41a | 18 | .PP |
045b2e5c | 19 | For a more powerful alternative to \fBtest\-openflowd\fR, see |
cb49ee4f BP |
20 | \fBovs\-vswitchd\fR(8). Do not run both daemons at the same time. |
21 | .PP | |
254f2dc8 BP |
22 | The mandatory \fIdatapath\fR argument argument specifies the local |
23 | datapath to relay. It takes the form [\fItype\fB@\fR]\fIname\fR, | |
24 | where \fIname\fR is the network device associated with the datapath's | |
25 | local port. If \fItype\fR is given, it specifies the datapath | |
26 | provider of \fIname\fR, otherwise the default provider \fBsystem\fR is | |
27 | assumed. | |
a9b4a41a | 28 | . |
064af421 | 29 | .PP |
67f6bdd7 BP |
30 | The optional \fIcontroller\fR arguments specify how to connect to the |
31 | OpenFlow controller or controllers. Each takes one of the following | |
32 | forms: | |
84ee7bcf BP |
33 | . |
34 | .so lib/vconn-active.man | |
f8bfdc30 BP |
35 | .IP "\fBnone\fR" |
36 | Run without actively maintaining a connection to a remote OpenFlow | |
37 | controller. (See the \fB\-\-listen\fR option, under \fBNetworking | |
38 | Options\fR below, for another way to make OpenFlow connections to the | |
39 | switch.) | |
84ee7bcf | 40 | . |
064af421 | 41 | .PP |
045b2e5c | 42 | When multiple controllers are configured, \fBtest\-openflowd\fR |
67f6bdd7 BP |
43 | connects to all of them simultaneously. OpenFlow 1.0 does not specify |
44 | how multiple controllers coordinate in interacting with a single | |
45 | switch, so more than one controller should be specified only if the | |
46 | controllers are themselves designed to coordinate with each other. | |
47 | (The Nicira-defined \fBNXT_ROLE\fR OpenFlow vendor extension may be | |
48 | useful for this.) | |
a9b4a41a | 49 | . |
76ce9432 BP |
50 | .SS "Contacting Controllers" |
51 | The OpenFlow switch must be able to contact the OpenFlow controllers | |
064af421 | 52 | over the network. It can do so in one of two ways: |
a9b4a41a | 53 | . |
064af421 BP |
54 | .IP out-of-band |
55 | In this configuration, OpenFlow traffic uses a network separate from | |
56 | the data traffic that it controls, that is, the switch does not use | |
57 | any of the network devices added to the datapath with \fBovs\-dpctl | |
58 | add\-if\fR in its communication with the controller. | |
a9b4a41a | 59 | .IP |
045b2e5c BP |
60 | To use \fBtest\-openflowd\fR in a network with out-of-band control, specify |
61 | \fB\-\-out\-of\-band\fR on the \fBtest\-openflowd\fR command line. The control | |
62 | network must be configured separately, before or after \fBtest\-openflowd\fR | |
064af421 | 63 | is started. |
a9b4a41a | 64 | . |
064af421 BP |
65 | .IP in-band |
66 | In this configuration, a single network is used for OpenFlow traffic | |
67 | and other data traffic, that is, the switch contacts the controller | |
68 | over one of the network devices added to the datapath with \fBovs\-dpctl | |
69 | add\-if\fR. This configuration is often more convenient than | |
70 | out-of-band control, because it is not necessary to maintain two | |
71 | independent networks. | |
a9b4a41a | 72 | .IP |
045b2e5c | 73 | In-band control is the default for \fBtest\-openflowd\fR, so no special |
064af421 | 74 | command-line option is required. |
195c8086 BP |
75 | |
76 | Specify the location of the | |
045b2e5c | 77 | controller on the \fBtest\-openflowd\fR command line as the \fIcontroller\fR |
064af421 | 78 | argument. You must also configure the network device for the OpenFlow |
045b2e5c BP |
79 | ``local port'' to allow \fBtest\-openflowd\fR to connect to that controller. |
80 | The OpenFlow local port is a virtual network port that \fBtest\-openflowd\fR | |
064af421 BP |
81 | bridges to the physical switch ports. The name of the local port for |
82 | a given \fIdatapath\fR may be seen by running \fBovs\-dpctl show | |
83 | \fIdatapath\fR; the local port is listed as port 0 in \fBshow\fR's | |
84 | output. | |
a9b4a41a | 85 | . |
064af421 | 86 | .IP |
045b2e5c | 87 | Before \fBtest\-openflowd\fR starts, the local port network device is not |
064af421 BP |
88 | bridged to any physical network, so the next step depends on whether |
89 | connectivity is required to configure the device's IP address. If the | |
90 | switch has a static IP address, you may configure its IP address now | |
91 | with a command such as | |
92 | .B ifconfig of0 192.168.1.1 | |
045b2e5c | 93 | and then invoke \fBtest\-openflowd\fR. |
a9b4a41a | 94 | .IP |
064af421 BP |
95 | On the other hand, if the switch does not have a static IP address, |
96 | e.g. it obtains its IP address dynamically via DHCP, the DHCP client | |
8cd4882f | 97 | will not be able to contact the DHCP server until the OpenFlow switch |
045b2e5c | 98 | has started up. Thus, start \fBtest\-openflowd\fR without configuring |
064af421 BP |
99 | the local port network device, and start the DHCP client afterward. |
100 | .RE | |
a9b4a41a | 101 | . |
064af421 | 102 | .SH OPTIONS |
0c30c8f1 JP |
103 | .SS "OpenFlow Options" |
104 | .TP | |
4e312e69 | 105 | \fB\-\-datapath\-id=\fIdpid\fR |
093ca5b3 BP |
106 | Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits |
107 | and may not be all-zero, | |
76ce9432 BP |
108 | as the datapath ID that the switch will use to identify itself to |
109 | OpenFlow controllers. | |
a9b4a41a | 110 | .IP |
0c30c8f1 JP |
111 | If this option is omitted, the default datapath ID is taken from the |
112 | Ethernet address of the datapath's local port (which is typically | |
113 | randomly generated) in the lower 48 bits and zeros in the upper 16. | |
a9b4a41a | 114 | . |
0c30c8f1 | 115 | .TP |
4e312e69 | 116 | \fB\-\-mfr\-desc=\fIdesc\fR |
0c30c8f1 JP |
117 | Set the description of the switch's manufacturer to \fIdesc\fR, which |
118 | may contain up to 255 ASCII characters. | |
a9b4a41a | 119 | . |
0c30c8f1 | 120 | .TP |
4e312e69 | 121 | \fB\-\-hw\-desc=\fIdesc\fR |
0c30c8f1 JP |
122 | Set the description of the switch's hardware revision to \fIdesc\fR, which |
123 | may contain up to 255 ASCII characters. | |
a9b4a41a | 124 | . |
0c30c8f1 | 125 | .TP |
4e312e69 | 126 | \fB\-\-sw\-desc=\fIdesc\fR |
0c30c8f1 JP |
127 | Set the description of the switch's software revision to \fIdesc\fR, which |
128 | may contain up to 255 ASCII characters. | |
a9b4a41a | 129 | . |
0c30c8f1 | 130 | .TP |
4e312e69 | 131 | \fB\-\-serial\-desc=\fIdesc\fR |
0c30c8f1 JP |
132 | Set the description of the switch's serial number to \fIdesc\fR, which |
133 | may contain up to 31 ASCII characters. | |
a9b4a41a | 134 | . |
0c30c8f1 | 135 | .TP |
4e312e69 | 136 | \fB\-\-dp\-desc=\fIdesc\fR |
0c30c8f1 JP |
137 | Set the description of the datapath to \fIdesc\fR, which may contain up to |
138 | 255 ASCII characters. Note that this field is intended for debugging | |
139 | purposes and is not guaranteed to be unique and should not be used as | |
140 | the primary identifier of the datapath. | |
a9b4a41a | 141 | . |
064af421 BP |
142 | .SS "Networking Options" |
143 | .TP | |
4e312e69 | 144 | \fB\-\-datapath\-id=\fIdpid\fR |
b123cc3c | 145 | Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits, |
064af421 BP |
146 | as the datapath ID that the switch will use to identify itself to the |
147 | OpenFlow controller. | |
a9b4a41a | 148 | .IP |
064af421 BP |
149 | If this option is omitted, the default datapath ID is taken from the |
150 | Ethernet address of the datapath's local port (which is typically | |
b123cc3c | 151 | randomly generated) in the lower 48 bits and zeros in the upper 16. |
a9b4a41a | 152 | . |
064af421 | 153 | .TP |
4e312e69 | 154 | \fB\-\-fail=\fR[\fBstandalone\fR|\fBsecure\fR] |
064af421 BP |
155 | The controller is, ordinarily, responsible for setting up all flows on |
156 | the OpenFlow switch. Thus, if the connection to the controller fails, | |
157 | no new network connections can be set up. If the connection to the | |
158 | controller stays down long enough, no packets can pass through the | |
159 | switch at all. | |
a9b4a41a | 160 | .IP |
33e01d3a | 161 | If this option is set to \fBstandalone\fR (the default), |
045b2e5c | 162 | \fBtest\-openflowd\fR will |
064af421 BP |
163 | take over responsibility for setting up flows in the local datapath |
164 | when no message has been received from the controller for three times | |
165 | the inactivity probe interval (see below), or 45 seconds by default. | |
045b2e5c BP |
166 | In this ``fail open'' mode, \fBtest\-openflowd\fR causes the datapath to act |
167 | like an ordinary MAC-learning switch. \fBtest\-openflowd\fR will continue to | |
064af421 | 168 | retry connection to the controller in the background and, when the |
33e01d3a | 169 | connection succeeds, it discontinues its standalone switching behavior. |
a9b4a41a | 170 | .IP |
045b2e5c | 171 | If this option is set to \fBsecure\fR, then \fBtest\-openflowd\fR will not |
064af421 | 172 | set up flows on its own when the controller connection fails. |
a9b4a41a | 173 | . |
064af421 | 174 | .TP |
4e312e69 | 175 | \fB\-\-inactivity\-probe=\fIsecs\fR |
8cd4882f BP |
176 | When the OpenFlow switch is connected to the controller, the |
177 | switch waits for a message to be received from the controller for | |
064af421 BP |
178 | \fIsecs\fR seconds before it sends a inactivity probe to the |
179 | controller. After sending the inactivity probe, if no response is | |
8cd4882f | 180 | received for an additional \fIsecs\fR seconds, the switch |
064af421 | 181 | assumes that the connection has been broken and attempts to reconnect. |
f9fb1858 | 182 | The default and the minimum value are both 5 seconds. |
a9b4a41a | 183 | .IP |
064af421 BP |
184 | When fail-open mode is configured, changing the inactivity probe |
185 | interval also changes the interval before entering fail-open mode (see | |
186 | above). | |
a9b4a41a | 187 | . |
064af421 | 188 | .TP |
4e312e69 | 189 | \fB\-\-max\-idle=\fIsecs\fR|\fBpermanent\fR |
064af421 | 190 | Sets \fIsecs\fR as the number of seconds that a flow set up by the |
8cd4882f | 191 | OpenFlow switch will remain in the switch's flow table without any |
064af421 | 192 | matching packets being seen. If \fBpermanent\fR is specified, which |
8cd4882f | 193 | is not recommended, flows set up by the switch will never |
064af421 | 194 | expire. The default is 15 seconds. |
a9b4a41a | 195 | .IP |
8cd4882f BP |
196 | Most flows are set up by the OpenFlow controller, not by the |
197 | switch. This option affects only the following flows, which the | |
198 | OpenFlow switch sets up itself: | |
a9b4a41a | 199 | . |
064af421 BP |
200 | .RS |
201 | .IP \(bu | |
4e312e69 | 202 | When \fB\-\-fail=open\fR is specified, flows set up when the |
8cd4882f | 203 | switch has not been able to contact the controller for the configured |
064af421 | 204 | fail-open delay. |
a9b4a41a | 205 | . |
064af421 BP |
206 | .IP \(bu |
207 | When in-band control is in use, flows set up to bootstrap contacting | |
208 | the controller (see \fBContacting the Controller\fR, above, for | |
209 | more information about in-band control). | |
210 | .RE | |
a9b4a41a | 211 | . |
064af421 | 212 | .IP |
4e312e69 | 213 | As a result, when both \fB\-\-fail=secure\fR and \fB\-\-out\-of\-band\fR are |
064af421 | 214 | specified, this option has no effect. |
a9b4a41a | 215 | . |
064af421 | 216 | .TP |
4e312e69 | 217 | \fB\-\-max\-backoff=\fIsecs\fR |
064af421 BP |
218 | Sets the maximum time between attempts to connect to the controller to |
219 | \fIsecs\fR, which must be at least 1. The actual interval between | |
220 | connection attempts starts at 1 second and doubles on each failing | |
221 | attempt until it reaches the maximum. The default maximum backoff | |
c9aaa877 | 222 | time is 8 seconds. |
a9b4a41a | 223 | . |
064af421 | 224 | .TP |
4e312e69 | 225 | \fB\-l\fR, \fB\-\-listen=\fImethod\fR |
436cf33b JP |
226 | By default, the switch listens for OpenFlow management connections on a |
227 | Unix domain socket named \fB@RUNDIR@/\fIdatapath\fB.mgmt\fR. This socket | |
228 | can be used to perform local OpenFlow monitoring and administration with | |
229 | tools such as \fBovs\-ofctl\fR. | |
a9b4a41a | 230 | .IP |
436cf33b | 231 | This option may be used to override the default listener. The \fImethod\fR |
064af421 BP |
232 | must be given as one of the passive OpenFlow connection methods listed |
233 | below. This option may be specified multiple times to listen to | |
436cf33b JP |
234 | multiple connection methods. If a single \fImethod\fR of \fBnone\fR is |
235 | used, no listeners will be created. | |
a9b4a41a | 236 | . |
064af421 | 237 | .RS |
84ee7bcf | 238 | .so lib/vconn-passive.man |
064af421 | 239 | .RE |
a9b4a41a | 240 | . |
064af421 | 241 | .TP |
4e312e69 | 242 | \fB\-\-snoop=\fImethod\fR |
064af421 BP |
243 | Configures the switch to additionally listen for incoming OpenFlow |
244 | connections for controller connection snooping. The \fImethod\fR must | |
245 | be given as one of the passive OpenFlow connection methods listed | |
4e312e69 | 246 | under the \fB\-\-listen\fR option above. This option may be specified |
064af421 | 247 | multiple times to listen to multiple connection methods. |
a9b4a41a | 248 | .IP |
064af421 | 249 | If \fBovs\-ofctl monitor\fR is used to connect to \fImethod\fR specified on |
4e312e69 | 250 | \fB\-\-snoop\fR, it will display all the OpenFlow messages traveling |
064af421 BP |
251 | between the switch and its controller on the primary OpenFlow |
252 | connection. This can be useful for debugging switch and controller | |
253 | problems. | |
a9b4a41a | 254 | . |
064af421 | 255 | .TP |
4e312e69 | 256 | \fB\-\-in\-band\fR, \fB\-\-out\-of\-band\fR |
045b2e5c | 257 | Configures \fBtest\-openflowd\fR to operate in in-band or out-of-band control |
064af421 BP |
258 | mode (see \fBContacting the Controller\fR above). When neither option |
259 | is given, the default is in-band control. | |
a9b4a41a | 260 | . |
064af421 | 261 | .TP |
4e312e69 | 262 | \fB\-\-netflow=\fIip\fB:\fIport\fR |
2b35e147 BP |
263 | Configures the given UDP \fIport\fR on the specified IP \fIip\fR as |
264 | a recipient of NetFlow messages for expired flows. The \fIip\fR must | |
265 | be specified numerically, not as a DNS name. | |
a9b4a41a | 266 | .IP |
064af421 BP |
267 | This option may be specified multiple times to configure additional |
268 | NetFlow collectors. | |
a9b4a41a | 269 | . |
064af421 | 270 | .SS "Rate-Limiting Options" |
a9b4a41a | 271 | . |
064af421 BP |
272 | These options configure how the switch applies a ``token bucket'' to |
273 | limit the rate at which packets in unknown flows are forwarded to an | |
274 | OpenFlow controller for flow-setup processing. This feature prevents | |
275 | a single OpenFlow switch from overwhelming a controller. | |
a9b4a41a | 276 | . |
064af421 | 277 | .TP |
4e312e69 | 278 | \fB\-\-rate\-limit\fR[\fB=\fIrate\fR] |
064af421 BP |
279 | . |
280 | Limits the maximum rate at which packets will be forwarded to the | |
281 | OpenFlow controller to \fIrate\fR packets per second. If \fIrate\fR | |
282 | is not specified then the default of 1,000 packets per second is used. | |
a9b4a41a | 283 | .IP |
4e312e69 | 284 | If \fB\-\-rate\-limit\fR is not used, then the switch does not limit the |
064af421 | 285 | rate at which packets are forwarded to the controller. |
a9b4a41a | 286 | . |
064af421 | 287 | .TP |
4e312e69 | 288 | \fB\-\-burst\-limit=\fIburst\fR |
064af421 BP |
289 | . |
290 | Sets the maximum number of unused packet credits that the switch will | |
291 | allow to accumulate during time in which no packets are being | |
292 | forwarded to the OpenFlow controller to \fIburst\fR (measured in | |
293 | packets). The default \fIburst\fR is one-quarter of the \fIrate\fR | |
4e312e69 | 294 | specified on \fB\-\-rate\-limit\fR. |
a9b4a41a | 295 | . |
4e312e69 | 296 | This option takes effect only when \fB\-\-rate\-limit\fR is also specified. |
a9b4a41a | 297 | . |
e3e9370b BP |
298 | .SS "Datapath Options" |
299 | . | |
300 | .IP "\fB\-\-ports=\fIport\fR[\fB,\fIport\fR...]" | |
045b2e5c | 301 | Ordinarily, \fBtest\-openflowd\fR expects the administrator to create |
e3e9370b BP |
302 | the specified \fIdatapath\fR and add ports to it externally with a |
303 | utility such as \fBovs\-dpctl\fR. However, the userspace switch | |
045b2e5c | 304 | datapath is implemented inside \fBtest\-openflowd\fR itself and does |
e3e9370b BP |
305 | not (currently) have any external interface for \fBovs\-dpctl\fR to |
306 | access. As a stopgap measure, this option specifies one or more ports | |
045b2e5c | 307 | to add to the datapath at \fBtest\-openflowd\fR startup time. Multiple |
e3e9370b BP |
308 | ports may be specified as a comma-separated list or by specifying |
309 | \fB\-\-ports\fR multiple times. | |
310 | .IP | |
311 | See \fBINSTALL.userspace\fR for more information about userspace | |
312 | switching. | |
a9b4a41a | 313 | . |
064af421 BP |
314 | .SS "Daemon Options" |
315 | .so lib/daemon.man | |
a9b4a41a | 316 | . |
ac300505 | 317 | .SS "Public Key Infrastructure Options" |
84ee7bcf BP |
318 | .so lib/ssl.man |
319 | .so lib/ssl-bootstrap.man | |
a9b4a41a | 320 | . |
064af421 BP |
321 | .SS "Logging Options" |
322 | .so lib/vlog.man | |
323 | .SS "Other Options" | |
018c0569 | 324 | .so lib/unixctl.man |
064af421 BP |
325 | .so lib/common.man |
326 | .so lib/leak-checker.man | |
a9b4a41a | 327 | . |
018c0569 BP |
328 | .SH "RUNTIME MANAGEMENT COMMANDS" |
329 | \fBovs\-appctl\fR(8) can send commands to a running | |
045b2e5c | 330 | \fBtest\-openflowd\fR process. The currently supported commands are |
018c0569 | 331 | described below. |
045b2e5c BP |
332 | .SS "TEST\-OPENFLOWD COMMANDS" |
333 | These commands are specific to \fBtest\-openflowd\fR. | |
00a250d2 | 334 | .IP "\fBexit\fR" |
045b2e5c | 335 | Causes \fBtest\-openflowd\fR to gracefully terminate. |
7aa697dd | 336 | .so ofproto/ofproto-unixctl.man |
018c0569 BP |
337 | .so lib/vlog-unixctl.man |
338 | . | |
064af421 | 339 | .SH "SEE ALSO" |
a9b4a41a | 340 | . |
064af421 BP |
341 | .BR ovs\-appctl (8), |
342 | .BR ovs\-controller (8), | |
064af421 BP |
343 | .BR ovs\-dpctl (8), |
344 | .BR ovs\-ofctl (8), | |
3b12adda | 345 | .BR ovs\-pki (8) |