[pve-devel] [PATCH pve-docs v4 18/18] firewall: add documentation for forward direction and vnet zone

[Stefan Hanreich]

Added a new direction section, mostly so I can write about the forward
direction and explain its use cases.

Signed-off-by: Stefan Hanreich <s.hanreich at proxmox.com>
---
 Makefile                      |  1 +
 gen-pve-firewall-vnet-opts.pl | 12 +++++
 pve-firewall-vnet-opts.adoc   |  8 +++
 pve-firewall.adoc             | 98 ++++++++++++++++++++++++++++++++---
 4 files changed, 112 insertions(+), 7 deletions(-)
 create mode 100755 gen-pve-firewall-vnet-opts.pl
 create mode 100644 pve-firewall-vnet-opts.adoc

diff --git a/Makefile b/Makefile
index 801a2a3..f30d77a 100644
--- a/Makefile
+++ b/Makefile
@@ -62,6 +62,7 @@ GEN_SCRIPTS=					\
 	gen-pve-firewall-macros-adoc.pl		\
 	gen-pve-firewall-rules-opts.pl		\
 	gen-pve-firewall-vm-opts.pl		\
+	gen-pve-firewall-vnet-opts.pl		\
 	gen-output-format-opts.pl
 
 API_VIEWER_FILES=							\
diff --git a/gen-pve-firewall-vnet-opts.pl b/gen-pve-firewall-vnet-opts.pl
new file mode 100755
index 0000000..c9f4f13
--- /dev/null
+++ b/gen-pve-firewall-vnet-opts.pl
@@ -0,0 +1,12 @@
+#!/usr/bin/perl
+
+use lib '.';
+use strict;
+use warnings;
+
+use PVE::Firewall;
+use PVE::RESTHandler;
+
+my $prop = $PVE::Firewall::vnet_option_properties;
+
+print PVE::RESTHandler::dump_properties($prop);
diff --git a/pve-firewall-vnet-opts.adoc b/pve-firewall-vnet-opts.adoc
new file mode 100644
index 0000000..ed1e88f
--- /dev/null
+++ b/pve-firewall-vnet-opts.adoc
@@ -0,0 +1,8 @@
+`enable`: `<boolean>` ('default =' `0`)::
+
+Enable/disable firewall rules.
+
+`policy_forward`: `<ACCEPT | DROP>` ::
+
+Forward policy.
+
diff --git a/pve-firewall.adoc b/pve-firewall.adoc
index b428703..47ab3d3 100644
--- a/pve-firewall.adoc
+++ b/pve-firewall.adoc
@@ -45,21 +45,68 @@ transparent, and we filter traffic for both protocols by default. So
 there is no need to maintain a different set of rules for IPv6.
 
 
+Directions & Zones
+------------------
+
+The Proxmox VE firewall groups the network into multiple logical zones. You can
+define rules for each zone independently. Depending on the zone, you can define
+rules for incoming, outgoing or forwarded traffic.
+
+
+Directions
+~~~~~~~~~~
+
+There are 3 directions that you can choose from when defining rules for a zone:
+
+In::
+
+Traffic that is arriving in a zone.
+
+Out::
+
+Traffic that is leaving a zone.
+
+Forward::
+
+Traffic that is passing through a zone. In the host zone this can be routed
+traffic (when the host is acting as a gateway or performing NAT). At a
+VNet-level this affects all traffic that is passing by a VNet, including
+traffic from/to bridged network interfaces.
+
+
+IMPORTANT: Creating rules for forwarded traffic is currently only possible when
+using the new xref:pve_firewall_nft[nftables-based proxmox-firewall]. Any
+forward rules will be ignored by the stock `pve-firewall` and have no effect!
+
+
 Zones
------
+~~~~~
 
-The Proxmox VE firewall groups the network into the following logical zones:
+There are 3 different zones that you can define firewall rules for:
 
 Host::
 
-Traffic from/to a cluster node
+Traffic going from/to a host, or traffic that is forwarded by a host.
+You can define rules for this zone either at the datacenter level or at the host
+level. Rules at host level take precedence over rules at datacenter level.
 
 VM::
 
-Traffic from/to a specific VM
+Traffic going from/to a VM or CT.
+You cannot define rules for forwarded traffic, only for incoming / outgoing
+traffic.
+
+VNet::
+
+Traffic passing through a SDN VNet, either from guest to guest or from host to
+guest and vice-versa.
+Since this traffic is always forwarded traffic, it is only possible to create
+rules with direction forward.
 
-For each zone, you can define firewall rules for incoming and/or
-outgoing traffic.
+
+IMPORTANT: Creating rules on a VNet-level is currently only possible when using
+the new xref:pve_firewall_nft[nftables-based proxmox-firewall]. Any VNet-level
+rules will be ignored by the stock `pve-firewall` and have no effect!
 
 
 Configuration Files
@@ -202,10 +249,46 @@ can selectively enable the firewall for each interface. This is
 required in addition to the general firewall `enable` option.
 
 
+[[pve_firewall_vnet_configuration]]
+VNet Configuration
+~~~~~~~~~~~~~~~~~~
+VNet related configuration is read from:
+
+ /etc/pve/sdn/firewall/<vnet_name>.fw
+
+This can be used for setting firewall configuration globally on a VNet level,
+without having to set firewall rules for each VM inside the VNet separately. It
+can only contain rules for the `FORWARD` direction, since there is no notion of
+incoming or outgoing traffic. This affects all traffic travelling from one
+bridge port to another, including the host interface.
+
+WARNING: This feature is currently only available for the new
+xref:pve_firewall_nft[nftables-based proxmox-firewall]
+
+Since traffic passing the `FORWARD` chain is bi-directional, you need to create
+rules for both directions if you want traffic to pass both ways. For instance if
+HTTP traffic for a specific host should be allowed, you would need to create the
+following rules:
+
+----
+FORWARD ACCEPT -dest 10.0.0.1 -dport 80
+FORWARD ACCEPT -source 10.0.0.1 -sport 80
+----
+
+`[OPTIONS]`::
+
+This is used to set VNet related firewall options.
+
+include::pve-firewall-vnet-opts.adoc[]
+
+`[RULES]`::
+
+This section contains VNet specific firewall rules.
+
 Firewall Rules
 --------------
 
-Firewall rules consists of a direction (`IN` or `OUT`) and an
+Firewall rules consists of a direction (`IN`, `OUT` or `FORWARD`) and an
 action (`ACCEPT`, `DENY`, `REJECT`). You can also specify a macro
 name. Macros contain predefined sets of rules and options. Rules can be
 disabled by prefixing them with `|`.
@@ -639,6 +722,7 @@ Ports used by {pve}
 * live migration (VM memory and local-disk data): 60000-60050 (TCP)
 
 
+[[pve_firewall_nft]]
 nftables
 --------
 
-- 
2.39.5