[PATCH pve-docs v2 16/16] sdn: dhcp: document the ebpf backend

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

The DHCP setting of a zone became a choice of backend, the eBPF
responder is available on every zone type while dnsmasq stays limited to
simple zones. Describe how the responder answers, what it needs and what
it does not do. Describe the two subnet options both backends read as
well, the DNS server handed out and the lease time.

Signed-off-by: Hannes Laimer <h.laimer@proxmox.com>
---
 pvesdn.adoc | 113 +++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 95 insertions(+), 18 deletions(-)

diff --git a/pvesdn.adoc b/pvesdn.adoc
index 3fd3533..8394adb 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 responder built into
+{pve}, chosen per zone. This is currently opt-in.
 
-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,10 @@ 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:: The DHCP backend for the zone, see xref:pvesdn_config_dhcp[DHCP].
+  `dnsmasq` is limited to Simple Zones, `ebpf` is available for every zone
+  type.  Optional.
+
 
 [[pvesdn_zone_plugin_simple]]
 Simple Zones
@@ -442,6 +447,14 @@ 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 a lease points the guest at. The `ebpf`
+  backend hands out an IPv4 DNS server only, one of the other address family
+  is left out of its answers.  Optional.
+
+DHCP Lease Time:: The lease time in seconds. Without it `dnsmasq` hands out
+  infinite leases and the `ebpf` backend leases of ten minutes. `dnsmasq`
+  raises anything below two minutes to two minutes.  Optional.
+
 
 [[pvesdn_config_controllers]]
 Controllers
@@ -1342,9 +1355,10 @@ 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. Two backend plugins are available, `dnsmasq` and `ebpf`, chosen per
+zone. Both answer from the mappings in the IPAM, `ebpf` for IPv4 Subnets only.
+An automatic allocation takes an address from the Subnet's DHCP ranges, or from
+the whole Subnet when it has none.
 
 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 +1376,11 @@ 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 UI via the Zones panel by
+choosing a DHCP backend in the advanced options of the zone.
 
-NOTE: Currently only Simple Zones have support for automatic DHCP
+NOTE: The `dnsmasq` backend is only available for Simple Zones, the `ebpf`
+backend for 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 +1394,24 @@ 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.
+A Subnet without a gateway is served by both backends, its guests then get no
+default route. An IPv6 Subnet needs a gateway with the `dnsmasq` backend.
 
 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 subnet options *DHCP DNS Server* and *DHCP Lease Time*, see
+xref:pvesdn_config_subnet[Subnets], shape the leases handed out.
+
+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.
+The plugin used by zones with `dnsmasq` as their DHCP backend.
 
 .Installation
 For installation see the xref:pvesdn_install_dhcp_ipam[DHCP IPAM] section.
@@ -1437,6 +1454,66 @@ 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_ebpf]]
+eBPF Plugin
+^^^^^^^^^^^
+The plugin used by zones with `ebpf` as their DHCP backend. It needs no
+additional package and is available for every zone type.
+
+Instead of running a DHCP server on the bridge, a small program is attached to
+the network interface of every guest on the zone's VNets. It answers the DHCP
+requests of that guest right there, from the cluster's cache of the MAC address
+and IP mappings, which every mapping change made through {pve} keeps current.
+The exchange never reaches the bridge. Each guest interface is answered from the
+mapping of its own network device only, and only a request carrying that
+device's MAC address is answered. Requests on an interface without a mapping
+pass through untouched, so such a guest can still reach another DHCP server on
+the network.
+
+A mapping changed through {pve} reaches a running guest at its next lease
+renewal, without a restart. A deleted one is no longer answered, the
+guest keeps its address until the lease runs out.
+
+The program is attached when a guest interface is plugged and detached when it
+is unplugged. Every SDN apply attaches what is missing, so a zone switched to
+`ebpf` serves its running guests that hold a mapping from the next apply on.
+
+.Requirements
+The responder needs kernel 6.6 or newer. Every kernel shipped with this {pve}
+release qualifies.
+
+.Limitations
+* IPv4 only. IPv6 subnets are ignored by this backend.
+* Only untagged frames are answered. A guest tagging its own traffic with a
+  VLAN, for example on a trunk port, is not served.
+* The answer is given before the firewall of the guest and the rate limit of its
+  interface see the request, so neither the guest's firewall rules nor its DHCP
+  firewall option nor the rate limit apply to the request. The reply is put on
+  the interface's egress, so its rate limit shapes the reply and the firewall
+  never sees it. A request on an interface without a mapping passes the firewall
+  and the rate limit as usual.
+* The answer carries the address, netmask, server identifier, lease time and
+  MTU, the router where the Subnet has a gateway and the DNS server where it has
+  an IPv4 one, plus a blank proxy autodiscovery option that keeps Windows guests
+  from searching for one. Options `dnsmasq` could add through its custom
+  configuration, such as a domain name or PXE boot parameters, are not
+  available. On an interface with a mapping, a DISCOVER and every REQUEST of the
+  guest itself that is not addressed to another server are answered or refused
+  here and never reach another DHCP server on the network. Every other message
+  type, an INFORM for example, passes on and gets no answer from this backend.
+* The responder keeps no lease file, the mapping is the lease. What a guest
+  holds is what the IPAM holds for its MAC address.
+* Only a request carrying the guest interface's MAC address is answered. A guest
+  bridging further clients, such as nested containers, or one that changed its
+  MAC address, gets no answer from this backend, as with an unknown MAC address
+  under `dnsmasq`.
+* The responder identifies itself with the subnet gateway, or with a
+  link-local address on a subnet without one, which is then served without a
+  default route. Where a guest cannot reach that address, it cannot renew its
+  lease by unicast and falls back to broadcasting at its rebinding time.
+* Mappings changed directly in an external IPAM are not picked up, as with
+  `dnsmasq`.
+
 [[pvesdn_firewall_integration]]
 Firewall Integration
 --------------------
-- 
2.47.3