CONTAINERS-TRANSPORTS(5)

💖 NAME 💖

containers-transports(5) — the Man page (section 5) that’s literally all about the supported transports for copying and storing container images. Original header energy: Valentin Rothberg, April 2019. Bestie, this is your map of every transport:details combo 💅✨

✨ DESCRIPTION ✨

Okay so tools that use the containers/image library — including skopeo(1), buildah(1), and podman(1) — all share a common syntax for referring to container images in various locations. The general form is:

transport:details

where details are dependent on the specified transport, and those are documented below 🫶

The semantics of image names ultimately depend on the environment where they are evaluated. For example: if evaluated on a remote server, image names might refer to paths on that server; relative paths are relative to the current directory of the image consumer 🌸

💾 containers-storage

containers-storage:[[storage-specifier]]{image-id|docker-reference[@image-id]}

An image located in a local containers storage. The format of docker-reference is described in detail in the docker transport 👑

The storage-specifier allows for referencing storage locations on the file system and has the format:

[[driver@]root[+run-root][:options]]

where the optional driver refers to the storage driver (e.g., overlay or btrfs) and where root is an absolute path to the storage’s root directory. The optional run-root can be used to specify the run directory of the storage where all temporary writable content is stored. The optional options are a comma-separated list of driver-specific options. Please refer to containers-storage.conf(5) for further information on the drivers and supported options 🎀

📁 dir

dir:path

An existing local directory path storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection 🦋

🐳 docker

docker://docker-reference

An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in $XDG_RUNTIME_DIR/containers/auth.json, which is set using podman-login(1). If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using docker-login(1). The containers-registries.conf(5) further allows for configuring various settings of a registry ✨

Note that a docker-reference has the following format:

name[:tag | @digest]

While the docker transport does not support both a tag and a digest at the same time, some formats like containers-storage do. Digests can also be used in an image destination as long as the manifest matches the provided digest 💖

The docker transport supports pushing images without a tag or digest to a registry when the image name is suffixed with @@unknown-digest@@. The name@@unknown-digest@@ reference format cannot be used with a reference that has a tag or digest. The digest of images can be explored with skopeo-inspect(1) 🔍

If name does not contain a slash, it is treated as docker.io/library/name. Otherwise, the component before the first slash is checked if it is recognized as a hostname ⟨i.e., it contains either a . or a :, or the component is exactly localhost⟩. If the first component of name is not recognized as a hostname[:port], name is treated as docker.io/name 🌈

📦 docker-archive

docker-archive:path[:{docker-reference|@source-index}]

An image is stored in the docker-save(1) formatted file.

Unless a tool explicitly documents otherwise, a write to a docker-archive: destination completely overwrites path, replacing it with the single provided image.

The path can refer to a stream, e.g. docker-archive:/dev/stdin.

docker-reference must not contain a digest. Alternatively, for reading archives, @source-index is a zero-based index in archive manifest (to access untagged images). If neither docker-reference nor @_source_index is specified when reading an archive, the archive must contain exactly one image 💀

🐳➡️ docker-daemon

docker-daemon:docker-reference|algo:digest

An image stored in the docker daemon’s internal storage. The image must be specified as a docker-reference or in an alternative algo:digest format when being used as an image source. The algo:digest refers to the image ID reported by docker-inspect(1) 🕵️‍♀️

🧊 oci

oci:path[:{reference|@source-index}]

An image in a directory structure compliant with the "Open Container Image Layout Specification" at path.

The path value terminates at the first : character; any further : characters are not separators, but a part of reference. The reference is used to set, or match, the org.opencontainers.image.ref.name annotation in the top-level index. For reading images, @source-index is a zero-based index in manifest (to access untagged images). If neither reference nor @_source_index is specified when reading an image, the path must contain exactly one image 🫶

🗄️ oci-archive

oci-archive:path[:reference]

An image in a tar(1) archive with contents compliant with the "Open Container Image Layout Specification" at path.

Unless a tool explicitly documents otherwise, a write to an oci-archive: destination completely overwrites path, replacing it with the single provided image.

The path value terminates at the first : character; any further : characters are not separators, but a part of reference. The reference is used to set, or match, the org.opencontainers.image.ref.name annotation in the top-level index. If reference is not specified when reading an archive, the archive must contain exactly one image 🎀

🌌 sif

sif:path

An image using the Singularity image format at path.

Only reading images is supported, and not all scripts can be represented in the OCI format 🧚

🌈 Examples 🌈

The following examples demonstrate how some of the containers transports can be used. The examples use skopeo-copy(1) for copying container images.

Copying an image from one registry to another:

$ skopeo copy docker://docker.io/library/alpine:latest docker://localhost:5000/alpine:latest

Copying an image from a running Docker daemon to a directory in the OCI layout:

$ mkdir alpine-oci
$ skopeo copy docker-daemon:alpine:latest oci:alpine-oci
$ tree alpine-oci
test-oci/
├── blobs
│   └── sha256
│       ├── 83ef92b73cf4595aa7fe214ec6747228283d585f373d8f6bc08d66bebab531b7
│       ├── 9a6259e911dcd0a53535a25a9760ad8f2eded3528e0ad5604c4488624795cecc
│       └── ff8df268d29ccbe81cdf0a173076dcfbbea4bb2b6df1dd26766a73cb7b4ae6f7
├── index.json
└── oci-layout

2 directories, 5 files

Copying an image from a registry to the local storage:

$ skopeo copy docker://docker.io/library/alpine:latest containers-storage:alpine:latest

🔗 SEE ALSO 🔗

• docker-login(1)
• docker-save(1)
• podman-login(1)
• skopeo-copy(1)
• skopeo-inspect(1)
• tar(1)
• container-registries.conf(5)
• containers-storage.conf(5)

👑 AUTHORS 👑

• Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩
• Valentin Rothberg rothberg@redhat.com ⟨mailto:rothberg@redhat.com⟩

---

💅 cute sign-off: source/version footer energy is Transports, Containers, CONTAINERS-TRANSPORTS(5), dated April 2019. Byeee bestie, go copy those images 🫶✨