.\" Automatically generated by Pandoc 2.2.1
.nh
.\"
.TH "firehol\-params" "5" "Built 12 Apr 2019" "FireHOL Reference" "3.1.6"
.hy
.SH NAME
.PP
firehol\-params \- optional rule parameters
.SH SYNOPSIS
.PP
\f[I]Common\f[]
.PP
{ src | src4 | src6 } [not] \f[I]host\f[]
.PP
{ dst | dst4 | dst6 } [not] \f[I]host\f[]
.PP
srctype [not] \f[I]type\f[]
.PP
dsttype [not] \f[I]type\f[]
.PP
proto [not] \f[I]protocol\f[]
.PP
mac [not] \f[I]macaddr\f[]
.PP
dscp [not] \f[I]value\f[] \f[I]class\f[] \f[I]classid\f[]
.PP
mark [not] \f[I]id\f[]
.PP
connmark [not] \f[I]id\f[]
.PP
custommark [not] \f[I]name\f[] \f[I]id\f[]
.PP
rawmark [not] \f[I]id\f[]
.PP
tos [not] \f[I]id\f[]
.PP
custom \[lq]\f[I]iptables\-options\f[]\&...\[rq]
.PP
custom\-in \[lq]\f[I]iptables\-options\f[]\&...\[rq]
.PP
custom\-out \[lq]\f[I]iptables\-options\f[]\&...\[rq]
.PP
\f[I]Router Only\f[]
.PP
inface [not] \f[I]interface\f[]
.PP
outface [not] \f[I]interface\f[]
.PP
physin [not] \f[I]interface\f[]
.PP
physout [not] \f[I]interface\f[]
.PP
\f[I]Interface Only\f[]
.PP
uid [not] \f[I]user\f[]
.PP
gid [not] \f[I]group\f[]
.PP
\f[I]Logging\f[]
.PP
connlog \[lq]log text\[rq]
.PP
log \[lq]log text\[rq] [level \f[I]loglevel\f[]]
.PP
loglimit \[lq]log text\[rq] [level \f[I]loglevel\f[]]
.PP
\f[I]Helpers Only\f[]
.PP
sport \f[I]port\f[]
.PP
dport \f[I]port\f[]
.PP
state \f[I]state\f[]
.PP
ipset [not] name flags [no\-counters]
[bytes\-lt|bytes\-eq|bytes\-gt|bytes\-not\-eq \f[I]number\f[]]
[packets\-lt|packets\-eq|packets\-gt|packets\-not\-eq \f[I]number\f[]]
[options \f[I]custom\-ipset\-options\f[]]
.PP
limit \f[I]limit\f[] \f[I]burst\f[]
.PP
connlimit upto|above \f[I]limit\f[] [mask \f[I]mask\f[]] [saddr|daddr]
.PP
hashlimit \f[I]name\f[] upto|above \f[I]amount/period\f[] [burst
\f[I]amount\f[]] [mode \f[I]{srcip|srcport|dstip|dstport},\&...\f[]]
[srcmask \f[I]prefix\f[]] [dstmask \f[I]prefix\f[]] [htable\-size
\f[I]buckets\f[]] [htable\-max \f[I]entries\f[]] [htable\-expire
\f[I]msec\f[]] [htable\-gcinterval \f[I]msec\f[]]
.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[]
.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[]
.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[C]not\f[] 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't support the \f[C]not\f[] 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[C]src\f[] and \f[C]dst\f[] to define the source and destination
IP addresses of the request respectively.
\f[I]host\f[] defines the IP or IPs to be matched.
.PP
\f[I]host\f[] can also refer to an ipset, using this syntax:
\f[C]ipset:NAME\f[], where NAME is the name of the ipset.
The ipset has to be of type \f[C]hash:ip\f[] 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[C]src\f[] or \f[C]dst\f[].
.PP
IPs and ipsets can be mixed together, like this:
\f[C]src\ 1.1.1.1,ipset:NAME1,2.2.2.2,ipset:NAME2\f[]
.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[]
.fi
.PP
When attempting to create rules for both IPv4 and IPv6 it is generally
easier to use the \f[C]src4\f[], \f[C]src6\f[], \f[C]dst4\f[] and
\f[C]dst6\f[] 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[]
.fi
.PP
To keep the rules sane, if one of the 4/6 pair specifies \f[C]not\f[],
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[C]srctype\f[] or \f[C]dsttype\f[] to define the source or
destination IP address type of the request.
\f[I]type\f[] is the address type category as used in the kernel's
network stack.
It can be one of:
.TP
.B UNSPEC
an unspecified address (i.e.\ 0.0.0.0)
.RS
.RE
.TP
.B UNICAST
a unicast address
.RS
.RE
.TP
.B LOCAL
a local address
.RS
.RE
.TP
.B BROADCAST
a broadcast address
.RS
.RE
.TP
.B ANYCAST
an anycast address
.RS
.RE
.TP
.B MULTICAST
a multicast address
.RS
.RE
.TP
.B BLACKHOLE
a blackhole address
.RS
.RE
.TP
.B UNREACHABLE
an unreachable address
.RS
.RE
.TP
.B PROHIBIT
a prohibited address
.RS
.RE
.TP
.B THROW; NAT; XRESOLVE
undocumented
.RS
.RE
.PP
See iptables(8) or run \f[C]iptables\ \-m\ addrtype\ \-\-help\f[] for
more information.
Examples:
.IP
.nf
\f[C]
server\ smtp\ accept\ srctype\ not\ "UNREACHABLE\ PROHIBIT"
\ \ \ \ 
\f[]
.fi
.SS proto
.PP
Use \f[C]proto\f[] to match by protocol.
The \f[I]protocol\f[] can be any accepted by iptables(8).
.SS mac
.PP
Use \f[C]mac\f[] to match by MAC address.
The \f[I]macaddr\f[] matches to the \[lq]remote\[rq] host.
In an \f[C]interface\f[], \[lq]remote\[rq] always means the non\-local
host.
In a \f[C]router\f[], \[lq]remote\[rq] refers to the source of requests
for \f[C]server\f[]s.
It refers to the destination of requests for \f[C]client\f[]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\ "00:01:01:00:00:e7\ 00:01:01:00:00:e8"
\f[]
.fi
.SS dscp
.PP
Use \f[C]dscp\f[] 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\ "0x20\ 0x30"
\ server\ smtp\ accept\ dscp\ not\ class\ "BE\ EF"
\f[]
.fi
.SS mark
.PP
Use \f[C]mark\f[] to match marks set on packets.
For details on mark ids, see firehol\-mark(5).
.IP
.nf
\f[C]
server\ smtp\ accept\ mark\ not\ "20\ 55"
\ \ \ \ 
\f[]
.fi
.SS tos
.PP
Use \f[C]tos\f[] 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\ "Maximize\-Throughput\ 0x10"
\ \ \ \ 
\f[]
.fi
.SS custom
.PP
Use \f[C]custom\f[] 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\ "\-\-some\-option\ some\-value"
server\ smtp\ accept\ custom\ "\-\-some\-option\ \[aq]some\-value\ second\-value\[aq]"
\f[]
.fi
.SH ROUTER ONLY
.SS inface, outface
.PP
Use \f[C]inface\f[] and \f[C]outface\f[] to define the
\f[I]interface\f[] 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\ "eth0\ eth1"
server\ smtp\ accept\ inface\ eth0\ outface\ eth1
\f[]
.fi
.SS physin, physout
.PP
Use \f[C]physin\f[] and \f[C]physout\f[] to define the physical
\f[I]interface\f[] 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[]
.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[]
.PP
The Linux kernel infrastructure to match PID/SID and executable names
with \f[C]pid\f[], \f[C]sid\f[] and \f[C]cmd\f[] has been removed so
these options can no longer be used.
.RE
.SS uid
.PP
Use \f[C]uid\f[] to match the operating system user sending the traffic.
The \f[I]user\f[] 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\ "pop3\ imap"\ accept\ user\ not\ "user1\ user2\ user3"
\ \ \ \ 
\f[]
.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[]
.fi
.SS gid
.PP
Use \f[C]gid\f[] to match the operating system group sending the
traffic.
The \f[I]group\f[] is a group name, gid number or a quoted list of the
two.
.SH LOGGING
.SS connlog
.PP
Use \f[C]connlog\f[] to log only the first packet of a connection.
.SS log, loglimit
.PP
Use \f[C]log\f[] or \f[C]loglimit\f[] 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[C]loglimit\f[] additionally honours the FIREHOL_LOG_FREQUENCY and
FIREHOL_LOG_BURST variables.
.PP
Specifying \f[C]level\f[] (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[C]dport\f[], \f[C]sport\f[] and \f[C]limit\f[]
which are used internally and rarely needed within configuration files.
.PP
\f[C]dport\f[] and \f[C]sport\f[] require an argument \f[I]port\f[]
which can be a name, number, range (FROM:TO) or a quoted list of ports.
.PP
For \f[C]dport\f[] \f[I]port\f[] 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[C]sport\f[] \f[I]port\f[] 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[C]limit\f[] requires the arguments \f[I]frequency\f[] and
\f[I]burst\f[] and will limit the matching of traffic in both
directions.
.SS connlimit
.PP
\f[C]connlimit\f[] matches on the number of connections per IP.
It has been added to FireHOL since v3.
.PP
\f[I]saddr\f[] matches on source IP.
\f[I]daddr\f[] matches on destination IP.
\f[I]mask\f[] groups IPs with the \f[I]mask\f[] given \f[I]upto\f[]
matches when the number of connections is up to the given \f[I]limit\f[]
\f[I]above\f[] matches when the number of connections above to the given
\f[I]limit\f[]
.PP
The number of connections counted are system wide, not service specific.
For example for \f[I]saddr\f[], 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[C]connlimit\f[] can safely be used:
.IP \[bu] 2
with \f[I]daddr\f[] to limit the connections a server can accept
.IP \[bu] 2
with \f[I]saddr\f[] to limit the total connections per client to all
services.
.SS hashlimit
.PP
\f[C]hashlimit\f[] has been added to FireHOL since v3.
.PP
\f[C]hashlimit\f[] 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[C]upto\f[], \f[C]above\f[]) and \f[I]name\f[] are
required.
.PP
\f[I]name\f[] The name for the /proc/net/ipt_hashlimit/\f[I]name\f[]
entry.
.PP
\f[C]upto\f[] \f[I]amount[/second|/minute|/hour|/day]\f[] 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[C]above\f[] \f[I]amount[/second|/minute|/hour|/day]\f[] Match if the
rate is above amount/quantum.
.PP
\f[C]burst\f[] \f[I]amount\f[] 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[C]mode\f[] \f[I]{srcip|srcport|dstip|dstport},\&...\f[] A
comma\-separated list of objects to take into consideration.
If no \f[C]mode\f[] option is given, \f[I]srcip,dstport\f[] is assumed.
.PP
\f[C]srcmask\f[] \f[I]prefix\f[] 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[C]srcmask\f[] \f[I]0\f[] is basically doing the same thing
as not specifying srcip for \f[C]mode\f[], but is technically more
expensive.
.PP
\f[C]dstmask\f[] \f[I]prefix\f[] Like \f[C]srcmask\f[], but for
destination addresses.
.PP
\f[C]htable\-size\f[] \f[I]buckets\f[] The number of buckets of the hash
table
.PP
\f[C]htable\-max\f[] \f[I]entries\f[] Maximum entries in the hash.
.PP
\f[C]htable\-expire\f[] \f[I]msec\f[] After how many milliseconds do
hash entries expire.
.PP
\f[C]htable\-gcinterval\f[] \f[I]msec\f[] 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[]
.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[]
.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[]
.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[]
.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[]
.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.