TC Hash Filter

Overview

The u32 filter allows you to match on any bit field within a packet, so
it is in some ways the most powerful filter provided by the Linux
traffic control engine. It is also the most complex, and by far the
hardest to use. To explain it I will start with a bit
of a tutorial.
Matching

The base operation of the u32 filter is actually very simple. 
It extracts a bit field from a 32 bit word in the packet, and if it is
equal to a value supplied by you it has a match. The 32 bit word must
lie at a 32 bit boundry. The syntax in tc is:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    classid 1:1 \
    match u32 0xc0a80800 0xffffff00 at 12
The first line uses the same syntax shared by all filters, so I will
ignore it for now. The second line just says that if the filter matches
assign the packet to class 1:1. The third line is the interesting one;
this is what it means:
match u32   This keyword introduces a match condition.  The u32
            is the type of match.  It must be followed by a value
            and mask.  A u32 match extracts a 32 bit word out of
            the header, masks it and compares the result to the
            supplied value.  This is in fact the only type of
            match the kernel can do.  Tc "compiles" all other
            types of matches into this one.

0xc0a80800  This is the value to compare the masked 32 bit word
            to.  If it is equal to the masked word the match is
            successfull.

0xffffff00  This is the mask.  The word extracted from the
            packet is bit-wise and'ed with this mask before
            comparision.

at 12       This keyword tells the kernel where the 32 bit word
            lives in the packet.  It is an offset, in bytes,
            from the start of the packet.  So in this case
            we are loading the 32 bit word that is 12 bytes from
            the start of the packet.  The offset is optional.
            If not supplied it defaults to 0 which is generally
            not what you want.
Now if you look at rfc791 you will see that the source address is stored
at offset 12 in an IP packet. So the match condition could be read as:
"match if the packet was sent from the network 192.168.8.0/24". To use
the u32 filter you do have to be familiar
with the fields in IP and TCP, UDP and ICMP headers. But you don't have
to remember the offsets of the individual fields - tc has some syntatic
sugar for that. This command has does the same thing as the one above.
The syntax is different, but the filter submitted
to the kernel is identical:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    classid 1:1 \
    match ip src 192.168.8.0/24
A u32 filter item can logically "and" several matches together,
succeeding if only if all matches succeed. This example will succeed
only if the packet was sent from network 192.168.8.0/24, and has a TOS
of 10 hex:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    classid 1:1 \
    match ip src 192.168.8.0/24 \
    match ip tos 0x10 1e
You can have as many match conditions on the one line as you want. All must be successful for the filter item to score a match.
If you enter several tc filter commands the filters are tried in turn until one matches. For example:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    classid 1:1 \
    match ip src 192.168.8.0/24 \
    match ip tos 0x10 1e
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    classid 1:2 \
    match ip src 192.168.4.0/24 \
    match ip tos 0x08 1e
The first filter item checks if the packet is from network 192.16.8.0/24
and has a TOS of 10 hex. If so the packet is assigned to class 1:1. If
not the second filter item is tried. It checks if the packet is from
network 192.168.0.4/24 and has a TOS of 08 hex
and if so it will assign to packet to class 1:2. If not the next filier
item would be tried. But there is none, so u32 filter fails to classify
the packet.
Now it is time to discuss u32 handles. A u32 handle is actually 3
numbers, written like this: 800:0:3. They are all in hex. For now we are
only interested in the last one. This last number identifies the filter
items we have been adding. Because we did not
specify an number generated for the filter item the kernel allocated
one for us. In fact it allocated the handles 800:0:800 and 800:0:801.
The handle it generates is one bigger than the largest handle used so
far, with a minum value of 800 hex. Valid filter
item handles range from 1 to ffe hex. Like all filter handles, the
complete handle (as in 800:0:801) must be unique. We can force a
particular handle to be used for a filier item by using the "handle"
option of "tc filter", like this:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    classid 1:1 \
    match ip src 192.168.8.0/24 \
    match ip tos 0x10 1e
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 handle ::1 u32 \
    classid 1:2 \
    match ip src 192.168.4.0/24 \
    match ip tos 0x08 1e
