Extending the firewall documentation regarding standard rules and logging

[pve-docs.git] / pve-firewall.adoc

diff --git a/pve-firewall.adoc b/pve-firewall.adoc
index 555e90ee6789b38f6c41bf7efe0254a2ce42edac..286c24b47d64fc318a0ed16b9983de6d49103b0c 100644 (file)
--- a/pve-firewall.adoc
+++ b/pve-firewall.adoc
@@ -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
 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.
 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.
 
 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
 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 `]`.
 
 
 name enclosed in `[` and `]`.
 
 


@@ -404,38 +404,130 @@ If you want to see the generated iptables rules you can use:
 
  # iptables-save
 
 
  # 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
 -------------------------
 
 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    | 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:

 
 ----
 
 ----

-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
 ----
 
 IN REJECT -p icmp
 ----