Ubuntu Manpage: containers-transports - description of supported transports for copying and storing

Provided by: golang-github-containers-image_5.29.2-2_all

NAME

       containers-transports  -  description  of  supported  transports  for  copying and storing
       container images

DESCRIPTION

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 transport:details, where details are dependent on the
specified transport, which are documented below.

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.

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: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-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[:port]
(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:path[:{docker-reference|@source-index}]
An image is stored in the docker-save(1) formatted file. 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.

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

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:path[:reference]
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. If reference is not
specified when reading an image, the directory must contain exactly one image.

oci-archive:path[:reference]
An image in a tar(1) archive with contents 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. If reference is not
specified when reading an archive, the archive must contain exactly one image.

ostree:docker-reference[@/absolute/repo/path]
An image in the local ostree(1) repository. /absolute/repo/path defaults to /ostree/repo.

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

AUTHORS

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

NAME

DESCRIPTION

Examples

SEE ALSO

AUTHORS