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 "debug", "info", "warn" or "error",
32 per default "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
102 default. 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 --userns-gid-map mapping
134 Directly specifies a GID mapping which should be used to set ownership,
137 at the filesystem level, on the working container's contents. Commands
138 run when handling RUN instructions will default to being run in their
139 own user namespaces, configured using the UID and GID maps.
140 Entries in this map take the form of one or more colon-separated
143 triples of a starting in-container GID, a corresponding starting
144 host-level GID, and the number of consecutive IDs which the map entry
145 represents.
146 This option overrides the remap-gids setting in the options section of
149 /etc/containers/storage.conf.
150 If this option is not specified, but a global --userns-gid-map setting
153 is supplied, settings from the global option will be used.
154 If none of --userns-uid-map-user, --userns-gid-map-group, or
157 --userns-gid-map are specified, but --userns-uid-map is specified, the
158 GID map will be set to use the same numeric values as the UID map.
159 --version, -v
162 Print the version
165
168 Buildah can set up environment variables from the env entry in the
169 [engine] table in the containers.conf(5). These variables can be over‐
170 ridden by passing environment variables before the buildah commands.
171
174 ┌──────────────────────┬────────────────────────────────┐
175 │Command │ Description │
176 ├──────────────────────┼────────────────────────────────┤
177 │buildah-add(1) │ Add the contents of a file, │
178 │ │ URL, or a directory to the │
179 │ │ container. │
180 ├──────────────────────┼────────────────────────────────┤
181 │buildah-bud(1) │ Build an image using instruc‐ │
182 │ │ tions from Dockerfiles. │
183 ├──────────────────────┼────────────────────────────────┤
184 │buildah-commit(1) │ Create an image from a working │
185 │ │ container. │
186 ├──────────────────────┼────────────────────────────────┤
187 │buildah-config(1) │ Update image configuration │
188 │ │ settings. │
189 ├──────────────────────┼────────────────────────────────┤
190 │buildah-containers(1) │ List the working containers │
191 │ │ and their base images. │
192 ├──────────────────────┼────────────────────────────────┤
193 │buildah-copy(1) │ Copies the contents of a file, │
194 │ │ URL, or directory into a con‐ │
195 │ │ tainer's working directory. │
196 ├──────────────────────┼────────────────────────────────┤
197 │buildah-from(1) │ Creates a new working con‐ │
198 │ │ tainer, either from scratch or │
199 │ │ using a specified image as a │
200 │ │ starting point. │
201 ├──────────────────────┼────────────────────────────────┤
202 │buildah-images(1) │ List images in local storage. │
203 ├──────────────────────┼────────────────────────────────┤
204 │buildah-info(1) │ Display Buildah system infor‐ │
205 │ │ mation. │
206 ├──────────────────────┼────────────────────────────────┤
207 │buildah-inspect(1) │ Inspects the configuration of │
208 │ │ a container or image │
209 ├──────────────────────┼────────────────────────────────┤
210 │buildah-login(1) │ Login to a container registry. │
211 ├──────────────────────┼────────────────────────────────┤
212 │buildah-logout(1) │ Logout of a container registry │
213 ├──────────────────────┼────────────────────────────────┤
214 │buildah-manifest(1) │ Create and manipulate manifest │
215 │ │ lists and image indexes. │
216 ├──────────────────────┼────────────────────────────────┤
217 │buildah-mount(1) │ Mount the working container's │
218 │ │ root filesystem. │
219 ├──────────────────────┼────────────────────────────────┤
220 │buildah-pull(1) │ Pull an image from the speci‐ │
221 │ │ fied location. │
222 ├──────────────────────┼────────────────────────────────┤
223 │buildah-push(1) │ Push an image from local stor‐ │
224 │ │ age to elsewhere. │
225 ├──────────────────────┼────────────────────────────────┤
226 │buildah-rename(1) │ Rename a local container. │
227 ├──────────────────────┼────────────────────────────────┤
228 │buildah-rm(1) │ Removes one or more working │
229 │ │ containers. │
230 ├──────────────────────┼────────────────────────────────┤
231 │buildah-rmi(1) │ Removes one or more images. │
232 ├──────────────────────┼────────────────────────────────┤
233 │buildah-run(1) │ Run a command inside of the │
234 │ │ container. │
235 ├──────────────────────┼────────────────────────────────┤
236 │buildah-tag(1) │ Add an additional name to a │
237 │ │ local image. │
238 ├──────────────────────┼────────────────────────────────┤
239 │buildah-umount(1) │ Unmount a working container's │
240 │ │ root file system. │
241 ├──────────────────────┼────────────────────────────────┤
242 │buildah-unshare(1) │ Launch a command in a user │
243 │ │ namespace with modified ID │
244 │ │ mappings. │
245 ├──────────────────────┼────────────────────────────────┤
246 │buildah-version(1) │ Display the Buildah Version │
247 │ │ Information │
248 ├──────────────────────┼────────────────────────────────┤
249 │ │ │
250 └──────────────────────┴────────────────────────────────┘
251
253 storage.conf (/etc/containers/storage.conf)
254 storage.conf is the storage configuration file for all tools using con‐
257 tainers/storage
258 The storage configuration file specifies all of the available container
261 storage options for tools using shared container storage.
262 mounts.conf (/usr/share/containers/mounts.conf and optionally /etc/con‐
265 tainers/mounts.conf)
266 The mounts.conf files specify volume mount files or directories that
269 are automatically mounted inside containers when executing the buildah
270 run or buildah build-using-dockerfile commands. Container processes
271 can then use this content. The volume mount content does not get com‐
272 mitted to the final image.
273 Usually these directories are used for passing secrets or credentials
276 required by the package software to access remote package repositories.
277 For example, a mounts.conf with the line
280 "/usr/share/rhel/secrets:/run/secrets", the content of
281 /usr/share/rhel/secrets directory is mounted on /run/secrets inside the
282 container. This mountpoint allows Red Hat Enterprise Linux subscrip‐
283 tions from the host to be used within the container. It is also possi‐
284 ble to omit the destination if it's equal to the source path. For
285 example, specifying /var/lib/secrets will mount the directory into the
286 same container destination path /var/lib/secrets.
287 Note this is not a volume mount. The content of the volumes is copied
290 into container storage, not bind mounted directly from the host.
291 registries.conf (/etc/containers/registries.conf)
294 registries.conf is the configuration file which specifies which con‐
297 tainer registries should be consulted when completing image names which
298 do not include a registry or domain portion.
299 registries.d (/etc/containers/registries.d)
302 Directory which contains configuration snippets which specify reg‐
305 istries which should be consulted when completing image names which do
306 not include a registry or domain portion.
307
310 containers.conf(5), containers-mounts.conf(5), newuidmap(1),
311 newgidmap(1), containers-registries.conf(5), containers-storage.conf(5)
312
315 December 2017, Originally compiled by Tom Sweeney tsweeney@redhat.com
316 ⟨mailto:tsweeney@redhat.com⟩
317buildah March 2017 buildah(1)