buildah-pull(1)

1buildah-pull(1)             General Commands Manual            buildah-pull(1)
2
3
4

NAME

6       buildah-pull - Pull an image from a registry.
7
8

SYNOPSIS

10       buildah pull [options] image
11
12

DESCRIPTION

14       Pulls  an image based upon the specified image name.  Image names use a
15       "transport":"details" format.
16
17
18       Multiple transports are supported:
19
20
21       dir:path
22         An existing local directory path containing the manifest, layer  tar‐
23       balls,  and  signatures in individual files. This is a non-standardized
24       format, primarily useful for debugging or noninvasive image inspection.
25
26
27       docker://docker-reference (Default)
28         An image in a registry implementing the  "Docker  Registry  HTTP  API
29       V2".   By   default,   uses   the  authorization  state  in  $XDG\_RUN‐
30       TIME\_DIR/containers/auth.json, which is set using (buildah login).  If
31       the  authorization  state is not found there, $HOME/.docker/config.json
32       is checked, which is set using (docker login).
33         If docker-reference does not include a registry name, localhost  will
34       be  consulted first, followed by any registries named in the registries
35       configuration.
36
37
38       docker-archive:path
39         An image is retrieved as a docker load formatted file.
40
41
42       docker-daemon:docker-reference
43         An image docker-reference stored  in  the  docker  daemon's  internal
44       storage.   docker-reference  must  include  either  a  tag or a digest.
45       Alternatively, when reading images, the format can also be  docker-dae‐
46       mon:algo:digest (an image ID).
47
48
49       oci:path:tag**
50         An image tag in a directory compliant with "Open Container Image Lay‐
51       out Specification" at path.
52
53
54       oci-archive:path:tag
55         An image tag in a directory compliant with "Open Container Image Lay‐
56       out Specification" at path.
57
58
59   DEPENDENCIES
60       Buildah  resolves  the  path  to the registry to pull from by using the
61       /etc/containers/registries.conf  file,   containers-registries.conf(5).
62       If  the  buildah  pull  command  fails with an "image not known" error,
63       first verify that the registries.conf file is installed and  configured
64       appropriately.
65
66

RETURN VALUE

68       The image ID of the image that was pulled.  On error 1 is returned.
69
70

OPTIONS

72       --all-tags, -a
73
74
75       All tagged images in the repository will be pulled.
76
77
78       --arch="ARCH"
79
80
81       Set the ARCH of the image to be pulled to the provided value instead of
82       using the architecture of the  host.  (Examples:  aarch64,  arm,  i686,
83       ppc64le, s390x, x86_64)
84
85
86       --authfile path
87
88
89       Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
90       ers/auth.json, which is set using buildah login.  If the  authorization
91       state  is  not found there, $HOME/.docker/config.json is checked, which
92       is set using docker login.
93
94
95       --cert-dir path
96
97
98       Use certificates at path (*.crt, *.cert, *.key) to connect to the  reg‐
99       istry.  The default certificates directory is /etc/containers/certs.d.
100
101
102       --creds creds
103
104
105       The  [username[:password]]  to use to authenticate with the registry if
106       required.  If one or both values  are  not  supplied,  a  command  line
107       prompt  will  appear  and  the  value  can be entered.  The password is
108       entered without echo.
109
110
111       --decryption-key key[:passphrase]
112
113
114       The [key[:passphrase]] to be used for decryption  of  images.  Key  can
115       point  to  keys  and/or certificates. Decryption will be tried with all
116       keys. If the key is protected by a passphrase, it  is  required  to  be
117       passed in the argument and omitted otherwise.
118
119
120       --quiet, -q
121
122
123       If  an  image  needs  to be pulled from the registry, suppress progress
124       output.
125
126
127       --os="OS"
128
129
130       Set the OS of the image to be pulled instead of using the current oper‐
131       ating system of the host.
132
133
134       --os="OS"
135
136
137       Set  the  OS of the image to be pulled to the provided value instead of
138       using the current operating system of the host.
139
140
141       --policy=always|missing|never
142
143
144       Pull image policy. The default is missing.
145
146
147              · missing: attempt to pull the latest image from the  registries
148                listed  in  registries.conf  if  a local image does not exist.
149                Raise an error if the image is not in any listed registry  and
150                is not present locally.
151
152              · always:  Pull the image from the first registry it is found in
153                as listed in  registries.conf. Raise an error if not found  in
154                the registries, even if the image is present locally.
155
156              · never:  do  not pull the image from the registry, use only the
157                local version. Raise an error if  the  image  is  not  present
158                locally.
159
160
161
162       --remove-signatures
163
164
165       Don't copy signatures when pulling images.
166
167
168       --tls-verify bool-value
169
170
171       Require  HTTPS  and  verification  of certificates when talking to con‐
172       tainer registries (defaults to true).  TLS verification cannot be  used
173       when talking to an insecure registry.
174
175
176       --variant=""
177
178
179       Set the architecture variant of the image to be pulled.
180
181

EXAMPLE

183       buildah pull imagename
184
185
186       buildah pull docker://myregistry.example.com/imagename
187
188
189       buildah pull docker-daemon:imagename:imagetag
190
191
192       buildah pull docker-archive:filename
193
194
195       buildah pull oci-archive:filename
196
197
198       buildah pull dir:directoryname
199
200
201       buildah    pull    --tls-verify=false    myregistry/myrepository/image‐
202       name:imagetag
203
204
205       buildah pull  --creds=myusername:mypassword  --cert-dir  ~/auth  myreg‐
206       istry/myrepository/imagename:imagetag
207
208
209       buildah  pull  --authfile=/tmp/auths/myauths.json  myregistry/myreposi‐
210       tory/imagename:imagetag
211
212
213       buildah pull --arch=aarch64 myregistry/myrepository/imagename:imagetag
214
215
216       buildah  pull  --arch=arm  --variant=v7  myregistry/myrepository/image‐
217       name:imagetag
218
219

ENVIRONMENT

221       BUILD_REGISTRY_SOURCES
222
223
224       BUILD_REGISTRY_SOURCES,  if set, is treated as a JSON object which con‐
225       tains lists  of  registry  names  under  the  keys  insecureRegistries,
226       blockedRegistries, and allowedRegistries.
227
228
229       When  pulling  an  image  from  a registry, if the name of the registry
230       matches any of the items in the blockedRegistries list, the image  pull
231       attempt  is  denied.   If there are registries in the allowedRegistries
232       list, and the registry's name is not in the list, the pull  attempt  is
233       denied.
234
235
236       TMPDIR The TMPDIR environment variable allows the user to specify where
237       temporary files are stored while pulling and pushing images.   Defaults
238       to '/var/tmp'.
239
240

FILES

242       registries.conf (/etc/containers/registries.conf)
243
244
245       registries.conf  is  the  configuration file which specifies which con‐
246       tainer registries should be consulted when completing image names which
247       do not include a registry or domain portion.
248
249
250       policy.json (/etc/containers/policy.json)
251
252
253       Signature  policy  file.   This  defines the trust policy for container
254       images.  Controls which container registries can be used for image, and
255       whether or not the tool should trust the images.
256
257