These tc commands are almost identical to the previous example. In fact
the tc command creating the first item is identical, so it will be
allocated the same handle as before, 800:0:800. The second command only
differs from the previous example in that it specifies
item handle 1 is to be used. (The rest of the numbers in the handle are
not specified, so the defaults are used.) The full handle created for
the second filter item will be 800:0:1. The kernel evaluates filter
items in handle order, with lower handle numbers
being checked first. So the impact of doing this will be to reverse the
order they two filter items are evaluated by the kernel, compared to
the previous example.
Linking

Before proceeding we need a new concept. In effect filter items that
share the same prefix in their handle (800:0 in the above examples) form
a numbered list. The number is the filter item number, ie the last
number is the handle. In the last example above
we had a two item list with these handles:
list 800:0:
  1   [src=192.168.4.0/24, tos=0x08] -> return classid 1:2
  800 [src=192.168.8.0/24, tos=0x10] -> return classid 1:1
I will call this a u32 filter list, or just a filter list for short. The
prefix (800:0 in this case) can be used as a handle to identify the
list. In the section above I described how the kernel "executes" such a
list. To recap it does this by running through
the list in filter item number order, checking each filter item in turn
to see if it matches. If a filter item matches it can classify the
packet, in which case the u32 filter stops and returns the classified
packet. But when a u32 filter item matches a packet
there is one other thing it can do besides classifing the packet. It
can "link" to another u32 filter list. For example:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    link 1:0: \
    match ip src 192.168.8.0/24
If this filter item matches it will "link" to filter list 1:0:, meaning
the kernel will now execute filter list 1:0:. If a filter item in that
list matches and classifies a packet then the u32 stops and returns
classified packet. If that does not happen, ie
if no filter item in the list classifies the packet then the kernel
resumes executing the original list. Execution continues at the next
filter item in the original list, ie the one after the filter item that
did the "link". A linked list can in turn link
to other lists. You can nest up to 7 link commands.
If you specify a "link" command for a filter item any attempt to
classify a packet in the same filter item will be ignored. Another way
of saying this is the "classid" option and its aliases won't work if you
put "link" on the command line.
This linking is not in itself very useful. It is usually faster to use
one big list, and it always easier to do it that way. But there are two
commands you can combine with the "link" command, and in fact neither
can be used without it.
Hashing

The filter lists we have been discussing are actually part of much
larger structures called hash tables. A hash table is just an an array
of things that I will call buckets. A bucket contains one thing: a
filter list. This will all become clear shortly, I hope.
We can now look at the meanings of the other two numbers in a u32 filter
handle. One handle in the examples above was 800:0:1. Well, the 800
identifies the hash table, and the 0 is the bucket within that hash
table. So 10:20:30 means: filter item 30, which
is located in bucket 20, which is located in hash table 10.
Hash table 800 is special. It is called the root. When you create a u32
filter the root hash table gets created for you automaically. It always
has exactly one bucket, numbered 0. This means the root hash table also
exactly one filter list associated with it.
When the u32 filter starts execution it always executes this filter
list. In other words a u32 filter does its thing by executing filter
list 800:0. If filter list 800:0 does not classify the packet (implying
that none of the lists it linked to clasified it
either) then the u32 filter returns the packet unclassified.
Not unsurprisingly you can't delete the root hash table. Actually you
can't delete any other hash table either (as of 2.4.9), but that is
because of a bug in the in the kernel u32 filter's reference counting
code. The only way to get rid of a hash table in
2.4.9 or earlier is to delete the entire u32 filter.
Hash tables other than the root must be created before you can add
filter items that link to them. Use this tc command to create hash
table:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 handle 1: u32 \
    divisor 256
This creates a hash table with 256 buckets. The buckets are numbered 0
through to 255. So we have effectively created 256 filter lists with
handles 1:0, 1:1, ... 1:255. A hash table can have 1, 2, 4, 8, 16, 32,
64, 128 or 256 buckets. Other values are possible
but can be very inefficient. The kernel has a bug that will allow you
to have 257 buckets, but doing that may cause an oops.
If you omit the "handle" option the kernel will allocate you a new
handle. Currently (2.4.9) the kernel has a bug - the handle allocation
routing will go infinite rather than return failure in the very unlikely
circumstance that all hash table handles are in
use.
The way the tc "link" option is written it might appear that you can
link to any bucket. You can't. The link option only allows you to
specify bucket 0 (implying that "link 1:1" is illegal). To select a
bucket other than 0 you must use the "hashkey" option:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    link 1: hashkey mask ffffff00 at 12 \
    match ip src 192.168.8.0/24
