X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-dpctl.8.in;h=5a0dd7064a7cbef2ef50667cb61ea3a685cb7341;hb=ec988646afe6aee6a63d6894a3e9b50f715d5941;hp=5b5941bedf403c22b4d934892fb34a399ceacc4a;hpb=032aa6a3543621213f133aff3e31021dfd4bef43;p=sliver-openvswitch.git diff --git a/utilities/ovs-dpctl.8.in b/utilities/ovs-dpctl.8.in index 5b5941bed..5a0dd7064 100644 --- a/utilities/ovs-dpctl.8.in +++ b/utilities/ovs-dpctl.8.in @@ -1,4 +1,9 @@ -.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 @@ -11,8 +16,7 @@ ovs\-dpctl \- administer Open vSwitch datapaths .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''. @@ -34,11 +38,12 @@ default provider \fBsystem\fR is assumed. 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 @@ -61,6 +66,9 @@ The following options are currently supported: .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 @@ -68,6 +76,14 @@ Adds an arbitrary key-value option to the port's configuration. \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 @@ -85,32 +101,99 @@ 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 +The datapath numbers consists of flow stats and mega flow mask stats. +.IP +The "lookups" row displays three stats related to flow lookup triggered +by processing incoming packets in the datapath. "hit" displays number +of packets matches existing flows. "missed" displays the number of +packets not matching any existing flow and require user space processing. +"lost" displays number of packets destined for user space process but +subsequently dropped before reaching userspace. The sum of "hit" and "miss" +equals to the total number of packets datapath processed. +.IP +The "flows" row displays the number of flows in datapath. +.IP +The "masks" row displays the mega flow mask stats. This row is omitted +for datapath not implementing mega flow. "hit" displays the total number +of masks visited for matching incoming packets. "total" displays number of +masks in the datapath. "hit/pkt" displays the average number of masks +visited per packet; the ratio between "hit" and total number of +packets processed by the datapath". +.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" -Prints to the console all flow entries in datapath \fIdp\fR's -flow table. +.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 "[\fB\-m \fR| \fB\-\-more\fR] \fBdump\-flows\fR [\fIdp\fR] [\fBfilter=\fIfilter\fR]" +Prints to the console all flow entries in datapath \fIdp\fR's flow +table. Without \fB\-m\fR or \fB\-\-more\fR, output omits match fields +that a flow wildcards entirely; with \fB\-m\fR or \fB\-\-more\fR, +output includes all wildcarded fields. .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. +If \fBfilter=\fIfilter\fR is specified, only displays the flows +that match the \fIfilter\fR. \fIfilter\fR is a flow in the form similiar +to that accepted by \fBovs\-ofctl\fR(8)'s \fBadd\-flow\fR command. (This is +not an OpenFlow flow: besides other differences, it never contains wildcards.) +The \fIfilter\fR is also useful to match wildcarded fields in the datapath +flow. As an example, \fBfilter='tcp,tp_src=100'\fR will match the +datapath flow containing '\fBtcp(src=80/0xff00,dst=8080/0xff)\fR'. +. +.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 +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 -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. +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 +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 -.IP "\fB\-s\fR, \fB\-\-statistics\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. -.TP -\fB\-t\fR, \fB\-\-timeout=\fIsecs\fR +. +.IP "\fB\-m\fR" +.IQ "\fB\-\-more\fR" +Increases the verbosity of \fBdump\-flows\fR output. +. +.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. @@ -118,34 +201,7 @@ 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)