Signed-off-by: Stefan Hanreich <s.hanre...@proxmox.com> --- 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/<vnet>/subnets/<subnet> + -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@<zone>`. 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/<zone>`: + +`00-default.conf`:: +This contains the default global configuration for a dnsmasq instance. + +`10-<zone>-<subnet_cidr>.conf`:: +This file configures specific options for a subnet, such as the DNS server that +should get configured via DHCP. + +`10-<zone>-<subnet_cidr>.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.<zone>.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 _______________________________________________ pve-devel mailing list pve-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel