.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\fC[[driver@]root[+run-root][:options]]\fR where the optional \fB\fCdriver\fR refers to the storage driver (e.g., overlay or btrfs) and where \fB\fCroot\fR is an absolute path to the storage's root directory.
The optional \fB\fCrun-root\fR can be used to specify the run directory of the storage where all temporary writable content is stored.
The optional \fB\fCoptions\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\fC$XDG_RUNTIME_DIR/containers/auth.json\fR, which is set using podman-login(1).
If the authorization state is not found there, \fB\fC$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: \fB\fCname[:tag|@digest]\fR\&.
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 digest of images can be explored with skopeo-inspect(1).
If \fB\fCname\fR does not contain a slash, it is treated as \fB\fCdocker.io/library/name\fR\&.
Otherwise, the component before the first slash is checked if it is recognized as a \fB\fChostname[: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 \fB\fChostname[:port]\fR, \fB\fCname\fR is treated as \fB\fCdocker.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
It is further possible to copy data to stdin by specifying \fB\fCdocker-archive:/dev/stdin\fR but note that the used file must be seekable.

.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 compliant with the "Open Container Image Layout Specification" at \fIpath\fP\&.
Using a \fIreference\fP is optional and allows for storing multiple images at the same \fIpath\fP\&.

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

.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\&.

.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:

.PP
.RS

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

.fi
.RE

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

.PP
.RS

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

.fi
.RE

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

.PP
.RS

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

.fi
.RE

.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]