The hashkey option causes the kernel to calculate the bucket number of
the filter list to link to from data in the packet. You get to specify
what data. This operation is usually called a hashing. In this case the
hash it is a particularly fast but primitive
one. In the example above this is what happens, in detail, if the match
succeeds:
The kernel reads the 32 bit word at offset 12 of the packet being sent.
This word is masked with ffffff00
The word is left shifted by 8 bits, and them masked with 0xff. The
amount of left shift is calculated from the mask - it is the number of
bits the mask has to be shifted so the first 1 bit appears in the least
significant bit. The is the "hashing function".
It changed between 2.4 and 2.6. In 2.4 the 4 bytes in the word are
xor'ed together. From what I have seen, the 2.4 version did a better job
on real data.
The result of the hash, which is a number in the range 0..255, is then masked with (number of buckets - 1).
The result is a bucket number, which is then combined with the hash table in the link option to form a filter list handle.
That filter list is then executed.
If you look at rfc791 you will see the hash in the example is selecting
the senders network address. Tc offers no syntatic sugar to help you
this time, ie there is no "hashkey ip src 0.0.0.0/24" or similar. You to
do it the hard way and look up the rfc's.
Why would you hash on the source network rather than testing for it in a
match option? Its only useful if you want to classify a packet based on
a lot of different source networks. If there is only one or two source
networks you are better off using match as
doing a couple of matches is faster than doing a hash. But, the amount
of time required to test all the matches will grow as number of source
networks grows. Hashing on the other hand takes a fixed amount of time
regardless whether there is 1 or 100 source
networks, so if there are thousand's of source networks hashing is
going to be literally 100's of times faster than testing them one by one
using matching.
I mention this because there is an example from Alexey's
"README.iproute2+tc" that selected the TCP protocol (among others) using
hashing. As an example of how to use hashing it is good, but it has
been cut and pasted by every man + dog, altered to only select
the TCP protocol, and then quoted as the way to do it. Wrong. A simple
"link" without hashing would be better in that case.
We have dealt with one side of hashing - how the filter list to be
executed (hash table, bucket) is selected. There is a second side to it -
adding items to the selected filter list. The problem is really quite
simple - which one is it? You know the hash table
number, it is the bucket number that is the problem. You could use the
description of the hashing algroithm above and manually calculate the
bucket number. That is a bad option for two reasons. Firstly, its hard
work in the general case. Secondly its fragile,
because the hashing algroithm in the kernel can and has changed. Tc can
calculate the hash for you, and it is better and easier to let it do
so. Letting Tc do this does not effect time it takes the kernel to
execute the filter. Here is how you do it:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    classid 1:2 \
    ht 1: sample ip src 192.168.8.0/8 \
    match ip src 192.168.8.0/8 \
    match ip tos 0x08 1e
