1ovs-testcontroller(8) Open vSwitch Manual ovs-testcontroller(8)
2
6 ovs-testcontroller - simple OpenFlow controller for testing
7
9 ovs-testcontroller [options] method [method]...
10
12 ovs-testcontroller is a simple OpenFlow controller that manages any
13 number of switches over the OpenFlow protocol, causing them to function
14 as L2 MAC-learning switches or hubs. It is suitable for initial test‐
15 ing of OpenFlow networks. It is not a necessary or desirable part of a
16 production OpenFlow deployment.
17 ovs-testcontroller controls one or more OpenFlow switches, specified as
19 one or more of the following OpenFlow connection methods:
20 pssl:[port][:host]
22 ptcp:[port][:host]
23 Listens for OpenFlow connections on port. The default
24 port is 6653. By default, connections are allowed from
25 any IPv4 address. Specify host as an IPv4 address or a
26 bracketed IPv6 address (e.g. ptcp:6653:[::1]). On Linux,
27 use %device to designate a scope for IPv6 link-level ad‐
28 dresses, e.g. ptcp:6653:[fe80::1234%eth0]. DNS names can
29 be used if built with unbound library. For pssl, the
30 --private-key,--certificate, and --ca-cert options are
31 mandatory.
32 punix:file
34 Listens for OpenFlow connections on the Unix domain
35 server socket named file.
36 ssl:host[:port]
38 tcp:host[:port]
39 The specified port on the given host, which can be ex‐
40 pressed either as a DNS name (if built with unbound li‐
41 brary) or an IP address in IPv4 or IPv6 address format.
42 Wrap IPv6 addresses in square brackets, e.g.
43 tcp:[::1]:6653. On Linux, use %device to designate a
44 scope for IPv6 link-level addresses, e.g.
45 tcp:[fe80::1234%eth0]:6653. For ssl, the --private-key,
46 --certificate, and --ca-cert options are mandatory.
47 If port is not specified, it defaults to 6653.
49 unix:file
51 On POSIX, a Unix domain server socket named file.
52 On Windows, connect to a local named pipe that is repre‐
54 sented by a file created in the path file to mimic the
55 behavior of a Unix domain socket.
56
58 -n
59 --noflow
60 By default, ovs-testcontroller sets up a flow in each OpenFlow
61 switch whenever it receives a packet whose destination is known
62 due through MAC learning. This option disables flow setup, so
63 that every packet in the network passes through the controller.
64 This option is most useful for debugging. It reduces switching
66 performance, so it should not be used in production.
67 --max-idle=secs|permanent
69 Sets secs as the number of seconds that a flow set up by the
70 controller will remain in the switch's flow table without any
71 matching packets being seen. If permanent is specified, which
72 is not recommended, flows will never expire. The default is 60
73 seconds.
74 This option has no effect when -n (or --noflow) is in use (be‐
76 cause the controller does not set up flows in that case).
77 -H
79 --hub By default, the controller acts as an L2 MAC-learning switch.
80 This option changes its behavior to that of a hub that floods
81 packets on all but the incoming port.
82 If -H (or --hub) and -n (or --noflow) are used together, then
84 the cumulative effect is that every packet passes through the
85 controller and every packet is flooded.
86 This option is most useful for debugging. It reduces switching
88 performance, so it should not be used in production.
89 -w[wildcard_mask]
91 --wildcards[=wildcard_mask]
92 By default, ovs-testcontroller sets up exact-match flows. This
93 option allows it to set up wildcarded flows, which may reduce
94 flow setup latency by causing less traffic to be sent up to the
95 controller.
96 The optional wildcard_mask is an OpenFlow wildcard bitmask in
98 hexadecimal that specifies the fields to wildcard. If no wild‐
99 card_mask is specified, the default value 0x2820F0 is used which
100 specifies L2-only switching and wildcards L3 and L4 fields. An‐
101 other interesting value is 0x2000EC, which specifies L3-only
102 switching and wildcards L2 and L4 fields.
103 This option has no effect when -n (or --noflow) is in use (be‐
105 cause the controller does not set up flows in that case).
106 -N
108 --normal
109 By default, ovs-testcontroller directs packets to a particular
110 port or floods them. This option causes it to direct non-
111 flooded packets to the OpenFlow OFPP_NORMAL port. This allows
112 the switch itself to make decisions about packet destinations.
113 Support for OFPP_NORMAL is optional in OpenFlow, so this option
114 may not well with some non-Open vSwitch switches.
115 --mute Prevents ovs-testcontroller from replying to any OpenFlow mes‐
117 sages sent to it by switches.
118 This option is only for debugging the Open vSwitch implementa‐
120 tion of ``fail open'' mode. It must not be used in production.
121 -q id
123 --queue=id
124 By default, ovs-testcontroller uses the default OpenFlow queue
125 for sending packets and setting up flows. Use one of these op‐
126 tions, supplying id as an OpenFlow queue ID as a decimal number,
127 to instead use that specific queue.
128 This option is incompatible with -N or --normal and with -H or
130 --hub. If more than one is specified then this option takes
131 precedence.
132 This option may be useful for testing or debugging quality of
134 service setups.
135 -Q port-name:queue-id
137 --port-queue port-name:queue-id
139 Configures packets received on the port named port-name (e.g.
140 eth0) to be output on OpenFlow queue ID queue-id (specified as a
141 decimal number). For the specified port, this option overrides
142 the default specified on -q or --queue.
143 This option may be specified any number of times with different
145 port-name arguments.
146 This option is incompatible with -N or --normal and with -H or
148 --hub. If more than one is specified then this option takes
149 precedence.
150 This option may be useful for testing or debugging quality of
152 service setups.
153 --with-flows file
155 When a switch connects, push the flow entries as described in
156 file. Each line in file is a flow entry in the format described
157 for the add-flows command in the Flow Syntax section of the
158 ovs-ofctl(8) man page.
159 Use this option more than once to add flows from multiple files.
161 Public Key Infrastructure Options
163 -p privkey.pem
164 --private-key=privkey.pem
165 Specifies a PEM file containing the private key used as
166 ovs-testcontroller's identity for outgoing SSL connections.
167 -c cert.pem
169 --certificate=cert.pem
170 Specifies a PEM file containing a certificate that certifies the
171 private key specified on -p or --private-key to be trustworthy.
172 The certificate must be signed by the certificate authority (CA)
173 that the peer in SSL connections will use to verify it.
174 -C cacert.pem
176 --ca-cert=cacert.pem
177 Specifies a PEM file containing the CA certificate that
178 ovs-testcontroller should use to verify certificates presented
179 to it by SSL peers. (This may be the same certificate that SSL
180 peers use to verify the certificate specified on -c or --cer‐
181 tificate, or it may be a different one, depending on the PKI de‐
182 sign in use.)
183 -C none
185 --ca-cert=none
186 Disables verification of certificates presented by SSL peers.
187 This introduces a security risk, because it means that certifi‐
188 cates cannot be verified to be those of known trusted hosts.
189 --peer-ca-cert=peer-cacert.pem
191 Specifies a PEM file that contains one or more additional cer‐
192 tificates to send to SSL peers. peer-cacert.pem should be the
193 CA certificate used to sign ovs-testcontroller's own certifi‐
194 cate, that is, the certificate specified on -c or --certificate.
195 If ovs-testcontroller's certificate is self-signed, then --cer‐
196 tificate and --peer-ca-cert should specify the same file.
197 This option is not useful in normal operation, because the SSL
199 peer must already have the CA certificate for the peer to have
200 any confidence in ovs-testcontroller's identity. However, this
201 offers a way for a new installation to bootstrap the CA certifi‐
202 cate on its first SSL connection.
203 Daemon Options
205 The following options are valid on POSIX based platforms.
206 --pidfile[=pidfile]
208 Causes a file (by default, ovs-testcontroller.pid) to be created
209 indicating the PID of the running process. If the pidfile argu‐
210 ment is not specified, or if it does not begin with /, then it
211 is created in /var/run/openvswitch.
212 If --pidfile is not specified, no pidfile is created.
214 --overwrite-pidfile
216 By default, when --pidfile is specified and the specified pid‐
217 file already exists and is locked by a running process,
218 ovs-testcontroller refuses to start. Specify --overwrite-pid‐
219 file to cause it to instead overwrite the pidfile.
220 When --pidfile is not specified, this option has no effect.
222 --detach
224 Runs ovs-testcontroller as a background process. The process
225 forks, and in the child it starts a new session, closes the
226 standard file descriptors (which has the side effect of dis‐
227 abling logging to the console), and changes its current direc‐
228 tory to the root (unless --no-chdir is specified). After the
229 child completes its initialization, the parent exits.
230 --monitor
232 Creates an additional process to monitor the ovs-testcontroller
233 daemon. If the daemon dies due to a signal that indicates a
234 programming error (SIGABRT, SIGALRM, SIGBUS, SIGFPE, SIGILL,
235 SIGPIPE, SIGSEGV, SIGXCPU, or SIGXFSZ) then the monitor process
236 starts a new copy of it. If the daemon dies or exits for an‐
237 other reason, the monitor process exits.
238 This option is normally used with --detach, but it also func‐
240 tions without it.
241 --no-chdir
243 By default, when --detach is specified, ovs-testcontroller
244 changes its current working directory to the root directory af‐
245 ter it detaches. Otherwise, invoking ovs-testcontroller from a
246 carelessly chosen directory would prevent the administrator from
247 unmounting the file system that holds that directory.
248 Specifying --no-chdir suppresses this behavior, preventing
250 ovs-testcontroller from changing its current working directory.
251 This may be useful for collecting core files, since it is common
252 behavior to write core dumps into the current working directory
253 and the root directory is not a good directory to use.
254 This option has no effect when --detach is not specified.
256 --no-self-confinement
258 By default daemon will try to self-confine itself to work with
259 files under well-known directories determined during build. It
260 is better to stick with this default behavior and not to use
261 this flag unless some other Access Control is used to confine
262 daemon. Note that in contrast to other access control implemen‐
263 tations that are typically enforced from kernel-space (e.g. DAC
264 or MAC), self-confinement is imposed from the user-space daemon
265 itself and hence should not be considered as a full confinement
266 strategy, but instead should be viewed as an additional layer of
267 security.
268 --user Causes ovs-testcontroller to run as a different user specified
270 in "user:group", thus dropping most of the root privileges.
271 Short forms "user" and ":group" are also allowed, with current
272 user or group are assumed respectively. Only daemons started by
273 the root user accepts this argument.
274 On Linux, daemons will be granted CAP_IPC_LOCK and
276 CAP_NET_BIND_SERVICES before dropping root privileges. Daemons
277 that interact with a datapath, such as ovs-vswitchd, will be
278 granted three additional capabilities, namely CAP_NET_ADMIN,
279 CAP_NET_BROADCAST and CAP_NET_RAW. The capability change will
280 apply even if the new user is root.
281 On Windows, this option is not currently supported. For security
283 reasons, specifying this option will cause the daemon process
284 not to start.
285 -v[spec]
287 --verbose=[spec]
288 Sets logging levels. Without any spec, sets the log level for
289 every module and destination to dbg. Otherwise, spec is a list
290 of words separated by spaces or commas or colons, up to one from
291 each category below:
292 • A valid module name, as displayed by the vlog/list com‐
294 mand on ovs-appctl(8), limits the log level change to the
295 specified module.
296 • syslog, console, or file, to limit the log level change
298 to only to the system log, to the console, or to a file,
299 respectively. (If --detach is specified, ovs-testcon‐
300 troller closes its standard file descriptors, so logging
301 to the console will have no effect.)
302 On Windows platform, syslog is accepted as a word and is
304 only useful along with the --syslog-target option (the
305 word has no effect otherwise).
306 • off, emer, err, warn, info, or dbg, to control the log
308 level. Messages of the given severity or higher will be
309 logged, and messages of lower severity will be filtered
310 out. off filters out all messages. See ovs-appctl(8)
311 for a definition of each log level.
312 Case is not significant within spec.
314 Regardless of the log levels set for file, logging to a file
316 will not take place unless --log-file is also specified (see be‐
317 low).
318 For compatibility with older versions of OVS, any is accepted as
320 a word but has no effect.
321 -v
323 --verbose
324 Sets the maximum logging verbosity level, equivalent to --ver‐
325 bose=dbg.
326 -vPATTERN:destination:pattern
328 --verbose=PATTERN:destination:pattern
329 Sets the log pattern for destination to pattern. Refer to
330 ovs-appctl(8) for a description of the valid syntax for pattern.
331 -vFACILITY:facility
333 --verbose=FACILITY:facility
334 Sets the RFC5424 facility of the log message. facility can be
335 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
336 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
337 local3, local4, local5, local6 or local7. If this option is not
338 specified, daemon is used as the default for the local system
339 syslog and local0 is used while sending a message to the target
340 provided via the --syslog-target option.
341 --log-file[=file]
343 Enables logging to a file. If file is specified, then it is
344 used as the exact name for the log file. The default log file
345 name used if file is omitted is /var/log/openvswitch/ovs-test‐
346 controller.log.
347 --syslog-target=host:port
349 Send syslog messages to UDP port on host, in addition to the
350 system syslog. The host must be a numerical IP address, not a
351 hostname.
352 --syslog-method=method
354 Specify method how syslog messages should be sent to syslog dae‐
355 mon. Following forms are supported:
356 • libc, use libc syslog() function. Downside of using this
358 options is that libc adds fixed prefix to every message
359 before it is actually sent to the syslog daemon over
360 /dev/log UNIX domain socket.
361 • unix:file, use UNIX domain socket directly. It is possi‐
363 ble to specify arbitrary message format with this option.
364 However, rsyslogd 8.9 and older versions use hard coded
365 parser function anyway that limits UNIX domain socket
366 use. If you want to use arbitrary message format with
367 older rsyslogd versions, then use UDP socket to localhost
368 IP address instead.
369 • udp:ip:port, use UDP socket. With this method it is pos‐
371 sible to use arbitrary message format also with older
372 rsyslogd. When sending syslog messages over UDP socket
373 extra precaution needs to be taken into account, for ex‐
374 ample, syslog daemon needs to be configured to listen on
375 the specified UDP port, accidental iptables rules could
376 be interfering with local syslog traffic and there are
377 some security considerations that apply to UDP sockets,
378 but do not apply to UNIX domain sockets.
379 • null, discards all messages logged to syslog.
381 The default is taken from the OVS_SYSLOG_METHOD environment
383 variable; if it is unset, the default is libc.
384 --unixctl=socket
386 Sets the name of the control socket on which ovs-testcontroller
387 listens for runtime management commands (see RUNTIME MANAGEMENT
388 COMMANDS, below). If socket does not begin with /, it is inter‐
389 preted as relative to /var/run/openvswitch. If --unixctl is not
390 used at all, the default socket is /var/run/open‐
391 vswitch/ovs-testcontroller.pid.ctl, where pid is ovs-testcon‐
392 troller's process ID.
393 On Windows a local named pipe is used to listen for runtime man‐
395 agement commands. A file is created in the absolute path as
396 pointed by socket or if --unixctl is not used at all, a file is
397 created as ovs-testcontroller.ctl in the configured OVS_RUNDIR
398 directory. The file exists just to mimic the behavior of a Unix
399 domain socket.
400 Specifying none for socket disables the control socket feature.
402 -h
404 --help Prints a brief help message to the console.
405 -V
407 --version
408 Prints version information to the console.
409 -O [version[,version]...]
411 --protocols=[version[,version]...]
412 Sets the OpenFlow protocol versions that are allowed when estab‐
413 lishing an OpenFlow session.
414 These protocol versions are enabled by default:
416 • OpenFlow10, for OpenFlow 1.0.
418 The following protocol versions are generally supported, but for com‐
419 patibility with older versions of Open vSwitch they are not enabled by
420 default:
421 • OpenFlow11, for OpenFlow 1.1.
423 • OpenFlow12, for OpenFlow 1.2.
425 • OpenFlow13, for OpenFlow 1.3.
427 • OpenFlow14, for OpenFlow 1.4.
429 • OpenFlow15, for OpenFlow 1.5.
431
433 To bind locally to port 6653 (the default) and wait for incoming con‐
434 nections from OpenFlow switches:
435 % ovs-testcontroller ptcp:
437
439 Configuring a Citrix XenServer to connect to a particular controller
440 only points the remote OVSDB management connection to that controller.
441 It does not also configure OpenFlow connections, because the manager is
442 expected to do that over the management protocol. ovs-testcontroller
443 is not an Open vSwitch manager and does not know how to do that.
444 As a stopgap workaround, ovs-vsctl can wait for an OVSDB connection and
446 set the controller, e.g.:
447 % ovs-vsctl -t0 --db=pssl: --certificate=cert.pem --ca-cert=none
449 --private-key=privkey.pem --peer-ca-cert=cacert.pem set-con‐
450 troller ssl:ip
451
453 ovs-appctl(8), ovs-ofctl(8), ovs-dpctl(8)
454Open vSwitch 2.15.0 ovs-testcontroller(8)