.\" 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-params" "5" "Built 30 Mar 2024" "FireHOL Reference" "3.1.7"
.hy
.SH NAME
.PP
firehol-params - optional rule parameters
.SH SYNOPSIS
.PP
\f[I]Common\f[R]
.PP
{ src | src4 | src6 } [not] \f[I]host\f[R]
.PP
{ dst | dst4 | dst6 } [not] \f[I]host\f[R]
.PP
srctype [not] \f[I]type\f[R]
.PP
dsttype [not] \f[I]type\f[R]
.PP
proto [not] \f[I]protocol\f[R]
.PP
mac [not] \f[I]macaddr\f[R]
.PP
dscp [not] \f[I]value\f[R] \f[I]class\f[R] \f[I]classid\f[R]
.PP
mark [not] \f[I]id\f[R]
.PP
connmark [not] \f[I]id\f[R]
.PP
custommark [not] \f[I]name\f[R] \f[I]id\f[R]
.PP
rawmark [not] \f[I]id\f[R]
.PP
tos [not] \f[I]id\f[R]
.PP
custom \[lq]\f[I]iptables-options\f[R]\&...\[rq]
.PP
custom-in \[lq]\f[I]iptables-options\f[R]\&...\[rq]
.PP
custom-out \[lq]\f[I]iptables-options\f[R]\&...\[rq]
.PP
\f[I]Router Only\f[R]
.PP
inface [not] \f[I]interface\f[R]
.PP
outface [not] \f[I]interface\f[R]
.PP
physin [not] \f[I]interface\f[R]
.PP
physout [not] \f[I]interface\f[R]
.PP
\f[I]Interface Only\f[R]
.PP
uid [not] \f[I]user\f[R]
.PP
gid [not] \f[I]group\f[R]
.PP
\f[I]Logging\f[R]
.PP
connlog \[lq]log text\[rq]
.PP
log \[lq]log text\[rq] [level \f[I]loglevel\f[R]]
.PP
loglimit \[lq]log text\[rq] [level \f[I]loglevel\f[R]]
.PP
\f[I]Helpers Only\f[R]
.PP
sport \f[I]port\f[R]
.PP
dport \f[I]port\f[R]
.PP
state \f[I]state\f[R]
.PP
ipset [not] name flags [no-counters]
[bytes-lt|bytes-eq|bytes-gt|bytes-not-eq \f[I]number\f[R]]
[packets-lt|packets-eq|packets-gt|packets-not-eq \f[I]number\f[R]]
[options \f[I]custom-ipset-options\f[R]]
.PP
limit \f[I]limit\f[R] \f[I]burst\f[R]
.PP
connlimit upto|above \f[I]limit\f[R] [mask \f[I]mask\f[R]] [saddr|daddr]
.PP
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]]
.SH DESCRIPTION
.PP
Optional rule parameters are accepted by many commands to narrow the
match they make.
Not all parameters are accepted by all commands so you should check the
individual commands for exclusions.
.PP
All matches are made against the REQUEST.
FireHOL automatically sets up the necessary stateful rules to deal with
replies in the reverse direction.
.PP
All matches should be true for a statement to be executed.
However, many matches support multiple values.
In this case, at least one of the values must match.
.PP
Example:
.IP
.nf
\f[C]
server smtp accept src 1.1.1.1 dst 2.2.2.2
\f[R]
.fi
.PP
In the above example all smtp requests coming in from 1.1.1.1 and going
out to smtp server 2.2.2.2 will be matched.
.IP
.nf
\f[C]
server smtp accept src 1.1.1.1 dst 2.2.2.2,3.3.3.3
\f[R]
.fi
.PP
In the above example all smtp requests coming in from 1.1.1.1 and going
out to either smtp server 2.2.2.2 or 3.3.3.3 will be matched.
.PP
Use the keyword \f[V]not\f[R] to match any value other than the one(s)
specified.
.PP
The logging parameters are unusual in that they do not affect the match,
they just cause a log message to be emitted.
Therefore, the logging parameters don\[cq]t support the \f[V]not\f[R]
option.
.PP
FireHOL is designed so that if you specify a parameter that is also used
internally by the command then a warning will be issued (and the
internal version will be used).
.SH COMMON
.SS src, dst
.PP
Use \f[V]src\f[R] and \f[V]dst\f[R] to define the source and destination
IP addresses of the request respectively.
\f[I]host\f[R] defines the IP or IPs to be matched.
.PP
\f[I]host\f[R] can also refer to an ipset, using this syntax:
\f[V]ipset:NAME\f[R], where NAME is the name of the ipset.
The ipset has to be of type \f[V]hash:ip\f[R] for this match to work.
The source IP or the destination IP will be used for the match,
depending if the ipset is given as \f[V]src\f[R] or \f[V]dst\f[R].
.PP
IPs and ipsets can be mixed together, like this:
\f[V]src 1.1.1.1,ipset:NAME1,2.2.2.2,ipset:NAME2\f[R]
.PP
Examples:
.IP
.nf
\f[C]
server4 smtp accept src not 192.0.2.1
server4 smtp accept dst 198.51.100.1
server4 smtp accept src not 192.0.2.1 dst 198.51.100.1
server6 smtp accept src not 2001:DB8:1::/64
server6 smtp accept dst 2001:DB8:2::/64
server6 smtp accept src not 2001:DB8:1::/64 dst 2001:DB8:2::/64
\f[R]
.fi
.PP
When attempting to create rules for both IPv4 and IPv6 it is generally
easier to use the \f[V]src4\f[R], \f[V]src6\f[R], \f[V]dst4\f[R] and
\f[V]dst6\f[R] pairs:
.IP
.nf
\f[C]
server46 smtp accept src4 192.0.2.1 src6 2001:DB8:1::/64
server46 smtp accept dst4 198.51.100.1 dst6 2001:DB8:2::/64
server46 smtp accept dst4 $d4 dst6 $d6 src4 not $d4 src6 not $s6
\f[R]
.fi
.PP
To keep the rules sane, if one of the 4/6 pair specifies \f[V]not\f[R],
then so must the other.
If you do not want to use both IPv4 and IPv6 addresses, you must specify
the rule as IPv4 or IPv6 only.
It is always possible to write a second IPv4 or IPv6 only rule.
.SS srctype, dsttype
.PP
Use \f[V]srctype\f[R] or \f[V]dsttype\f[R] to define the source or
destination IP address type of the request.
\f[I]type\f[R] is the address type category as used in the kernel\[cq]s
network stack.
It can be one of:
.TP
UNSPEC
an unspecified address (i.e.\ 0.0.0.0)
.TP
UNICAST
a unicast address
.TP
LOCAL
a local address
.TP
BROADCAST
a broadcast address
.TP
ANYCAST
an anycast address
.TP
MULTICAST
a multicast address
.TP
BLACKHOLE
a blackhole address
.TP
UNREACHABLE
an unreachable address
.TP
PROHIBIT
a prohibited address
.TP
THROW; NAT; XRESOLVE
undocumented
.PP
See iptables(8) or run \f[V]iptables -m addrtype --help\f[R] for more
information.
Examples:
.IP
.nf
\f[C]
server smtp accept srctype not \[dq]UNREACHABLE PROHIBIT\[dq]
    
