.nh
.TH buildah "1" "March 2017" "buildah"
.SH NAME
.PP
Buildah \- A command line tool that facilitates building OCI container images.

.SH SYNOPSIS
.PP
buildah [OPTIONS] COMMAND [ARG...]

.SH DESCRIPTION
.PP
The Buildah package provides a command line tool which can be used to:

.PP
.RS

.nf
* Create a working container, either from scratch or using an image as a starting point.
* Mount a working container's root filesystem for manipulation.
* Unmount a working container's root filesystem.
* Use the updated contents of a container's root filesystem as a filesystem layer to create a new image.
* Delete a working container or an image.
* Rename a local container.

.fi
.RE

.SH OPTIONS
.PP
\fB\-\-log\-level\fP \fBvalue\fP

.PP
The log level to be used. Either "debug", "info", "warn" or "error", per default "warn".

.PP
\fB\-\-help, \-h\fP

.PP
Show help

.PP
\fB\-\-registries\-conf\fP \fIpath\fP

.PP
Pathname of the configuration file which specifies which container registries should be
consulted when completing image names which do not include a registry or domain
portion.  It is not recommended that this option be used, as the default
behavior of using the system\-wide configuration
(\fI/etc/containers/registries.conf\fP) is most often preferred.

.PP
\fB\-\-registries\-conf\-dir\fP \fIpath\fP

.PP
Pathname of the directory which contains configuration snippets which specify
registries which should be consulted when completing image names which do not
include a registry or domain portion.  It is not recommended that this option
be used, as the default behavior of using the system\-wide configuration
(\fI/etc/containers/registries.d\fP) is most often preferred.

.PP
\fB\-\-root\fP \fBvalue\fP

.PP
Storage root dir (default: "/var/lib/containers/storage" for UID 0, "$HOME/.local/share/containers/storage" for other users)
Default root dir is configured in /etc/containers/storage.conf

.PP
\fB\-\-runroot\fP \fBvalue\fP

.PP
Storage state dir (default: "/run/containers/storage" for UID 0, "/run/user/$UID" for other users)
Default state dir is configured in /etc/containers/storage.conf

.PP
\fB\-\-storage\-driver\fP \fBvalue\fP

.PP
Storage driver.  The default storage driver for UID 0 is configured in /etc/containers/storage.conf (\fB\fC$HOME/.config/containers/storage.conf\fR in rootless mode), and is \fIvfs\fP for other users.  The \fB\fCSTORAGE\_DRIVER\fR environment variable overrides the default.  The \-\-storage\-driver specified driver overrides all.

.PP
Examples: "overlay", "devicemapper", "vfs"

.PP
Overriding this option will cause the \fIstorage\-opt\fP settings in /etc/containers/storage.conf to be ignored.  The user must
specify additional options via the \fB\fC\-\-storage\-opt\fR flag.

.PP
\fB\-\-storage\-opt\fP \fBvalue\fP

.PP
Storage driver option, Default storage driver options are configured in /etc/containers/storage.conf (\fB\fC$HOME/.config/containers/storage.conf\fR in rootless mode). The \fB\fCSTORAGE\_OPTS\fR environment variable overrides the default. The \-\-storage\-opt specified options overrides all.

.PP
\fB\-\-userns\-uid\-map\fP \fImapping\fP

.PP
Directly specifies a UID mapping which should be used to set ownership, at the
filesystem level, on the working container's contents.
Commands run when handling \fB\fCRUN\fR instructions will default to being run in
their own user namespaces, configured using the UID and GID maps.

.PP
Entries in this map take the form of one or more colon\-separated triples of a starting
in\-container UID, a corresponding starting host\-level UID, and the number of
consecutive IDs which the map entry represents.

.PP
This option overrides the \fIremap\-uids\fP setting in the \fIoptions\fP section of
/etc/containers/storage.conf.

.PP
If this option is not specified, but a global \-\-userns\-uid\-map setting is
supplied, settings from the global option will be used.

.PP
If none of \-\-userns\-uid\-map\-user, \-\-userns\-gid\-map\-group, or \-\-userns\-uid\-map
are specified, but \-\-userns\-gid\-map is specified, the UID map will be set to
use the same numeric values as the GID map.

.PP
\fB\-\-userns\-gid\-map\fP \fImapping\fP

.PP
Directly specifies a GID mapping which should be used to set ownership, at the
filesystem level, on the working container's contents.
Commands run when handling \fB\fCRUN\fR instructions will default to being run in
their own user namespaces, configured using the UID and GID maps.

.PP
Entries in this map take the form of one or more colon\-separated triples of a starting
in\-container GID, a corresponding starting host\-level GID, and the number of
consecutive IDs which the map entry represents.

.PP
This option overrides the \fIremap\-gids\fP setting in the \fIoptions\fP section of
/etc/containers/storage.conf.

