.\" Automatically generated by Pandoc 2.2.1
.nh
.\"
.TH "firehol\-action" "5" "Built 12 Apr 2019" "FireHOL Reference" "3.1.6"
.hy
.SH NAME
.PP
firehol\-action \- set up custom filtering actions
.SH SYNOPSIS
.PP
action \f[I]name\f[] [table \f[I]table_name\f[]] \f[I]type\f[]
\f[I]type_params\f[] [ next [ \f[I]type\f[] \f[I]type_params\f[] [ next
\&... ] ] ]
.SH DESCRIPTION
.PP
The \f[C]action\f[] helper creates custom actions that can be used
everywhere in FireHOL, like this:
.IP
.nf
\f[C]
action\ ACT1\ chain\ accept

interface\ any\ world
\ \ \ \ server\ smtp\ ACT1

router\ myrouter
\ \ \ \ policy\ ACT1
\f[]
.fi
.PP
The \f[C]action\f[] helper allows linking multiple actions together and
having some logic to select which action to execute, like this:
.IP
.nf
\f[C]
action\ ACT1\ \\
\ \ \ \ \ \ \ \ \ rule\ src\ 192.168.0.0/16\ action\ reject\ \\
\ \ \ \ next\ rule\ dst\ 192.168.0.0/16\ action\ reject\ \\
\ \ \ \ next\ rule\ inface\ eth2\ action\ drop\ \\
\ \ \ \ next\ rule\ outface\ eth2\ action\ drop\ \\
\ \ \ \ next\ action\ accept

interface\ any\ world
\ \ \ \ server\ smtp\ ACT1

router\ myrouter
\ \ \ \ policy\ ACT1
\f[]
.fi
.PP
There is no limit on the number of actions that can be linked together.
.PP
\f[C]type\f[] can be \f[C]chain\f[] or \f[C]action\f[] (\f[C]chain\f[]
and \f[C]action\f[] are aliases), \f[C]rule\f[], \f[C]iptrap\f[],
\f[C]ipuntrap\f[] or \f[C]sockets_suspects_trap\f[].
.SS Chain type actions
.PP
This is the simpler action.
It creates an iptables(8) chain which can be used to control the action
of other firewall rules once the firewall is running.
.PP
For example, you can setup the custom action ACT1, which by default is
ACCEPT, but can be dynamically changed to DROP, REJECT or RETURN (and
back) without restarting the firewall.
.PP
The \f[I]name\f[] can be any chain name accepted by iptables.
You should try to keep it within 5 and 10 characters.
.RS
.PP
\f[B]Note\f[]
.PP
The \f[I]name\f[]s created with this command are case\-sensitive.
.RE
.PP
The \f[I]action\f[] can be any of those supported by FireHOL (see
firehol\-actions(5)).
Only ACCEPT, REJECT, DROP, RETURN have any meaning in this instance.
.PP
Once the firewall is running you can dynamically modify the behaviour of
the chain from the Linux command\-line, as detailed below:
.IP
.nf
\f[C]
action\ ACT1\ chain\ accept

interface\ any\ world
\ \ \ \ server\ smtp\ ACT1
\ \ \ \ client\ smtp\ ACT1
\f[]
.fi
.PP
To insert a DROP action at the start of the chain to override the
default action (ACCEPT):
.IP
.nf
\f[C]
iptables\ \-t\ filter\ \-I\ ACT1\ \-j\ DROP
\f[]
.fi
.PP
To delete the DROP action from the start of the chain to return to the
default action:
.IP
.nf
\f[C]
iptables\ \-t\ filter\ \-D\ ACT1\ \-j\ DROP
\f[]
.fi
.RS
.PP
\f[B]Note\f[]
.PP
If you delete all of the rules in the chain, the default will be to
RETURN, in which case the behaviour will be as if any rules with the
action were not present in the configuration file.
.RE
.SS Rule type actions
.PP
\f[C]rule\f[] type actions define a few conditions that will lead to an
action.
.PP
All optional rule parameters FireHOL supports can be used here (see
firehol\-params(5)).
.IP
.nf
\f[C]
action\ ACT1\ \\
\ \ \ \ rule\ inface\ eth0\ action\ accept
\ \ \ \ next\ rule\ outface\ eth0\ action\ accept
\ \ \ \ next\ action\ reject

