From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 8871A9A3EA for ; Fri, 17 Nov 2023 12:40:59 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id AA6E530CBE for ; Fri, 17 Nov 2023 12:40:26 +0100 (CET) Received: from lana.proxmox.com (unknown [94.136.29.99]) by firstgate.proxmox.com (Proxmox) with ESMTP for ; Fri, 17 Nov 2023 12:40:24 +0100 (CET) Received: by lana.proxmox.com (Postfix, from userid 10043) id 07CA92C3BA4; Fri, 17 Nov 2023 12:40:19 +0100 (CET) From: Stefan Hanreich To: pve-devel@lists.proxmox.com Date: Fri, 17 Nov 2023 12:40:11 +0100 Message-Id: <20231117114011.834002-34-s.hanreich@proxmox.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20231117114011.834002-1-s.hanreich@proxmox.com> References: <20231117114011.834002-1-s.hanreich@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.601 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 KAM_LAZY_DOMAIN_SECURITY 1 Sending domain does not have any anti-forgery methods 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 RDNS_NONE 0.793 Delivered to internal network by a host with no rDNS SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_NONE 0.001 SPF: sender does not publish an SPF Record T_SCC_BODY_TEXT_LINE -0.01 - Subject: [pve-devel] [PATCH v4 pve-docs 33/33] sdn: dhcp: Add documentation for DHCP X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 17 Nov 2023 11:40:59 -0000 Signed-off-by: Stefan Hanreich --- pvesdn.adoc | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/pvesdn.adoc b/pvesdn.adoc index b796c5e..24878e2 100644 --- a/pvesdn.adoc +++ b/pvesdn.adoc @@ -79,6 +79,9 @@ In addition to this, the following options are offered: * DNS: Define a DNS server API for registering virtual guests' hostname and IP addresses +* 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. + [[pvesdn_config_main_sdn]] SDN @@ -418,6 +421,17 @@ for all subnets defined in those zones. This is the default internal IPAM for your {pve} cluster, if you don't have external IPAM software. +You can inspect the current status of the PVE IPAM Plugin via the Panel IPAM in +the SDN section of the datacenter configuration. This UI can be used to create, +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. + [[pvesdn_ipam_plugin_phpipam]] phpIPAM Plugin ~~~~~~~~~~~~~~ @@ -484,6 +498,114 @@ key:: An API access key ttl:: The default TTL for records +[[pvesdn_config_dhcp]] +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. + +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 +information on how to configure an IPAM in the +xref:pvesdn_config_ipam[respective section of our documentation]. + +When the VM starts, a mapping for the MAC address and IP gets created in the DHCP +plugin of the zone. When the network interfaces is removed or the VM/CT are +destroyed, then the entry in the IPAM and the DHCP server are deleted as well. + +NOTE: Some features (adding/editing/removing IP mappings) are currently only +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. + +NOTE: Currently only Simple Zones have support for automatic DHCP + +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: + +---- +pvesh set /cluster/sdn/vnets//subnets/ + -dhcp-range start-address=10.0.1.100,end-address=10.0.1.200 + -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_dhcp_dnsmasq_installation[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. + +[[pvesdn_dhcp_dnsmasq_installation]] +.Installation +In order to be able to use the Dnsmasq plugin you need to install +the dnsmasq package and disable the default DNS server that gets automatically +started: + +---- +apt install dnsmasq +systemctl disable --now dnsmasq +---- + +.Configuration +The plugin will create a new systemd service for each zone that dnsmasq gets +deployed to. The name for the service is `dnsmasq@`. The lifecycle of this +service is managed by the DHCP plugin. + +The plugin automatically generates the following configuration files in the +folder `/etc/dnsmasq.d/`: + +`00-default.conf`:: +This contains the default global configuration for a dnsmasq instance. + +`10--.conf`:: +This file configures specific options for a subnet, such as the DNS server that +should get configured via DHCP. + +`10--.ranges.conf`:: +This file configures the DHCP ranges for the dnsmasq instance. + +`ethers`:: +This file contains the MAC-address and IP mappings from the IPAM plugin. In +order to override those mappings, please use the respective IPAM plugin rather +than editing this file, as it will get overwritten by the dnsmasq plugin. + +You must not edit any of the above files, since they are managed by the DHCP +plugin. In order to customize the dnsmasq configuration you can create +additional files (e.g. `90-custom.conf`) in the configuration folder - they will +not get changed by the dnsmasq DHCP plugin. + +Configuration files are read in order, so you can control the order of the +configuration directives by naming your custom configuration files appropriately. + +DHCP leases are stored in the file `/var/lib/misc/dnsmasq..leases`. + +When using the PVE IPAM plugin, you can update, create and delete DHCP leases. +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. + Examples -------- -- 2.39.2