Debian Codegraph @

docs/config/section/iplist.md

raw
1 # iplist
2
3 Instead of using static IP addresses Foomuuri can perform periodical DNS
4 hostname lookups and download external IP-lists. These addresses are
5 stored to sets and cached across reboots and single lookup failures.
6
7 First word in line is set name, which must begin with `@` character.
8 Next words can be:
9
10 * IPv4 or IPv6 address, with or without mask
11 * DNS hostname
12 * Filename containing IP addresses, with or without mask
13 * URL for file containing IP addresses, with or without mask
14
15 Example:
16
17 ```
18 iplist {
19 # Resolve known good hostnames
20 @goodhost foobar.fi mydomain.com
21
22 # Download Finnish IPv4 and IPv6 addresses from https://github.com/ipverse/rir-ip
23 @fi https://raw.githubusercontent.com/ipverse/rir-ip/master/country/fi/ipv4-aggregated.txt
24 @fi + https://raw.githubusercontent.com/ipverse/rir-ip/master/country/fi/ipv6-aggregated.txt
25
26 # Download Finnish Elisa operator IP addresses from https://github.com/ipverse/asn-ip
27 @elisa https://raw.githubusercontent.com/ipverse/asn-ip/master/as/719/ipv4-aggregated.txt
28 @elisa + https://raw.githubusercontent.com/ipverse/asn-ip/master/as/719/ipv6-aggregated.txt
29
30 # Read blacklist from text files
31 @blacklist /etc/foomuuri/blacklist*.txt
32
33 # Read content from file and add some extra IPs to it
34 @whitelist /etc/foomuuri/whitelist*.txt 10.0.0.0/8 192.0.2.32
35
36 # Manipulate this list with "foomuuri iplist add mylist 10.0.0.1" command.
37 # See command line help for "foomuuri add/del/flush" commands.
38 @mylist
39 }
40
41 public-localhost {
42 # Allow SSH from known good hosts
43 ssh saddr @goodhost
44
45 # Don't allow blacklisted addresses to IMAP
46 imap saddr @blacklist drop log "public-localhost DROP-blacklist"
47
48 # Allow mylist entries to IMAP without rate
49 imap saddr @mylist
50
51 # Allow Finnish users to IMAP with fast 1 per second rate
52 imap saddr @fi saddr_rate "1/second burst 10"
53
54 # Allow everybody to IMAP with slow 1 per minute rate. This includes
55 # over rate limit Finnish users.
56 imap saddr_rate "1/minute burst 1"
57
58 # ...rest of the rules...
59 }
60 ```
61
62 Hostnames are refreshed every 15 minutes and they will timeout after 24 hours.
63 URLs are refreshed once a day and timeout is 10 days. These values can be
64 changed globally or per set.
65
66 ```
67 iplist {
68 # Define global timeouts
69 dns_refresh=15m
70 dns_timeout=24h
71 url_refresh=1d
72 url_timeout=10d
73
74 # Define per set timeout
75 @fasturl https://some/url url_refresh=1h30m url_timeout=2d
76 }
77 ```
78
79 Above timeouts are rounded to 15 minutes. This can be configured with
80 `systemctl edit foomuuri-iplist.timer` command.
81
82 Timeout can be:
83
84 * `4w` weeks
85 * `2d` days
86 * `3h` hours
87 * `15m` minutes
88 * `900s` seconds
89 * `2d3h15m` or `1w90m` combination of above
90
91 Downloaded content can be filtered by adding `|filter` after filename,
92 URL or hostname. Multiple filters can be chained.
93
94 * `|shell:/path/to/command` pipe it via external command
95 * `|json:filter` use external `jq` command to parse it as JSON data
96 * `|html:XPath` parse it as HTML data, using XPath filter
97 * `|xml:XPath` parse it as XML data, using XPath filter
98 * `|missing-ok` don't print warning if download or DNS resolve fails
99
100 Example:
101
102 ```
103 iplist {
104 # Download Github IP address list and parse it as JSON, returning
105 # "actions" list.
106 @github https://api.github.com/meta|json:.actions[]
107
108 # Download network scanner IP address list and parse it from HTML page.
109 @netscanner https://internet-measurement.com/|html://div/pre/text()
110 }
111 ```
112
113 Maximum content size for downloaded IP address list can be defined with
114 `url_max_size=bytes` line. Default value is 33554432 (32 MiB). List will
115 be ignored if it's too large.
116
117 Optional `dynamic=yes` option enables dynamic flag on generated ruleset.
118 This flag is needed when updating iplist content on packet path with
119 [`iplist_update`](../rule/matcher.md#iplist_update) matcher, for example in automatic
120 IP address [banning](../../example/advanced.md#automatic-ip-address-banning).
121 For normal usage this option should not be used.
122
123 Optional `element_timeout=time` option sets default element expire timeout.
124 This is needed in automatic IP address banning and port knocking.
125
126 Optional `merge=no` option disables IP address auto-merge. Normally it is
127 recommended to keep it enabled. When using external `fail2ban` program
128 (see below) it is recommended to be disabled.
129
130 Foomuuri startup will not add IP addresses to lists marked with optional
131 `start=no` option. Entries will be added later by `foomuuri-iplist.timer`
132 service. This can be used with "unsafe" external iplists to make sure
133 Foomuuri start will not fail or block your access for first minutes after
134 reboot.
135
136 Iplists can be manipulated from command line, for example by `fail2ban`
137 external program. Command `foomuuri iplist add @setname ipaddress` adds IP
138 address to `@setname`. Other commands are `foomuuri iplist list`,
139 `foomuuri iplist del` and `foomuuri iplist flush`. See command line help for
140 usage. Example:
141
142 ```
143 iplist {
144 @banned dynamic=yes element_timeout=5m # automatic IP address banning
145 @blacklist merge=no # fail2ban
146 }
147
148 # Manipulate with command:
149 #
150 # foomuuri iplist add @blacklist 10.0.0.1
151 # foomuuri iplist del @blacklist 10.0.0.1
152 ```
153
154 Another example how to create a macro to allow access to Valve Steam:
155
156 ```
157 iplist {
158 # Create iplist from Valve's IP addresses
159 @valve_as https://raw.githubusercontent.com/ipverse/asn-ip/master/as/32590/ipv4-aggregated.txt
160 @valve_as + https://raw.githubusercontent.com/ipverse/asn-ip/master/as/32590/ipv6-aggregated.txt
161 }
162
163 macro {
164 # Create macro to allow outgoing traffic to Valve iplist
165 valve-steam udp 3478 4379-4380 27000-27100 daddr @valve_as;
166 valve-steam + tcp 27015-27050 daddr @valve_as
167 }
168
169 localhost-public {
170 # Allow outgoing traffic to Valve Steam
171 valve-steam
172 }
173 ```