interface\ any\ world
\ \ \ \ server\ smtp\ ACT1
\f[]
.fi
.PP
In the above example the smtp server can only be accessed from eth0.
.PP
It is important to remember that actions will be applied for all the
traffic, both requests and replies.
The type of traffic can be filtered with the \f[C]state\f[] optional
rule parameter, like this:
.IP
.nf
\f[C]
action\ ACT1\ \\
\ \ \ \ rule\ inface\ eth0\ state\ NEW\ action\ reject
\ \ \ \ next\ action\ accept

interface\ any\ world
\ \ \ \ server\ smtp\ ACT1
\ \ \ \ client\ smtp\ ACT1
\f[]
.fi
.PP
In the above example, the smtp server will not accept NEW connections
from eth0, but the smtp client will be able to connect to servers on
eth0 (and everywhere else).
.SS iptrap type actions
.PP
\f[C]iptrap\f[] (see [firehol\-iptrap(5)][]) is a helper than copies
(traps) an IP to an ipset (see [firehol\-ipset(5)][]).
It does not perform any action on the traffic.
.PP
Using the \f[C]iptrap\f[] action, the \f[C]iptrap\f[] helper can be
linked to filtering actions, like this:
.IP
.nf
\f[C]
\ #\ a\ simple\ version\ of\ TRAP_AND_REJECT
\ #\ this\ uses\ just\ 2\ ipsets,\ one\ for\ counting\ packets\ (policytrap)
\ #\ and\ one\ to\ store\ the\ banned\ IPs\ (trap).
\ #\ it\ also\ needs\ a\ ipset\ called\ whitelist,\ for\ excluded\ source\ IPs.
\ #\ it\ will\ ban\ IPs\ when\ they\ have\ 50+\ reject\ packets
\ action4\ TRAP_AND_REJECT\ \\
\ \ \ \ rule\ iptrap\ src\ policytrap\ 30\ inface\ "${wan}"\ \\
\ \ \ \ \ \ \ \ src\ not\ "${UNROUTABLE_IPS}\ ipset:whitelist"\ \\
\ \ \ \ \ \ \ \ state\ NEW\ log\ "POLICY\ TRAP"\ \\
\ \ \ \ next\ iptrap\ trap\ src\ 86400\ \\
\ \ \ \ \ \ \ \ state\ NEW\ log\ "POLICY\ TRAP\ \-\ BANNED"\ \\
\ \ \ \ \ \ \ \ ipset\ policytrap\ src\ no\-counters\ packets\-above\ 50\ \\
\ \ \ \ next\ action\ reject

\ #\ a\ complete\ TRAP_AND_REJECT
\ #\ this\ uses\ 3\ ipset,\ one\ for\ keeping\ track\ of\ the\ rejected\ sockets
\ #\ per\ source\ IP\ (called\ \[aq]sockets\[aq]),\ one\ for\ counting\ the\ sockets
\ #\ per\ source\ IP\ (called\ \[aq]suspects\[aq])\ and\ one\ to\ store\ the\ banned\ IPs
\ #\ (called\ \[aq]trap\[aq]).
\ #\ it\ also\ needs\ a\ ipset\ called\ whitelist,\ for\ excluded\ source\ IPs.
\ #\ it\ will\ ban\ IPs\ when\ they\ have\ 3\ or\ more\ rejected\ sockets
\ action4\ TRAP_AND_REJECT\ \\
\ \ \ \ iptrap\ sockets\ src,dst,dst\ 3600\ method\ hash:ip,port,ip\ counters\ \\
\ \ \ \ \ \ \ \ state\ NEW\ log\ "TRAP\ AND\ REJECT\ \-\ NEW\ SOCKET"\ \\
\ \ \ \ \ \ \ \ inface\ "${wan}"\ \\
\ \ \ \ \ \ \ \ src\ not\ "${UNROUTABLE_IPS}\ ipset:whitelist"\ \\
\ \ \ \ next\ iptrap\ suspects\ src\ 3600\ counters\ \\
\ \ \ \ \ \ \ \ state\ NEW\ log\ "TRAP\ AND\ REJECT\ \-\ NEW\ SUSPECT"\ \\
\ \ \ \ \ \ \ \ ipset\ sockets\ src,dst,dst\ no\-counters\ packets\ 1\ \\
\ \ \ \ next\ iptrap\ trap\ src\ 86400\ \\
\ \ \ \ \ \ \ \ state\ NEW\ log\ "TRAP\ AND\ REJECT\ \-\ BANNED"\ \\
\ \ \ \ \ \ \ \ ipset\ suspects\ src\ no\-counters\ packets\-above\ 2\ \\
\ \ \ \ next\ action\ REJECT

