| CARVIEW |
Select Language
HTTP/2 301
server: nginx/1.14.0 (Ubuntu)
date: Mon, 29 Dec 2025 07:40:35 GMT
content-type: text/html
content-length: 194
location: https://canonical.com/maas/install
x-cache-status: from content-cache-il3/0
HTTP/2 302
server: nginx/1.14.0 (Ubuntu)
date: Mon, 29 Dec 2025 07:40:36 GMT
content-type: text/html; charset=utf-8
content-length: 247
location: /maas/docs/how-to-install-maas
content-security-policy: default-src 'self'; img-src data: blob: *; script-src-elem 'self' assets.ubuntu.com www.google-analytics.com www.googletagmanager.com www.youtube.com asciinema.org player.vimeo.com script.crazyegg.com www.googleadservices.com js.zi-scripts.com *.g.doubleclick.net www.google.com www.gstatic.com www.brighttalk.com snap.licdn.com connect.facebook.net maps.googleapis.com www.redditstatic.com munchkin.marketo.net w.usabilla.com api.usabilla.com *.googlesyndication.com cdn.jsdelivr.net https://esm.sh https://cdn.jsdelivr.net buttons.github.io cdn.livechatinc.com api.livechatinc.com secure.livechatinc.com 'unsafe-inline'; font-src 'self' assets.ubuntu.com fonts.google.com cdn.livechatinc.com secure.livechatinc.com; script-src 'self' blob: 'unsafe-eval' 'unsafe-hashes' 'unsafe-inline'; connect-src 'self' www.google.com ubuntu.com analytics.google.com www.googletagmanager.com sentry.is.canonical.com www.google-analytics.com *.crazyegg.com *.g.doubleclick.net js.zi-scripts.com *.google-analytics.com px.ads.linkedin.com ws.zoominfo.com youtube.com google.com fonts.google.com maps.googleapis.com pixel-config.reddit.com www.redditstatic.com conversions-config.reddit.com https://esm.sh https://lottie.host https://cdn.jsdelivr.net *.analytics.google.com www.facebook.com *.googlesyndication.com *.mktoresp.com assets.ubuntu.com api.github.com api.livechatinc.com cdn.livechatinc.com secure.livechatinc.com web.facebook.com; frame-src 'self' *.doubleclick.net www.youtube.com/ asciinema.org player.vimeo.com www.googletagmanager.com www.google.com www.brighttalk.com cdn.livechatinc.com secure.livechatinc.com cdn.livechat-static.com; style-src 'self' cdn.jsdelivr.net 'unsafe-inline'; media-src 'self' res.cloudinary.com assets.ubuntu.com; child-src 'self' blob: youtube.com google.com fonts.google.com api.livechatinc.com cdn.livechatinc.com secure.livechatinc.com;
referrer-policy: strict-origin-when-cross-origin
cross-origin-embedder-policy: unsafe-none
cross-origin-opener-policy: same-origin-allow-popups
cross-origin-resource-policy: cross-origin
x-permitted-cross-domain-policies: none
vary: Accept-Encoding
x-view-name: canonicalwebteam.templatefinder.templatefinder.template_finder
x-clacks-overhead: GNU Terry Pratchett
permissions-policy: interest-cohort=()
x-frame-options: SAMEORIGIN
x-content-type-options: NOSNIFF
x-vcs-revision: 1766157328-5b097a5
x-request-id: 259d8257e5f6f2b5b64f90f7253c0988
strict-transport-security: max-age=15724800
link: ; rel=preconnect; crossorigin, ; rel=preconnect
x-cache-status: MISS from content-cache-il3/2
HTTP/2 302
server: nginx/1.14.0 (Ubuntu)
date: Mon, 29 Dec 2025 07:40:37 GMT
content-type: text/html; charset=utf-8
content-length: 269
location: /maas/docs/how-to-get-maas-up-and-running
content-security-policy: default-src 'self'; img-src data: blob: *; script-src-elem 'self' assets.ubuntu.com www.google-analytics.com www.googletagmanager.com www.youtube.com asciinema.org player.vimeo.com script.crazyegg.com www.googleadservices.com js.zi-scripts.com *.g.doubleclick.net www.google.com www.gstatic.com www.brighttalk.com snap.licdn.com connect.facebook.net maps.googleapis.com www.redditstatic.com munchkin.marketo.net w.usabilla.com api.usabilla.com *.googlesyndication.com cdn.jsdelivr.net https://esm.sh https://cdn.jsdelivr.net buttons.github.io cdn.livechatinc.com api.livechatinc.com secure.livechatinc.com 'unsafe-inline'; font-src 'self' assets.ubuntu.com fonts.google.com cdn.livechatinc.com secure.livechatinc.com; script-src 'self' blob: 'unsafe-eval' 'unsafe-hashes' 'unsafe-inline'; connect-src 'self' www.google.com ubuntu.com analytics.google.com www.googletagmanager.com sentry.is.canonical.com www.google-analytics.com *.crazyegg.com *.g.doubleclick.net js.zi-scripts.com *.google-analytics.com px.ads.linkedin.com ws.zoominfo.com youtube.com google.com fonts.google.com maps.googleapis.com pixel-config.reddit.com www.redditstatic.com conversions-config.reddit.com https://esm.sh https://lottie.host https://cdn.jsdelivr.net *.analytics.google.com www.facebook.com *.googlesyndication.com *.mktoresp.com assets.ubuntu.com api.github.com api.livechatinc.com cdn.livechatinc.com secure.livechatinc.com web.facebook.com; frame-src 'self' *.doubleclick.net www.youtube.com/ asciinema.org player.vimeo.com www.googletagmanager.com www.google.com www.brighttalk.com cdn.livechatinc.com secure.livechatinc.com cdn.livechat-static.com; style-src 'self' cdn.jsdelivr.net 'unsafe-inline'; media-src 'self' res.cloudinary.com assets.ubuntu.com; child-src 'self' blob: youtube.com google.com fonts.google.com api.livechatinc.com cdn.livechatinc.com secure.livechatinc.com;
referrer-policy: strict-origin-when-cross-origin
cross-origin-embedder-policy: unsafe-none
cross-origin-opener-policy: same-origin-allow-popups
cross-origin-resource-policy: cross-origin
x-permitted-cross-domain-policies: none
vary: Accept-Encoding
x-view-name: canonicalwebteam.discourse.app.docs.document_view
x-clacks-overhead: GNU Terry Pratchett
permissions-policy: interest-cohort=()
x-frame-options: SAMEORIGIN
x-content-type-options: NOSNIFF
x-vcs-revision: 1766157328-5b097a5
x-request-id: 3c214fec308293c354dab4459006e098
strict-transport-security: max-age=15724800
link: ; rel=preconnect; crossorigin, ; rel=preconnect
x-cache-status: MISS from content-cache-il3/2
HTTP/2 200
server: nginx/1.14.0 (Ubuntu)
date: Mon, 29 Dec 2025 07:40:37 GMT
content-type: text/html; charset=utf-8
content-length: 23119
discourse-warning: Could not parse URL map item {'hidden': False, 'level': 3, 'path': 'reference-api-documentation', 'navlink_href': '/maas/docs/api', 'navlink_fragment': '', 'navlink_text': 'API reference', 'is_active': False, 'has_active_child': False, 'children': []}
discourse-warning: Redirect path /maas/docs/reference-release-notes-maas-3-5 clashes with URL map
discourse-warning: Redirect path /maas/docs/reference-release-notes-maas-3-4 clashes with URL map
discourse-warning: Could not parse URL map item {'hidden': False, 'level': 3, 'path': 'reference-api-documentation', 'navlink_href': '/maas/docs/api', 'navlink_fragment': '', 'navlink_text': 'API reference', 'is_active': False, 'has_active_child': False, 'children': []}
discourse-warning: Redirect path /maas/docs/reference-release-notes-maas-3-5 clashes with URL map
discourse-warning: Redirect path /maas/docs/reference-release-notes-maas-3-4 clashes with URL map
content-security-policy: default-src 'self'; img-src data: blob: *; script-src-elem 'self' assets.ubuntu.com www.google-analytics.com www.googletagmanager.com www.youtube.com asciinema.org player.vimeo.com script.crazyegg.com www.googleadservices.com js.zi-scripts.com *.g.doubleclick.net www.google.com www.gstatic.com www.brighttalk.com snap.licdn.com connect.facebook.net maps.googleapis.com www.redditstatic.com munchkin.marketo.net w.usabilla.com api.usabilla.com *.googlesyndication.com cdn.jsdelivr.net https://esm.sh https://cdn.jsdelivr.net buttons.github.io cdn.livechatinc.com api.livechatinc.com secure.livechatinc.com 'unsafe-inline'; font-src 'self' assets.ubuntu.com fonts.google.com cdn.livechatinc.com secure.livechatinc.com; script-src 'self' blob: 'unsafe-eval' 'unsafe-hashes' 'unsafe-inline'; connect-src 'self' www.google.com ubuntu.com analytics.google.com www.googletagmanager.com sentry.is.canonical.com www.google-analytics.com *.crazyegg.com *.g.doubleclick.net js.zi-scripts.com *.google-analytics.com px.ads.linkedin.com ws.zoominfo.com youtube.com google.com fonts.google.com maps.googleapis.com pixel-config.reddit.com www.redditstatic.com conversions-config.reddit.com https://esm.sh https://lottie.host https://cdn.jsdelivr.net *.analytics.google.com www.facebook.com *.googlesyndication.com *.mktoresp.com assets.ubuntu.com api.github.com api.livechatinc.com cdn.livechatinc.com secure.livechatinc.com web.facebook.com; frame-src 'self' *.doubleclick.net www.youtube.com/ asciinema.org player.vimeo.com www.googletagmanager.com www.google.com www.brighttalk.com cdn.livechatinc.com secure.livechatinc.com cdn.livechat-static.com; style-src 'self' cdn.jsdelivr.net 'unsafe-inline'; media-src 'self' res.cloudinary.com assets.ubuntu.com; child-src 'self' blob: youtube.com google.com fonts.google.com api.livechatinc.com cdn.livechatinc.com secure.livechatinc.com;
referrer-policy: strict-origin-when-cross-origin
cross-origin-embedder-policy: unsafe-none
cross-origin-opener-policy: same-origin-allow-popups
cross-origin-resource-policy: cross-origin
x-permitted-cross-domain-policies: none
vary: Accept-Encoding
content-encoding: gzip
x-view-name: canonicalwebteam.discourse.app.docs.document_view
x-clacks-overhead: GNU Terry Pratchett
permissions-policy: interest-cohort=()
cache-control: max-age=60, stale-while-revalidate=86400, stale-if-error=300
x-frame-options: SAMEORIGIN
x-content-type-options: NOSNIFF
x-vcs-revision: 1765980830-6ff684b
x-request-id: 28d3427baed3c9f930dcc87c54e13215
strict-transport-security: max-age=15724800
link: ; rel=preconnect; crossorigin, ; rel=preconnect
x-cache-status: STALE from content-cache-il3/2
accept-ranges: bytes
How to get MAAS up and running
Skip to main content
Your submission was sent successfully! Close
Thank you for signing up for our newsletter!
In these regular emails you will find the latest updates from Canonical and upcoming events where you can meet our team.Close
Thank you for contacting us. A member of our team will be in touch shortly. Close
An error occurred while submitting your form. Please try again or file a bug report. Close
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
- 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
Option 1 – Snap (recommended)
sudo snap install --channel=<version>/stable maas
Replace <version> with the desired MAAS version (for example, 3.6).
Option 2 – Debian packages
sudo apt-add-repository ppa:maas/<version>
sudo apt update
sudo apt -y install maas
Post-install setup
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
-
Disable conflicting NTP services:
sudo systemctl disable --now systemd-timesyncd -
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" -
Edit PostgreSQL authentication:
Add this line to/etc/postgresql/14/main/pg_hba.conf:host $DBNAME $DBUSER 0/0 md5 -
Initialize MAAS with the database:
sudo maas init region+rack --database-uri "postgres://$DBUSER:$DBPASS@$HOSTNAME/$DBNAME" -
Create an admin user:
sudo maas createadmin --username=$PROFILE --email=$EMAIL_ADDRESS
Configure and start MAAS
Check MAAS service status
sudo maas status
Example:
bind9 RUNNING
dhcpd STOPPED
postgresql RUNNING
Web UI setup
- Open:
https://<API_HOST>:5240/MAAS - Log in with your admin credentials.
- 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)
- DNS forwarder (e.g.,
CLI setup
- Log in:
maas login $PROFILE $MAAS_URL $(cat api-key-file) - Configure DNS:
maas $PROFILE maas set-config name=upstream_dns value="8.8.8.8" - Add an SSH key (
$SSH_KEYmust be set to a valid SSH key):maas $PROFILE sshkeys create "key=$SSH_KEY"
Enable DHCP
Web UI
- Go to Subnets > VLAN > Configure DHCP
- Select options
- Save and apply
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
General steps
- Backup your system and database.
- Verify Ubuntu release (
lsb_release -a). Upgrade to 22.04 Jammy or 24.04 Noble as required. - Verify PostgreSQL version (14 required, 16 recommended).
- Upgrade rack nodes first, then region nodes.
Upgrade commands
-
Snap
sudo snap refresh maas --channel=<version>/stable -
Debian package (PPA)
sudo apt-add-repository ppa:maas/<version> sudo apt update && sudo apt upgrade maas
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
- NTP conflicts:
sudo systemctl disable --now systemd-timesyncd - BMC migration (3.3+): Ensure unique BMC IP/username/password combinations.
Verification
After installation or upgrade:
lsb_release -a # Verify Ubuntu release
maas --version # Verify MAAS version
sudo maas status # Verify services running
Related documentation
Last updated 3 months ago. Help improve this document in the forum.