--- title: How to get MAAS up and running description: Canonical makes open source secure, reliable and easy to use, providing support for Ubuntu and a portfolio of enterprise-grade technologies. Founded in 2004, Canonical operates globally with team members in over 80 countries. url: https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md --- *Submit* # How to get MAAS up and running This guide shows you how to install MAAS, set it up for either a Proof-of-Concept (POC) or a production environment, and verify that it is working. ## [Prerequisites](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-prerequisites) * A host running Ubuntu 22.04 LTS (Jammy) or newer. * Administrative privileges (sudo) on the host. * Network access to download snaps or packages. * (Production only) A PostgreSQL server (version 14 or newer recommended). * (Production only) A plan for DNS forwarder and DHCP scope. ## [Install MAAS](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-install-maas) ### [Option 1 – Snap (recommended)](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-option-1-snap-recommended) ``` sudo snap install --channel=/stable maas ``` Replace `` with the desired MAAS version (for example, `3.6`). ### [Option 2 – Debian packages](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-option-2-debian-packages) ``` sudo apt-add-repository ppa:maas/ sudo apt update sudo apt -y install maas ``` ## [Post-install setup](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-post-install-setup) ### [POC setup](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-poc-setup) Install the test database and initialize MAAS: ``` sudo snap install maas-test-db maas init --help ``` Follow the prompts to configure the POC environment. ### [Production setup](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-production-setup) 1. Disable conflicting NTP services: ``` sudo systemctl disable --now systemd-timesyncd ``` 2. Install and configure PostgreSQL: ``` sudo apt install -y postgresql sudo -i -u postgres psql -c "CREATE USER \"$DBUSER\" WITH ENCRYPTED PASSWORD '$DBPASS'" sudo -i -u postgres createdb -O "$DBUSER" "$DBNAME" ``` 3. Edit PostgreSQL authentication: Add this line to `/etc/postgresql/14/main/pg_hba.conf`: ``` host $DBNAME $DBUSER 0/0 md5 ``` 4. Initialize MAAS with the database: ``` sudo maas init region+rack --database-uri "postgres://$DBUSER:$DBPASS@$HOSTNAME/$DBNAME" ``` 5. Create an admin user: ``` sudo maas createadmin --username=$PROFILE --email=$EMAIL_ADDRESS ``` ## [Configure and start MAAS](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-configure-and-start-maas) ### [Check MAAS service status](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-check-maas-service-status) ``` sudo maas status ``` Example: ``` bind9 RUNNING dhcpd STOPPED postgresql RUNNING ``` ### [Web UI setup](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-web-ui-setup) 1. Open: `http://:5240/MAAS` 2. Log in with your admin credentials. 3. Configure: * DNS forwarder (e.g., `8.8.8.8`) * At least one Ubuntu LTS image * SSH key (Launchpad, GitHub, or upload from `~/.ssh/id_rsa.pub`) ### [CLI setup](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-cli-setup) 1. Log in: ``` maas login $PROFILE $MAAS_URL $(cat api-key-file) ``` 2. Configure DNS: ``` maas $PROFILE maas set-config name=upstream_dns value="8.8.8.8" ``` 3. Add an SSH key (`$SSH_KEY` must be set to a valid SSH key): ``` maas $PROFILE sshkeys create "key=$SSH_KEY" ``` ## [Enable DHCP](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-enable-dhcp) ### [Web UI](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-web-ui) * Go to Subnets > VLAN > Configure DHCP * Select options * Save and apply ### [CLI](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-cli) Find the subnet CIDR and fabric you want using this expression: ``` maas $PROFILE subnets read | jq -r ' ["subnet", "|", "fabric ID", "|", "gateway IP"], # header (.[] | [ .cidr, "|", (.vlan.fabric_id|tostring), "|", .gateway_ip ]) #rows | @tsv ' | column -t ``` Find the precise name of the primary rack controller with this expression, which always finds the primary rack, regardless of how many racks are active: ``` maas $PROFILE rack-controllers read | jq -r '.[] | .interface_set[] | .vlan?.primary_rack // empty' ``` Plug those values into the following commands to configure DHCP: ``` maas $PROFILE vlan update $FABRIC_ID untagged dhcp_on=True primary_rack=$PRIMARY_RACK_CONTROLLER maas $PROFILE subnet update $SUBNET_CIDR gateway_ip=$MY_GATEWAY ``` ## [Upgrading MAAS](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-upgrading-maas) ### [General steps](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-general-steps) 1. Backup your system and database. 2. Verify Ubuntu release (`lsb_release -a`). Upgrade to 22.04 Jammy or 24.04 Noble as required. 3. Verify PostgreSQL version (14 required, 16 recommended). 4. Upgrade rack nodes first, then region nodes. ### [Upgrade commands](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-upgrade-commands) * Snap ``` sudo snap refresh maas --channel=/stable ``` * Debian package (PPA) ``` sudo apt-add-repository ppa:maas/ sudo apt update && sudo apt upgrade maas ``` ### [Version-specific notes](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-version-specific-notes) * MAAS 3.6: PostgreSQL 14+ supported; PostgreSQL 16 recommended. * MAAS 3.5: Requires PostgreSQL 14. * MAAS 3.3: PostgreSQL 12 deprecated. Upgrade to 14 before proceeding. * MAAS 2.8 or earlier: Full backup required. Fresh install recommended if upgrade fails. ## [Troubleshooting notes](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-troubleshooting-notes) * NTP conflicts: ``` sudo systemctl disable --now systemd-timesyncd ``` * BMC migration (3.3+): Ensure unique BMC IP/username/password combinations. ## [Verification](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-verification) After installation or upgrade: ``` lsb_release -a # Verify Ubuntu release maas --version # Verify MAAS version sudo maas status # Verify services running ``` ## [Related documentation](https://canonical-com-2934.demos.haus/maas/docs/how-to-get-maas-up-and-running?format=md#p-9034-related-documentation) * [About controllers](https://canonical.com/maas/docs/about-controllers) * [Back up MAAS](https://canonical.com/maas/docs/how-to-back-up-maas) * [Networking in MAAS](https://canonical.com/maas/docs/about-maas-networking) --- [Previous How-to guides](https://canonical-com-2934.demos.haus/maas/docs/how-to-guides) [Next Back up MAAS](https://canonical-com-2934.demos.haus/maas/docs/how-to-back-up-maas) Last updated 1 year, 12 days ago. [Help improve this document in the forum](https://discourse.maas.io/t/how-to-get-maas-up-and-running/5128).