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