.\" Automatically generated by Pandoc 3.1.3
.nh
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "firehol-actions" "5" "Built 30 Mar 2024" "FireHOL Reference" "3.1.7"
.hy
.SH NAME
.PP
firehol-actions - actions for rules
.SH SYNOPSIS
.PP
accept
.PP
accept with hashlimit \f[I]name\f[R] upto|above \f[I]amount/period\f[R]
[burst \f[I]amount\f[R]] [mode
\f[I]{srcip|srcport|dstip|dstport},\&...\f[R]] [srcmask
\f[I]prefix\f[R]] [dstmask \f[I]prefix\f[R]] [htable-size
\f[I]buckets\f[R]] [htable-max \f[I]entries\f[R]] [htable-expire
\f[I]msec\f[R]] [htable-gcinterval \f[I]msec\f[R]]
.PP
accept with connlimit upto|above \f[I]limit\f[R] [mask \f[I]mask\f[R]]
[saddr|daddr]
.PP
accept with limit \f[I]requests/period burst\f[R] [overflow
\f[I]action\f[R]]
.PP
accept with recent \f[I]name\f[R] \f[I]seconds\f[R] \f[I]hits\f[R]
.PP
accept with knock \f[I]name\f[R]
.PP
reject [with \f[I]message\f[R]]
.PP
drop | deny
.PP
return
.PP
tarpit
.SH DESCRIPTION
.PP
These actions are the actions to be taken on traffic that has been
matched by a particular rule.
.PP
FireHOL will also pass through any actions that iptables(8) accepts,
however these definitions provide lowercase versions which accept
arguments where appropriate and which could otherwise not be passed
through.
.RS
.PP
\f[B]Note\f[R]
.PP
The iptables(8) LOG action is best used through the optional rule
parameter \f[V]log\f[R] since the latter can be combined with one of
these actions (FireHOL will generate multiple firewall rules to make
this happen).
For more information see log and loglimit.
.RE
.PP
The following actions are defined:
.SS accept
.PP
\f[V]accept\f[R] allows the traffic matching the rules to reach its
destination.
.PP
For example, to allow SMTP requests and their replies to flow:
.IP
.nf
\f[C]
server smtp accept
                
