extras/packetforge/README.rst

   1 .. _packetforge_doc:
   2
   3 Packetforge for generic flow
   4 ============================
   5
   6 Packetforge is a tool to support generic flow. Since the input format of
   7 generic flow is hard to read and create, packetforge can help to create
   8 generic flow rules using a format of naming protocols (like Scapy) or json
   9 profile. Packetforge is built based on a parsegraph, users can modify the
  10 graph nodes and edges if needed.
  11
  12 Command examples
  13 ----------------
  14
  15 ::
  16
  17      $ python flow_create.py --add -p "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
  18        -a "redirect-to-queue 3" -i 1
  19
  20      $ python flow_create.py --add
  21        --pattern "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
  22        --actions "redirect-to-queue 3" --interface 1
  23
  24      $ python flow_create.py --del -i 1 -I 0
  25
  26      $ python flow_create.py --del --interface 1 --flow-index 0
  27
  28 Naming format input. There are two operations, add and delete flow rules.
  29 For add, it needs three parameters. Pattern is similar to Scapy protocols.
  30 Actions is the same as vnet/flow command. Interface is the device to which
  31 we want to add the flow rule. For delete, flow index is the index of the
  32 flow rule we want to delete. We can get the index number when we add the
  33 flow or use command to show the existed flow entry in CLI.
  34
  35 ::
  36
  37      $ python flow_create.py --add -f "./flow_rule_examples/mac_ipv4.json" -i 1
  38
  39      $ python flow_create.py --add --file "./flow_rule_examples/mac_ipv4.json"
  40        --interface 1
  41
  42      $ python flow_create.py --add -f "./flow_rule_examples/mac_ipv4.json"
  43        -a "redirect-to-queue 3" -i 1
  44
  45 Json profile format input. This command takes a json profile as parameter.
  46 In the json profile, there will be protocols and their fields and values.
  47 Users can define spec and mask for each field. Actions can be added in the
  48 profile directly, otherwise "-a" option should be added in the command to
  49 specify actions. The example can be found in parsegraph/samples folder.
  50 Users can create their own json files according to examples and Spec.
  51
  52 ::
  53
  54      $ python flow_create.py --show -p "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
  55
  56      $ python flow_parse.py --show -p "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
  57
  58 These commands can show the forging result of spec and mask only, without invoving
  59 VPP. No need to configure actions and interfaces. Users can get the binary string
  60 of spec and mask from a flow pattern if needed. flow_parse.py can be used without
  61 VAPI installed.
  62
  63 ::
  64
  65       $ show flow entry
  66
  67 It is a vnet/flow command, used in VPP CLI. It can show the added flow rules
  68 after using the above commands. Users can get the flow index with this command
  69 and use it to delete the flow rule.
  70
  71 ParseGraph
  72 ----------
  73
  74 Packetforge is built based on a ParseGraph. The ParseGraph is constructed
  75 with nodes and edges. Nodes are protocols, including information about
  76 protocol's name, fields and default values. Edges are the relationship
  77 between two protocols, including some actions needed when connecting two
  78 protocols. For example, change the mac header ethertype to 0x0800 when
  79 connecting mac and ipv4. More details are in the Spec in parsegraph folder.
  80 Users can build the ParseGraph following the spec by themselves, like
  81 adding a new protocol. If NIC supports the new protocol, the rule can be
  82 created. Otherwise, it will return error.