buildsys: switch upload dist over to buster
[pve-docs.git] / pve-firewall.adoc
index a7c9d24..2bcdf6e 100644 (file)
@@ -1,7 +1,8 @@
+[[chapter_pve_firewall]]
 ifdef::manvolnum[]
-PVE({manvolnum})
-================
-include::attributes.txt[]
+pve-firewall(8)
+===============
+:pve-toplevel:
 
 NAME
 ----
@@ -9,7 +10,7 @@ NAME
 pve-firewall - PVE Firewall Daemon
 
 
-SYNOPSYS
+SYNOPSIS
 --------
 
 include::pve-firewall.8-synopsis.adoc[]
@@ -18,12 +19,14 @@ include::pve-firewall.8-synopsis.adoc[]
 DESCRIPTION
 -----------
 endif::manvolnum[]
-
 ifndef::manvolnum[]
 {pve} Firewall
 ==============
-include::attributes.txt[]
+:pve-toplevel:
 endif::manvolnum[]
+ifdef::wiki[]
+:title: Firewall
+endif::wiki[]
 
 {pve} Firewall provides an easy way to protect your IT
 infrastructure. You can setup firewall rules for all hosts
@@ -32,7 +35,7 @@ containers. Features like firewall macros, security groups, IP sets
 and aliases help to make that task easier.
 
 While all configuration is stored on the cluster file system, the
-`iptables`-based firewall runs on each cluster node, and thus provides
+`iptables`-based firewall service runs on each cluster node, and thus provides
 full isolation between virtual machines. The distributed nature of
 this system also provides much higher bandwidth than a central
 firewall solution.
@@ -71,12 +74,13 @@ You can configure anything using the GUI (i.e. *Datacenter* -> *Firewall*,
 or on a *Node* -> *Firewall*), or you can edit the configuration files
 directly using your preferred editor.
 
-Firewall configuration files contains sections of key-value
+Firewall configuration files contain sections of key-value
 pairs. Lines beginning with a `#` and blank lines are considered
-comments. Sections starts with a header line containing the section
+comments. Sections start with a header line containing the section
 name enclosed in `[` and `]`.
 
 
+[[pve_firewall_cluster_wide_setup]]
 Cluster Wide Setup
 ~~~~~~~~~~~~~~~~~~
 
@@ -139,6 +143,7 @@ To simplify that task, you can instead create an IPSet called
 firewall rules to access the GUI from remote.
 
 
+[[pve_firewall_host_specific_configuration]]
 Host Specific Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -160,7 +165,7 @@ include::pve-firewall-host-opts.adoc[]
 
 This sections contains host specific firewall rules.
 
-
+[[pve_firewall_vm_container_configuration]]
 VM/Container Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -196,10 +201,6 @@ Each virtual network device has its own firewall enable flag. So you
 can selectively enable the firewall for each interface. This is
 required in addition to the general firewall `enable` option.
 
-The firewall requires a special network device setup, so you need to
-restart the VM/container after enabling the firewall on a network
-interface.
-
 
 Firewall Rules
 --------------
@@ -230,8 +231,8 @@ Here are some examples:
 IN SSH(ACCEPT) -i net0
 IN SSH(ACCEPT) -i net0 # a comment
 IN SSH(ACCEPT) -i net0 -source 192.168.2.192 # only allow SSH from 192.168.2.192
-IN SSH(ACCEPT) -i net0 -source 10.0.0.1-10.0.0.10 # accept SSH for ip range
-IN SSH(ACCEPT) -i net0 -source 10.0.0.1,10.0.0.2,10.0.0.3 #accept ssh for ip list
+IN SSH(ACCEPT) -i net0 -source 10.0.0.1-10.0.0.10 # accept SSH for IP range
+IN SSH(ACCEPT) -i net0 -source 10.0.0.1,10.0.0.2,10.0.0.3 #accept ssh for IP list
 IN SSH(ACCEPT) -i net0 -source +mynetgroup # accept ssh for ipset mynetgroup
 IN SSH(ACCEPT) -i net0 -source myserveralias #accept ssh for alias myserveralias
 
@@ -242,6 +243,7 @@ OUT ACCEPT # accept all outgoing packages
 ----
 
 
+[[pve_firewall_security_groups]]
 Security Groups
 ---------------
 
@@ -266,7 +268,7 @@ Then, you can add this group to a VM's firewall
 GROUP webserver
 ----
 
-
+[[pve_firewall_ip_aliases]]
 IP Aliases
 ----------
 
@@ -301,10 +303,10 @@ explicitly assign the local IP address
 ----
 #  /etc/pve/firewall/cluster.fw
 [ALIASES]
-local_network 1.2.3.4 # use the single ip address
+local_network 1.2.3.4 # use the single IP address
 ----
 
-
+[[pve_firewall_ip_sets]]
 IP Sets
 -------
 
@@ -352,7 +354,7 @@ Traffic from these IPs is dropped by every host's and VM's firewall.
 ----
 
 
-[[ipfilter-section]]
+[[pve_firewall_ipfilter_section]]
 Standard IP set `ipfilter-net*`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -402,6 +404,145 @@ If you want to see the generated iptables rules you can use:
 
  # iptables-save
 
