api-viewer: tree-tools: use modern callback and add tooltips
[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 service 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 contain sections of key-value
78 pairs. Lines beginning with a `#` and blank lines are considered
79 comments. Sections start 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 [[pve_firewall_default_rules]]
408 Default firewall rules
409 ----------------------
410
411 The following traffic is filtered by the default firewall configuration:
412
413 Datacenter incoming/outgoing DROP/REJECT
414 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
415
416 If the input or output policy for the firewall is set to DROP or REJECT, the
417 following traffic is still allowed for all {pve} hosts in the cluster:
418
419 * traffic over the loopback interface
420 * already established connections
421 * traffic using the IGMP protocol
422 * TCP traffic from management hosts to port 8006 in order to allow access to
423   the web interface
424 * TCP traffic from management hosts to the port range 5900 to 5999 allowing
425   traffic for the VNC web console
426 * TCP traffic from management hosts to port 3128 for connections to the SPICE
427   proxy
428 * TCP traffic from management hosts to port 22 to allow ssh access
429 * UDP traffic in the cluster network to port 5404 and 5405 for corosync
430 * UDP multicast traffic in the cluster network
431 * ICMP traffic type 3 (Destination Unreachable), 4 (congestion control) or 11
432   (Time Exceeded)
433
434 The following traffic is dropped, but not logged even with logging enabled:
435
436 * TCP connections with invalid connection state
437 * Broadcast, multicast and anycast traffic not related to corosync, i.e., not
438   coming through port 5404 or 5405
439 * TCP traffic to port 43
440 * UDP traffic to ports 135 and 445
441 * UDP traffic to the port range 137 to 139
442 * UDP traffic form source port 137 to port range 1024 to 65535
443 * UDP traffic to port 1900
444 * TCP traffic to port 135, 139 and 445
445 * UDP traffic originating from source port 53
446
447 The rest of the traffic is dropped or rejected, respectively, and also logged.
448 This may vary depending on the additional options enabled in
449 *Firewall* -> *Options*, such as NDP, SMURFS and TCP flag filtering.
450
451 [[pve_firewall_iptables_inspect]]
452 Please inspect the output of the
453
454 ----
455  # iptables-save
456 ----
457
458 system command to see the firewall chains and rules active on your system.
459 This output is also included in a `System Report`, accessible over a node's
460 subscription tab in the web GUI, or through the `pvereport` command line tool.
461
462 VM/CT incoming/outgoing DROP/REJECT
463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
464
465 This drops or rejects all the traffic to the VMs, with some exceptions for
466 DHCP, NDP, Router Advertisement, MAC and IP filtering depending on the set
467 configuration.  The same rules for dropping/rejecting packets are inherited
468 from the datacenter, while the exceptions for accepted incomming/outgoing
469 traffic of the host do not apply.
470
471 Again, you can use xref:pve_firewall_iptables_inspect[iptables-save (see above)]
472 to inspect all rules and chains applied.
473
474 Logging of firewall rules
475 -------------------------
476
477 By default, all logging of traffic filtered by the firewall rules is disabled.
478 To enable logging, the `loglevel` for incommig and/or outgoing traffic has to be
479 set in *Firewall* -> *Options*. This can be done for the host as well as for the
480 VM/CT firewall individually. By this, logging of {PVE}'s standard firewall rules
481 is enabled and the output can be observed in *Firewall* -> *Log*.
482 Further, only some dropped or rejected packets are logged for the standard rules
483 (see xref:pve_firewall_default_rules[default firewall rules]).
484
485 `loglevel` does not affect how much of the filtered traffic is logged. It
486 changes a `LOGID` appended as prefix to the log output for easier filtering and
487 post-processing.
488
489 `loglevel` is one of the following flags:
490
491 [[pve_firewall_log_levels]]
492 [width="25%", options="header"]
493 |===================
494 | loglevel | LOGID
495 | nolog    | --
496 | emerg    | 0
497 | alert    | 1
498 | crit     | 2
499 | err      | 3
500 | warning  | 4
501 | notice   | 5
502 | info     | 6
503 | debug    | 7
504 |===================
505
506 A typical firewall log output looks like this:
507
508 ----
509 VMID LOGID CHAIN TIMESTAMP POLICY: PACKET_DETAILS
510 ----
511
512 In case of the host firewall, `VMID` is equal to 0.
513
514
515 Logging of user defined firewall rules
516 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
517
518 In order to log packets filtered by user-defined firewall rules, it is possible
519 to set a log-level parameter for each rule individually.
520 This allows to log in a fine grained manner and independent of the log-level
521 defined for the standard rules in *Firewall* -> *Options*.
522
523 While the `loglevel` for each individual rule can be defined or changed easily
524 in the WebUI during creation or modification of the rule, it is possible to set
525 this also via the corresponding `pvesh` API calls.
526
527 Further, the log-level can also be set via the firewall configuration file by
528 appending a `-log <loglevel>` to the selected rule (see
529 xref:pve_firewall_log_levels[possible log-levels]).
530
531 For example, the following two are ident:
532
533 ----
534 IN REJECT -p icmp -log nolog
535 IN REJECT -p icmp
536 ----
537
538 whereas
539
540 ----
541 IN REJECT -p icmp -log debug
542 ----
543
544 produces a log output flagged with the `debug` level.
545
546
547 Tips and Tricks
548 ---------------
549
550 How to allow FTP
551 ~~~~~~~~~~~~~~~~
552
553 FTP is an old style protocol which uses port 21 and several other dynamic ports. So you
554 need a rule to accept port 21. In addition, you need to load the `ip_conntrack_ftp` module.
555 So please run: 
556
557  modprobe ip_conntrack_ftp
558
559 and add `ip_conntrack_ftp` to `/etc/modules` (so that it works after a reboot).
560
561
562 Suricata IPS integration
563 ~~~~~~~~~~~~~~~~~~~~~~~~
564
565 If you want to use the http://suricata-ids.org/[Suricata IPS]
566 (Intrusion Prevention System), it's possible.
567
568 Packets will be forwarded to the IPS only after the firewall ACCEPTed
569 them.
570
571 Rejected/Dropped firewall packets don't go to the IPS.
572
573 Install suricata on proxmox host:
574
575 ----
576 # apt-get install suricata
577 # modprobe nfnetlink_queue  
578 ----
579
580 Don't forget to add `nfnetlink_queue` to `/etc/modules` for next reboot.
581
582 Then, enable IPS for a specific VM with:
583
584 ----
585 # /etc/pve/firewall/<VMID>.fw
586
587 [OPTIONS]
588 ips: 1
589 ips_queues: 0
590 ----
591
592 `ips_queues` will bind a specific cpu queue for this VM.
593
594 Available queues are defined in
595
596 ----
597 # /etc/default/suricata
598 NFQUEUE=0
599 ----
600
601
602 Notes on IPv6
603 -------------
604
605 The firewall contains a few IPv6 specific options. One thing to note is that
606 IPv6 does not use the ARP protocol anymore, and instead uses NDP (Neighbor
607 Discovery Protocol) which works on IP level and thus needs IP addresses to
608 succeed. For this purpose link-local addresses derived from the interface's MAC
609 address are used. By default the `NDP` option is enabled on both host and VM
610 level to allow neighbor discovery (NDP) packets to be sent and received.
611
612 Beside neighbor discovery NDP is also used for a couple of other things, like
613 auto-configuration and advertising routers.
614
615 By default VMs are allowed to send out router solicitation messages (to query
616 for a router), and to receive router advertisement packets. This allows them to
617 use stateless auto configuration. On the other hand VMs cannot advertise
618 themselves as routers unless the ``Allow Router Advertisement'' (`radv: 1`) option
619 is set.
620
621 As for the link local addresses required for NDP, there's also an ``IP Filter''
622 (`ipfilter: 1`) option which can be enabled which has the same effect as adding
623 an `ipfilter-net*` ipset for each of the VM's network interfaces containing the
624 corresponding link local addresses.  (See the
625 <<pve_firewall_ipfilter_section,Standard IP set `ipfilter-net*`>> section for details.)
626
627
628 Ports used by {pve}
629 -------------------
630
631 * Web interface: 8006
632 * VNC Web console: 5900-5999
633 * SPICE proxy: 3128
634 * sshd (used for cluster actions): 22
635 * rpcbind: 111
636 * corosync multicast (if you run a cluster): 5404, 5405 UDP
637
638
639 ifdef::manvolnum[]
640
641 Macro Definitions
642 -----------------
643
644 include::pve-firewall-macros.adoc[]
645
646
647 include::pve-copyright.adoc[]
648
649 endif::manvolnum[]