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