Matches

The programmatic interface to packet matching is based on the concept of a Match object that provides methods returning Criterion objects which in turn allow for equality (and inequality) testing against a stored value.

In the following example, PacketMatch (a subclass of Match) provides matching against packet attributes such as protocol, source address, etc.

m = PacketMatch()
m.protocol().equals('udp')

The protocol() method returns a ProtocolCriterion` object which stores the value that we want to compare against (udp in this case).

A Match object may have multiple criteria; such criteria are specific to the Match subclass.

Continuing the example:

a = IPv4Network('1.2.3.4/32')
mcast = IPV4Network('224.0.0.0/4')
m.source_address().equals(a).dest_address().not_equals(mcast)

The source_address() method returns a SourceAddressCriterion object, while the dest_address() method returns a DestAddressCriterion object. The resulting Match object now matches UDP packets with a source address of 1.2.3.4 and a destination address that is not a multicast address.

---

The Match class is the parent class of all match-related classes. No objects of this class are instantiated.

The Criterion class is the parent class of all classes implementing match-specific criteria. No objects of this class are instantiated. Objects of subclasses of Criterion are never directly instantiated by the user; they are instantiated as needed by the Match subclasses.

MatchNone is a special subclass of Match that is used to indicate the absence of a match.

---

class Match

Parent class for all match-specific subclasses.

static build_iptables_args(match_name: Optional[str], crit_iterable) → List[str]

Helper method to build an iptables(8) argument list from a match name and a list of Criterion objects. iptables(8) arguments will be extracted from each criterion that is set.

Parameters:

• match_name – optional match name that will result in adding ‘-m’ match_name at the beginning of the argument list; there must be at least one set criterion for the match name to be included in the return value

• crit_iterable – a Criterion iterator

has_criteria() → bool

Returns True if the match has any criteria set

to_iptables_args() → List[str]

Returns a list of iptables(8) arguments

This method must be implemented by subclasses.

---

class Criterion(match: Match)

This class is used to express an iptables(8) match criterion; it does not perform any comparisons.

Criterion is a superclass that serves the following purposes:

1. it provides an equals() method and a not_equals() method to express comparison against a value

2. it keeps track of whether the criterion has been set; a criterion is set when either the equals() or not_equals() method is invoked; a criterion may only be set once

3. it keeps track of whether a criterion is negated or not

4. its iptables_to_args() method generates the ‘!’ iptables(8) argument, and also checks if the criterion was set

The equals()/not_equals() methods of Criterion subclasses must invoke the _set_polarity() method of Criterion to indicate the polarity of the test. These methods are also responsible for saving the comparison value in the subclass object.

A Criterion has an owner which is an object of a subclass of Match. The equals()/not_equals() methods return this object to facilitate building a criteria list:

match.crit1().equals('foo').crit2().not_equals('bar')

Parameters:

match – the Match object that owns this Criterion

compare(is_equal: bool, *args, **kwargs) → Match

Alternative method used for comparisons. It invokes equals() (or not_equals()) with args and kwargs if is_equal is True (or False).

equals(*args, **kwargs) → Match

Express equality comparison against the argument values.

The method implementation in this class expects no arguments and expresses a bool comparison.

Subclasses will implement this method to express comparisons against a specific value (or values). These values will be the arguments of the subclass method and will be stored in the subclass object.

Subclasses overriding this method should invoke the _set_polarity() method of this class to set the polarity to True.

Returns this object.

get_value() → Any

Returns the value that this criterion is comparing against

is_positive() → bool

Returns the ‘polarity’ of the criterion; True for equals() or False for not_equals()

Raises IptablesError if the criterion is not set

is_set() → bool

Returns True if the criterion has been set

not_equals(*args, **kwargs) → Match

Express inequality comparison against the argument values.

The method implementation in this class invokes the equals() method and then reverses the polarity; subclasses should not need to override it.

Subclasses overriding this method should invoke the _set_polarity() method of this class to set the polarity to False.

Returns this object.

to_iptables_args() → List[str]

Returns a list of iptables(8) arguments

---

class MatchNone

This is a special class to indicate the absence of any Match objects.

to_iptables_args() → List[str]

Returns a list of iptables(8) arguments