utilities/dpctl.8

   1 .TH dpctl 8 "May 2008" "OpenFlow" "OpenFlow Manual"
   2
   3 .SH NAME
   4 dpctl \- command line tool to administer OpenFlow datapaths
   5
   6 .SH SYNOPSIS
   7 .B dpctl
   8 [OPTIONS] COMMAND [SWITCH] [ARGS...]
   9
  10 .SH DESCRIPTION
  11 The
  12 .B dpctl
  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,
  17 .B dpctl
  18 is used to add, delete, modify, and monitor datapaths.
  19
  20
  21 .SH OPTIONS
  22 .TP
  23 .BR \-h ", " \-\^\-help
  24 Prints a brief help message to the console.
  25
  26 .TP
  27 .BR \-v ", " \-\^\-verbose
  28 Prints debug messages to the console.
  29
  30 .TP
  31 .BR \-V ", " \-\^\-version
  32 Prints version information to the console.
  33
  34 .SH COMMANDS
  35
  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.
  42
  43 .B COMMANDS FOR THE KERNEL MODULE
  44
  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.
  49
  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
  54 \fBaddif\fR command.
  55
  56
  57 .TP
  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.
  62
  63 .TP
  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
  68 command).
  69
  70 .TP
  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.
  78
  79 .TP
  80 .BI delif " nl:DP_IDX INTERFACE"
  81 Removes \fIINTERFACE\fR from the list of network interfaces datapath
  82 \fIDP_IDX\fR monitors.
  83
  84 .TP
  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
  88 existing datapath.
  89
  90 .TP
  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.
  95
  96
  97 .TP
  98 .B GENERAL COMMANDS
  99
 100 .TP
 101 The following commands can be used regardless of the connection method.
 102
 103 .TP
 104 .BI show " SWITCH"
 105 Prints to the console information on datapath \fISWITCH\fR including
 106 information on its flow tables and ports.
 107
 108 .TP
 109 .BI dump-tables " SWITCH"
 110 Prints to the console statistics for each of the flow tables used by
 111 datapath \fISWITCH\fR.
 112
 113 .TP
 114 .BI dump-ports " SWITCH"
 115 Prints to the console statistics for each of the physical interfaces
 116 associated with datapath \fISWITCH\fR.
 117
 118 .TP
 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.
 123
 124 .TP
 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
 129 tables.
 130
 131 .TP
 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..
 136
 137 .TP
 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
 141 tables are removed.
 142
 143 .SH EXAMPLES
 144
 145 A typical dpctl command sequence for controlling an OpenFlow kernel module:
 146 .nf
 147 .TP
 148 Create datapath numbered 0:
 149
 150 .B % dpctl adddp nl:0
 151
 152 .TP
 153 Add two interfaces to the new datapath:
 154
 155 .B % dpctl addif nl:0 eth0
 156 .B % dpctl addif nl:0 eth1
 157
 158 .TP
 159 Monitor traffic received by the datapath (exit with control-C):
 160
 161 .B % dpctl monitor nl:0
 162
 163
 164 .TP
 165 View the datapath's table stats after some traffic has passed through:
 166
 167 .B % dpctl dump-tables nl:0
 168
 169 .TP
 170 View the flow entries in the datapath:
 171
 172 .B % dpctl dump-flows nl:0
 173
 174 .TP
 175 Remove interfaces from the datapath when finished:
 176
 177 .B % dpctl delif nl:0 eth0
 178 .B % dpctl delif nl:0 eth1
 179
 180 .TP
 181 Delete the datapath:
 182
 183 .B % dpctl deldp nl:0
 184 .fi
 185 .SH "SEE ALSO"
 186
 187 .BR secchan (8),
 188 .BR switch (8)
 189 .BR controller (8)
 190 .BR vlogconf (8)