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, registries.conf(5).  If the buil‐
62       dah  pull  command  fails with an "image not known" error, first verify
63       that the registries.conf file is  installed  and  configured  appropri‐
64       ately.
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       --shm-size=""
111
112
113       Size  of /dev/shm. The format is <number><unit>. number must be greater
114       than 0.  Unit  is  optional  and  can  be  b  (bytes),  k  (kilobytes),
115       m(megabytes),  or g (gigabytes).  If you omit the unit, the system uses
116       bytes. If you omit the size entirely, the system uses 64m.
117
118
119       --tls-verify bool-value
120
121
122       Require HTTPS and verify certificates when talking  to  container  reg‐
123       istries (defaults to true)
124
125

EXAMPLE

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

ENVIRONMENT

158       BUILD_REGISTRY_SOURCES
159
160
161       BUILD_REGISTRY_SOURCES, if set, is treated as a JSON object which  con‐
162       tains  lists  of  registry  names  under  the  keys insecureRegistries,
163       blockedRegistries, and allowedRegistries.
164
165
166       When pulling an image from a registry, if  the  name  of  the  registry
167       matches  any of the items in the blockedRegistries list, the image pull
168       attempt is denied.  If there are registries  in  the  allowedRegistries
169       list,  and  the registry's name is not in the list, the pull attempt is
170       denied.
171
172

FILES

174       registries.conf (/etc/containers/registries.conf)
175
176
177       registries.conf is the configuration file which  specifies  which  con‐
178       tainer registries should be consulted when completing image names which
179       do not include a registry or domain portion.
180
181
182       policy.json (/etc/containers/policy.json)
183
184
185       Signature policy file.  This defines the  trust  policy  for  container
186       images.  Controls which container registries can be used for image, and
187       whether or not the tool should trust the images.
188
189