.nh
.TH CONTAINERS-TRANSPORTS 5 Containers Transports Man Page
Valentin Rothberg
April 2019
.SH NAME
.PP
containers-transports - description of supported transports for copying and storing container images

.SH DESCRIPTION
.PP
Tools which use the containers/image library, including skopeo(1), buildah(1), podman(1), all share a common syntax for referring to container images in various locations.
The general form of the syntax is \fItransport:details\fP, where details are dependent on the specified transport, which are documented below.

.PP
The semantics of the 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.

.SS \fBcontainers-storage\fP:[\fB[\fPstorage-specifier\fB]\fP]{image-id|docker-reference[@image-id]}
.PP
An image located in a local containers storage.
The format of \fIdocker-reference\fP is described in detail in the \fBdocker\fP transport.

.PP
The \fIstorage-specifier\fP allows for referencing storage locations on the file system and has the format \fB[[driver@]root[+run-root][:options]]\fR where the optional \fBdriver\fR refers to the storage driver (e.g., overlay or btrfs) and where \fBroot\fR is an absolute path to the storage's root directory.
The optional \fBrun-root\fR can be used to specify the run directory of the storage where all temporary writable content is stored.
The optional \fBoptions\fR 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.

.SS \fBdir:\fP\fIpath\fP
.PP
An existing local directory \fIpath\fP storing the manifest, layer tarballs and signatures as individual files.
This is a non-standardized format, primarily useful for debugging or noninvasive container inspection.

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

.PP
Note that a \fIdocker-reference\fP has the following format: \fIname\fP[\fB:\fP\fItag\fP | \fB@\fP\fIdigest\fP].
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.

.PP
The docker transport supports pushing images without a tag or digest to a registry when the image name is suffixed with \fB@@unknown-digest@@\fP\&. The \fIname\fP\fB@@unknown-digest@@\fP 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).

.PP
If \fBname\fR does not contain a slash, it is treated as \fBdocker.io/library/name\fR\&.
Otherwise, the component before the first slash is checked if it is recognized as a \fBhostname[:port]\fR (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 \fBhostname[:port]\fR, \fBname\fR is treated as \fBdocker.io/name\fR\&.

.SS \fBdocker-archive:\fP\fIpath[:{docker-reference|@source-index}]\fP
.PP
An image is stored in the docker-save(1) formatted file.
\fIdocker-reference\fP must not contain a digest.
Alternatively, for reading archives, @\fIsource-index\fP is a zero-based index in archive manifest
(to access untagged images).
If neither \fIdocker-reference\fP nor @_source_index is specified when reading an archive, the archive must contain exactly one image.

.PP
The \fIpath\fP can refer to a stream, e.g. \fBdocker-archive:/dev/stdin\fR\&.

.SS \fBdocker-daemon:\fP\fIdocker-reference|algo:digest\fP
.PP
An image stored in the docker daemon's internal storage.
The image must be specified as a \fIdocker-reference\fP or in an alternative \fIalgo:digest\fP format when being used as an image source.
The \fIalgo:digest\fP refers to the image ID reported by docker-inspect(1).

.SS \fBoci:\fP\fIpath[:reference]\fP
.PP
An image in a directory structure compliant with the "Open Container Image Layout Specification" at \fIpath\fP\&.

.PP
The \fIpath\fP value terminates at the first \fB:\fR character; any further \fB:\fR characters are not separators, but a part of \fIreference\fP\&.
The \fIreference\fP is used to set, or match, the \fBorg.opencontainers.image.ref.name\fR annotation in the top-level index.
If \fIreference\fP is not specified when reading an image, the directory must contain exactly one image.

.SS \fBoci-archive:\fP\fIpath[:reference]\fP
.PP
An image in a tar(1) archive with contents compliant with the "Open Container Image Layout Specification" at \fIpath\fP\&.

.PP
The \fIpath\fP value terminates at the first \fB:\fR character; any further \fB:\fR characters are not separators, but a part of \fIreference\fP\&.
The \fIreference\fP is used to set, or match, the \fBorg.opencontainers.image.ref.name\fR annotation in the top-level index.
If \fIreference\fP is not specified when reading an archive, the archive must contain exactly one image.

.SS \fBostree:\fP\fIdocker-reference[@/absolute/repo/path]\fP
.PP
An image in the local ostree(1) repository.
\fI/absolute/repo/path\fP defaults to \fI/ostree/repo\fP\&.

.SS \fBsif:\fP\fIpath\fP
.PP
An image using the Singularity image format at \fIpath\fP\&.

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

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

.PP
\fBCopying an image from one registry to another\fP:

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

.EE

.PP
\fBCopying an image from a running Docker daemon to a directory in the OCI layout\fP:

.EX
$ 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

.EE

.PP
\fBCopying an image from a registry to the local storage\fP:

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

.EE

.SH SEE ALSO
.PP
docker-login(1), docker-save(1), ostree(1), podman-login(1), skopeo-copy(1), skopeo-inspect(1), tar(1), container-registries.conf(5), containers-storage.conf(5)

.SH AUTHORS
.PP
Miloslav Trmač mitr@redhat.com
\[la]mailto:mitr@redhat.com\[ra]
Valentin Rothberg rothberg@redhat.com
\[la]mailto:rothberg@redhat.com\[ra]