1buildah(1) General Commands Manual buildah(1)
2
6 Buildah - A command line tool that facilitates building OCI container
7 images.
8
11 buildah [OPTIONS] COMMAND [ARG...]
12
15 The Buildah package provides a command line tool which can be used to:
16 * 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
28 --cgroup-manager=manager
29 The CGroup manager to use for container cgroups. Supported values are
32 cgroupfs or systemd. Default is systemd unless overridden in the con‐
33 tainers.conf file.
34 Note: Setting this flag can cause certain commands to break when called
37 on containers previously created by the other CGroup manager type.
38 Note: CGroup manager is not supported in rootless mode when using
39 CGroups Version V1.
40 --log-level value
43 The log level to be used. Either "trace", "debug", "info", "warn", "er‐
46 ror", "fatal", or "panic", defaulting to "warn".
47 --help, -h
50 Show help
53 --registries-conf path
56 Pathname of the configuration file which specifies which container reg‐
59 istries should be consulted when completing image names which do not
60 include a registry or domain portion. It is not recommended that this
61 option be used, as the default behavior of using the system-wide con‐
62 figuration (/etc/containers/registries.conf) is most often preferred.
63 --registries-conf-dir path
66 Pathname of the directory which contains configuration snippets which
69 specify registries which should be consulted when completing image
70 names which do not include a registry or domain portion. It is not
71 recommended that this option be used, as the default behavior of using
72 the system-wide configuration (/etc/containers/registries.d) is most
73 often preferred.
74 --root value
77 Storage root dir (default: "/var/lib/containers/storage" for UID 0,
80 "$HOME/.local/share/containers/storage" for other users) Default root
81 dir is configured in /etc/containers/storage.conf
82 --runroot value
85 Storage state dir (default: "/run/containers/storage" for UID 0,
88 "/run/user/$UID" for other users) Default state dir is configured in
89 /etc/containers/storage.conf
90 --short-name-alias-conf path
93 Pathname of the file which contains cached mappings between short image
96 names and their corresponding fully-qualified names. It is used for
97 mapping from names of images specified using short names like "ubi8"
98 which don't include a registry component and a corresponding fully-
99 specified name which includes a registry and any other components, such
100 as "registry.access.redhat.com/ubi8". It is not recommended that this
101 option be used, as the default behavior of using the system-wide cache
102 (/var/cache/containers/short-name-aliases.conf) or per-user cache
103 ($HOME/.cache/containers/short-name-aliases.conf) to supplement system-
104 wide defaults is most often preferred.
105 --storage-driver value
108 Storage driver. The default storage driver for UID 0 is configured in
111 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
112 rootless mode), and is vfs for other users. The STORAGE_DRIVER envi‐
113 ronment variable overrides the default. The --storage-driver specified
114 driver overrides all.
115 Examples: "overlay", "vfs"
118 Overriding this option will cause the storage-opt settings in /etc/con‐
121 tainers/storage.conf to be ignored. The user must specify additional
122 options via the --storage-opt flag.
123 --storage-opt value
126 Storage driver option, Default storage driver options are configured in
129 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
130 rootless mode). The STORAGE_OPTS environment variable overrides the de‐
131 fault. The --storage-opt specified options overrides all.
132 --userns-gid-map mapping
135 Directly specifies a GID mapping which should be used to set ownership,
138 at the filesystem level, on the working container's contents. Commands
139 run when handling RUN instructions will default to being run in their
140 own user namespaces, configured using the UID and GID maps.
141 Entries in this map take the form of one or more colon-separated
144 triples of a starting in-container GID, a corresponding starting host-
145 level GID, and the number of consecutive IDs which the map entry repre‐
146 sents.
147 This option overrides the remap-gids setting in the options section of
150 /etc/containers/storage.conf.
151 If this option is not specified, but a global --userns-gid-map setting
154 is supplied, settings from the global option will be used.
155 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
158 gid-map are specified, but --userns-uid-map is specified, the GID map
159 will be set to use the same numeric values as the UID map.
160 NOTE: When this option is specified by a rootless user, the specified
163 mappings are relative to the rootless usernamespace in the container,
164 rather than being relative to the host as it would be when run rootful.
165 --userns-uid-map mapping
168 Directly specifies a UID mapping which should be used to set ownership,
171 at the filesystem level, on the working container's contents. Commands
172 run when handling RUN instructions will default to being run in their
173 own user namespaces, configured using the UID and GID maps.
174 Entries in this map take the form of one or more colon-separated
177 triples of a starting in-container UID, a corresponding starting host-
178 level UID, and the number of consecutive IDs which the map entry repre‐
179 sents.
180 This option overrides the remap-uids setting in the options section of
183 /etc/containers/storage.conf.
184 If this option is not specified, but a global --userns-uid-map setting
187 is supplied, settings from the global option will be used.
188 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
191 uid-map are specified, but --userns-gid-map is specified, the UID map
192 will be set to use the same numeric values as the GID map.
193 NOTE: When this option is specified by a rootless user, the specified
196 mappings are relative to the rootless usernamespace in the container,
197 rather than being relative to the host as it would be when run rootful.
198 --version, -v
201 Print the version
204
207 Buildah can set up environment variables from the env entry in the [en‐
208 gine] table in the containers.conf(5). These variables can be overrid‐
209 den by passing environment variables before the buildah commands.
210
213 ┌───────────┬───────────────────────┬────────────────────────────────┐
214 │Command │ Man Page │ Description │
215 ├───────────┼───────────────────────┼────────────────────────────────┤
216 │add │ buildah-add(1) │ Add the contents of a file, │
217 │ │ │ URL, or a directory to the │
218 │ │ │ container. │
219 ├───────────┼───────────────────────┼────────────────────────────────┤
220 │build │ buildah-build(1) │ Builds an OCI image using in‐ │
221 │ │ │ structions in one or more Con‐ │
222 │ │ │ tainerfiles. │
223 ├───────────┼───────────────────────┼────────────────────────────────┤
224 │commit │ buildah-commit(1) │ Create an image from a working │
225 │ │ │ container. │
226 ├───────────┼───────────────────────┼────────────────────────────────┤
227 │config │ buildah-config(1) │ Update image configuration │
228 │ │ │ settings. │
229 ├───────────┼───────────────────────┼────────────────────────────────┤
230 │containers │ buildah-containers(1) │ List the working containers │
231 │ │ │ and their base images. │
232 ├───────────┼───────────────────────┼────────────────────────────────┤
233 │copy │ buildah-copy(1) │ Copies the contents of a file, │
234 │ │ │ URL, or directory into a con‐ │
235 │ │ │ tainer's working directory. │
236 ├───────────┼───────────────────────┼────────────────────────────────┤
237 │from │ buildah-from(1) │ Creates a new working con‐ │
238 │ │ │ tainer, either from scratch or │
239 │ │ │ using a specified image as a │
240 │ │ │ starting point. │
241 ├───────────┼───────────────────────┼────────────────────────────────┤
242 │images │ buildah-images(1) │ List images in local storage. │
243 ├───────────┼───────────────────────┼────────────────────────────────┤
244 │info │ buildah-info(1) │ Display Buildah system infor‐ │
245 │ │ │ mation. │
246 ├───────────┼───────────────────────┼────────────────────────────────┤
247 │inspect │ buildah-inspect(1) │ Inspects the configuration of │
248 │ │ │ a container or image │
249 ├───────────┼───────────────────────┼────────────────────────────────┤
250 │login │ buildah-login(1) │ Login to a container registry. │
251 ├───────────┼───────────────────────┼────────────────────────────────┤
252 │logout │ buildah-logout(1) │ Logout of a container registry │
253 ├───────────┼───────────────────────┼────────────────────────────────┤
254 │manifest │ buildah-manifest(1) │ Create and manipulate manifest │
255 │ │ │ lists and image indexes. │
256 ├───────────┼───────────────────────┼────────────────────────────────┤
257 │mkcw │ buildah-mkcw(1) │ Convert a conventional con‐ │
258 │ │ │ tainer image into a confiden‐ │
259 │ │ │ tial workload image. │
260 ├───────────┼───────────────────────┼────────────────────────────────┤
261 │mount │ buildah-mount(1) │ Mount the working container's │
262 │ │ │ root filesystem. │
263 ├───────────┼───────────────────────┼────────────────────────────────┤
264 │prune │ buildah-prune(1) │ Cleanup intermediate images as │
265 │ │ │ well as build and mount cache. │
266 ├───────────┼───────────────────────┼────────────────────────────────┤
267 │pull │ buildah-pull(1) │ Pull an image from the speci‐ │
268 │ │ │ fied location. │
269 ├───────────┼───────────────────────┼────────────────────────────────┤
270 │push │ buildah-push(1) │ Push an image from local stor‐ │
271 │ │ │ age to elsewhere. │
272 ├───────────┼───────────────────────┼────────────────────────────────┤
273 │rename │ buildah-rename(1) │ Rename a local container. │
274 ├───────────┼───────────────────────┼────────────────────────────────┤
275 │rm │ buildah-rm(1) │ Removes one or more working │
276 │ │ │ containers. │
277 ├───────────┼───────────────────────┼────────────────────────────────┤
278 │rmi │ buildah-rmi(1) │ Removes one or more images. │
279 ├───────────┼───────────────────────┼────────────────────────────────┤
280 │run │ buildah-run(1) │ Run a command inside of the │
281 │ │ │ container. │
282 ├───────────┼───────────────────────┼────────────────────────────────┤
283 │source │ buildah-source(1) │ Create, push, pull and manage │
284 │ │ │ source images and associated │
285 │ │ │ source artifacts. │
286 ├───────────┼───────────────────────┼────────────────────────────────┤
287 │tag │ buildah-tag(1) │ Add an additional name to a │
288 │ │ │ local image. │
289 ├───────────┼───────────────────────┼────────────────────────────────┤
290 │umount │ buildah-umount(1) │ Unmount a working container's │
291 │ │ │ root file system. │
292 ├───────────┼───────────────────────┼────────────────────────────────┤
293 │unshare │ buildah-unshare(1) │ Launch a command in a user │
294 │ │ │ namespace with modified ID │
295 │ │ │ mappings. │
296 ├───────────┼───────────────────────┼────────────────────────────────┤
297 │version │ buildah-version(1) │ Display the Buildah Version │
298 │ │ │ Information │
299 └───────────┴───────────────────────┴────────────────────────────────┘
300
302 storage.conf (/etc/containers/storage.conf)
303 storage.conf is the storage configuration file for all tools using con‐
306 tainers/storage
307 The storage configuration file specifies all of the available container
310 storage options for tools using shared container storage.
311 mounts.conf (/usr/share/containers/mounts.conf and optionally /etc/con‐
314 tainers/mounts.conf)
315 The mounts.conf files specify volume mount files or directories that
318 are automatically mounted inside containers when executing the buildah
319 run or buildah build commands. Container processes can then use this
320 content. The volume mount content does not get committed to the final
321 image.
322 Usually these directories are used for passing secrets or credentials
325 required by the package software to access remote package repositories.
326 For example, a mounts.conf with the line "/usr/share/rhel/se‐
329 crets:/run/secrets", the content of /usr/share/rhel/secrets directory
330 is mounted on /run/secrets inside the container. This mountpoint al‐
331 lows Red Hat Enterprise Linux subscriptions from the host to be used
332 within the container. It is also possible to omit the destination if
333 it's equal to the source path. For example, specifying /var/lib/se‐
334 crets will mount the directory into the same container destination path
335 /var/lib/secrets.
336 Note this is not a volume mount. The content of the volumes is copied
339 into container storage, not bind mounted directly from the host.
340 registries.conf (/etc/containers/registries.conf)
343 registries.conf is the configuration file which specifies which con‐
346 tainer registries should be consulted when completing image names which
347 do not include a registry or domain portion.
348 registries.d (/etc/containers/registries.d)
351 Directory which contains configuration snippets which specify reg‐
354 istries which should be consulted when completing image names which do
355 not include a registry or domain portion.
356
359 containers.conf(5), containers-mounts.conf(5), newuidmap(1),
360 newgidmap(1), containers-registries.conf(5), containers-storage.conf(5)
361
364 December 2017, Originally compiled by Tom Sweeney tsweeney@redhat.com
365 ⟨mailto:tsweeney@redhat.com⟩
366buildah March 2017 buildah(1)