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 7398A1FF09C for ; Mon, 02 Nov 2026 16:21:07 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id ADBB421C1E; Mon, 02 Nov 2026 16:19:47 +0100 (CET) From: Hannes Laimer To: pve-devel@lists.proxmox.com Subject: [PATCH pve-docs v5 15/15] sdn: dhcp: add eBPF backend section Date: Mon, 2 Nov 2026 16:18:42 +0100 Message-ID: <20261102151842.1605234-16-h.laimer@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261102151842.1605234-1-h.laimer@proxmox.com> References: <20261102151842.1605234-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: 1793632741660 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.190 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: YIC5P2OCT2I7V4LZM347PJ6E6UK5VNZU X-Message-ID-Hash: YIC5P2OCT2I7V4LZM347PJ6E6UK5VNZU 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 --- Notes: v5: * DHCP ranges only limit the allocation, both backends answer every mapping * an edited mapping reaches the guest at its next renewal, a forced reacquire is only needed with infinite leases pvesdn.adoc | 127 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 98 insertions(+), 29 deletions(-) diff --git a/pvesdn.adoc b/pvesdn.adoc index 3fd3533ad07f..b5358ceedbca 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 @@ -1262,10 +1277,13 @@ update and delete IP mappings. This is particularly convenient in conjunction with the xref:pvesdn_config_dhcp[DHCP feature]. If you are using DHCP, you can use the IPAM panel to create or edit leases for -specific VMs, which enables you to change the IPs allocated via DHCP. When -editing an IP of a VM that is using DHCP you must make sure to force the guest -to acquire a new DHCP leases. This can usually be done by reloading the network -stack of the guest or rebooting it. +specific VMs, which enables you to change the IPs allocated via DHCP. + +A guest picks up an edited IP when it next renews its DHCP lease. With an +infinite lease, the default of the `dnsmasq` backend, the guest never renews. +Then you have to make it acquire a new lease, for example by reloading its +network stack or rebooting it. The subnet option *DHCP Lease Time* sets a +finite lease time, see xref:pvesdn_config_subnet[Subnets]. [[pvesdn_ipam_plugin_netbox]] NetBox IPAM Plugin @@ -1342,9 +1360,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. +for a Zone. It provides DHCP for all Subnets in a Zone. 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,16 +1380,18 @@ 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 -select the Subnet for which you want to configure DHCP ranges. In the edit -dialogue you can configure DHCP ranges in the respective Tab. Alternatively you -can set DHCP ranges for a Subnet via the following CLI command: +After automatic DHCP has been enabled for a Zone, you can configure DHCP Ranges +for its subnets to limit which IPs get allocated. To do that, go to the Vnets +panel and select the Subnet for which you want to configure DHCP ranges. In the +edit dialogue you can configure DHCP ranges in the respective Tab. Alternatively +you can set DHCP ranges for a Subnet via the following CLI command: ---- pvesh set /cluster/sdn/vnets//subnets/ @@ -1379,22 +1399,26 @@ 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 then allocates IPs in the IPAM only in the configured ranges. +A subnet without ranges gets IPs allocated from its whole address range. The +ranges only limit the allocation. Both backends answer every mapping in the +Zone, including mappings outside the ranges. -The DHCP plugin will then allocate IPs in the IPAM only in the configured -ranges. +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. -Do not forget to follow the installation steps for the -xref:pvesdn_install_dhcp_ipam[dnsmasq DHCP plugin] as well. +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 +1461,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