containers-transports

CONTAINERS-TRANSPORTS(5) Man CONTAINERS-TRANSPORTS(5)

Valentin Rothberg April 2019

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 gen
   eral 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 stor
   age  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 nonin
   vasive 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 i.e., it con
   tains 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.

   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-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|@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.opencontain
   ers.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.  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 im
   age.

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.opencontain
   ers.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

SEE ALSO

   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)

AUTHORS

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

Transports Containers CONTAINERS-TRANSPORTS(5)