1ovs-testcontroller(8)         Open vSwitch Manual        ovs-testcontroller(8)
2
3
4

NAME

6       ovs-testcontroller - simple OpenFlow controller for testing
7

SYNOPSIS

9       ovs-testcontroller [options] method [method]...
10

DESCRIPTION

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
18       ovs-testcontroller controls one or more OpenFlow switches, specified as
19       one or more of the following OpenFlow connection methods:
20
21              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
33              punix:file
34                     Listens for  OpenFlow  connections  on  the  Unix  domain
35                     server socket named file.
36
37              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
48                     If port is not specified, it defaults to 6653.
49
50              unix:file
51                     On POSIX, a Unix domain server socket named file.
52
53                     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

OPTIONS

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
65              This  option is most useful for debugging.  It reduces switching
66              performance, so it should not be used in production.
67
68       --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
75              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
78       -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
83              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
87              This  option is most useful for debugging.  It reduces switching
88              performance, so it should not be used in production.
89
90       -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
97              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
104              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
107       -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
116       --mute Prevents ovs-testcontroller from replying to any  OpenFlow  mes‐
117              sages sent to it by switches.
118
119              This  option  is only for debugging the Open vSwitch implementa‐
120              tion of ``fail open'' mode.  It must not be used in production.
121
122       -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
129              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
133              This  option  may  be useful for testing or debugging quality of
134              service setups.
135
136       -Q port-name:queue-id
137
138       --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
144              This  option may be specified any number of times with different
145              port-name arguments.
146
147              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
151              This option may be useful for testing or  debugging  quality  of
152              service setups.
153
154       --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
160              Use this option more than once to add flows from multiple files.
161
162   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
168       -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
175       -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
184       -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
190       --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
198              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
204   Daemon Options
205       The following options are valid on POSIX based platforms.
206
207       --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
213              If --pidfile is not specified, no pidfile is created.
214
215       --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
221              When --pidfile is not specified, this option has no effect.
222
223       --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
231       --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
239              This option is normally used with --detach, but  it  also  func‐
240              tions without it.
241
242       --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
249              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
255              This option has no effect when --detach is not specified.
256
257       --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
269       --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
275              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
282              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
286       -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
293              •      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
297syslog, 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
303                     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
307off, 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
313              Case is not significant within spec.
314
315              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
319              For compatibility with older versions of OVS, any is accepted as
320              a word but has no effect.
321
322       -v
323       --verbose
324              Sets  the  maximum logging verbosity level, equivalent to --ver‐
325              bose=dbg.
326
327       -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
332       -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
342       --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
348       --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
353       --syslog-method=method
354              Specify method how syslog messages should be sent to syslog dae‐
355              mon.  Following forms are supported:
356
357libc, 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
362unix: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
370udp: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
380null, discards all messages logged to syslog.
381
382              The default is  taken  from  the  OVS_SYSLOG_METHOD  environment
383              variable; if it is unset, the default is libc.
384
385       --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
394              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
401              Specifying none for socket disables the control socket feature.
402
403       -h
404       --help Prints a brief help message to the console.
405
406       -V
407       --version
408              Prints version information to the console.
409
410       -O [version[,version]...]
411       --protocols=[version[,version]...]
412              Sets the OpenFlow protocol versions that are allowed when estab‐
413              lishing an OpenFlow session.
414
415              These protocol versions are enabled by default:
416
417OpenFlow10, 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
422OpenFlow11, for OpenFlow 1.1.
423
424OpenFlow12, for OpenFlow 1.2.
425
426OpenFlow13, for OpenFlow 1.3.
427
428OpenFlow14, for OpenFlow 1.4.
429
430OpenFlow15, for OpenFlow 1.5.
431

EXAMPLES

433       To  bind  locally to port 6653 (the default) and wait for incoming con‐
434       nections from OpenFlow switches:
435
436              % ovs-testcontroller ptcp:
437

SEE ALSO

439       ovs-appctl(8), ovs-ofctl(8), ovs-dpctl(8)
440
441
442
443Open vSwitch                         3.2.0               ovs-testcontroller(8)
Impressum