.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.
-
.PP
The following commands can be apply to OpenFlow switches regardless of
the connection method.
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. Each line in \fIfile\fR is a flow entry in the format
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. When invoked with the \fB--strict\fR option,
+wildcards are not treated as active for matching purposes. See
+\fBFLOW SYNTAX\fR, below, for the syntax of \fIflows\fR.
+
.TP
\fBdel-flows \fIswitch \fR[\fIflow\fR]
Deletes entries from the datapath \fIswitch\fR's tables that match
-\fIflow\fR. If \fIflow\fR is omitted, all flows in the datapath's
-tables are removed. See \fBFLOW SYNTAX\fR, below, for the syntax of
-\fIflows\fR.
+\fIflow\fR. When invoked with the \fB--strict\fR option, wildcards are
+not treated as active for matching purposes. If \fIflow\fR is
+omitted and the \fB--strict\fR option is not used, all flows in the
+datapath's 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
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:
\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.)
+.IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR
+Modifies the VLAN id on a packet. The VLAN tag is added or modified
+as necessary to match the value specified. If the VLAN tag is added,
+a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set
+this).
+
+.IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR
+Modifies the VLAN priority on a packet. The VLAN tag is added or modified
+as necessary to match the value specified. Valid values are between 0
+(lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used
+(see the \fBmod_vlan_vid\fR action to set this).
+
+.IP \fBstrip_vlan\fR
+Strips the VLAN tag from a packet if it is present.
.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--strict\fR
+Uses strict matching when running flow modification commands.
+
.TP
\fB-t\fR, \fB--timeout=\fIsecs\fR
Limits \fBdpctl\fR runtime to approximately \fIsecs\fR seconds. If
git://git.onelab.eu / sliver-openvswitch.git / blobdiff