---
title: How to manage images
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-manage-images?format=md
---

*Submit*

# How to manage images

MAAS deploys machines from a repository of operating system images called a SimpleStreams source. There are two image streams:

* Stable – fully tested, production-ready (default).
* Candidate – newer, less tested; use when you need support for a newer OS not yet in stable.

Each image includes Ubuntu or CentOS, a bootloader, an initramfs, and release notifications.

* Images sync hourly at the region level.
* Rack controllers cache files as needed for deployment.

## [Switch image streams](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-switch-image-streams)

You can change streams at any time.

UI

* *Images* > *Change source* > *Custom*
* Set *URL* to:
  + Stable: `http://images.maas.io/ephemeral-v3/stable`
  + Candidate: `http://images.maas.io/ephemeral-v3/candidate`

CLI

```
BOOT_SOURCE_ID=$(maas $PROFILE boot-sources read)
```

## [Manage images](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-manage-images)

Images must be downloaded before deployment. Choose which ones to keep locally.

UI

* *Main menu* > *Images* > *Select/Unselect* > *Save selection*

CLI

```
maas $PROFILE boot-sources read  # list boot sources
maas $PROFILE boot-source-selections create $SOURCE_ID     os="ubuntu" release="$SERIES" arches="$ARCH"     subarches="$KERNEL" labels="*" # select boot sources
maas $PROFILE boot-resources read # list images
maas $PROFILE boot-resources import # select images
```

## [Additional CLI management](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-additional-cli-management)

### [Delete a boot source](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-delete-a-boot-source)

```
maas $PROFILE boot-source delete $SOURCE_ID
```

### [Update a boot source](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-update-a-boot-source)

```
maas $PROFILE boot-source update $SOURCE_ID     url=$URL keyring_filename=$KEYRING_FILE
```

### [Add a new boot source](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-add-a-new-boot-source)

```
maas $PROFILE boot-sources create     url=$URL keyring_filename=$KEYRING_FILE
```

Use `/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg` if the new source mirrors the official streams.

## [Use a custom mirror](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-use-a-custom-mirror)

UI

* *Images* > *Change source* > *Custom* > enter *URL* > *Connect*
* For advanced settings, choose *Show advanced options*
* Use a local mirror (see below) for faster imports

## [Use a local mirror](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-use-a-local-mirror)

A local SimpleStreams mirror improves sync performance.

### [Install SimpleStreams](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-install-simplestreams)

```
sudo apt install simplestreams
```

### [Define helper variables](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-define-helper-variables)

```
KEYRING_FILE=/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg
IMAGE_SRC=https://images.maas.io/ephemeral-v3/stable
IMAGE_DIR=/var/www/html/maas/images/ephemeral-v3/stable
```

### [Mirror kernels](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-mirror-kernels)

```
sudo sstream-mirror --keyring=$KEYRING_FILE $IMAGE_SRC $IMAGE_DIR 'arch=amd64' 'release~(bionic|focal)' --max=1 --progress
sudo sstream-mirror --keyring=$KEYRING_FILE $IMAGE_SRC $IMAGE_DIR 'os~(grub*|pxelinux)' --max=1 --progress
```

* Use `--dry-run` to preview.
* Images save to `$IMAGE_DIR`.
* New boot source URL: `http://<myserver>/maas/images/ephemeral-v3/stable/`.

### [Verify and update](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-verify-and-update)

* Open the URL above to confirm access.
* Schedule regular updates with `cron`.

### [Configure MAAS to use your mirror](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-configure-maas-to-use-your-mirror)

```
URL=https://$MIRROR/maas/images/ephemeral-v3/stable/
KEYRING_FILE=/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg
```

Replace `$MIRROR` with your mirror server hostname.

## [Safety nets](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-safety-nets)

* Production use: stick to the *stable* stream.
* Candidate images may contain bugs — only use if you need newer OS support.
* Check mirrors after setup to confirm availability.

## [Next steps](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-images?format=md#p-9030-next-steps)

* Learn [About MAAS images](https://canonical.com/maas/docs/about-images)
* Discover [How to build custom images](https://canonical.com/maas/docs/how-to-build-custom-images)
* Find out [How to deploy a real-time kernel](https://canonical.com/maas/docs/how-to-deploy-a-real-time-kernel)

---

[Previous

Manage machine groups](https://canonical-com-2934.demos.haus/maas/docs/how-to-manage-machine-groups)
[Next

Build Ubuntu images](https://canonical-com-2934.demos.haus/maas/docs/how-to-build-ubuntu-images)

Last updated 1 year, 1 month ago. [Help improve this document in the forum](https://discourse.maas.io/t/how-to-manage-images/5124).