Maximo Application Suite CLI Ansible CLI
Edit on GitHub
Home Image Mirroring (v2) Prerequisites Usage Environment Variables Image Mirroring Mirror All Packages Advanced Options

Image Mirroring (v2)

The mas mirror command is the next-generation Python-based image mirroring tool, replacing the legacy mas mirror-images bash command. It uses oc-mirror under the hood and supports three mirror modes:

Mode Description
m2m Mirror to mirror — pull from IBM registries and push directly to your private registry
m2d Mirror to disk — pull from IBM registries and save to the local filesystem
d2m Disk to mirror — push previously saved filesystem content to your private registry

Two-phase mirroring (m2d followed by d2m) is recommended in most cases. It requires more storage but cleanly separates the internet-facing download from the private-network upload, making it easier to recover from network interruptions.

This guide assumes you are targeting the latest release (9.2.x) from the most recent catalog (v9-261029-amd64). Remove any --<package> flags that correspond to applications or dependencies you are not deploying.

Prerequisites

  • The oc-mirror executable must be available on the PATH of the system running mas mirror (the command fails immediately if it is not found).
  • Catalog v9-260129-amd64 (January 2026) or newer is required, earlier catalogs are not supported by mas mirror. Use mas mirror-images for older catalogs.
  • The image set configurations are read from ~/.ibm-mas/image-set-configs and are automatically downloaded from ibm-mas/image-set-configs if not present, so the system running the command needs access to GitHub (or the files must be pre-populated in that directory).

Usage

For full usage information run:

mas mirror --help

The following arguments are always required: --catalog, --release, --mode and --dir. --target-registry is additionally required for the m2m and d2m modes. The IBM Maximo Operator Catalog is always mirrored, the --<package> flags (or --all) select which additional content is mirrored.

The architecture of the mirrored images is determined by the suffix of the catalog name (-amd64, -ppc64le or -s390x).

Environment Variables

The following environment variables are used to authenticate with registries. Which ones are required depends on the mirror mode in use:

Variable Required for modes Description
IBM_ENTITLEMENT_KEY m2m, m2d IBM Entitlement Key to pull images from cp.icr.io
REGISTRY_USERNAME m2m, d2m Username for your private target registry
REGISTRY_PASSWORD m2m, d2m Password for your private target registry 
export IBM_ENTITLEMENT_KEY=xxx
export REGISTRY_USERNAME=xxx
export REGISTRY_PASSWORD=xxx #pragma: allowlist secret

Alternatively, you can provide a pre-built Docker/Podman credentials file via --authfile <path> to bypass automatic credential generation.

Image Mirroring

mas mirror does not have an interactive mode, all options must be provided as command line arguments. The sections below walk through mirroring content in four stages, with a tab for each mirror mode. Clear milestones make it easier to diagnose failures and measure progress:

Preparation

Set these environment variables once; they are reused in every stage:

export IBM_ENTITLEMENT_KEY=xxx
export LOCAL_DIR=xxx
export REGISTRY_HOST=xxx
export REGISTRY_USERNAME=xxx
export REGISTRY_PASSWORD=xxx #pragma: allowlist secret

If the system that has internet access cannot reach your private registry, you will need to transfer the filesystem content (produced in the m2d phase) to a separate system on your private network before running the d2m phase.

To bootstrap the MAS CLI container itself into an air-gapped environment, first mirror it to the filesystem from an internet-connected system:

oc image mirror --dir $LOCAL_DIR/cli quay.io/ibmmas/cli:23.18.0 file://ibmmas/cli:23.18.0 --filter-by-os='.*'

Transfer $LOCAL_DIR/cli to your private-network system and push the image to your mirror registry:

docker login $REGISTRY_HOST -u $REGISTRY_USERNAME -p $REGISTRY_PASSWORD
oc image mirror --dir $LOCAL_DIR/cli file://ibmmas/cli:23.18.0 $REGISTRY_HOST/ibmmas/cli:23.18.0 --filter-by-os='.*'

Note

Only images for the architecture of the selected catalog are mirrored. To mirror a different architecture, choose the matching catalog, for example v9-260129-ppc64le instead of v9-260129-amd64.

Stage 1 — MAS Core & Catalog

Mirror to Mirror Mirror to Disk Disk to Mirror

Stage 2 — MAS Applications

Mirror to Mirror Mirror to Disk Disk to Mirror

Stage 3 — Cloud Pak for Data

Mirror to Mirror Mirror to Disk Disk to Mirror

Stage 4 — Other Dependencies

Mirror to Mirror Mirror to Disk Disk to Mirror

Mirror All Packages

To mirror every supported package in one command, use --all. This is convenient but will require significantly more storage and time than mirroring only what you need.

docker run -ti --rm -v $LOCAL_DIR:/mnt/registry \
  -e IBM_ENTITLEMENT_KEY=$IBM_ENTITLEMENT_KEY \
  -e REGISTRY_USERNAME=$REGISTRY_USERNAME \
  -e REGISTRY_PASSWORD=$REGISTRY_PASSWORD \
  quay.io/ibmmas/cli:23.18.0 mas mirror \
  --catalog v9-261029-amd64 --release 9.2.x \
  --mode m2m --target-registry $REGISTRY_HOST \
  --dir /mnt/registry/all \
  --all

Note

Mirror Red Hat images to install required Red Hat dependencies (DRO, Cert Manager, and Grafana) needed for MAS installation. Missing this step will result in installation failures.

Advanced Options

Flag Default Description
--authfile <path> — Path to an existing Docker/Podman auth file; skips credential auto-generation
--dest-tls-verify true Verify TLS certificates for the destination registry (true/false)
--image-timeout 20m Per-image operation timeout (e.g., 1h20m10s, 1h, 20m, 10s)