\f[R]
.fi
.SS proto
.PP
Use \f[V]proto\f[R] to match by protocol.
The \f[I]protocol\f[R] can be any accepted by iptables(8).
.SS mac
.PP
Use \f[V]mac\f[R] to match by MAC address.
The \f[I]macaddr\f[R] matches to the \[lq]remote\[rq] host.
In an \f[V]interface\f[R], \[lq]remote\[rq] always means the non-local
host.
In a \f[V]router\f[R], \[lq]remote\[rq] refers to the source of requests
for \f[V]server\f[R]s.
It refers to the destination of requests for \f[V]client\f[R]s.
Examples:
.IP
.nf
\f[C]
 # Only allow pop3 requests to the e6 host
 client pop3 accept mac 00:01:01:00:00:e6

 # Only allow hosts other than e7/e8 to access smtp
 server smtp accept mac not \[dq]00:01:01:00:00:e7 00:01:01:00:00:e8\[dq]
\f[R]
.fi
.SS dscp
.PP
Use \f[V]dscp\f[R] to match the DSCP field on packets.
For details on DSCP values and classids, see firehol-dscp(5).
.IP
.nf
\f[C]
 server smtp accept dscp not \[dq]0x20 0x30\[dq]
 server smtp accept dscp not class \[dq]BE EF\[dq]
