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 It is further possible to copy data to stdin by specifying docker-ar‐
81 chive:/dev/stdin but note that the used file must be seekable.
82 docker-daemon:docker-reference|algo:digest
85 An image stored in the docker daemon's internal storage. The image
86 must be specified as a docker-reference or in an alternative algo:di‐
87 gest format when being used as an image source. The algo:digest refers
88 to the image ID reported by docker-inspect(1).
89 oci:path[:reference]
92 An image compliant with the "Open Container Image Layout Specification"
93 at path. Using a reference is optional and allows for storing multiple
94 images at the same path.
95 oci-archive:path[:reference]
98 An image compliant with the "Open Container Image Layout Specification"
99 stored as a tar(1) archive at path.
100 ostree:docker-reference[@/absolute/repo/path]
103 An image in the local ostree(1) repository. /absolute/repo/path de‐
104 faults to /ostree/repo.
105
108 The following examples demonstrate how some of the containers trans‐
109 ports can be used. The examples use skopeo-copy(1) for copying con‐
110 tainer images.
111 Copying an image from one registry to another:
114 $ skopeo copy docker://docker.io/library/alpine:latest docker://localhost:5000/alpine:latest
117 Copying an image from a running Docker daemon to a directory in the OCI
121 layout:
122 $ mkdir alpine-oci
125 $ skopeo copy docker-daemon:alpine:latest oci:alpine-oci
126 $ tree alpine-oci
127 test-oci/
128 ├── blobs
129 │ └── sha256
130 │ ├── 83ef92b73cf4595aa7fe214ec6747228283d585f373d8f6bc08d66bebab531b7
131 │ ├── 9a6259e911dcd0a53535a25a9760ad8f2eded3528e0ad5604c4488624795cecc
132 │ └── ff8df268d29ccbe81cdf0a173076dcfbbea4bb2b6df1dd26766a73cb7b4ae6f7
133 ├── index.json
134 └── oci-layout
135 2 directories, 5 files
137 Copying an image from a registry to the local storage:
141 $ skopeo copy docker://docker.io/library/alpine:latest containers-storage:alpine:latest
144
148 docker-login(1), docker-save(1), ostree(1), podman-login(1), skopeo-
149 copy(1), skopeo-inspect(1), tar(1), container-registries.conf(5), con‐
150 tainers-storage.conf(5)
151
154 Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩ Valentin Roth‐
155 berg rothberg@redhat.com ⟨mailto:rothberg@redhat.com⟩
156Transports Containers CONTAINERS-TRANSPORTS(5)