Version: v1.8

Mirror Command

hangar mirror command is for mirror multiple container images between image registry servers. It allows you to specify architecture and platforms when copying image, and use multiple workers to copy images parallelly.

Quick Start

Use following command to mirror multiple images between image registry servers parallelly:

Prepare an example image list file.
example_image_list.txt
```
cnrancher/hangar:latest
cnrancher/hangar:v1.8.0
# Add more images here...
```
Hangar mirror command supports two kinds of image list file formats, the image list file in this example is in default format. See Image List Formats for image list format specification.

Run following command to mirror amd64 & arm64, linux container images by image list file from SOURCE REGISTRY to DESTINATION REGISTRY parallelly.

#!/bin/bash

hangar mirror \
    --file="example_image_list.txt" \
    --source=SOURCE_REGISTRY_URL \
    --destination=DESTINATION_REGISTRY_URL \
    --arch=amd64,arm64 \
    --os=linux \
    --jobs=4

Use inspect command to view the copied image manifest.

hangar inspect --raw docker://DESTINATION_REGISTRY_URL/cnrancher/hangar:latest

Image List Format

hangar mirror command supports two different kinds of image list formats, see Image List Formats for image list format specification.

Usage

hangar mirror --help
Mirror images between registry servers

Usage:
  hangar mirror -f IMAGE_LIST.txt -d DESTINATION_REGISTRY [flags]
  hangar mirror [command]

Examples:
# Mirror images from SOURCE REGISTRY to DESTINATION REGISTRY.
hangar mirror \
        --file IMAGE_LIST.txt \
        --source SOURCE_REGISTRY \
        --destination DESTINATION_REGISTRY \
        --arch amd64,arm64 \
        --os linux \
        --sigstore-private-key SIGSTORE.key

Available Commands:
  validate    Ensure the images were mirrored correctly

Flags:
  -a, --arch strings                      architecture list of images (default [amd64,arm64])
  -d, --destination string                specify the destination image registry
      --destination-project string        override all destination image projects
  -o, --failed string                     file name of the mirror failed image list (default "mirror-failed.txt")
  -f, --file string                       image list file
  -h, --help                              help for mirror
  -j, --jobs int                          worker number, copy images parallelly (1-20) (default 1)
      --os strings                        OS list of images (default [linux])
      --overwrite                         overwrite exist manifest index in destination registry
      --provenance                        copy SLSA provenance (default true)
      --remove-signatures                 do not copy image signatures when mirror images
      --sigstore-passphrase-file string   passphrase file of the sigstore private key
      --sigstore-private-key string       sign images by sigstore private key when mirror images
      --skip-login                        skip check the destination registry is logged in (used in shell script)
  -s, --source string                     override the source registry in image list
      --source-project string             override all source image projects
      --timeout duration                  timeout when mirror each images (default 10m0s)
      --tls-verify                        require HTTPS and verify certificates

Global Flags:
      --debug             enable debug output
      --insecure-policy   run Hangar without policy check

Use "hangar mirror [command] --help" for more information about a command.

Override project name when mirror images

Hangar mirror command provides some advanced options to customize the project name (namespace) of the SOURCE IMAGE and DESTINATION IMAGE.

You can use the --source-project option to override all source image projects and --destination-project option to override all destination image projects in the image list file.

Here is an example:

The example Default format image list file contains images on Docker Hub with different projects (library and cnrancher).
example.txt
```
docker.io/library/nginx:latest
docker.io/cnrancher/hangar:latest
```

Use the --destination-project option to mirror these images to another user on Docker Hub.

$ hangar mirror -f "example.txt" --destination-project="USERNAME"
[17:00:00] [INFO] [IMG:1] Copying [docker.io/library/nginx:latest] => [docker.io/USERNAME/nginx:latest]
[17:00:00] [INFO] [IMG:2] Copying [docker.io/cnrancher/hangar:latest] => [docker.io/USERNAME/hangar:latest]
......

Sign images with sigstore private key when copy

Starting from v1.8.0, you can specify the sigstore private key by with --sigstore-private-key option to sign images when mirroring.

hangar mirror \
    --file "example.txt" \
    --source "SOURCE_REGISTRY" \
    --destination "DESTINATION_REGISTRY" \
    --sigstore-private-key "sigstore.key"

By default, the mirror command will copy the sigstore signature to the destination registry server if the source image is already signed. You can specify the --remove-signatures option to disable sigstore signature copy when mirroring container images.

Overwrite exist manifest index

Starting from v1.8.7, you can use --overwrite option to overwrite existing manifest list in destination registry server when copy images.

hangar mirror \
    --file "example.txt" \
    --source "SOURCE_REGISTRY" \
    --destination "DESTINATION_REGISTRY" \
    --overwrite=true

By default, hangar will merge the new images into existing manifest list in destination registry server, if unexpected problem with the manifest list of the image copied to the destination registry, use the --overwrite option to fix it.

Quick Start​

Image List Format​

Usage​

Override project name when mirror images​

Sign images with sigstore private key when copy​

Overwrite exist manifest index​