\ interface\ any\ world
\ \ \ \ policy\ TRAP_AND_REJECT
\ \ \ \ protection\ bad\-packets
\ \ \ \ ...

\ router\ wan2lan\ inface\ "${wan}"\ outface\ "${lan}"
\ \ \ \ policy\ TRAP_AND_REJECT
\ \ \ \ protection\ bad\-packets
\ \ \ \ ...
\f[]
.fi
.PP
Since we used the action TRAP_AND_REJECT as an interface policy, it will
get all the traffic not accepted, rejected, or dropped by the server and
client statements.
.PP
For all these packets, the action TRAP_AND_REJECT will first check that
they are coming in from wan0, that their src IP is not in
\f[C]UNROUTABLE_IPS\f[] list and in the \f[C]whitelist\f[] ipset, that
they are NEW connections, and if all these conditions are met, it will
log with the tag \f[C]POLICY\ TRAP\f[] and add the src IP of the packets
in the \f[C]policytrap\f[] ipset for 30 seconds.
.PP
All traffic not matched by the above, will be just rejected.
.SS sockets_suspects_trap type actions
.PP
The type \f[C]sockets_suspects_trap\f[] will automatically a custom trap
using the following template:
.IP
.nf
\f[C]
action4\ *name*\ sockets_suspects_trap\ *SUSPECTS_TIMEOUT*\ *TRAP_TIMEOUT*\ *VALID_CONNECTIONS*\ [*optional\ params*]\ next\ ...
\f[]
.fi
.PP
This will:
.IP "1." 3
Create the ipset \f[C]${name}_sockets\f[] where the matched sockets will
be stored for \f[C]SUSPECTS_TIMEOUT\f[] seconds.
.IP "2." 3
Create the ipset \f[C]${name}_suspects\f[] where the source IPs of the
matched sockets will be stored for \f[C]SUSPECTS_TIMEOUT\f[] seconds.
.IP "3." 3
Create the ipset \f[C]${name}_trap\f[] where the trapped IPs will be
stored for \f[C]TRAP_TIMEOUT\f[] seconds.
IPs will be added to this ipset only if more than
\f[C]VALID_CONNECTIONS\f[] have been matched by this IP.
.PP
\f[C]optional\ params\f[] are FireHOL optional rule parameters
(firehol\-params(5)) that can be used to limit the match for the first
ipset (sockets).
.PP
So, to design the same TRAP_AND_REJECT as above, this statement is
needed:
.IP
.nf
\f[C]
action4\ TRAP_AND_REJECT\ \\
\ \ \ \ sockets_suspects_trap\ 3600\ 86400\ 2\ \\
\ \ \ \ \ \ \ \ inface\ "${wan}"\ \\
\ \ \ \ \ \ \ \ src\ not\ "${UNROUTABLE_IPS}\ ipset:whitelist"\ \\
\ \ \ \ next\ action\ REJECT
\f[]
.fi
.PP
The ipsets that will be created will be named:
\f[C]TRAP_AND_REJECT_sockets\f[], \f[C]TRAP_AND_REJECT_suspects\f[] and
\f[C]TRAP_AND_REJECT_trap\f[].
.RS
.PP
\f[B]Note\f[] Always terminate \f[C]sockets_suspects_trap\f[] with a
\f[C]next\ action\ DROP\f[] or \f[C]next\ action\ REJECT\f[], or the
traffic will continue to flow.
.RE
.SH SEE ALSO
.IP \[bu] 2
firehol(1) \- FireHOL program
.IP \[bu] 2
firehol.conf(5) \- FireHOL configuration
.IP \[bu] 2
firehol\-actions(5) \- optional rule parameters
.IP \[bu] 2
iptables(8) (http://ipset.netfilter.org/iptables.man.html) \-
administration tool for IPv4 firewalls
.IP \[bu] 2
ip6tables(8) (http://ipset.netfilter.org/ip6tables.man.html) \-
administration tool for IPv6 firewalls
.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.