+[[pve_firewall_default_rules]]
+Default firewall rules
+----------------------
+
+The following traffic is filtered by the default firewall configuration:
+
+Datacenter incoming/outgoing DROP/REJECT
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the input or output policy for the firewall is set to DROP or REJECT, the
+following traffic is still allowed for all {pve} hosts in the cluster:
+
+* traffic over the loopback interface
+* already established connections
+* traffic using the IGMP protocol
+* TCP traffic from management hosts to port 8006 in order to allow access to
+  the web interface
+* TCP traffic from management hosts to the port range 5900 to 5999 allowing
+  traffic for the VNC web console
+* TCP traffic from management hosts to port 3128 for connections to the SPICE
+  proxy
+* TCP traffic from management hosts to port 22 to allow ssh access
+* UDP traffic in the cluster network to port 5404 and 5405 for corosync
+* UDP multicast traffic in the cluster network
+* ICMP traffic type 3 (Destination Unreachable), 4 (congestion control) or 11
+  (Time Exceeded)
+
+The following traffic is dropped, but not logged even with logging enabled:
+
+* TCP connections with invalid connection state
+* Broadcast, multicast and anycast traffic not related to corosync, i.e., not
+  coming through port 5404 or 5405
+* TCP traffic to port 43
+* UDP traffic to ports 135 and 445
+* UDP traffic to the port range 137 to 139
+* UDP traffic form source port 137 to port range 1024 to 65535
+* UDP traffic to port 1900
+* TCP traffic to port 135, 139 and 445
+* UDP traffic originating from source port 53
+
+The rest of the traffic is dropped or rejected, respectively, and also logged.
+This may vary depending on the additional options enabled in
+*Firewall* -> *Options*, such as NDP, SMURFS and TCP flag filtering.
+
+[[pve_firewall_iptables_inspect]]
+Please inspect the output of the
+
+----
+ # iptables-save
+----
+
+system command to see the firewall chains and rules active on your system.
+This output is also included in a `System Report`, accessible over a node's
+subscription tab in the web GUI, or through the `pvereport` command line tool.
+
+VM/CT incoming/outgoing DROP/REJECT
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This drops or rejects all the traffic to the VMs, with some exceptions for
+DHCP, NDP, Router Advertisement, MAC and IP filtering depending on the set
+configuration.  The same rules for dropping/rejecting packets are inherited
+from the datacenter, while the exceptions for accepted incomming/outgoing
+traffic of the host do not apply.
+
+Again, you can use xref:pve_firewall_iptables_inspect[iptables-save (see above)]
+to inspect all rules and chains applied.
+
+Logging of firewall rules
+-------------------------
+
+By default, all logging of traffic filtered by the firewall rules is disabled.
+To enable logging, the `loglevel` for incommig and/or outgoing traffic has to be
+set in *Firewall* -> *Options*. This can be done for the host as well as for the
+VM/CT firewall individually. By this, logging of {PVE}'s standard firewall rules
+is enabled and the output can be observed in *Firewall* -> *Log*.
+Further, only some dropped or rejected packets are logged for the standard rules
+(see xref:pve_firewall_default_rules[default firewall rules]).
+
+`loglevel` does not affect how much of the filtered traffic is logged. It
+changes a `LOGID` appended as prefix to the log output for easier filtering and
+post-processing.
+
+`loglevel` is one of the following flags:
+
+[[pve_firewall_log_levels]]
+[width="25%", options="header"]
+|===================
+| loglevel | LOGID
+| nolog    | --
+| emerg    | 0
+| alert    | 1
+| crit     | 2
+| err      | 3
+| warning  | 4
+| notice   | 5
+| info     | 6
+| debug    | 7
+|===================
+
+A typical firewall log output looks like this:
+
+----
+VMID LOGID CHAIN TIMESTAMP POLICY: PACKET_DETAILS
+----
+
+In case of the host firewall, `VMID` is equal to 0.
+
+
+Logging of user defined firewall rules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to log packets filtered by user-defined firewall rules, it is possible
+to set a log-level parameter for each rule individually.
+This allows to log in a fine grained manner and independent of the log-level
+defined for the standard rules in *Firewall* -> *Options*.
+
+While the `loglevel` for each individual rule can be defined or changed easily
+in the WebUI during creation or modification of the rule, it is possible to set
+this also via the corresponding `pvesh` API calls.
+
+Further, the log-level can also be set via the firewall configuration file by
+appending a `-log <loglevel>` to the selected rule (see
+xref:pve_firewall_log_levels[possible log-levels]).
+
+For example, the following two are ident:
+
+----
+IN REJECT -p icmp -log nolog
+IN REJECT -p icmp
+----
+
+whereas
+
+----
+IN REJECT -p icmp -log debug
+----
+
+produces a log output flagged with the `debug` level.
+
 
 Tips and Tricks
 ---------------
@@ -469,7 +610,7 @@ address are used. By default the `NDP` option is enabled on both host and VM
 level to allow neighbor discovery (NDP) packets to be sent and received.
 
 Beside neighbor discovery NDP is also used for a couple of other things, like
-autoconfiguration and advertising routers.
+auto-configuration and advertising routers.
 
 By default VMs are allowed to send out router solicitation messages (to query
 for a router), and to receive router advertisement packets. This allows them to
@@ -481,7 +622,7 @@ As for the link local addresses required for NDP, there's also an ``IP Filter''
 (`ipfilter: 1`) option which can be enabled which has the same effect as adding
 an `ipfilter-net*` ipset for each of the VM's network interfaces containing the
 corresponding link local addresses.  (See the
-<<ipfilter-section,Standard IP set `ipfilter-net*`>> section for details.)
+<<pve_firewall_ipfilter_section,Standard IP set `ipfilter-net*`>> section for details.)
 
 
 Ports used by {pve}