-
Notifications
You must be signed in to change notification settings - Fork 192
Dpctl Documentation
Dpctl is a management utility that enable some control over the OpenFlow switch. With this tool it's possible to add flows to the flow table, query for switch features and status, and change other configurations.
A dpctl command has the following syntax
dpctl [OPTIONS] SWITCH COMMAND [ARG...]
The SWITCH argument should use one of the following active OpenFlow connection methods:
tcp:HOST[:PORT] PORT (default: 6633) on remote TCP HOST
unix:FILE Unix domain socket named FILE
fd:N File descriptor N
- Features
- Get-config and set-config
- Status description
- Table status
- Group Commands
- Meter Commands
- Port Commands
- Flow mod Commands
dpctl -h
The command above shows the available dpctl but some doubts may appear on how to use some of them. So lets's have a closer look at all commands with usage examples.
Dpctl sends a features request message to the switch, which answers with a features reply.
Usage Example
dpctl unix:/var/run/s1.sock features
The reply message should look like this.
feat_repl{dpid="0x000002d5e8cde975", buffs="256", tabs="64", aux_id="0", caps="0x4f"]}
Where dpid is the datapath identification, buffs is the number of packets the switch can buffer, tabs is the number of flow_tables, aux_id refers to the auxiliary connection id and caps is the value of the switch capabilities bitmask.
Dpctl can query and set switch configuration parameters.
Usage Example
We will query for the switch configuration. You should see the default values for the configuration flags and the maximum number of bytes of a packet, mlen, that the switch can send to the controller.
dpctl unix:/var/run/s1.sock get-config
SENDING:
conf_req
RECEIVED:
conf_repl{conf={flags="0x0", mlen="128"}}
Now we will set the switch configuration flags to 1, which means drop fragments, and increase the packet limit of bytes to send to the controller.
dpctl unix:/var/run/s1.sock set-config flags=0x1,miss=512
SENDING:
set_conf{conf={flags="0x1", mlen="512"}}
OK.
Now we query again to check the changes
dpctl unix:/var/run/s1.sock get-config
SENDING:
conf_req
RECEIVED:
conf_repl{conf={flags="0x1", mlen="512"}}
Query description of switch hardware and software, where mfr is the manufacturer description, hw is the hardware description, sw is the software description, sn is the serial number and, dp refers to the datapath description.
Usage Example
dpctl unix:/var/run/s1.sock stats-desc
SENDING:
stat_req{type="desc", flags="0x0"}
RECEIVED:
stat_repl{type="desc", flags="0x0", mfr="Stanford University, Ericsson Research and CPqD Research",
hw="OpenFlow 1.3 Reference Userspace Switch", sw="Dec 14 2012 09:52:06", sn="1", dp="OpenFlow 1.3
Reference Userspace Switch Datapath"}
Usage Example
dpctl unix:/tmp/ofd stats-table
SENDING:
stat_req{type="table", flags="0x0"}
RECEIVED:
stat_repl{type="table", flags="0x0", stats=[{table="0", active="0", lookup="305", match="0", {table="1", active="0", lookup="0", match="0", {table="2", active="0", lookup="0", match="0", {table="3", active="0", lookup="0", match="0", {table="4", active="0", lookup="0", match="0", {table="5", active="0", lookup="0", match="0", {table="6", active="0", lookup="0", match="0", {table="7", active="0", lookup="0", match="0", {table="8", active="0", lookup="0", match="0", {table="9", active="0", lookup="0", match="0", {table="10", active="0", lookup="0", match="0", {table="11", active="0", lookup="0", match="0", {table="12", active="0", lookup="0", match="0", {table="13", active="0", lookup="0", match="0", {table="14", active="0", lookup="0", match="0", {table="15", active="0", lookup="0", match="0", {table="16", active="0", lookup="0", match="0", {table="17", active="0", lookup="0", match="0", {table="18", active="0", lookup="0", match="0", {table="19", active="0", lookup="0", match="0", {table="20", active="0", lookup="0", match="0", {table="21", active="0", lookup="0", match="0", {table="22", active="0", lookup="0", match="0", {table="23", active="0", lookup="0", match="0", {table="24", active="0", lookup="0", match="0", {table="25", active="0", lookup="0", match="0", {table="26", active="0", lookup="0", match="0", {table="27", active="0", lookup="0", match="0", {table="28", active="0", lookup="0", match="0", {table="29", active="0", lookup="0", match="0", {table="30", active="0", lookup="0", match="0", {table="31", active="0", lookup="0", match="0", {table="32", active="0", lookup="0", match="0", {table="33", active="0", lookup="0", match="0", {table="34", active="0", lookup="0", match="0", {table="35", active="0", lookup="0", match="0", {table="36", active="0", lookup="0", match="0", {table="37", active="0", lookup="0", match="0", {table="38", active="0", lookup="0", match="0", {table="39", active="0", lookup="0", match="0", {table="40", active="0", lookup="0", match="0", {table="41", active="0", lookup="0", match="0", {table="42", active="0", lookup="0", match="0", {table="43", active="0", lookup="0", match="0", {table="44", active="0", lookup="0", match="0", {table="45", active="0", lookup="0", match="0", {table="46", active="0", lookup="0", match="0", {table="47", active="0", lookup="0", match="0", {table="48", active="0", lookup="0", match="0", {table="49", active="0", lookup="0", match="0", {table="50", active="0", lookup="0", match="0", {table="51", active="0", lookup="0", match="0", {table="52", active="0", lookup="0", match="0", {table="53", active="0", lookup="0", match="0", {table="54", active="0", lookup="0", match="0", {table="55", active="0", lookup="0", match="0", {table="56", active="0", lookup="0", match="0", {table="57", active="0", lookup="0", match="0", {table="58", active="0", lookup="0", match="0", {table="59", active="0", lookup="0", match="0", {table="60", active="0", lookup="0", match="0", {table="61", active="0", lookup="0", match="0", {table="62", active="0", lookup="0", match="0", {table="63", active="0", lookup="0", match="0"]}
These commands can be used to query for status, description, features and modification of the group table.
Group mod is the command utilized to modify the group table. It's possible to add, modify and delete group entries from the table.
Usage Example
The example add a group with id 1 and type all, to execute all buckets.
dpctl unix:/var/run/s1.sock group-mod cmd=add,type=all,group=1 weight=0,port=any,group=any output=1 weight=0,port=any,group=any output=2
SENDING:
grp_mod{group="1", cmd="add", type="all", buckets=[{w="0", wprt="any", wgrp="any", acts=[out{port="1"}]}, {w="0", wprt="any", wgrp="any", acts=[out{port="2"}]}]}
OK.
This command can be used to see the installed group entries in the group table.
Usage Example
dpctl unix:/var/run/s1.sock stats-group-desc
SENDING:
stat_req{type="gdesc", flags="0x0"}
RECEIVED:
stat_repl{type="gdesc", flags="0x0", stats=[{type="all", group="1", buckets=[{w="0", wprt="any", wgrp="any", acts=[out{port="1"}]}, {w="0", wprt="any", wgrp="any", acts=[out{port="2"}]}]}]}
The stats-group command is utilized to get group entries statistics.
Usage Example
dpctl unix:/var/run/s1.sock stats-group
SENDING:
stat_req{type="grp", flags="0x0", group="all"}
RECEIVED:
stat_repl{type="grp", flags="0x0", stats=[{group="1", ref_cnt="0", pkt_cnt="0", byte_cnt="0", cntrs=[{pkt_cnt="0", byte_cnt="0"}, {pkt_cnt="0", byte_cnt="0"}]}]}
Usage Example
dpctl dpctl unix:/var/run/s1.sock group-features
SENDING:
stat_req{type="grp_features", flags="0x0"}
RECEIVED:
stat_repl{type="grp_features", flags="0x0", types="3", capabilities="1 [all: max_groups=255, actions= out/ttl_out/mpls_ttl/vlan_psh/mpls_psh/queue/nw_ttl/set_field/, sel: max_groups=255, actions= out/ttl_out/mpls_ttl/vlan_psh/mpls_psh/queue/nw_ttl/set_field/, ind: max_groups=255, actions= out/ttl_out/mpls_ttl/vlan_psh/mpls_psh/queue/nw_ttl/set_field/, ff: max_groups=255, actions= out/ttl_out/mpls_ttl/vlan_psh/mpls_psh/queue/nw_ttl/set_field/}
The meter-mod command is utilized to add, modify or delete meter entries from the meter table.
Usage Example
The example shows the addition of a meter to limit the packet rate, in Kbps, at the rate of 10Mbps.
dpctl unix:/var/run/s1.sock meter-mod cmd=add,flags=1,meter=3 drop:rate=10000
SENDING:
meter_mod{cmd="add", flags="0x1"", meter_id="3"", bands=[{type = drop, rate="10000", burst_size="0"}]}
OK.
Usage Example
dpctl unix:/var/run/s1.sock meter-config
SENDING:
stat_req{type="mconf", flags="0x0"{meter_id= ffffffff"}
RECEIVED:
stat_repl{type="mconf", flags="0x0", stats=[{meter= 3"", flags="1", bands=[{type = drop, rate="10000", burst_size="0"}]}]}
Usage Example
dpctl unix:/var/run/s1.sock stats-meter
SENDING:
stat_req{type="mstats", flags="0x0"{meter_id= ffffffff"}
RECEIVED:
stat_repl{type="mstats", flags="0x0", stats=[{meter= 3"", flow_cnt="0", pkt_in_cnt="0", byte_in_cnt="0"duration_sec="0", duration_nsec="0", bands=[{pkt_band_cnt="0", byte_band_cnt="0"}]}]}
Usage Example
dpctl unix:/var/run/s1.sock meter-features
SENDING:
stat_req{type="mfeat", flags="0x0"}
RECEIVED:
stat_repl{type="mfeat", flags="0x0"{max_meter="256", band_types="1",capabilities ="d", max_bands = 16 , max_color = 8}}
Dpctl have commands to get port statistics, port description and to modify the port behavior.
This command sends a message requesting the ports description, with the current configurations.
Usage Example
The example gets information from all switch ports, where the no is the port index, name is the interface name, config is a bitmap of OFPPC_* flags, the state field is a bitmap of OFPPS_*, curr shows a bitmap of current port features, adv and supp are information about features being advertised and supported, peer is the features advertised by peers, and curr_spd and max_spd are the port current and max birate in kbps.
dpctl unix:/tmp/ofd port-desc
SENDING:
stat_req{type="port-desc", flags="0x0"}
RECEIVED:
stat_repl{type="port-desc", flags="0x0"{no="1", hw_addr="b2:bc:ac:8d:b4:a5", name="veth0", config="0x0", state="0x0", curr="0x840", adv="0x0", supp="0x0", peer="0x0", curr_spd="10485760kbps", max_spd="0kbps"}, {no="2", hw_addr="a2:27:7f:16:bf:1a", name="veth2", config="0x0", state="0x0", curr="0x840", adv="0x0", supp="0x0", peer="0x0", curr_spd="10485760kbps", max_spd="0kbps"}, {no="3", hw_addr="62:bf:72:3c:98:a7", name="veth4", config="0x0", state="0x0", curr="0x840", adv="0x0", supp="0x0", peer="0x0", curr_spd="10485760kbps", max_spd="0kbps"}, {no="4", hw_addr="52:1b:5d:5d:af:6c", name="veth6", config="0x0", state="0x0", curr="0x840", adv="0x0", supp="0x0", peer="0x0", curr_spd="10485760kbps", max_spd="0kbps"}, {no="local", hw_addr="26:27:e3:71:ae:00", name="tap:", config="0x0", state="0x0", curr="0x802", adv="0x0", supp="0x0", peer="0x0", curr_spd="10240kbps", max_spd="0kbps"}}}
Port mod allows the user to modify the port configuration.
Usage Example
The example changes the port behavior to no generate a packet-in message on a table miss.
dpctl unix:/var/run/s1.sock port-mod port=1,addr=b2:bc:ac:8d:b4:a5,conf=0x64,mask=0xffffffff
SENDING:
port_mod{port="1", hwaddr="b2:bc:ac:8d:b4:a5", config="0x00000064", mask="0xffffffff", adv="0x0"}
OK.
The command is utilized to show port statistics.
Usage Example
The example query the switch for port 1 statistics.
dpctl unix:/tmp/ofd stats-port 1
SENDING:
stat_req{type="port", flags="0x0", port="1"}
RECEIVED:
stat_repl{type="port", flags="0x0", stats=[{port="1", rx_pkt="64", tx_pkt="0", rx_bytes="10356", tx_bytes="0", rx_drops="0", tx_drops="0", rx_errs="0", tx_errs="0", rx_frm="0", rx_over="0", rx_crc="0", coll="0"}]}
Flow related commands, probably, will be the most utilized and are the most variable one due to the diversity of possible match fields, instructions and actions. In this page we will show only basic examples of . For a more complete list please visit the Flow-mod page in the wiki.
Flow-mod command is utilized to add, modify or delete flows.
Usage Example
dpctl unix:/var/run/s1.sock flow-mod cmd=add,table=0,idle=5,hard=300,prio=2048 in_port=2,eth_type=0x800 apply:output=1
SENDING:
flow_mod{table="0", cmd="add", cookie="0x0", mask="0x0", idle="30", hard="300", prio="2048", buf="none", port="any", group="any", flags="0x0", match=oxm{in_port="2", eth_type=0x"800"}, insts=[apply{acts=[out{port="1"}]}]}
OK.
Query for flow statistics. In the following example, the message ask for flow statistics from all tables.
Usage Example
dpctl unix:/var/run/s1.sock stats-flow
SENDING:
stat_req{type="flow", flags="0x0", table="all", oport="any", ogrp="any", cookie=0x0", mask=0x0", match=oxm{all match}}
RECEIVED:
stat_repl{type="flow", flags="0x0", stats=[{table="0", match="oxm{in_port="2", eth_type=0x"800"}", dur_s="1", dur_ns="342000", prio="2048", idle_to="30", hard_to="300", cookie="0x0", pkt_cnt="0", byte_cnt="0", insts=[apply{acts=[out{port="1"}]}]}]}
Get the aggregate status for multiple flows.
Usage Example
dpctl unix:/tmp/ofd stats-aggr
SENDING:
stat_req{type="aggr", flags="0x0", table="all", oport="any", ogrp="any", cookie=0x0", mask=0x0", match=oxm{all match}}
RECEIVED:
stat_repl{type="aggr", flags="0x0", pkt_cnt="0", byte_cnt="0", flow_cnt="0"}
There are a few number of options to be passed to dpctl, which can be used for purposes of information, increase the switch verbosity level and change default command behaviors.
-v, --verbose=MODULE[:FACILITY[:LEVEL]] set logging levels
-v, --verbose set maximum verbosity level
--log-file[=FILE] enable logging to specified FILE
(default: /usr/local/var/log/openflow/dpctl.log)
--strict use strict match for flow commands
-t, --timeout=SECS give up after SECS seconds
-h, --help display this help message
-V, --version display version information