X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=flowspec-xdp;a=blobdiff_plain;f=README.md;h=9ed1c187174ece2125df9b5d5cf5c742b261988d;hp=2ed249964497af1af0f46ec20b76fe04954063f3;hb=HEAD;hpb=79f6ee6a61f63356c44a8a0a170e19ec2a4f05cb

diff --git a/README.md b/README.md
index 2ed2499..9ed1c18 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,25 @@
 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.
+This utility allows you to convert flowspec rules (extracted from a local BIRD instance with birdc)
+to an XDP program. It currently supports the entire flowspec match grammar, rate limits, traffic
+action packet match counting (sample bit) and terminal bit, and traffic marking. The redirect
+community is not supported.
+
+Note that correctly sorting rules is *not* fully implemented as it requires implementing the
+flowspec wire serialization format and it may better be done inside bird/birdc. Thus, be vary
+careful using the terminal bit in the traffict action community.
+
+In addition to the communities specified in RFC 8955, two additional communities are supported which
+provide rate-limiting on a per-source basis. When the upper two bytes in an extended community are
+0x8306 (rate in bytes) or 0x830c (rate in packets), we rate limit the same as 0x8006 or 0x800c
+except that the rate limit is applied per source address. The encoding mirrors the non-per-source
+encoding in that the last 4 octets are the floating-point rate limit. Instead of a 2 octet
+AS/ignored value, the third octet is the maximum number of source IPs tracked (plus one, times 4096)
+and the fourth octet is a prefix length mask, which is applied to the source IP before rate-limiting.
+
+See `collision_prob.py` for collision probabilities in the hash table to estimate the size you
+should use.
 
 `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
@@ -28,7 +44,11 @@ controlled by parameters to `genrules.py` -
    * 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.
+Note that if all of the above options are set to their "drop" or "ignore" variants, 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`.
+
+Note that rate limiting is currently tracked under a single per-rule spinlock, which may be a
+bottleneck for high speed NICs with many RX queues. Adapting this to per-RX-queue/CPU limits would
+be trivial but is left as a future project.