[pve-devel] [PATCH pve-docs v2 17/17] firewall: add documentation for forward direction

[Hannes Dürr]

On 10/10/24 17:56, Stefan Hanreich wrote:
> Additionally add information about the SDN VNet firewall, which has
> been introduced with this changes.
>
> 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             | 53 ++++++++++++++++++++++++++++++++---
>   4 files changed, 70 insertions(+), 4 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..339a42f 100644
> --- a/pve-firewall.adoc
> +++ b/pve-firewall.adoc
> @@ -52,14 +52,22 @@ The Proxmox VE firewall groups the network into the following logical zones:
>   
>   Host::
>   
> -Traffic from/to a cluster node
> +Traffic from/to a cluster node or traffic forwarded by a cluster node
>   
>   VM::
>   
>   Traffic from/to a specific VM
>   
> -For each zone, you can define firewall rules for incoming and/or
> -outgoing traffic.
> +VNet::
> +
> +Traffic flowing through a SDN VNet
> +
> +For each zone, you can define firewall rules for incoming, outgoing or
> +forwarded traffic.

This is not really true, I can not create rules on the forward chain of 
VMs, can I?

I think the "Zones" section could benefit from some rewording because 
IMO the Zone representation is not really fitting and also in the rest 
of the article we are talking about 'Levels' and not 'Zones'.
I'd propose something like this:

Firewall rules can be created on 4 levels, Cluster, Node, Vnet, VM. 
However, the Rules only act on the 3 levels Node, Vnet and VM.
The reason for this is the distributed architecture: if a firewall rule 
is created at cluster level, it gets rolled out to all hosts and acts at 
host level.

At host level the rules can act on and manipulate traffic from/into the 
host. With the new proxmox-firewall based on nftables it is additionally 
possible to create rules that act on and manipulate traffic passing 
trough the host (forwarded).

The Vnet level is only available with the new proxmox-firewall. At Vnet 
level the rules can act on and manipulate traffic passing through the 
Vnet (forwarded).

At VM level the rules can act on and manipulate traffic from/into a VM.

> +
> +IMPORTANT: Creating rules for forwarded traffic or on a VNet-level is currently
> +only possible when using the new
> +xref:pve_firewall_nft[nftables-based proxmox-firewall].
>   
>   
>   Configuration Files
> @@ -202,10 +210,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 +683,7 @@ Ports used by {pve}
>   * live migration (VM memory and local-disk data): 60000-60050 (TCP)
Here I'd also add that it is dependent on the Level the Rule is applied to.
>   
>   
> +[[pve_firewall_nft]]
>   nftables
>   --------
>