--strict
Uses strict matching when running flow modification
commands.
--names
--no-names
Every OpenFlow port has a name and a number, and every
OpenFlow flow table has a number and sometimes a name. By
default, ovs-ofctl commands accept both port and table
names and numbers, and they display port and table names
if ovs-ofctl is running on an interactive console, numbers
otherwise. With --names, ovs-ofctl commands both accept
and display port and table names; with --no-names,
commands neither accept nor display port and table names.
If a port or table name contains special characters or
might be confused with a keyword within a flow, it may be
enclosed in double quotes (escaped from the shell). If
necessary, JSON-style escape sequences may be used inside
quotes, as specified in RFC 7159. When it displays port
and table names, ovs-ofctl quotes any name that does not
start with a letter followed by letters or digits.
Open vSwitch added support for port names and these
options. Open vSwitch 2.10 added support for table names.
Earlier versions always behaved as if --no-names were
specified.
Open vSwitch does not place its own limit on the length of
port names, but OpenFlow limits port names to 15 bytes.
Because ovs-ofctl uses OpenFlow to retrieve the mapping
between port names and numbers, names longer than this
limit will be truncated for both display and acceptance.
Truncation can also cause long names that are different to
appear to be the same; when a switch has two ports with
the same (truncated) name, ovs-ofctl refuses to display or
accept the name, using the number instead.
OpenFlow and Open vSwitch limit table names to 32 bytes.
--stats
--no-stats
The dump-flows command by default, or with --stats,
includes flow duration, packet and byte counts, and idle
and hard age in its output. With --no-stats, it omits all
of these, as well as cookie values and table IDs if they
are zero.
--read-only
Do not execute read/write commands.
--bundle
Execute flow mods as an OpenFlow 1.4 atomic bundle
transaction.
• Within a bundle, all flow mods are processed in the
order they appear and as a single atomic
transaction, meaning that if one of them fails, the
whole transaction fails and none of the changes are
made to the switch's flow table, and that each
given datapath packet traversing the OpenFlow
tables sees the flow tables either as before the
transaction, or after all the flow mods in the
bundle have been successfully applied.
• The beginning and the end of the flow table
modification commands in a bundle are delimited
with OpenFlow 1.4 bundle control messages, which
makes it possible to stream the included commands
without explicit OpenFlow barriers, which are
otherwise used after each flow table modification
command. This may make large modifications execute
faster as a bundle.
• Bundles require OpenFlow 1.4 or higher. An
explicit -O OpenFlow14 option is not needed, but
you may need to enable OpenFlow 1.4 support for OVS
by setting the OVSDB protocols column in the bridge
table.
-O [version[,version]...]
--protocols=[version[,version]...]
Sets the OpenFlow protocol versions that are allowed when
establishing an OpenFlow session.
These protocol versions are enabled by default:
• OpenFlow10, for OpenFlow 1.0.
The following protocol versions are generally supported, but for
compatibility with older versions of Open vSwitch they are not
enabled by default:
• OpenFlow11, for OpenFlow 1.1.
• OpenFlow12, for OpenFlow 1.2.
• OpenFlow13, for OpenFlow 1.3.
• OpenFlow14, for OpenFlow 1.4.
• OpenFlow15, for OpenFlow 1.5.
-F format[,format...]
--flow-format=format[,format...]
ovs-ofctl supports the following individual flow formats,
any number of which may be listed as format:
OpenFlow10-table_id
This is the standard OpenFlow 1.0 flow format. All
OpenFlow switches and all versions of Open vSwitch
support this flow format.
OpenFlow10+table_id
This is the standard OpenFlow 1.0 flow format plus
a Nicira extension that allows ovs-ofctl to specify
the flow table in which a particular flow should be
placed. Open vSwitch 1.2 and later supports this
flow format.
NXM-table_id (Nicira Extended Match)
This Nicira extension to OpenFlow is flexible and
extensible. It supports all of the Nicira flow
extensions, such as tun_id and registers. Open
vSwitch 1.1 and later supports this flow format.
NXM+table_id (Nicira Extended Match)
This combines Nicira Extended match with the
ability to place a flow in a specific table. Open
vSwitch 1.2 and later supports this flow format.
OXM-OpenFlow12
OXM-OpenFlow13
OXM-OpenFlow14
OXM-OpenFlow15
These are the standard OXM (OpenFlow Extensible
Match) flow format in OpenFlow 1.2 and later.
ovs-ofctl also supports the following abbreviations for
collections of flow formats:
any Any supported flow format.
OpenFlow10
OpenFlow10-table_id or OpenFlow10+table_id.
NXM NXM-table_id or NXM+table_id.
OXM OXM-OpenFlow12, OXM-OpenFlow13, or OXM-OpenFlow14.
For commands that modify the flow table, ovs-ofctl by
default negotiates the most widely supported flow format
that supports the flows being added. For commands that
query the flow table, ovs-ofctl by default uses the most
advanced format supported by the switch.
This option, where format is a comma-separated list of one
or more of the formats listed above, limits ovs-ofctl's
choice of flow format. If a command cannot work as
requested using one of the specified flow formats,
ovs-ofctl will report a fatal error.
-P format
--packet-in-format=format
ovs-ofctl supports the following ``packet-in'' formats, in
order of increasing capability:
standard
This uses the OFPT_PACKET_IN message, the standard
``packet-in'' message for any given OpenFlow
version. Every OpenFlow switch that supports a
given OpenFlow version supports this format.
nxt_packet_in
This uses the NXT_PACKET_IN message, which adds
many of the capabilities of the OpenFlow 1.1 and
later ``packet-in'' messages before those OpenFlow
versions were available in Open vSwitch. Open
vSwitch 1.1 and later support this format. Only
Open vSwitch 2.6 and later, however, support it for
OpenFlow 1.1 and later (but there is little reason
to use it with those versions of OpenFlow).
nxt_packet_in2
This uses the NXT_PACKET_IN2 message, which is
extensible and should avoid the need to define new
formats later. In particular, this format supports
passing arbitrary user-provided data to a
controller using the userdata option on the
controller action. Open vSwitch 2.6 and later
support this format.
Without this option, ovs-ofctl prefers nxt_packet_in2 if
the switch supports it. Otherwise, if OpenFlow 1.0 is in
use, ovs-ofctl prefers nxt_packet_in if the switch
supports it. Otherwise, ovs-ofctl falls back to the
standard packet-in format. When this option is specified,
ovs-ofctl insists on the selected format. If the switch
does not support the requested format, ovs-ofctl will
report a fatal error.
Before version 2.6, Open vSwitch called standard format
openflow10 and nxt_packet_in format nxm, and ovs-ofctl
still accepts these names as synonyms. (The name
openflow10 was a misnomer because this format actually
varies from one OpenFlow version to another; it is not
consistently OpenFlow 1.0 format. Similarly, when
nxt_packet_in2 was introduced, the name nxm became
confusing because it also uses OXM/NXM.)
This option affects only the monitor command.
--timestamp
Print a timestamp before each received packet. This
option only affects the monitor, snoop, and ofp-parse-pcap
commands.
-m
--more Increases the verbosity of OpenFlow messages printed and
logged by ovs-ofctl commands. Specify this option more
than once to increase verbosity further.
--sort[=field]
--rsort[=field]
Display output sorted by flow field in ascending (--sort)
or descending (--rsort) order, where field is any of the
fields that are allowed for matching or priority to sort
by priority. When field is omitted, the output is sorted
by priority. Specify these options multiple times to sort
by multiple fields.
Any given flow will not necessarily specify a value for a
given field. This requires special treatement:
• A flow that does not specify any part of a field
that is used for sorting is sorted after all the
flows that do specify the field. For example,
--sort=tcp_src will sort all the flows that specify
a TCP source port in ascending order, followed by
the flows that do not specify a TCP source port at
all.
• A flow that only specifies some bits in a field is
sorted as if the wildcarded bits were zero. For
example, --sort=nw_src would sort a flow that
specifies nw_src=192.168.0.0/24 the same as
nw_src=192.168.0.0.
These options currently affect only dump-flows output.
Daemon Options
The following options are valid on POSIX based platforms.
--pidfile[=pidfile]
Causes a file (by default, ovs-ofctl.pid) to be created
indicating the PID of the running process. If the pidfile
argument is not specified, or if it does not begin with /,
then it is created in /usr/local/var/run/openvswitch.
If --pidfile is not specified, no pidfile is created.
--overwrite-pidfile
By default, when --pidfile is specified and the specified
pidfile already exists and is locked by a running process,
ovs-ofctl refuses to start. Specify --overwrite-pidfile
to cause it to instead overwrite the pidfile.
When --pidfile is not specified, this option has no
effect.
--detach
Runs ovs-ofctl as a background process. The process
forks, and in the child it starts a new session, closes
the standard file descriptors (which has the side effect
of disabling logging to the console), and changes its
current directory to the root (unless --no-chdir is
specified). After the child completes its initialization,
the parent exits. ovs-ofctl detaches only when executing
the monitor or snoop commands.
--monitor
Creates an additional process to monitor the ovs-ofctl
daemon. If the daemon dies due to a signal that indicates
a programming error (SIGABRT, SIGALRM, SIGBUS, SIGFPE,
SIGILL, SIGPIPE, SIGSEGV, SIGXCPU, or SIGXFSZ) then the
monitor process starts a new copy of it. If the daemon
dies or exits for another reason, the monitor process
exits.
This option is normally used with --detach, but it also
functions without it.
--no-chdir
By default, when --detach is specified, ovs-ofctl changes
its current working directory to the root directory after
it detaches. Otherwise, invoking ovs-ofctl from a
carelessly chosen directory would prevent the
administrator from unmounting the file system that holds
that directory.
Specifying --no-chdir suppresses this behavior, preventing
ovs-ofctl from changing its current working directory.
This may be useful for collecting core files, since it is
common behavior to write core dumps into the current
working directory and the root directory is not a good
directory to use.
This option has no effect when --detach is not specified.
--no-self-confinement
By default daemon will try to self-confine itself to work
with files under well-known directories determined during
build. It is better to stick with this default behavior
and not to use this flag unless some other Access Control
is used to confine daemon. Note that in contrast to other
access control implementations that are typically enforced
from kernel-space (e.g. DAC or MAC), self-confinement is
imposed from the user-space daemon itself and hence should
not be considered as a full confinement strategy, but
instead should be viewed as an additional layer of
security.
--user Causes ovs-ofctl to run as a different user specified in
"user:group", thus dropping most of the root privileges.
Short forms "user" and ":group" are also allowed, with
current user or group are assumed respectively. Only
daemons started by the root user accepts this argument.
On Linux, daemons will be granted CAP_IPC_LOCK and
CAP_NET_BIND_SERVICES before dropping root privileges.
Daemons that interact with a datapath, such as
ovs-vswitchd, will be granted three additional
capabilities, namely CAP_NET_ADMIN, CAP_NET_BROADCAST and
CAP_NET_RAW. The capability change will apply even if the
new user is root.
On Windows, this option is not currently supported. For
security reasons, specifying this option will cause the
daemon process not to start.
--unixctl=socket
Sets the name of the control socket on which ovs-ofctl
listens for runtime management commands (see RUNTIME
MANAGEMENT COMMANDS, below). If socket does not begin
with /, it is interpreted as relative to
/usr/local/var/run/openvswitch. If --unixctl is not used
at all, the default socket is
/usr/local/var/run/openvswitch/ovs-ofctl.pid.ctl, where
pid is ovs-ofctl's process ID.
On Windows a local named pipe is used to listen for
runtime management commands. A file is created in the
absolute path as pointed by socket or if --unixctl is not
used at all, a file is created as ovs-ofctl.ctl in the
configured OVS_RUNDIR directory. The file exists just to
mimic the behavior of a Unix domain socket.
Specifying none for socket disables the control socket
feature.
Public Key Infrastructure Options
-p privkey.pem
--private-key=privkey.pem
Specifies a PEM file containing the private key used as
ovs-ofctl's identity for outgoing SSL connections.
-c cert.pem
--certificate=cert.pem
Specifies a PEM file containing a certificate that
certifies the private key specified on -p or --private-key
to be trustworthy. The certificate must be signed by the
certificate authority (CA) that the peer in SSL
connections will use to verify it.
-C cacert.pem
--ca-cert=cacert.pem
Specifies a PEM file containing the CA certificate that
ovs-ofctl should use to verify certificates presented to
it by SSL peers. (This may be the same certificate that
SSL peers use to verify the certificate specified on -c or
--certificate, or it may be a different one, depending on
the PKI design in use.)
-C none
--ca-cert=none
Disables verification of certificates presented by SSL
peers. This introduces a security risk, because it means
that certificates cannot be verified to be those of known
trusted hosts.
-v[spec]
--verbose=[spec]
Sets logging levels. Without any spec, sets the log level
for every module and destination to dbg. Otherwise, spec
is a list of words separated by spaces or commas or
colons, up to one from each category below:
• A valid module name, as displayed by the vlog/list
command on ovs-appctl(8), limits the log level
change to the specified module.
• syslog, console, or file, to limit the log level
change to only to the system log, to the console,
or to a file, respectively. (If --detach is
specified, ovs-ofctl closes its standard file
descriptors, so logging to the console will have no
effect.)
On Windows platform, syslog is accepted as a word
and is only useful along with the --syslog-target
option (the word has no effect otherwise).
• off, emer, err, warn, info, or dbg, to control the
log level. Messages of the given severity or
higher will be logged, and messages of lower
severity will be filtered out. off filters out all
messages. See ovs-appctl(8) for a definition of
each log level.
Case is not significant within spec.
Regardless of the log levels set for file, logging to a
file will not take place unless --log-file is also
specified (see below).
For compatibility with older versions of OVS, any is
accepted as a word but has no effect.
-v
--verbose
Sets the maximum logging verbosity level, equivalent to
--verbose=dbg.
-vPATTERN:destination:pattern
--verbose=PATTERN:destination:pattern
Sets the log pattern for destination to pattern. Refer to
ovs-appctl(8) for a description of the valid syntax for
pattern.
-vFACILITY:facility
--verbose=FACILITY:facility
Sets the RFC5424 facility of the log message. facility can
be one of kern, user, mail, daemon, auth, syslog, lpr,
news, uucp, clock, ftp, ntp, audit, alert, clock2, local0,
local1, local2, local3, local4, local5, local6 or local7.
If this option is not specified, daemon is used as the
default for the local system syslog and local0 is used
while sending a message to the target provided via the
--syslog-target option.
--log-file[=file]
Enables logging to a file. If file is specified, then it
is used as the exact name for the log file. The default
log file name used if file is omitted is
/usr/local/var/log/openvswitch/ovs-ofctl.log.
--syslog-target=host:port
Send syslog messages to UDP port on host, in addition to
the system syslog. The host must be a numerical IP
address, not a hostname.
--syslog-method=method
Specify method how syslog messages should be sent to
syslog daemon. Following forms are supported:
• libc, use libc syslog() function. Downside of
using this options is that libc adds fixed prefix
to every message before it is actually sent to the
syslog daemon over /dev/log UNIX domain socket.
• unix:file, use UNIX domain socket directly. It is
possible to specify arbitrary message format with
this option. However, rsyslogd 8.9 and older
versions use hard coded parser function anyway that
limits UNIX domain socket use. If you want to use
arbitrary message format with older rsyslogd
versions, then use UDP socket to localhost IP
address instead.
• udp:ip:port, use UDP socket. With this method it
is possible to use arbitrary message format also
with older rsyslogd. When sending syslog messages
over UDP socket extra precaution needs to be taken
into account, for example, syslog daemon needs to
be configured to listen on the specified UDP port,
accidental iptables rules could be interfering with
local syslog traffic and there are some security
considerations that apply to UDP sockets, but do
not apply to UNIX domain sockets.
• null, discards all messages logged to syslog.
The default is taken from the OVS_SYSLOG_METHOD
environment variable; if it is unset, the default is libc.
--color[=when]
Colorize the output (for some commands); when can be
never, always, or auto (the default).
Only some commands support output coloring. Color names
and default colors may change in future releases.
The environment variable OVS_COLORS can be used to specify
user-defined colors and other attributes used to highlight
various parts of the output. If set, its value is a colon-
separated list of capabilities that defaults to
ac:01;31:dr=34:le=31:pm=36:pr=35:sp=33:vl=32. Supported
capabilities were initially designed for coloring flows
from ovs-ofctl dump-flows switch command, and they are as
follows.
ac=01;31
SGR substring for actions= keyword in a
flow. The default is a bold red text
foreground.
dr=34 SGR substring for drop keyword. The default
is a dark blue text foreground.
le=31 SGR substring for learn= keyword in a flow.
The default is a red text foreground.
pm=36 SGR substring for flow match attribute
names. The default is a cyan text
foreground.
pr=35 SGR substring for keywords in a flow that
are followed by arguments inside
parenthesis. The default is a magenta text
foreground.
sp=33 SGR substring for some special keywords in a
flow, notably: table=, priority=, load:,
output:, move:, group:, CONTROLLER:,
set_field:, resubmit:, exit. The default is
a yellow text foreground.
vl=32 SGR substring for a lone flow match
attribute with no field name. The default
is a green text foreground.
See the Select Graphic Rendition (SGR) section in the
documentation of the text terminal that is used for
permitted values and their meaning as character
attributes.
-h
--help Prints a brief help message to the console.
-V
--version
Prints version information to the console.