Caveat: as of 07/Feb/2006, the hashing algorithm in tc is still at the
2.4 version(!). Ergo, for 2.6 tc ends up with the wrong answer, so this
example above won't work until this bug is fixed.
The line in question is the third one - the rest we have seen before.
The "ht 1:" says the filter item is to be inserted into hash table 1::.
The "sample ..." says what value we want to calculate has bucket number
for, ie we want that value to be hashed. Tc
will apply the same hashing algorithm used by the kernel to calculate
the bucket number. The "..." can be anything that could legally follow a
"match" option, so all the syntatic sugar for calculating IP offsets is
available to you.
There is, unfortunately, three bugs in the current version of "tc" (ie
tc up until cvs 2006-02-09), which render "sample" useless. Firstly,
"sample" assumes the target hash table has 256 buckets. If it doesn't,
you are out of luck - you must use the "ht" option
instead. Secondly, the "sample" option always uses the 2.4 kernel
hashing function. Ie, it doesn't work on 2.6 kernels. Finally, the
"sample" parsing code in "tc" has a bug (a missing memset()), which
causes tc to get segmentation violations. This last bug
renders it completely useless.
Now for some random points. First of all, why did I not use the "handle"
option of tc to specify the hash table, as is done everywhere else?
Answer: because you must give the "ht" option. You can also give the
"handle" option, but if you do the hash table number
in it must be blank, (as in ::1), or be equal to the hash table given
in the "ht" option. Is there a good reason why tc and the kernel work
like this? No, not that I can see.
Secondly, why is the fourth line required in the command? First of all,
perhaps isn't obvious why it may not be required. It may not be needed
because the "sample" option has already selected the filter list for
this source network. If no other source networks
hash this this same bucket there is indeed no reason to for the match
command. But if several source networks hash to the same bucket it is
required - the filter won't work without it. If you are hashing for a
good reason, ie to speed up the process of selecting
among many possibilities, and you are being conservative, ie you assume
you don't know the internals of the hashing algroithm, then you can
never be sure that each bucket will only have one filter item. So this
match line should always be present.
Thirdly, there are many examples on the net that hash on the IP
protocol, then selects protocol 6 directly using "ht 1:6:" rather than
using the "sample" option. Should I copy that? Answer: No. This example
should sound familiar. It is the same cut & paste
(aka hack, because they always try to improve the example) from
Alexey's "README.iproute2+tc" file I referred to earlier. In that
example Alexey assumed he knew how the hashing algroithm worked. It
probably sounded like a reasonable assumption to him - he
designed and coded the algorithm. But it is not a good assumption for
the rest of us. He did this because under the current hashing algorithm
the value is trival to calculate under some circumstances. If you are
selecting one byte from the packet on a byte
boundry, and use a hash table 256 elements long, then the byte always
hashes to itself. The IP protocol byte meets those conditions.
Fourthly, should I allocate my own handles to filter items in a hash
bucket? Answer: Avoid it if possible. You can manually allocate filter
item numbers using the handle option, as in "handle ::1". If you do so
be sure to allocate a unique filter item number
to each filter item in the hash table (as opposed to unique to just the
bucket the filter item lives it). You have to do this if you assume (as
you should) that you don't know what bucket the filter item is going to
hash to. But, as I said earlier, avoid it
if possible. You would not be hashing if there weren't a lot of filter
items to choose from. And if there are a lot of them doing your own
filter item numbering will be painful.
Header Offsets

The IP header (and other headers) are variable length. This creates a
problem if you are trying to use "match" to look at a value in a header
that follows - you don't know where it is. It is not an impossible
problem because every header in an IP packet contains
a length field. The "header offsets" feature of u32 allows you to
extract that length from the packet, and then add it to the offset
specified in the "match" option.
Here is how it works. Recall that the match option looks like this:
match u32 VALUE MASK at OFFSET
I said earlier that OFFSET tells the kernel which word in the packet to
compare to VALUE. That statement was a simplification. Two other values
can be added to OFFSET to determine which word to use. Both those values
start off as 0, but they can be modified
when a "link" option calls another filter list. Any modification made
only applies while called filter list is being executed as the old
values are restored if the called filter list fails to classify the
packet. Here are the two values and the names I call
them:
permoff     This value is unconditionally added to every OFFSET
            that is done in the destination link, ie that one
            that is called.  This includes calculations of new
            permoff's and tempoff's.  Permoff's are cumulative
            in that if the destination link calls another link
            and calculates a new permoff, the result is added to
            this one.

tempoff     A "match" option in the destintaion link can optionally
            add this value its OFFSET.  Tempoff's are temporary, in
            that it does not apply to any links the destination link
            calls.  It also does not effect the calculation of
            OFFSET's for new permoff's and tempoff's.
Time for an example. Consider this command:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    link 1: offset at 0 mask 0f00 shift 6 plus 0 eat \
    match ip protocol 6 ff
The match extression selects tcp packets (which is IP protocol 6). If we
have protocol 6 we execute filter 1:0. Now for the rest of it:
offset  This signals that we want to modify permoff or tempoff
        if the link is executed.  If this is not present,
        neither permoff nor tempoff are effected - in other
        words the target of the link inherits the current
        permoff and tempoff.

