utilities/ovs-ofctl.8.in

   1 .TH ovs\-ofctl 8 "June 2009" "Open vSwitch" "Open vSwitch Manual"
   2 .ds PN ovs\-ofctl
   3
   4 .SH NAME
   5 ovs\-ofctl \- administer OpenFlow switches
   6
   7 .SH SYNOPSIS
   8 .B ovs\-ofctl
   9 [\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR\&...]
  10
  11 .SH DESCRIPTION
  12 The
  13 .B ovs\-ofctl
  14 program is a command line tool for monitoring and administering
  15 OpenFlow switches.  It can also show the current state of an OpenFlow
  16 switch, including features, configuration, and table entries.
  17
  18 .SS "OpenFlow Switch Management Commands"
  19
  20 These commands allow \fBovs\-ofctl\fR to monitor and administer an OpenFlow
  21 switch.  It is able to show the current state of a switch, including
  22 features, configuration, and table entries.
  23
  24 Most of these commands take an argument that specifies the method for
  25 connecting to an OpenFlow switch.  The following connection methods
  26 are supported:
  27
  28 .RS
  29 .so lib/vconn-active.man
  30 .
  31 .IP "\fIfile\fR"
  32 This is short for \fBunix:\fIfile\fR, as long as \fIfile\fR does not
  33 contain a colon.
  34 .
  35 .IP \fIdp\fR
  36 This is short for \fBunix:@RUNDIR@/\fIdp\fB.mgmt\fR, as long as
  37 \fIdp\fR does not contain a colon.
  38 .RE
  39
  40 .TP
  41 \fBshow \fIswitch\fR
  42 Prints to the console information on \fIswitch\fR, including
  43 information on its flow tables and ports.
  44
  45 .TP
  46 \fBstatus \fIswitch\fR [\fIkey\fR]
  47 Prints to the console a series of key-value pairs that report the
  48 status of \fIswitch\fR.  If \fIkey\fR is specified, only the key-value
  49 pairs whose key names begin with \fIkey\fR are printed.  If \fIkey\fR is
  50 omitted, all key-value pairs are printed.
  51
  52 .TP
  53 \fBdump-tables \fIswitch\fR
  54 Prints to the console statistics for each of the flow tables used by
  55 \fIswitch\fR.
  56
  57 .TP
  58 \fBdump-ports \fIswitch\fR
  59 Prints to the console statistics for each of the network devices
  60 associated with \fIswitch\fR.
  61
  62 .TP
  63 \fBmod-port \fIswitch\fR \fInetdev\fR \fIaction\fR
  64 Modify characteristics of an interface monitored by \fIswitch\fR.
  65 \fInetdev\fR can be referred to by its OpenFlow assigned port number or
  66 the device name, e.g. \fBeth0\fR.  The \fIaction\fR may be any one of the
  67 following:
  68
  69 .RS
  70 .IP \fBup\fR
  71 Enables the interface.  This is equivalent to ``ifconfig up'' on a Unix
  72 system.
  73
  74 .IP \fBdown\fR
  75 Disables the interface.  This is equivalent to ``ifconfig down'' on a Unix
  76 system.
  77
  78 .IP \fBflood\fR
  79 When a \fIflood\fR action is specified, traffic will be sent out this
  80 interface.  This is the default posture for monitored ports.
  81
  82 .IP \fBnoflood\fR
  83 When a \fIflood\fR action is specified, traffic will not be sent out
  84 this interface.  This is primarily useful to prevent loops when a
  85 spanning tree protocol is not in use.
  86
  87 .RE
  88
  89 .TP
  90 \fBdump-flows \fIswitch \fR[\fIflows\fR]
  91 Prints to the console all flow entries in \fIswitch\fR's
  92 tables that match \fIflows\fR.  If \fIflows\fR is omitted, all flows
  93 in the switch are retrieved.  See \fBFlow Syntax\fR, below, for the
  94 syntax of \fIflows\fR.  The output format is described in
  95 \fBTable Entry Output\fR.
  96
  97 .TP
  98 \fBdump-aggregate \fIswitch \fR[\fIflows\fR]
  99 Prints to the console aggregate statistics for flows in
 100 \fIswitch\fR's tables that match \fIflows\fR.  If \fIflows\fR is omitted,
 101 the statistics are aggregated across all flows in the switch's flow
 102 tables.  See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR.
 103 The output format is descrbed in \fBTable Entry Output\fR.
 104
 105 .TP
 106 \fBadd-flow \fIswitch flow\fR
 107 Add the flow entry as described by \fIflow\fR to the \fIswitch\fR's
 108 tables.  The flow entry is in the format described in \fBFlow Syntax\fR,
 109 below.
 110
 111 .TP
 112 \fBadd-flows \fIswitch file\fR
 113 Add flow entries as described in \fIfile\fR to \fIswitch\fR's
 114 tables.  Each line in \fIfile\fR is a flow entry in the format
 115 described in \fBFlow Syntax\fR, below.
 116
 117 .TP
 118 \fBmod-flows \fIswitch flow\fR
 119 Modify the actions in entries from the \fIswitch\fR's tables
 120 that match \fIflow\fR.  When invoked with the \fB--strict\fR option,
 121 wildcards are not treated as active for matching purposes.  See
 122 \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR.
 123
 124 .TP
 125 \fBdel-flows \fIswitch \fR[\fIflow\fR]
 126 Deletes entries from the \fIswitch\fR's tables that match
 127 \fIflow\fR.  When invoked with the \fB--strict\fR option, wildcards are
 128 not treated as active for matching purposes.  If \fIflow\fR is
 129 omitted and the \fB--strict\fR option is not used, all flows in the
 130 switch's tables are removed.  See \fBFlow Syntax\fR, below, for the
 131 syntax of \fIflows\fR.
 132
 133 .TP
 134 \fBmonitor \fIswitch\fR [\fImiss-len\fR [\fIsend-exp]]
 135 Connects to \fIswitch\fR and prints to the console all OpenFlow
 136 messages received.  Usually, \fIswitch\fR should specify a connection
 137 named on \fBovs\-openflowd\fR(8)'s \fB-l\fR or \fB--listen\fR command line
 138 option.
 139
 140 If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set
 141 configuration'' message at connection setup time that requests
 142 \fImiss-len\fR bytes of each packet that misses the flow table.  The
 143 OpenFlow reference implementation does not send these messages to the
 144 \fBovs\-ofctl monitor\fR client connection unless a nonzero value is
 145 specified on this argument.
 146
 147 If \fIsend-exp\fR is specified as \fB1\fR, \fBovs\-ofctl\fR will also
 148 request to be sent flow expiration messages.  If this argument is
 149 omitted, or \fB0\fR is specified, then \fRovs\-ofctl\fR will not request
 150 flow expirations.
 151
 152 This command may be useful for debugging switch or controller
 153 implementations.
 154
 155 .SS "OpenFlow Switch and Controller Commands"
 156
 157 The following commands, like those in the previous section, may be
 158 applied to OpenFlow switches, using any of the connection methods
 159 described in that section.  Unlike those commands, these may also be
 160 applied to OpenFlow controllers.
 161
 162 .TP
 163 \fBprobe \fItarget\fR
 164 Sends a single OpenFlow echo-request message to \fItarget\fR and waits
 165 for the response.  With the \fB-t\fR or \fB--timeout\fR option, this
 166 command can test whether an OpenFlow switch or controller is up and
 167 running.
 168
 169 .TP
 170 \fBping \fItarget \fR[\fIn\fR]
 171 Sends a series of 10 echo request packets to \fItarget\fR and times
 172 each reply.  The echo request packets consist of an OpenFlow header
 173 plus \fIn\fR bytes (default: 64) of randomly generated payload.  This
 174 measures the latency of individual requests.
 175
 176 .TP
 177 \fBbenchmark \fItarget n count\fR
 178 Sends \fIcount\fR echo request packets that each consist of an
 179 OpenFlow header plus \fIn\fR bytes of payload and waits for each
 180 response.  Reports the total time required.  This is a measure of the
 181 maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte
 182 messages.
 183
 184 .SS "Flow Syntax"
 185
 186 Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or
 187 flows.  Such flow descriptions comprise a series
 188 \fIfield\fB=\fIvalue\fR assignments, separated by commas or white
 189 space.  (Embedding spaces into a flow description normally requires
 190 quoting to prevent the shell from breaking the description into
 191 multiple arguments.)
 192
 193 The following field assignments describe how a flow matches a packet.
 194 If any of these assignments is omitted from the flow syntax, the field
 195 is treated as a wildcard; thus, if all of them are omitted, the
 196 resulting flow matches all packets.  The string \fB*\fR or \fBANY\fR
 197 may be specified to explicitly mark any of these fields as a wildcard.
 198 (\fB*\fR should be quoted to protect it from shell expansion.)
 199
 200 .IP \fBin_port=\fIport_no\fR
 201 Matches physical port \fIport_no\fR.  Switch ports are numbered as
 202 displayed by \fBovs\-ofctl show\fR.
 203
 204 .IP \fBdl_vlan=\fIvlan\fR
 205 Matches IEEE 802.1q Virtual LAN tag \fIvlan\fR.  Specify \fB0xffff\fR
 206 as \fIvlan\fR to match packets that are not tagged with a Virtual LAN;
 207 otherwise, specify a number between 0 and 4095, inclusive, as the
 208 12-bit VLAN ID to match.
 209
 210 .IP \fBdl_src=\fImac\fR
 211 Matches Ethernet source address \fImac\fR, which is specified as 6 pairs
 212 of hexadecimal digits delimited by colons (e.g. \fB00:0A:E4:25:6B:B0\fR).
 213
 214 .IP \fBdl_dst=\fImac\fR
 215 Matches Ethernet destination address \fImac\fR.
 216
 217 .IP \fBdl_type=\fIethertype\fR
 218 Matches Ethernet protocol type \fIethertype\fR, which is specified as an
 219 integer between 0 and 65535, inclusive, either in decimal or as a
 220 hexadecimal number prefixed by \fB0x\fR (e.g. \fB0x0806\fR to match ARP
 221 packets).
 222
 223 .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR]
 224 Matches IPv4 source address \fIip\fR, which may be specified as an
 225 IP address or host name (e.g. \fB192.168.1.1\fR or
 226 \fBwww.example.com\fR).  The optional \fInetmask\fR allows restricting a
 227 match to an IPv4 address prefix.  The netmask may be specified as a dotted
 228 quad (e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block
 229 (e.g. \fB192.168.1.0/24\fR).
 230
 231 .IP \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR]
 232 Matches IPv4 destination address \fIip\fR.
 233
 234 .IP \fBnw_proto=\fIproto\fR
 235 Matches IP protocol type \fIproto\fR, which is specified as a decimal
 236 number between 0 and 255, inclusive (e.g. 6 to match TCP packets).
 237
 238 .IP \fBtp_src=\fIport\fR
 239 Matches UDP or TCP source port \fIport\fR, which is specified as a decimal
 240 number between 0 and 65535, inclusive (e.g. 80 to match packets originating
 241 from a HTTP server).
 242
 243 .IP \fBtp_dst=\fIport\fR
 244 Matches UDP or TCP destination port \fIport\fR.
 245
 246 .IP \fBicmp_type=\fItype\fR
 247 Matches ICMP message with \fItype\fR, which is specified as a decimal
 248 number between 0 and 255, inclusive.
 249
 250 .IP \fBicmp_code=\fIcode\fR
 251 Matches ICMP messages with \fIcode\fR.
 252
 253 .PP
 254 The following shorthand notations are also available:
 255
 256 .IP \fBip\fR
 257 Same as \fBdl_type=0x0800\fR.
 258
 259 .IP \fBicmp\fR
 260 Same as \fBdl_type=0x0800,nw_proto=1\fR.
 261
 262 .IP \fBtcp\fR
 263 Same as \fBdl_type=0x0800,nw_proto=6\fR.
 264
 265 .IP \fBudp\fR
 266 Same as \fBdl_type=0x0800,nw_proto=17\fR.
 267
 268 .IP \fBarp\fR
 269 Same as \fBdl_type=0x0806\fR.
 270
 271 .PP
 272 The \fBadd-flow\fR and \fBadd-flows\fR commands require an additional field:
 273
 274 .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
 275 Specifies a comma-separated list of actions to take on a packet when the
 276 flow entry matches.  If no \fItarget\fR is specified, then packets
 277 matching the flow are dropped.  The \fItarget\fR may be a decimal port
 278 number designating the physical port on which to output the packet, or one
 279 of the following keywords:
 280
 281 .RS
 282 .IP \fBoutput\fR:\fIport\fR
 283 Outputs the packet on the port specified by \fIport\fR.
 284
 285 .IP \fBnormal\fR
 286 Subjects the packet to the device's normal L2/L3 processing.  (This
 287 action is not implemented by all OpenFlow switches.)
 288
 289 .IP \fBflood\fR
 290 Outputs the packet on all switch physical ports other than the port on
 291 which it was received and any ports on which flooding is disabled
 292 (typically, these would be ports disabled by the IEEE 802.1D spanning
 293 tree protocol).
 294
 295 .IP \fBall\fR
 296 Outputs the packet on all switch physical ports other than the port on
 297 which it was received.
 298
 299 .IP \fBcontroller\fR:\fImax_len\fR
 300 Sends the packet to the OpenFlow controller as a ``packet in''
 301 message.  If \fImax_len\fR is a number, then it specifies the maximum
 302 number of bytes that should be sent.  If \fImax_len\fR is \fBALL\fR or
 303 omitted, then the entire packet is sent.
 304
 305 .IP \fBlocal\fR
 306 Outputs the packet on the ``local port,'' which corresponds to the
 307 \fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in
 308 \fBovs\-openflowd\fR(8) for information on the \fBof\fIn\fR network device).
 309
 310 .IP \fBdrop\fR
 311 Discards the packet, so no further processing or forwarding takes place.
 312 If a drop action is used, no other actions may be specified.
 313
 314 .IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR
 315 Modifies the VLAN id on a packet.  The VLAN tag is added or modified
 316 as necessary to match the value specified.  If the VLAN tag is added,
 317 a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set
 318 this).
 319
 320 .IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR
 321 Modifies the VLAN priority on a packet.  The VLAN tag is added or modified
 322 as necessary to match the value specified.  Valid values are between 0
 323 (lowest) and 7 (highest).  If the VLAN tag is added, a vid of zero is used
 324 (see the \fBmod_vlan_vid\fR action to set this).
 325
 326 .IP \fBstrip_vlan\fR
 327 Strips the VLAN tag from a packet if it is present.
 328
 329 .IP \fBmod_dl_src\fB:\fImac\fR
 330 Sets the source Ethernet address to \fImac\fR.
 331
 332 .IP \fBmod_dl_dst\fB:\fImac\fR
 333 Sets the destination Ethernet address to \fImac\fR.
 334
 335 .IP \fBmod_nw_src\fB:\fIip\fR
 336 Sets the IPv4 source address to \fIip\fR.
 337
 338 .IP \fBmod_nw_dst\fB:\fIip\fR
 339 Sets the IPv4 destination address to \fIip\fR.
 340
 341 .IP \fBmod_tp_src\fB:\fIport\fR
 342 Sets the TCP or UDP source port to \fIport\fR.
 343
 344 .IP \fBmod_tp_dst\fB:\fIport\fR
 345 Sets the TCP or UDP destination port to \fIport\fR.
 346 .RE
 347
 348 .IP
 349 (The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does
 350 not yet expose to the user.)
 351
 352 .PP
 353 The \fBadd-flow\fR, \fBadd-flows\fR, and \fBdel-flows\fR commands
 354 support an additional optional field:
 355
 356 .IP \fBpriority=\fIvalue\fR
 357 The priority at which a wildcarded entry will match in comparison to
 358 others.  \fIvalue\fR is a number between 0 and 65535, inclusive.  A higher
 359 \fIvalue\fR will match before a lower one.  An exact-match entry will always
 360 have priority over an entry containing wildcards, so it has an implicit
 361 priority value of 65535.  When adding a flow, if the field is not specified,
 362 the flow's priority will default to 32768.
 363
 364 .PP
 365 The \fBadd-flow\fR and \fBadd-flows\fR commands support additional
 366 optional fields:
 367
 368 .TP
 369 \fBidle_timeout=\fIseconds\fR
 370 Causes the flow to expire after the given number of seconds of
 371 inactivity.  A value of 0 prevents a flow from expiring due to
 372 inactivity.  The default is 60 seconds.
 373
 374 .IP \fBhard_timeout=\fIseconds\fR
 375 Causes the flow to expire after the given number of seconds,
 376 regardless of activity.  A value of 0 (the default) gives the flow no
 377 hard expiration deadline.
 378
 379 .PP
 380 The \fBdump-flows\fR, \fBdump-aggregate\fR, \fBdel-flow\fR
 381 and \fBdel-flows\fR commands support one additional optional field:
 382
 383 .TP
 384 \fBout_port=\fIport\fR
 385 If set, a matching flow must include an output action to \fIport\fR.
 386
 387 .PP
 388 The \fBdump-flows\fR and \fBdump-aggregate\fR commands support an
 389 additional optional field:
 390
 391 .IP \fBtable=\fInumber\fR
 392 If specified, limits the flows about which statistics are gathered to
 393 those in the table with the given \fInumber\fR.  Tables are numbered
 394 as shown by the \fBdump-tables\fR command.
 395
 396 If this field is not specified, or if \fInumber\fR is given as
 397 \fB255\fR, statistics are gathered about flows from all tables.
 398
 399 .SS "Table Entry Output"
 400
 401 The \fBdump-tables\fR and \fBdump-aggregate\fR commands print information
 402 about the entries in a datapath's tables.  Each line of output is a
 403 unique flow entry, which begins with some common information:
 404
 405 .IP \fBduration\fR
 406 The number of seconds the entry has been in the table.
 407
 408 .IP \fBtable_id\fR
 409 The table that contains the flow.  When a packet arrives, the switch
 410 begins searching for an entry at the lowest numbered table.  Tables are
 411 numbered as shown by the \fBdump-tables\fR command.
 412
 413 .IP \fBpriority\fR
 414 The priority of the entry in relation to other entries within the same
 415 table.  A higher value will match before a lower one.
 416
 417 .IP \fBn_packets\fR
 418 The number of packets that have matched the entry.
 419
 420 .IP \fBn_bytes\fR
 421 The total number of bytes from packets that have matched the entry.
 422
 423 .PP
 424 The rest of the line consists of a description of the flow entry as
 425 described in \fBFlow Syntax\fR, above.
 426
 427
 428 .SH OPTIONS
 429 .TP
 430 \fB--strict\fR
 431 Uses strict matching when running flow modification commands.
 432
 433 .so lib/ssl.man
 434 .so lib/vlog.man
 435 .so lib/common.man
 436
 437 .SH EXAMPLES
 438
 439 The following examples assume that an OpenFlow switch on the local
 440 host has been configured to listen for management connections on a
 441 Unix domain socket named \fB@RUNDIR@/openflow.sock\fR, e.g. by
 442 specifying \fB--listen=punix:@RUNDIR@/openflow.sock\fR on the
 443 \fBovs\-openflowd\fR(8) command line.
 444
 445 .TP
 446 \fBovs\-ofctl dump-tables unix:@RUNDIR@/openflow.sock\fR
 447 Prints out the switch's table stats.  (This is more interesting after
 448 some traffic has passed through.)
 449
 450 .TP
 451 \fBovs\-ofctl dump-flows unix:@RUNDIR@/openflow.sock\fR
 452 Prints the flow entries in the switch.
 453
 454 .SH "SEE ALSO"
 455
 456 .BR ovs\-appctl (8),
 457 .BR ovs\-controller (8),
 458 .BR ovs\-vswitchd (8)