-
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
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
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"}
table-mod stats-table
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/}
meter-config stats-meter meter-mod meter-features
stats-port port-mod port-desc
queue-get-config stats-queue
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