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
-created, deleted, modified, and monitored. A single machine may
+created, deleted, and modified. A single machine may
host up to 32 datapaths (numbered 0 to 31). In most situations,
a machine hosts only one datapath.
command).
.TP
-\fBaddif nl:\fIdp_idx netdev\fR
-Adds \fInetdev\fR to the list of network devices datapath
+\fBaddif nl:\fIdp_idx netdev\fR...
+Adds each \fInetdev\fR to the list of network devices datapath
\fIdp_idx\fR monitors, where \fIdp_idx\fR is the ID of an existing
datapath, and \fInetdev\fR is the name of one of the host's
network devices, e.g. \fBeth0\fR. Once a network device has been added
traffic and the network device appears silent to the rest of the system.
.TP
-\fBdelif nl:\fIdp_idx netdev\fR
-Removes \fInetdev\fR from the list of network devices datapath
+\fBdelif nl:\fIdp_idx netdev\fR...
+Removes each \fInetdev\fR from the list of network devices datapath
\fIdp_idx\fR monitors.
-.TP
-\fBmonitor nl:\fIdp_idx\fR
-Prints to the console all OpenFlow packets sent by datapath
-\fIdp_idx\fR to its controller, where \fIdp_idx\fR is the ID of an
-existing datapath.
-
-.TP
-\fBbenchmark-nl nl:\fIdp_idx n size\fR
-Checks the netlink performance between the kernel and userspace.
-This is done by sending \fIN\fR packets of \fIsize\fR bytes from
-the kernel module to dpctl.
-
.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
the statistics are aggregated across all flows in the datapath's flow
tables. See \fBFLOW SYNTAX\fR, below, for the syntax of \fIflows\fR.
+.TP
+\fBadd-flow \fIswitch flow\fR
+Add the flow entry as described by \fIflow\fR to the datapath \fIswitch\fR's
+tables. The flow entry is in the format described in \fBFLOW SYNTAX\fR,
+below.
+
.TP
\fBadd-flows \fIswitch file\fR
Add flow entries as described in \fIfile\fR to the datapath \fIswitch\fR's
tables. Each line in \fIfile\fR is a flow entry in the format
-described in \fBFLOW SYNTAX\fB, below.
+described in \fBFLOW SYNTAX\fR, below.
+
+.TP
+\fBmod-flows \fIswitch flow\fR
+Modify the actions in entries from the datapath \fIswitch\fR's tables
+that match \fIflow\fR. See \fBFLOW SYNTAX\fR, below, for the syntax
+of \fIflows\fR.
.TP
\fBdel-flows \fIswitch \fR[\fIflow\fR]
tables are removed. See \fBFLOW SYNTAX\fR, below, for the syntax of
\fIflows\fR.
+.TP
+\fBmonitor \fIswitch\fR
+Connects to \fIswitch\fR and prints to the console all OpenFlow
+messages received. Usually, \fIswitch\fR should specify a connection
+named on \fBsecchan\fR(8)'s \fB-m\fR or \fB--monitor\fR command line
+option, in which the messages printed will be all those sent or
+received by \fBsecchan\fR to or from the kernel datapath module. A
+\fIswitch\fR of the form \fBnl:\fIdp_idx\fR will print all
+asynchronously generated OpenFlow messages (such as packet-in
+messages), but it will not print any messages sent to the kernel by
+\fBsecchan\fR and other processes, nor will it print replies sent by
+the kernel in response to those messages.
+
+.PP
+The following commands can be used regardless of the connection
+method. They apply to OpenFlow switches and controllers.
+
+.TP
+\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 \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 \fIvconn\fR for round-trips of \fIn\fR-byte
+messages.
+
.SH "FLOW SYNTAX"
Some \fBdpctl\fR commands accept an argument that describes a flow or
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
Matches UDP or TCP destination port \fIport\fR.
.PP
-The \fBadd-flow\fR command requires an additional field:
+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:
-.IP \fBaction=\fItarget\fR
-Specifies the action to take on a packet when the flow entry matches.
-The \fItarget\fR may be a decimal port number designating the physical
-port on which to output the packet, or one of the following keywords:
+.IP \fIactions\fB=\fItarget\fR[\fB,\fItarget\fR...]\fR
+Specifies a comma-separated list of actions to take on a packet when the
+flow entry matches. The \fItarget\fR may be a decimal port number
+designating the physical port on which to output the packet, or one of
+the following keywords:
.RS
+.IP \fBoutput\fR:\fIport\fR
+Outputs the packet on the port specified by \fIport\fR.
+
.IP \fBnormal\fR
-Subjects the packet to the device's normal L2/L3 processing. This
-action is not implemented by all OpenFlow switches.
+Subjects the packet to the device's normal L2/L3 processing. (This
+action is not implemented by all OpenFlow switches.)
.IP \fBflood\fR
Outputs the packet on all switch physical ports other than the port on
Outputs the packet on all switch physical ports other than the port on
which it was received.
-.IP \fBcontroller\fR
+.IP \fBcontroller\fR:\fImax_len\fR
Sends the packet to the OpenFlow controller as a ``packet in''
-message.
+message. If \fImax_len\fR is a number, then it specifies the maximum
+number of bytes that should be sent. If \fImax_len\fR is \fBALL\fR or
+omitted, then the entire packet is sent.
.IP \fBlocal\fR
Outputs the packet on the ``local port,'' which corresponds to the
\fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in
\fBsecchan\fR(8) for information on the \fBof\fIn\fR network device).
+
+.IP \fBmod_vlan\fR:\fIvlan_id\fR
+Modifies the VLAN tag on a packet. If \fIvlan_id\fR is a number, then
+the VLAN tag is added or modified as necessary to match the value
+specified. If \fIvlan_id\fR is \fBSTRIP\fR, then the VLAN tag is
+stripped from the packet if one is present. (This action is not
+implemented by all OpenFlow switches.)
.RE
.IP
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
git://git.onelab.eu / sliver-openvswitch.git / blobdiff