<!DOCTYPE html> <html lang="en" dir="ltr" itemscope itemtype="http://schema.org/Product" prefix="og: http://ogp.me/ns#"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title itemprop="name">MAAS | How to install MAAS </title>  <script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-1018242-58', 'auto', {'allowLinker': true, 'siteSpeedSampleRate': 100}); ga('require', 'GTM-N953L4W'); ga('require', 'linker'); ga('linker:autoLink', ['conjure-up.io', 'login.ubuntu.com', 'www.ubuntu.com', 'ubuntu.com', 'insights.ubuntu.com', 'developer.ubuntu.com', 'cn.ubuntu.com', 'design.ubuntu.com', 'maas.io', 'canonical.com', 'landscape.canonical.com', 'pages.ubuntu.com', 'tutorials.ubuntu.com', 'docs.ubuntu.com']); </script>   <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-P4TGJR9');</script>   <script src="/static/js/ga.js" defer></script> <script src="/static/js/navigation.js" defer></script> <script src="https://assets.ubuntu.com/v1/703e23c9-lazysizes+noscript+native-loading.5.1.2.min.js" defer></script> <script type="module" src="https://md-block.verou.me/md-block.js"></script>  <link rel="stylesheet" type="text/css" media="screen" href="/static/css/main.css?v=7363de0" /> <link rel="icon" type="image/png" href="https://assets.ubuntu.com/v1/c555447f-maas-2022-favicon-16.png" sizes="16x16" /> <link rel="icon" type="image/png" href="https://assets.ubuntu.com/v1/6cce4f7c-maas-2022-favicon-32.png" sizes="32x32" /> <link rel="icon" type="image/png" href="https://assets.ubuntu.com/v1/bdcff402-maas-2022-favicon-64.png" sizes="64x64" /> <link rel="icon" type="image/png" href="https://assets.ubuntu.com/v1/7baeacdb-maas-2022-favicon-128.png" sizes="128x128" /> <meta name="google-site-verification" content="oJqEviYsw1FaDzCq7kzhewyJ2enm5vk9Q-prliavhjw" /> <meta name="description" content="MAAS (Metal as a Service) offers cloud style provisioning for physical servers. It is open source and free to use, with commercial support available from Canonical." /> <meta name="twitter:card" content="summary"> <meta name="twitter:site" content="@ubuntucloud"> <meta name="twitter:creator" content="@ubuntucloud"> <meta name="twitter:domain" content="maas.io"> <meta name="twitter:title" content="How to install MAAS"> <meta name="twitter:description" content="MAAS (Metal as a Service) offers cloud style provisioning for physical servers. It is open source and free to use, with commercial support available from Canonical."> <meta name="twitter:image" content="https://assets.ubuntu.com/v1/85274a82-maas-social-banner.png"> <meta property="og:type" content="website"> <meta property="og:url" content="https://maas.io/"> <meta property="og:site_name" content="MAAS"> <meta property="og:title" content="How to install MAAS"> <meta property="og:description" content="MAAS (Metal as a Service) offers cloud style provisioning for physical servers. It is open source and free to use, with commercial support available from Canonical."> <meta property="og:image" content="https://assets.ubuntu.com/v1/85274a82-maas-social-banner.png"> </head> <body class="docs"> <div class="l-docs"> <div class="l-docs__header"> <header id="navigation" class="p-navigation"> <div class="l-docs__subgrid"> <div class="l-docs__sidebar"> <div class="p-navigation__banner"> <div class="p-navigation__tagged-logo"> <a class="p-navigation__link" href="/"> <div class="p-navigation__logo-tag"> <img class="p-navigation__logo-icon" src="https://assets.ubuntu.com/v1/0a863174-MAAS+logomark+only.svg" alt=""> </div> <span class="p-navigation__logo-title">Canonical MAAS</span> </a> </div> <a href="#navigation" class="p-navigation__toggle--open" title="menu">Menu</a> <a href="#navigation-closed" class="p-navigation__toggle--close" title="close menu">Close menu</a> </div> </div> <div class="l-docs__main"> <div class="p-navigation__row u-fixed-width"> <nav class="p-navigation__nav" aria-label="main"> <ul id="main-navigation" class="global-nav p-navigation__items u-clearfix"> <li class="p-navigation__item"> <a class="p-navigation__link" href="/how-it-works" onclick="dataLayer.push({'event' : 'GAEvent' , 'eventCategory' : 'Main navigation' , 'eventAction' : 'Click' , 'eventLabel' : 'How it works' });">How it works</a> </li> <li class="p-navigation__item"> <a class="p-navigation__link" href="/install" onclick="dataLayer.push({'event' : 'GAEvent' , 'eventCategory' : 'Main navigation' , 'eventAction' : 'Click' , 'eventLabel' : 'Install' });">Install</a> </li> <li class="p-navigation__item is-selected" aria-current="page"> <a class="p-navigation__link" href="/docs" onclick="dataLayer.push({'event' : 'GAEvent', 'eventCategory' : 'Main navigation' , 'eventAction' : 'Click' , 'eventLabel' : 'Docs' });">Docs</a> </li> <li class="p-navigation__item--dropdown-toggle" id="learn"> <a href="#learn-menu" aria-controls="learn-menu" class="p-navigation__link">Learn</a> <ul class="p-navigation__dropdown" id="learn-menu" aria-hidden="true"> <li> <a class="p-navigation__dropdown-item" href="/tour" onclick="dataLayer.push({'event' : 'GAEvent' , 'eventCategory' : 'Main navigation' , 'eventAction' : 'Click' , 'eventLabel' : 'Tour' });">Features</a> </li> <li> <a class="p-navigation__dropdown-item" href="/tutorials" onclick="dataLayer.push({'event' : 'GAEvent', 'eventCategory' : 'Main navigation' , 'eventAction' : 'Click' , 'eventLabel' : 'Tutorials' });">Tutorials</a> </li> <li> <a class="p-navigation__dropdown-item" href="/resources" onclick="dataLayer.push({'event' : 'GAEvent', 'eventCategory' : 'Main navigation' , 'eventAction' : 'Click' , 'eventLabel' : 'Resources' });">Understand MAAS</a> </li> <li> <a class="p-navigation__dropdown-item" href="/blog" onclick="dataLayer.push({'event' : 'GAEvent', 'eventCategory' : 'Main navigation' , 'eventAction' : 'Click' , 'eventLabel' : 'Blog' });">Blog</a> </li> </ul> </li> <li class="p-navigation__item"> <a class="p-navigation__link" href="https://discourse.maas.io" onclick="dataLayer.push({'event' : 'GAEvent', 'eventCategory' : 'Main navigation' , 'eventAction' : 'Click' , 'eventLabel' : 'Discourse' });">Forum</a> </li> </ul> </nav> </div> </div> </div> </header> <section id="search-docs" class="p-strip--light is-shallow is-bordered l-docs__subgrid"> <div class="l-docs__main"> <div class="row"> <form class="p-search-box u-no-margin--bottom" action="/docs/search"> <input type="search" class="p-search-box__input" name="q" placeholder="Search documentation" required/> <button type="reset" class="p-search-box__reset" alt="reset"><i class="p-icon--close">Close</i></button> <button type="submit" class="p-search-box__button" alt="search"><i class="p-icon--search">Search</i></button> </form> </div> </div> </section> </div> <div class="l-docs__sidebar"> <div class="l-docs__sticky-container"> <nav data-js="navigation" class="p-side-navigation" id="default" style="margin-top: 0.5rem"> <div class="u-fixed-width"> <a href="#default" class="p-side-navigation__toggle js-drawer-toggle" aria-controls="default"> Toggle side navigation </a> </div> <div class="p-side-navigation__overlay js-drawer-toggle" aria-controls="default"></div> <div class="p-side-navigation__drawer"> <div class="p-side-navigation__drawer-header"> <a href="#" class="p-side-navigation__toggle--in-drawer js-drawer-toggle" aria-controls="default"> Toggle side navigation </a> </div> <h3 class="p-side-navigation__heading--linked"> <a class="p-side-navigation__link" href="/docs" > MAAS Documentation </a> </h3> <ul class="p-side-navigation__list"> </ul> <ul class="p-side-navigation__list"> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/maas-in-thirty-minutes" >Tutorial: MAAS in thirty minutes</a> <ul class="p-side-navigation__list"> </ul> </li> </ul> <ul class="p-side-navigation__list"> <li class="p-side-navigation__item"> <a class="p-side-navigation__link is-expandable" href="/docs/how-to-guides" aria-expanded="false" >How-to guides</a> <button class="p-side-navigation__expand" aria-expanded="true" aria-label="show submenu for How-to guides"></button> <ul class="p-side-navigation__list"> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-manage-your-maas-workflow" >Manage MAAS workflow</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-install-maas" aria-current="page" >Install MAAS</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-back-up-maas" >Back up MAAS</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-manage-maas-networks" >Manage networks</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-manage-machines" >Manage machines</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-manage-machine-groups" >Manage machine groups</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-manage-images" >Manage images</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-use-logging" >Use logging</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-monitor-maas" >Monitor MAAS</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-enhance-maas-security" >Enhance MAAS security</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-enable-high-availability" >Enable high availability</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-build-maas-images" >Build MAAS images</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-build-an-ubuntu-image" >Build Ubuntu</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-deploy-vms-on-ibm-z" >Deploy VMs on IBM Z</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-deploy-a-real-time-kernel" >Deploy a real-time kernel</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-deploy-a-fips-compliant-kernel" >Deploy a FIPS kernel</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-configure-an-air-gapped-maas" >Set up air-gapped MAAS</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-use-the-python-api-client" >Script MAAS with Python</a> <ul class="p-side-navigation__list"> </ul> </li> </ul> </li> </ul> <ul class="p-side-navigation__list"> <li class="p-side-navigation__item"> <a class="p-side-navigation__link is-expandable" href="/docs/reference" aria-expanded="false" >Reference</a> <button class="p-side-navigation__expand" aria-expanded="false" aria-label="show submenu for Reference"></button> <ul class="p-side-navigation__list"> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/release-notes-and-upgrade-instructions" >Release notes</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-installation-requirements" >Installation requirements</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/maas-configuration-guide" >Configuring MAAS settings</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/maas-troubleshooting-guide" >Troubleshooting guide</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-maas-glossary" >MAAS glossary</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-use-cloud-init-with-maas" >Cloud-init examples</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/how-to-authenticate-to-the-maas-api" >Login to the MAAS API</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/api" >MAAS API reference</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-commissioning-scripts" >Commissioning scripts</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-hardware-test-scripts" >Hardware test scripts</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-terraform" >Terraform IAC</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-device-labels" >Device labels</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-maas-metrics" >MAAS metrics</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-power-drivers" >Power drivers</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-bmc-drivers" >BMC drivers</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/reference-maas-storage" >Storage reference</a> <ul class="p-side-navigation__list"> </ul> </li> </ul> </li> </ul> <ul class="p-side-navigation__list"> <li class="p-side-navigation__item"> <a class="p-side-navigation__link is-expandable" href="/docs/explanation" aria-expanded="false" >Explanation</a> <button class="p-side-navigation__expand" aria-expanded="false" aria-label="show submenu for Explanation"></button> <ul class="p-side-navigation__list"> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-maas" >MAAS</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-maas-networking" >Networking</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-dhcp-in-maas" >DHCP in MAAS</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-controllers" >Controllers</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-machine-basics" >Machine basics</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-commissioning-machines" >Commissioning machines</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-the-machine-life-cycle" >The machine life-cycle</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-deploying-machines" >Deploying machines</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-machine-customisation" >Machine customisation</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-deploying-running-machines" >Deploying running machines</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-lxd" >LXD</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-lxd-projects" >LXD projects</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-standard-images" >Standard images</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-custom-images" >Custom images</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-availability-zones" >Availability zones</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-resource-pools" >Resource pools</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-device-labels" >Device labels</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-maas-performance" >MAAS performance</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-maas-events" >MAAS events</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-audit-events" >Audit events</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-maas-logging" >MAAS logging</a> <ul class="p-side-navigation__list"> </ul> </li> <li class="p-side-navigation__item"> <a class="p-side-navigation__link " href="/docs/about-maas-security" >MAAS security</a> <ul class="p-side-navigation__list"> </ul> </li> </ul> </li> </ul> </div> </nav> </div> </div> <div class="l-docs__title"> <div class="p-section--shallow"> <div class="u-fixed-width"> <h1>How to install MAAS</h1> </div> </div> </div> <div class="l-docs__meta"> <div class="l-docs__sticky-container"> <aside class="p-table-of-contents"> <div class="p-table-of-contents__section"> <h4 class="p-table-of-contents__header">On this page</h4> <nav class="p-table-of-contents__nav" aria-label="Table of contents"> <ul class="p-table-of-contents__list"> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-install-maas-snap-or-packages">Install MAAS (snap or packages)</a></li> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-post-install-setup-poc">Post-install setup (POC)</a></li> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-post-install-setup-production">Post-install setup (production)</a></li> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-configuring-and-starting-maas">Configuring and starting MAAS</a></li> <ul class="p-table-of-contents__list"> <li class="p-table-of-contents__item"><a href="#p-9034-checking-maas-status" class="p-table-of-contents__link">Checking MAAS status</a></li> <li class="p-table-of-contents__item"><a href="#p-9034-maas-ui-setup" class="p-table-of-contents__link">MAAS UI setup</a></li> <li class="p-table-of-contents__item"><a href="#p-9034-maas-cli-setup" class="p-table-of-contents__link">MAAS CLI setup</a></li> </ul> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-enabling-dhcp">Enabling DHCP</a></li> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-notes-on-upgrading-maas">Notes on upgrading MAAS</a></li> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-upgrade-to-maas-35">Upgrade to MAAS 3.5</a></li> <ul class="p-table-of-contents__list"> <li class="p-table-of-contents__item"><a href="#p-9034-upgrade-snap-region-rack" class="p-table-of-contents__link">Upgrade Snap (region + rack)</a></li> <li class="p-table-of-contents__item"><a href="#p-9034-upgrade-package-ppa-based-installations" class="p-table-of-contents__link">Upgrade package (PPA-based installations)</a></li> <li class="p-table-of-contents__item"><a href="#p-9034-upgrade-packages-from-maas-versions-29-33" class="p-table-of-contents__link">Upgrade packages from MAAS versions 2.9-3.3</a></li> <li class="p-table-of-contents__item"><a href="#p-9034-upgrade-packages-from-maas-28-or-earlier" class="p-table-of-contents__link">Upgrade packages from MAAS 2.8 or earlier</a></li> </ul> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-upgrade-to-maas-34">Upgrade to MAAS 3.4</a></li> <ul class="p-table-of-contents__list"> <li class="p-table-of-contents__item"><a href="#p-9034-upgrade-snap" class="p-table-of-contents__link">Upgrade snap</a></li> <li class="p-table-of-contents__item"><a href="#p-9034-upgrade-package" class="p-table-of-contents__link">Upgrade package</a></li> </ul> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-upgrade-to-maas-33">Upgrade to MAAS 3.3</a></li> <ul class="p-table-of-contents__list"> <li class="p-table-of-contents__item"><a href="#p-9034-upgrade-snap" class="p-table-of-contents__link">Upgrade snap</a></li> <li class="p-table-of-contents__item"><a href="#p-9034-upgrade-packages" class="p-table-of-contents__link">Upgrade packages</a></li> </ul> <li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#p-9034-additional-notes">Additional notes</a></li> <ul class="p-table-of-contents__list"> <li class="p-table-of-contents__item"><a href="#p-9034-avoiding-ntp-conflicts" class="p-table-of-contents__link">Avoiding NTP conflicts</a></li> <li class="p-table-of-contents__item"><a href="#p-9034-bmc-migration-issue-maas-33" class="p-table-of-contents__link">BMC migration issue (MAAS 3.3+)</a></li> <li class="p-table-of-contents__item"><a href="#p-9034-verification-steps" class="p-table-of-contents__link">Verification steps</a></li> </ul> </ul> </nav> </div> </aside> </div> </div> <div class="l-docs__main u-text-max-width"> <main class="u-fixed-width"> <div class="p-section--shallow"> <div class="u-fixed-width"> <h2><a class="anchor" href="#p-9034-install-maas-snap-or-packages" name="p-9034-install-maas-snap-or-packages"></a>Install MAAS (snap or packages)</h2> <ul> <li> <p><strong>Install from <a href="https://snapcraft.io/maas">snap</a>:</strong></p> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo snap install --channel=<version> maas </code></pre> <p>Replace <code><version></code> with the desired MAAS version.</p> </li> <li> <p><strong>Install from packages:</strong></p> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo apt-add-repository ppa:maas/<version> sudo apt update sudo apt-get -y install maas </code></pre> </li> </ul> <h2><a class="anchor" href="#p-9034-post-install-setup-poc" name="p-9034-post-install-setup-poc"></a>Post-install setup (POC)</h2> <p>There is a proof-of-concept configuration defined <em><strong>for the MAAS snap version only</strong></em>. To initialise the MAAS snap in this POC configuration, use the <code>--help</code> flag with <code>maas init</code> and follow the instructions. This POC uses the <a href="https://snapcraft.io/maas-test-db"><code>maas-test-db</code></a>.</p> <h2><a class="anchor" href="#p-9034-post-install-setup-production" name="p-9034-post-install-setup-production"></a>Post-install setup (production)</h2> <ol> <li> <p><strong>Disable conflicting NTP:</strong></p> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo systemctl disable --now systemd-timesyncd </code></pre> </li> <li> <p><strong>Configure PostgreSQL for production:</strong></p> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">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" </code></pre> </li> <li> <p><strong>Edit <code>/etc/postgresql/14/main/pg_hba.conf</code></strong>, adding a line for the newly created database:</p> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight"> host $MAAS_DBNAME $MAAS_DBUSER 0/0 md5 </code></pre> </li> <li> <p><strong>Initialize MAAS with the database:</strong></p> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo maas init region+rack --database-uri "postgres://$DBUSER:$DBPASS@$HOSTNAME/$DBNAME" </code></pre> <pre><code class="lang-auto"></code></pre> </li> <li> <p><strong>Create an admin user:</strong></p> <pre data-code-wrap="bash"><code class="lang-bash">sudo maas create admin --username=$PROFILE --email=$EMAIL_ADDRESS </code></pre> </li> </ol> <h2><a class="anchor" href="#p-9034-configuring-and-starting-maas" name="p-9034-configuring-and-starting-maas"></a>Configuring and starting MAAS</h2> <h3><a class="anchor" href="#p-9034-checking-maas-status" name="p-9034-checking-maas-status"></a>Checking MAAS status</h3> <p>To check the status of MAAS services, use:</p> <pre data-code-wrap="bash"><code class="lang-bash">sudo maas status </code></pre> <p>Output example:</p> <pre data-code-wrap="bash"><code class="lang-bash">bind9 RUNNING pid 7999, uptime 0:09:17 dhcpd STOPPED Not started postgresql RUNNING pid 8001, uptime 0:09:17 ... </code></pre> <h3><a class="anchor" href="#p-9034-maas-ui-setup" name="p-9034-maas-ui-setup"></a>MAAS UI setup</h3> <ol> <li><strong>Access the UI:</strong><br/> <code>http://$API_HOST:5240/MAAS</code><br/> Log in with the credentials created during installation.</li> <li><strong>DNS forwarder:</strong> Set to a suitable value (e.g., 8.8.8.8).</li> <li><strong>Image import:</strong> Select at least one Ubuntu LTS image.</li> <li><strong>SSH key import:</strong> Choose between Launchpad, GitHub, or upload a key from <code>.ssh/id_rsa.pub</code>.</li> </ol> <h3><a class="anchor" href="#p-9034-maas-cli-setup" name="p-9034-maas-cli-setup"></a>MAAS CLI setup</h3> <ol> <li><strong>Login:</strong><pre data-code-wrap="bash"><code class="lang-bash">maas login $PROFILE $MAAS_URL $(cat api-key-file) </code></pre> </li> <li><strong>Configure DNS:</strong><pre data-code-wrap="bash"><code class="lang-bash">maas $PROFILE maas set-config name=upstream_dns value="8.8.8.8" </code></pre> </li> <li><strong>Add SSH key:</strong><pre data-code-wrap="bash"><code class="lang-bash">maas $PROFILE sshkeys create "key=$SSH_KEY" </code></pre> </li> </ol> <h2><a class="anchor" href="#p-9034-enabling-dhcp" name="p-9034-enabling-dhcp"></a>Enabling DHCP</h2> <p><strong>UI</strong></p> <ol> <li><strong>Navigate to Subnets > VLAN > Configure DHCP.</strong></li> <li><strong>Select the appropriate DHCP options (Managed or Relay).</strong></li> <li><strong>Save and apply changes.</strong></li> </ol> <p><strong>CLI</strong></p> <ol> <li><strong>Enable DHCP:</strong><pre data-code-wrap="bash"><code class="lang-bash">maas $PROFILE vlan update $FABRIC_ID untagged dhcp_on=True \ primary_rack=$PRIMARY_RACK_CONTROLLER </code></pre> </li> <li><strong>Set default gateway:</strong><pre data-code-wrap="bash"><code class="lang-bash">maas $PROFILE subnet update $SUBNET_CIDR gateway_ip=$MY_GATEWAY </code></pre> </li> </ol> <h2><a class="anchor" href="#p-9034-notes-on-upgrading-maas" name="p-9034-notes-on-upgrading-maas"></a>Notes on upgrading MAAS</h2> <p>The following general notes apply to an upgrade:</p> <ul> <li><strong>Review PostgreSQL Requirements:</strong> MAAS 3.5 and later require PostgreSQL 14. <a href="https://discourse.maas.io/t/how-to-upgrade-postgresql-v12-to-v14/7203">Upgrade instructions here</a>.</li> <li><strong>Upgrade Ubuntu if needed:</strong> Ensure you鈥檙e running Ubuntu 22.04 (Jammy) before upgrading MAAS.</li> <li><strong>Backup your data:</strong> Always create a backup before upgrading.</li> <li><strong>Multi-node setups:</strong> Upgrade rack nodes first, then region nodes.</li> </ul> <h2><a class="anchor" href="#p-9034-upgrade-to-maas-35" name="p-9034-upgrade-to-maas-35"></a>Upgrade to MAAS 3.5</h2> <h3><a class="anchor" href="#p-9034-upgrade-snap-region-rack" name="p-9034-upgrade-snap-region-rack"></a>Upgrade Snap (region + rack)</h3> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo snap refresh maas --channel=3.5/stable </code></pre> <h3><a class="anchor" href="#p-9034-upgrade-package-ppa-based-installations" name="p-9034-upgrade-package-ppa-based-installations"></a>Upgrade package (PPA-based installations)</h3> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo apt-add-repository ppa:maas/3.5 sudo apt update && sudo apt upgrade maas </code></pre> <h3><a class="anchor" href="#p-9034-upgrade-packages-from-maas-versions-29-33" name="p-9034-upgrade-packages-from-maas-versions-29-33"></a>Upgrade packages from MAAS versions 2.9-3.3</h3> <ol> <li><strong>Upgrade PostgreSQL</strong>: If running PostgreSQL 12, <a href="https://discourse.maas.io/t/how-to-upgrade-postgresql-v12-to-v14/7203">upgrade to 14</a>.</li> <li><strong>Ensure Ubuntu 22.04 (Jammy)</strong>:<pre data-code-wrap="nohighlight"><code class="lang-nohighlight">lsb_release -a </code></pre> If on Ubuntu 20.04, upgrade:<pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo do-release-upgrade --allow-third-party </code></pre> </li> <li><strong>Add PPA and Upgrade:</strong><pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo apt-add-repository ppa:maas/3.5 sudo apt update && sudo apt upgrade maas </code></pre> </li> <li><strong>Verify Installation:</strong><pre data-code-wrap="nohighlight"><code class="lang-nohighlight">maas --version </code></pre> </li> </ol> <h3><a class="anchor" href="#p-9034-upgrade-packages-from-maas-28-or-earlier" name="p-9034-upgrade-packages-from-maas-28-or-earlier"></a>Upgrade packages from MAAS 2.8 or earlier</h3> <ol> <li><strong>Backup your system</strong> completely.</li> <li><strong>Ensure Ubuntu 22.04</strong> (see steps above).</li> <li><strong>Add PPA and Upgrade:</strong><pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo apt-add-repository ppa:maas/3.5 sudo apt update && sudo apt upgrade maas </code></pre> </li> <li><strong>If the upgrade fails</strong>, restore from backup and consider a fresh installation.</li> </ol> <h2><a class="anchor" href="#p-9034-upgrade-to-maas-34" name="p-9034-upgrade-to-maas-34"></a>Upgrade to MAAS 3.4</h2> <h3><a class="anchor" href="#p-9034-upgrade-snap" name="p-9034-upgrade-snap"></a>Upgrade snap</h3> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo snap refresh maas --channel=3.4/stable </code></pre> <h3><a class="anchor" href="#p-9034-upgrade-package" name="p-9034-upgrade-package"></a>Upgrade package</h3> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo apt-add-repository ppa:maas/3.4 sudo apt update && sudo apt upgrade maas </code></pre> <ul> <li><strong>Follow the same Ubuntu and PostgreSQL upgrade steps as above.</strong></li> </ul> <h2><a class="anchor" href="#p-9034-upgrade-to-maas-33" name="p-9034-upgrade-to-maas-33"></a>Upgrade to MAAS 3.3</h2> <h3><a class="anchor" href="#p-9034-upgrade-snap" name="p-9034-upgrade-snap"></a>Upgrade snap</h3> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo snap refresh maas --channel=3.3/stable </code></pre> <h3><a class="anchor" href="#p-9034-upgrade-packages" name="p-9034-upgrade-packages"></a>Upgrade packages</h3> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo apt-add-repository ppa:maas/3.3 sudo apt update && sudo apt upgrade maas </code></pre> <ul> <li><strong>PostgreSQL 12 is deprecated in MAAS 3.3 and unsupported in 3.5.</strong> Upgrade to PostgreSQL 14 before proceeding.</li> </ul> <h2><a class="anchor" href="#p-9034-additional-notes" name="p-9034-additional-notes"></a>Additional notes</h2> <h3><a class="anchor" href="#p-9034-avoiding-ntp-conflicts" name="p-9034-avoiding-ntp-conflicts"></a>Avoiding NTP conflicts</h3> <p>If you experience time synchronization issues:</p> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">sudo systemctl disable --now systemd-timesyncd </code></pre> <h3><a class="anchor" href="#p-9034-bmc-migration-issue-maas-33" name="p-9034-bmc-migration-issue-maas-33"></a>BMC migration issue (MAAS 3.3+)</h3> <p>Ensure unique BMC IP/username/password combinations before upgrading to avoid migration failures.</p> <h3><a class="anchor" href="#p-9034-verification-steps" name="p-9034-verification-steps"></a>Verification steps</h3> <p>After upgrading, confirm MAAS is running correctly:</p> <pre data-code-wrap="nohighlight"><code class="lang-nohighlight">lsb_release -a # Ensure Ubuntu version is correct maas --version # Verify MAAS version </code></pre> </div> </div> <div class="p-section--shallow"> <div class="u-fixed-width"> <hr /> <p><i>Last updated a day ago.</i></p> </div> </div> <div class="p-section--shallow"> <div class="u-fixed-width"> <div class="p-notification--information"> <div class="p-notification__content"> <p class="p-notification__message"> <a href="https://discourse.maas.io/t/how-to-install-maas/5128">Help improve this document in the forum</a>. </p> </div> </div> </div> </div> </main> </div> <div class="l-docs__footer"> <footer class="p-footer p-strip"> <div class="l-docs__subgrid"> <div class="l-docs__sidebar"> <div class="u-fixed-width"> <p>漏 2025 Canonical Ltd.</p> </div> </div> <div class="l-docs__main"> <div class="row"> <div class="col-4"> <h3 class="p-heading--4">MAAS</h3> <ul class="p-list"> <li class="p-list__item"> <a href="/">Home</a> </li> <li class="p-list__item"> <a href="/install">Install MAAS</a> </li> <li class="p-list__item"> <a href="/how-it-works">How it works</a> </li> <li class="p-list__item"> <a href="/tour">Tour</a> </li> <li class="p-list__item"> <a href="/docs">Docs</a> </li> <li class="p-list__item"> <a href="/tutorials">Tutorials</a> </li> <li class="p-list__item"> <a href="/contact-us">Contact us</a> </li> <li class="p-list__item"> <a href="/support">Support</a> </li> </ul> </div> <div class="col-4"> <h3 class="p-heading--4">Need help?</h3> <ul class="p-list"> <li class="p-list__item"> <a href="https://discourse.maas.io/">Discourse</a> </li> <li class="p-list__item"> <a class="js-invoke-modal" href="/contact-us">Commercial support</a> </li> </ul> </div> <div class="col-4"> <h3 class="p-heading--4">Contribute</h3> <ul class="p-list"> <li class="p-list__item"> <a href="https://launchpad.net/maas" >Launchpad</a > </li> <li class="p-list__item"> <a href="https://discourse.maas.io/c/docs" >Contribute to documentation</a > </li> </ul> </div> </div> <nav class="row"> <div class="has-cookie"> <p> <a href="https://www.ubuntu.com">Ubuntu</a> and <a href="https://www.canonical.com">Canonical</a> are registered trademarks of Canonical Ltd. </p> <ul class="p-inline-list--middot"> <li class="p-inline-list__item"> <a href="https://www.ubuntu.com/legal" ><small>Legal information</small></a > </li> <li class="p-inline-list__item"> <a class="p-footer__link js-revoke-cookie-manager" href="" ><small>Manage your tracker settings</small></a > </li> <li class="p-inline-list__item"> <a href="https://github.com/canonical-web-and-design/maas.io/issues/new/" ><small>Report a bug on this site</small></a > </li> </ul> <span class="u-off-screen" ><a href="#">Go to the top of the page</a></span > </div> </nav> </div> </div> </footer> <script src="/static/js/modules/global-nav/global-nav.js"></script> <script src="/static/js/modules/cookie-policy/cookie-policy.js"></script> <script> canonicalGlobalNav.createNav({ breakpoint: 960 }); cpNs.cookiePolicy(); </script> </div> </div> <script src="/static/js/highlight.pack.js"></script> <script> hljs.initHighlightingOnLoad(); window.addEventListener("DOMContentLoaded", function() { // Based on Vanilla side navigation example // Should be moved out from the template as part of a given project JS /** Toggles the expanded/collapsed classed on side navigation element. @param {HTMLElement} sideNavigation The side navigation element. @param {Boolean} show Whether to show or hide the drawer. */ function toggleDrawer(sideNavigation, show) { const toggleButtonOutsideDrawer = sideNavigation.querySelector( ".p-side-navigation__toggle" ); const toggleButtonInsideDrawer = sideNavigation.querySelector( ".p-side-navigation__toggle--in-drawer" ); if (sideNavigation) { if (show) { sideNavigation.classList.remove("is-drawer-collapsed"); sideNavigation.classList.add("is-drawer-expanded"); toggleButtonInsideDrawer.focus(); toggleButtonOutsideDrawer.setAttribute("aria-expanded", true); toggleButtonInsideDrawer.setAttribute("aria-expanded", true); } else { sideNavigation.classList.remove("is-drawer-expanded"); sideNavigation.classList.add("is-drawer-collapsed"); toggleButtonOutsideDrawer.focus(); toggleButtonOutsideDrawer.setAttribute("aria-expanded", false); toggleButtonInsideDrawer.setAttribute("aria-expanded", false); } } } // throttle util (for window resize event) var throttle = function (fn, delay) { var timer = null; return function () { var context = this, args = arguments; clearTimeout(timer); timer = setTimeout(function () { fn.apply(context, args); }, delay); }; }; /** Attaches event listeners for the side navigation toggles @param {HTMLElement} sideNavigation The side navigation element. */ function setupSideNavigation(sideNavigation) { var toggles = [].slice.call( sideNavigation.querySelectorAll(".js-drawer-toggle") ); var drawerEl = sideNavigation.querySelector(".p-side-navigation__drawer"); // hide navigation drawer on small screens sideNavigation.classList.add("is-drawer-hidden"); // setup drawer element drawerEl.addEventListener("animationend", () => { if (!sideNavigation.classList.contains("is-drawer-expanded")) { sideNavigation.classList.add("is-drawer-hidden"); } }); window.addEventListener("keydown", (e) => { if (e.key === "Escape") { toggleDrawer(sideNavigation, false); } }); // setup toggle buttons toggles.forEach(function (toggle) { toggle.addEventListener("click", function (event) { event.preventDefault(); if (sideNavigation) { sideNavigation.classList.remove("is-drawer-hidden"); toggleDrawer( sideNavigation, !sideNavigation.classList.contains("is-drawer-expanded") ); } }); }); // hide side navigation drawer when screen is resized window.addEventListener( "resize", throttle(function () { toggles.forEach((toggle) => { return toggle.setAttribute("aria-expanded", false); }); // remove expanded/collapsed class names to avoid unexpected animations sideNavigation.classList.remove("is-drawer-expanded"); sideNavigation.classList.remove("is-drawer-collapsed"); sideNavigation.classList.add("is-drawer-hidden"); }, 10) ); } /** Attaches event listeners for all the side navigations in the document. @param {String} sideNavigationSelector The CSS selector matching side navigation elements. */ function setupSideNavigations(sideNavigationSelector) { // Setup all side navigations on the page. var sideNavigations = [].slice.call( document.querySelectorAll(sideNavigationSelector) ); sideNavigations.forEach(setupSideNavigation); } setupSideNavigations('.p-side-navigation, [class*="p-side-navigation--"]'); // Setup expandable side navigation var expandToggles = document.querySelectorAll(".p-side-navigation__expand"); var navigationLinks = document.querySelectorAll(".p-side-navigation__link"); // setup default values of aria-expanded for the toggle button, list title and list itself const setup = (toggle) => { const isExpanded = toggle.getAttribute("aria-expanded") === "true"; if (!isExpanded) { toggle.setAttribute("aria-expanded", isExpanded); } const item = toggle.closest(".p-side-navigation__item"); const link = item.querySelector(".p-side-navigation__link"); const nestedList = item.querySelector(".p-side-navigation__list"); if (!link?.hasAttribute("aria-expanded")) { link.setAttribute("aria-expanded", isExpanded); } if (!nestedList?.hasAttribute("aria-expanded")) { nestedList.setAttribute("aria-expanded", isExpanded); } }; const handleToggle = (e) => { const item = e.currentTarget.closest(".p-side-navigation__item"); const button = item.querySelector(".p-side-navigation__expand"); const link = item.querySelector(".p-side-navigation__link"); const nestedList = item.querySelector(".p-side-navigation__list"); [button, link, nestedList].forEach((el) => el.setAttribute( "aria-expanded", el.getAttribute("aria-expanded") === "true" ? "false" : "true" ) ); }; expandToggles.forEach((toggle) => { setup(toggle); toggle.addEventListener("click", (e) => { handleToggle(e); }); }); }); </script> <script src="/static/js/modules/discourse-rad-parser/discourse-rad-parser.js"></script> <script> drpNs.DiscourseRADParser(); </script> </body> </html>

CINXE.COM