summaryrefslogtreecommitdiffstats
path: root/extras/packetforge/README.rst
diff options
context:
space:
mode:
authorTing Xu <ting.xu@intel.com>2022-04-24 06:14:25 +0000
committerDave Wallace <dwallacelf@gmail.com>2022-09-20 20:44:42 +0000
commitce4b6451787389c5b0ebfac413c350ef3a424b8b (patch)
treeaa777368e14fca9b6613f747817331336ca2b11b /extras/packetforge/README.rst
parentf5e0a17c9cca09822296a0ed3196fde36c1ca5f8 (diff)
packetforge: add packetforge for generic flow to extras
Add a new tool packetforge to extras. This tool is to support generic flow. Packetforge is a library to translate naming or json profile format flow pattern to the required input of generic flow, i.e. spec and mask. Using python script flow_create.py, it can add and enable a new flow rule for an interface via flow VAPI, and can delete an existed flow rule as well. Command examples are shown below. Json profile examples can be found in ./parsegraph/samples. Naming format input: python flow_create.py --add -p "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()" -a "redirect-to-queue 3" -i 1 python flow_create.py --del -i 1 -I 0 Json profile format input: python flow_create.py -f "./flow_rule_examples/mac_ipv4.json" -i 1 With this command, flow rule can be added or deleted, and the flow entry can be listed with "show flow entry" command in VPP CLI. Packetforge is based on a parsegraph. The parsegraph can be built by users. A Spec can be found in ./parsegraph as guidance. More details about packetforge are in README file. Type: feature Signed-off-by: Ting Xu <ting.xu@intel.com> Change-Id: Ia9f539741c5dca27ff236f2bcc493c5dd48c0df1
Diffstat (limited to 'extras/packetforge/README.rst')
-rw-r--r--extras/packetforge/README.rst71
1 files changed, 71 insertions, 0 deletions
diff --git a/extras/packetforge/README.rst b/extras/packetforge/README.rst
new file mode 100644
index 00000000000..f477c0bab38
--- /dev/null
+++ b/extras/packetforge/README.rst
@@ -0,0 +1,71 @@
+.. _packetforge_doc:
+
+Packetforge for generic flow
+============================
+
+Packetforge is a tool to support generic flow. Since the input format of
+generic flow is hard to read and create, packetforge can help to create
+generic flow rules using a format of naming protocols (like Scapy) or json
+profile. Packetforge is built based on a parsegraph, users can modify the
+graph nodes and edges if needed.
+
+Command examples
+----------------
+
+::
+
+ $ python flow_create.py --add -p "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
+ -a "redirect-to-queue 3" -i 1
+
+ $ python flow_create.py --add
+ --pattern "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
+ --actions "redirect-to-queue 3" --interface 1
+
+ $ python flow_create.py --del -i 1 -I 0
+
+ $ python flow_create.py --del --interface 1 --flow-index 0
+
+Naming format input. There are two operations, add and delete flow rules.
+For add, it needs three parameters. Pattern is similar to Scapy protocols.
+Actions is the same as vnet/flow command. Interface is the device to which
+we want to add the flow rule. For delete, flow index is the index of the
+flow rule we want to delete. We can get the index number when we add the
+flow or use command to show the existed flow entry in CLI.
+
+::
+
+ $ python flow_create.py --add -f "./flow_rule_examples/mac_ipv4.json" -i 1
+
+ $ python flow_create.py --add --file "./flow_rule_examples/mac_ipv4.json"
+ --interface 1
+
+ $ python flow_create.py --add -f "./flow_rule_examples/mac_ipv4.json"
+ -a "redirect-to-queue 3" -i 1
+
+Json profile format input. This command takes a json profile as parameter.
+In the json profile, there will be protocols and their fields and values.
+Users can define spec and mask for each field. Actions can be added in the
+profile directly, otherwise "-a" option should be added in the command to
+specify actions. The example can be found in parsegraph/samples folder.
+Users can create their own json files according to examples and Spec.
+
+::
+
+ $ show flow entry
+
+It is a vnet/flow command, used in VPP CLI. It can show the added flow rules
+after using the above commands. Users can get the flow index with this command
+and use it to delete the flow rule.
+
+ParseGraph
+----------
+
+Packetforge is built based on a ParseGraph. The ParseGraph is constructed
+with nodes and edges. Nodes are protocols, including information about
+protocol's name, fields and default values. Edges are the relationship
+between two protocols, including some actions needed when connecting two
+protocols. For example, change the mac header ethertype to 0x0800 when
+connecting mac and ipv4. More details are in the Spec in parsegraph folder.
+Users can build the ParseGraph following the spec by themselves, like
+adding a new protocol. If NIC supports the new protocol, the rule can be
+created. Otherwise, it will return error.