at 0    This says the 16 bit word that contains the value we
        are going to use to calculate permoff or tempoff lives
        offset 0 the IP packet - ie at the start of the packet.
        This offset must be even.  If not specified 0 is used.

mask 0f00   This mask (which is in hex) is bit-wise anded with the
            16 bit word extracted from the packet header.  It
            isolates the header length from the rest of the
            information in the word.  If not specified 0 is used
            for the extracted value.

shift 6     This says the word extracted is to be divided by 32
            after being masked.  If not present the value is not
            shifted.

plus 0      After extracting the word, masking it and dividing it by
            32, this value is now added to it.  If not present is
            assumed to be 0.

eat         If this is present we are calculating permoff, and the
            result of the calculation above is added to it.  Tempoff
            is set to 0 in this case.  If this is not present we are
            calculating tempoff, and the result of the calculation
            becomes tempoff's new value.  Permoff is not altered in
            this case.
If you don't understand this then accept at face value that it does
calculate the position of the second header in an IP packet. Copy &
paste it into your scripts. I am not going to try and explain it
further. You should of course dig out rfc791 and verify
it for yourself. That way you will be able to apply it to headers
beyond the second one.
Having calculated your offset you can now add entries to the destination
filter list that depend on it. Here is an example entry:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    classid 1:4 \
    ht 1:0 \
    match u32 0x140000 ffff0000 at nexthdr+0
We have see almost all of this before. "ht 1:0" inserts this filter item
into hash table 1, bucket 0. "classid 1:4" classifies the packet if the
filter matches. The "match" selects protocol 14 hex (which is 20
decimal - ftp). The "at nexthdr+0" is the only
new bit, or at least the "nexthdr+" is new. The "0" sort of means the
same thing as it always did - that the 32 bit word that contains the TCP
port is at offset 0. But it is offset 0 from the TCP header, because
either permoff of tempoff has been set to point
to that header. As for "nexthdr+", recall that adding "tempoff" was
optional. If you add "nexthdr+" it gets added. If you don't it doesn't.
Tc does supply syntatic sugar for this as well. I could of written this way, and generated an identical filter item:
# tc filter add dev eth0 parent 999:0 protocol ip prio 99 u32 \
    classid 1:4 \
    ht 1:0 \
    match tcp protocol 6 ff
Recall that I said modification made to permoff and tempoff only applies
while called filter list is being executed as the old values are
restored if the called filter list fails to classify the packet. This
was a lie. Permoff is restored, but tempoff isn't.
This can make for subtle suprises in the way a U32 filter executes,
because you tend to assume that during the execution of a filter list
permoff and tempoff never change. But if you link to another list
tempoff may change. I recommend always using permoff's
(ie, always specify "eat", and never use "nexthdr+") to avoid this.
Reference

Handles

The u32 filter uses 3 numbers for its handle. These numbers are written:
H:B:I, eg 1:1:2. All are in hex. The first number, H, identifies a hash
table. The second number, B, identifies a bucket within the hash table,
and the third number, I, identifies the
filter item within the bucket. The combination must be unique.
Hash table numbers must lie between 001 and fff hex. The traffic control
engine will generate a hash table number for you if you don't supply
one. Generated numbers are 800 or above. The hash table number in the
handle is not used when creating or changing
a hash table item. Instead the hash table specified by the "ht" option
is used, and the hash table in the handle must be not specified, 0, or
equal to the hash table in the "ht" option.
A bucket number can range from 0 to 1 less than then number of buckets
in the parent hash table. If no bucket is specified (as in 1::2), then 0
is assumed.
Filter Item numbers must lie between 001 and fff hex. The traffic
control engine will generate a filter item number for you if you don't
supply one. The generated number is the larger of 800 and one bigger
than the current largest item number in the bucket.
Execution

Each "tc filter add ... u32" item adds either a hash table, or adds a
filter item to a bucket within a hash table. When a u32 filter is
created the root hash table, whose handle is 800::, is automatically
created. It has one bucket. The u32 starts by checking
each filter item in bucket 0 of the root hash table. Filter items
within a bucket are always checked in filter item number order. As soon
as a filter item classifies the packet the u32 filter stops execution.
Filter items may use the "link" option to execute
a filter item list held by a bucket in another hash table.
Options

