e2e81a
% CONTAINERS-TRANSPORTS 5 Containers Transports Man Page
5dd126
% Valentin Rothberg
5dd126
% April 2019
5dd126
5dd126
## NAME
5dd126
5dd126
containers-transports - description of supported transports for copying and storing container images
5dd126
5dd126
## DESCRIPTION
5dd126
5dd126
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.
5dd126
The general form of the syntax is _transport:details_, where details are dependent on the specified transport, which are documented below.
5dd126
c929c0
The semantics of the image names ultimately depend on the environment where
c929c0
they are evaluated. For example: if evaluated on a remote server, image names
c929c0
might refer to paths on that server; relative paths are relative to the current
c929c0
directory of the image consumer.
c929c0
5dd126
### **containers-storage**:[**[**storage-specifier**]**]{image-id|docker-reference[@image-id]}
5dd126
5dd126
An image located in a local containers storage.
5dd126
The format of _docker-reference_ is described in detail in the **docker** transport.
5dd126
5dd126
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.
5dd126
The optional `run-root` can be used to specify the run directory of the storage where all temporary writable content is stored.
5dd126
The optional `options` are a comma-separated list of driver-specific options.
5dd126
Please refer to containers-storage.conf(5) for further information on the drivers and supported options.
5dd126
5dd126
### **dir:**_path_
5dd126
5dd126
An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files.
5dd126
This is a non-standardized format, primarily useful for debugging or noninvasive container inspection.
5dd126
5dd126
### **docker://**_docker-reference_
5dd126
5dd126
An image in a registry implementing the "Docker Registry HTTP API V2".
5dd126
By default, uses the authorization state in `$XDG_RUNTIME_DIR/containers/auth.json`, which is set using podman-login(1).
5dd126
If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using docker-login(1).
5dd126
The containers-registries.conf(5) further allows for configuring various settings of a registry.
5dd126
5dd126
Note that a _docker-reference_ has the following format: `name[:tag|@digest]`.
5dd126
While the docker transport does not support both a tag and a digest at the same time some formats like containers-storage do.
5dd126
Digests can also be used in an image destination as long as the manifest matches the provided digest.
5dd126
The digest of images can be explored with skopeo-inspect(1).
5dd126
If `name` does not contain a slash, it is treated as `docker.io/library/name`.
5dd126
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).
5dd126
If the first component of name is not recognized as a `hostname[:port]`, `name` is treated as `docker.io/name`.
5dd126
5dd126
### **docker-archive:**_path[:{docker-reference|@source-index}]_
5dd126
5dd126
An image is stored in the docker-save(1) formatted file.
5dd126
_docker-reference_ must not contain a digest.
5dd126
Alternatively, for reading archives, @_source-index_ is a zero-based index in archive manifest
5dd126
(to access untagged images).
5dd126
If neither _docker-reference_ nor @_source_index is specified when reading an archive, the archive must contain exactly one image.
5dd126
5dd126
It is further possible to copy data to stdin by specifying `docker-archive:/dev/stdin` but note that the used file must be seekable.
5dd126
5dd126
### **docker-daemon:**_docker-reference|algo:digest_
5dd126
5dd126
An image stored in the docker daemon's internal storage.
5dd126
The image must be specified as a _docker-reference_ or in an alternative _algo:digest_ format when being used as an image source.
5dd126
The _algo:digest_ refers to the image ID reported by docker-inspect(1).
5dd126
e2e81a
### **oci:**_path[:reference]_
5dd126
5dd126
An image compliant with the "Open Container Image Layout Specification" at _path_.
e2e81a
Using a _reference_ is optional and allows for storing multiple images at the same _path_.
5dd126
e2e81a
### **oci-archive:**_path[:reference]_
5dd126
5dd126
An image compliant with the "Open Container Image Layout Specification" stored as a tar(1) archive at _path_.
5dd126
5dd126
### **ostree:**_docker-reference[@/absolute/repo/path]_
5dd126
5dd126
An image in the local ostree(1) repository.
5dd126
_/absolute/repo/path_ defaults to _/ostree/repo_.
5dd126
5dd126
## Examples
5dd126
5dd126
The following examples demonstrate how some of the containers transports can be used.
5dd126
The examples use skopeo-copy(1) for copying container images.
5dd126
5dd126
**Copying an image from one registry to another**:
5dd126
```
5dd126
$ skopeo copy docker://docker.io/library/alpine:latest docker://localhost:5000/alpine:latest
5dd126
```
5dd126
5dd126
**Copying an image from a running Docker daemon to a directory in the OCI layout**:
5dd126
```
5dd126
$ mkdir alpine-oci
5dd126
$ skopeo copy docker-daemon:alpine:latest oci:alpine-oci
5dd126
$ tree alpine-oci
5dd126
test-oci/
5dd126
├── blobs
5dd126
│   └── sha256
5dd126
│       ├── 83ef92b73cf4595aa7fe214ec6747228283d585f373d8f6bc08d66bebab531b7
5dd126
│       ├── 9a6259e911dcd0a53535a25a9760ad8f2eded3528e0ad5604c4488624795cecc
5dd126
│       └── ff8df268d29ccbe81cdf0a173076dcfbbea4bb2b6df1dd26766a73cb7b4ae6f7
5dd126
├── index.json
5dd126
└── oci-layout
5dd126
5dd126
2 directories, 5 files
5dd126
```
5dd126
5dd126
**Copying an image from a registry to the local storage**:
5dd126
```
5dd126
$ skopeo copy docker://docker.io/library/alpine:latest containers-storage:alpine:latest
5dd126
```
5dd126
5dd126
## SEE ALSO
5dd126
5dd126
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)
5dd126
5dd126
## AUTHORS
5dd126
5dd126
Miloslav Trmač <mitr@redhat.com>
5dd126
Valentin Rothberg <rothberg@redhat.com>