How to manage IP addresses

Management of DHCP and IP ranges is a key element of configuring and managing MAAS. This article will help you learn:

How to manage MAAS DHCP

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 will help you learn:

How to enable MAAS-managed DHCP

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

To enable MAAS-managed DHCP, under the ‘Subnets’ page select the desired VLAN and then:

  1. Under the ‘Take action’ button select ‘Provide DHCP’. A new window will appear.
  2. Select the primary rack controller. For DHCP HA, select both the primary and the secondary.
  3. Create a reserved, dynamic IP range. Fill in the fields ‘Dynamic range start IP’ and ‘Dynamic range end IP’.
  4. Apply your changes with the ‘Provide DHCP’ button.

Now, addresses in this range will get assigned to machines that are being either enlisted or commissioned. In addition, if you are deploying a machine that has an interface connected to the untagged VLAN, and it has an IP assignment mode set to ‘DHCP,’ then it will also get an address in this range.

To enable DHCP on a VLAN on a certain fabric:

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

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 \
    secondary_rack=$SECONDARY_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

How to resolve 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.

How to extend a reserved dynamic IP range

If necessary, it is possible to add further portions of the subnet to the dynamic IP range (see below). 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.

How to configure external DHCP

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 below to create such a range. It should correspond to the lease range of the external server.

How to use a 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. Configure MAAS-managed DHCP. Navigate to the source VLAN page and select the ‘Relay DHCP’ action. Fill in the fields in the resulting form. The crucial setting is the target VLAN (‘Relay VLAN’). Press the ‘Relay DHCP’ button to finish.
  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

How to customise MAAS with 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.

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/lib/maas/dhcpd.conf or /var/lib/maas/dhcpd6.conf. For information on what options to use, refer to the dhcpd.conf man page.

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.

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/lib/maas/dhcpd.conf or /var/lib/maas/dhcpd6.conf. For information on what options to use, refer to the dhcpd.conf man page.

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.

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/lib/maas/dhcpd.conf or /var/lib/maas/dhcpd6.conf. For information on what options to use, refer to the dhcpd.conf man page.

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.

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/lib/maas/dhcpd.conf or /var/lib/maas/dhcpd6.conf. 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.

To manage snippets, as an admin, open the ‘Settings’ page and click on the ‘DHCP snippets’ tab.

For example, to create a new snippet press ‘Add custom snippet’. In the resulting window, choose a name and type for it and enter its associated DHCP configuration. Click ‘Save snippet’ to apply the change, and make sure to activate the checkbox in the ‘Enabled’ column of the snippets list.

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

To create a global snippet:

maas $PROFILE dhcpsnippets create name=$DHCP_SNIPPET_NAME \
    value=$DHCP_CONFIG description=$DHCP_SNIPPET_DESCRIPTION \
    global_snippet=true

To create a subnet snippet:

maas $PROFILE dhcpsnippets create name=$DHCP_SNIPPET_NAME \
    value=$DHCP_CONFIG description=$DHCP_SNIPPET_DESCRIPTION \
    subnet=$SUBNET_ID

You can also specify subnets in CIDR format.

To create a node snippet:

maas $PROFILE dhcpsnippets create name=$DHCP_SNIPPET_NAME \
    value=$DHCP_CONFIG description=$DHCP_SNIPPET_DESCRIPTION \
    node=$NODE_ID

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

How to list DHCP 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

How to update a DHCP 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.

How to enable or disable a DHCP 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.

How to delete a DHCP snippet

To delete a snippet:

maas $PROFILE dhcpsnippet delete $DHCP_SNIPPET_ID

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

How to set DNS parameters

It is possible to set DNS parameters using the MAAS CLI, using the following instructions.

How to create an A or AAAA record in DNS

An administrator can create an A record when creating a DNS resource with an IPv4 address.

mass $PROFILE dnsresources create fqdn=$HOSTNAME.$DOMAIN ip_addresses=$IPV4ADDRESS

An administrator can create an AAAA record when creating a DNS resource with an IPv6 address.

mass $PROFILE dnsresources create fqdn=$HOSTNAME.$DOMAIN ip_addresses=$IPV6ADDRESS

How to create an alias (CNAME) record in DNS

An administrator can set a DNS Alias (CNAME record) to an already existing DNS entry of a machine.

