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       ostree:image[@/absolute/repo/path]
60         An image in local OSTree repository.  /absolute/repo/path defaults to
61       /ostree/repo.
62
63
64   DEPENDENCIES
65       Buildah resolves the path to the registry to pull  from  by  using  the
66       /etc/containers/registries.conf file, registries.conf(5).  If the buil‐
67       dah pull command fails with an "image not known"  error,  first  verify
68       that  the  registries.conf  file  is installed and configured appropri‐
69       ately.
70
71

RETURN VALUE

73       The image ID of the image that was pulled.  On error 1 is returned.
74
75

OPTIONS

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

EXAMPLE

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

Files

163       registries.conf (/etc/containers/registries.conf)
164
165
166       registries.conf  is  the  configuration file which specifies which con‐
167       tainer registries should be consulted when completing image names which
168       do not include a registry or domain portion.
169
170
171       policy.json (/etc/containers/policy.json)
172
173
174       Signature  policy  file.   This  defines the trust policy for container
175       images.  Controls which container registries can be used for image, and
176       whether or not the tool should trust the images.
177
178