1CONTAINERS-TRANSPORTS(5) Man CONTAINERS-TRANSPORTS(5)
2Valentin Rothberg April 2019
6
8 containers-transports - description of supported transports for copying
9 and storing container images
10
13 Tools which use the containers/image library, including skopeo(1),
14 buildah(1), podman(1), all share a common syntax for referring to con‐
15 tainer images in various locations. The general form of the syntax is
16 transport:details, where details are dependent on the specified trans‐
17 port, which are documented below.
18 The semantics of the image names ultimately depend on the environment
21 where they are evaluated. For example: if evaluated on a remote server,
22 image names might refer to paths on that server; relative paths are
23 relative to the current directory of the image consumer.
24 containers-storage:[[storage-specifier]]{image-id|docker-reference[@image-
27 id]}
28 An image located in a local containers storage. The format of docker-
29 reference is described in detail in the docker transport.
30 The storage-specifier allows for referencing storage locations on the
33 file system and has the format [[driver@]root[+run-root][:options]]
34 where the optional driver refers to the storage driver (e.g., overlay
35 or btrfs) and where root is an absolute path to the storage's root di‐
36 rectory. The optional run-root can be used to specify the run direc‐
37 tory of the storage where all temporary writable content is stored.
38 The optional options are a comma-separated list of driver-specific op‐
39 tions. Please refer to containers-storage.conf(5) for further informa‐
40 tion on the drivers and supported options.
41 dir:path
44 An existing local directory path storing the manifest, layer tarballs
45 and signatures as individual files. This is a non-standardized format,
46 primarily useful for debugging or noninvasive container inspection.
47 docker://docker-reference
50 An image in a registry implementing the "Docker Registry HTTP API V2".
51 By default, uses the authorization state in $XDG_RUNTIME_DIR/contain‐
52 ers/auth.json, which is set using podman-login(1). If the authoriza‐
53 tion state is not found there, $HOME/.docker/config.json is checked,
54 which is set using docker-login(1). The containers-registries.conf(5)
55 further allows for configuring various settings of a registry.
56 Note that a docker-reference has the following format: name[:tag|@di‐
59 gest]. While the docker transport does not support both a tag and a
60 digest at the same time some formats like containers-storage do. Di‐
61 gests can also be used in an image destination as long as the manifest
62 matches the provided digest. The digest of images can be explored with
63 skopeo-inspect(1). If name does not contain a slash, it is treated as
64 docker.io/library/name. Otherwise, the component before the first
65 slash is checked if it is recognized as a hostname[:port] (i.e., it
66 contains either a . or a :, or the component is exactly localhost). If
67 the first component of name is not recognized as a hostname[:port],
68 name is treated as docker.io/name.
69 docker-archive:path[:{docker-reference|@source-index}]
72 An image is stored in the docker-save(1) formatted file. docker-refer‐
73 ence must not contain a digest. Alternatively, for reading archives,
74 @source-index is a zero-based index in archive manifest (to access un‐
75 tagged images). If neither docker-reference nor @_source_index is
76 specified when reading an archive, the archive must contain exactly one
77 image.
78 The path can refer to a stream, e.g. docker-archive:/dev/stdin.
81 docker-daemon:docker-reference|algo:digest
84 An image stored in the docker daemon's internal storage. The image
85 must be specified as a docker-reference or in an alternative algo:di‐
86 gest format when being used as an image source. The algo:digest refers
87 to the image ID reported by docker-inspect(1).
88 oci:path[:reference]
91 An image in a directory structure compliant with the "Open Container
92 Image Layout Specification" at path.
93 The path value terminates at the first : character; any further : char‐
96 acters are not separators, but a part of reference. The reference is
97 used to set, or match, the org.opencontainers.image.ref.name annotation
98 in the top-level index. If reference is not specified when reading an
99 image, the directory must contain exactly one image.
100 oci-archive:path[:reference]
103 An image in a tar(1) archive with contents compliant with the "Open
104 Container Image Layout Specification" at path.
105 The path value terminates at the first : character; any further : char‐
108 acters are not separators, but a part of reference. The reference is
109 used to set, or match, the org.opencontainers.image.ref.name annotation
110 in the top-level index. If reference is not specified when reading an
111 archive, the archive must contain exactly one image.
112 ostree:docker-reference[@/absolute/repo/path]
115 An image in the local ostree(1) repository. /absolute/repo/path de‐
116 faults to /ostree/repo.
117 sif:path
120 An image using the Singularity image format at path.
121 Only reading images is supported, and not all scripts can be repre‐
124 sented in the OCI format.
125
128 The following examples demonstrate how some of the containers trans‐
129 ports can be used. The examples use skopeo-copy(1) for copying con‐
130 tainer images.
131 Copying an image from one registry to another:
134 $ skopeo copy docker://docker.io/library/alpine:latest docker://localhost:5000/alpine:latest
137 Copying an image from a running Docker daemon to a directory in the OCI
141 layout:
142 $ mkdir alpine-oci
145 $ skopeo copy docker-daemon:alpine:latest oci:alpine-oci
146 $ tree alpine-oci
147 test-oci/
148 ├── blobs
149 │ └── sha256
150 │ ├── 83ef92b73cf4595aa7fe214ec6747228283d585f373d8f6bc08d66bebab531b7
151 │ ├── 9a6259e911dcd0a53535a25a9760ad8f2eded3528e0ad5604c4488624795cecc
152 │ └── ff8df268d29ccbe81cdf0a173076dcfbbea4bb2b6df1dd26766a73cb7b4ae6f7
153 ├── index.json
154 └── oci-layout
155 2 directories, 5 files
157 Copying an image from a registry to the local storage:
161 $ skopeo copy docker://docker.io/library/alpine:latest containers-storage:alpine:latest
164
168 docker-login(1), docker-save(1), ostree(1), podman-login(1), skopeo-
169 copy(1), skopeo-inspect(1), tar(1), container-registries.conf(5), con‐
170 tainers-storage.conf(5)
171
174 Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩ Valentin Roth‐
175 berg rothberg@redhat.com ⟨mailto:rothberg@redhat.com⟩
176Transports Containers CONTAINERS-TRANSPORTS(5)