-.TH dpctl 8 "May 2008" "OpenFlow" "OpenFlow Manual"
+.TH dpctl 8 "March 2009" "OpenFlow" "OpenFlow Manual"
.ds PN dpctl
.SH NAME
-dpctl \- administer OpenFlow datapaths
+dpctl \- administer OpenFlow switches and datapaths
.SH SYNOPSIS
.B dpctl
-[\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR&...]
+[\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR\&...]
.SH DESCRIPTION
The
.B dpctl
-program is a command line tool for monitoring and administering OpenFlow
-datapaths. It is able to show the current state of a datapath,
-including features, configuration, and tables entries. When using the
-OpenFlow kernel module,
+program is a command line tool primarily for monitoring and
+administering OpenFlow switches. It is able to show the current state
+of a switch, including features, configuration, and table entries.
.B dpctl
-is used to add, delete, modify, and monitor datapaths.
+can also add, delete, and modify OpenFlow reference implementation
+datapaths.
-Most \fBdpctl\fR commands take an argument that specifies the
-method for connecting to an OpenFlow switch. The following connection
-methods are supported:
+.SS "Datapath Commands"
-.TP
-\fBnl:\fIdp_idx\fR
-The local Netlink datapath numbered \fIdp_idx\fR. This form requires
-that the local host has the OpenFlow kernel module for Linux loaded.
+The \fBdpctl\fR program can create, modify, and delete datapaths
+supported by the OpenFlow reference implementation. A
+single machine may host up to 256 datapaths (numbered 0 to 255).
+
+A newly created datapath is associated with only one network device, a
+virtual network device sometimes called the datapath's ``local port''.
+A newly created datapath is not, however, associated with any of the
+host's other network devices. To intercept and process traffic on a
+given network device, use the \fBaddif\fR command to explicitly add
+that network device to the datapath.
+Do not use \fBdpctl\fR commands to modify datapaths in conjunction
+with \fBvswitchd\fR(8). Instead, modify the \fBvswitchd\fR
+configuration file and send \fBSIGHUP\fR to the \fBvswitchd\fR
+process.
+
+.PP
+Most \fBdpctl\fR commands that work with datapaths take an argument
+that specifies the name of the datapath, in one of the following
+forms:
+
+.RS
.TP
-\fBssl:\fIhost\fR[\fB:\fIport\fR]
-The specified SSL \fIport\fR (default: 6633) on the given remote
-\fIhost\fR. The \fB--private-key\fR, \fB--certificate\fR, and
-\fB--ca-cert\fR options are mandatory when this form is used.
+\fBdp\fIN\fR
+Datapath number \fIN\fR, where \fIN\fR is a number between 0 and 255,
+inclusive.
.TP
-\fBtcp:\fIhost\fR[\fB:\fIport\fR]
-The specified TCP \fIport\fR (default: 6633) on the given remote
-\fIhost\fR.
+\fIname\fR
+The name of the network device associated with the datapath's local
+port. (\fBdpctl\fR internally converts this into a datapath number,
+as above.)
.TP
-\fBunix:\fIfile\fR
-The Unix domain server socket named \fIfile\fR.
+\fBnl:\fIN\fR
+This is an obsolete synonym for \fBdp\fIN\fR.
+.RE
-.SH COMMANDS
+.PP
+The following commands manage datapaths.
-With the \fBdpctl\fR program, datapaths running in the kernel can be
-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.
+.TP
+\fBadddp \fIdp\fR [\fInetdev\fR...]
-A newly created datapath is not associated with any of the
-host's network devices thus does not process any incoming
-traffic. To intercept and process traffic on a given network device, the
-network device must be explicitly added to a datapath through the
-\fBaddif\fR command.
+Creates datapath \fIdp\fR. The name of the new datapath's local port
+depends on how \fIdp\fR is specified: if it takes the form
+\fBdp\fIN\fR, the local port will be named \fBdp\fIN\fR; if \fIdp\fR
+is \fBnl:\fI, the local port will be named \fBof\fIN\fR; otherwise,
+the local port's name will be \fIdp\fR.
-The following commands manage local datapaths.
+This will fail if the host already has 256 datapaths, if a network
+device with the same name as the new datapath's local port already
+exists, or if \fIdp\fR is given in the form \fBdp\fIN\fR or
+\fBnl:\fIN\fR and a datapath numbered \fIN\fR already exists.
-.TP
-\fBadddp nl:\fIdp_idx\fR
-Creates datapath numbered \fIdp_idx\fR on the local host. This will
-fail if \fIdp_idx\fR is not in the range 0 to 31, or if the datapath
-with that number already exists on the host.
+If \fInetdev\fRs are specified, \fBdpctl\fR adds them to the datapath.
.TP
-\fBdeldp nl:\fIdp_idx\fR
-Deletes datapath \fIdp_idx\fR on the local host. \fIdp_idx\fR must be
-an existing datapath. All of a datapath's network devices must be
-explicitly removed before the datapath can be deleted (see \fBdelif\fR
-command).
+\fBdeldp \fIdp\fR
+Deletes datapath \fIdp\fR. If \fIdp\fR is associated with any network
+devices, they are automatically removed.
.TP
-\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
+\fBaddif \fIdp netdev\fR...
+Adds each \fInetdev\fR to the set of network devices datapath
+\fIdp\fR monitors, where \fIdp\fR is the name 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
to a datapath, the datapath has complete ownership of the network device's
traffic and the network device appears silent to the rest of the system.
.TP
-\fBdelif nl:\fIdp_idx netdev\fR...
+\fBdelif \fIdp netdev\fR...
Removes each \fInetdev\fR from the list of network devices datapath
-\fIdp_idx\fR monitors.
+\fIdp\fR monitors.
.TP
-\fBget-idx \fIof_dev\fR
-Prints the datapath index for OpenFlow device \fIof_dev\fR.
+\fBget-idx \fIdp\fR
+Prints the datapath number of datapath \fIdp\fR.
-.PP
-The following commands can be apply to OpenFlow switches regardless of
-the connection method.
+.TP
+\fBget-name \fIdp\fR
+Prints the name of datapath \fIdp\fR, that is, the name of the network
+device acting as its local port.
+
+.TP
+\fBshowdp \fR[\fIdp\fR...]
+Prints a summary of configured datapaths, including their datapath
+numbers and a list of ports connected to each datapath. (The local
+port is identified as port 0.)
+
+If one or more datapaths are specified, information on only those
+datapaths are displayed. Otherwise, \fBdpctl\fR displays information
+about all configured datapaths.
+
+.SS "OpenFlow Switch Management Commands"
+
+These commands allow \fBdpctl\fR to monitor and administer an OpenFlow
+switch. It is able to show the current state of a switch, including
+features, configuration, and table entries.
+
+Most of these commands take an argument that specifies the method for
+connecting to an OpenFlow switch. The following connection methods
+are supported:
+
+.RS
+.TP
+\fBssl:\fIhost\fR[\fB:\fIport\fR]
+The specified SSL \fIport\fR (default: 6633) on the given remote
+\fIhost\fR. The \fB--private-key\fR, \fB--certificate\fR, and
+\fB--ca-cert\fR options are mandatory when this form is used.
+
+.TP
+\fBtcp:\fIhost\fR[\fB:\fIport\fR]
+The specified TCP \fIport\fR (default: 6633) on the given remote
+\fIhost\fR.
+
+.TP
+\fBunix:\fIfile\fR
+The Unix domain server socket named \fIfile\fR.
+.RE
.TP
\fBshow \fIswitch\fR
-Prints to the console information on datapath \fIswitch\fR including
+Prints to the console information on \fIswitch\fR, including
information on its flow tables and ports.
.TP
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
-datapath \fIswitch\fR.
+\fIswitch\fR.
.TP
\fBdump-ports \fIswitch\fR
Prints to the console statistics for each of the network devices
-associated with datapath \fIswitch\fR.
+associated with \fIswitch\fR.
.TP
\fBmod-port \fIswitch\fR \fInetdev\fR \fIaction\fR
.TP
\fBdump-flows \fIswitch \fR[\fIflows\fR]
-Prints to the console all flow entries in datapath \fIswitch\fR's
+Prints to the console all flow entries in \fIswitch\fR's
tables that match \fIflows\fR. If \fIflows\fR is omitted, all flows
-in the datapath are retrieved. See \fBFLOW SYNTAX\fR, below, for the
+in the switch are retrieved. See \fBFlow Syntax\fR, below, for the
syntax of \fIflows\fR.
.TP
\fBdump-aggregate \fIswitch \fR[\fIflows\fR]
-Prints to the console aggregate statistics for flows in datapath
-\fSWITCH\fR's tables that match \fIflows\fR. If \fIflows\fR is omitted,
-the statistics are aggregated across all flows in the datapath's flow
-tables. See \fBFLOW SYNTAX\fR, below, for the syntax of \fIflows\fR.
+Prints to the console aggregate statistics for flows in
+\fIswitch\fR's tables that match \fIflows\fR. If \fIflows\fR is omitted,
+the statistics are aggregated across all flows in the switch'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,
+Add the flow entry as described by \fIflow\fR to the \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
+Add flow entries as described in \fIfile\fR to \fIswitch\fR's
tables. Each line in \fIfile\fR is a flow entry in the format
-described in \fBFLOW SYNTAX\fR, 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
+Modify the actions in entries from the \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.
+\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
+Deletes entries from the \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. 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
+switch'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.
+named on \fBsecchan\fR(8)'s \fB-l\fR or \fB--listen\fR command line
+option.
+
+This option may be useful for debugging switch implementations.
.TP
\fBexecute \fIswitch command \fR[\fIarg\fR...]
-
Sends a request to \fIswitch\fR to execute \fIcommand\fR along with
each \fIarg\fR, if any, then waits for the command to complete and
reports its completion status on \fBstderr\fR and its output, if any,
switch-dependent. (This command uses a Nicira extension to OpenFlow
that may not be available on all switches.)
-.PP
-The following commands can be used regardless of the connection
-method. They apply to OpenFlow switches and controllers.
+.SS "OpenFlow Switch and Controller Commands"
+
+The following commands, like those in the previous section, may be
+applied to OpenFlow switches, using any of the connection methods
+described in that section. Unlike those commands, these may also be
+applied to OpenFlow 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.
+\fBprobe \fItarget\fR
+Sends a single OpenFlow echo-request message to \fItarget\fR 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
+\fBping \fItarget \fR[\fIn\fR]
+Sends a series of 10 echo request packets to \fItarget\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
+\fBbenchmark \fItarget 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
+maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte
messages.
-.SH "FLOW SYNTAX"
+.SS "Flow Syntax"
Some \fBdpctl\fR commands accept an argument that describes a flow or
flows. Such flow descriptions comprise a series
\fIfield\fB=\fIvalue\fR assignments, separated by commas or white
-space.
+space. (Embedding spaces into a flow description normally requires
+quoting to prevent the shell from breaking the description into
+multiple arguments.)
The following field assignments describe how a flow matches a packet.
If any of these assignments is omitted from the flow syntax, the field
is treated as a wildcard; thus, if all of them are omitted, the
resulting flow matches all packets. The string \fB*\fR or \fBANY\fR
may be specified a value to explicitly mark any of these fields as a
-wildcard.
+wildcard. (\fB*\fR should be quoted to protect it from shell
+expansion.)
.IP \fBin_port=\fIport_no\fR
Matches physical port \fIport_no\fR. Switch ports are numbered as
.PP
The \fBadd-flow\fR and \fBadd-flows\fR commands require an additional field:
-.IP \fIactions\fB=\fItarget\fR[\fB,\fItarget\fR...]\fR
+.IP \fBactions=\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
.PP
The \fBdump-flows\fR, \fBdump-aggregate\fR, \fBdel-flow\fR
-and \fBdel-flows\fR commands support the additional optional field:
+and \fBdel-flows\fR commands support one additional optional field:
.TP
\fBout_port=\fIport\fR
.SH EXAMPLES
-A typical dpctl command sequence for controlling an OpenFlow kernel module:
-.nf
-.TP
-Create datapath numbered 0:
+.SS "Datapath Examples"
-.B % dpctl adddp nl:0
+A typical \fBdpctl\fR command sequence for controlling an OpenFlow
+kernel module:
.TP
-Add two network devices to the new datapath:
-
-.B % dpctl addif nl:0 eth0
-.B % dpctl addif nl:0 eth1
+\fBdpctl adddp dp0\fR
+Creates datapath numbered 0.
.TP
-Monitor traffic received by the datapath (exit with control-C):
-
-.B % dpctl monitor nl:0
+\fBdpctl addif dp0 eth0 eth1\fR
+Adds two network devices to the new datapath.
+.PP
+At this point one would ordinarily start \fBsecchan\fR(8) on
+\fBdp0\fR, transforming \fBdp0\fR into an OpenFlow switch. Then, when
+the switch and the datapath is no longer needed:
.TP
-View the datapath's table stats after some traffic has passed through:
-
-.B % dpctl dump-tables nl:0
+\fBdpctl delif dp0 eth0 eth1\fR
+Removes network devices from the datapath.
.TP
-View the flow entries in the datapath:
+\fBdpctl deldp dp0\fR
+Deletes the datapath.
-.B % dpctl dump-flows nl:0
+.SS "OpenFlow Switch Examples"
-.TP
-Remove network devices from the datapath when finished:
+The following examples assume that an OpenFlow switch on the local
+host has been configured to listen for management connections on a
+Unix domain socket named \fB/var/run/openflow.sock\fR, e.g. by
+specifying \fB--listen=punix:/var/run/openflow.sock\fR on the
+\fBsecchan\fR(8) command line.
-.B % dpctl delif nl:0 eth0
-.B % dpctl delif nl:0 eth1
+.TP
+\fBdpctl dump-tables unix:/var/run/openflow.sock\fR
+Prints out the switch's table stats. (This is more interesting after
+some traffic has passed through.)
.TP
-Delete the datapath:
+\fBdpctl dump-flows unix:/var/run/openflow.sock\fR
+Prints the flow entries in the switch.
-.B % dpctl deldp nl:0
-.fi
.SH "SEE ALSO"
.BR secchan (8),
projects / openvswitch / commitdiff