mass $PROFILE dnsresource-records create fqdn=$HOSTNAME.$DOMAIN rrtype=cname rrdata=$ALIAS

For example, to set webserver.maas.io to alias to www.maas.io:

maas $PROFILE dnsresource-records create fqdn=webserver.maas.io rrtype=cname rrdata=www

How to create a Mail Exchange pointer record in DNS

An administrator can set a DNS Mail Exchange pointer record (MX and value) to a domain.

maas $PROFILE dnsresource-records create fqdn=$DOMAIN rrtype=mx rrdata='10 $MAIL_SERVER.$DOMAIN'

For example, to set the domain.name managed by MAAS to have an MX record and that you own the domain:

maas $PROFILE dnsresource-records create fqdn=maas.io rrtype=mx rrdata='10 smtp.maas.io'

How to set a DNS forwarder

To set a DNS forwarder:

maas $PROFILE maas set-config name=upstream_dns value=$MY_UPSTREAM_DNS

How to manage IP ranges

In MAAS-managed networks, you can further manage your subnets with a reserved range of IP addresses. You can reserve IP addresses by adding one or more reserved ranges to a subnet configuration. You can define two types of ranges: reserved ranges and reserved dynamic ranges.

A reserved range operates differently depending on whether the subnet is managed or unmanaged. For a managed (subnet), MAAS will never assign IP addresses inside this range. You can use this range for anything, such as infrastructure systems, network hardware, external DHCP, or an OpenStack namespace. For an unmanaged (subnet), MAAS will only assign IP addresses inside this range – but MAAS can assign any IP within this range.

A reserved dynamic range is used by MAAS for enlisting, commissioning and, if enabled, MAAS-managed DHCP on the machine’s VLAN during commissioning and deployment. If created with the Web UI, an initial range is created as part of the DHCP enablement process. MAAS never uses IP addresses from this range for an unmanaged subnet.

This section gives specific instructions about creating and managing IP ranges; it will help you learn:

How to create an IP range

To create a range with the web UI, choose the “Subnets” option across the top:

In the “SUBNET” column, choose the subnet for which you want to create an IP range(s):

Scroll down to “Reserved ranges” on the subnet screen and click on the “Reserve range” drop-down:

Choose ‘Reserve range’ or ‘Reserve dynamic range’. If you choose the latter, MAAS will automatically provide DHCP for enlistment and commissioning provided that the associated VLAN has DHCP enabled.

When you choose either of those two options, a window will appear allowing you to enter start and end addresses for the range as well as a comment.

Below is an example window when creating a ‘reserved range’ (the windows are identical):

Click the ‘Reserve’ button when done.

See Concepts and terms for an explanation of the two kinds of reserved IP ranges MAAS uses.

To create a range of dynamic IP addresses that will be used by MAAS for node enlistment, commissioning, and possibly deployment:

maas $PROFILE ipranges create type=dynamic \
    start_ip=$IP_DYNAMIC_RANGE_LOW end_ip=$IP_DYNAMIC_RANGE_HIGH \
    comment='This is a reserved dynamic range'

To create a range of IP addresses that will not be used by MAAS:

maas $PROFILE ipranges create type=reserved \
    start_ip=$IP_STATIC_RANGE_LOW end_ip=$IP_STATIC_RANGE_HIGH \
    comment='This is a reserved range'

To reserve a single IP address that will not be used by MAAS:

maas $PROFILE ipaddresses reserve ip_address=$IP_STATIC_SINGLE

To remove such a single reserved IP address:

maas $PROFILE ipaddresses release ip=$IP_STATIC_SINGLE

How to edit an existing IP range

Click the ‘Menu’ button at the far right of the row corresponding to the subnet in question and select ‘Edit reserved range’ from the menu that appears. Edit the fields as desired and click the ‘Save’ button.

How to delete an existing IP range

Select ‘Remove range’ from the menu that appears when clicking the ‘Menu’ button at the far right of the row corresponding to the subnet in question.

To edit an IP range, first find the ID of the desired IP range with the command:

maas admin ipranges read

Examine the JSON output to find the ID corresponding to the IP range you want to edit, then enter:

maas admin iprange update $ID start_ip="<start ip>" end_ip="<end ip>" comment="freeform comment"

This command will update the IP range associated with $ID.