From: Matt Corallo Date: Sun, 4 Apr 2021 16:42:55 +0000 (-0400) Subject: Add README X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=flowspec-xdp;a=commitdiff_plain;h=79f6ee6a61f63356c44a8a0a170e19ec2a4f05cb Add README --- diff --git a/README.md b/README.md new file mode 100644 index 0000000..2ed2499 --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +FlowSpec -> XDP Conversion Utility +================================== + +This utility allows you to convert flowspec rules (exctracted from a local BIRD instance with birdc) +to an XDP program. It currently supports the entire flowspec grammar, however does not implement +community parsing to detect actions due to BIRD limitations. + +`install.sh` provides a simple example script which will compile and install a generated XDP program +from the rules in bird's `flowspec4` and `flowspec6` routing tables. It will drop any packets which +match any flowspec filter. + +`genrules.py` will accept birdc output on stdin and generate a rules.h file which is included in +xdp.c to check individual rules. The specific behavior of some less-common parsing options can be +controlled by parameters to `genrules.py` - + * --8021q can be either "drop-vlan", "accept-vlan" or "parse-vlan" to either drop all traffic with + a VLAN tag, accept all traffic with a VLAN tag (without comparing it against any flowspec rules), + or parse VLAN traffic and compare it against flowspec rules just like any other traffic. + * If --8021q is set to "parse-vlan", --require-8021q can be set to a specific VLAN tag, and all + traffic with different VLAN tags is dropped. + * --ihl can be set to "drop-options", "accept-options", or "parse-options" to drop all traffic with + extra IPv4 option fields, accept all traffic with extra IPv4 options fields (without comparing it + to any flowspec rules), or parse IPv4 traffic with option fields like normal. + * --v6frag can be set to "drop-frags","ignore","parse-frags","ignore-parse-if-rule" to: + * drop all IPv6 fragments, + * ignore IPv6 fragments, matching only the IPv6 header but no ICMP/TCP/UDP options, + * parse IPv6 fragments, matching ICMP/TCP/UDP options if relevant (eg often only in the first + fragment), or + * ignore IPv6 fragments as above, unless a flow6 rule specifies the "fragment" keyword, in which + case parse all IPv6 fragments as above for all rules. + +Note that if all of the above options are set to their "drop" variant, the parsing can avoid all +offset calculation, using static offsets for all fields. + +Drop counts are tracked in XDP per-CPU arrays, and can be viewed with `dropcount.sh`.