Managing DHCP (snap/2.8/CLI)

2.7 2.8 2.9
Packages CLI ~ UI CLI ~ UI CLI ~ UI

MAAS enlists and commissions machines through the use of its DHCP server running on an untagged VLAN. Although this MAAS-managed DHCP can also be part of the deploy phase, an external DHCP server can optionally be used instead for this purpose. If MAAS detects an external DHCP server, it will display it on the rack controller’s page, accessible by selecting ‘Controllers’ from the top menu in the web UI.

In addition, the machine subnet is usually on the untagged VLAN. If not, you will need to route DHCP packets between the subnet and the MAAS-provided DHCP subnet. It is also possible to forward DHCP traffic from one VLAN to another using an external DHCP relay service.

This documentation presupposes that MAAS-managed DHCP is used to enlist and commission machines. Using an external DHCP server for enlistment and commissioning may work, but note that this is not supported. MAAS cannot manage an external DHCP server, nor can it keep leases synchronised when you return a machine to the pool.

This article delves into these issues, offering guidance on setting up and managing your DHCP configuration.

Eight questions you may have:

  1. What are reserved IP ranges?
  2. What is post-commission configuration
  3. How and why should I enable MAAS-managed DHCP?
  4. How do I resolve IP conflicts?
  5. How can I extend a reserved dynamic IP range?
  6. How and why should I configure external DHCP?
  7. How and why should I use a DHCP relay?
  8. How and why should I customise MAAS with DHCP snippets?

Enabling DHCP

MAAS-managed DHCP needs a reserved dynamic IP range enlist and commission machines. You should create such a range when you are enabling DHCP with the web UI.

To enable DHCP on a VLAN on a certain fabric:

maas $PROFILE vlan update $FABRIC_ID $VLAN_TAG dhcp_on=True \

To enable DHCP HA, you will need both a primary and a secondary controller:

maas $PROFILE vlan update $FABRIC_ID $VLAN_TAG dhcp_on=True \
    primary_rack=$PRIMARY_RACK_CONTROLLER \

You must enable DHCP for PXE booting on the ‘untagged’ VLAN.

You will also need to set a default gateway:

maas $PROFILE subnet update $SUBNET_CIDR gateway_ip=$MY_GATEWAY

Resolving IP conflicts

In some cases, MAAS manages a subnet that is not empty, which could result in MAAS assigning a duplicate IP address. MAAS is capable of detecting IPs in use on a subnet. Be aware that there are two caveats:

  1. If a previously-assigned NIC is in a quiescent state or turned off, MAAS may not detect it before duplicating an IP address.

2/ At least one rack controller must have access to the IP-assigned machine in order for this feature to work.

MAAS also recognises when the subnet ARP cache is full, so that it can re-check the oldest IPs added to the cache to search for free IP addresses.

Extending a reserved dynamic IP range

If necessary, it is possible to add further portions of the subnet to the dynamic IP range (see IP ranges). Furthermore, since you enabled DHCP on a VLAN basis and a VLAN can contain multiple subnets, it is possible to add a portion from those subnets as well. Just select the subnet under the ‘Subnets’ page and reserve a dynamic range. DHCP will be enabled automatically.

External DHCP and a reserved IP range

If an external DHCP server is used to deploy machines, then a reserved IP range should be created to prevent the address namespace from being corrupted. For instance, address conflicts may occur if you set a machine’s IP assignment mode to ‘Auto assign’ in the context of an external DHCP server. See IP ranges to create such a range. It should correspond to the lease range of the external server.

DHCP relay

You should not enable DHCP relays in MAAS without sufficient planning. In particular, MAAS does not provide the actual relay. It must be set up as an external service by the administrator. What MAAS does provide is the DHCP configuration that MAAS-managed DHCP requires in order to satisfy any client requests relayed from another VLAN.

To relay from one VLAN (source) to another VLAN (target):

  1. Ensure the target VLAN has DHCP enabled.

  2. Set up the external relay. This relay is set up independently from MAAS. See DHCP relay for software suggestions.

  1. To relay DHCP traffic for a VLAN (source) through another VLAN (target):
maas $PROFILE vlan update $FABRIC_ID $VLAN_VID_SRC relay_vlan=$VLAN_ID_TARGET

For example, to relay VLAN with vid 0 (on fabric-2) through VLAN with id 5002 :

maas $PROFILE vlan update 2 0 relay_van=5002

DHCP Snippets

When MAAS manages DHCP, you customise it through the use of DHCP snippets. These are user-defined configuration options that can be applied either globally, per subnet, or per machine. You apply a global snippet to all VLANs, subnets, and machines. All three types end up in /var/snap/maas/common/maas/dhcpd.conf or /var/snap/maas/common/maas/dhcpd6.conf. Be aware that if you edit these files directly, you will need to sudo to root, as there is no maas user in the snap (all relevant files are owned by root). For information on what options to use, refer to the dhcpd.conf man page.

Modifications made directly to dhcpd.conf.template or dhcpd6.conf.template are not supported.

When you create a snippet, MAAS enables it by default.

To create a global snippet:

maas $PROFILE dhcpsnippets create name=$DHCP_SNIPPET_NAME \

To create a subnet snippet:

maas $PROFILE dhcpsnippets create name=$DHCP_SNIPPET_NAME \

You can also specify subnets in CIDR format.

To create a node snippet:

maas $PROFILE dhcpsnippets create name=$DHCP_SNIPPET_NAME \

You can also use a hostname instead of the node ID.

List snippets

To list all snippets (and their characteristics) in the MAAS:

maas $PROFILE dhcpsnippets read

To list a specific snippet:

maas $PROFILE dhcpsnippet read id=$DHCP_SNIPPET_ID

The snippet name can also be used instead of its ID:

maas $PROFILE dhcpsnippet read name=$DHCP_SNIPPET_NAME

Update a snippet

Update a snippet attribute:

maas $PROFILE dhcpsnippet update $DHCP_SNIPPET_ID <option=value>

You can also use a snippet name instead of its ID.

Enable or disable a snippet

Enabling and disabling a snippet is considered a snippet update and is done via a boolean option (‘true’ or ‘false’). You can disable a snippet like this:

maas $PROFILE dhcpsnippet update $DHCP_SNIPPET_ID enabled=false

When you disable a snippet, MAAS removes the text you added to the dhcpd.conf file when you created the snippet.

Delete a snippet

To delete a snippet:

maas $PROFILE dhcpsnippet delete $DHCP_SNIPPET_ID

You can also use a snippet name in place of its ID.