.PP
If this option is not specified, but a global \-\-userns\-gid\-map setting is
supplied, settings from the global option will be used.

.PP
If none of \-\-userns\-uid\-map\-user, \-\-userns\-gid\-map\-group, or \-\-userns\-gid\-map
are specified, but \-\-userns\-uid\-map is specified, the GID map will be set to
use the same numeric values as the UID map.

.PP
\fB\-\-version\fP, \fB\-v\fP

.PP
Print the version

.SH Environment Variables
.PP
Buildah can set up environment variables from the env entry in the [engine] table in the containers.conf(5). These variables can be overridden by passing environment variables before the \fB\fCbuildah\fR commands.

.SH COMMANDS
.TS
allbox;
l l 
l l .
\fB\fCCommand\fR	\fB\fCDescription\fR
buildah\-add(1)	T{
Add the contents of a file, URL, or a directory to the container.
T}
buildah\-bud(1)	T{
Build an image using instructions from Dockerfiles.
T}
buildah\-commit(1)	T{
Create an image from a working container.
T}
buildah\-config(1)	T{
Update image configuration settings.
T}
buildah\-containers(1)	T{
List the working containers and their base images.
T}
buildah\-copy(1)	T{
Copies the contents of a file, URL, or directory into a container's working directory.
T}
buildah\-from(1)	T{
Creates a new working container, either from scratch or using a specified image as a starting point.
T}
buildah\-images(1)	List images in local storage.
buildah\-info(1)	T{
Display Buildah system information.
T}
buildah\-inspect(1)	T{
Inspects the configuration of a container or image
T}
buildah\-login(1)	Login to a container registry.
buildah\-logout(1)	Logout of a container registry
buildah\-manifest(1)	T{
Create and manipulate manifest lists and image indexes.
T}
buildah\-mount(1)	T{
Mount the working container's root filesystem.
T}
buildah\-pull(1)	T{
Pull an image from the specified location.
T}
buildah\-push(1)	T{
Push an image from local storage to elsewhere.
T}
buildah\-rename(1)	Rename a local container.
buildah\-rm(1)	T{
Removes one or more working containers.
T}
buildah\-rmi(1)	Removes one or more images.
buildah\-run(1)	T{
Run a command inside of the container.
T}
buildah\-tag(1)	T{
Add an additional name to a local image.
T}
buildah\-umount(1)	T{
Unmount a working container's root file system.
T}
buildah\-unshare(1)	T{
Launch a command in a user namespace with modified ID mappings.
T}
buildah\-version(1)	T{
Display the Buildah Version Information
T}
.TE

.SH Files
.PP
\fBstorage.conf\fP (\fB\fC/etc/containers/storage.conf\fR)

.PP
storage.conf is the storage configuration file for all tools using containers/storage

.PP
The storage configuration file specifies all of the available container storage options for tools using shared container storage.

.PP
\fBmounts.conf\fP (\fB\fC/usr/share/containers/mounts.conf\fR and optionally \fB\fC/etc/containers/mounts.conf\fR)

.PP
The mounts.conf files specify volume mount files or directories that are automatically mounted inside containers when executing the \fB\fCbuildah run\fR or \fB\fCbuildah build\-using\-dockerfile\fR commands.  Container processes can then use this content.  The volume mount content does not get committed to the final image.

.PP
Usually these directories are used for passing secrets or credentials required by the package software to access remote package repositories.

.PP
For example, a mounts.conf with the line "\fB\fC/usr/share/rhel/secrets:/run/secrets\fR", the content of \fB\fC/usr/share/rhel/secrets\fR directory is mounted on \fB\fC/run/secrets\fR inside the container.  This mountpoint allows Red Hat Enterprise Linux subscriptions from the host to be used within the container.  It is also possible to omit the destination if it's equal to the source path.  For example, specifying \fB\fC/var/lib/secrets\fR will mount the directory into the same container destination path \fB\fC/var/lib/secrets\fR\&.

.PP
Note this is not a volume mount. The content of the volumes is copied into container storage, not bind mounted directly from the host.

.PP
\fBregistries.conf\fP (\fB\fC/etc/containers/registries.conf\fR)

.PP
registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.

.PP
\fBregistries.d\fP (\fB\fC/etc/containers/registries.d\fR)

.PP
Directory which contains configuration snippets which specify registries which should be consulted when completing image names which do not include a registry or domain portion.

.SH SEE ALSO
.PP
containers.conf(5), containers\-mounts.conf(5), newuidmap(1), newgidmap(1), containers\-registries.conf(5), containers\-storage.conf(5)

.SH HISTORY
.PP
December 2017, Originally compiled by Tom Sweeney tsweeney@redhat.com
\[la]mailto:tsweeney@redhat.com\[ra]