-.TH ovs\-dpctl 8 "August 2009" "Open vSwitch" "Open vSwitch Manual"
+.de IQ
+. br
+. ns
+. IP "\\$1"
+..
+.TH ovs\-dpctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
.ds PN ovs\-dpctl
.
.SH NAME
.SH DESCRIPTION
.PP
The \fBovs\-dpctl\fR program can create, modify, and delete Open vSwitch
-datapaths. A single machine may host up to 256 datapaths (numbered 0
-to 255).
+datapaths. A single machine may host any number of datapaths.
.PP
A newly created datapath is associated with only one network device, a
virtual network device sometimes called the datapath's ``local port''.
The following commands manage datapaths.
.
.TP
-\fBadd\-dp \fIdp\fR [\fInetdev\fR...]
+\fBadd\-dp \fIdp\fR [\fInetdev\fR[\fB,\fIoption\fR]...]
Creates datapath \fIdp\fR, with a local port also named \fIdp\fR.
This will fail if a network device \fIdp\fR already exists.
.IP
-If \fInetdev\fRs are specified, \fBovs\-dpctl\fR adds them to the datapath.
+If \fInetdev\fRs are specified, \fBovs\-dpctl\fR adds them to the
+new datapath, just as if \fBadd\-if\fR was specified.
.
.TP
\fBdel\-dp \fIdp\fR
.RS
.IP "\fBtype=\fItype\fR"
Specifies the type of port to add. The default type is \fBsystem\fR.
+.IP "\fBport_no=\fIport\fR"
+Requests a specific port number within the datapath. If this option is
+not specified then one will be automatically assigned.
.IP "\fIkey\fB=\fIvalue\fR"
Adds an arbitrary key-value option to the port's configuration.
.RE
\fBovs\-vswitchd.conf.db\fR(5) documents the available port types and
options.
.
+.IP "\fBset\-if \fIdp port\fR[\fB,\fIoption\fR]..."
+Reconfigures each \fIport\fR in \fIdp\fR as specified. An
+\fIoption\fR of the form \fIkey\fB=\fIvalue\fR adds the specified
+key-value option to the port or overrides an existing key's value. An
+\fIoption\fR of the form \fIkey\fB=\fR, that is, without a value,
+deletes the key-value named \fIkey\fR. The type and port number of a
+port cannot be changed, so \fBtype\fR and \fBport_no\fR are only allowed if
+they match the existing configuration.
.TP
\fBdel\-if \fIdp netdev\fR...
Removes each \fInetdev\fR from the list of network devices datapath
Prints the name of each configured datapath on a separate line.
.
.TP
-\fBshow \fR[\fIdp\fR...]
+[\fB\-s\fR | \fB\-\-statistics\fR] \fBshow \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.)
+port is identified as port 0.) If \fB\-s\fR or \fB\-\-statistics\fR
+is specified, then packet and byte counters are also printed for each
+port.
.IP
If one or more datapaths are specified, information on only those
datapaths are displayed. Otherwise, \fBovs\-dpctl\fR displays information
about all configured datapaths.
+.SS "DEBUGGING COMMANDS"
+The following commands are primarily useful for debugging Open
+vSwitch. The flow table entries (both matches and actions) that they
+work with are not OpenFlow flow entries. Instead, they are different
+and considerably simpler flows maintained by the Open vSwitch kernel
+module. Use \fBovs\-ofctl\fR(8), instead, to work with OpenFlow flow
+entries.
.
-.IP "\fBdump\-flows \fIdp\fR"
+.PP
+The \fIdp\fR argument to each of these commands is optional when
+exactly one datapath exists, in which case that datapath is the
+default. When multiple datapaths exist, then a datapath name is
+required.
+.
+.IP "\fBdump\-flows\fR [\fIdp\fR]"
Prints to the console all flow entries in datapath \fIdp\fR's
flow table.
+.
+.IP "\fBadd\-flow\fR [\fIdp\fR] \fIflow actions\fR"
+.IQ "[\fB\-\-clear\fR] [\fB\-\-may-create\fR] [\fB\-s\fR | \fB\-\-statistics\fR] \fBmod\-flow\fR [\fIdp\fR] \fIflow actions\fR"
+Adds or modifies a flow in \fIdp\fR's flow table that, when a packet
+matching \fIflow\fR arrives, causes \fIactions\fR to be executed.
.IP
-This command is primarily useful for debugging Open vSwitch. The flow
-table entries that it displays are not
-OpenFlow flow entries. Instead, they are different and considerably
-simpler flows maintained by the Open vSwitch kernel module.
-.IP "\fBdel\-flows \fIdp\fR"
-Deletes all flow entries from datapath \fIdp\fR's flow table.
+The \fBadd\-flow\fR command succeeds only if \fIflow\fR does not
+already exist in \fIdp\fR. Contrariwise, \fBmod\-flow\fR without
+\fB\-\-may\-create\fR only modifies the actions for an existing flow.
+With \fB\-\-may\-create\fR, \fBmod\-flow\fR will add a new flow or
+modify an existing one.
+.IP
+If \fB\-s\fR or \fB\-\-statistics\fR is specified, then
+\fBmod\-flows\fR prints the modified flow's statistics. A flow's
+statistics are the number of packets and bytes that have passed
+through the flow, the elapsed time since the flow last processed a
+packet (if ever), and (for TCP flows) the union of the TCP flags
+processed through the flow.
.IP
-This command is primarily useful for debugging Open vSwitch. As
-discussed in \fBdump\-flows\fR, these entries are
-not OpenFlow flow entries. By deleting them, the process that set them
-up may be confused about their disappearance.
+With \fB\-\-clear\fR, \fBmod\-flows\fR zeros out the flow's
+statistics. The statistics printed if \fB\-s\fR or
+\fB\-\-statistics\fR is also specified are those from just before
+clearing the statistics.
+.
+.IP "[\fB\-s\fR | \fB\-\-statistics\fR] \fBdel\-flow\fR [\fIdp\fR] \fIflow\fR"
+Deletes the flow from \fIdp\fR's flow table that matches \fIflow\fR.
+If \fB\-s\fR or \fB\-\-statistics\fR is specified, then
+\fBmod\-flows\fR prints the deleted flow's statistics.
+.
+.IP "\fBdel\-flows\fR [\fIdp\fR]"
+Deletes all flow entries from datapath \fIdp\fR's flow table.
.
.SH OPTIONS
-.TP
-\fB\-t\fR, \fB\-\-timeout=\fIsecs\fR
+.IP "\fB\-s\fR"
+.IQ "\fB\-\-statistics\fR"
+Causes the \fBshow\fR command to print packet and byte counters for
+each port within the datapaths that it shows.
+.
+.IP "\fB\-t\fR"
+.IQ "\fB\-\-timeout=\fIsecs\fR"
Limits \fBovs\-dpctl\fR runtime to approximately \fIsecs\fR seconds. If
the timeout expires, \fBovs\-dpctl\fR will exit with a \fBSIGALRM\fR
signal.
.so lib/vlog.man
.so lib/common.man
.
-.SH EXAMPLES
-.
-A typical \fBovs\-dpctl\fR command sequence for controlling an
-Open vSwitch kernel module:
-.
-.TP
-\fBovs\-dpctl add\-dp dp0\fR
-Creates datapath number 0.
-.
-.TP
-\fBovs\-dpctl add\-if dp0 eth0 eth1\fR
-Adds two network devices to the new datapath.
-.
-.PP
-At this point one would ordinarily start \fBovs\-openflowd\fR(8) on
-\fBdp0\fR, transforming \fBdp0\fR into an OpenFlow switch. Then, when
-the switch and the datapath is no longer needed:
-.
-.TP
-\fBovs\-dpctl del\-if dp0 eth0 eth1\fR
-Removes network devices from the datapath.
-.
-.TP
-\fBovs\-dpctl del\-dp dp0\fR
-Deletes the datapath.
-.
.SH "SEE ALSO"
.
.BR ovs\-appctl (8),
-.BR ovs\-openflowd (8),
.BR ovs\-vswitchd (8)