\f[R]
.fi
.SS accept with hashlimit \f[I]name\f[R] upto|above \f[I]amount/period\f[R] [burst \f[I]amount\f[R]] [mode \f[I]{srcip|srcport|dstip|dstport},\&...\f[R]] [srcmask \f[I]prefix\f[R]] [dstmask \f[I]prefix\f[R]] [htable-size \f[I]buckets\f[R]] [htable-max \f[I]entries\f[R]] [htable-expire \f[I]msec\f[R]] [htable-gcinterval \f[I]msec\f[R]]
.PP
\f[V]hashlimit\f[R] hashlimit uses hash buckets to express a rate
limiting match (like the limit match) for a group of connections using a
single iptables rule.
Grouping can be done per-hostgroup (source and/or destination address)
and/or per-port.
.PP
\f[I]name\f[R] The name for the /proc/net/ipt_hashlimit/\f[I]name\f[R]
entry.
.PP
\f[V]upto\f[R] \f[I]amount[/second|/minute|/hour|/day]\f[R] Match if the
rate is below or equal to amount/quantum.
It is specified either as a number, with an optional time quantum suffix
(the default is 3/hour).
.PP
\f[V]above\f[R] \f[I]amount[/second|/minute|/hour|/day]\f[R] Match if
the rate is above amount/quantum.
.PP
\f[V]burst\f[R] \f[I]amount\f[R] Maximum initial number of packets to
match: this number gets recharged by one every time the limit specified
above is not reached, up to this number; the default is 5.
This option should be used with caution - if the entry expires, the
burst value is reset too.
.PP
\f[V]mode\f[R] \f[I]{srcip|srcport|dstip|dstport},\&...\f[R] A
comma-separated list of objects to take into consideration.
If no \f[V]mode\f[R] option is given, \f[I]srcip,dstport\f[R] is
assumed.
.PP
\f[V]srcmask\f[R] \f[I]prefix\f[R] When \[en]hashlimit-mode srcip is
used, all source addresses encountered will be grouped according to the
given prefix length and the so-created subnet will be subject to
hashlimit.
prefix must be between (inclusive) 0 and 32.
Note that \f[V]srcmask\f[R] \f[I]0\f[R] is basically doing the same
thing as not specifying srcip for \f[V]mode\f[R], but is technically
more expensive.
.PP
\f[V]dstmask\f[R] \f[I]prefix\f[R] Like \f[V]srcmask\f[R], but for
destination addresses.
.PP
\f[V]htable-size\f[R] \f[I]buckets\f[R] The number of buckets of the
hash table
.PP
\f[V]htable-max\f[R] \f[I]entries\f[R] Maximum entries in the hash.
.PP
\f[V]htable-expire\f[R] \f[I]msec\f[R] After how many milliseconds do
hash entries expire.
.PP
\f[V]htable-gcinterval\f[R] \f[I]msec\f[R] How many milliseconds between
garbage collection intervals.
.PP
Examples:
.PP
Allow up to 5 connections per second per client to SMTP server:
.IP
.nf
\f[C]
server smtp accept with hashlimit smtplimit upto 5/s
\f[R]
.fi
.PP
You can monitor it using the file /proc/net/ipt_hashlimit/smtplimit
.SS accept with connlimit upto|above \f[I]limit\f[R] [mask \f[I]mask\f[R]] [saddr|daddr]
.PP
\f[V]accept with connlimit\f[R] matches on the number of connections per
IP.
.PP
\f[I]saddr\f[R] matches on source IP.
\f[I]daddr\f[R] matches on destination IP.
\f[I]mask\f[R] groups IPs with the \f[I]mask\f[R] given \f[I]upto\f[R]
matches when the number of connections is up to the given
\f[I]limit\f[R] \f[I]above\f[R] matches when the number of connections
above to the given \f[I]limit\f[R]
.PP
The number of connections counted are system wide, not service specific.
For example for \f[I]saddr\f[R], you cannot connlimit 2 connections for
SSH and 4 for SMTP.
If you connlimit 2 connections for SSH, then the first 2 connections of
a client can be SSH.
If a client has already 2 connections to another service, the client
will not be able to connect to SSH.
.PP
So, \f[V]connlimit\f[R] can safely be used:
.IP \[bu] 2
with \f[I]daddr\f[R] to limit the connections a server can accept
.IP \[bu] 2
with \f[I]saddr\f[R] to limit the total connections per client to all
services.
.SS accept with limit \f[I]requests/period burst\f[R] [overflow \f[I]action\f[R]]
.PP
\f[V]accept with limit\f[R] allows the traffic, with new connections
limited to \f[I]requests/period\f[R] with a maximum \f[I]burst\f[R].
Run \f[V]iptables -m limit --help\f[R] for more information.
.PP
The default \f[V]overflow\f[R] \f[I]action\f[R] is to REJECT the excess
connections (DROP would produce timeouts on otherwise valid service
clients).
.PP
Examples:
.IP
.nf
\f[C]

server smtp accept with limit 10/sec 100

server smtp accept with limit 10/sec 100 overflow drop
\f[R]
.fi
.SS accept with recent \f[I]name\f[R] \f[I]seconds\f[R] \f[I]hits\f[R]
.PP
\f[V]accept with recent\f[R] allows the traffic matching the rules to
reach its destination, limited per remote IP to \f[I]hits\f[R] per
\f[I]seconds\f[R].
Run \f[V]iptables -m recent --help\f[R] for more information.
.PP
The \f[I]name\f[R] parameter is used to allow multiple rules to share
the same table of recent IPs.
.PP
For example, to allow only 2 connections every 60 seconds per remote IP,
to the smtp server:
.IP
.nf
\f[C]
server smtp accept with recent mail 60 2
              
