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       --authfile path
79
80
81       Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
82       ers/auth.json, which is set using buildah login.  If the  authorization
83       state  is  not found there, $HOME/.docker/config.json is checked, which
84       is set using docker login.
85
86
87       --cert-dir path
88
89
90       Use certificates at path (*.crt, *.cert, *.key) to connect to the  reg‐
91       istry.  The default certificates directory is /etc/containers/certs.d.
92
93
94       --creds creds
95
96
97       The  [username[:password]]  to use to authenticate with the registry if
98       required.  If one or both values  are  not  supplied,  a  command  line
99       prompt  will  appear  and  the  value  can be entered.  The password is
100       entered without echo.
101
102
103       --quiet, -q
104
105
106       If an image needs to be pulled from  the  registry,  suppress  progress
107       output.
108
109
110       --remove-signatures
111
112
113       Don't copy signatures when pulling images.
114
115
116       --shm-size=""
117
118
119       Size  of /dev/shm. The format is <number><unit>. number must be greater
120       than 0.  Unit  is  optional  and  can  be  b  (bytes),  k  (kilobytes),
121       m(megabytes),  or g (gigabytes).  If you omit the unit, the system uses
122       bytes. If you omit the size entirely, the system uses 64m.
123
124
125       --tls-verify bool-value
126
127
128       Require HTTPS and verify certificates when talking  to  container  reg‐
129       istries (defaults to true)
130
131

EXAMPLE

133       buildah pull imagename
134
135
136       buildah pull docker://myregistry.example.com/imagename
137
138
139       buildah pull docker-daemon:imagename:imagetag
140
141
142       buildah pull docker-archive:filename
143
144
145       buildah pull oci-archive:filename
146
147
148       buildah pull dir:directoryname
149
150
151       buildah    pull    --tls-verify=false    myregistry/myrepository/image‐
152       name:imagetag
153
154
155       buildah pull --creds=myusername:mypassword  --cert-dir    /auth  myreg‐
156       istry/myrepository/imagename:imagetag
157
158
159       buildah  pull  --authfile=/tmp/auths/myauths.json  myregistry/myreposi‐
160       tory/imagename:imagetag
161
162

ENVIRONMENT

164       BUILD_REGISTRY_SOURCES
165
166
167       BUILD_REGISTRY_SOURCES, if set, is treated as a JSON object which  con‐
168       tains  lists  of  registry  names  under  the  keys insecureRegistries,
169       blockedRegistries, and allowedRegistries.
170
171
172       When pulling an image from a registry, if  the  name  of  the  registry
173       matches  any of the items in the blockedRegistries list, the image pull
174       attempt is denied.  If there are registries  in  the  allowedRegistries
175       list,  and  the registry's name is not in the list, the pull attempt is
176       denied.
177
178
179       TMPDIR The TMPDIR environment variable allows the user to specify where
180       temporary  files are stored while pulling and pushing images.  Defaults
181       to '/var/tmp'.
182
183

FILES

185       registries.conf (/etc/containers/registries.conf)
186
187
188       registries.conf is the configuration file which  specifies  which  con‐
189       tainer registries should be consulted when completing image names which
190       do not include a registry or domain portion.
191
192
193       policy.json (/etc/containers/policy.json)
194
195
196       Signature policy file.  This defines the  trust  policy  for  container
197       images.  Controls which container registries can be used for image, and
198       whether or not the tool should trust the images.
199
200