Jump to content
From ArchWiki

Related articles

- Cgroups
- Docker
- Podman
- Linux Containers

Buildah is a tool that facilitates building Open Container Initiative (OCI) container images. The Buildah package provides a command line tool that can be used to:

- create a working container, either from scratch or using an image as a starting point
- create an image, either from a working container or via the instructions in a Dockerfile
- images can be built in either the OCI image format or the traditional upstream docker image format
- 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

The most widely known alternative for building containers is docker. Do note that Buildah does not run containers, for that you may want to consider podman.

## Installation

Install the buildah and podman packages or, for the development version, the buildah-gitAUR package.

If you want to run as non-root user, also install fuse-overlayfs for better performance and storage space efficiency.

Note: official buildah installation guide points at podman section where advise is given to install fuse-overlayfs before installing podman

## Configuration

### Enable support to build unprivileged containers

Users wishing to use Buildah to build unprivileged containers need to complete additional setup steps before running podman for the first time.

Note: If you are building system dedicated for running unprivileged containers, follow the steps bellow before adding any user. This way you will not have to edit `/etc/subuid` and `/etc/subgid`: useradd will do that for you, you only need to run `touch /etc/subgid` and `touch /etc/subuid` as root.

Finally, create both `/etc/subuid` and `/etc/subgid` to contain the mapping to the containerized UID/GID pairs for each user who shall be able to run the containers.[1] The example below is for the root user (and systemd system unit) and an example user `buildah`:

    /etc/subuid

    buildah:100000:65536

    /etc/subgid

    buildah:100000:65536

If you did run podman before applying the changes above, you will get errors when trying to pull images as an unprivileged user. Run `podman system migrate` to fix it.

If everything went well then after logging out and logging back in `buildah images` should not result in error

Note: If you see errors accessing `/run/user/0` then you have probably used su to become the user you are using for test — you should log in as such user since su without the `--login` flag will not set `XDG_RUNTIME_DIR` and other environmental variables to correct values.

## Troubleshooting

### WARN[0000] "/" is not a shared mount, this could cause issues or missing mounts with rootless containers

Buildah/Podman running as rootless expects the bind mount to be shared, check if it is set to private:

    $ findmnt -o PROPAGATION /

    PROPAGATION
    private

In this case see mount(8) § Shared subtree operations and set temporarily the mount as shared with:

    # mount --make-shared /

To set it permanently, edit /etc/fstab and add the shared option to the desired mount and reboot. It will result in a entry like:

    /etc/fstab

    # <device>                                <dir> <type> <options> <dump> <fsck>
    UUID=0a3407de-014b-458b-b5c1-848e92a327a3 /     ext4   defaults,shared   0      1

## See also

- Buildah Blog Post Series
- Containers Organization GitHub projects
- Podman daemonless container engine

Categories:

- Virtualization
- Sandboxing