\f[R]
.fi
.RS
.PP
\f[B]Note\f[R]
.PP
When a new connection is not allowed, the traffic will continue to be
matched by the rest of the firewall.
In other words, if the traffic is not allowed due to the limitations set
here, it is not dropped, it is just not matched by this rule.
.RE
.SS accept with knock \f[I]name\f[R]
.PP
\f[V]accept with knock\f[R] allows easy integration with
knockd (http://www.zeroflux.org/projects/knock/), a server that allows
you to control access to services by sending certain packets to
\[lq]knock\[rq] on the door, before the door is opened for service.
.PP
The \f[I]name\f[R] is used to build a special chain
knock_<\f[V]name\f[R]> which contains rules to allow established
connections to work.
If knockd has not allowed new connections any traffic entering this
chain will just return back and continue to match against the other
rules until the end of the firewall.
.PP
For example, to allow HTTPS requests based on a knock write:
.IP
.nf
\f[C]
server https accept with knock hidden
                
\f[R]
.fi
.PP
then configure knockd to enable the HTTPS service with:
.IP
.nf
\f[C]
iptables -A knock_hidden -s %IP% -j ACCEPT
                
\f[R]
.fi
.PP
and disable it with:
.IP
.nf
\f[C]
iptables -D knock_hidden -s %IP% -j ACCEPT
                
\f[R]
.fi
.PP
You can use the same knock \f[I]name\f[R] in more than one FireHOL rule
to enable/disable all the services based on a single knockd
configuration entry.
.RS
.PP
\f[B]Note\f[R]
.PP
There is no need to match anything other than the IP in knockd.
FireHOL already matches everything else needed for its rules to work.
.RE
.SS reject
.PP
\f[V]reject\f[R] discards the traffic matching the rules and sends a
rejecting message back to the sender.
.SS reject with \f[I]message\f[R]
.PP
When used with \f[V]with\f[R] the specific message to return can be
specified.
Run \f[V]iptables -j REJECT --help\f[R] for a list of the
\f[V]--reject-with\f[R] values which can be used for \f[I]message\f[R].
See REJECT WITH MESSAGES for some examples.
.PP
The default (no \f[I]message\f[R] specified) is to send
\f[V]tcp-reset\f[R] when dealing with TCP connections and
\f[V]icmp-port-unreachable\f[R] for all other protocols.
.PP
For example:
.IP
.nf
\f[C]

UNMATCHED_INPUT_POLICY=\[dq]reject with host-prohib\[dq]

policy reject with host-unreach

server ident reject with tcp-reset
\f[R]
.fi
.SS drop; deny
.PP
\f[V]drop\f[R] discards the traffic matching the rules.
It does so silently and the sender will need to timeout to conclude it
cannot reach the service.
.PP
\f[V]deny\f[R] is a synonym for \f[V]drop\f[R].
For example, either of these would silently discard SMTP traffic:
.IP
.nf
\f[C]
server smtp drop

server smtp deny
\f[R]
.fi
.SS return
.PP
\f[V]return\f[R] will return the flow of processing to the parent of the
current command.
.PP
Currently, the only time \f[V]return\f[R] can be used meaningfully used
is as a policy for an interface definition.
Unmatched traffic will continue being processed with the possibility of
being matched by a later definition.
For example:
.IP
.nf
\f[C]
policy return
              
\f[R]
.fi
.SS tarpit
.PP
\f[V]tarpit\f[R] captures and holds incoming TCP connections open.
.PP
Connections are accepted and immediately switched to the persist state
(0 byte window), in which the remote side stops sending data and asks to
continue every 60-240 seconds.
.PP
Attempts to close the connection are ignored, forcing the remote side to
time out the connection after 12-24 minutes.
.PP
Example:
.IP
.nf
\f[C]
server smtp tarpit
\f[R]
.fi
.RS
.PP
\f[B]Note\f[R]
.PP
As the kernel conntrack modules are always loaded by FireHOL, some
per-connection resources will be consumed.
See this bug report (http://bugs.sanewall.org/sanewall/issues/10) for
details.
.RE
.PP
The following actions also exist but should not be used under normal
circumstances:
.SS mirror
.PP
\f[V]mirror\f[R] returns the traffic it receives by switching the source
and destination fields.
REJECT will be used for traffic generated by the local host.
.RS
.PP
\f[B]Warning\f[R]
.PP
The MIRROR target was removed from the Linux kernel due to its security
implications.
.PP
MIRROR is dangerous; use it with care and only if you understand what
you are doing.
.RE
.SS redirect; redirect to-port port
.PP
\f[V]redirect\f[R] is used internally by FireHOL helper commands.
.PP
Only FireHOL developers should need to use this action directly.
.SH REJECT WITH MESSAGES
.PP
The following RFCs contain information relevant to these messages:
.IP \[bu] 2
RFC 1812 (http://www.ietf.org/rfc/rfc1812.txt)
.IP \[bu] 2
RFC 1122 (http://www.ietf.org/rfc/rfc1122.txt)
.IP \[bu] 2
RFC 792 (http://www.ietf.org/rfc/rfc0792.txt)
.TP
icmp-net-unreachable; net-unreach
ICMP network unreachable
.RS
.PP
Generated by a router if a forwarding path (route) to the destination
network is not available.
.PP
From RFC 1812, section 5.2.7.1.
See RFC 1812 and RFC 792.
.RS
.PP
\f[B]Note\f[R]
.PP
Use with care.
The sender and the routers between you and the sender may conclude that
the whole network your host resides in is unreachable, and prevent other
traffic from reaching you.
.RE
.RE
.TP
icmp-host-unreachable; host-unreach
ICMP host unreachable
.RS
.PP
Generated by a router if a forwarding path (route) to the destination
host on a directly connected network is not available (does not respond
to ARP).
.PP
From RFC 1812, section 5.2.7.1.
See RFC 1812 and RFC 792.
.RS
.PP
\f[B]Note\f[R]
.PP
Use with care.
The sender and the routers between you and the sender may conclude that
your host is entirely unreachable, and prevent other traffic from
reaching you.
.RE
.RE
.TP
icmp-proto-unreachable; proto-unreach
ICMP protocol unreachable
.RS
.PP
Generated if the transport protocol designated in a datagram is not
supported in the transport layer of the final destination.
.PP
From RFC 1812, section 5.2.7.1.
See RFC 1812 and RFC 792.
.RE
.TP
icmp-port-unreachable; port-unreach
ICMP port unreachable
.RS
.PP
Generated if the designated transport protocol (e.g.\ TCP, UDP, etc.)
is unable to demultiplex the datagram in the transport layer of the
final destination but has no protocol mechanism to inform the sender.
.PP
From RFC 1812, section 5.2.7.1.
See RFC 1812 and RFC 792.
.PP
Generated by hosts to indicate that the required port is not active.
.RE
.TP
icmp-net-prohibited; net-prohib
ICMP communication with destination network administratively prohibited
.RS
.PP
This code was intended for use by end-to-end encryption devices used by
U.S.
military agencies.
Routers SHOULD use the newly defined Code 13 (Communication
Administratively Prohibited) if they administratively filter packets.
.PP
From RFC 1812, section 5.2.7.1.
See RFC 1812 and RFC 1122.
.RS
.PP
\f[B]Note\f[R]
.PP
This message may not be widely understood.
.RE
.RE
.TP
icmp-host-prohibited; host-prohib
ICMP communication with destination host administratively prohibited
.RS
.PP
This code was intended for use by end-to-end encryption devices used by
U.S.
military agencies.
Routers SHOULD use the newly defined Code 13 (Communication
Administratively Prohibited) if they administratively filter packets.
.PP
From RFC 1812, section 5.2.7.1.
See RFC 1812 and RFC 1122.
.RS
.PP
\f[B]Note\f[R]
.PP
This message may not be widely understood.
.RE
.RE
.TP
tcp-reset
TCP RST
.RS
.PP
The port unreachable message of the TCP stack.
.PP
See RFC 1122.
.RS
.PP
\f[B]Note\f[R]
.PP
\f[V]tcp-reset\f[R] is useful when you want to prevent timeouts on
rejected TCP services where the client incorrectly ignores ICMP port
unreachable messages.
.RE
.RE
.SH SEE ALSO
.IP \[bu] 2
firehol(1) - FireHOL program
.IP \[bu] 2
firehol.conf(5) - FireHOL configuration
.IP \[bu] 2
firehol-interface(5) - interface definition
.IP \[bu] 2
firehol-router(5) - router definition
.IP \[bu] 2
firehol-params(5) - optional rule parameters
.IP \[bu] 2
FireHOL Website (http://firehol.org/)
.IP \[bu] 2
FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)
.IP \[bu] 2
FireHOL Online Documentation (http://firehol.org/documentation/)
.SH AUTHORS
FireHOL Team.