.\" Automatically generated by Pandoc 2.2.1
.nh
.\"
.TH "fireqos\-params\-match" "5" "Built 12 Apr 2019" "FireQOS Reference" "3.1.6"
.hy
.SH NAME
.PP
fireqos\-params\-match \- optional match parameters
.SH SYNOPSIS
.PP
at { root | \f[I]name\f[] }
.PP
class \f[I]name\f[]
.PP
syn|syns
.PP
ack|acks
.PP
{ proto|protocol \f[I]protocol\f[] [,\f[I]protocol\f[]\&...] }
|tcp|udp|icmp|gre|ipv6
.PP
{ tos | priority } \f[I]tosid\f[] [,\f[I]tosid\f[]\&...]
.PP
{ DSCP } \f[I]classname\f[] [,\f[I]classname\f[]\&...]
.PP
mark \f[I]mark\f[] [,\f[I]mark\f[]\&...]
.PP
connmark \f[I]mark\f[] [,\f[I]mark\f[]\&...]
.PP
rawmark \f[I]mark\f[] [,\f[I]mark\f[]\&...]
.PP
custommark \f[I]name\f[] \f[I]mark\f[] [,\f[I]mark\f[]\&...]
.PP
{ port | ports } \f[I]port\f[][:\f[I]range\f[]] [
,\f[I]port\f[][:\f[I]range\f[]]\&... ]
.PP
{ sport | sports } \f[I]port\f[][:\f[I]range\f[]] [
,\f[I]port\f[][:\f[I]range\f[]]\&... ]
.PP
{ dport | dports } \f[I]port\f[][:\f[I]range\f[]] [
,\f[I]port\f[][:\f[I]range\f[]]\&... ]
.PP
{ ip | net | host } \f[I]net\f[] [,\f[I]net\f[]\&...]
.PP
src \f[I]net\f[] [,\f[I]net\f[]\&...]
.PP
dst \f[I]net\f[] [,\f[I]net\f[]\&...]
.PP
{ srcmac | smac } \f[I]mac\f[]
.PP
{ dstmac | dmac } \f[I]mac\f[]
.PP
prio \f[I]id\f[]
.PP
input
.PP
output
.PP
custom `\f[I]custom tc parameters\f[]'
.PP
estimator \f[I]interval\f[] \f[I]decay\f[]
.PP
police \f[I]police\f[]
.PP
insidegre
.SH DESCRIPTION
.PP
These options apply to \f[C]match\f[] statements.
.SS input, output
.PP
On \f[C]bidirectional\f[] interfaces, \f[C]input\f[] and \f[C]output\f[]
will check the current direction of the interface.
If the match is \f[C]input\f[] but the interface is \f[C]output\f[] the
match will be reversed.
The same will happen if \f[C]output\f[] is given at the match and the
interface is \f[C]input\f[].
.PP
The parameters that are reversed are:
.IP \[bu] 2
\f[C]src\f[] and \f[C]dst\f[]
.IP \[bu] 2
\f[C]sport\f[] and \f[C]dport\f[]
.IP \[bu] 2
\f[C]srcmac\f[] and \f[C]dstmac\f[]
.PP
This allows a definition like this:
.IP
.nf
\f[C]
\ \ interface\ dsl0\ world\ bidirectional\ ...
\ \ \ \ class\ surfing\ ...
\ \ \ \ \ \ match\ input\ sport\ 0:1023
\f[]
.fi
.PP
The above will match \f[C]sport\ 0:1023\f[] at the \f[C]input\f[]
interface, and will automatically reverse it to match
\f[C]dport\ 0:1023\f[] at the \f[C]output\f[] interface.
.SS at
.PP
By default a \f[C]match\f[] is attached to the parent of its parent
class.
For example, if its parent is a class directly under the interface, then
the \f[C]match\f[] is attached to the interface and is compared against
all traffic of the interface.
For nested classes, a \f[C]match\f[] of a leaf, is attached to the
parent class and is compared against all traffic of this parent class.
.PP
With the \f[C]at\f[] parameter, a \f[C]match\f[] can be attached any
class.
The \f[I]name\f[] parameter should be a class name.
The name \f[C]root\f[] attaches the \f[C]match\f[] to the interface.
.SS class
.PP
Defines the \f[I]name\f[] of the class that will get the packets matched
by this \f[C]match\f[].
.PP
By default it is the name of the class the \f[C]match\f[] statement
appears under.
.RS
.PP
\f[I]Note\f[]
.PP
There is also a \f[C]class\f[] definition for traffic, see
fireqos\-class(5).
.RE
.SS syn, syns
.PP
Match TCP SYN packets.
Note that the \f[C]tcp\f[] parameter must be specified.
.PP
If the same match statement includes more protocols than TCP, then this
match will work for the TCP packets (it will be silently ignored for all
other protocols).
.PP
For example, syn is ignored when generating the UDP filter in the below:
.IP
.nf
\f[C]
match\ tcp\ syn
match\ proto\ tcp,udp\ syn
\f[]
.fi
.SS ack, acks
.PP
Same as \f[C]syn\f[], but matching small TCP packets with the ACK bit
set.
.SS proto, protocol, tcp, udp, icmp, gre, ipv6
.PP
Match the \f[I]protocol\f[] in the IP header.
.SS tos, priority
.PP
Match to TOS field of ipv4 or the priority field of ipv6.
The \f[I]tosid\f[] can be a value/mask in any format tc(8) accepts, or
one of the following:
.IP \[bu] 2
min\-delay, minimize\-delay, minimum\-delay, low\-delay, interactive
.IP \[bu] 2
maximize\-throughput, maximum\-throughput, max\-throughput,
high\-throughput, bulk
.IP \[bu] 2
maximize\-reliability, maximum\-reliability, max\-reliability, reliable
.IP \[bu] 2
min\-cost, minimize\-cost, minimum\-cost, low\-cost, cheap,
normal\-service, normal
.RS
.PP
\f[I]Note\f[]
.PP
There is also a class parameter called \f[C]priority\f[], see
fireqos\-params\-class(5).
.RE
.SS dscp
.PP
Match to DSCP value in IP TOS header field.
The \f[I]classname\f[] has to be one of the following values:
.IP \[bu] 2
CS1, CS2, CS3, CS4, CS5, CS6, CS7
.IP \[bu] 2
AF11, AF12, AF13
.IP \[bu] 2
AF21, AF22, AF23
.IP \[bu] 2
AF31, AF32, AF33
.IP \[bu] 2
AF41, AF42, AF43
.IP \[bu] 2
EF
.RS
.PP
\f[I]Note\f[]
.PP
tc\-filter only supports ToS parameters.
That is why a lookaside table is configured within fireqos code to
translate the DSCP value to their matching TOS value.
See RFC2474 for more information.
.RE
.SS mark, connmark, custommark, rawmark
.PP
Match an iptables(8) MARK.
This works the same way it works for FireHOL.
FireHOL and FireQOS share the same marks and their masks.
.PP
Matching iptables(8) MARKs do not work on input interfaces.
You can use them only on output.
The IFB devices that are used for shaping inbound traffic do not have
any iptables hooks to allow matching MARKs.
If you try it, FireQOS will attempt to do it, but currently you will get
an error from the tc(8) command executed or they will be silently
ignored by it.
.PP
On some Linux distributions (e.g.\ OpenWRT) there is a module called
\f[C]act_commark\f[] that will enable this feature.
Set this within your \f[C]fireqos.conf\f[] to enable it:
.IP
.nf
\f[C]
FIREQOS_CONNMARK_RESTORE="act_connmark"
\f[]
.fi
.PP
Also note that matching marks requires a suitably configured kernel
(with \f[C]CONFIG_CLS_U32_MARK=y\f[]).
There is no error if the kernel is not configured correctly; it just
silently drops the rules.
For details see this error
report (https://github.com/firehol/firehol/issues/231).
.SS ports, sports, dports
.PP
Match ports of the IP header.
\f[C]ports\f[] will create rules for matching source and destination
ports (separate rules for each).
\f[C]dports\f[] matches destination ports, \f[C]sports\f[] matches
source ports.
.SS ip, net, host, src, dst
.PP
Match IPs of the IP header.
\f[C]ip\f[], \f[C]net\f[] and \f[C]host\f[] will create rules for
matching source and destination IPs (separate rules for each).
\f[C]src\f[] matches source IPs and \f[C]dst\f[] destination IPs.
.RS
.PP
\f[B]Note\f[]
.PP
If the class these matches appear in are IPv4, then only IPv4 IPs can be
used.
To override use \f[C]match6\ ...\ src/dst\ *IPV6_IP*\f[]
.PP
Similarly, if the class is IPv6, then only IPv6 IPs can be used.
To override use \f[C]match4\ ...\ src/dst\ *IPV4_IP*\f[].
.RE
.PP
You can mix IPv4 and IPv6 in any way you like.
FireQOS supports inheritance, to figure out for each statement which is
the default.
For example:
.IP
.nf
\f[C]
interface46\ eth0\ lan\ output\ rate\ 1Gbit\ #\ ipv4\ and\ ipv6\ enabled
\ \ class\ voip\ #\ ipv4\ and\ ipv6\ class,\ as\ interface\ is\ both
\ \ \ \ match\ udp\ port\ 53\ #\ ipv4\ and\ ipv6\ rule,\ as\ class\ is\ both
\ \ \ \ match4\ src\ 192.0.2.1\ #\ ipv4\ only\ rule
\ \ \ \ match6\ src\ 2001:db8::1\ #\ ipv6\ only\ rule

\ \ class4\ realtime\ #\ ipv4\ only\ class
\ \ \ \ match\ src\ 198.51.100.1\ #\ ipv4\ only\ rule,\ as\ class\ is\ ipv4\-only

\ \ class6\ servers\ #\ ipv6\ only\ class
\ \ \ \ \ \ \ \ match\ src\ 2001:db8::2\ #\ ipv6\ only\ rule,\ as\ class\ is\ ipv6\-only
\f[]
.fi
.PP
To convert an IPv4 interface to IPv6, just replace \f[C]interface\f[]
with \f[C]interface6\f[].
All the rules in that interface, will automatically inherit the new
protocol.
Of course, if you use IP addresses for matching packets, make sure they
are IPv6 IPs too.
.SS prio (match)
.RS
.PP
\f[I]Note\f[]
.PP
There is also a class parameter called \f[C]prio\f[], see
fireqos\-params\-class(5).
.RE
.PP
All match statements are attached to the interface.
They forward traffic to their class, but they are actually executed for
all packets that are leaving the interface (note: input matches are
actually output matches on an IFB device).
.PP
By default, the priority they are executed, is the priority they appear
in the configuration file, i.e.\ the first match of the first class is
executed first, then the rest matches of the first class in the sequence
they appear, then the matches of the second class, etc.
.PP
It is sometimes necessary to control the order of matches.
For example, when you want host 192.0.2.1 to be assigned the first
class, except port tcp/1234 which should be assigned the second class.
The following will \f[I]not\f[] work:
.IP
.nf
\f[C]
interface\ eth0\ lan\ output\ rate\ 1Gbit
\ \ class\ high
\ \ \ \ match\ host\ 192.0.2.1

\ \ class\ low
\ \ \ \ match\ host\ 192.0.2.1\ port\ 1234\ #\ Will\ never\ match
\f[]
.fi
.PP
In this case, the first match is assigned priority 10 and the second
priority 20.
The second match will never match anything, since all traffic for the
host is already matched by the first one.
.PP
Setting an explicit priority allows you to change the order in which the
matches are executed.
FireQOS gives priority 10 to the first match of every interface, 20 to
the second match, 30 to the third match, etc.
So the default is 10 x the sequence number.
You can set \f[C]prio\f[] to overwrite this number.
.PP
To force executing the second match before the first, just set a lower
priority for it.
For example, this will cause the desired behaviour:
.IP
.nf
\f[C]
interface\ eth0\ lan\ output\ rate\ 1Gbit
\ \ class\ high
\ \ \ \ match\ host\ 192.0.2.1

\ \ class\ low
\ \ \ \ match\ host\ 192.0.2.1\ port\ 1234\ prio\ 1\ #\ Matches\ before\ host\-only
\f[]
.fi
.SS insidegre
.PP
By specifying keyword \f[C]insidegre\f[] a GRE (Generic Routing
Encapsulation) packet can be matched on the encapsulated IP packet
header information.
.PP
\f[C]insidegre\f[] is available for the following matches:
.IP \[bu] 2
src
.IP \[bu] 2
dst
.IP \[bu] 2
protocol
.IP \[bu] 2
port
.IP \[bu] 2
tos
.IP \[bu] 2
dscp
.IP
.nf
\f[C]
\ \ interface\ eth0\ world\ ...
\ \ \ \ class\ surfing\ commit\ 128kbit\ ceil\ 1024kbit\ prio\ 7
\ \ \ \ \ \ match\ src\ 10.1.128.230\ dst\ 8.8.8.8\ insidegre
\ \ \ \ \ \ match\ protocol\ ospf\ insidegre
\ \ \ \ \ \ match\ port\ 25\ insidegre
\ \ \ \ \ \ match\ tos\ 3\ insidegre
\ \ \ \ \ \ match\ dscp\ ef\ insidegre
\f[]
.fi
.SH SEE ALSO
.IP \[bu] 2
fireqos(1) \- FireQOS program
.IP \[bu] 2
fireqos.conf(5) \- FireQOS configuration file
.IP \[bu] 2
fireqos\-match(5) \- QOS traffic match
.IP \[bu] 2
FireHOL Website (http://firehol.org/)
.IP \[bu] 2
FireQOS Online PDF Manual (http://firehol.org/fireqos-manual.pdf)
.IP \[bu] 2
FireQOS Online Documentation (http://firehol.org/documentation/)
.SH AUTHORS
FireHOL Team.