From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id 845281FF0C0 for ; Wed, 21 Oct 2026 10:48:25 +0200 (CEST) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 133A02186B; Wed, 21 Oct 2026 10:45:55 +0200 (CEST) From: Hannes Laimer To: pve-devel@lists.proxmox.com Subject: [PATCH pve-docs v4 20/20] sdn: dhcp: add eBPF backend section Date: Wed, 21 Oct 2026 10:44:45 +0200 Message-ID: <20261021084445.462195-21-h.laimer@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261021084445.462195-1-h.laimer@proxmox.com> References: <20261021084445.462195-1-h.laimer@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1792572322950 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.202 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) POISEN_SPAM_PILL 0.1 Meta: its spam POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust 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: IZURH57J55OX67MDDMMSMZAA6L6JOPQF X-Message-ID-Hash: IZURH57J55OX67MDDMMSMZAA6L6JOPQF X-MailFrom: h.laimer@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: Hannes Laimer --- pvesdn.adoc | 101 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 83 insertions(+), 18 deletions(-) diff --git a/pvesdn.adoc b/pvesdn.adoc index 3fd3533..ec5c500 100644 --- a/pvesdn.adoc +++ b/pvesdn.adoc @@ -98,10 +98,12 @@ source /etc/network/interfaces.d/* DHCP IPAM ~~~~~~~~~ -The DHCP integration into the built-in 'PVE' IP Address Management stack -currently uses `dnsmasq` for giving out DHCP leases. This is currently opt-in. +The DHCP integration into the built-in 'PVE' IP Address Management stack gives +out leases either through `dnsmasq` or through an eBPF backend built into +{pve}. Each zone selects its backend, and DHCP is opt-in per zone. -To use that feature you need to install the `dnsmasq` package on every node: +The eBPF backend needs no additional package. To use the `dnsmasq` backend you +need to install the `dnsmasq` package on every node: ---- apt update @@ -153,9 +155,8 @@ in your SDN setup. * xref:pvesdn_config_controllers[Controllers]: For controlling layer 3 routing in complex setups -* xref:pvesdn_config_dhcp[DHCP]: Define a DHCP server for a zone that - automatically allocates IPs for guests in the IPAM and leases them to the - guests via DHCP. +* xref:pvesdn_config_dhcp[DHCP]: Let a zone automatically allocate IPs for + guests in the IPAM and lease them to the guests via DHCP. * xref:pvesdn_config_ipam[IPAM]: Enables external for IP address management for guests @@ -229,6 +230,11 @@ DNSZone:: DNS domain name. Used to register hostnames, such as `.`. The DNS zone must already exist on the DNS server. Optional. +DHCP Backend:: Hand out leases to the zone's guests through this backend, see + xref:pvesdn_config_dhcp[DHCP]. The `dnsmasq` backend is only available for + Simple Zones. The `ebpf` backend works with every zone type. Optional, + defaults to none, which disables DHCP. + [[pvesdn_zone_plugin_simple]] Simple Zones @@ -442,6 +448,15 @@ SNAT:: Enable Source NAT which allows VMs from inside a DNS Zone Prefix:: Add a prefix to the domain registration, like .prefix. Optional. +DHCP DNS Server:: The DNS server handed out to guests with their lease. + Optional. + +DHCP Lease Time:: The lease time in seconds, at least 60. A guest picks up a + changed mapping when it renews its lease, so a shorter lease time applies + changes sooner. Without it `dnsmasq` hands out infinite leases and the `ebpf` + backend ten-minute leases. `dnsmasq` raises anything below two minutes to + two minutes. Optional. + [[pvesdn_config_controllers]] Controllers @@ -1343,8 +1358,9 @@ DHCP The DHCP plugin in {pve} SDN can be used to automatically deploy a DHCP server for a Zone. It provides DHCP for all Subnets in a Zone that have a DHCP range -configured. Currently the only available backend plugin for DHCP is the dnsmasq -plugin. +configured. Each zone selects one of two backend plugins, `dnsmasq` or `ebpf`. +Both answer from the MAC address and IP mappings in the IPAM. The `ebpf` +backend serves IPv4 subnets only. The DHCP plugin works by allocating an IP in the IPAM plugin configured in the Zone when adding a new network interface to a VM/CT. You can find more @@ -1362,10 +1378,12 @@ available when using the xref:pvesdn_ipam_plugin_pveipam[PVE IPAM plugin]. Configuration ~~~~~~~~~~~~~ -You can enable automatic DHCP for a zone in the Web UI via the Zones panel and -enabling DHCP in the advanced options of a zone. +You can enable automatic DHCP for a zone in the web interface via the Zones +panel by selecting a backend in the *DHCP Backend* field of the zone's advanced +options. -NOTE: Currently only Simple Zones have support for automatic DHCP +NOTE: The `dnsmasq` backend is only available for Simple Zones. The `ebpf` +backend works with every zone type. After automatic DHCP has been enabled for a Zone, DHCP Ranges need to be configured for the subnets in a Zone. In order to that, go to the Vnets panel and @@ -1379,22 +1397,24 @@ pvesh set /cluster/sdn/vnets//subnets/ -dhcp-range start-address=10.0.2.100,end-address=10.0.2.200 ---- -You also need to have a gateway configured for the subnet - otherwise -automatic DHCP will not work. - The DHCP plugin will then allocate IPs in the IPAM only in the configured ranges. -Do not forget to follow the installation steps for the -xref:pvesdn_install_dhcp_ipam[dnsmasq DHCP plugin] as well. +The `dnsmasq` backend needs a gateway on the subnet. The `ebpf` backend also +serves a subnet without one, but then hands out no default route. + +The subnet options *DHCP DNS Server* and *DHCP Lease Time* set the DNS server +and the lease time handed out, see xref:pvesdn_config_subnet[Subnets]. + +When using the `dnsmasq` backend, do not forget to follow the installation +steps for the xref:pvesdn_install_dhcp_ipam[dnsmasq DHCP plugin] as well. Plugins ~~~~~~~ Dnsmasq Plugin ^^^^^^^^^^^^^^ -Currently this is the only DHCP plugin and therefore the plugin that gets used -when you enable DHCP for a zone. +This plugin serves zones with `dnsmasq` as their DHCP backend. .Installation For installation see the xref:pvesdn_install_dhcp_ipam[DHCP IPAM] section. @@ -1437,6 +1457,51 @@ For more information please consult the documentation of xref:pvesdn_ipam_plugin_pveipam[the PVE IPAM plugin]. Changing DHCP leases is currently not supported for the other IPAM plugins. +[[pvesdn_dhcp_plugin_ebpf]] +eBPF Plugin +^^^^^^^^^^^ +This plugin serves zones with `ebpf` as their DHCP backend. + +.Installation +The backend needs no additional package. It requires host kernel version 6.6 +or newer. + +Instead of a DHCP server on the bridge, the backend attaches a small eBPF +program to the network interface of every guest on the zone's VNets. The +program answers the guest's DHCP requests from the MAC address and IP mapping +in the IPAM, so these requests never reach the bridge. It only answers +requests that carry the MAC address of its own network interface. Requests on +a network interface without a mapping pass through untouched, so such a guest +can still reach another DHCP server on the network. + +The backend attaches the program when a guest starts or a network interface +is hot-plugged. Applying the SDN configuration attaches it to running guests +as well, so a zone switched to `ebpf` serves them without a restart. + +A mapping changed through {pve} reaches a running guest when it next renews +its lease. After a mapping is deleted, the backend stops answering the guest, +which keeps its address until the lease runs out. + +The answer carries the address, netmask, lease time, and server address. The +zone's MTU, the subnet's gateway, and its IPv4 DNS server are included where +the zone or subnet has one. Options `dnsmasq` can add through its custom +configuration, such as a domain name or PXE boot parameters, are not +available. + +.Notes +The backend serves IPv4 only. Only untagged requests are answered, so a guest +tagging its own traffic, for example on a trunk port, is not served. A guest +with a mapping cannot use another DHCP server on the network, since its +requests never leave its network interface. Clients behind a guest, such as +containers bridged inside a VM, get no answer, and neither does a guest that +changed its MAC address in the guest OS. + +NOTE: Requests this backend answers never reach the firewall of the guest's +network interface, so the guest's firewall rules and the DHCP option of its +firewall have no effect on them. The rate limit applies to the reply only. +Requests the backend does not answer pass the firewall and the rate limit as +usual. + [[pvesdn_firewall_integration]] Firewall Integration -------------------- -- 2.47.3