\f[R]
.fi
.SS mark
.PP
Use \f[V]mark\f[R] to match marks set on packets.
For details on mark ids, see firehol-mark(5).
.IP
.nf
\f[C]
server smtp accept mark not \[dq]20 55\[dq]
    
\f[R]
.fi
.SS tos
.PP
Use \f[V]tos\f[R] to match the TOS field on packets.
For details on TOS ids, see firehol-tos(5).
.IP
.nf
\f[C]
server smtp accept tos not \[dq]Maximize-Throughput 0x10\[dq]
    
\f[R]
.fi
.SS custom
.PP
Use \f[V]custom\f[R] to pass arguments directly to iptables(8).
All of the parameters must be in a single quoted string.
To pass an option to iptables(8) that itself contains a space you need
to quote strings in the usual bash(1) manner.
For example:
.IP
.nf
\f[C]
server smtp accept custom \[dq]--some-option some-value\[dq]
server smtp accept custom \[dq]--some-option \[aq]some-value second-value\[aq]\[dq]
\f[R]
.fi
.SH ROUTER ONLY
.SS inface, outface
.PP
Use \f[V]inface\f[R] and \f[V]outface\f[R] to define the
\f[I]interface\f[R] via which a request is received and forwarded
respectively.
Use the same format as firehol-interface(5).
Examples:
.IP
.nf
\f[C]
server smtp accept inface not eth0
server smtp accept inface not \[dq]eth0 eth1\[dq]
server smtp accept inface eth0 outface eth1
\f[R]
.fi
.SS physin, physout
.PP
Use \f[V]physin\f[R] and \f[V]physout\f[R] to define the physical
\f[I]interface\f[R] via which a request is received or send in cases
where the inface or outface is known to be a virtual interface; e.g.\ a
bridge.
Use the same format as firehol-interface(5).
Examples:
.IP
.nf
\f[C]
server smtp accept physin not eth0
    
\f[R]
.fi
.SH INTERFACE ONLY
.PP
These parameters match information related to information gathered from
the local host.
They apply only to outgoing packets and are silently ignored for
incoming requests and requests that will be forwarded.
.RS
.PP
\f[B]Note\f[R]
.PP
The Linux kernel infrastructure to match PID/SID and executable names
with \f[V]pid\f[R], \f[V]sid\f[R] and \f[V]cmd\f[R] has been removed so
these options can no longer be used.
.RE
.SS uid
.PP
Use \f[V]uid\f[R] to match the operating system user sending the
traffic.
The \f[I]user\f[R] is a username, uid number or a quoted list of the
two.
.PP
For example, to limit which users can access POP3 and IMAP by preventing
replies for certain users from being sent:
.IP
.nf
\f[C]
client \[dq]pop3 imap\[dq] accept user not \[dq]user1 user2 user3\[dq]
    
\f[R]
.fi
.PP
Similarly, this will allow all requests to reach the server but prevent
replies unless the web server is running as apache:
.IP
.nf
\f[C]
server http accept user apache
    
