Networking (deb/2.7/CLI)

You can use the CLI to manage the networking elements of MAAS, including subnets, fabrics, VLANs, and spaces. This page shows how to access and edit these elements. See Concepts and terms for the definitions of networking objects, along with a basic networking tutorial (if needed).

Nine questions you may have:

  1. How do I list available subnets?
  2. How do I manage subnets?
  3. How do I manage static routes?
  4. How do I manage reserved ranges?
  5. How do I set up a bridge?
  6. How do I set up a bridge with the MAAS CLI/API?
  7. How do I set up a bridge with netplan?

List available subnets

To view the list of available subnets, enter the following command:

maas admin subnets read | \
jq -r '(["FABRIC", "VLAN", "DHCP", "SUBNET"]
| (., map(length*"-"))),
(.[] | [.vlan.fabric,, .vlan.dhcp_on, .cidr])
| @tsv' \
| column -t

which produces output something like this:

FABRIC        VLAN      DHCP       SUBNET
------        ----      ---------  ------
Patient-Care  untagged  true
fabric-0      untagged  false
fabric-0      untagged  false
fabric-1      untagged  false
fabric-1      untagged  false      fd42:8b52:7114:9ef8::/64
fabric-3      untagged  true
fabric-3      untagged  true       2600:100d:b125:d5e9::/64
fabric-3      untagged  true       2600:100d:b120:3933::/64
fabric-3      untagged  true       2600:100d:b109:dee0::/64
fabric-3      untagged  true       2600:100d:b104:94c0::/64

Fabrics, VLANs, and spaces do not require much configuration beyond names and descriptions. You can change the MTU for a VLAN, as well as enable DHCP (see ‘Take action’ button). None of these options requires detailed instruction. A subnet, on the other hand, provides a number of configuration options relevant to the day-to-day operation of MAAS.

Managing subnets

You can view the details of an individual subnet with the command:

maas $PROFILE subnet read $SUBNET_ID \
| (., map(length*"-"))), ([.name,.cidr,.gateway_ip // "-", .allow_dns,.active_discovery,,.vlan.fabric]) | @tsv' | column -t

This command retrieves output similar to this:

NAME              CIDR              GATEWAY  DNS   DISCOVERY  FABRIC    VLAN
----              ----              -------  ---   ---------  ------    ----  -        true  false      untagged  default

If you don’t know the subnet ID, you can look it up like this:

maas $PROFILE subnets read \
| jq -r '(["NAME", "SUBNET_ID"]
| (., map(length*"-"))), (.[] | [.name, .id]) | @tsv' \
| column -t | grep $SUBNET_NAME

For example, if you’re using the “admin” profile, and your subnet name contains “192.168.123,” you could find the subnet ID with this command:

maas admin subnets read \
| jq -r '(["NAME", "SUBNET_ID"]
| (., map(length*"-"))), (.[] | [.name, .id]) | @tsv' \
| column -t | grep 192.168.123

Subnets support the following configurable values:

  • Name: Subnet names can be any valid text string, although usually, and by default, they are named with the CIDR of the subnet itself.

  • CIDR: This is the address parameter for the subnet. In keeping with standard CIDR notation, the number of bits of the prefix are indicated after the slash.

  • Gateway IP: This is the address of the default gateway for your subnet, which is the IP address that transfers packets to other subnets or networks. Typically, this is simply the first IP address in a block of addresses (the .1 address).

  • DNS: This is the address of a DNS (domain name server, or simply “nameserver”) for your subnet. It’s optional, but can be configured if desired.

  • Description: This field represents freeform text that you can enter to describe your subnet, as needed to keep important notes attached to the definition of the subnet.

  • Managed allocation refers to the ability of MAAS to completely manage a subnet. See Subnet management.

  • Active mapping instructs MAAS to scan the subnet every 3 hours to discover hosts that have not been discovered passively.

  • Proxy access instructs MAAS to allow clients from this subnet to access the MAAS proxy.

  • Allow DNS resolution allows subnet clients to use MAAS for DNS resolution.

  • Fabric: This field allows you to set the subnet’s fabric.

  • VLAN: This field allows you to set the subnet’s VLAN.

  • Space is presented for clarity, though spaces are managed at the VLAN level.

Static Routes

This section can be used to define a static route between two subnets. A route is defined on a per-subnet basis to use a particular gateway, using a configured destination and metric.

To create a static route, use the following command:

maas admin static-routes create source=$SOURCE_SUBNET destination=$DEST_SUBNET \

Reserved ranges

This subject is treated separately in IP ranges.

Setting up a bridge

At various times in your MAAS network, you may need to set up a bridge to connect between your machines and MAAS. This section explains several ways of accomplishing this.

It’s essential to enforce usage of IP addresses to avoid domain name conflicts, should different controllers resolve the same domain name with different IP addresses. You should also avoid using when running multiple controllers, as it would confuse MAAS.

Use the MAAS API to configure a bridge

You can use the MAAS CLI/API to configure a bridge, with the following procedure:

  1. Select the interface you wish to configure the bridge on. This example uses the boot interface, since the boot interface must be connected to a MAAS controlled network – but any interface is allowed:

     INTERFACE_ID=$(maas $PROFILE machine read $SYSTEM_ID | jq
  2. Create the bridge:

      BRIDGE_ID=$(maas $PROFILE interfaces create-bridge $SYSTEM_ID name=br0 parent=$INTERFACE_ID | jq .id)
  3. Select the subnet where you want the bridge (this should be a MAAS controlled subnet):

     SUBNET_ID=$(maas $PROFILE subnets read | jq -r '.[] | select(.cidr == "" and .managed == true).id')
  4. Connect the bridge to the subnet:

       maas $PROFILE interface link-subnet $SYSTEM_ID $BRIDGE_ID subnet=$SUBNET_ID mode="STATIC" ip_address=""

Use netplan to configure a bridge

You can also use netplan to configure a bridge:

Open your netplan configuration file. This should be in /etc/netplan. It could be called 50-cloud-init.yaml, netplan.yaml, or something else. Modify the file to add a bridge, using the example below to guide you:

            - enp1s0
            macaddress: 52:54:00:39:9d:f9
            mtu: 1500
                - maas
                forward-delay: 15
                stp: false
                macaddress: 52:54:00:39:9d:f9
            mtu: 1500
            set-name: enp1s0
                macaddress: 52:54:00:df:87:ac
            mtu: 1500
            set-name: enp2s0
                macaddress: 52:54:00:a7:ac:46
            mtu: 1500
            set-name: enp3s0
    version: 2

Apply the new configuration with netplan apply.