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 --log-level value
29 The log level to be used. Either "trace", "debug", "info", "warn", "er‐
32 ror", "fatal", or "panic", defaulting to "warn".
33 --help, -h
36 Show help
39 --registries-conf path
42 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 --registries-conf-dir path
52 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 --root value
63 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 --runroot value
71 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 --storage-driver value
79 Storage driver. The default storage driver for UID 0 is configured in
82 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
83 rootless mode), and is vfs for other users. The STORAGE_DRIVER envi‐
84 ronment variable overrides the default. The --storage-driver specified
85 driver overrides all.
86 Examples: "overlay", "devicemapper", "vfs"
89 Overriding this option will cause the storage-opt settings in /etc/con‐
92 tainers/storage.conf to be ignored. The user must specify additional
93 options via the --storage-opt flag.
94 --storage-opt value
97 Storage driver option, Default storage driver options are configured in
100 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
101 rootless mode). The STORAGE_OPTS environment variable overrides the de‐
102 fault. The --storage-opt specified options overrides all.
103 --userns-uid-map mapping
106 Directly specifies a UID mapping which should be used to set ownership,
109 at the filesystem level, on the working container's contents. Commands
110 run when handling RUN instructions will default to being run in their
111 own user namespaces, configured using the UID and GID maps.
112 Entries in this map take the form of one or more colon-separated
115 triples of a starting in-container UID, a corresponding starting
116 host-level UID, and the number of consecutive IDs which the map entry
117 represents.
118 This option overrides the remap-uids setting in the options section of
121 /etc/containers/storage.conf.
122 If this option is not specified, but a global --userns-uid-map setting
125 is supplied, settings from the global option will be used.
126 If none of --userns-uid-map-user, --userns-gid-map-group, or
129 --userns-uid-map are specified, but --userns-gid-map is specified, the
130 UID map will be set to use the same numeric values as the GID map.
131 NOTE: When this option is specified by a rootless user, the specified
134 mappings are relative to the rootless usernamespace in the container,
135 rather than being relative to the host as it would be when run rootful.
136 --userns-gid-map mapping
139 Directly specifies a GID mapping which should be used to set ownership,
142 at the filesystem level, on the working container's contents. Commands
143 run when handling RUN instructions will default to being run in their
144 own user namespaces, configured using the UID and GID maps.
145 Entries in this map take the form of one or more colon-separated
148 triples of a starting in-container GID, a corresponding starting
149 host-level GID, and the number of consecutive IDs which the map entry
150 represents.
151 This option overrides the remap-gids setting in the options section of
154 /etc/containers/storage.conf.
155 If this option is not specified, but a global --userns-gid-map setting
158 is supplied, settings from the global option will be used.
159 If none of --userns-uid-map-user, --userns-gid-map-group, or
162 --userns-gid-map are specified, but --userns-uid-map is specified, the
163 GID map will be set to use the same numeric values as the UID map.
164 NOTE: When this option is specified by a rootless user, the specified
167 mappings are relative to the rootless usernamespace in the container,
168 rather than being relative to the host as it would be when run rootful.
169 --version, -v
172 Print the version
175
178 Buildah can set up environment variables from the env entry in the [en‐
179 gine] table in the containers.conf(5). These variables can be overrid‐
180 den by passing environment variables before the buildah commands.
181
184 ┌──────────────────────┬────────────────────────────────┐
185 │Command │ Description │
186 ├──────────────────────┼────────────────────────────────┤
187 │buildah-add(1) │ Add the contents of a file, │
188 │ │ URL, or a directory to the │
189 │ │ container. │
190 ├──────────────────────┼────────────────────────────────┤
191 │buildah-bud(1) │ Build an image using instruc‐ │
192 │ │ tions from Dockerfiles. │
193 ├──────────────────────┼────────────────────────────────┤
194 │buildah-commit(1) │ Create an image from a working │
195 │ │ container. │
196 ├──────────────────────┼────────────────────────────────┤
197 │buildah-config(1) │ Update image configuration │
198 │ │ settings. │
199 ├──────────────────────┼────────────────────────────────┤
200 │buildah-containers(1) │ List the working containers │
201 │ │ and their base images. │
202 ├──────────────────────┼────────────────────────────────┤
203 │buildah-copy(1) │ Copies the contents of a file, │
204 │ │ URL, or directory into a con‐ │
205 │ │ tainer's working directory. │
206 ├──────────────────────┼────────────────────────────────┤
207 │buildah-from(1) │ Creates a new working con‐ │
208 │ │ tainer, either from scratch or │
209 │ │ using a specified image as a │
210 │ │ starting point. │
211 ├──────────────────────┼────────────────────────────────┤
212 │buildah-images(1) │ List images in local storage. │
213 ├──────────────────────┼────────────────────────────────┤
214 │buildah-info(1) │ Display Buildah system infor‐ │
215 │ │ mation. │
216 ├──────────────────────┼────────────────────────────────┤
217 │buildah-inspect(1) │ Inspects the configuration of │
218 │ │ a container or image │
219 ├──────────────────────┼────────────────────────────────┤
220 │buildah-login(1) │ Login to a container registry. │
221 ├──────────────────────┼────────────────────────────────┤
222 │buildah-logout(1) │ Logout of a container registry │
223 ├──────────────────────┼────────────────────────────────┤
224 │buildah-manifest(1) │ Create and manipulate manifest │
225 │ │ lists and image indexes. │
226 ├──────────────────────┼────────────────────────────────┤
227 │buildah-mount(1) │ Mount the working container's │
228 │ │ root filesystem. │
229 ├──────────────────────┼────────────────────────────────┤
230 │buildah-pull(1) │ Pull an image from the speci‐ │
231 │ │ fied location. │
232 ├──────────────────────┼────────────────────────────────┤
233 │buildah-push(1) │ Push an image from local stor‐ │
234 │ │ age to elsewhere. │
235 ├──────────────────────┼────────────────────────────────┤
236 │buildah-rename(1) │ Rename a local container. │
237 ├──────────────────────┼────────────────────────────────┤
238 │buildah-rm(1) │ Removes one or more working │
239 │ │ containers. │
240 ├──────────────────────┼────────────────────────────────┤
241 │buildah-rmi(1) │ Removes one or more images. │
242 ├──────────────────────┼────────────────────────────────┤
243 │buildah-run(1) │ Run a command inside of the │
244 │ │ container. │
245 ├──────────────────────┼────────────────────────────────┤
246 │buildah-tag(1) │ Add an additional name to a │
247 │ │ local image. │
248 ├──────────────────────┼────────────────────────────────┤
249 │buildah-umount(1) │ Unmount a working container's │
250 │ │ root file system. │
251 ├──────────────────────┼────────────────────────────────┤
252 │buildah-unshare(1) │ Launch a command in a user │
253 │ │ namespace with modified ID │
254 │ │ mappings. │
255 ├──────────────────────┼────────────────────────────────┤
256 │buildah-version(1) │ Display the Buildah Version │
257 │ │ Information │
258 ├──────────────────────┼────────────────────────────────┤
259 │ │ │
260 └──────────────────────┴────────────────────────────────┘
261
263 storage.conf (/etc/containers/storage.conf)
264 storage.conf is the storage configuration file for all tools using con‐
267 tainers/storage
268 The storage configuration file specifies all of the available container
271 storage options for tools using shared container storage.
272 mounts.conf (/usr/share/containers/mounts.conf and optionally /etc/con‐
275 tainers/mounts.conf)
276 The mounts.conf files specify volume mount files or directories that
279 are automatically mounted inside containers when executing the buildah
280 run or buildah build-using-dockerfile commands. Container processes
281 can then use this content. The volume mount content does not get com‐
282 mitted to the final image.
283 Usually these directories are used for passing secrets or credentials
286 required by the package software to access remote package repositories.
287 For example, a mounts.conf with the line "/usr/share/rhel/se‐
290 crets:/run/secrets", the content of /usr/share/rhel/secrets directory
291 is mounted on /run/secrets inside the container. This mountpoint al‐
292 lows Red Hat Enterprise Linux subscriptions from the host to be used
293 within the container. It is also possible to omit the destination if
294 it's equal to the source path. For example, specifying /var/lib/se‐
295 crets will mount the directory into the same container destination path
296 /var/lib/secrets.
297 Note this is not a volume mount. The content of the volumes is copied
300 into container storage, not bind mounted directly from the host.
301 registries.conf (/etc/containers/registries.conf)
304 registries.conf is the configuration file which specifies which con‐
307 tainer registries should be consulted when completing image names which
308 do not include a registry or domain portion.
309 registries.d (/etc/containers/registries.d)
312 Directory which contains configuration snippets which specify reg‐
315 istries which should be consulted when completing image names which do
316 not include a registry or domain portion.
317
320 containers.conf(5), containers-mounts.conf(5), newuidmap(1),
321 newgidmap(1), containers-registries.conf(5), containers-storage.conf(5)
322
325 December 2017, Originally compiled by Tom Sweeney tsweeney@redhat.com
326 ⟨mailto:tsweeney@redhat.com⟩
327buildah March 2017 buildah(1)