buildsys: switch upload dist over to buster
[pve-docs.git] / pve-firewall.adoc
index 555e90e..2bcdf6e 100644 (file)
@@ -35,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.
@@ -74,9 +74,9 @@ 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 `]`.
 
 
@@ -404,38 +404,134 @@ 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, logging of traffic filtered by the firewall rules is disabled. To
-enable logging for the default firewall rules, the log-level for incommig and
-outgoing traffic has to be set in the firewall `Options` tab for the host and/or
-the VM/CT firewall.
-Logging of dropped packets is rate limited to 1 packet per second in order to
-reduce output to the log file.
-Further, only some dropped or rejected packets are logged for the standard 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]).
 
-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 particular, each rule is logged independently from the log-level set for the
-standard rules in the firewall `Options`.
+`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.
 
-The log level for the rule can also be set via the firewall configuration file by
-appending a `-log <loglevel>` to the selected rule.
-Here, `<loglevel>` is one of the following flags, attached to the log output:
-`nolog, emerg, alert, crit, err, warning, notice, info, debug`
+`loglevel` is one of the following flags:
 
-For example:
+[[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:
 
 ----
-IN REJECT -p icmp -log nolog
+VMID LOGID CHAIN TIMESTAMP POLICY: PACKET_DETAILS
 ----
 
-is the same as
+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
 ----