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       $ show flow entry
  55
  56 It is a vnet/flow command, used in VPP CLI. It can show the added flow rules
  57 after using the above commands. Users can get the flow index with this command
  58 and use it to delete the flow rule.
  59
  60 ParseGraph
  61 ----------
  62
  63 Packetforge is built based on a ParseGraph. The ParseGraph is constructed
  64 with nodes and edges. Nodes are protocols, including information about
  65 protocol's name, fields and default values. Edges are the relationship
  66 between two protocols, including some actions needed when connecting two
  67 protocols. For example, change the mac header ethertype to 0x0800 when
  68 connecting mac and ipv4. More details are in the Spec in parsegraph folder.
  69 Users can build the ParseGraph following the spec by themselves, like
  70 adding a new protocol. If NIC supports the new protocol, the rule can be
  71 created. Otherwise, it will return error.