\f[R]
.fi
.SS gid
.PP
Use \f[V]gid\f[R] to match the operating system group sending the
traffic.
The \f[I]group\f[R] is a group name, gid number or a quoted list of the
two.
.SH LOGGING
.SS connlog
.PP
Use \f[V]connlog\f[R] to log only the first packet of a connection.
.SS log, loglimit
.PP
Use \f[V]log\f[R] or \f[V]loglimit\f[R] to log matching packets to
syslog.
Unlike iptables(8) logging, this is not an action: FireHOL will produce
multiple iptables(8) commands to accomplish both the action for the rule
and the logging.
.PP
Logging is controlled using the FIREHOL_LOG_OPTIONS and
FIREHOL_LOG_LEVEL environment variables - see firehol-defaults.conf(5).
\f[V]loglimit\f[R] additionally honours the FIREHOL_LOG_FREQUENCY and
FIREHOL_LOG_BURST variables.
.PP
Specifying \f[V]level\f[R] (which takes the same values as
FIREHOL_LOG_LEVEL) allows you to override the log level for a single
rule.
.SH HELPERS ONLY PARAMETERS
.SS dport, sport
.PP
FireHOL also provides \f[V]dport\f[R], \f[V]sport\f[R] and
\f[V]limit\f[R] which are used internally and rarely needed within
configuration files.
.PP
\f[V]dport\f[R] and \f[V]sport\f[R] require an argument \f[I]port\f[R]
which can be a name, number, range (FROM:TO) or a quoted list of ports.
.PP
For \f[V]dport\f[R] \f[I]port\f[R] specifies the destination port of a
request and can be useful when matching traffic to helper commands (such
as nat) where there is no implicit port.
.PP
For \f[V]sport\f[R] \f[I]port\f[R] specifies the source port of a
request and can be useful when matching traffic to helper commands (such
as nat) where there is no implicit port.
.SS limit
.PP
\f[V]limit\f[R] requires the arguments \f[I]frequency\f[R] and
\f[I]burst\f[R] and will limit the matching of traffic in both
directions.
.SS connlimit
.PP
\f[V]connlimit\f[R] matches on the number of connections per IP.
It has been added to FireHOL since v3.
.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 hashlimit
.PP
\f[V]hashlimit\f[R] has been added to FireHOL since v3.
.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.
It gives you the ability to express \[lq]N packets per time quantum per
group\[rq] or \[lq]N bytes per seconds\[rq] (see below for some
examples).
.PP
A hash limit type (\f[V]upto\f[R], \f[V]above\f[R]) and \f[I]name\f[R]
are required.
.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), or as amountb/second (number of bytes per
second).
.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.
When byte-based rate matching is requested, this option specifies the
amount of bytes that can exceed the given rate.
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
matching on source host: \[lq]1000 packets per second for every host in
192.168.0.0/16\[rq]
.IP
.nf
\f[C]
src 192.168.0.0/16 hashlimit mylimit mode srcip upto 1000/sec
\f[R]
.fi
.PP
matching on source port: \[lq]100 packets per second for every service
of 192.168.1.1\[rq]
.IP
.nf
\f[C]
src 192.168.1.1 hashlimit mylimit mode srcport upto 100/sec
\f[R]
.fi
.PP
matching on subnet: \[lq]10000 packets per minute for every /28 subnet
(groups of 8 addresses) in 10.0.0.0/8\[rq]
.IP
.nf
\f[C]
src 10.0.0.8 hashlimit mylimit mask 28 upto 10000/min
\f[R]
.fi
.PP
matching bytes per second: \[lq]flows exceeding 512kbyte/s\[rq]
.IP
.nf
\f[C]
hashlimit mylimit mode srcip,dstip,srcport,dstport above 512kb/s
\f[R]
.fi
.PP
matching bytes per second: \[lq]hosts that exceed 512kbyte/s, but permit
up to 1Megabytes without matching\[rq]
.IP
.nf
\f[C]
hashlimit mylimit mode dstip above 512kb/s burst 1mb
\f[R]
.fi
.SH SEE ALSO
.IP \[bu] 2
firehol(1) - FireHOL program
.IP \[bu] 2
firehol.conf(5) - FireHOL configuration
.IP \[bu] 2
firehol-server(5) - server, route commands
.IP \[bu] 2
firehol-client(5) - client command
.IP \[bu] 2
firehol-interface(5) - interface definition
.IP \[bu] 2
firehol-router(5) - router definition
.IP \[bu] 2
firehol-mark(5) - mark config helper
.IP \[bu] 2
firehol-tos(5) - tos config helper
.IP \[bu] 2
firehol-dscp(5) - dscp config helper
.IP \[bu] 2
firehol-defaults.conf(5) - control variables
.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.