How to connect MAAS networks

• How to enable network discovery
• How to toggle subnet management
• How to access the main networking view
• How to display the subnet window
• How to view the subnet summary
• How to view utilisation
• How to manage static routes between subnets
• How to view reserved ranges
• How to view used IP addresses
• How to set up a bridge with MAAS
• How to set up a bridge with netplan

• How to enable network discovery
• How to toggle subnet management
• How to determine fabric ID
• How to set a default gateway
• How to set a DNS server
• How to list available subnets
• How to view subnet details
• How to manage static routes between subnets
• How to set up a bridge with MAAS
• How to set up a bridge with netplan

To enable network discovery:

1. Select Networking > Network discovery in the left navigation panel.

2. Select the Configuration tab at the top of the Network discovery panel.

3. In the Network discovery dropdown, select “Enabled”.

4. Select Save to register your changes.

To enable network discovery:

1. Click on “Canonical MAAS” at the top left of the screen.

2. Click on “Configuration”.

3. In the dropdown labeled “Network discovery”, choose “Enabled” or “Disabled”.

To enable network discovery, enter the following at the command line:

maas $PROFILE maas set-config name=network_discovery value="enabled"

If successful, you should receive output similar to:

Success.
Machine-readable output follows:
OK

Network discovery can be disabled or re-enabled at any time with this CLI command.

To toggle subnet management:

1. Select Subnets from the left navigation panel.

2. Select the subnet you wish to change by clicking on its address.

3. Select Edit in the upper right of the Subnet summary panel.

4. Select Managed allocation to toggle between enabled and disabled.

5. Select Save to register your changes.

You can (re)enable subnet management at any time by checking Managed allocation.

How to access the main networking view

To access the main networking view, select Networking > Subnets.

This main view can also be filtered through the use of the ‘Filters’ drop-down.

To disable (or re-enable) subnet management, use the following procedure:

1. Select Subnets.

2. Select the subnet in question

3. Select Edit.

4. Select Managed allocation to toggle between enabled and disabled.

5. Select Save summary.

How to access the main networking view

To access the main networking view, select Subnets.

This main view can also be filtered via the Group by drop-down.

To enable or disable subnet management:

maas $PROFILE subnet update $SUBNET_CIDR managed=false|true

For example, to disable subnet management:

maas $PROFILE subnet update 192.168.1.0/24 managed=false

You can use the subnets ID in place of the CIDR address.

How to determine fabric ID

To determine a fabric ID based on a subnet address:

FABRIC_ID=$(maas $PROFILE subnet read $SUBNET_CIDR \
    | grep fabric | cut -d ' ' -f 10 | cut -d '"' -f 2)

This may come in handy when you need a fabric ID for other CLI calls.

How to set a default gateway

To set the default gateway for a subnet:

maas $PROFILE subnet update $SUBNET_CIDR gateway_ip=$MY_GATEWAY

How to set a DNS server

To set the DNS server for a subnet:

maas $PROFILE subnet update $SUBNET_CIDR dns_servers=$MY_NAME SERVER

How to 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.name, .vlan.dhcp_on, .cidr])
| @tsv' \
| column -t

How to display the subnet window

Selecting a subnet will display its detail screen.

How to view subnet utilisation

This section of the subnet page presents metrics.

How to view subnet details

View the details of an individual subnet with the command:

