[PATCH pve-docs v5 15/15] sdn: dhcp: add eBPF backend section

[Hannes Laimer <h.laimer@proxmox.com>]

Signed-off-by: Hannes Laimer <h.laimer@proxmox.com>
---

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
 `<hostname>.<domain>`. 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
   <hostname>.prefix.<domain>  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/<vnet>/subnets/<subnet>
@@ -1379,22 +1399,26 @@ pvesh set /cluster/sdn/vnets/<vnet>/subnets/<subnet>
  -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