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.  Al‐
45       ternatively, 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}/con‐
90       tainers/auth.json. If  XDG_RUNTIME_DIR  is  not  set,  the  default  is
91       /run/containers/$UID/auth.json.  This file is created using using buil‐
92       dah login.
93
94
95       If the authorization  state  is  not  found  there,  $HOME/.docker/con‐
96       fig.json is checked, which is set using docker login.
97
98
99       Note: You can also override the default path of the authentication file
100       by setting the REGISTRY_AUTH_FILE  environment  variable.  export  REG‐
101       ISTRY_AUTH_FILE=path
102
103
104       --cert-dir path
105
106
107       Use  certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
108       istry.  The default certificates directory is /etc/containers/certs.d.
109
110
111       --creds creds
112
113
114       The [username[:password]] to use to authenticate with the  registry  if
115       required.   If  one  or  both  values  are not supplied, a command line
116       prompt will appear and the value can be entered.  The password  is  en‐
117       tered without echo.
118
119
120       --decryption-key key[:passphrase]
121
122
123       The  [key[:passphrase]]  to  be  used for decryption of images. Key can
124       point to keys and/or certificates. Decryption will be  tried  with  all
125       keys.  If  the  key  is protected by a passphrase, it is required to be
126       passed in the argument and omitted otherwise.
127
128
129       --quiet, -q
130
131
132       If an image needs to be pulled from  the  registry,  suppress  progress
133       output.
134
135
136       --os="OS"
137
138
139       Set the OS of the image to be pulled instead of using the current oper‐
140       ating system of the host.
141
142
143       --os="OS"
144
145
146       Set the OS of the image to be pulled to the provided value  instead  of
147       using the current operating system of the host.
148
149
150       --policy=always|missing|never
151
152
153       Pull image policy. The default is missing.
154
155
156              • missing:  attempt to pull the latest image from the registries
157                listed in registries.conf if a local  image  does  not  exist.
158                Raise  an error if the image is not in any listed registry and
159                is not present locally.
160
161              • always: Pull the image from the first registry it is found  in
162                as  listed in  registries.conf. Raise an error if not found in
163                the registries, even if the image is present locally.
164
165              • never: do not pull the image from the registry, use  only  the
166                local  version. Raise an error if the image is not present lo‐
167                cally.
168
169
170
171       --remove-signatures
172
173
174       Don't copy signatures when pulling images.
175
176
177       --tls-verify bool-value
178
179
180       Require HTTPS and verification of certificates  when  talking  to  con‐
181       tainer  registries (defaults to true).  TLS verification cannot be used
182       when talking to an insecure registry.
183
184
185       --variant=""
186
187
188       Set the architecture variant of the image to be pulled.
189
190

EXAMPLE

192       buildah pull imagename
193
194
195       buildah pull docker://myregistry.example.com/imagename
196
197
198       buildah pull docker-daemon:imagename:imagetag
199
200
201       buildah pull docker-archive:filename
202
203
204       buildah pull oci-archive:filename
205
206
207       buildah pull dir:directoryname
208
209
210       buildah pull  --tls-verify=false  myregistry/myrepository/imagename:im‐
211       agetag
212
213
214       buildah  pull  --creds=myusername:mypassword  --cert-dir  ~/auth myreg‐
215       istry/myrepository/imagename:imagetag
216
217
218       buildah  pull  --authfile=/tmp/auths/myauths.json  myregistry/myreposi‐
219       tory/imagename:imagetag
220
221
222       buildah pull --arch=aarch64 myregistry/myrepository/imagename:imagetag
223
224
225       buildah  pull  --arch=arm  --variant=v7  myregistry/myrepository/image‐
226       name:imagetag
227
228

ENVIRONMENT

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

FILES

251       registries.conf (/etc/containers/registries.conf)
252
253
254       registries.conf is the configuration file which  specifies  which  con‐
255       tainer registries should be consulted when completing image names which
256       do not include a registry or domain portion.
257
258
259       policy.json (/etc/containers/policy.json)
260
261
262       Signature policy file.  This defines the trust policy for container im‐
263       ages.   Controls  which container registries can be used for image, and
264       whether or not the tool should trust the images.
265
266