Debian Codegraph @

docs/config/rule/matcher.md

raw
1 # Matchers
2
3
4 ## tcp, udp, icmp, icmpv6
5
6 Matches TCP / UDP / ICMP / ICMPv6 traffic. This matcher is usually followed by
7 port number. For example `tcp 443` matches TCP traffic to port 443 (https).
8 Without port number all traffic is matched. See [protocol](matcher.md#protocol)
9 how to match other protocols.
10
11 Instead of using `tcp 443` it is recommended to use pre-defined `https`
12 macro. All
13 [known macros](https://github.com/FoobarOy/foomuuri/blob/main/etc/default.services.conf)
14 can be listed with `foomuuri macro list` command.
15
16
17 ## sport, dport
18
19 Matches source / destination port, followed by port number. `dport` matcher is
20 usually optional: `tcp 443` is equal to `tcp dport 443`.
21
22 Port number can be:
23
24 * Single number `443`
25 * Multiple numbers `80 443`, matching 80 or 443
26 * Range `8880-9000`
27 * Range and number `80 443 8880-9000`
28 * Negative number `-443`, matching all but 443
29 * Multiple negative numbers `-80 -443`, matching all but 80 or 443
30
31
32 ## saddr, daddr
33
34 Matches source / destination IPv4 or IPv6 address.
35
36 Address can be
37
38 * Single IPv4 address `10.0.0.1`
39 * Single IPv6 address `fd00:f00::1`
40 * Address with netmask `10.0.0.0/8` or `fd00:f00::/32`
41 * IPv6 address with suffix netmask `::10:0:0:f00/-64` to match with netmask
42 `::ffff:ffff:ffff:ffff`
43 * Interval `10.0.0.10-10.0.0.20` or `fd00:f00::10-fd00:f00::20`
44 * Multiple addresses `10.0.0.1 10.0.0.10-10.0.0.20 fd00:f00::/32`.
45 You can list both IPv4 and IPv6 addresses in same rule. Foomuuri will
46 split them automatically to correct traffic chains.
47 * Negative address `-10.0.0.1` or `-fd00:f00::1`, meaning all other
48 addresses.
49 * Negative IPv6 address with suffix netmask `-::10:0:0:f00/-64`
50 * Multiple negative addresses `-10.0.0.1 -fd00:f00::1`
51 * Iplist set name `@listname`
52 * Negative iplist set name `-@listname`
53
54 This matcher is usually combined with `tcp port` matcher to allow traffic
55 from specific source IP only, `tcp 443 saddr 10.0.0.1`, or to specific
56 destination IP.
57
58
59 ## mac_saddr, mac_daddr
60
61 Matches source / destination MAC address for incoming traffic. This doesn't
62 work for outgoing traffic.
63
64 Address can be:
65
66 * Single MAC address `01:23:45:67:89:ab`
67 * Multiple MAC addresses `01:23:45:67:89:ab 01:23:45:67:89:cc`
68 * Negative MAC address `-01:23:45:67:89:ab`, meaning all other addresses.
69 * Multiple negative MAC addresses `-01:23:45:67:89:ab -01:23:45:67:89:cc`
70
71 Example:
72
73 ```
74 internal-localhost {
75 # drop spoofed traffic from 10.0.0.3
76 saddr 10.0.0.3 mac_saddr -12:00:27:00:00:ce drop log "MAC-SPOOF"
77 ...
78 }
79 ```
80
81
82 ## iifname, oifname
83
84 Matches incoming / outgoing interface name. This is used mostly on `snat`,
85 `dnat` and `zonemap` sections. For example in snat
86 `saddr 10.0.0.0/8 oifname eth0 masquerade` will match all traffic coming
87 from 10.0.0.0/8, going to eth0, and masquerades it.
88
89 Multiple interface names can be specified. Negative interface name(s) works
90 too, meaning all but specified name(s).
91
92
93 ## ipv4, ipv6
94
95 Single rule will apply to both IPv4 and IPv6 traffic. Adding
96 `ipv4` or `ipv6` matcher to rule will limit it to IPv4 or IPv6 only.
97
98
99 ## multicast, broadcast
100
101 Matches multicast or broadcast traffic. Foomuuri will silently drop all
102 incoming multicast and broadcast traffic unless explicitly accepted by rule.
103
104 Linux kernel can match multicast/broadcast only in incoming traffic.
105 Therefore Foomuuri generates outgoing nft rule without multicast/broadcast
106 matcher even if one was specified in the rule. This makes it easy to use same
107 rule or macro for all traffic, no matter if it's incoming or outgoing.
108
109 Rule `broadcast udp 11430` allows incoming broadcast messages to UDP port
110 11430, or all outgoing traffic to UDP port 11430. Rule `multicast` allows all
111 incoming multicasts, nothing for outgoing. It is highly recommended to always
112 specify `daddr` for multicast rules.
113
114 Example:
115
116 ```
117 public-localhost {
118 # Allow all incoming multicasts
119 multicast
120 ...
121 }
122
123 localhost-public {
124 # Allow some outgoing multicast addresses. This rule can also be written
125 # without "multicast" matcher as it will be omitted.
126 multicast daddr 224.0.0.0/8 239.0.0.0/8 ff00::/8
127 ...
128 }
129 ```
130
131 It is much better to accept specific multicast/broadcast only, not everything.
132 For example macro `ssdp` is defined as:
133
134 ```
135 macro {
136 ssdp multicast udp 1900 daddr 239.255.255.250 ff02::c; udp sport 1900
137 }
138
139 public-localhost {
140 # Allow incoming ssdp
141 ssdp
142 ...
143 }
144
145 localhost-public {
146 # Allow outgoing ssdp
147 ssdp
148 ...
149 }
150 ```
151
152 Above macro allows incoming traffic to specific multicast addresses and UDP
153 port 1900, outgoing traffic to same addresses and port, and finally unicast
154 from same port.
155
156
157 ## protocol
158
159 Matches specific protocol traffic. For example `protocol gre` will match all
160 GRE traffic and `protocol sctp 22` will match SCTP traffic to port 22.
161
162 For TCP, UDP, ICMP and ICMPv6 protocols it is recommended to use
163 [shortcut](matcher.md#tcp-udp-icmp-icmpv6) matchers.
164
165
166 ## sipsec, dipsec
167
168 Matches incoming / outgoing IPsec traffic. These are useful if you want to
169 allow traffic from/to IPsec without creating a new `vpn` zone for them.
170 Example:
171
172 ```
173 public-localhost {
174 ssh # Allow SSH with and without IPsec
175 tcp 1234 sipsec # Allow TCP 1234 with IPsec only
176 ...
177 }
178 ```
179
180 To split IPsec and non-IPsec traffic to `vpn` and `public` zones you can
181 use these matchers in `zonemap` [section](../section/zonemap.md). Usually
182 it is not necessary to create separate zone for that.
183
184 Negative matchers `-sipsec` and `-dipsec` can also be used. They match
185 non-IPsec traffic. These are useful in `snat` and `dnat`
186 [sections](../section/snat.md).
187
188
189 ## uid, gid
190
191 Matches traffic generated by uid / gid user. This works only for traffic
192 from `localhost`. For example `tcp 2703 uid amavis` in `localhost-public`
193 section allows outgoing TCP 2703 traffic from user `amavis`.
194
195 Multiple uid / gid names or numbers can be specified. Negative value(s)
196 works too, meaning all but specified value(s).
197
198
199 ## mark_match
200
201 Matches packet's mark. Argument can be:
202
203 * Number `42` or `0x2a`
204 * Number with mask `0x100/0xff00`, meaning check if `mark and 0xff00` is
205 equal to `0x100`
206 * Negative number `-42`, meaning all other marks than `42`
207 * Negative number with mask `-0x0000/0xff00` for non-equal check
208
209
210 ## mark_set
211
212 Set packet's mark. Argument can be:
213
214 * Number `42` or `0x2a`
215 * Number with mask `0x100/0xff00`, meaning set bits `0xff00` to `0x100`. In
216 other words, this keeps lower 8 bits as they are and sets upper 8 bits.
217
218 This is not normal matcher as it matches everything. Usually some other
219 matcher should be used first. Example:
220
221 ```
222 prerouting {
223 iifname eth0 mark_set 0x100/0xff00 # Mark traffic from eth0 and accept it
224 iifname eth1 mark_set 0x200/0xff00 # Mark traffic from eth1 and accept it
225 mark_set 0x300/0xff00 # Mark all other traffic
226 }
227 ```
228
229
230 ## priority_match
231
232 Matches packet's traffic control class id. Argument can be:
233
234 * Class id `1:ff01` or `1:0xff01` (`0x` is optional)
235 * Text `none` for no priority set
236
237
238 ## priority_set
239
240 Set packet's traffic control class id.
241
242 This is not normal matcher as it matches everything. Usually some other
243 matcher should be used first. Example:
244
245 ```
246 forward {
247 daddr 192.168.0.0/16 priority_match none priority_set 1:ff01
248 saddr 192.168.0.0/16 priority_match none priority_set 1:ff01
249 priority_match none priority_set 1:2
250 }
251 ```
252
253
254 ## iplist_add
255
256 Add packet source or destination IP address to
257 [iplist](../section/iplist.md), using default `element_timeout`.
258 Timeout is not updated if IP address is already in iplist.
259 Two arguments are needed: `saddr` or `daddr`, and iplist `@name`.
260
261 Normally `iplist_update` is a better choice as it updates timeout.
262
263
264 ## iplist_update
265
266 Add/update packet source or destination IP address to
267 [iplist](../section/iplist.md), using default `element_timeout`.
268 Timeout will be updated if IP address is already in iplist.
269 Two arguments are needed: `saddr` or `daddr`, and iplist `@name`.
270
271 See [port knocking](../../example/advanced.md#port-knocking)
272 and automatic IP address
273 [banning](../../example/advanced.md#automatic-ip-address-banning)
274 for examples.
275
276
277 ## iplist_delete
278
279 Delete packet source or destination IP address from
280 [iplist](../section/iplist.md).
281 Two arguments are needed: `saddr` or `daddr`, and iplist `@name`.
282
283 See [port knocking](../../example/advanced.md#port-knocking) for example.
284
285
286 ## ct_status
287
288 Matches packet's conntrack status, mostly used with
289 [SNAT or DNAT](../section/dnat.md). Valid arguments are: expected,
290 seen-reply, assured, confirmed, snat, dnat, dying.
291
292
293 ## cgroup
294
295 Matches cgroup id or cgroupv2 name. Argument can be:
296
297 * Single number `1234`
298 * Multiple numbers `1234 1244`
299 * Range `4000-5000`
300 * Range and number `1234 1244 4000-5000`
301 * Negative number `-1234`, matching all but 1234
302 * Multiple negative numbers `-1234 -1244`, matching all but 1234 or 1244
303 * cgroupv2 name `user.slice` or `system.slice/sshd.service`
304
305 **Warning**: cgroupv2 must exist before starting Foomuuri. As Foomuuri starts
306 very early on boot using this feature incorrectly can break your firewall
307 startup.
308
309
310 ## time
311
312 Matches current time, date and day of the week. Argument can be:
313
314 * Time `hh:mm` or `hh:mm:ss`
315 * Time interval `hh:mm-hh:mm` (see warning below)
316 * Date `yyyy-mm-dd`
317 * Day of the week: `Monday`, `Tuesday`, `Wednesday`, `Thursday`,
318 `Friday`, `Saturday`, `Sunday`
319 * Compare function: `==` (equal, the default), `!=` (not equal), `<`, `>`,
320 `<=`, `>=`
321 * Combination of above
322
323 **Warning**: Some versions of `nft` do not handle time interval crossing
324 midnight UTC. If your timezone is +03:00, interval `23:00-02:00` works
325 but `02:00-06:00` fails.
326
327 Example:
328
329 ```
330 public-localhost {
331 # Allow until year 2025
332 tcp 1234 time "< 2025-01-01"
333
334 # Kids, go to bed! Reject traffic at night time.
335 saddr @kids time "23:00-07:00" reject
336
337 # Strange combination: Allow traffic on Mondays at 16-22, until year 2025
338 tcp 5001 time "Monday 16:00-22:00 < 2025-01-01"
339 }
340 ```
341
342
343 ## dscp
344
345 Matches packet's differentiated services code point (DSCP) value. Example:
346
347 ```
348 internal-public {
349 saddr 10.0.0.4 dscp 10
350 dscp af13
351 }
352 ```
353
354
355 ## tproxy
356
357 Transparent proxy traffic to ipaddress:port. Example:
358
359 ```
360 prerouting {
361 # Use lower 8 bits to mark tproxy traffic
362 mark_match -0x00/0xff # Anti-loop protection
363
364 # All IPv4 and IPv6 TCP traffic
365 tcp tproxy 127.0.0.1:8888 [::1]:8888 mark_set 0x01/0xff
366 }
367 ```