classid :<classify-spec>: | flowid :<classify-spec>:
  If all the match options succeed then this will :classify:
  the packet and the u32 filter will stop execution.  Ignored
  if "link" option is given.

divisor <NUMBER>
  If supplied this parameter must appear on its own, without
  any other arguments.  It creates a new hash table.  <NUMBER>
  specifies the number of buckets in the hash table.  It can
  range from 1 to 256, and should be a power of 2.  The hash
  table number is taken from the handle supplied.  If no handle
  is supplied a new hash table number is generated.

hashkey mask <MASK> at <AT>
  If the link specified by the "link" option is taken then this
  option specifies the bucket within the hash table to use.  This
  is how the bucket number is calculated:
  1.  The 32 bit work at offset <AT> is read from the packet.
  2.  The 32 word is masked with <MASK>.  <MASK> is in hex.
  3.  The 4 bytes in the result are xor'ed together.
  4.  The result is bit-wise anded with the value (number of
      buckets in the hash tabled linked to - 1).

ht <HASHTABLE-HANDLE>
  This option specifies the handle of a filter item being added
  or changed.  The filter item in <HASHTABLE-HANDLE> must be
  unspecified or 0 - it can only be specified by the "handle"
  option.  The bucket specified may be overridden by the "sample"
  option.

link <HASHTABLE-HANDLE>
  If all match options succeed in this filter item the "link"
  option causes the filter items in another hash table's bucket to
  be checked.  If none of the filter items in the linked to bucket
  classify the item then u32 filter continues checking filter
  items in the current bucket.  The "link"ed to bucket may link to
  yet another bucket, to a maximum level of 7 such calls (in 2.4.9
  .. 2.6.15).  The <HASHTABLE-HANDLE> specifies the hash table to
  link to.  The bucket and filter item numbers in that handle must
  both be unspecified or blank.  Bucket 0 will be used unless
  overridden by the "hashkey" option.  The "offset" option can be
  used to alter packet offsets in the linked to bucket.

match <selector>
  This option checks if a field in the packet has a particular
  value.  A filter item may contain more than one "match" option.
  All match options must be satisified before the filter item
  considers it has a match.  What the filter item does when it
  has a match is specified by the "link", "classid"/"flowid", and
  "police" options.  If none are specified the filter item does
  nothing when it matches.  Selectors are described below.

offset mask <MASK> at <AT> shift <SHIFT> plus <PLUS> eat
  If the link specified by the "link" option is taken then the
  position of the values extracted from the packet by the hash
  table linked to will be offset by this specification.  This is
  how the offset is evaluated & implemented:
  1.  The 16 bit word at offset <AT> is read from the packet.  If
      <AT> is not present the 16 bit work is read from offset 0.
  2.  The 16 bit word is masked with <MASK>.  If no masked is
      specified 0 is assumed.
  3.  The masked 16 bit word is divided by (2**<SHIFT>).
  4.  The resulting value has <PLUS> added to it.  If not specified
      <PLUS> defaults to 0.
  5.  If none of <MASK>, <AT>, <SHIFT>, nor <PLUS> are specified
      then the current temporary offset is used.
  6.  If "eat" is specified the offset is permanent, and is added
      to the current permanant offset.  The permanent offset is
      unconditionally added to the <AT> value in "match", "offset"
      and "hashkey" options in the hash table linked to, and any
      nested links.  If "eat" is not specified the offset is
      temporary.  Temporary offsets any added to the "at
      nexthdr+<AT>" values in "match" options, but do not effect
      any other <AT> values.
  7.  If then specified does not classify the packet, and hence
      execution resumes at the next filter item, then the permanent
      offset calculated here is discarded.  The temporary offset,
      however, remains in effect.
  8.  When the u32 filter starts executing both the permanent and
      temporary offset are initialised to 0.

police <police-spec>
  If all the match options succeed then this will :police: the
  packet and the u32 filter will stop execution.  Ignored if "link"
  option is given.

