U32IPFilter

The U32IPFilter uses the packet contents to classify a packet. Matching is done using selector classes. The following selector classes are available:

The class U32FilterHandle describes the U32 filter handle.

class U32IPFilter(*, prio: Optional[int] = None, dest_class_handle: Optional[Handle] = None, filter_handle: Optional[U32FilterHandle] = None, filter_name: Optional[str] = None, selectors: Optional[List[U32Selector]] = None)[source]

This class is used for U32 filters when the ethernet frames carry IP datagrams. It uses an arbitrary number of selectors for matching against the packet fields.

Parameters:

  • prio – filter priority

  • dest_class_handle – if there is a match, traffic will be directed to the QClass with this Handle

  • filter_handle – handle of this filter

  • filter_name – name for this filter

  • selectors – list of U32Selector objects specifying the matching criteria

get_match_name() → Optional[str][source]

Returns a string with the name that describes the traffic matched by the filter.

get_description() → str[source]

Returns a string with detail info about the filter

filter_creation_args()[source]

Returns a list of tc(8) arguments to create this filter

get_filter_handle() → U32FilterHandle[source]

Returns the filter handle

set_filter_handle(filter_handle: U32FilterHandle)[source]

Set the filter handle.

Raises TcError if the filter is instantiated.

get_selectors() → List[U32Selector][source]

Returns the selector list

has_selector(selector: U32Selector) → bool[source]

Returns True if a selector matching selector is included in this filter (U32Selector objects support equality comparisons)

add_selector(selector: U32Selector)[source]

Add the specified selector to this filter.

add_action(action: TrafficAction) → None

Add a filter action

get_actions() → List[TrafficAction]

Returns the action list for this filter

get_dest_handle() → Optional[Handle]

Returns the Handle of the QClass where this filter will send traffic

get_filter_name() → Optional[str]

Returns the filter name

get_filter_type() → str

Returns the filter type

get_prio() → int

Returns the filter priority

is_instantiated() → bool

Returns True if the filter is in the kernel

set_dest_handle(handle: Handle)

Sets the handle of the class where this filter will send traffic.

Raises TcError if the filter is instantiated.

set_filter_name(filter_name: str)

Set the filter name

set_prio(prio: int)

Set the filter priority.

Raises TcError if the filter is instantiated.

class U32FilterHandle(htid: int, *, bucket: Optional[int] = 0, nodeid: Optional[int] = 0)[source]

U32 filter handle.

Parameters:

  • htid – hash table id (12-bit integer)

  • bucket – bucket value (8-bit integer)

  • nodeid – 12-bit integer

property htid: int

Hash table id

property bucket: int

Bucket value (aka hash value)

property nodeid: int

Nodeid value

classmethod create_from_string(handle_str: str) → U32FilterHandle[source]

Create a U32FilterHandle object from a string

Parameters:

handle_str – string containing handle with the expected syntax <num>:[<num>][:<num>]; the number strings are interpreted as hexadecimal numbers

Raises a ValueError if handle_str is malformed

IPSubnetSelector

class IPSubnetSelector(direction: str, ipv4_network: IPv4Network)[source]

A U32 selector that identifies a subnet

Parameters:

  • direction – should be either src or dst

  • ipv4_network – match against this subnet

get_name() → Optional[str][source]

Returns an (optional) selector name.

get_direction() → str[source]

Returns the direction

get_description() → str[source]

Returns a string describing the selector

get_address() → str[source]

Returns the subnet address as a string

get_prefix() → int[source]

Returns the subnet prefix (an int)

static any_source_ip() → IPSubnetSelector[source]

Returns an IPSubnetSelector that matches any source IP address

static any_dest_ip() → IPSubnetSelector[source]

Returns an IPSubnetSelector that matches any destination IP address

tc_creation_args() → List[str][source]

Returns a list of strings suitable to be used as tc args

IPPortSelector

class IPPortSelector(direction: str, port: int)[source]

A U32 selector that identifies a TCP/UDP port

Precondition:

The protocol should be TCP or UDP.

Parameters:

  • direction – should be either src or dst

  • port – match against this port number

get_name() → Optional[str][source]

Returns an (optional) selector name.

get_direction() → str[source]

Returns the direction

get_port() → int[source]

Returns the port

get_description() → str[source]

Returns a string describing the selector

tc_creation_args() → List[str][source]

Returns a list of strings suitable to be used as arguments to the tc(8) command.

IPProtocolSelector

class IPProtocolSelector(protonum: int)[source]

A U32 selector that identifies a protocol by number

Parameters:

protonum – protocol number

get_name() → Optional[str][source]

Returns an (optional) selector name.

get_description() → str[source]

Returns a string describing the selector

tc_creation_args() → List[str][source]

Returns a list of strings suitable to be used as arguments to the tc(8) command.

NumberSelector

class NumberSelector(width: str, number: int, mask: int, offset: int)[source]

A U32 selector that matches a number at a specific offset in the packet.

Parameters:

  • width – one of u8, u16, u32

  • number – compare packet contents against this number

  • mask – apply this mask to the number and the packet contents before comparing

  • offset – offset inside the packet, always in bytes, regardless of width

get_description() → str[source]

Returns a string describing the selector

tc_creation_args() → List[str][source]

Returns a list of strings suitable to be used as arguments to the tc(8) command.

get_number() → int[source]

Return the comparison value

get_mask() → int[source]

Return the mask

get_offset() → int[source]

Return the offset

get_name() → Optional[str]

Returns an (optional) selector name.

IPHeaderLength

class IPHeaderLength(header_length: int)[source]

Bases: NumberSelector

This is a convenience U32 selector that matches against a specific IP header length

Parameters:

header_length – compare packet header length against this number; header_length must be a multiple of 4

get_name() → Optional[str][source]

Returns an (optional) selector name.

get_description() → str[source]

Returns a string describing the selector

get_mask() → int

Return the mask

get_number() → int

Return the comparison value

get_offset() → int

Return the offset

tc_creation_args() → List[str]

Returns a list of strings suitable to be used as arguments to the tc(8) command.

IPDatagramLimit

class IPDatagramLimit(limit: int)[source]

Bases: NumberSelector

This is a convenience U32 selector that matches if the IP datagram size is less that a specific limit; the limit must be a power of 2.

Parameters:

limit – compare against this limit

get_name() → Optional[str][source]

Returns an (optional) selector name.

get_description() → str[source]

Returns a string describing the selector

get_mask() → int

Return the mask

get_number() → int

Return the comparison value

get_offset() → int

Return the offset

tc_creation_args() → List[str]

Returns a list of strings suitable to be used as arguments to the tc(8) command.

TcpAck

class TcpAck[source]

Bases: NumberSelector

This is a convenience U32 selector that matches the TCP ACK bit. Preconditions:

  • no IP options

  • no IP fragmentation

__init__() expects no parameters.

get_name() → Optional[str][source]

Returns an (optional) selector name.

get_description() → str[source]

Returns a string describing the selector

get_mask() → int

Return the mask

get_number() → int

Return the comparison value

get_offset() → int

Return the offset

tc_creation_args() → List[str]

Returns a list of strings suitable to be used as arguments to the tc(8) command.