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 input. It supports all trans‐
15       ports from containers-transports(5) (see examples below). If no  trans‐
16       port  is  specified, the input is subject to short-name resolution (see
17       containers-registries.conf(5)) and the  docker  (i.e.,  container  reg‐
18       istry) transport is used.
19
20
21   DEPENDENCIES
22       Buildah  resolves  the  path  to the registry to pull from by using the
23       /etc/containers/registries.conf  file,   containers-registries.conf(5).
24       If  the  buildah  pull  command  fails with an "image not known" error,
25       first verify that the registries.conf file is installed and  configured
26       appropriately.
27
28

RETURN VALUE

30       The image ID of the image that was pulled.  On error 1 is returned.
31
32

OPTIONS

34       --all-tags, -a
35
36
37       All tagged images in the repository will be pulled.
38
39
40       --arch="ARCH"
41
42
43       Set the ARCH of the image to be pulled to the provided value instead of
44       using the architecture of the host. (Examples: arm, arm64, 386,  amd64,
45       ppc64le, s390x)
46
47
48       --authfile path
49
50
51       Path  of  the  authentication file. Default is ${XDG_\RUNTIME_DIR}/con‐
52       tainers/auth.json. If  XDG_RUNTIME_DIR  is  not  set,  the  default  is
53       /run/containers/$UID/auth.json.  This file is created using buildah lo‐
54       gin.
55
56
57       If the authorization  state  is  not  found  there,  $HOME/.docker/con‐
58       fig.json is checked, which is set using docker login.
59
60
61       Note: You can also override the default path of the authentication file
62       by setting the REGISTRY_AUTH_FILE  environment  variable.  export  REG‐
63       ISTRY_AUTH_FILE=path
64
65
66       --cert-dir path
67
68
69       Use  certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
70       istry.  The default certificates directory is /etc/containers/certs.d.
71
72
73       --creds creds
74
75
76       The [username[:password]] to use to authenticate with the  registry  if
77       required.   If  one  or  both  values  are not supplied, a command line
78       prompt will appear and the value can be entered.  The password  is  en‐
79       tered without echo.
80
81
82       --decryption-key key[:passphrase]
83
84
85       The  [key[:passphrase]]  to  be  used for decryption of images. Key can
86       point to keys and/or certificates. Decryption will be  tried  with  all
87       keys.  If  the  key  is protected by a passphrase, it is required to be
88       passed in the argument and omitted otherwise.
89
90
91       --os="OS"
92
93
94       Set the OS of the image to be pulled instead of using the current oper‐
95       ating system of the host.
96
97
98       --platform="OS/ARCH[/VARIANT]"
99
100
101       Set the OS/ARCH of the image to be pulled to the provided value instead
102       of using the current operating system and architecture of the host (for
103       example linux/arm).
104
105
106       OS/ARCH  pairs  are those used by the Go Programming Language.  In sev‐
107       eral cases the ARCH value for a platform differs from one  produced  by
108       other  tools  such as the arch command.  Valid OS and architecture name
109       combinations  are  listed  as  values  for   $GOOS   and   $GOARCH   at
110       https://golang.org/doc/install/source#environment,   and  can  also  be
111       found by running go tool dist list.
112
113
114       NOTE: The --platform option may not be used  in  combination  with  the
115       --arch, --os, or --variant options.
116
117
118       --policy=always|missing|never|newer
119
120
121       Pull image policy. The default is missing.
122
123
124              • always:  Always  pull the image and throw an error if the pull
125                fails.
126
127              • missing: Pull the image only if it could not be found  in  the
128                local containers storage.  Throw an error if no image could be
129                found and the pull fails.
130
131              • never: Never pull the image but use the  one  from  the  local
132                containers  storage.   Throw  an  error  if  no image could be
133                found.
134
135              • newer: Pull if the image on the registry is newer than the one
136                in the local containers storage.  An image is considered to be
137                newer when the digests  are  different.   Comparing  the  time
138                stamps  is  prone  to errors.  Pull errors are suppressed if a
139                local image was found.
140
141
142
143       --quiet, -q
144
145
146       If an image needs to be pulled from  the  registry,  suppress  progress
147       output.
148
149
150       --remove-signatures
151
152
153       Don't copy signatures when pulling images.
154
155
156       --retry attempts
157
158
159       Number of times to retry in case of failure when performing pull of im‐
160       ages from registry.
161
162
163       Defaults to 3.
164
165
166       --retry-delay duration
167
168
169       Duration of delay between retry attempts in case of failure  when  per‐
170       forming pull of images from registry.
171
172
173       Defaults to 2s.
174
175
176       --tls-verify bool-value
177
178
179       Require  HTTPS  and  verification  of certificates when talking to con‐
180       tainer registries (defaults to true).  TLS verification cannot be  used
181       when talking to an insecure registry.
182
183
184       --variant=""
185
186
187       Set the architecture variant of the image to be pulled.
188
189

EXAMPLE

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

ENVIRONMENT

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

FILES

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