[pve-devel] [PATCH docs] Extending the firewall documentation regarding standard rules and logging

[Christian Ebner]

Signed-off-by: Christian Ebner <c.ebner at proxmox.com>
---
 pve-firewall.adoc | 123 ++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 110 insertions(+), 13 deletions(-)

diff --git a/pve-firewall.adoc b/pve-firewall.adoc
index 0781334..286c24b 100644
--- a/pve-firewall.adoc
+++ b/pve-firewall.adoc
@@ -404,28 +404,125 @@ 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 incomming/outgoing DROP/REJECT
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the input/output policy for the firewall is set to DROP/REJECT, the following
+traffic is still allowed for the host:
+
+* 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,4 or 11
+
+The following traffic is dropped, but not logged even with logging enabled:
+
+* tcp connections with invalid connection state
+* Broad-, multi- and anycast traffic not related to corosync
+* 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/rejected and logged.
+This may vary depending on the additional options enabled in
+*Firewall* -> *Options*, such as NDP, SMURFS and TCP flag filtering.
+
+Please inspect the output of
+
+ # iptables-save
+
+to see the firewall chains and rules active on your system.
+
+VM/CT incomming/outgoing DROP/REJECT
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This drops/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, please inspect the output of
+
+ # iptables-save
+
+to see in detail the firewall chains and rules active for the VMs/CTs.
+
 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]).
+
+`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    | no log
+| 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.
 
-// TODO: describe standard/default rules and note which of them get logged
+
+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 the firewall `Options`.
+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.
 
-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:
-`nolog, emerg, alert, crit, err, warning, notice, info, debug`
+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:
 
-- 
2.11.0