|
Packit Service |
3880ab |
.TH "Universal 32bit classifier in tc" 8 "25 Sep 2015" "iproute2" "Linux"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.SH NAME
|
|
Packit Service |
3880ab |
u32 \- universal 32bit traffic control filter
|
|
Packit Service |
3880ab |
.SH SYNOPSIS
|
|
Packit Service |
3880ab |
.in +8
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.BR tc " " filter " ... [ " handle
|
|
Packit Service |
3880ab |
.IR HANDLE " ] "
|
|
Packit Service |
3880ab |
.B u32
|
|
Packit Service |
3880ab |
.IR OPTION_LIST " [ "
|
|
Packit Service |
3880ab |
.B offset
|
|
Packit Service |
3880ab |
.IR OFFSET " ] [ "
|
|
Packit Service |
3880ab |
.B hashkey
|
|
Packit Service |
3880ab |
.IR HASHKEY " ] [ "
|
|
Packit Service |
3880ab |
.B classid
|
|
Packit Service |
3880ab |
.IR CLASSID " ] [ "
|
|
Packit Service |
3880ab |
.B divisor
|
|
Packit Service |
3880ab |
.IR uint_value " ] [ "
|
|
Packit Service |
3880ab |
.B order
|
|
Packit Service |
3880ab |
.IR u32_value " ] [ "
|
|
Packit Service |
3880ab |
.B ht
|
|
Packit Service |
3880ab |
.IR HANDLE " ] [ "
|
|
Packit Service |
3880ab |
.B sample
|
|
Packit Service |
3880ab |
.IR SELECTOR " [ "
|
|
Packit Service |
3880ab |
.B divisor
|
|
Packit Service |
3880ab |
.IR uint_value " ] ] [ "
|
|
Packit Service |
3880ab |
.B link
|
|
Packit Service |
3880ab |
.IR HANDLE " ] [ "
|
|
Packit Service |
3880ab |
.B indev
|
|
Packit Service |
3880ab |
.IR ifname " ] [ "
|
|
Packit Service |
3880ab |
.BR skip_hw " | "
|
|
Packit Service |
3880ab |
.BR skip_sw " ] [ "
|
|
Packit Service |
3880ab |
.BR help " ]"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR HANDLE " := { "
|
|
Packit Service |
3880ab |
\fIu12_hex_htid\fB:\fR[\fIu8_hex_hash\fB:\fR[\fIu12_hex_nodeid\fR] | \fB0x\fIu32_hex_value\fR }
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR OPTION_LIST " := [ " OPTION_LIST " ] " OPTION
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR HASHKEY " := [ "
|
|
Packit Service |
3880ab |
.B mask
|
|
Packit Service |
3880ab |
.IR u32_hex_value " ] [ "
|
|
Packit Service |
3880ab |
.B at
|
|
Packit Service |
3880ab |
.IR 4*int_value " ]"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR CLASSID " := { "
|
|
Packit Service |
3880ab |
.BR root " | "
|
|
Packit Service |
3880ab |
.BR none " | "
|
|
Packit Service |
3880ab |
[\fIu16_major\fR]\fB:\fIu16_minor\fR | \fIu32_hex_value\fR }
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR OFFSET " := [ "
|
|
Packit Service |
3880ab |
.B plus
|
|
Packit Service |
3880ab |
.IR int_value " ] [ "
|
|
Packit Service |
3880ab |
.B at
|
|
Packit Service |
3880ab |
.IR 2*int_value " ] [ "
|
|
Packit Service |
3880ab |
.B mask
|
|
Packit Service |
3880ab |
.IR u16_hex_value " ] [ "
|
|
Packit Service |
3880ab |
.B shift
|
|
Packit Service |
3880ab |
.IR int_value " ] [ "
|
|
Packit Service |
3880ab |
.BR eat " ]"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR OPTION " := { "
|
|
Packit Service |
3880ab |
.B match
|
|
Packit Service |
3880ab |
.IR SELECTOR " | "
|
|
Packit Service |
3880ab |
.B action
|
|
Packit Service |
3880ab |
.IR ACTION " } "
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR SELECTOR " := { "
|
|
Packit Service |
3880ab |
.B u32
|
|
Packit Service |
3880ab |
.IR VAL_MASK_32 " | "
|
|
Packit Service |
3880ab |
.B u16
|
|
Packit Service |
3880ab |
.IR VAL_MASK_16 " | "
|
|
Packit Service |
3880ab |
.B u8
|
|
Packit Service |
3880ab |
.IR VAL_MASK_8 " | "
|
|
Packit Service |
3880ab |
.B ip
|
|
Packit Service |
3880ab |
.IR IP " | "
|
|
Packit Service |
3880ab |
.B ip6
|
|
Packit Service |
3880ab |
.IR IP6 " | { "
|
|
Packit Service |
3880ab |
.BR tcp " | " udp " } "
|
|
Packit Service |
3880ab |
.IR TCPUDP " | "
|
|
Packit Service |
3880ab |
.B icmp
|
|
Packit Service |
3880ab |
.IR ICMP " | "
|
|
Packit Service |
3880ab |
.B mark
|
|
Packit Service |
3880ab |
.IR VAL_MASK_32 " | "
|
|
Packit Service |
3880ab |
.B ether
|
|
Packit Service |
3880ab |
.IR ETHER " }"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR IP " := { { "
|
|
Packit Service |
3880ab |
.BR src " | " dst " } { " default " | " any " | " all " | "
|
|
Packit Service |
3880ab |
.IR ip_address " [ "
|
|
Packit Service |
3880ab |
.BR / " { "
|
|
Packit Service |
3880ab |
.IR prefixlen " | " netmask " } ] } " AT " | { "
|
|
Packit Service |
3880ab |
.BR dsfield " | " ihl " | " protocol " | " precedence " | "
|
|
Packit Service |
3880ab |
.BR icmp_type " | " icmp_code " } "
|
|
Packit Service |
3880ab |
.IR VAL_MASK_8 " | { "
|
|
Packit Service |
3880ab |
.BR sport " | " dport " } "
|
|
Packit Service |
3880ab |
.IR VAL_MASK_16 " | "
|
|
Packit Service |
3880ab |
.BR nofrag " | " firstfrag " | " df " | " mf " }"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR IP6 " := { { "
|
|
Packit Service |
3880ab |
.BR src " | " dst " } { " default " | " any " | " all " | "
|
|
Packit Service |
3880ab |
.IR ip6_address " [/" prefixlen " ] } " AT " | "
|
|
Packit Service |
3880ab |
.B priority
|
|
Packit Service |
3880ab |
.IR VAL_MASK_8 " | { "
|
|
Packit Service |
3880ab |
.BR protocol " | " icmp_type " | " icmp_code " } "
|
|
Packit Service |
3880ab |
.IR VAL_MASK_8 " | "
|
|
Packit Service |
3880ab |
.B flowlabel
|
|
Packit Service |
3880ab |
.IR VAL_MASK_32 " | { "
|
|
Packit Service |
3880ab |
.BR sport " | " dport " } "
|
|
Packit Service |
3880ab |
.IR VAL_MASK_16 " }"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR TCPUDP " := { "
|
|
Packit Service |
3880ab |
.BR src " | " dst " } "
|
|
Packit Service |
3880ab |
.I VAL_MASK_16
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR ICMP " := { "
|
|
Packit Service |
3880ab |
.B type
|
|
Packit Service |
3880ab |
.IR VAL_MASK_8 " | "
|
|
Packit Service |
3880ab |
.B code
|
|
Packit Service |
3880ab |
.IR VAL_MASK_8 " }"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR ETHER " := { "
|
|
Packit Service |
3880ab |
.BR src " | " dst " } "
|
|
Packit Service |
3880ab |
.IR ether_address " " AT
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR VAL_MASK_32 " := " u32_value " " u32_hex_mask " [ " AT " ]"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR VAL_MASK_16 " := " u16_value " " u16_hex_mask " [ " AT " ]"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR VAL_MASK_8 " := " u8_value " " u8_hex_mask " [ " AT " ]"
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.ti -8
|
|
Packit Service |
3880ab |
.IR AT " := [ "
|
|
Packit Service |
3880ab |
.BR at " [ " nexthdr+ " ] "
|
|
Packit Service |
3880ab |
.IR int_value " ]"
|
|
Packit Service |
3880ab |
.SH DESCRIPTION
|
|
Packit Service |
3880ab |
The Universal/Ugly 32bit filter allows to match arbitrary bitfields in the
|
|
Packit Service |
3880ab |
packet. Due to breaking everything down to values, masks and offsets, It is
|
|
Packit Service |
3880ab |
equally powerful and hard to use. Luckily many abstracting directives are
|
|
Packit Service |
3880ab |
present which allow defining rules on a higher level and therefore free the
|
|
Packit Service |
3880ab |
user from having to fiddle with bits and masks in many cases.
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
There are two general modes of invocation: The first mode creates a new filter
|
|
Packit Service |
3880ab |
to delegate packets to different destinations. Apart from the obvious ones,
|
|
Packit Service |
3880ab |
namely classifying the packet by specifying a
|
|
Packit Service |
3880ab |
.I CLASSID
|
|
Packit Service |
3880ab |
or calling an
|
|
Packit Service |
3880ab |
.BR action ,
|
|
Packit Service |
3880ab |
one may
|
|
Packit Service |
3880ab |
.B link
|
|
Packit Service |
3880ab |
one filter to another one (or even a list of them), effectively organizing
|
|
Packit Service |
3880ab |
filters into a tree-like hierarchy.
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
Typically filter delegation is done by means of a hash table, which leads to the
|
|
Packit Service |
3880ab |
second mode of invocation: it merely serves to set up these hash tables. Filters
|
|
Packit Service |
3880ab |
can select a hash table and provide a key selector from which a hash is to be
|
|
Packit Service |
3880ab |
computed and used as key to lookup the table's bucket which contains filters for
|
|
Packit Service |
3880ab |
further processing. This is useful if a high number of filters is in use, as the
|
|
Packit Service |
3880ab |
overhead of performing the hash operation and table lookup becomes negligible in
|
|
Packit Service |
3880ab |
that case. Using hashtables with
|
|
Packit Service |
3880ab |
.B u32
|
|
Packit Service |
3880ab |
basically involves the following pattern:
|
|
Packit Service |
3880ab |
.IP (1) 4
|
|
Packit Service |
3880ab |
Creating a new hash table, specifying it's size using the
|
|
Packit Service |
3880ab |
.B divisor
|
|
Packit Service |
3880ab |
parameter and ideally a handle by which the table can be identified. If the
|
|
Packit Service |
3880ab |
latter is not given, the kernel chooses one on it's own, which has to be
|
|
Packit Service |
3880ab |
guessed later.
|
|
Packit Service |
3880ab |
.IP (2) 4
|
|
Packit Service |
3880ab |
Creating filters which link to the created table in
|
|
Packit Service |
3880ab |
.I (1)
|
|
Packit Service |
3880ab |
using the
|
|
Packit Service |
3880ab |
.B link
|
|
Packit Service |
3880ab |
parameter and defining the packet data which the kernel will use to calculate
|
|
Packit Service |
3880ab |
the
|
|
Packit Service |
3880ab |
.BR hashkey .
|
|
Packit Service |
3880ab |
.IP (3) 4
|
|
Packit Service |
3880ab |
Adding filters to buckets in the hash table from
|
|
Packit Service |
3880ab |
.IR (1) .
|
|
Packit Service |
3880ab |
In order to avoid having to know how exactly the kernel creates the hash key,
|
|
Packit Service |
3880ab |
there is the
|
|
Packit Service |
3880ab |
.B sample
|
|
Packit Service |
3880ab |
parameter, which gives sample data to hash and thereby define the table bucket
|
|
Packit Service |
3880ab |
the filter should be added to.
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
In fact, even if not explicitly requested
|
|
Packit Service |
3880ab |
.B u32
|
|
Packit Service |
3880ab |
creates a hash table for every
|
|
Packit Service |
3880ab |
.B priority
|
|
Packit Service |
3880ab |
a filter is being added with. The table's size is 1 though, so it is in fact
|
|
Packit Service |
3880ab |
merely a linked list.
|
|
Packit Service |
3880ab |
.SH VALUES
|
|
Packit Service |
3880ab |
Options and selectors require values to be specified in a specific format, which
|
|
Packit Service |
3880ab |
is often non-intuitive. Therefore the terminals in
|
|
Packit Service |
3880ab |
.I SYNOPSIS
|
|
Packit Service |
3880ab |
have been given descriptive names to indicate the required format and/or maximum
|
|
Packit Service |
3880ab |
allowed numeric value: Prefixes
|
|
Packit Service |
3880ab |
.IR u32 ", " u16 " and " u8
|
|
Packit Service |
3880ab |
indicate four, two and single byte unsigned values. E.g.
|
|
Packit Service |
3880ab |
.I u16
|
|
Packit Service |
3880ab |
indicates a two byte-sized value in range between 0 and 65535 (0xFFFF)
|
|
Packit Service |
3880ab |
inclusive. A prefix of
|
|
Packit Service |
3880ab |
.I int
|
|
Packit Service |
3880ab |
indicates a four byte signed value. A middle part of
|
|
Packit Service |
3880ab |
.I _hex_
|
|
Packit Service |
3880ab |
indicates that the value is parsed in hexadecimal format. Otherwise, the
|
|
Packit Service |
3880ab |
value's base is automatically detected, i.e. values prefixed with
|
|
Packit Service |
3880ab |
.I 0x
|
|
Packit Service |
3880ab |
are considered hexadecimal, a leading
|
|
Packit Service |
3880ab |
.I 0
|
|
Packit Service |
3880ab |
indicates octal format and decimal format otherwise. There are some values with
|
|
Packit Service |
3880ab |
special formatting as well:
|
|
Packit Service |
3880ab |
.IR ip_address " and " netmask
|
|
Packit Service |
3880ab |
are in dotted-quad formatting as usual for IPv4 addresses. An
|
|
Packit Service |
3880ab |
.I ip6_address
|
|
Packit Service |
3880ab |
is specified in common, colon-separated hexadecimal format. Finally,
|
|
Packit Service |
3880ab |
.I prefixlen
|
|
Packit Service |
3880ab |
is an unsigned, decimal integer value in range from 0 to the address width in
|
|
Packit Service |
3880ab |
bits (32 for IPv4 and 128 for IPv6).
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
Sometimes values need to be dividable by a certain number. In that case a name
|
|
Packit Service |
3880ab |
of the form
|
|
Packit Service |
3880ab |
.I N*val
|
|
Packit Service |
3880ab |
was chosen, indicating that
|
|
Packit Service |
3880ab |
.I val
|
|
Packit Service |
3880ab |
must be dividable by
|
|
Packit Service |
3880ab |
.IR N .
|
|
Packit Service |
3880ab |
Or the other way around: the resulting value must be a multiple of
|
|
Packit Service |
3880ab |
.IR N .
|
|
Packit Service |
3880ab |
.SH OPTIONS
|
|
Packit Service |
3880ab |
.B U32
|
|
Packit Service |
3880ab |
recognizes the following options:
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI handle " HANDLE"
|
|
Packit Service |
3880ab |
The handle is used to reference a filter and therefore must be unique. It
|
|
Packit Service |
3880ab |
consists of a hash table identifier
|
|
Packit Service |
3880ab |
.B htid
|
|
Packit Service |
3880ab |
and optional
|
|
Packit Service |
3880ab |
.B hash
|
|
Packit Service |
3880ab |
(which identifies the hash table's bucket) and
|
|
Packit Service |
3880ab |
.BR nodeid .
|
|
Packit Service |
3880ab |
All these values are parsed as unsigned, hexadecimal numbers with length 12bits
|
|
Packit Service |
3880ab |
(
|
|
Packit Service |
3880ab |
.BR htid " and " nodeid )
|
|
Packit Service |
3880ab |
or 8bits (
|
|
Packit Service |
3880ab |
.BR hash ).
|
|
Packit Service |
3880ab |
Alternatively one may specify a single, 32bit long hex number which contains
|
|
Packit Service |
3880ab |
the three fields bits in concatenated form. Other than the fields themselves, it
|
|
Packit Service |
3880ab |
has to be prefixed by
|
|
Packit Service |
3880ab |
.BR 0x .
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI offset " OFFSET"
|
|
Packit Service |
3880ab |
Set an offset which defines where matches of subsequent filters are applied to.
|
|
Packit Service |
3880ab |
Therefore this option is useful only when combined with
|
|
Packit Service |
3880ab |
.BR link " or a combination of " ht " and " sample .
|
|
Packit Service |
3880ab |
The offset may be given explicitly by using the
|
|
Packit Service |
3880ab |
.B plus
|
|
Packit Service |
3880ab |
keyword, or extracted from the packet data with
|
|
Packit Service |
3880ab |
.BR at .
|
|
Packit Service |
3880ab |
It is possible to mangle the latter using
|
|
Packit Service |
3880ab |
.BR mask " and/or " shift
|
|
Packit Service |
3880ab |
keywords. By default, this offset is recorded but not implicitly applied. It is
|
|
Packit Service |
3880ab |
used only to substitute the
|
|
Packit Service |
3880ab |
.B nexthdr+
|
|
Packit Service |
3880ab |
statement. Using the keyword
|
|
Packit Service |
3880ab |
.B eat
|
|
Packit Service |
3880ab |
though inverses this behaviour: the offset is applied always, and
|
|
Packit Service |
3880ab |
.B nexthdr+
|
|
Packit Service |
3880ab |
will fall back to zero.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI hashkey " HASHKEY"
|
|
Packit Service |
3880ab |
Spefify what packet data to use to calculate a hash key for bucket lookup. The
|
|
Packit Service |
3880ab |
kernel adjusts the value according to the hash table's size. For this to work,
|
|
Packit Service |
3880ab |
the option
|
|
Packit Service |
3880ab |
.B link
|
|
Packit Service |
3880ab |
must be given.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI classid " CLASSID"
|
|
Packit Service |
3880ab |
Classify matching packets into the given
|
|
Packit Service |
3880ab |
.IR CLASSID ,
|
|
Packit Service |
3880ab |
which consists of either 16bit
|
|
Packit Service |
3880ab |
.BR major " and " minor
|
|
Packit Service |
3880ab |
numbers or a single 32bit value combining both.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI divisor " u32_value"
|
|
Packit Service |
3880ab |
Specify a modulo value. Used when creating hash tables to define their size or
|
|
Packit Service |
3880ab |
for declaring a
|
|
Packit Service |
3880ab |
.B sample
|
|
Packit Service |
3880ab |
to calculate hash table keys from. Must be a power of two with exponent not
|
|
Packit Service |
3880ab |
exceeding eight.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI order " u32_value"
|
|
Packit Service |
3880ab |
A value to order filters by, ascending. Conflicts with
|
|
Packit Service |
3880ab |
.B handle
|
|
Packit Service |
3880ab |
which serves the same purpose.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI sample " SELECTOR"
|
|
Packit Service |
3880ab |
Used together with
|
|
Packit Service |
3880ab |
.B ht
|
|
Packit Service |
3880ab |
to specify which bucket to add this filter to. This allows one to avoid having
|
|
Packit Service |
3880ab |
to know how exactly the kernel calculates hashes. The additional
|
|
Packit Service |
3880ab |
.B divisor
|
|
Packit Service |
3880ab |
defaults to 256, so must be given for hash tables of different size.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI link " HANDLE"
|
|
Packit Service |
3880ab |
Delegate matching packets to filters in a hash table.
|
|
Packit Service |
3880ab |
.I HANDLE
|
|
Packit Service |
3880ab |
is used to only specify the hash table, so only
|
|
Packit Service |
3880ab |
.BR htid " may be given, " hash " and " nodeid
|
|
Packit Service |
3880ab |
have to be omitted. By default, bucket number 0 will be used and can be
|
|
Packit Service |
3880ab |
overridden by the
|
|
Packit Service |
3880ab |
.B hashkey
|
|
Packit Service |
3880ab |
option.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI indev " ifname"
|
|
Packit Service |
3880ab |
Filter on the incoming interface of the packet. Obviously works only for
|
|
Packit Service |
3880ab |
forwarded traffic.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI skip_sw
|
|
Packit Service |
3880ab |
Do not process filter by software. If hardware has no offload support for this
|
|
Packit Service |
3880ab |
filter, or TC offload is not enabled for the interface, operation will fail.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI skip_hw
|
|
Packit Service |
3880ab |
Do not process filter by hardware.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI help
|
|
Packit Service |
3880ab |
Print a brief help text about possible options.
|
|
Packit Service |
3880ab |
.SH SELECTORS
|
|
Packit Service |
3880ab |
Basically the only real selector is
|
|
Packit Service |
3880ab |
.B u32 .
|
|
Packit Service |
3880ab |
All others merely provide a higher level syntax and are internally translated
|
|
Packit Service |
3880ab |
into
|
|
Packit Service |
3880ab |
.B u32 .
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI u32 " VAL_MASK_32"
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.BI u16 " VAL_MASK_16"
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.BI u8 " VAL_MASK_8"
|
|
Packit Service |
3880ab |
Match packet data to a given value. The selector name defines the sample length
|
|
Packit Service |
3880ab |
to extract (32bits for
|
|
Packit Service |
3880ab |
.BR u32 ,
|
|
Packit Service |
3880ab |
16bits for
|
|
Packit Service |
3880ab |
.B u16
|
|
Packit Service |
3880ab |
and 8bits for
|
|
Packit Service |
3880ab |
.BR u8 ).
|
|
Packit Service |
3880ab |
Before comparing, the sample is binary AND'ed with the given mask. This way
|
|
Packit Service |
3880ab |
uninteresting bits can be cleared before comparison. The position of the sample
|
|
Packit Service |
3880ab |
is defined by the offset specified in
|
|
Packit Service |
3880ab |
.IR AT .
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI ip " IP"
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.BI ip6 " IP6"
|
|
Packit Service |
3880ab |
Assume packet starts with an IPv4 (
|
|
Packit Service |
3880ab |
.BR ip )
|
|
Packit Service |
3880ab |
or IPv6 (
|
|
Packit Service |
3880ab |
.BR ip6 )
|
|
Packit Service |
3880ab |
header.
|
|
Packit Service |
3880ab |
.IR IP / IP6
|
|
Packit Service |
3880ab |
then allows to match various header fields:
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI src " ADDR"
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.BI dst " ADDR"
|
|
Packit Service |
3880ab |
Compare Source or Destination Address fields against the value of
|
|
Packit Service |
3880ab |
.IR ADDR .
|
|
Packit Service |
3880ab |
The reserved words
|
|
Packit Service |
3880ab |
.BR default ", " any " and " all
|
|
Packit Service |
3880ab |
effectively match any address. Otherwise an IP address of the particular
|
|
Packit Service |
3880ab |
protocol is expected, optionally suffixed by a prefix length to match whole
|
|
Packit Service |
3880ab |
subnets. In case of IPv4 a netmask may also be given.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI dsfield " VAL_MASK_8"
|
|
Packit Service |
3880ab |
IPv4 only. Match the packet header's DSCP/ECN field. Synonyms to this are
|
|
Packit Service |
3880ab |
.BR tos " and " precedence .
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI ihl " VAL_MASK_8"
|
|
Packit Service |
3880ab |
IPv4 only. Match the Internet Header Length field. Note that the value's unit is
|
|
Packit Service |
3880ab |
32bits, so to match a packet with 24byte header length
|
|
Packit Service |
3880ab |
.I u8_value
|
|
Packit Service |
3880ab |
has to be 6.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI protocol " VAL_MASK_8"
|
|
Packit Service |
3880ab |
Match the Protocol (IPv4) or Next Header (IPv6) field value, e.g. 6 for TCP.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI icmp_type " VAL_MASK_8"
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.BI icmp_code " VAL_MASK_8"
|
|
Packit Service |
3880ab |
Assume a next-header protocol of icmp or ipv6-icmp and match Type or Code
|
|
Packit Service |
3880ab |
field values. This is dangerous, as the code assumes minimal header size for
|
|
Packit Service |
3880ab |
IPv4 and lack of extension headers for IPv6.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI sport " VAL_MASK_16"
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.BI dport " VAL_MASK_16"
|
|
Packit Service |
3880ab |
Match layer four source or destination ports. This is dangerous as well, as it
|
|
Packit Service |
3880ab |
assumes a suitable layer four protocol is present (which has Source and
|
|
Packit Service |
3880ab |
Destination Port fields right at the start of the header and 16bit in size).
|
|
Packit Service |
3880ab |
Also minimal header size for IPv4 and lack of IPv6 extension headers is assumed.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.B nofrag
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.B firstfrag
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.B df
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.B mf
|
|
Packit Service |
3880ab |
IPv4 only, check certain flags and fragment offset values. Match if the packet
|
|
Packit Service |
3880ab |
is not a fragment
|
|
Packit Service |
3880ab |
.RB ( nofrag ),
|
|
Packit Service |
3880ab |
the first fragment
|
|
Packit Service |
3880ab |
.RB ( firstfrag ),
|
|
Packit Service |
3880ab |
if Don't Fragment
|
|
Packit Service |
3880ab |
.RB ( df )
|
|
Packit Service |
3880ab |
or More Fragments
|
|
Packit Service |
3880ab |
.RB ( mf )
|
|
Packit Service |
3880ab |
bits are set.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI priority " VAL_MASK_8"
|
|
Packit Service |
3880ab |
IPv6 only. Match the header's Traffic Class field, which has the same purpose
|
|
Packit Service |
3880ab |
and semantics of IPv4's ToS field since RFC 3168: upper six bits are DSCP, the
|
|
Packit Service |
3880ab |
lower two ECN.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI flowlabel " VAL_MASK_32"
|
|
Packit Service |
3880ab |
IPv6 only. Match the Flow Label field's value. Note that Flow Label itself is
|
|
Packit Service |
3880ab |
only 20bytes long, which are the least significant ones here. The remaining
|
|
Packit Service |
3880ab |
upper 12bytes match Version and Traffic Class fields.
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI tcp " TCPUDP"
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.BI udp " TCPUDP"
|
|
Packit Service |
3880ab |
Match fields of next header of protocol TCP or UDP. The possible values for
|
|
Packit Service |
3880ab |
.I TCPDUP
|
|
Packit Service |
3880ab |
are:
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI src " VAL_MASK_16"
|
|
Packit Service |
3880ab |
Match on Source Port field value.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI dst " VALMASK_16"
|
|
Packit Service |
3880ab |
Match on Destination Port field value.
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI icmp " ICMP"
|
|
Packit Service |
3880ab |
Match fields of next header of protocol ICMP. The possible values for
|
|
Packit Service |
3880ab |
.I ICMP
|
|
Packit Service |
3880ab |
are:
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI type " VAL_MASK_8"
|
|
Packit Service |
3880ab |
Match on ICMP Type field.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI code " VAL_MASK_8"
|
|
Packit Service |
3880ab |
Match on ICMP Code field.
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI mark " VAL_MASK_32"
|
|
Packit Service |
3880ab |
Match on netfilter fwmark value.
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI ether " ETHER"
|
|
Packit Service |
3880ab |
Match on ethernet header fields. Possible values for
|
|
Packit Service |
3880ab |
.I ETHER
|
|
Packit Service |
3880ab |
are:
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.TP
|
|
Packit Service |
3880ab |
.BI src " ether_address" " " AT
|
|
Packit Service |
3880ab |
.TQ
|
|
Packit Service |
3880ab |
.BI dst " ether_address" " " AT
|
|
Packit Service |
3880ab |
Match on source or destination ethernet address. This is dangerous: It assumes
|
|
Packit Service |
3880ab |
an ethernet header is present at the start of the packet. This will probably
|
|
Packit Service |
3880ab |
lead to unexpected things if used with layer three interfaces like e.g. tun or
|
|
Packit Service |
3880ab |
ppp.
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
.SH EXAMPLES
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.EX
|
|
Packit Service |
3880ab |
tc filter add dev eth0 parent 999:0 prio 99 protocol ip u32 \\
|
|
Packit Service |
3880ab |
match ip src 192.168.8.0/24 classid 1:1
|
|
Packit Service |
3880ab |
.EE
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
This attaches a filter to the qdisc identified by
|
|
Packit Service |
3880ab |
.BR 999:0.
|
|
Packit Service |
3880ab |
It's priority is
|
|
Packit Service |
3880ab |
.BR 99 ,
|
|
Packit Service |
3880ab |
which affects in which order multiple filters attached to the same
|
|
Packit Service |
3880ab |
.B parent
|
|
Packit Service |
3880ab |
are consulted (the lower the earlier). The filter handles packets of
|
|
Packit Service |
3880ab |
.B protocol
|
|
Packit Service |
3880ab |
type
|
|
Packit Service |
3880ab |
.BR ip ,
|
|
Packit Service |
3880ab |
and
|
|
Packit Service |
3880ab |
.BR match es
|
|
Packit Service |
3880ab |
if the IP header's source address is within the
|
|
Packit Service |
3880ab |
.B 192.168.8.0/24
|
|
Packit Service |
3880ab |
subnet. Matching packets are classified into class
|
|
Packit Service |
3880ab |
.BR 1.1 .
|
|
Packit Service |
3880ab |
The effect of this command might be surprising at first glance:
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.EX
|
|
Packit Service |
3880ab |
filter parent 1: protocol ip pref 99 u32
|
|
Packit Service |
3880ab |
filter parent 1: protocol ip pref 99 u32 \\
|
|
Packit Service |
3880ab |
fh 800: ht divisor 1
|
|
Packit Service |
3880ab |
filter parent 1: protocol ip pref 99 u32 \\
|
|
Packit Service |
3880ab |
fh 800::800 order 2048 key ht 800 bkt 0 flowid 1:1 \\
|
|
Packit Service |
3880ab |
match c0a80800/ffffff00 at 12
|
|
Packit Service |
3880ab |
.EE
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
So parent
|
|
Packit Service |
3880ab |
.B 1:
|
|
Packit Service |
3880ab |
is assigned a new
|
|
Packit Service |
3880ab |
.B u32
|
|
Packit Service |
3880ab |
filter, which contains a hash table of size 1 (as the
|
|
Packit Service |
3880ab |
.B divisor
|
|
Packit Service |
3880ab |
indicates). The table ID is
|
|
Packit Service |
3880ab |
.BR 800 .
|
|
Packit Service |
3880ab |
The third line then shows the actual filter which was added above: it sits in
|
|
Packit Service |
3880ab |
table
|
|
Packit Service |
3880ab |
.B 800
|
|
Packit Service |
3880ab |
and bucket
|
|
Packit Service |
3880ab |
.BR 0 ,
|
|
Packit Service |
3880ab |
classifies packets into class ID
|
|
Packit Service |
3880ab |
.B 1:1
|
|
Packit Service |
3880ab |
and matches the upper three bytes of the four byte value at offset
|
|
Packit Service |
3880ab |
.B 12
|
|
Packit Service |
3880ab |
to be
|
|
Packit Service |
3880ab |
.BR 0xc0a808 ,
|
|
Packit Service |
3880ab |
which is 192, 168 and 8.
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
Now for something more complicated, namely creating a custom hash table:
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.EX
|
|
Packit Service |
3880ab |
tc filter add dev eth0 prio 99 handle 1: u32 divisor 256
|
|
Packit Service |
3880ab |
.EE
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
This creates a table of size 256 with handle
|
|
Packit Service |
3880ab |
.B 1:
|
|
Packit Service |
3880ab |
in priority
|
|
Packit Service |
3880ab |
.BR 99 .
|
|
Packit Service |
3880ab |
The effect is as follows:
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.EX
|
|
Packit Service |
3880ab |
filter parent 1: protocol all pref 99 u32
|
|
Packit Service |
3880ab |
filter parent 1: protocol all pref 99 u32 fh 1: ht divisor 256
|
|
Packit Service |
3880ab |
filter parent 1: protocol all pref 99 u32 fh 800: ht divisor 1
|
|
Packit Service |
3880ab |
.EE
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
So along with the requested hash table (handle
|
|
Packit Service |
3880ab |
.BR 1: ),
|
|
Packit Service |
3880ab |
the kernel has created his own table of size 1 to hold other filters of the same
|
|
Packit Service |
3880ab |
priority.
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
The next step is to create a filter which links to the created hash table:
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.EX
|
|
Packit Service |
3880ab |
tc filter add dev eth0 parent 1: prio 1 u32 \\
|
|
Packit Service |
3880ab |
link 1: hashkey mask 0x0000ff00 at 12 \\
|
|
Packit Service |
3880ab |
match ip src 192.168.0.0/16
|
|
Packit Service |
3880ab |
.EE
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
The filter is given a lower priority than the hash table itself so
|
|
Packit Service |
3880ab |
.B u32
|
|
Packit Service |
3880ab |
consults it before manually traversing the hash table. The options
|
|
Packit Service |
3880ab |
.BR link " and " hashkey
|
|
Packit Service |
3880ab |
determine which table and bucket to redirect to. In this case the hash key
|
|
Packit Service |
3880ab |
should be constructed out of the second byte at offset 12, which corresponds to
|
|
Packit Service |
3880ab |
an IP packet's third byte of the source address field. Along with the
|
|
Packit Service |
3880ab |
.B match
|
|
Packit Service |
3880ab |
statement, this effectively maps all class C networks below 192.168.0.0/16 to
|
|
Packit Service |
3880ab |
different buckets of the hash table.
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
Filters for certain subnets can be created like so:
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.EX
|
|
Packit Service |
3880ab |
tc filter add dev eth0 parent 1: prio 99 u32 \\
|
|
Packit Service |
3880ab |
ht 1: sample u32 0x00000800 0x0000ff00 at 12 \\
|
|
Packit Service |
3880ab |
match ip src 192.168.8.0/24 classid 1:1
|
|
Packit Service |
3880ab |
.EE
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
The bucket is defined using the
|
|
Packit Service |
3880ab |
.B sample
|
|
Packit Service |
3880ab |
option: In this case, the second byte at offset 12 must be 0x08, exactly. In
|
|
Packit Service |
3880ab |
this case, the resulting bucket ID is obviously 8, but as soon as
|
|
Packit Service |
3880ab |
.B sample
|
|
Packit Service |
3880ab |
selects an amount of data which could exceed the
|
|
Packit Service |
3880ab |
.BR divisor ,
|
|
Packit Service |
3880ab |
one would have to know the kernel-internal algorithm to deduce the destination
|
|
Packit Service |
3880ab |
bucket. This filter's
|
|
Packit Service |
3880ab |
.B match
|
|
Packit Service |
3880ab |
statement is redundant in this case, as the entropy for the hash key does not
|
|
Packit Service |
3880ab |
exceed the table size and therefore no collisions can occur. Otherwise it's
|
|
Packit Service |
3880ab |
necessary to prevent matching unwanted packets.
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
Matching upper layer fields is problematic since IPv4 header length is variable
|
|
Packit Service |
3880ab |
and IPv6 supports extension headers which affect upper layer header offset. To
|
|
Packit Service |
3880ab |
overcome this, there is the possibility to specify
|
|
Packit Service |
3880ab |
.B nexthdr+
|
|
Packit Service |
3880ab |
when giving an offset, and to make things easier there are the
|
|
Packit Service |
3880ab |
.BR tcp " and " udp
|
|
Packit Service |
3880ab |
matches which use
|
|
Packit Service |
3880ab |
.B nexthdr+
|
|
Packit Service |
3880ab |
implicitly. This offset has to be calculated in beforehand though, and the only
|
|
Packit Service |
3880ab |
way to achieve that is by doing it in a separate filter which then links to the
|
|
Packit Service |
3880ab |
filter which wants to use it. Here is an example of doing so:
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
.RS
|
|
Packit Service |
3880ab |
.EX
|
|
Packit Service |
3880ab |
tc filter add dev eth0 parent 1:0 protocol ip handle 1: \\
|
|
Packit Service |
3880ab |
u32 divisor 1
|
|
Packit Service |
3880ab |
tc filter add dev eth0 parent 1:0 protocol ip \\
|
|
Packit Service |
3880ab |
u32 ht 1: \\
|
|
Packit Service |
3880ab |
match tcp src 22 FFFF \\
|
|
Packit Service |
3880ab |
classid 1:2
|
|
Packit Service |
3880ab |
tc filter add dev eth0 parent 1:0 protocol ip \\
|
|
Packit Service |
3880ab |
u32 ht 800: \\
|
|
Packit Service |
3880ab |
match ip protocol 6 FF \\
|
|
Packit Service |
3880ab |
match ip firstfrag \\
|
|
Packit Service |
3880ab |
offset at 0 mask 0f00 shift 6 \\
|
|
Packit Service |
3880ab |
link 1:
|
|
Packit Service |
3880ab |
.EE
|
|
Packit Service |
3880ab |
.RE
|
|
Packit Service |
3880ab |
|
|
Packit Service |
3880ab |
This is what is being done: In the first call, a single element sized hash table
|
|
Packit Service |
3880ab |
is created so there is a place to hold the linked to filter and a known handle
|
|
Packit Service |
3880ab |
.RB ( 1: )
|
|
Packit Service |
3880ab |
to reference to it. The second call then adds the actual filter, which pushes
|
|
Packit Service |
3880ab |
packets with TCP source port 22 into class
|
|
Packit Service |
3880ab |
.BR 1:2 .
|
|
Packit Service |
3880ab |
Using
|
|
Packit Service |
3880ab |
.BR ht ,
|
|
Packit Service |
3880ab |
it is moved into the hash table created by the first call. The third call then
|
|
Packit Service |
3880ab |
does the actual magic: It matches IPv4 packets with next layer protocol 6 (TCP),
|
|
Packit Service |
3880ab |
only if it's the first fragment (usually TCP sets DF bit, but if it doesn't and
|
|
Packit Service |
3880ab |
the packet is fragmented, only the first one contains the TCP header), and then
|
|
Packit Service |
3880ab |
sets the offset based on the IP header's IHL field (right-shifting by 6
|
|
Packit Service |
3880ab |
eliminates the offset of the field and at the same time converts the value into
|
|
Packit Service |
3880ab |
byte unit). Finally, using
|
|
Packit Service |
3880ab |
.BR link ,
|
|
Packit Service |
3880ab |
the hash table from first call is referenced which holds the filter from second
|
|
Packit Service |
3880ab |
call.
|
|
Packit Service |
3880ab |
.SH SEE ALSO
|
|
Packit Service |
3880ab |
.BR tc (8),
|
|
Packit Service |
3880ab |
.br
|
|
Packit Service |
3880ab |
.BR cls_u32.txt " at " http://linux-tc-notes.sourceforge.net/
|