Offline docs (switch to live docs)                          UI-only  CLI-only

Bootstrap MAAS

Modern data centers and cloud infrastructure rely heavily on efficient hardware management to ensure optimal performance and scalability. Metal as a Service, or MAAS, stands as a pivotal solution in this landscape. MAAS empowers organizations to unlock the full potential of their hardware resources by transforming bare-metal servers into a dynamic, easily configurable resource pool. In this chapter, you'll embark on a journey into the world of MAAS, learning how to harness its capabilities to streamline hardware provisioning and management like a seasoned pro.

MAAS operates at the intersection of hardware orchestration and cloud-like flexibility. Imagine being able to rapidly deploy servers with precision, allocate resources on demand, and effortlessly scale your infrastructure—all from a centralized and user-friendly interface. Whether you're running a small data center or managing a sprawling cloud ecosystem, MAAS is designed to help you make the most of your hardware investments. We'll explore the installation, configuration, and operation of MAAS, empowering you to take full control of your hardware resources with ease.

As you embark on this MAAS tutorial, prepare to delve into the intricacies of hardware management with confidence. Whether you're a sysadmin, a cloud architect, or a DevOps enthusiast, MAAS equips you with the tools to simplify and automate complex tasks. From initial setup to advanced orchestration, you'll learn how to bootstrap and manage your hardware infrastructure efficiently, setting the stage for seamless scalability and resource allocation. Let's dive in and unlock the potential of MAAS together.


Before you embark on your journey to master MAAS, it's essential to ensure that you have the necessary prerequisites in place. While MAAS is designed to simplify hardware management, a few foundational components and requirements must be met to get started.

  1. Hardware Infrastructure: First and foremost, you'll need access to the hardware infrastructure you intend to manage with MAAS. This includes servers, machines, or devices that you plan to commission, enlist, and deploy. Ensure that these systems are connected to your network and meet the minimum hardware requirements for MAAS.

  2. Operating System Knowledge: Familiarity with the Ubuntu operating system is highly beneficial, as MAAS is tightly integrated with Ubuntu. Understanding Linux-based systems and basic command-line operations will be advantageous as you navigate MAAS's configuration and management.

  3. Network Configuration: A solid grasp of network fundamentals is crucial. You should have knowledge of IP addressing, subnetting, DNS, and DHCP configuration, as MAAS relies on these network services to function effectively. It may also help to know just a little about modern cloud architectures. Ensure that your network is correctly configured and accessible from the machines you plan to manage.

  4. Access to MAAS Server: You'll need access to a machine or server where MAAS will be installed and configured. This server should have network connectivity to both the managed hardware and the internet, as MAAS may require package downloads during installation and updates.

  5. Administrator Privileges: To install and configure MAAS, you may need administrative privileges on the machines where MAAS will be deployed. Ensure that you can execute commands with sudo or have root access.

By satisfying these prerequisites, you'll be well-prepared to dive into the world of MAAS with confidence. With the foundational elements in place, you can proceed to install and configure MAAS effectively and begin managing your hardware resources efficiently.


Before you can harness the power of Metal as a Service (MAAS) to streamline your hardware management, you'll need to get it up and running on your Ubuntu host. This installation process involves a series of carefully orchestrated steps to ensure that MAAS operates smoothly and efficiently. By following these instructions diligently, you'll pave the way for a robust hardware management infrastructure that can scale with your needs. Let's dive into the installation journey, one step at a time, and unlock the potential of MAAS on your Ubuntu host.

