MAAS is relatively easy to install and configure. Let’s give it a try.
NOTE: MAAS will run on just about any modern hardware configuration, even a development laptop. If you’re not sure whether your target server will handle MAAS, you can always double-check.
NOTE:
IMPORTANT: If you’re having trouble accessing your MAAS, double-check your URL. It should be of the form http://nn.nn.nn.nn:5240/MAAS, where nn.nn... is the IP address. Note that this is http and not https. ALSO check whether the IP of your MAAS host may have changed, e.g., due to the MAAS host using a DHCP lease. If the MAAS host’s IP changes for any reason, you will need to re-initialise MAAS to pick up the new IP address.
How to check the status of MAAS services
You can check the status of running services with:
sudo maas status
Typically, the output looks something like this:
bind9 RUNNING pid 7999, uptime 0:09:17
dhcpd STOPPED Not started
dhcpd6 STOPPED Not started
ntp RUNNING pid 8598, uptime 0:05:42
postgresql RUNNING pid 8001, uptime 0:09:17
proxy STOPPED Not started
rackd RUNNING pid 8000, uptime 0:09:17
regiond:regiond-0 RUNNING pid 8003, uptime 0:09:17
regiond:regiond-1 RUNNING pid 8008, uptime 0:09:17
regiond:regiond-2 RUNNING pid 8005, uptime 0:09:17
regiond:regiond-3 RUNNING pid 8015, uptime 0:09:17
tgt RUNNING pid 8040, uptime 0:09:15
It is also possible to re-initialise MAAS to switch modes. For example, to switch from rack to region:
sudo maas init region
How to list additional MAAS initialisation options
The init command can takes optional arguments. To list them, as well as read a brief description of each, you can enter:
sudo maas init --help
Once you’ve successfully installed MAAS (regardless of method), you can login to the MAAS CLI via the following process. First, generate the API-key for the user you’re going to employing:
sudo maas apikey --username=$PROFILE > api-key-file
Replace $PROFILE with whatever username you set during the createadmin part of the install process. Next, login with the following command:
maas login $PROFILE $MAAS_URL < api-key-file
Substitute $MAAS_URL with the URL that was returned to you when you initialised MAAS, for example, 192.168.43.251:5240/MAAS. Remember that, once you’ve logged in, you can get extensive CLI help with the command:
maas admin --help
Sample output is shown in the detail section below.
MAAS CLI help, sample output
usage: maas admin [-h] COMMAND …
Issue commands to the MAAS region controller at http://192.168.43.251:5240/MAAS/api/2.0/.
optional arguments: -h, –help show this help message and exit
drill down: COMMAND account Manage the current logged-in user. bcache-cache-set Manage bcache cache set on a machine. bcache-cache-sets Manage bcache cache sets on a machine. bcache Manage bcache device on a machine. bcaches Manage bcache devices on a machine. block-device Manage a block device on a machine. block-devices Manage block devices on a machine. boot-resource Manage a boot resource. boot-resources Manage the boot resources. boot-source Manage a boot source. boot-source-selection Manage a boot source selection. boot-source-selections Manage the collection of boot source selections. boot-sources Manage the collection of boot sources. commissioning-script Manage a custom commissioning script. commissioning-scripts Manage custom commissioning scripts. dhcpsnippet Manage an individual DHCP snippet. dhcpsnippets Manage the collection of all DHCP snippets in MAAS. dnsresource Manage dnsresource. dnsresource-record Manage dnsresourcerecord. dnsresource-records Manage DNS resource records (e.g. CNAME, MX, NS, SRV, TXT) dnsresources Manage dnsresources. device Manage an individual device. devices Manage the collection of all the devices in the MAAS. discoveries Query observed discoveries. discovery Read or delete an observed discovery. domain Manage domain. domains Manage domains. events Retrieve filtered node events. fabric Manage fabric. fabrics Manage fabrics. fan-network Manage Fan Network. fan-networks Manage Fan Networks. file Manage a FileStorage object. files Manage the collection of all the files in this MAAS. ipaddresses Manage IP addresses allocated by MAAS. iprange Manage IP range. ipranges Manage IP ranges. interface Manage a node’s or device’s interface. interfaces Manage interfaces on a node. license-key Manage a license key. license-keys Manage the license keys. maas Manage the MAAS server. machine Manage an individual machine. machines Manage the collection of all the machines in the MAAS. network Manage a network. networks Manage the networks. node Manage an individual Node. node-results Read the collection of commissioning script results. node-script Manage or view a custom script. node-script-result Manage node script results. node-script-results Manage node script results. node-scripts Manage custom scripts. nodes Manage the collection of all the nodes in the MAAS. notification Manage an individual notification. notifications Manage the collection of all the notifications in MAAS. package-repositories Manage the collection of all Package Repositories in MAAS. package-repository Manage an individual package repository. partition Manage partition on a block device. partitions Manage partitions on a block device. pod Manage an individual pod. pods Manage the collection of all the pod in the MAAS. rack-controller Manage an individual rack controller. rack-controllers Manage the collection of all rack controllers in MAAS. raid Manage a specific RAID (Redundant Array of Independent Disks) on a machine. raids Manage all RAIDs (Redundant Array of Independent Disks) on a machine. region-controller Manage an individual region controller. region-controllers Manage the collection of all region controllers in MAAS. resource-pool Manage a resource pool. resource-pools Manage resource pools. sshkey Manage an SSH key. sshkeys Manage the collection of all the SSH keys in this MAAS. sslkey Manage an SSL key. sslkeys Operations on multiple keys. space Manage space. spaces Manage spaces. static-route Manage static route. static-routes Manage static routes. subnet Manage subnet. subnets Manage subnets. tag Tags are properties that can be associated with a Node and serve as criteria for selecting and allocating nodes. tags Manage all tags known to MAAS. user Manage a user account. users Manage the user accounts of this MAAS. version Information about this MAAS instance. vlan Manage a VLAN on a fabric. vlans Manage VLANs on a fabric. vm-host Manage an individual vm-host. vm-hosts Manage the collection of all the vm-hosts in the MAAS. vmfs-datastore Manage VMFS datastore on a machine. vmfs-datastores Manage VMFS datastores on a machine. volume-group Manage volume group on a machine. volume-groups Manage volume groups on a machine. zone Manage a physical zone. zones Manage physical zones.
This is a profile. Any commands you issue on this profile will operate on the MAAS region server.
The command information you see here comes from the region server’s API; it may differ for different profiles. If you believe the API may have changed, use the command’s ‘refresh’ sub-command to fetch the latest version of this help information from the server.
Configuring MAAS consists of four broad steps:
This section will cover those four operations
After logging in for the first time, you will need to set a number of system-wide configuration options. First up, you should configure DNS. You can check out the help for DNS settings, known in the CLI as a “DNS forwarder”:
maas $PROFILE maas set-config name=upstream_dns value="8.8.8.8"
Here, we’ve set the DNS forwarder to “8.8.8.8” (Google), which is a reliable value.
How to set up SSH for the admin user
To add a public SSH key to a MAAS user account, type the following command:
maas $PROFILE sshkeys create "key=$SSH_KEY"
Before going any further, it’s worthwhile to start the image import, as it can sometimes take a few minutes. You can see what images you already have downloaded with this command:
maas $PROFILE boot-resources read | jq -r '.[] | "\(.name)\t\(.architecture)"'
This command will return a list similar to the following:
grub-efi-signed/uefi amd64/generic
grub-efi/uefi arm64/generic
grub-ieee1275/open-firmware ppc64el/generic
pxelinux/pxe i386/generic
ubuntu/bionic amd64/ga-18.04
ubuntu/bionic amd64/ga-18.04-lowlatency
ubuntu/bionic amd64/hwe-18.04
ubuntu/bionic amd64/hwe-18.04-edge
ubuntu/bionic amd64/hwe-18.04-lowlatency
ubuntu/bionic amd64/hwe-18.04-lowlatency-edge
Suppose you also want a version called “Trusty” – you can import a new image by first selecting it for download, like this:
maas $PROFILE boot-source-selections create 1 os="ubuntu" release="trusty" arches="amd64" subarches="*" labels="*"
which returns some JSON confirming your action:
Success.
Machine-readable output follows:
{
"os": "ubuntu",
"release": "trusty",
"arches": [
"amd64"
],
"subarches": [
"*"
],
"labels": [
"*"
],
"boot_source_id": 1,
"id": 2,
"resource_uri": "/MAAS/api/2.0/boot-sources/1/selections/2/"
}
Once selected, you can start the image import with this command:
maas admin boot-resources import
which offers a shorter confirmation message:
Success.
Machine-readable output follows:
Import of boot resources started
Once your image has been imported, you’ll want to get DHCP working, which means finding the untagged VLAN. In truth, it shouldn’t be too hard, because at this point, there still should only be one.
In order to turn on DHCP, you need to know two things besides the VLAN name (“untagged”): the fabric ID and the primary rack controller name. To start, all the fabrics will be on the same untagged VLAN, so any fabric will do. You can find a valid fabric ID by reading it from any subnet, so just pick one (e.g., 192.168.123.0/24) and find a usable fabric ID like this:
maas $PROFILE subnet read $SUBNET_CIDR | grep fabric_id
which returns (in this example):
"fabric_id": $FABRIC_ID,
Next, find the name of the primary rack controller. It’s usually fairly obvious, but for purposes of argument, assume that it’s not known. You can get it this way:
maas $PROFILE rack-controllers read | grep hostname | cut -d '"' -f 4
This returns a hostname, which we’ll call:
$RACK_CONTR_HOSTNAME
Finally, you need to create an IP range for DHCP, in this case, a dynamic range:
maas $PROFILE ipranges create type=dynamic start_ip=$START_IP end_ip=$END_IP
This command returns something similar to this sample output:
Success.
Machine-readable output follows:
{
"subnet": {
"name": "192.168.123.0/24",
"description": "",
"vlan": {
"vid": 0,
"mtu": 1500,
"dhcp_on": false,
"external_dhcp": null,
"relay_vlan": null,
"fabric": "fabric-2",
"primary_rack": null,
"name": "untagged",
"id": 5003,
"space": "undefined",
"secondary_rack": null,
"fabric_id": 2,
"resource_uri": "/MAAS/api/2.0/vlans/5003/"
},
"cidr": "192.168.123.0/24",
"rdns_mode": 2,
"gateway_ip": null,
"dns_servers": [],
"allow_dns": true,
"allow_proxy": true,
"active_discovery": false,
"managed": true,
"id": 4,
"space": "undefined",
"resource_uri": "/MAAS/api/2.0/subnets/4/"
},
"type": "dynamic",
"start_ip": "192.168.123.190",
"end_ip": "192.168.123.253",
"user": {
"is_superuser": true,
"username": "admin",
"email": "admin@admin.com",
"is_local": true,
"resource_uri": "/MAAS/api/2.0/users/admin/"
},
"comment": "",
"id": 1,
"resource_uri": "/MAAS/api/2.0/ipranges/1/"
}
So you should now be able to turn on DHCP like this:
maas $PROFILE vlan update $FABRIC_ID untagged dhcp_on=True primary_rack=$RACK_CONTR_HOSTNAME
If you’ve done everything correctly, you should see JSON output similar to this sample:
Success.
Machine-readable output follows:
{
"vid": 0,
"mtu": 1500,
"dhcp_on": true,
"external_dhcp": null,
"relay_vlan": null,
"fabric": "fabric-2",
"space": "undefined",
"primary_rack": "8dwnne",
"secondary_rack": null,
"name": "untagged",
"fabric_id": 2,
"id": 5003,
"resource_uri": "/MAAS/api/2.0/vlans/5003/"
}