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
119
120
121       Pull image policy. The default is missing.
122
123
124              • missing:  attempt to pull the latest image from the registries
125                listed in registries.conf if a local  image  does  not  exist.
126                Raise  an error if the image is not in any listed registry and
127                is not present locally.
128
129              • always: Pull the image from the first registry it is found  in
130                as  listed in  registries.conf. Raise an error if not found in
131                the registries, even if the image is present locally.
132
133              • never: do not pull the image from the registry, use  only  the
134                local  version. Raise an error if the image is not present lo‐
135                cally.
136
137
138
139       --quiet, -q
140
141
142       If an image needs to be pulled from  the  registry,  suppress  progress
143       output.
144
145
146       --remove-signatures
147
148
149       Don't copy signatures when pulling images.
150
151
152       --tls-verify bool-value
153
154
155       Require  HTTPS  and  verification  of certificates when talking to con‐
156       tainer registries (defaults to true).  TLS verification cannot be  used
157       when talking to an insecure registry.
158
159
160       --variant=""
161
162
163       Set the architecture variant of the image to be pulled.
164
165

EXAMPLE

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

ENVIRONMENT

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

FILES

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