sample <selector>
  This option computes the bucket for the filter item being or
  changed from the <selctor> passed.  The packet offset and
  mask parts of the selector are ignored if given.  When
  calculating the hash bucket, the divisor in the target hash
  bucket is assumed to be 256.  There is no way of altering
  this.  If the divisor isn't 256, use the "ht" option instead.
  Selectors are described below.
Selectors

Selectors are used by the match option to extract information from the
packet and compare it to a value. All selectors compile to the one
format which is accepted by the kernel. This format reads a 32 value
from the supplied offset within the packet. The offset
must be on a 32 bit boundary. The value read is bit wise anded with the
supplied mask. If match succeeds if the result is equal to the supplied
value. In C:
if ((*(u32*)((char*)packet+offset+permoff) & mask) == value)
   match();
The "permoff" variable in this statement is calculated by the "offset" option that executed this filter list.
Here are some conventions which won't be repeated below for brevity:
at nexthdr+<OFFSET>
  Except where noted this can be appended to all selectors to
  override the default position of the field in the packet.  The
  <OFFSET> is the offset within the packet where the field can
  be found.  If an 16 bit value is being compared the <OFFSET>
  should be on a 16 bit boundary, and if a 32 bit value is being
  compared if should be on a 32 bit boundary.  The <OFFSET> is
  given in decimal; prefix with 0x to enter it in hex.  If
  "nexthdr+" is present any temporary offset calculated by the
  "offset" option is added to <OFFSET>.  The current permanent
  offset calculated by the "offset" optional is unconditionally
  added to <OFFSET>.  It is unlikely you will want to specify
  the "at" option with anthing other than u32, u16 and u8
  selectors.

<IP6ADDR>/<CIDR>
  This specifies set of up to 4 32 bit masks and values that
  will match a 128 bit IPv6 address.  The combined values equal
  the IPv6 address supplied, which may be in any IPv6 address
  format.  The combined masks are derived from the <CIDR>
  portion - it is a 128 bit word with the upper <CIDR> bits
  set to 1's, the rest are 0's.  If the HOST is not given the
  host is all 1's.  The IP address must be numeric.

<IPADDR>/<CIDR>
  This specifies a mask and value.  The value is equal to the
  IPv4 address supplied.  The mask is derived from the
  <CIDR> portion - it is a 32 bit word with the upper
  <CIDR> bits set to 1's, the rest are 0's.  If <CIDR>
  is not given the mask is all 1's.  The IP address must be
  numeric.  For example, 192.168.10.0/24 would yield a value
  of c0a80a00 hex and a mask of ffffff00 hex.

<MASK>
  This specifies a mask value the field will be bit wise anded
  with before being compared to <VALUE>.  It is given in hex.

<VALUE>
  This specifies the value the field extracted from the packet
  must equal, after being anded with the <MASK>.  It is decimal,
  unless prefixed with 0x, in which case it is hex.  Ie 0x10 and
  16 both mean the same thing.
Here are the selectors that can follow a "match" or "sample" option:
icmp code <VALUE> <MASK>
  Match the 8 bit code field an the icmp packet.  This must
  be in a hash table that is "link"ed to by a filter item which
  contains an "offset" option that skips the IP header.

icmp type <VALUE> <MASK>
  Match the 8 bit type field an the icmp packet.  This must be
  in a hash table that is "link"ed to by a filter item which
  contains an "offset" option that skips the IP header.

ip df
  Matches if the IPv4 packet has the "don't fragment" bit set.
  May not be followed by an "at" option.

ip dport <VALUE> <MASK>
  Matches the 16 bit desination port in a tcp or udp IPv4 packet.
  This only works if the ip header contains no options.  Use the
  "link" and "match tcp dst" or "match udp dst" option if you can
  not be sure of that.

ip dst <IPADDR>/<CIDR>
  Matches the destination IP address of an IPv4 packet.

ip firstfrag
  Matches is this IPv4 packet is not fragmented, or it the first
  first fragment.

ip icmp_code <VALUE> <MASK>
  Matches the 8 bit code field in icmp IPv4 packet.  This only
  works if the ip header contains no options.  Use the "link"
  and "match icmp code" options if you can not be sure of that.

