From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id 85F531FF146 for ; Tue, 12 May 2026 19:35:38 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 3D44D1D73A; Tue, 12 May 2026 19:33:05 +0200 (CEST) From: Stefan Hanreich To: pve-devel@lists.proxmox.com Subject: [PATCH pve-docs v5 29/29] sdn: fabrics: add section about wireguard Date: Tue, 12 May 2026 19:31:44 +0200 Message-ID: <20260512173145.596958-30-s.hanreich@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260512173145.596958-1-s.hanreich@proxmox.com> References: <20260512173145.596958-1-s.hanreich@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1778607004888 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.615 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: W3JU2UHIUUPH2HB5M2HRKGIVIWGQU3XM X-Message-ID-Hash: W3JU2UHIUUPH2HB5M2HRKGIVIWGQU3XM X-MailFrom: s.hanreich@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Signed-off-by: Stefan Hanreich --- pvesdn.adoc | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/pvesdn.adoc b/pvesdn.adoc index d20a0eb..1e83495 100644 --- a/pvesdn.adoc +++ b/pvesdn.adoc @@ -769,6 +769,106 @@ NOTE: The dummy interface will automatically be configured as `passive`. Every interface which doesn't have an ip-address configured will be treated as a `point-to-point` link. +[[pvesdn_wireguard]] +WireGuard +~~~~~~~~~ + +WireGuard can be used for establishing a VPN between Proxmox VE nodes and / or +external nodes. It does not provide dynamic routing by itself, but can be used +in conjunction with dynamic routing protocols operating on layer 3 and above +(OSPF, BGP) to provide a dynamically routed, encrypted transport for e.g. EVPN +or VXLAN. + +NOTE: In order to use WireGuard, the package `wireguard-tools` needs to be +installed. + +Configuration options: + +[[pvesdn_wireguard_fabric]] +On the Fabric +^^^^^^^^^^^^^ + +Name:: This is the name of the WireGuard fabric and can be at most 8 characters +long. + +Persistent Keepalive:: If this is set, then WireGuard will send an empty +authenticated packet every N seconds to each configured peer. This can help +keeping connections alive when using stateful firewalls or NAT. + +[[pvesdn_wireguard_node]] +On the Node +^^^^^^^^^^^ + +There are two types of nodes: internal and external. Internal nodes are Proxmox +VE nodes, external nodes everything else. They are essentially reusable peer +definitions that can be used across the whole cluster. + +.Internal + +Endpoint:: This is the IP or hostname that other Proxmox VE nodes should use for +connecting to this Proxmox VE node. This is used as the endpoint when +configuring this Proxmox VE node as a peer. + +Allowed IPs:: A comma-separated list of IP addresses. When selecting this node +as a peer on other nodes, then this is used as the `AllowedIPs` setting in the +WireGuard peer configuration. They specify the addresses that are allowed for +incoming and outgoing traffic from/to this node. + +.External + +Name:: The name of the external node. + +Public Key:: The public key used by the external node. + +Endpoint:: The endpoint which is used for connecting to this external peer (e.g. +192.0.2.1:51820). + +Allowed IPs:: A comma-separated list of IP addresses. When selecting this node +as a peer on other nodes, then this is used as the `AllowedIPs` setting in the +WireGuard peer configuration. They specify the addresses that are allowed for +incoming and outgoing traffic from/to this node. + +[[pvesdn_wireguard_interface]] +On The Interface +^^^^^^^^^^^^^^^^ + +Name:: The name of the network interface on the Linux host. At most 8 +alphanumerical characters + hyphens. + +IP::: The IPv4 address that should be configured on this interface. + +IPv6::: The IPv6 address that should be configured on this interface. + +Listen Port:: The listening port for this interface. + +Peers:: A list of peers that should be configured for that interface. All nodes +that are part of the fabric can be selected as peers - the peer definition will +be auto-generated from the configuration in the node. + +When defining an interface, then Proxmox VE automatically generates a public key +for that interface in `/etc/pve/priv/wg-keys.conf` upon saving the interface. +The public key can then be inspected in the Web UI when editing the node. +Deleting an interface and re-applying the SDN configuration will delete the +private key again. + +The fabric will also automatically generate routes for every allowed IP of every +peer. E.g. if an interface wg0 has two peers with 198.51.100.0/24 and +203.0.113.0/24 as allowed IPs, then routes for both subnets will be +automatically created. If the peer is the interface of a Proxmox VE node, then +the configured IP address will also be automatically added to the Allowed IPs in +the peer configuration (e.g. if the other node has 192.0.2.10/24 as IP config, +then 192.0.2.10/32 will be added to the allowed IPs). + + +[[pvesdn_wireguard_interface]] +On The Peer +^^^^^^^^^^^ + +Skip Route Generation:: The fabric will autogenerate routes in the kernel +routing table for all allowed IPs of a peer. By setting this option, no routes +will be inserted into the kernel routing table. + + [[pvesdn_config_ipam]] IPAM ---- -- 2.47.3