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 using buil‐
54       dah login.
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       --quiet, -q
92
93
94       If an image needs to be pulled from  the  registry,  suppress  progress
95       output.
96
97
98       --os="OS"
99
100
101       Set the OS of the image to be pulled instead of using the current oper‐
102       ating system of the host.
103
104
105       --platform="OS/ARCH[/VARIANT]"
106
107
108       Set the OS/ARCH of the image to be pulled to the provided value instead
109       of using the current operating system and architecture of the host (for
110       example linux/arm).  If --platform is  set,  then  the  values  of  the
111       --arch, --os, and --variant options will be overridden.
112
113
114       OS/ARCH  pairs  are those used by the Go Programming Language.  In sev‐
115       eral cases the ARCH value for a platform differs from one  produced  by
116       other  tools  such as the arch command.  Valid OS and architecture name
117       combinations  are  listed  as  values  for   $GOOS   and   $GOARCH   at
118       https://golang.org/doc/install/source#environment,   and  can  also  be
119       found by running go tool dist list.
120
121
122       --policy=always|missing|never
123
124
125       Pull image policy. The default is missing.
126
127
128              • missing: attempt to pull the latest image from the  registries
129                listed  in  registries.conf  if  a local image does not exist.
130                Raise an error if the image is not in any listed registry  and
131                is not present locally.
132
133              • always:  Pull the image from the first registry it is found in
134                as listed in  registries.conf. Raise an error if not found  in
135                the registries, even if the image is present locally.
136
137              • never:  do  not pull the image from the registry, use only the
138                local version. Raise an error if the image is not present  lo‐
139                cally.
140
141
142
143       --remove-signatures
144
145
146       Don't copy signatures when pulling images.
147
148
149       --tls-verify bool-value
150
151
152       Require  HTTPS  and  verification  of certificates when talking to con‐
153       tainer registries (defaults to true).  TLS verification cannot be  used
154       when talking to an insecure registry.
155
156
157       --variant=""
158
159
160       Set the architecture variant of the image to be pulled.
161
162

EXAMPLE

164       buildah pull imagename
165
166
167       buildah pull docker://myregistry.example.com/imagename
168
169
170       buildah pull docker-daemon:imagename:imagetag
171
172
173       buildah pull docker-archive:filename
174
175
176       buildah pull oci-archive:filename
177
178
179       buildah pull dir:directoryname
180
181
182       buildah  pull  --tls-verify=false myregistry/myrepository/imagename:im‐
183       agetag
184
185
186       buildah pull  --creds=myusername:mypassword  --cert-dir  ~/auth  myreg‐
187       istry/myrepository/imagename:imagetag
188
189
190       buildah  pull  --authfile=/tmp/auths/myauths.json  myregistry/myreposi‐
191       tory/imagename:imagetag
192
193
194       buildah pull --arch=aarch64 myregistry/myrepository/imagename:imagetag
195
196
197       buildah  pull  --arch=arm  --variant=v7  myregistry/myrepository/image‐
198       name:imagetag
199
200

ENVIRONMENT

202       BUILD_REGISTRY_SOURCES
203
204
205       BUILD_REGISTRY_SOURCES,  if set, is treated as a JSON object which con‐
206       tains lists  of  registry  names  under  the  keys  insecureRegistries,
207       blockedRegistries, and allowedRegistries.
208
209
210       When  pulling  an  image  from  a registry, if the name of the registry
211       matches any of the items in the blockedRegistries list, the image  pull
212       attempt  is  denied.   If there are registries in the allowedRegistries
213       list, and the registry's name is not in the list, the pull  attempt  is
214       denied.
215
216
217       TMPDIR The TMPDIR environment variable allows the user to specify where
218       temporary files are stored while pulling and pushing images.   Defaults
219       to '/var/tmp'.
220
221

FILES

223       registries.conf (/etc/containers/registries.conf)
224
225
226       registries.conf  is  the  configuration file which specifies which con‐
227       tainer registries should be consulted when completing image names which
228       do not include a registry or domain portion.
229
230
231       policy.json (/etc/containers/policy.json)
232
233
234       Signature policy file.  This defines the trust policy for container im‐
235       ages.  Controls which container registries can be used for  image,  and
236       whether or not the tool should trust the images.
237
238