From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 924531FF146 for ; Tue, 26 May 2026 16:22:52 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 447122D2A; Tue, 26 May 2026 16:22:49 +0200 (CEST) From: Stefan Hanreich To: pve-devel@lists.proxmox.com Subject: [PATCH pve-docs 1/1] sdn: fabrics: wireguard: add simple example Date: Tue, 26 May 2026 16:22:35 +0200 Message-ID: <20260526142237.370426-1-s.hanreich@proxmox.com> X-Mailer: git-send-email 2.47.3 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1779805339297 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.600 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: BVY2ZZ7ZD7KUZPN2NVXSGZJZ4IRQKKGT X-Message-ID-Hash: BVY2ZZ7ZD7KUZPN2NVXSGZJZ4IRQKKGT 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: Initial feedback has shown that the UI currently is a bit confusing as to which field expects which value. Provide a step-by-step setup guide for a concrete example setup that should cover most basic uses cases. This should help users with setting up WireGuard. In the future, we should provide some kind of wizard or auto-full-meshify feature in order to automate this procedure. Signed-off-by: Stefan Hanreich --- Notes: The referenced screenshots are available in my staff repo (including this commit) on the branch 'wireguard-example'. The commit containing the screenshots has the hash 259e951. pvesdn.adoc | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) diff --git a/pvesdn.adoc b/pvesdn.adoc index f584526..a09a443 100644 --- a/pvesdn.adoc +++ b/pvesdn.adoc @@ -1867,6 +1867,135 @@ If you have configured an external BGP router, the BGP-EVPN routes (10.0.1.0/24 and 10.0.2.0/24 in this example), will be announced dynamically. +[[pvesdn_setup_example_wireguard]] +WireGuard Setup Example +~~~~~~~~~~~~~~~~~~~~~~~ + +The examples assumes a 3-node Proxmox cluster ('sdn1', 'sdn2' and 'sdn3') with +the IP addresses `192.0.2.1`, `192.0.2.2` and `192.0.2.3`, as well as an +external WireGuard peer ('sdn-router') with IP address `192.0.2.10`. + +In this example the Proxmox nodes as well as the external peer will be connected +full-mesh via WireGuard in the `198.51.100.0/24` subnet and additionally the +`203.0.113.0/24` subnet will allowed to be sent via the external WireGuard peer, +`198.51.100.10`. + +Setup WireGuard Fabric +^^^^^^^^^^^^^^^^^^^^^^ + +[thumbnail="screenshot/gui-datacenter-create-fabric-wireguard.png"] + +Click on 'Datacenter' in the left-hand resource tree then navigate to 'SDN' > +'Fabrics' and create new WireGuard fabric by clicking 'Create' and selecting +'WireGuard'. + +Choose a name for the fabric, in this case 'example' has been chosen. + +Setup WireGuard Interfaces +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +[thumbnail="screenshot/gui-datacenter-create-internal-node-wireguard.png"] + +Each participating node requires a WireGuard interface. This can be configured +by adding a new node with type 'Internal' to the WireGuard fabric, selecting the +respective node and then creating a new WireGuard interface. + +On the node itself, two properties can be configured: 'Endpoint' and 'Allowed +IPs'. 'Endpoint' refers to the IP / hostname that will be used for connecting to +this node, `192.0.2.1` in the case of sdn1. Since we do not want to route +additional subnets via this node in our example, leave the 'Allowed IPs' field +empty. + +Create a new WireGuard interface, `wg0`, and configure the IP address that +should be configured on the WireGuard interface, `198.51.100.1/24` in the case +of sdn1. The default listen port is `51820`, but can be manually changed via the +'Listen Port' field. A public / private key pair will be automatically created +for every new WireGuard interface. + +Setup External Node +^^^^^^^^^^^^^^^^^^^ + +[thumbnail="screenshot/gui-datacenter-create-external-node-wireguard.png"] + +In order to add an external node, add another node to the WireGuard fabric, but +select type 'External' in the Node creation dialogue. Enter the public key of +the interface of the external node, as well as the IP / hostname + port that can +be used to reach this external peer (`192.0.2.10:51820` in this example). Add +the IP of the node, `198.51.100.10/32`, as well as the `203.0.113.0/24` subnet +to the allowed IPs field. + +Setup WireGuard Peerings +^^^^^^^^^^^^^^^^^^^^^^^^ + +[thumbnail="screenshot/gui-datacenter-select-peers-wireguard.png"] + +Now that all interfaces and external peers have been set up, they can be +selected as peers in the WireGuard interface configuration. Add the nodes 'sdn2' +and 'sdn3', as well as 'sdn-router' to the peers of the interface `wg0` on node +'sdn1': + +This will generate the following `wg0.conf` file in `/etc/wireguard/proxmox`: + +---- +root@sdn1:~# cat /etc/wireguard/proxmox/wg0.conf +[Interface] +PrivateKey = EpP9R0kqNA1UjGGeDL0/y9Ok66G44dqa2ALYJ0jTWwQ= +ListenPort = 51820 + +[Peer] +PublicKey = xIlHE6ZA25Qnpa+HYT1un3fbjO5/0A9YUbbRmTyLWW4= +AllowedIPs = 198.51.100.10/32, 203.0.113.0/24 +Endpoint = 192.0.2.10:51820 + +[Peer] +PublicKey = CKClJbQ42U1pQM8MqMGCa1IpZbNcqb+OJBxVWJHIrx4= +AllowedIPs = 198.51.100.2/32 +Endpoint = 192.0.2.2:51820 + +[Peer] +PublicKey = gCXBt+n2VNBR6RiUmUxG3+15G0qnXUzsSxEQvmwGMkw= +AllowedIPs = 198.51.100.3/32 +Endpoint = 192.0.2.3:51820 +---- + +There is a `[Peer]` section for each selected peer. The IP configured on the +WireGuard interfaces will be added to the 'Allowed IPs' of a peer as well. + +Verifying the Setup +^^^^^^^^^^^^^^^^^^^ + +Verify connectivity to the other participants in the WireGuard fabric by +pinging: + +---- +root@sdn1:~# ping -c1 198.51.100.2 +PING 198.51.100.2 (198.51.100.2) 56(84) bytes of data. +64 bytes from 198.51.100.2: icmp_seq=1 ttl=64 time=2.08 ms + +--- 198.51.100.2 ping statistics --- +1 packets transmitted, 1 received, 0% packet loss, time 0ms +rtt min/avg/max/mdev = 2.083/2.083/2.083/0.000 ms + + +root@sdn1:~# ping -c1 198.51.100.3 +PING 198.51.100.3 (198.51.100.3) 56(84) bytes of data. +64 bytes from 198.51.100.3: icmp_seq=1 ttl=64 time=2.26 ms + +--- 198.51.100.3 ping statistics --- +1 packets transmitted, 1 received, 0% packet loss, time 0ms +rtt min/avg/max/mdev = 2.255/2.255/2.255/0.000 ms + + +root@sdn1:~# ping -c1 198.51.100.10 +PING 198.51.100.10 (198.51.100.10) 56(84) bytes of data. +64 bytes from 198.51.100.10: icmp_seq=1 ttl=64 time=1.29 ms + +--- 198.51.100.10 ping statistics --- +1 packets transmitted, 1 received, 0% packet loss, time 0ms +rtt min/avg/max/mdev = 1.286/1.286/1.286/0.000 ms +---- + + [[pvesdn_notes]] Notes ----- -- 2.47.3