maas $PROFILE subnet read $SUBNET_ID \
| jq -r '(["NAME","CIDR","GATEWAY","DNS","DISCOVERY","FABRIC","VLAN"]
| (., map(length*"-"))), ([.name,.cidr,.gateway_ip // "-", .allow_dns,.active_discovery,.vlan.name,.vlan.fabric]) | @tsv' | column -t

Look up the subnet ID like this:

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

For example, using the “admin” profile with a subnet name containing “192.168.123,” 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

To create a static route:

1. Select Networking > Subnets.

2. Select the Subnet you want to change by clicking on its IP address.

3. In the Subnet summary pane, scroll down to Add static route and select it.

4. Enter a Gateway IP address.

5. Select a Destination subnet from the dropdown.

6. Enter a routing Metric value, if desired.

7. Select Save to register your changes.

To create a static route:

1. Click the ‘Add static route’ button to reveal the edit pane.

2. Enter a Gateway IP address.

3. Select a destination subnet from the ‘Destination’ drop-down list.

4. Edit the routing metric value if needed.

5. Click ‘Add’ to activate the route.

Routes can be edited and removed using the icons to the right of each entry.

To create a static route between two subnets, use the following command:

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

How to view reserved ranges

The reserved ranges section of the subnet screen contains information on defined IP ranges.

How to view used IP addresses

The “Used IP addresses” section displays hosts (including controllers) associated with the used addresses along with related bits of host information.

To configure a bridge with the MAAS UI:

1. Select Machines.

2. Select the machine you want to bridge.

3. Select Network.

4. Checkbox the network where you want to create the bridge.

5. Select Create bridge.

6. Fill in the bridge details in the form which appears.

7. Optionally include the bridge in the spanning tree protocol by selecting the slider under Advanced options.

8. Optionally set the Forward delay in milliseconds.

9. Select Save interface to register your changes.

You can then deploy machines using this bridge.

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

1. Select the interface on which you wish to configure the bridge. 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 .boot_interface.id)
   

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 == "10.0.0.0/24" 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="10.0.0.101"
   

To edit a machine interface:

1. Select Machines.

2. Select the machine in question by clicking on its name.

3. Select Network.

4. Checkbox the interface in question.

5. Click the Actions dropdown at the right end of row for that interface.

6. Select Edit physical.

7. Change any of the desired parameters in the form which appears.

8. Select an IP mode.

9. Select Save interface to register your changes.

To edit a machine interface:

1. From a machine’s “Interfaces” page, click the menu icon for the interface to be edited and select Edit Physical from the resulting menu.

2. Select an IP mode from the drop-down menu. More information about IP modes is found in About networks.

3. Press Save to apply the changes.

To edit the IP assignment mode of a network interface, perform the following steps:

1. Find the interface ID and subnet link ID with the command:

maas $PROFILE node read $SYSTEM_ID

2. Unlink the old interface:

maas $PROFILE interface unlink-subnet $SYSTEM_ID $INTERFACE_ID id=$SUBNET_LINK_ID

3. Link the new interface:

maas $PROFILE interface link-subnet $SYSTEM_ID $INTERFACE_ID mode=$IP_MODE subnet=$SUBNET_CIDR [$OPTIONS]

1. Select more than one interface.

2. Select Create bond; the bond configuration pane will appear.

3. Rename the bond, if desired.

4. Select a bond mode:

• balance-rr: Transmit packets in sequential order from the first available follower through to the last. This mode provides load balancing and fault tolerance.

• active-backup: Only one follower in the bond is active. A different follower becomes active if, and only if, the active follower fails. The bond’s MAC address is externally visible on only one port (network adaptor) to avoid confusing the switch.

• balance-xor: Transmit based on the selected transmit hash policy. The default policy is simple, which means that an XOR operation selects packages. This XOR compares the source MAC address and the resultant XOR between the destination MAC address, the packet type identifier, and the modulo follower count.

• broadcast: Transmit everything on all follower interfaces. This mode provides fault tolerance.

• 802.3ad: Creates aggregation groups that share the same speed and duplex settings. This mode utilises all followers in the active aggregation, following the IEEE 802.3ad specification.

• balance-tlb: Adaptive transmit load balancing, channel bonding that does not require any special switch support.

• balance-alb: Adaptive load balancing, includes balance-tlb plus receive load balancing (rlb) for IPV4 traffic. This mode does not require any special switch support. ARP negotiation achieves load balancing in this case.

5. Assign a MAC address to the aggregate device.

6. Attach one or more Tags, if desired.

7. Select the Primary device.

8. Select Save to register your changes.

To create a bond, execute the following command:

maas $PROFILE interfaces create-bond $SYSTEM_ID name=$BOND_NAME \
parents=$IFACE1_ID mac_address=$MAC_ADDR \ 
parents=$IFACE2_ID bond_mode=$BOND_MODE \
bond_updelay=$BOND_UP bond_downdelay=$BOND_DOWN mtu=$MTU

Note that:

• The parents parameters define which interfaces form the aggregate interface.

• The bond_updelay and bond_downdelay parameters specify the number of milliseconds to wait before either enabling or disabling a follower after a failure has been detected.

• There are a wide range of bond parameters you can choose when creating a bond:

• Supported bonding modes include:

To create a bridge interface:

1. Select Machines.

2. Select a machine.

3. Select Network.

4. Select an interface by choosing its checkbox.

5. Select Create bridge.

6. Optionally enter a unique Bridge name.

7. Choose a Bridge type.

8. Enter a valid MAC address.

9. Choose a Fabric.

10. Choose a VLAN.

11. Optionally choose a Subnet.

12. Optionally enter Tags.

13. Optionally turn on STP.

14. Register your new bridge by selecting Save interface.

Please use the UI interface to create a bridge interface. Select the “UI” dropdown above to see how.

An interface can only be deleted via the MAAS CLI. Choose the “CLI” dropdown above to see how.

To create a bridge interface:

maas $PROFILE interfaces create-bridge $SYSTEM_ID name=$BRIDGE_NAME \
parent=$IFACE_ID

Use parent to define the primary interface used for the bridge:

maas admin interfaces create-bridge 4efwb4 name=bridged0 parent=4

The following parameters may be applied when creating a bridge:

• name: Optional string. Name of the interface.

• mac_address: Optional string. MAC address of the interface.

• tags: Optional string. Tags for the interface.

• vlan: Optional string. VLAN the interface is connected to.

• parent: Optional integer. Parent interface id for this bridge interface.

• bridge_type: Optional string. The type of bridge to create. Possible values are: standard, ovs.

• bridge_stp: Optional Boolean. Turn spanning tree protocol on or off. (Default: False).

• bridge_fd: Optional integer. Set bridge forward delay to time seconds. (Default: 15).

• mtu: Optional integer. Maximum transmission unit.

• accept_ra: Optional Boolean. Accept router advertisements. (IPv6 only)

• autoconf: Optional Boolean. Perform stateless autoconfiguration. (IPv6 only)

A network interface may be assigned to a fabric with the MAAS CLI only. Choose the “CLI” dropdown above to see how.

This task is made easier with the aid of the jq utility. It filters the maas command (JSON formatted) output and prints it in the desired way, which allows you to view and compare data quickly. Go ahead and install it:

sudo apt install jq

In summary, MAAS assigns an interface to a fabric by assigning it to a VLAN. First, we need to gather various bits of data.

List some information on all machines:

maas $PROFILE machines read | jq ".[] | \
    {hostname:.hostname, system_id: .system_id, status:.status}" --compact-output

Example output:

{"hostname":"machine1","system_id":"dfgnnd","status":4}
{"hostname":"machine2","system_id":"bkaf6e","status":6}
{"hostname":"machine4","system_id":"63wqky","status":6}
{"hostname":"machine3","system_id":"qwkmar","status":4}

List some information for all interfaces on the machine in question (identified by its system id ‘dfgnnd’):

maas $PROFILE interfaces read dfgnnd | jq ".[] | \
    {id:.id, name:.name, mac:.mac_address, vid:.vlan.vid, fabric:.vlan.fabric}" --compact-output

Example output:

{"id":8,"name":"eth0","mac":"52:54:00:01:01:01","vid":0,"fabric":"fabric-1"}
{"id":9,"name":"eth1","mac":"52:54:00:01:01:02","vid":null,"fabric":null}

List some information for all fabrics:

maas $PROFILE fabrics read | jq ".[] | \
    {name:.name, vlans:.vlans[] | {id:.id, vid:.vid}}" --compact-output

Example output:

{"name":"fabric-0","vlans":{"id":5001,"vid":0}}
{"name":"fabric-1","vlans":{"id":5002,"vid":0}}
{"name":"fabric-2","vlans":{"id":5003,"vid":0}}

This example will show how to move interface ‘8’ (on machine ‘dfgnnd’) from ‘fabric-1’ to ‘fabric-0’. Based on the gathered information, this will consist of changing the interface’s VLAN from ‘5002’ to ‘5001’:

maas $PROFILE interface update dfgnnd 8 vlan=5001 >/dev/null

Verify the operation by relisting information for the machine’s interface:

maas $PROFILE interfaces read dfgnnd | jq ".[] | \
    {id:.id, name:.name, mac:.mac_address, vid:.vlan.vid, fabric:.vlan.fabric}" --compact-output

The output shows that the interface is now on fabric-0:

{"id":8,"name":"eth0","mac":"52:54:00:01:01:01","vid":0,"fabric":"fabric-0"}
{"id":9,"name":"eth1","mac":"52:54:00:01:01:02","vid":null,"fabric":null}

Interface identifiers can only be discovered via the MAAS CLI. Choose the “CLI” dropdown above to see how.

The MAAS CLI uses a numeric interface identifier for many interface operations. Use the following command to retrieve the identifier(s):

maas $PROFILE interfaces read $SYSTEM_ID

Look for either id or the number at the end of an interface’s resource URI, such as 15 in the following example output:

"id": 15,
"mac_address": "52:54:00:55:06:40",
...
"name": "ens9",
...
"resource_uri": "/MAAS/api/2.0/nodes/4efwb4/interfaces/15/"

VLAN interfaces can only be created via the MAAS CLI. Select the “CLI” dropdown above to see how.

To create a VLAN interface, use the following syntax:

maas $PROFILE vlans create $FABRIC_ID name=$NAME vid=$VLAN_ID

For example, the following command creates a VLAN called 'Storage network:

maas admin vlans create 0 name="Storage network" vid=100

The above command generates the following output:

Success.
Machine-readable output follows:
{
    "vid": 100,
    "mtu": 1500,
    "dhcp_on": false,
    "external_dhcp": null,
    "relay_vlan": null,
    "name": "Storage network",
    "space": "undefined",
    "fabric": "fabric-0",
    "id": 5004,
    "primary_rack": null,
    "fabric_id": 0,
    "secondary_rack": null,
    "resource_uri": "/MAAS/api/2.0/vlans/5004/"
}

Be aware that the $VLAN_ID parameter does not indicate a VLAN ID that corresponds to the VLAN tag. You must first create the VLAN and then associate it with the interface:

maas $PROFILE interfaces create-vlan $SYSTEM_ID vlan=$OUTPUT_VLAN_ID \
parent=$IFACE_ID

The following example contains values that correspond to the output above:

maas admin interfaces create-vlan 4efwb4 vlan=5004 parent=4

The above command generates the following output:

Success.
Machine-readable output follows:
{
    "tags": [],
    "type": "vlan",
    "enabled": true,
    "system_id": "4efwb4",
    "id": 21,
    "children": [],
    "mac_address": "52:54:00:eb:f2:29",
    "params": {},
    "vlan": {
        "vid": 100,
        "mtu": 1500,
        "dhcp_on": false,
        "external_dhcp": null,
        "relay_vlan": null,
        "id": 5004,
        "secondary_rack": null,
        "fabric_id": 0,
        "space": "undefined",
        "fabric": "fabric-0",
        "name": "Storage network",
        "primary_rack": null,
        "resource_uri": "/MAAS/api/2.0/vlans/5004/"
    },
    "parents": [
        "ens3"
    ],
    "effective_mtu": 1500,
    "links": [
        {
            "id": 55,
            "mode": "link_up"
        }
    ],
    "discovered": null,
    "name": "ens3.100",
    "resource_uri": "/MAAS/api/2.0/nodes/4efwb4/interfaces/21/"
}

VLAN interfaces can only be deleted via the MAAS CLI. Select the “CLI” dropdown above to see how.

The following command outlines the syntax required to delete a VLAN interface from the command line:

maas $PROFILE vlan delete $FABRIC__ID $VLAN_ID

Using the values from previous examples, you executed this step as follows:

maas admin vlan delete 0 100

1. In the web UI, visit the ‘Settings’ page and select the ‘Network services’ tab.

2. Modify the ‘Proxy’ section at the top, as desired:

• To enable the internal proxy, ensure that the checkbox adjacent to ‘MAAS Built-in’ is selected. This internal proxy is the default configuration.

• To enable an external proxy, activate the ‘External’ checkbox and use the new field that is displayed to define the proxy’s URL (and port if necessary).

• An upstream cache peer can be defined by enabling the ‘Peer’ checkbox and entering the external proxy URL into the field. With this enabled, machines will be configured to use the MAAS built-in proxy to download cached APT packages.

• To prevent MAAS machines from using a proxy, enable the ‘Don’t use a proxy’ checkbox.

Enabling and disabling proxying, in general, is done via a Boolean option (‘true’ or ‘false’). The following command will disable proxying completely:

maas $PROFILE maas set-config name=enable_http_proxy value=false

To set an external proxy, ensure proxying is enabled (see above) and then define it:

maas $PROFILE maas set-config name=http_proxy value=$EXTERNAL_PROXY

For example,

maas $PROFILE maas set-config name=enable_http_proxy value=true
maas $PROFILE maas set-config name=http_proxy value=http://squid.example.com:3128/

Enabling and disabling proxying per subnet is done via a Boolean option (‘true’ or ‘false’). Here is how you can disable proxying on a per-subnet basis:

maas $PROFILE subnet update $SUBNET_CIDR allow_proxy=false

For example,

maas $PROFILE subnet update 192.168.0.0/22 allow_proxy=false

You can specify an external site by choosing the NTP server(s) and selecting the ‘External Only’ option. The region controller always uses an external site.

1. On the ‘Settings’ page, select the ‘Network services’ tab and scroll down to the ‘NTP’ section.

2. Enter the address of the desired NTP server.

You can specify an external NTP server with two successive commands:

maas $PROFILE maas set-config name=ntp_servers value=$NTP_IP_ADDRESS

followed by:

maas admin maas set-config name=ntp_external_only value=true