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