The specified TCP \fIport\fR (default: 975) on the given remote
\fIhost\fR.
+.TP
+\fBunix:\fIfile\fR
+The Unix domain server socket named \fIfile\fR.
+
.SH COMMANDS
With the \fBdpctl\fR program, datapaths running in the kernel can be
existing datapath.
.PP
-The following commands can be used regardless of the connection method.
+The following commands can be apply to OpenFlow switches regardless of
+the connection method.
.TP
\fBshow \fIswitch\fR
Prints to the console information on datapath \fIswitch\fR including
information on its flow tables and ports.
+.TP
+\fBstatus \fIswitch\fR [\fIkey\fR]
+Prints to the console a series of key-value pairs that report the
+status of \fIswitch\fR. If \fIkey\fR is specified, only the key-value
+pairs whose key names begin with \fIkey\fR are printed. If \fIkey\fR is
+omitted, all key-value pairs are printed.
+
+(In the OpenFlow reference implementation, the \fBstatus\fR command is
+implemented in \fBsecchan\fR(8), not in the kernel module, so the
+\fBnl:\fIdp_idx\fR connection method should not be used with this
+command. Instead, specify \fB-l\fR or \fB--listen\fR on the
+\fBsecchan\fR command line and tell \fBdpctl\fR to use the connection
+method specified there.)
+
.TP
\fBdump-tables \fIswitch\fR
Prints to the console statistics for each of the flow tables used by
Prints to the console statistics for each of the network devices
associated with datapath \fIswitch\fR.
+.TP
+\fBmod-port \fIswitch\fR \fInetdev\fR \fIaction\fR
+Modify characteristics of an interface monitored by \fIswitch\fR.
+\fInetdev\fR can be referred to by its OpenFlow assigned port number or
+the device name, e.g. \fBeth0\fR. The \fIaction\fR may be any one of the
+following:
+
+.RS
+.IP \fBup\fR
+Enables the interface. This is equivalent to ``ifconfig up'' on a Unix
+system.
+
+.IP \fBdown\fR
+Disables the interface. This is equivalent to ``ifconfig down'' on a Unix
+system.
+
+.IP \fBflood\fR
+When a \fIflood\fR action is specified, traffic will be sent out this
+interface. This is the default posture for monitored ports.
+
+.IP \fBnoflood\fR
+When a \fIflood\fR action is specified, traffic will not be sent out
+this interface. This is primarily useful to prevent loops when a
+spanning tree protocol is not in use.
+
+.RE
+
.TP
\fBdump-flows \fIswitch \fR[\fIflows\fR]
Prints to the console all flow entries in datapath \fIswitch\fR's
tables are removed. See \fBFLOW SYNTAX\fR, below, for the syntax of
\fIflows\fR.
+.PP
+The following commands can be used regardless of the connection
+method. They apply to OpenFlow switches and controllers.
+
.TP
-\fBping \fIswitch \fR[\fIn\fR]
-Sends a series of 10 echo request packets to \fIswitch\fR and times
+\fBprobe \fIvconn\fR
+Connects to \fIvconn\fR and sends a single OpenFlow echo-request
+packet and waits for the response. With the \fB-t\fR or
+\fB--timeout\fR option, this command can test whether an OpenFlow
+switch or controller is up and running.
+
+.TP
+\fBping \fIvconn \fR[\fIn\fR]
+Sends a series of 10 echo request packets to \fIvconn\fR and times
each reply. The echo request packets consist of an OpenFlow header
plus \fIn\fR bytes (default: 64) of randomly generated payload. This
measures the latency of individual requests.
.TP
-\fBbenchmark \fIswitch n count\fR
+\fBbenchmark \fIvconn n count\fR
Sends \fIcount\fR echo request packets that each consist of an
OpenFlow header plus \fIn\fR bytes of payload and waits for each
response. Reports the total time required. This is a measure of the
-maximum bandwidth to \fIswitch\fR for round-trips of \fIn\fR-byte
+maximum bandwidth to \fIvconn\fR for round-trips of \fIn\fR-byte
messages.
.SH "FLOW SYNTAX"
decimal or as a hexadecimal number prefixed by \fB0x\fR,
e.g. \fB0x0806\fR to match ARP packets.
-.IP \fBnw_src=\fIip\fR
+.IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR]
Matches IPv4 source address \fIip\fR, which should be specified as an
IP address or host name, e.g. \fB192.168.1.1\fR or
-\fBwww.example.com\fR.
+\fBwww.example.com\fR. The optional \fInetmask\fR allows matching
+only on an IPv4 address prefix. It may be specified as a dotted quad
+(e.g. \fB192.168.1.0/255.255.255.0\fR) or as a count of bits
+(e.g. \fB192.168.1.0/24\fR).
-.IP \fBnw_dst=\fInw_dst\fR
+.IP \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR]
Matches IPv4 destination address \fIip\fR.
.IP \fBnw_proto=\fIproto\fR
.IP \fBtp_dst=\fIport\fR
Matches UDP or TCP destination port \fIport\fR.
+.PP
+The following shorthand notations are also available:
+
+.IP \fBip\fR
+Same as \fBdl_type=0x0800\fR.
+
+.IP \fBicmp\fR
+Same as \fBdl_type=0x0800,nw_proto=1\fR.
+
+.IP \fBtcp\fR
+Same as \fBdl_type=0x0800,nw_proto=6\fR.
+
+.IP \fBudp\fR
+Same as \fBdl_type=0x0800,nw_proto=17\fR.
+
+.IP \fBarp\fR
+Same as \fBdl_type=0x0806\fR.
+
.PP
The \fBadd-flow\fR and \fBadd-flows\fR commands require an additional field:
not yet expose to the user.)
.PP
-The \fBadd-flows\fR and \fBdel-flows\fR commands support an additional
-optional field:
+The \fBadd-flow\fR, \fBadd-flows\fR, and \fBdel-flows\fR commands
+support an additional optional field:
.IP \fBpriority=\fIvalue\fR
Sets the priority of the flow to be added or deleted to \fIvalue\fR,
which should be a number between 0 and 65535, inclusive. If this
field is not specified, it defaults to 32768.
+.PP
+The \fBadd-flow\fR and \fBadd-flows\fR commands support additional
+optional fields:
+
+.TP
+\fBidle_timeout=\fIseconds\fR
+Causes the flow to expire after the given number of seconds of
+inactivity. A value of 0 prevents a flow from expiring due to
+inactivity. The default is 60 seconds.
+
+.IP \fBhard_timeout=\fIseconds\fR
+Causes the flow to expire after the given number of seconds,
+regardless of activity. A value of 0 (the default) gives the flow no
+hard expiration deadline.
+
.PP
The \fBdump-flows\fR and \fBdump-aggregate\fR commands support an
additional optional field:
\fB255\fR, statistics are gathered about flows from all tables.
.SH OPTIONS
+.TP
+\fB-t\fR, \fB--timeout=\fIsecs\fR
+Limits \fBdpctl\fR runtime to approximately \fIsecs\fR seconds. If
+the timeout expires, \fBdpctl\fR will exit with a \fBSIGALRM\fR
+signal.
+
.TP
\fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
Specifies a PEM file containing the private key used as the
Prints a brief help message to the console.
.TP
-\fB-v\fR \fImodule\fB:\fIfacility\fB:\fIlevel\fR, \fB--verbose=\fImodule\fB:\fIfacility\fB:\fIlevel\fR
+\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
Sets the logging level for \fImodule\fR in \fIfacility\fR to
\fIlevel\fR. The \fImodule\fR may be any valid module name (as
displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
special name \fBANY\fR to set the logging levels for all modules. The
\fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
for logging to the system log or to the console, respectively, or
-\fBANY\fR to set the logging levels for both facilities. The
-\fIlevel\fR must be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or
-\fBdbg\fR, designating the minimum severity of a message for it to be
-logged.
+\fBANY\fR to set the logging levels for both facilities. If it is
+omitted, \fIfacility\fR defaults to \fBANY\fR. The \fIlevel\fR must
+be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
+the minimum severity of a message for it to be logged. If it is
+omitted, \fIlevel\fR defaults to \fBdbg\fR.
.TP
\fB-v\fR, \fB--verbose\fR
projects / openvswitch / blobdiff