Explicit matches are those that have to be specifically loaded with
the -m or --match option. State
matches, for example, demand the directive -m state prior
to entering the actual match that you want to use. Some of these matches may
be protocol specific . Some may be unconnected with any specific protocol -
for example connection states. These might be NEW (the
first packet of an as yet unestablished connection),
ESTABLISHED (a connection that is already registered in the
kernel), RELATED (a new connection that was created by an
older, established one) etc. A few may just have been evolved for testing or
experimental purposes, or just to illustrate what iptables is capable of. This
in turn means that not all of these matches may at first sight be of any use.
Nevertheless, it may well be that you personally will find a use for specific
explicit matches. And there are new ones coming along all the time, with each
new iptables release. Whether you find a use for them or
not depends on your imagination and your needs. The difference between
implicitly loaded matches and explicitly loaded ones, is that the implicitly
loaded matches will automatically be loaded when, for example, you match on
the properties of TCP packets, while explicitly
loaded matches will never be loaded automatically - it is up to you to
discover and activate explicit matches.
These matches are used for the IPSEC AH and ESP protocols. IPSEC is used to
create secure tunnels over an insecure Internet connection. The AH and ESP
protocols are used by IPSEC to create these secure connections. The AH and ESP
matches are really two separate matches, but are both described here since they
look very much alike, and both are used in the same function.
I will not go into detail to describe IPSEC here, instead look at the following
pages and documents for more information:
There is also a ton more documentation on the Internet on this, but you are
free to look it up as needed.
To use the AH/ESP matches, you need to use -m ah to load the
AH matches, and -m esp to load the ESP matches.
In 2.2 and 2.4 kernels, Linux used something called FreeS/WAN for the IPSEC
implementation, but as of Linux kernel 2.5.47 and up, Linux kernels have a
direct implementation of IPSEC that requires no patching of the kernel. This is
a total rewrite of the IPSEC implementation on Linux.
Table 10-5. AH match options
Match
--ahspi
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p 51 -m ah --ahspi
500
Explanation
This matches the AH Security Parameter Index (SPI) number of the AH packets.
Please note that you must specify the protocol as well, since AH runs on a
different protocol than the standard TCP, UDP or ICMP protocols. The SPI number
is used in conjunction with the source and destination address and the secret
keys to create a security association (SA). The SA uniquely identifies each
and every one of the IPSEC tunnels to all hosts. The SPI is used to uniquely
distinguish each IPSEC tunnel connected between the same two peers. Using the
--ahspi match, we can match a packet based on the SPI of
the packets. This match can match a whole range of SPI values by using a :
sign, such as 500:520, which will match the whole range of SPI's.
Table 10-6. ESP match options
Match
--espspi
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p 50 -m esp --espspi
500
Explanation
The ESP counterpart Security Parameter Index (SPI) is used exactly the same way
as the AH variant. The match looks exactly the same, with the esp/ah
difference. Of course, this match can match a whole range of SPI numbers as
well as the AH variant of the SPI match, such as --espspi 200:250 which
matches the whole range of SPI's.
The conntrack match is an extended version of the state
match, which makes it possible to match packets in a much more granular way. It
let's you look at information directly available in the connection tracking
system, without any "frontend" systems, such as in the state match. For more
information about the connection tracking system, take a look at the The state machine chapter.
There are a number of different matches put together in the conntrack match,
for several different fields in the connection tracking system. These are
compiled together into the list below. To load these matches, you need to
specify -m conntrack.
Table 10-7. Conntrack match options
Match
--ctstate
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m conntrack --ctstate RELATED
Explanation
This match is used to match the state of a packet, according to the conntrack
state. It is used to match pretty much the same states as in the original
state match. The valid entries for this match are:
INVALID
ESTABLISED
NEW
RELATED
SNAT
DNAT
The entries can be used together with each other separated by a comma. For
example, -m conntrack --ctstate ESTABLISHED,RELATED. It can
also be inverted by putting a ! in front of --ctstate. For
example: -m conntrack ! --ctstate ESTABLISHED,RELATED, which
matches all but the ESTABLISHED and
RELATED states.
Match
--ctproto
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m conntrack --ctproto
TCP
Explanation
This matches the protocol, the same as the --protocol does.
It can take the same types of values, and is inverted using the ! sign. For
example, -m conntrack ! --ctproto TCP matches all protocols
but the TCP protocol.
Match
--ctorigsrc
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m conntrack --ctorigsrc
192.168.0.0/24
Explanation
--ctorigsrc matches based on the original source IP
specification of the conntrack entry that the packet is related to. The match
can be inverted by using a ! between the --ctorigsrc and
IP specification, such as --ctorigsrc ! 192.168.0.1. It
can also take a netmask of the CIDR form, such as --ctorigsrc
192.168.0.0/24.
Match
--ctorigdst
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m conntrack --ctorigdst
192.168.0.0/24
Explanation
This match is used exactly as the --ctorigsrc, except that
it matches on the destination field of the conntrack entry. It has the same
syntax in all other respects.
Match
--ctreplsrc
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m conntrack --ctreplysrc
192.168.0.0/24
Explanation
The --ctreplysrc match is used to match based on the
original conntrack reply source of the packet. Basically, this is the same
as the --ctorigsrc, but instead we match the reply source
expected of the upcoming packets. This target can, of course, be inverted and
address a whole range of addresses, just the same as the the previous targets
in this class.
Match
--ctrepldst
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m conntrack --ctreplydst
192.168.0.0/24
Explanation
The --ctreplydst match is the same as the
--ctreplysrc match, with the exception that it matches the
reply destination of the conntrack entry that matched the packet. It too can
be inverted, and accept ranges, just as the --ctreplysrc
match.
Match
--ctstatus
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m conntrack --ctstatus
RELATED
Explanation
This matches the status of the connection, as described in the The state machine chapter. It can
match the following statuses.
NONE - The connection has no status at all.
EXPECTED - This connection is expected and was added by one of the expectation
handlers.
SEEN_REPLY - This connection has seen a reply but isn't assured yet.
ASSURED - The connection is assured and will not be removed until it times out
or the connection is closed by either end.
This can also be inverted by using the ! sign. For example -m
conntrack ! --ctstatus ASSURED which will match all but the ASSURED
status.
Match
--ctexpire
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m conntrack --ctexpire 100:150
Explanation
This match is used to match on packets based on how long is left on the
expiration timer of the conntrack entry, measured in seconds. It can either
take a single value and match against, or a range such as in the example
above. It can also be inverted by using the ! sign, such as this
-m conntrack ! --ctexpire 100. This will match every
expiration time, which does not have exactly 100 seconds left to it.
This match is used to match on packets based on their DSCP (Differentiated
Services Code Point) field. This is documented in the RFC 2638 - A Two-bit Differentiated Services Architecture
for the Internet RFC. The match is
explicitly loaded by specifying -m dscp. The match can take
two mutually exclusive options, described below.
Table 10-8. DSCP match options
Match
--dscp
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m dscp --dscp 32
Explanation
This option takes a DSCP value in either decimal or in hex. If the option
value is in decimal, it would be written like 32 or 16, et cetera. If written
in hex, it should be prefixed with 0x, like this: 0x20. It can also be
inverted by using the ! character, like this: -m dscp ! --dscp
32.
Match
--dscp-class
Kernel
2.5 and 2.6
Example
iptables -A INPUT -p tcp -m dscp --dscp-class BE
Explanation
The --dscp-class match is used to match on the DiffServ
class of a packet. The values can be any of the BE, EF, AFxx or CSx classes as
specified in the various RFC's. This match can be inverted just the same way
as the --dscp option.
Please note that the --dscp and --dscp-class options are mutually exclusive
and can not be used in conjunction with each other.
The ECN match is used to match on the different ECN fields in the TCP and IPv4
headers. ECN is described in detail in the RFC 3168 - The Addition of Explicit Congestion Notification
(ECN) to IP RFC. The match is explicitly loaded by
using -m ecn in the command line. The ECN match takes three
different options as described below.
Table 10-9. ECN match options
Match
--ecn
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m ecn --ecn-tcp-cwr
Explanation
This match is used to match the CWR
(Congestion Window Received) bit, if it has been set.
The CWR flag is set to notify the other endpoint of
the connection that they have received an ECE, and
that they have reacted to it. Per default this matches if the CWR bit is set, but the match may also be inversed using an exclamation
point.
Match
--ecn-tcp-ece
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m ecn --ecn-tcp-ece
Explanation
This match can be used to match the ECE
(ECN-Echo) bit. The ECE is
set once one of the endpoints has received a packet with the
CE bit set by a router. The endpoint then sets the
ECE in the returning ACK packet, to notify the other
endpoint that it needs to slow down. The other endpoint then sends a
CWR packet as described in the
--ecn-tcp-cwr explanation. This matches per default if the
ECE bit is set, but may be inversed by using an
exclamation point.
Match
--ecn-ip-ect
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m ecn --ecn-ip-ect 1
Explanation
The --ecn-ip-ect match is used to match the
ECT (ECN Capable Transport)
codepoints. The ECT codepoints has several types of
usage. Mainly, they are used to negotiate if the connection is
ECN capable by setting one of the two bits to 1. The
ECT is also used by routers to indicate that they are
experiencing congestion, by setting both ECT
codepoints to 1. The ECT values are all available in the in the ECN Field in IP table below.
The match can be inversed using an exclamation point, for example
! --ecn-ip-ect 2 which will match all ECN values but the
ECT(0) codepoint. The valid value range is 0-3 in iptables. See the above
table for their values.
Table 10-10. ECN Field in IP
Iptables value
ECT
CE
[Obsolete] RFC 2481 names for the ECN bits.
0
0
0
Not-ECT, ie. non-ECN capable connection.
1
0
1
ECT(1), New naming convention of ECT codepoints in RFC
3168.
2
1
0
ECT(0), New naming convention of ECT codepoints in RFC
3168.
3
1
1
CE (Congestion Experienced), Used to notify endpoints of
congestion
This is a rather unorthodox match in comparison to the other matches, in the
sense that it uses a little bit specific syntax. The match is used to match
packets, based on which conntrack helper that the packet is related to. For
example, let's look at the FTP session. The Control
session is opened up, and the ports/connection is negotiated for the Data
session within the Control session. The ip_conntrack_ftp
helper module will find this information, and create a related entry in the
conntrack table. Now, when a packet enters, we can see which protocol it was
related to, and we can match the packet in our ruleset based on which helper
was used.
Table 10-11. Helper match options
Match
--helper
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m helper --helper ftp-21
Explanation
The --helper option is used to specify a string value,
telling the match which conntrack helper to match. In the basic form, it may
look like --helper irc. This is where the syntax starts to
change from the normal syntax. We can also choose to only match packets based
on which port that the original expectation was caught on. For example, the
FTP Control session is normally transferred over port
21, but it may as well be port 954 or any other port. We may then specify upon
which port the expectation should be caught on, like --helper ftp-954.
The IP range match is used to match IP ranges, just as the --source and --destination matches are able to do as
well. However, this match adds a different kind of matching in the sense that
it is able to match in the manner of from IP - to IP, which the --source and --destination matches are unable to.
This may be needed in some specific network setups, and it is rather a bit
more flexible.
Table 10-12. IP range match options
Match
--src-range
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m iprange --src-range 192.168.1.13-192.168.2.19
Explanation
This matches a range of source IP addresses. The range includes every single IP address from the first to the last, so the example above includes everything from 192.168.1.13 to 192.168.2.19. The match may also be inverted by adding an !. The above example would then look like -m iprange ! --src-range 192.168.1.13-192.168.2.19, which would match every single IP address, except the ones specified.
Match
--dst-range
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m iprange --dst-range 192.168.1.13-192.168.2.19
Explanation
The --dst-range works exactly the same as the --src-range match, except that it matches destination IP's instead
of source IP's.
The length match is used to match packets based on their length. It is very
simple. If you want to limit packet length for some strange reason, or want to
block ping-of-death-like behaviour, use the length match.
Table 10-13. Length match options
Match
--length
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m length --length 1400:1500
Explanation
The example --length will match all packets with a length
between 1400 and 1500 bytes. The match may also be inversed using the ! sign, like this: -m length ! --length 1400:1500
. It may also be used to match only a specific length, removing the : sign and
onwards, like this: -m length --length 1400. The range
matching is, of course, inclusive, which means that it includes all packet
lengths in between the values you specify.
The limit match extension must be loaded
explicitly with the -m limit option. This match can,
for example, be used to advantage to give limited logging of specific
rules etc. For example, you could use this to match all packets that do
not exceed a given value, and after this value has been exceeded,
limit logging of the event in question. Think of a time
limit: You could limit how many times a certain rule may be matched in a
certain time frame, for example to lessen the effects of
DoS syn flood attacks. This is its main usage, but
there are more usages, of course. The limit match may
also be inverted by adding a ! flag in front of the
limit match. It would then be expressed as -m limit !
--limit 5/s.This means that all packets will be matched after they
have broken the limit.
To further explain the limit match, it is basically a token
bucket filter. Consider having a leaky bucket where the bucket leaks X
packets per time-unit. X is defined depending on how many matching packets
we get, so if we get 3 packets, the bucket leaks 3 packets per that
time-unit. The --limit option tells us how many packets
to refill the bucket with per time-unit, while the
--limit-burst option tells us how big the bucket is in
the first place. So, setting --limit 3/minute --limit-burst
5, and then receiving 5 matches will empty the bucket. After 20
seconds, the bucket is refilled with another token, and so on until the
--limit-burst is reached again or until they get used.
Consider the example below for further explanation of how this may look.
We set a rule with -m limit --limit 5/second --limit-burst 10/second.
The limit-burst token bucket is set to 10 initially. Each packet that matches
the rule uses a token.
We get packet that matches, 1-2-3-4-5-6-7-8-9-10, all within a 1/1000 of a
second.
The token bucket is now empty. Once the token bucket is empty, the packets
that qualify for the rule otherwise no longer match the rule and proceed to
the next rule if any, or hit the chain policy.
For each 1/5 s without a matching packet, the token count goes up by 1, upto a
maximum of 10. 1 second after receiving the 10 packets, we will once again have
5 tokens left.
And of course, the bucket will be emptied by 1 token for each packet it
receives.
Table 10-14. Limit match options
Match
--limit
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A INPUT -m limit --limit
3/hour
Explanation
This sets the maximum average match rate for the
limit match. You specify it with a number and an optional
time unit. The following time units are currently recognized:
/second/minute/hour/day. The default value here is 3 per hour, or
3/hour. This tells the limit match how
many times to allow the match to occur per time unit (e.g. per
minute).
Match
--limit-burst
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A INPUT -m limit --limit-burst
5
Explanation
This is the setting for the burst
limit of the limit match. It tells
iptables the maximum number of packets to match within the
given time unit. This number gets decremented by one for every time unit
(specified by the --limit option) in which the event does
not occur, back down to the lowest possible value, 1. If the event is
repeated, the counter is again incremented, until the count reaches the burst
limit. And so on. The default --limit-burst value is 5. For
a simple way of checking out how this works, you can use the example Limit-match.txt
one-rule-script. Using this script, you can see for yourself how the limit
rule works, by simply sending ping packets at different intervals and in
different burst numbers. All echo replies will be
blocked until the threshold for the burst limit has again been reached.
The MAC (Ethernet Media
Access Control) match can be used to match packets based on their
MAC source address. As of writing this documentation,
this match is a little bit limited, however, in the future this may be more
evolved and may be more useful. This match can be used to match packets on the
source MAC address only as previously said.
Do note that to use this module we explicitly load it with the -m
mac option. The reason that I am saying this is that a lot of people
wonder if it should not be -m mac-source, which it should
not.
Table 10-15. MAC match options
Match
--mac-source
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A INPUT -m mac --mac-source
00:00:00:00:00:01
Explanation
This match is used to match packets based on their
MAC source address. The MAC
address specified must be in the form
XX:XX:XX:XX:XX:XX, else it will not be legal. The match
may
be reversed with an ! sign and would look like
--mac-source ! 00:00:00:00:00:01. This would in other words
reverse the meaning of the match, so that all packets except packets from this
MAC address would be matched. Note that since
MAC addresses are only used on Ethernet type
networks, this match will only be possible to use for Ethernet interfaces. The
MAC match is only valid in the
PREROUTING, FORWARD and
INPUT chains and nowhere else.
The mark match extension is used to match packets based on
the marks they have set. A mark is a special field, only
maintained within the kernel, that is associated with the packets as they
travel through the computer. Marks may be used by different kernel
routines for such tasks as traffic shaping and filtering. As of today, there
is only one way of setting a mark in Linux, namely the
MARK target in iptables. This was
previously done with the FWMARK target in
ipchains, and this is why people still refer to
FWMARK in advanced routing areas. The mark field is
currently set to an unsigned integer, or 4294967296 possible values on a
32 bit system. In other words, you are probably not going to run into this
limit for quite some time.
Table 10-16. Mark match options
Match
--mark
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -t mangle -A INPUT -m mark --mark
1
Explanation
This match is used to match packets that have previously
been marked. Marks can be set with the MARK target
which we will discuss in the next section. All packets traveling through
Netfilter get a special mark
field associated with them. Note that this mark
field is not in any way propagated, within or outside the
packet. It stays inside the computer that made it. If the mark
field matches the mark, it is a match. The mark
field is an unsigned integer, hence there can be a maximum of
4294967296 different marks. You may also use a mask with the mark. The
mark specification would then look like, for example, --mark
1/1. If a mask is specified, it is logically AND ed with the mark
specified before the actual comparison.
The multiport match extension can be used to specify
multiple
destination ports and port ranges. Without the possibility this match
gives, you would have to use multiple rules of the same type, just to
match different ports.
You can not use both standard port matching and multiport matching at the
same time, for example you can't write: --sport 1024:63353 -m
multiport --dport 21,23,80. This will simply not work. What in fact
happens, if you do, is that iptables honors the first element in the rule, and
ignores the multiport instruction.
Table 10-17. Multiport match options
Match
--source-port
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m multiport --source-port
22,53,80,110
Explanation
This match matches multiple source ports. A maximum of 15
separate ports may be specified. The ports must be comma delimited, as in the
above example. The match may only be used in conjunction with the -p
tcp or -p udp matches. It is mainly an enhanced
version of the normal --source-port match.
Match
--destination-port
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m multiport
--destination-port
22,53,80,110
Explanation
This match is used to match multiple destination ports. It
works exactly the same way as the above mentioned source port match, except
that it matches destination ports. It too has a limit of 15 ports and may only
be used in conjunction with -p tcp and -p
udp.
Match
--port
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m multiport --port
22,53,80,110
Explanation
This match extension can be used to match packets based
both on their destination port and their source port. It works the same
way as the --source-port and
--destination-port matches above. It can take a maximum of
15 ports and can only be used in conjunction with -p tcp
and -p udp. Note that the --port match
will only match packets coming in from and going to the same port, for
example, port 80 to port 80, port 110 to port 110 and so on.
The owner match extension is used to match packets based
on the identity of the process that created them. The owner
can be specified as the process ID either of the user who issued the command
in question, that of the group, the process, the session, or that of the
command itself. This extension was originally written as an example of what
iptables could be used for. The owner
match only works within the OUTPUT chain, for obvious
reasons: It is pretty much impossible to find out any information about the
identity of the instance that sent a packet from the other end, or where there
is an intermediate hop to the real destination. Even within the
OUTPUT chain it is not very reliable, since certain
packets may not have an owner. Notorious packets of that sort are (among
other things) the different ICMP responses.
ICMP responses will never match.
Table 10-18. Owner match options
Match
--uid-owner
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m owner --uid-owner
500
Explanation
This packet match will match if the packet was created by
the given User ID (UID). This could be used
to
match outgoing packets based on who created them. One possible use would be to
block any other user than root from opening new connections outside your
firewall. Another possible use could be to block everyone but the
http user from sending packets from the
HTTP port.
Match
--gid-owner
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m owner --gid-owner
0
Explanation
This match is used to match all packets based on their
Group ID (GID). This means that we match all
packets based on what group the user creating the packets is in. This could
be used to block all but the users in the
network group from getting out onto the
Internet or, as described above, only to allow members of the
http group to create packets going out from
the HTTP port.
Match
--pid-owner
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m owner --pid-owner
78
Explanation
This match is used to match packets based on the
Process ID (PID) that was
responsible for them. This match is a bit harder to use, but one example would
be only to allow PID 94 to send packets from the
HTTP port (if the HTTP
process is not threaded, of course). Alternatively we could write a small
script that grabs the PID from a
ps output for a specific daemon and then adds a rule for
it. For an example, you could have a rule as shown in the Pid-owner.txt example.
Match
--sid-owner
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m owner --sid-owner
100
Explanation
This match is used to match packets based on the
Session ID used by the program in question. The value
of the SID, or Session ID of
a process, is that of the process itself and all processes resulting from the
originating process. These latter could be threads, or a child of the original
process. So, for example, all of our HTTPD processes
should have the same SID as their parent process (the
originating HTTPD process), if our
HTTPD is threaded (most
HTTPDs are, Apache and Roxen for instance). To show
this in example, we have created a small script called Sid-owner.txt. This script could
possibly be run every hour or so together with some extra code to check if the
HTTPD is actually running and start it again if
necessary, then flush and re-enter our OUTPUT chain
if needed.
The packet type match is used to match packets based on their type. I.e., are
they destined to a specific person, to everyone or to a specific group of
machines or users. These three groups are generally called unicast, broadcast
and multicast, as discussed in the TCP/IP repetition chapter. The match is loaded by using
-m pkttype.
Table 10-19. Packet type match options
Match
--pkttype
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m owner --pkttype unicast
Explanation
The --pkttype match is used to tell the packet type match
which packet type to match. It can either take unicast
, broadcast or multicast as
an argument, as in the example. It can also be inverted by using a ! like this: -m pkttype --pkttype ! broadcast,
which will match all other packet types.
The recent match is a rather large and complex matching system, which allows
us to match packets based on recent events that we have previously matched.
For example, if we would see an outgoing IRC connection, we could set the IP
addresses into a list of hosts, and have another rule that allows identd
requests back from the IRC server within 15 seconds of seeing the original
packet.
Before we can take a closer look at this match, let's try and explain a little
bit how it works. First of all, we use several different rules to accomplish
the use of the recent match. The recent match uses several different lists of
recent events. The default list being used is the DEFAULT list. We create a new
entry in a list with the set option, so once a rule is entirely matched (the
set option is always a match), we also add an entry in the recent list
specified. The list entry contains a timestamp, and the source IP address used
in the packet that triggered the set option. Once this has happened, we can
use a series of different recent options to match on this information, as well
as update the entries timestamp, et cetera.
Finally, if we would for some reason want to remove a list entry, we would do this using the remove match from the recent module. All rules using the recent match, must load the recent module (-m recent) as usual. Before we go on with an example of the recent match, let's take a look at all the options.
Table 10-20. Recent match options
Match
--name
Kernel
2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m recent --name examplelist
Explanation
The name option gives the name of the list to use. Per default the DEFAULT
list is used, which is probably not what we want if we are using more than one
list.
Match
--set
Kernel
2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m recent --set
Explanation
This creates a new list entry in the named recent list, which contains a
timestamp and the source IP address of the host that triggered the rule. This
match will always return success, unless it is preceded by a ! sign, in which
case it will return failure.
Match
--rcheck
Kernel
2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m recent --name examplelist --rcheck
Explanation
The --rcheck option will check if the source IP address of
the packet is in the named list. If it is, the match will return true,
otherwise it returns false. The option may be inverted by using the ! sign. In
the later case, it will return true if the source IP address is not in the
list, and false if it is in the list.
Match
--update
Kernel
2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m recent --name examplelist --update
Explanation
This match is true if the source combination is available in the specified
list and it also updates the last-seen time in the list. This match may also be
reversed by setting the ! mark in front of the match. For
example, ! --update.
Match
--remove
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -m recent --name example --remove
Explanation
This match will try to find the source address of the packet in the list, and
returns true if the packet is there. It will also remove the corresponding
list entry from the list. The command is also possible to inverse with the ! sign.
Match
--seconds
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -m recent --name example --check --seconds 60
Explanation
This match is only valid together with the --check and
--update matches. The --seconds match is
used to specify how long since the "last seen" column was updated in the recent
list. If the last seen column was older than this amount in seconds, the match
returns false. Other than this the recent match works as normal, so the
source address must still be in the list for a true return of the match.
Match
--hitcount
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -m recent --name example --check --hitcount 20
Explanation
The --hitcount match must be used together with the
--check or --update matches and it will
limit the match to only include packets that have seen at least the hitcount
amount of packets. If this match is used together with the
--seconds match, it will require the specified hitcount
packets to be seen in the specific timeframe. This match may also be reversed
by adding a ! sign in front of the match. Together with the
--seconds match, this means that a maximum of this amount
of packets may have been seen during the specified timeframe. If both of the
matches are inversed, then a maximum of this amount of packets may have been
seen during the last minumum of seconds.
Match
--rttl
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -m recent --name example --check --rttl
Explanation
The --rttl match is used to verify that the
TTL value of the current packet is the same as the
original packet that was used to set the original entry in the recent list.
This can be used to verify that people are not spoofing their source address
to deny others access to your servers by making use of the recent match.
Match
--rsource
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -m recent --name example --rsource
Explanation
The --rsource match is used to tell the recent match to
save the source address and port in the recent list. This is the default
behavior of the recent match.
Match
--rdest
Kernel
2.4, 2.5 and 2.6
Example
iptables -A INPUT -m recent --name example --rdest
Explanation
The --rdest match is the opposite of the
--rsource match in that it tells the recent match to save
the destination address and port to the recent list.
I have created a small sample script of how the recent
match can be used, which you can find in the Recent-match.txt section.
Briefly, this is a poor
replacement for the state engine available in netfilter. This version was
created with a http server in mind, but will work with any
TCP connection. First we have created two chains named
http-recent and
http-recent-final. The
http-recent chain is used in the starting stages of
the connection, and for the actual data transmission, while the
http-recent-final chain is used for the last and final
FIN, FIN/ACK handshake.
This is a very bad replacement for the built in state engine and can not handle
all of the possibilities that the state engine can handle. However, it is a
good example of what can be done with the recent match without being too
specific. Do not use this example in a real world environment. It is slow,
handles special cases badly, and should generally never be used more than as an
example.
For example, it does not handle closed ports on connection,
asyncronuous FIN handshake (where one of the connected parties closes down,
while the other continues to send data), etc.
Let's follow a packet through the example ruleset. First a packet enters the
INPUT chain, and we send it to the
http-recent chain.
The first packet should be a SYN packet, and should not have the ACK,FIN or RST
bits set. Hence it is matched using the --tcp-flags SYN,ACK,FIN,RST
SYN line. At this point we add the connection to the httplist using
-m recent --name httplist --set line. Finally we accept the
packet.
After the first packet we should receive a SYN/ACK packet to acknowledge that
the SYN packet was received. This can be matched using the
--tcp-flags SYN,ACK,FIN,RST SYN,ACK line. FIN and RST
should be illegal at this point as well. At this point we update the entry in
the httplist using -m recent --name httplist --update and
finally we ACCEPT the packet.
By now we should get a final ACK packet, from the
original creater of the connection, to acknowledge the SYN/ACK sent by the
server. SYN, FIN and RST are illegal at this point of the connection, so the
line should look like --tcp-flags SYN,ACK,FIN,RST ACK. We
update the list in exactly the same way as in the previous step, and ACCEPT it.
At this point the data tranmission can start. The connection should never
contain any SYN packet now, but it will contain ACK packets to acknowledge the
data packets that are sent. Each time we see any packet like this, we update
the list and ACCEPT the packets.
The transmission can be ended in two ways, the simplest is the RST packet. RST
will simply reset the connection and it will die. With FIN, the other endpoint
answers with a FIN,ACK, and this closes down the connection so that the
original source of the FIN can no longer send any data. The receiver of the
FIN, will still be able to send data, hence we send the connection to a
"final" stage chain to handle the rest.
In the http-recent-final chain we check if the packet is still in the httplist,
and if so, we send it to the http-recent-final1 chain. In that chain we remove
the connection from the httplist and add it to the http-recent-final list
instead. If the connection has already been removed and moved over to the
http-recent-final list, we send te packet to the http-recent-final2 chain.
In the final http-recent-final2 chain, we wait for the non-closed side to
finish sending its data, and to close the connection from their side as well.
Once this is done, the connection is completely removed.
As you can see the recent list can become quite complex, but it will give you
a huge set of possibilities if need be. Still, try and remember not to
reinvent the wheel. If the ability you need is already implemented, try and use
it instead of trying to create your own solution.
The state match extension is used in conjunction with the
connection tracking code in the kernel. The state match accesses the connection
tracking state of the packets from the conntracking machine. This allows us to
know in what state the connection is, and works for pretty much all protocols,
including stateless protocols such as ICMP and
UDP. In all cases,
there will be a default timeout for the connection and it will then be dropped
from the connection tracking database. This match needs to be loaded
explicitly by adding a -m state statement to the rule. You
will then have access to one new match called state. The concept of state
matching is covered more fully in the The state machine chapter, since it is such a large topic.
Table 10-21. State matches
Match
--state
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A INPUT -m state --state
RELATED,ESTABLISHED
Explanation
This match option tells the state
match what states the packets must be in to be matched. There are currently 4
states that can be used. INVALID,
ESTABLISHED, NEW and
RELATED. INVALID means that the packet is
associated with no known stream or connection and that it may contain faulty
data or headers. ESTABLISHED means that the packet is part
of an already established connection that has seen packets in both directions
and is fully valid. NEW means that the packet has or will
start a new connection, or that it is associated with a connection that has not
seen packets in both directions. Finally, RELATED means that
the packet is starting a new connection and is associated with an already
established connection. This could for example mean an FTP data
transfer, or an ICMP error associated
with a TCP or UDP
connection. Note that the NEW state does not look for
SYN bits in TCP packets
trying to start a new connection and should, hence, not be used unmodified in
cases where we have only one firewall and no load balancing between different
firewalls. However, there may be times where this could be useful. For more
information on how this could be used, read the The state machine chapter.
iptables -A INPUT -p tcp --tcp-flags SYN,ACK,RST SYN -m tcpmss --mss 2000:2500
Explanation
The --mss option tells the tcpmss match which Maximum Segment Sizes to match. This can either be a single
specific MSS value, or a range of
MSS values separated by a :. The
value may also be inverted as usual using the ! sign, as in
the following example:
-m tcpmss ! --mss 2000:2500
. This
example will match all MSS values, except for values
in the range 2000 through 2500.
The TOS match can be used to match packets based on their
TOS field. TOS stands for
Type Of Service, consists of 8 bits, and is located
in the IP header. This match is loaded explicitly by adding -m
tos to the rule. TOS is normally used to
inform intermediate hosts of the precedence of the stream and its content (it
doesn't really, but it informs of any specific requirements for the stream,
such as it having to be sent as fast as possible, or it needing to be able to
send as much payload as possible). How different routers and administrators
deal with these values depends. Most do not care at all, while others try
their best to do something good with the packets in question and the data they
provide.
Table 10-23. TOS matches
Match
--tos
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A INPUT -p tcp -m tos --tos
0x16
Explanation
This match is used as described above. It can match packets
based on their TOS field and their value. This could
be used, among other things together with the iproute2
and advanced routing functions in Linux, to mark packets
for later usage. The match takes a hex or numeric value as an option, or
possibly one of the names resulting from 'iptables -m tos
-h'. At the time of writing it contained the following named values:
Minimize-Delay 16 (0x10),
Maximize-Throughput 8 (0x08),
Maximize-Reliability 4 (0x04),
Minimize-Cost 2 (0x02), and
Normal-Service 0 (0x00).
Minimize-Delay means to minimize the delay in
putting the packets through - example of standard services that would require
this include telnet, SSH and
FTP-control.
Maximize-Throughput means to find a path that
allows as big a throughput as possible - a standard protocol would be
FTP-data.
Maximize-Reliability means to maximize the
reliability of the connection and to use lines that are as reliable as
possible - a couple of typical examples are BOOTP and
TFTP. Minimize-Cost
means minimizing the cost of packets getting through each link to the client
or server; for example finding the route that costs the least to travel along.
Examples of normal protocols that would use this would be
RTSP (Real Time Stream Control Protocol) and other
streaming video/radio protocols. Finally,
Normal-Service would mean any normal protocol
that has no special needs.
The TTL match is used to match packets based on their
TTL (Time To Live) field residing in the IP headers.
The TTL field contains 8 bits of data and is
decremented once every time it is processed by an intermediate host between
the client and recipient host. If the TTL reaches 0,
an ICMP type 11 code 0 (TTL equals 0 during transit)
or code 1 (TTL equals 0 during reassembly) is transmitted to the party sending
the packet and informing it of the problem. This match is only used to match
packets based on their TTL, and not to change
anything. The latter, incidentally, applies to all kinds of matches. To load
this match, you need to add an -m ttl to the rule.
Table 10-24. TTL matches
Match
--ttl
Kernel
2.3, 2.4, 2.5 and 2.6
Example
iptables -A OUTPUT -m ttl --ttl 60
Explanation
This match option is used to specify the
TTL value to match. It takes a numeric value and
matches this value within the packet. There is no inversion and there are no
other specifics to match. It could, for example, be used for debugging your
local network - e.g. LAN hosts that seem to have problems connecting to hosts
on the Internet - or to find possible ingress by Trojans etc. The usage is
relatively limited, however; its usefulness really depends on your
imagination. One example would be to find hosts with bad default
TTL values (could be due to a badly implemented
TCP/IP stack, or simply to misconfiguration).
The unclean match takes no options and requires
no more than explicitly loading it when you want to use it. Note that this
option is regarded as experimental and may not work at all times, nor will it
take care of all unclean packages or problems. The unclean match tries to
match packets that seem malformed or unusual, such as packets with bad headers
or checksums and so on. This could be used to DROP
connections and to check for bad streams, for example; however you should be
aware that it could possibly break legal connections.
