fix: #2123 Logging of user defined firewall rules
[pve-docs.git] / pve-firewall.adoc
1 [[chapter_pve_firewall]]
2 ifdef::manvolnum[]
3 pve-firewall(8)
4 ===============
5 :pve-toplevel:
6
7 NAME
8 ----
9
10 pve-firewall - PVE Firewall Daemon
11
12
13 SYNOPSIS
14 --------
15
16 include::pve-firewall.8-synopsis.adoc[]
17
18
19 DESCRIPTION
20 -----------
21 endif::manvolnum[]
22 ifndef::manvolnum[]
23 {pve} Firewall
24 ==============
25 :pve-toplevel:
26 endif::manvolnum[]
27 ifdef::wiki[]
28 :title: Firewall
29 endif::wiki[]
30
31 {pve} Firewall provides an easy way to protect your IT
32 infrastructure. You can setup firewall rules for all hosts
33 inside a cluster, or define rules for virtual machines and
34 containers. Features like firewall macros, security groups, IP sets
35 and aliases help to make that task easier.
36
37 While all configuration is stored on the cluster file system, the
38 `iptables`-based firewall runs on each cluster node, and thus provides
39 full isolation between virtual machines. The distributed nature of
40 this system also provides much higher bandwidth than a central
41 firewall solution.
42
43 The firewall has full support for IPv4 and IPv6. IPv6 support is fully
44 transparent, and we filter traffic for both protocols by default. So
45 there is no need to maintain a different set of rules for IPv6.
46
47
48 Zones
49 -----
50
51 The Proxmox VE firewall groups the network into the following logical zones:
52
53 Host::
54
55 Traffic from/to a cluster node
56
57 VM::
58
59 Traffic from/to a specific VM
60
61 For each zone, you can define firewall rules for incoming and/or
62 outgoing traffic.
63
64
65 Configuration Files
66 -------------------
67
68 All firewall related configuration is stored on the proxmox cluster
69 file system. So those files are automatically distributed to all
70 cluster nodes, and the `pve-firewall` service updates the underlying
71 `iptables` rules automatically on changes.
72
73 You can configure anything using the GUI (i.e. *Datacenter* -> *Firewall*,
74 or on a *Node* -> *Firewall*), or you can edit the configuration files
75 directly using your preferred editor.
76
77 Firewall configuration files contains sections of key-value
78 pairs. Lines beginning with a `#` and blank lines are considered
79 comments. Sections starts with a header line containing the section
80 name enclosed in `[` and `]`.
81
82
83 [[pve_firewall_cluster_wide_setup]]
84 Cluster Wide Setup
85 ~~~~~~~~~~~~~~~~~~
86
87 The cluster wide firewall configuration is stored at:
88  
89  /etc/pve/firewall/cluster.fw
90
91 The configuration can contain the following sections:
92
93 `[OPTIONS]`::
94
95 This is used to set cluster wide firewall options.
96
97 include::pve-firewall-cluster-opts.adoc[]
98
99 `[RULES]`::
100
101 This sections contains cluster wide firewall rules for all nodes.
102
103 `[IPSET <name>]`::
104
105 Cluster wide IP set definitions.
106
107 `[GROUP <name>]`::
108
109 Cluster wide security group definitions.
110
111 `[ALIASES]`::
112
113 Cluster wide Alias definitions.
114
115
116 Enabling the Firewall
117 ^^^^^^^^^^^^^^^^^^^^^
118
119 The firewall is completely disabled by default, so you need to
120 set the enable option here:
121
122 ----
123 [OPTIONS]
124 # enable firewall (cluster wide setting, default is disabled)
125 enable: 1
126 ----
127
128 IMPORTANT: If you enable the firewall, traffic to all hosts is blocked by
129 default. Only exceptions is WebGUI(8006) and ssh(22) from your local
130 network.
131
132 If you want to administrate your {pve} hosts from remote, you
133 need to create rules to allow traffic from those remote IPs to the web
134 GUI (port 8006). You may also want to allow ssh (port 22), and maybe
135 SPICE (port 3128).
136
137 TIP: Please open a SSH connection to one of your {PVE} hosts before
138 enabling the firewall. That way you still have access to the host if
139 something goes wrong .
140
141 To simplify that task, you can instead create an IPSet called
142 ``management'', and add all remote IPs there. This creates all required
143 firewall rules to access the GUI from remote.
144
145
146 [[pve_firewall_host_specific_configuration]]
147 Host Specific Configuration
148 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
149
150 Host related configuration is read from:
151
152  /etc/pve/nodes/<nodename>/host.fw
153
154 This is useful if you want to overwrite rules from `cluster.fw`
155 config. You can also increase log verbosity, and set netfilter related
156 options. The configuration can contain the following sections:
157
158 `[OPTIONS]`::
159
160 This is used to set host related firewall options.
161
162 include::pve-firewall-host-opts.adoc[]
163
164 `[RULES]`::
165
166 This sections contains host specific firewall rules.
167
168 [[pve_firewall_vm_container_configuration]]
169 VM/Container Configuration
170 ~~~~~~~~~~~~~~~~~~~~~~~~~~
171
172 VM firewall configuration is read from:
173
174  /etc/pve/firewall/<VMID>.fw
175
176 and contains the following data:
177
178 `[OPTIONS]`::
179
180 This is used to set VM/Container related firewall options.
181
182 include::pve-firewall-vm-opts.adoc[]
183
184 `[RULES]`::
185
186 This sections contains VM/Container firewall rules.
187
188 `[IPSET <name>]`::
189
190 IP set definitions.
191
192 `[ALIASES]`::
193
194 IP Alias definitions.
195
196
197 Enabling the Firewall for VMs and Containers
198 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
199
200 Each virtual network device has its own firewall enable flag. So you
201 can selectively enable the firewall for each interface. This is
202 required in addition to the general firewall `enable` option.
203
204
205 Firewall Rules
206 --------------
207
208 Firewall rules consists of a direction (`IN` or `OUT`) and an
209 action (`ACCEPT`, `DENY`, `REJECT`). You can also specify a macro
210 name. Macros contain predefined sets of rules and options. Rules can be
211 disabled by prefixing them with `|`.
212
213 .Firewall rules syntax
214 ----
215 [RULES]
216
217 DIRECTION ACTION [OPTIONS]
218 |DIRECTION ACTION [OPTIONS] # disabled rule
219
220 DIRECTION MACRO(ACTION) [OPTIONS] # use predefined macro
221 ----
222
223 The following options can be used to refine rule matches. 
224
225 include::pve-firewall-rules-opts.adoc[]
226
227 Here are some examples:
228
229 ----
230 [RULES]
231 IN SSH(ACCEPT) -i net0
232 IN SSH(ACCEPT) -i net0 # a comment
233 IN SSH(ACCEPT) -i net0 -source 192.168.2.192 # only allow SSH from 192.168.2.192
234 IN SSH(ACCEPT) -i net0 -source 10.0.0.1-10.0.0.10 # accept SSH for IP range
235 IN SSH(ACCEPT) -i net0 -source 10.0.0.1,10.0.0.2,10.0.0.3 #accept ssh for IP list
236 IN SSH(ACCEPT) -i net0 -source +mynetgroup # accept ssh for ipset mynetgroup
237 IN SSH(ACCEPT) -i net0 -source myserveralias #accept ssh for alias myserveralias
238
239 |IN SSH(ACCEPT) -i net0 # disabled rule
240
241 IN  DROP # drop all incoming packages
242 OUT ACCEPT # accept all outgoing packages
243 ----
244
245
246 [[pve_firewall_security_groups]]
247 Security Groups
248 ---------------
249
250 A security group is a collection of rules, defined at cluster level, which
251 can be used in all VMs' rules. For example you can define a group named
252 ``webserver'' with rules to open the 'http' and 'https' ports.
253
254 ----
255 # /etc/pve/firewall/cluster.fw
256
257 [group webserver]
258 IN  ACCEPT -p tcp -dport 80
259 IN  ACCEPT -p tcp -dport 443
260 ----
261
262 Then, you can add this group to a VM's firewall
263
264 ----
265 # /etc/pve/firewall/<VMID>.fw
266
267 [RULES]
268 GROUP webserver
269 ----
270
271 [[pve_firewall_ip_aliases]]
272 IP Aliases
273 ----------
274
275 IP Aliases allow you to associate IP addresses of networks with a
276 name. You can then refer to those names:
277
278 * inside IP set definitions
279 * in `source` and `dest` properties of firewall rules
280
281
282 Standard IP Alias `local_network`
283 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
284
285 This alias is automatically defined. Please use the following command
286 to see assigned values:
287
288 ----
289 # pve-firewall localnet
290 local hostname: example
291 local IP address: 192.168.2.100
292 network auto detect: 192.168.0.0/20
293 using detected local_network: 192.168.0.0/20
294 ----
295
296 The firewall automatically sets up rules to allow everything needed
297 for cluster communication (corosync, API, SSH) using this alias.
298
299 The user can overwrite these values in the `cluster.fw` alias
300 section. If you use a single host on a public network, it is better to
301 explicitly assign the local IP address
302
303 ----
304 #  /etc/pve/firewall/cluster.fw
305 [ALIASES]
306 local_network 1.2.3.4 # use the single IP address
307 ----
308
309 [[pve_firewall_ip_sets]]
310 IP Sets
311 -------
312
313 IP sets can be used to define groups of networks and hosts. You can
314 refer to them with `+name` in the firewall rules' `source` and `dest`
315 properties.
316
317 The following example allows HTTP traffic from the `management` IP
318 set.
319
320  IN HTTP(ACCEPT) -source +management
321
322
323 Standard IP set `management`
324 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
325
326 This IP set applies only to host firewalls (not VM firewalls).  Those
327 IPs are allowed to do normal management tasks (PVE GUI, VNC, SPICE,
328 SSH).
329
330 The local cluster network is automatically added to this IP set (alias
331 `cluster_network`), to enable inter-host cluster
332 communication. (multicast,ssh,...)
333
334 ----
335 # /etc/pve/firewall/cluster.fw
336
337 [IPSET management] 
338 192.168.2.10
339 192.168.2.10/24
340 ----
341
342
343 Standard IP set `blacklist`
344 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
345
346 Traffic from these IPs is dropped by every host's and VM's firewall.
347
348 ----
349 # /etc/pve/firewall/cluster.fw
350
351 [IPSET blacklist] 
352 77.240.159.182
353 213.87.123.0/24
354 ----
355
356
357 [[pve_firewall_ipfilter_section]]
358 Standard IP set `ipfilter-net*`
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
360
361 These filters belong to a VM's network interface and are mainly used to prevent
362 IP spoofing. If such a set exists for an interface then any outgoing traffic
363 with a source IP not matching its interface's corresponding ipfilter set will
364 be dropped.
365
366 For containers with configured IP addresses these sets, if they exist (or are
367 activated via the general `IP Filter` option in the VM's firewall's *options*
368 tab), implicitly contain the associated IP addresses.
369
370 For both virtual machines and containers they also implicitly contain the
371 standard MAC-derived IPv6 link-local address in order to allow the neighbor
372 discovery protocol to work.
373
374 ----
375 /etc/pve/firewall/<VMID>.fw
376
377 [IPSET ipfilter-net0] # only allow specified IPs on net0
378 192.168.2.10
379 ----
380
381
382 Services and Commands
383 ---------------------
384
385 The firewall runs two service daemons on each node:
386
387 * pvefw-logger: NFLOG daemon (ulogd replacement).
388 * pve-firewall: updates iptables rules
389
390 There is also a CLI command named `pve-firewall`, which can be used to
391 start and stop the firewall service:
392
393  # pve-firewall start
394  # pve-firewall stop
395
396 To get the status use:
397
398  # pve-firewall status
399
400 The above command reads and compiles all firewall rules, so you will
401 see warnings if your firewall configuration contains any errors.
402
403 If you want to see the generated iptables rules you can use:
404
405  # iptables-save
406
407 Logging of firewall rules
408 -------------------------
409
410 By default, logging of traffic filtered by the firewall rules is disabled. To
411 enable logging for the default firewall rules, the log-level for incommig and
412 outgoing traffic has to be set in the firewall `Options` tab for the host and/or
413 the VM/CT firewall.
414 Logging of dropped packets is rate limited to 1 packet per second in order to
415 reduce output to the log file.
416 Further, only some dropped or rejected packets are logged for the standard rules.
417
418 In order to log packets filtered by user-defined firewall rules, it is possible
419 to set a log-level parameter for each rule individually.
420 This allows to log in a fine grained manner and independent of the log-level
421 defined for the standard rules.
422 In particular, each rule is logged independently from the log-level set for the
423 standard rules in the firewall `Options`.
424
425 The log level for the rule can also be set via the firewall configuration file by
426 appending a `-log <loglevel>` to the selected rule.
427 Here, `<loglevel>` is one of the following flags, attached to the log output:
428 `nolog, emerg, alert, crit, err, warning, notice, info, debug`
429
430 For example:
431
432 ----
433 IN REJECT -p icmp -log nolog
434 ----
435
436 is the same as
437
438 ----
439 IN REJECT -p icmp
440 ----
441
442 whereas
443
444 ----
445 IN REJECT -p icmp -log debug
446 ----
447
448 produces a log output flagged with the `debug` level.
449
450
451 Tips and Tricks
452 ---------------
453
454 How to allow FTP
455 ~~~~~~~~~~~~~~~~
456
457 FTP is an old style protocol which uses port 21 and several other dynamic ports. So you
458 need a rule to accept port 21. In addition, you need to load the `ip_conntrack_ftp` module.
459 So please run: 
460
461  modprobe ip_conntrack_ftp
462
463 and add `ip_conntrack_ftp` to `/etc/modules` (so that it works after a reboot).
464
465
466 Suricata IPS integration
467 ~~~~~~~~~~~~~~~~~~~~~~~~
468
469 If you want to use the http://suricata-ids.org/[Suricata IPS]
470 (Intrusion Prevention System), it's possible.
471
472 Packets will be forwarded to the IPS only after the firewall ACCEPTed
473 them.
474
475 Rejected/Dropped firewall packets don't go to the IPS.
476
477 Install suricata on proxmox host:
478
479 ----
480 # apt-get install suricata
481 # modprobe nfnetlink_queue  
482 ----
483
484 Don't forget to add `nfnetlink_queue` to `/etc/modules` for next reboot.
485
486 Then, enable IPS for a specific VM with:
487
488 ----
489 # /etc/pve/firewall/<VMID>.fw
490
491 [OPTIONS]
492 ips: 1
493 ips_queues: 0
494 ----
495
496 `ips_queues` will bind a specific cpu queue for this VM.
497
498 Available queues are defined in
499
500 ----
501 # /etc/default/suricata
502 NFQUEUE=0
503 ----
504
505
506 Notes on IPv6
507 -------------
508
509 The firewall contains a few IPv6 specific options. One thing to note is that
510 IPv6 does not use the ARP protocol anymore, and instead uses NDP (Neighbor
511 Discovery Protocol) which works on IP level and thus needs IP addresses to
512 succeed. For this purpose link-local addresses derived from the interface's MAC
513 address are used. By default the `NDP` option is enabled on both host and VM
514 level to allow neighbor discovery (NDP) packets to be sent and received.
515
516 Beside neighbor discovery NDP is also used for a couple of other things, like
517 auto-configuration and advertising routers.
518
519 By default VMs are allowed to send out router solicitation messages (to query
520 for a router), and to receive router advertisement packets. This allows them to
521 use stateless auto configuration. On the other hand VMs cannot advertise
522 themselves as routers unless the ``Allow Router Advertisement'' (`radv: 1`) option
523 is set.
524
525 As for the link local addresses required for NDP, there's also an ``IP Filter''
526 (`ipfilter: 1`) option which can be enabled which has the same effect as adding
527 an `ipfilter-net*` ipset for each of the VM's network interfaces containing the
528 corresponding link local addresses.  (See the
529 <<pve_firewall_ipfilter_section,Standard IP set `ipfilter-net*`>> section for details.)
530
531
532 Ports used by {pve}
533 -------------------
534
535 * Web interface: 8006
536 * VNC Web console: 5900-5999
537 * SPICE proxy: 3128
538 * sshd (used for cluster actions): 22
539 * rpcbind: 111
540 * corosync multicast (if you run a cluster): 5404, 5405 UDP
541
542
543 ifdef::manvolnum[]
544
545 Macro Definitions
546 -----------------
547
548 include::pve-firewall-macros.adoc[]
549
550
551 include::pve-copyright.adoc[]
552
553 endif::manvolnum[]