1 .TH dpctl 8 "May 2008" "OpenFlow" "OpenFlow Manual"
4 dpctl \- command line tool to administer OpenFlow datapaths
8 [OPTIONS] COMMAND [SWITCH] [ARGS...]
13 program is a command line tool for monitoring and administering OpenFlow
14 datapaths. It is able to show the current state of a datapath,
15 including features, configuration, and tables entries. When using the
16 OpenFlow kernel module,
18 is used to add, delete, modify, and monitor datapaths.
23 .BR \-h ", " \-\^\-help
24 Prints a brief help message to the console.
27 .BR \-v ", " \-\^\-verbose
28 Prints debug messages to the console.
31 .BR \-V ", " \-\^\-version
32 Prints version information to the console.
36 Depending on the type of datapath, \fBdpctl\fR communicates using
37 different connection methods. As such, one must provide the method to
38 use as the \fISWITCH\fR argument. To communicate with userspace,
39 \fItcp:host[:port]\fR is used. The netlink interface is used to
40 communicate with the kernel module directly. This uses the form
41 \fInl:DP_IDX\fR, where \fIDP_IDX\fR is explained below.
43 .B COMMANDS FOR THE KERNEL MODULE
45 With the \fBdpctl\fR program, datapaths running in the kernel can be
46 created, deleted, modified, and monitored. A single machine may
47 host up to 32 datapaths (numbered 0 to 31). In most situations,
48 a machine hosts only one datapath.
50 A newly created datapath is not associated with any of the
51 host's network interfaces and thus does not process any incoming
52 traffic. To intercept and process traffic on a given interface, the
53 interface must be explicitly added to a datapath through the
58 .BI adddp " nl:DP_IDX"
59 Creates datapath numbered \fIDP_IDX\fR on the local host. This will
60 fail if \fIDP_IDX\fR is not in the range 0 to 31, or if the datapath
61 with that number already exists on the host.
64 .BI deldp " nl:DP_IDX"
65 Deletes datapath \fIDP_IDX\fR on the local host. \fIDP_IDX\fR must be
66 an existing datapath. All of a datapath's interfaces must be
67 explicitly removed before the datapath can be deleted (see \fBdelif\fR
71 .BI addif " nl:DP_IDX INTERFACE"
72 Adds \fIINTERFACE\fR to the list of network interfaces datapath
73 \fIDP_IDX\fR monitors, where \fIDP_IDX\fR is the ID of an existing
74 datapath, and \fIINTERFACE\fR is the name of one of the host's
75 interfaces, e.g. \fBeth0\fR. Once an interface has been added
76 to a datapath, the datapath has complete ownership of the interface's
77 traffic and the interface appears silent to the rest of the system.
80 .BI delif " nl:DP_IDX INTERFACE"
81 Removes \fIINTERFACE\fR from the list of network interfaces datapath
82 \fIDP_IDX\fR monitors.
85 .BI monitor " nl:DP_IDX"
86 Prints to the console all OpenFlow packets sent by datapath
87 \fIDP_IDX\fR to its controller, where \fIDP_IDX\fR is the ID of an
91 .BI benchmark-nl " nl:DP_IDX N SIZE"
92 Checks the netlink performance between the kernel and userspace.
93 This is done by sending \fIN\fR packets of \fISIZE\fR bytes from
94 the kernel module to dpctl.
101 The following commands can be used regardless of the connection method.
105 Prints to the console information on datapath \fISWITCH\fR including
106 information on its flow tables and ports.
109 .BI dump-tables " SWITCH"
110 Prints to the console statistics for each of the flow tables used by
111 datapath \fISWITCH\fR.
114 .BI dump-ports " SWITCH"
115 Prints to the console statistics for each of the physical interfaces
116 associated with datapath \fISWITCH\fR.
119 .BI dump-flows " SWITCH [FLOW]"
120 Prints to the console all flow entries in datapath \fISWITCH\fR's tables
121 that match \fIFLOW\fR. If \fIFLOW\fR is omitted, all flows in the
122 datapath are retrieved.
125 .BI dump-aggregate " SWITCH [FLOWS]"
126 Prints to the console aggregate statistics for flows in datapath
127 \fSWITCH\fR's tables that match \fIFLOWS\fR. If \fIFLOWS\fR is omitted,
128 the statistics are aggregated across all flows in the datapath's flow
132 .BI add-flows " SWITCH FILE"
133 Add flow entries as described in \fIFILE\fR to the datapath \fISWITCH\fR's
134 tables. Each line in \fIFILE\fR describes an entry in the format used
135 to describe a \fIFLOW\fR in other commands..
138 .BI del-flows " SWITCH [FLOW]"
139 Deletes entries from the datapath \fISWITCH\fR's tables that match
140 \fIFLOW\fR. If \fIFLOW\fR is omitted, all flows in the datapath's
145 A typical dpctl command sequence for controlling an OpenFlow kernel module:
148 Create datapath numbered 0:
150 .B % dpctl adddp nl:0
153 Add two interfaces to the new datapath:
155 .B % dpctl addif nl:0 eth0
156 .B % dpctl addif nl:0 eth1
159 Monitor traffic received by the datapath (exit with control-C):
161 .B % dpctl monitor nl:0
165 View the datapath's table stats after some traffic has passed through:
167 .B % dpctl dump-tables nl:0
170 View the flow entries in the datapath:
172 .B % dpctl dump-flows nl:0
175 Remove interfaces from the datapath when finished:
177 .B % dpctl delif nl:0 eth0
178 .B % dpctl delif nl:0 eth1
183 .B % dpctl deldp nl:0