ip icmp_type <VALUE> <MASK>
  Matches the 8 bit type field in ICMP IPv4 packet.  This only
  works if the ip header contains no options.  Use the "link"
  and "match ip icmp" options if you can not be sure of that.

ip ihl <VALUE> <MASK>
  Matches the 8 bit ip version + header length byte in the IPv4
  header.

ip mf
  Matches if the IPv4 packet is there are more fragments from the
  same packet to follow this one.  May not be followed by an "at"
  option.

ip nofrag
  Matches if this is not a fragmented IPv4 packet.  May not be
  followed by an "at" option.

ip protocol <VALUE> <MASK>
  Matches the 8 bit protocol byte in the IPv4 header.  You can
  not use symbolic protocol names (eg "tcp" or "udp").

ip sport <VALUE> <MASK>
  Matches the 16 bit source port in a TCP or UDP IPv4 packet.
  This only works if the ip header contains no options.  Use the
  "link" and "match tcp src" or "match udp src" options if you
  can not be sure of that.

ip src <IPADDR>/<CIDR>
  Matches the source IP address of an IPv4 packet.

ip tos <VALUE> <MASK> | ip precedence <VALUE> <MASK>
  Matches the 8 bit TOS byte in the IPv4 header.

ip6 dport <VALUE> <MASK>
  Matches the 16 bit desination port in a TCP or UDP IPv6 packet.
  This only works if the ip header contains no options.  Use the
  "link" and "match ip tcp" or "match ip udp" options if you can
  not be sure of that.

ip6 dst <IP6ADDR>/<CIDR>
  Matches the destination IP address of an IPv6 packet.

ip6 icmp_code <VALUE> <MASK>
  Matches the 8 bit code field in ICMP IPv6 packet.  This only
  works if the ip header contains no options.  Use the "link" and
  "match icmp" options if you can not be sure of that.

ip6 icmp_type <VALUE> <MASK>
  Matches the 8 bit type field in an ICMP IPv4 packet.  This only
  works if the ip header contains no options.  Use the "link" and
  "match icmp" options if you can not be sure of that.

ip6 flowlabel <VALUE> <MASK>
  Matches the 32 bit flowlabel in the IPv6 header.

ip6 priority <VALUE> <MASK>
  Matches the 8 bit priority byte in the IPv6 header.

ip6 protocol <VALUE> <MASK>
  Matches the 8 bit protocol byte in the IPv6 header.  You can
  not use symbolic protocol names (eg "tcp" or "udp").

ip6 sport <VALUE> <MASK>
  Matches thw 16 bit source port in a TCP or UDP IPv6.  This only
  works if the ip header contains no options.  Use the "link" and
  "match tcp src" or "match udp src" options if you can not be sure
  of that.

ip6 src <IPADDR>/<CIDR>
  Matches the src IP address in an IPv6 packet.

tcp dst <VALUE> <MASK>
  Match the 16 bit destination port in the tcp packet.  This must
  be in a hash table is "link"ed to by a filter item which contains
  an "offset" option that skips the IP header.

tcp src <VALUE> <MASK>
  Match the 16 bit source port in the tcp packet.  This must be
  in a hash table is "link"ed to by a filter item which contains
  an "offset" option that skips the IP header.

u16 <VALUE> <MASK>
  Match a 16 bit value in the packet.  The offset defaults to 0
  which is usually not want you want, at append the "at" option
  to give the correct value.

u32 <VALUE> <MASK>
  Match a 32 bit value in the packet.  The offset defaults to 0
  which is usually not want you want, at append the "at" option
  to give the correct value.

u8 <VALUE> <MASK>
  Match a 8 bit value in the packet.  The offset defaults to 0
  which is usually not want you want, at append the "at" option
  to give the correct value.

udp dst <VALUE> <MASK>
  Match the 16 bit destination port in the udp packet.  This must
  be in a hash table is "link"ed to by a filter item which contains
  an "offset" option that skips the IP header.

udp src <VALUE> <MASK>
  Match the 16 bit source port in the udp packet.  This must be
  in a hash table is "link"ed to by a filter item which contains
  an "offset" option that skips the IP header.