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

How to mirror images locally

Mirroring images is worthy of consideration. The SimpleStreams protocol delivers Images to MAAS, which is especially useful when your Internet link is slow or unreliable. In this mirrored configuration, images will be instantly available when MAAS requests them.

Canonical provides two SimpleStreams for MAAS images: candidate and stable. Both streams contain Ubuntu images, CentOS images, bootloaders extracted from the Ubuntu archive, and release notifications. Either stream can be used in any version of MAAS greater than 2.1, but not all images are supported in older versions.

This article will tell you:

About the candidate stream

The candidate stream contains images and bootloaders which have not been explicitly tested with MAAS. Canonical’s automated build process dumps all images and bootloaders here before they are tested with MAAS. This stream is useful when testing a bug fix before an image or bootloader has been promoted to stable. Think of the candidate stream as a preview: it should never be used in a production environment; and users are encouraged to provide feedback on any issues they find with this stream.

This stream is available here.

About the stable stream

The stable stream contains images and bootloaders which have been tested with the latest version of MAAS. This is the default stream which should be used in production environments. This stream is available here.

About the retired daily stream

Previously there was only one MAAS stream available, daily. This stream has been replaced by the stable stream. Any client using this stream will be automatically redirected to the stable stream.

How to change the stream with the UI

To switch to the candidate stream simply select “custom” on the images page, set the URL to http://images.maas.io/ephemeral-v3/candidate, and click “Connect”

MAAS uses the stable stream by default. To switch back to it simply select maas.io on the images page

How to change the stream with the CLI

To switch to a stream with the CLI, enter the following commands:

BOOT_SOURCE_ID=$(maas $PROFILE boot-sources read | jq '.[] | select(.url | contains("images.maas.io/ephemeral-v3")) | .id')
maas $PROFILE boot-source update $BOOT_SOURCE_ID url=$STREAM_URL

How to set up a local mirror

To use mirroring, you begin by installing the necessary software on the host that will house the mirror:

sudo apt install simplestreams

First define some variables to unclutter eventual CLI commands:

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

The below example selects all available kernels that are compatible with either Ubuntu 18.04 (Bionic) and Ubuntu 20.04 (Focal) for the amd64 architecture, resulting in a download of approximately 3.1 GB. The second command mirrors the bootloaders.

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

To know in advance what the sstream-mirror command will grab, or if you want to save bandwidth and time by avoiding bad selections, include the --dry-run option. When you are satisfied, remove that option to initiate the download.

MAAS will write the images to disk in the directory defined by the variable ‘IMAGE_DIR’ above, and the ‘location’ of the new boot source will be:

URL=http://<myserver>/maas/images/ephemeral-v3/stable/

Where <myserver> identifies your server’s hostname or IP address.

Verify the availability of the images by visiting the above URL.

The final sstream-mirror command should be invoked at regular intervals (i.e. with cron) to ensure the mirror contains the latest images.