To install MAAS on your Ubuntu host:

  1. Update your package index and install dependencies:

    bash sudo apt update sudo apt install snapd lxd lxd-client python3-lxc python3-openstackclient

  2. Install the MAAS snap package:

    bash sudo snap install maas --classic

  3. Install the PostgreSQL database:

    bash sudo apt install postgresql postgresql-contrib

  4. Switch to the postgres user and open the PostgreSQL shell:

    bash sudo su - postgres psql

  5. Create a database user for MAAS:

    sql CREATE USER maas WITH PASSWORD 'password';

  6. Create the MAAS database:

    sql CREATE DATABASE maasdb OWNER maas;

  7. Exit PostgreSQL and return to your regular user:

    \q exit

  8. Edit /etc/postgresql/12/main/pg_hba.conf, adding a line like the one below, to allow the MAAS user to connect:

    ```bash sudo vi /etc/postgresql/12/main/pg_hba.conf host $MAAS_DBNAME $MAAS_DBUSER 0/0 md5

  9. Initialize MAAS, specifying the PostgreSQL URL:

    sudo maas init region+rack --database-uri postgres://maas:password@localhost/maasdb

  10. Visit the web UI and create your admin account.

MAAS is now installed, and you've taken the crucial first steps towards efficient hardware management. But this is just the beginning of your journey with MAAS. With the core installation completed, you're ready to explore its powerful features and capabilities. In the upcoming section, we'll delve deeper into configuring and optimizing MAAS, commissioning and deploying nodes, and integrating it seamlessly into your infrastructure.

Initial configuration

Now that you've successfully installed MAAS, it's time to fine-tune your environment for optimal hardware management. This phase of configuration ensures that MAAS operates seamlessly, allowing you to efficiently manage your resources. We'll walk you through the essential steps, from accessing the web-based interface to configuring DNS settings, SSH keys, and more. By the end of this section, your MAAS installation will be finely tuned and ready to take on the task of managing and provisioning nodes.

After installing, complete the initial configuration:

  1. Access MAAS at this address, where $API_HOST is the MAAS URL which was generated earlier:

    bash http://${API_HOST}:5240/MAAS

Log in using the login information you created when initializing MAAS.

  1. In the web UI, go to Settings > General and set a forward DNS server, such as "".

  2. Under Images, select the Ubuntu release to sync; you can usually accept the default.

  3. Under Accounts, import your SSH public key from Launchpad or GitHub, or upload your existing public key. Follow the on-screen instructions.

  4. Review remaining config options like proxy usage, NTP, etc.

MAAS can now manage and provision nodes.

Setting up LXD

For this tutorial, we'll use LXD containers, alongside any physical servers you may choose to enlist:

  1. Install the LXD snap:

    sudo snap install lxd

  2. Initialize the LXD configuration:

    sudo lxd init

    Choose appropriate options for networking, storage pools, etc.

  3. Disable LXD's built-in DHCP server:

    lxc network set lxdbr0 ipv4.dhcp=false

Configuring Networking and DHCP

Finally, you'll need to configure DHCP on the subnet that bridges the LXD instance:

  1. Identify the LXD bridge IP address:

    ip addr show lxdbr0

  2. In MAAS, go to Subnets and identify the VLAN for that subnet.

  3. Select the VLAN and configure DHCP with the bridge IP as the gateway.

MAAS now provides networking and DHCP for provisioning. Your hardware resources are now under the watchful eye of MAAS, ready to be deployed, managed, and scaled as needed. In the following sections, we'll delve into more advanced topics, ensuring that you make the most of this powerful tool. So, stay tuned, and let's continue the exploration of MAAS as you take your hardware management to the next level.

Bootstrapping a virtual machine

With MAAS installed and configured, you now have the foundation for streamlined hardware management -- but we've only just scratched the surface of MAAS's capabilities. Now it's time to take things to the next level by bootstrapping your MAAS environment.

Bootstrapping is the process of adding and commissioning machines, so that MAAS has something to manage. By bootstrapping, you empower MAAS to take control of your infrastructure and begin managing nodes.

Let's walk through the bootstrapping process together. We'll create a couple of LXD test machines to see MAAS in action. You'll learn how to use the MAAS UI to:

With these key skills under your belt, you'll gain hands-on experience bringing machines under MAAS's control. The bootstrapping journey marks a major milestone, equipping you with the knowledge to automate node deployment at scale.

Create a VM host

You can use physical or virtual machines with MAAS. Since there are so many variations of physical hardware -- and potentially a lot of configuration steps -- we'll simplify this exercise by using LXD as a VM host.

To create a LXD VM host (with a MAAS-generated certificate):

  1. Select KVM > LXD.

  2. Select Add KVM.

  3. Enter a Name for the KVM host.

  4. Optionally, select a non-default Zone.

  5. Optionally, select a non-default Resource pool.

  6. Enter the LXD address as the gateway address of the bridge for that LXD instance. For example, if lxdbr0 has address, the default gateway address is

  7. Select Generate new certificate.

  8. Select Next.

  9. Select Add trust to LXD via command line.

  10. Copy the bash command and certificate from the text box.

  11. In a terminal, paste the copied command and make sure that it runs.

  12. Select Check authentication. You'll switch screens; if all goes well, you'll see Connected with a green check-mark.

  13. Select Add new project or Select existing project. Be aware that if you select an existing project, any VMs already in that project will begin to commission.

  14. Select Next. You will drop out to a dashboard for the VM host.

You can then add virtual machines to this new VM host as desired.

Add a LXD virtual machine

MAAS automatically commissions newly-added machines. "Commissioning" just means that MAAS boots the machine with a special, ephemeral (in-RAM) version of Ubuntu, and then uses that version to learn everything it can about the hardware. This smooths the deployment process later.

To add a virtual machine from the MAAS UI:

  1. Select KVM > .

  2. Select the desired VM host by clicking on its name.

  3. Select *Add VM".

  4. Optionally enter the VM name.

  5. Select Use any available core(s) or Pin VM to specific core(s), as desired. Enter specific core identities as appropriate.

  6. Enter the RAM desired.

  7. Select Show advanced if you want to edit the Domain, Zone, Resource pool, or Architecture. Make those changes as desired.

  8. Optionally Define interfaces.

  9. Optionally Add disks.

  10. Select Compose machine to create the virtual machine.

You can switch from here to the Machine list to watch the commissioning process in action.

Acquiring a "Ready" machine

Acquisition -- also called allocation by a quirk of terminology -- claims the machine for your use. Once you've acquired it, nobody else can control it until you release it:

  1. Select a machine which is in the "Ready" state.

  2. Drop down the Take action menu.

  3. Select Allocate and confirm your choice on the following screen.

MAAS will allocate the selected machine for your exclusive use. You can now find it in the list of "Allocated" machines.

Deploying your newly acquired machine

Deployment is the pivotal moment where your newly-acquired machine becomes useful. Later on, you'll learn how to use cloud-init to deploy specific workloads; for now, we'll just get it up and running, and then log into it with SSH to examine the results.

To deploy directly from MAAS,

  1. Select an allocated machine and choose Deploy.

  2. On the follow-on options screen, don't worry about deviating from the default OS, release, and kernel, at least not for now.

  3. When you're ready, press Deploy... to get the machine up and running.

While deploying, the status will change several times, as MAAS steps through the process. Once finished, the status settles on the name of the OS (e.g. 'Ubuntu 18.04 LTS').

Admiring your handiwork

As long as you've added your SSH key to MAAS, you can connect to the newly-deployed machine. SSH to the machine's IP with username ubuntu; there's no password, since you're using your SSH key to login. Explore the machine you just fielded. You can type sudo -i for root access.

For further study

In this tutorial, we've effectively transformed a blank canvas into a fully operational server, showcasing the way MAAS automates and streamlines server provisioning. There's a lot more to learn:

Hopefully, this short walk-through gave you some confidence to explore further.