1buildah(1) General Commands Manual buildah(1)
2
3
4
6 Buildah - A command line tool that facilitates building OCI container
7 images.
8
9
11 buildah [OPTIONS] COMMAND [ARG...]
12
13
15 The Buildah package provides a command line tool which can be used to:
16
17
18 * Create a working container, either from scratch or using an image as a starting point.
19 * Mount a working container's root filesystem for manipulation.
20 * Unmount a working container's root filesystem.
21 * Use the updated contents of a container's root filesystem as a filesystem layer to create a new image.
22 * Delete a working container or an image.
23 * Rename a local container.
24
25
26
28 --log-level value
29
30
31 The log level to be used. Either "trace", "debug", "info", "warn", "er‐
32 ror", "fatal", or "panic", defaulting to "warn".
33
34
35 --help, -h
36
37
38 Show help
39
40
41 --registries-conf path
42
43
44 Pathname of the configuration file which specifies which container reg‐
45 istries should be consulted when completing image names which do not
46 include a registry or domain portion. It is not recommended that this
47 option be used, as the default behavior of using the system-wide con‐
48 figuration (/etc/containers/registries.conf) is most often preferred.
49
50
51 --registries-conf-dir path
52
53
54 Pathname of the directory which contains configuration snippets which
55 specify registries which should be consulted when completing image
56 names which do not include a registry or domain portion. It is not
57 recommended that this option be used, as the default behavior of using
58 the system-wide configuration (/etc/containers/registries.d) is most
59 often preferred.
60
61
62 --root value
63
64
65 Storage root dir (default: "/var/lib/containers/storage" for UID 0,
66 "$HOME/.local/share/containers/storage" for other users) Default root
67 dir is configured in /etc/containers/storage.conf
68
69
70 --runroot value
71
72
73 Storage state dir (default: "/run/containers/storage" for UID 0,
74 "/run/user/$UID" for other users) Default state dir is configured in
75 /etc/containers/storage.conf
76
77
78 --short-name-alias-conf path
79
80
81 Pathname of the file which contains cached mappings between short image
82 names and their corresponding fully-qualified names. It is used for
83 mapping from names of images specified using short names like "hello-
84 world" which don't include a registry component and a corresponding
85 fully-specified name which includes a registry and any other compo‐
86 nents, such as "docker.io/library/hello-world". It is not recommended
87 that this option be used, as the default behavior of using the system-
88 wide cache (/var/cache/containers/short-name-aliases.conf) or per-user
89 cache ($HOME/.cache/containers/short-name-aliases.conf) to supplement
90 system-wide defaults is most often preferred.
91
92
93 --storage-driver value
94
95
96 Storage driver. The default storage driver for UID 0 is configured in
97 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
98 rootless mode), and is vfs for other users. The STORAGE_DRIVER envi‐
99 ronment variable overrides the default. The --storage-driver specified
100 driver overrides all.
101
102
103 Examples: "overlay", "devicemapper", "vfs"
104
105
106 Overriding this option will cause the storage-opt settings in /etc/con‐
107 tainers/storage.conf to be ignored. The user must specify additional
108 options via the --storage-opt flag.
109
110
111 --storage-opt value
112
113
114 Storage driver option, Default storage driver options are configured in
115 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
116 rootless mode). The STORAGE_OPTS environment variable overrides the de‐
117 fault. The --storage-opt specified options overrides all.
118
119
120 --userns-uid-map mapping
121
122
123 Directly specifies a UID mapping which should be used to set ownership,
124 at the filesystem level, on the working container's contents. Commands
125 run when handling RUN instructions will default to being run in their
126 own user namespaces, configured using the UID and GID maps.
127
128
129 Entries in this map take the form of one or more colon-separated
130 triples of a starting in-container UID, a corresponding starting host-
131 level UID, and the number of consecutive IDs which the map entry repre‐
132 sents.
133
134
135 This option overrides the remap-uids setting in the options section of
136 /etc/containers/storage.conf.
137
138
139 If this option is not specified, but a global --userns-uid-map setting
140 is supplied, settings from the global option will be used.
141
142
143 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
144 uid-map are specified, but --userns-gid-map is specified, the UID map
145 will be set to use the same numeric values as the GID map.
146
147
148 NOTE: When this option is specified by a rootless user, the specified
149 mappings are relative to the rootless usernamespace in the container,
150 rather than being relative to the host as it would be when run rootful.
151
152
153 --userns-gid-map mapping
154
155
156 Directly specifies a GID mapping which should be used to set ownership,
157 at the filesystem level, on the working container's contents. Commands
158 run when handling RUN instructions will default to being run in their
159 own user namespaces, configured using the UID and GID maps.
160
161
162 Entries in this map take the form of one or more colon-separated
163 triples of a starting in-container GID, a corresponding starting host-
164 level GID, and the number of consecutive IDs which the map entry repre‐
165 sents.
166
167
168 This option overrides the remap-gids setting in the options section of
169 /etc/containers/storage.conf.
170
171
172 If this option is not specified, but a global --userns-gid-map setting
173 is supplied, settings from the global option will be used.
174
175
176 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
177 gid-map are specified, but --userns-uid-map is specified, the GID map
178 will be set to use the same numeric values as the UID map.
179
180
181 NOTE: When this option is specified by a rootless user, the specified
182 mappings are relative to the rootless usernamespace in the container,
183 rather than being relative to the host as it would be when run rootful.
184
185
186 --version, -v
187
188
189 Print the version
190
191
193 Buildah can set up environment variables from the env entry in the [en‐
194 gine] table in the containers.conf(5). These variables can be overrid‐
195 den by passing environment variables before the buildah commands.
196
197
199 ┌──────────────────────┬────────────────────────────────┐
200 │Command │ Description │
201 ├──────────────────────┼────────────────────────────────┤
202 │buildah-add(1) │ Add the contents of a file, │
203 │ │ URL, or a directory to the │
204 │ │ container. │
205 ├──────────────────────┼────────────────────────────────┤
206 │buildah-build(1) │ Build an image using instruc‐ │
207 │ │ tions from Dockerfiles. │
208 ├──────────────────────┼────────────────────────────────┤
209 │buildah-commit(1) │ Create an image from a working │
210 │ │ container. │
211 ├──────────────────────┼────────────────────────────────┤
212 │buildah-config(1) │ Update image configuration │
213 │ │ settings. │
214 ├──────────────────────┼────────────────────────────────┤
215 │buildah-containers(1) │ List the working containers │
216 │ │ and their base images. │
217 ├──────────────────────┼────────────────────────────────┤
218 │buildah-copy(1) │ Copies the contents of a file, │
219 │ │ URL, or directory into a con‐ │
220 │ │ tainer's working directory. │
221 ├──────────────────────┼────────────────────────────────┤
222 │buildah-from(1) │ Creates a new working con‐ │
223 │ │ tainer, either from scratch or │
224 │ │ using a specified image as a │
225 │ │ starting point. │
226 ├──────────────────────┼────────────────────────────────┤
227 │buildah-images(1) │ List images in local storage. │
228 ├──────────────────────┼────────────────────────────────┤
229 │buildah-info(1) │ Display Buildah system infor‐ │
230 │ │ mation. │
231 ├──────────────────────┼────────────────────────────────┤
232 │buildah-inspect(1) │ Inspects the configuration of │
233 │ │ a container or image │
234 ├──────────────────────┼────────────────────────────────┤
235 │buildah-login(1) │ Login to a container registry. │
236 ├──────────────────────┼────────────────────────────────┤
237 │buildah-logout(1) │ Logout of a container registry │
238 ├──────────────────────┼────────────────────────────────┤
239 │buildah-manifest(1) │ Create and manipulate manifest │
240 │ │ lists and image indexes. │
241 ├──────────────────────┼────────────────────────────────┤
242 │buildah-mount(1) │ Mount the working container's │
243 │ │ root filesystem. │
244 ├──────────────────────┼────────────────────────────────┤
245 │buildah-pull(1) │ Pull an image from the speci‐ │
246 │ │ fied location. │
247 ├──────────────────────┼────────────────────────────────┤
248 │buildah-push(1) │ Push an image from local stor‐ │
249 │ │ age to elsewhere. │
250 ├──────────────────────┼────────────────────────────────┤
251 │buildah-rename(1) │ Rename a local container. │
252 ├──────────────────────┼────────────────────────────────┤
253 │buildah-rm(1) │ Removes one or more working │
254 │ │ containers. │
255 ├──────────────────────┼────────────────────────────────┤
256 │buildah-rmi(1) │ Removes one or more images. │
257 ├──────────────────────┼────────────────────────────────┤
258 │buildah-run(1) │ Run a command inside of the │
259 │ │ container. │
260 ├──────────────────────┼────────────────────────────────┤
261 │buildah-source(1) │ Create, push, pull and manage │
262 │ │ source images and associated │
263 │ │ source artifacts. │
264 ├──────────────────────┼────────────────────────────────┤
265 │buildah-tag(1) │ Add an additional name to a │
266 │ │ local image. │
267 ├──────────────────────┼────────────────────────────────┤
268 │buildah-umount(1) │ Unmount a working container's │
269 │ │ root file system. │
270 ├──────────────────────┼────────────────────────────────┤
271 │buildah-unshare(1) │ Launch a command in a user │
272 │ │ namespace with modified ID │
273 │ │ mappings. │
274 ├──────────────────────┼────────────────────────────────┤
275 │buildah-version(1) │ Display the Buildah Version │
276 │ │ Information │
277 └──────────────────────┴────────────────────────────────┘
278
280 storage.conf (/etc/containers/storage.conf)
281
282
283 storage.conf is the storage configuration file for all tools using con‐
284 tainers/storage
285
286
287 The storage configuration file specifies all of the available container
288 storage options for tools using shared container storage.
289
290
291 mounts.conf (/usr/share/containers/mounts.conf and optionally /etc/con‐
292 tainers/mounts.conf)
293
294
295 The mounts.conf files specify volume mount files or directories that
296 are automatically mounted inside containers when executing the buildah
297 run or buildah build-using-dockerfile commands. Container processes
298 can then use this content. The volume mount content does not get com‐
299 mitted to the final image.
300
301
302 Usually these directories are used for passing secrets or credentials
303 required by the package software to access remote package repositories.
304
305
306 For example, a mounts.conf with the line "/usr/share/rhel/se‐
307 crets:/run/secrets", the content of /usr/share/rhel/secrets directory
308 is mounted on /run/secrets inside the container. This mountpoint al‐
309 lows Red Hat Enterprise Linux subscriptions from the host to be used
310 within the container. It is also possible to omit the destination if
311 it's equal to the source path. For example, specifying /var/lib/se‐
312 crets will mount the directory into the same container destination path
313 /var/lib/secrets.
314
315
316 Note this is not a volume mount. The content of the volumes is copied
317 into container storage, not bind mounted directly from the host.
318
319
320 registries.conf (/etc/containers/registries.conf)
321
322
323 registries.conf is the configuration file which specifies which con‐
324 tainer registries should be consulted when completing image names which
325 do not include a registry or domain portion.
326
327
328 registries.d (/etc/containers/registries.d)
329
330
331 Directory which contains configuration snippets which specify reg‐
332 istries which should be consulted when completing image names which do
333 not include a registry or domain portion.
334
335
337 containers.conf(5), containers-mounts.conf(5), newuidmap(1),
338 newgidmap(1), containers-registries.conf(5), containers-storage.conf(5)
339
340
342 December 2017, Originally compiled by Tom Sweeney tsweeney@redhat.com
343 ⟨mailto:tsweeney@redhat.com⟩
344
345
346
347buildah March 2017 buildah(1)