podman-fips

packaged by Chainguard

Chainguard Container for podman-fips

FIPS-compliant Podman: A tool for managing OCI containers and pods.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/podman-fips:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

Chainguard's podman-fips image is comparable to the upstream Podman stable image (quay.io/podman/stable). Like upstream, the default command is /bin/bash, the working directory is /, the image runs as root, and it has a podman user (UID 1000) for rootless use. It sets the same environment variables and ships the same in-container defaults, so podman run and podman build work without extra flags, as root and as the podman user.

It differs from upstream in the following ways:

• It ships Podman 6.1, while upstream stable currently ships Podman 5.8. Podman 6 removed slirp4netns support, so configurations that select it fail; rootless users can use --network=pasta instead.
• Upstream writes its in-container defaults to /etc/containers/containers.conf, /etc/containers/storage.conf, and the podman user's ~/.config/containers/containers.conf. This image ships the same settings as drop-in files under /usr/share/containers/, because Podman 6 reads only the first main configuration file it finds, while drop-in files always apply on top of it. The rootless settings apply to every non-root user, not only podman.
• /var/tmp is a volume, which it is not upstream. Podman 6 builds mount an overlay over the build context with its upper directory in /var/tmp, and the kernel does not allow that directory on overlayfs, which a container's root filesystem usually is. Docker and containerd create the volume automatically. If your container runtime does not, mount a volume or tmpfs at /var/tmp, or rootless builds fail with not supported as upperdir.
• The image is minimal: it contains Podman, its runtime helpers, bash (also as /bin/sh), git, CRIU, and composefs, but no package manager and no common utilities such as ls or mkdir. Unlike upstream, it has no cpp, so podman build cannot use Containerfile.in files. It has no ssh client either; Podman's own SSH connections use its built-in client.
• Podman signs and verifies images with GnuPG, not Sequoia: --sign-by works, but --sign-by-sq-fingerprint fails with Sequoia-PGP support is not enabled in this build.
• It has no qemu-user-static. As with upstream, which ships it but does not register it inside the container, cross-architecture builds with --platform use the emulation registered on the host.
• Upstream's /etc/containers/mounts.conf passes Red Hat subscription secrets (/run/secrets/etc-pki-entitlement and /run/secrets/rhsm) into nested containers. These apply only on Red Hat hosts, so this image keeps the empty mounts.conf from containers-common. Use the -dev variant or Custom Assembly if you need more tools.

Prerequisites

Running Podman inside a container requires --privileged, or an equivalent combination of capabilities, devices such as /dev/fuse, and relaxed seccomp, SELinux, and AppArmor settings, such as Docker's --security-opt apparmor=unconfined. Refer to How to use Podman inside of a container for the details.

Rootless Podman needs the host to allow unprivileged user namespaces. On hosts where AppArmor restricts them, such as Ubuntu 24.04 by default, running the container directly with Docker as the podman user fails with failed to reexec: Permission denied, as with the upstream image. Running as root is not affected. Refer to unprivileged user namespace restrictions in the Ubuntu 24.04 release notes for the host settings.

Rootless networking with --network pasta also needs a /dev/net/tun device that the podman user can open. Where the host does not allow that, Podman fails with Failed to open() /dev/net/tun: Permission denied. The default in-container settings share the outer container's network, so only an explicit --network pasta is affected.

Getting Started

Check the installed Podman version:

docker run --rm cgr.dev/ORGANIZATION/podman-fips:latest podman --version

Run a container with Podman inside the podman-fips container:

docker run --rm --privileged \
  cgr.dev/ORGANIZATION/podman-fips:latest \
  podman run --rm cgr.dev/chainguard/wolfi-base:latest echo "Hello from Podman"

Hello from Podman

To build an image, create a Containerfile on the host:

mkdir -p podman-demo
cat > podman-demo/Containerfile <<EOF
FROM cgr.dev/chainguard/wolfi-base:latest
RUN echo "Built with Podman" > /message.txt
CMD ["cat", "/message.txt"]
EOF

Build it with Podman, keeping the image store in a named volume so later runs can use the image:

docker run --rm --privileged \
  -v "$PWD/podman-demo:/work" \
  -v podman-storage:/var/lib/containers \
  cgr.dev/ORGANIZATION/podman-fips:latest \
  podman build -t localhost/podman-demo:latest /work

Then run the image you built:

docker run --rm --privileged \
  -v podman-storage:/var/lib/containers \
  cgr.dev/ORGANIZATION/podman-fips:latest \
  podman run --rm localhost/podman-demo:latest

Built with Podman

To run Podman rootless, start the container as the podman user:

docker run --rm --privileged --user podman \
  cgr.dev/ORGANIZATION/podman-fips:latest \
  podman run --rm cgr.dev/chainguard/wolfi-base:latest echo "Hello from rootless Podman"

Hello from rootless Podman

Configuration

The image sets the following environment variables, matching the upstream image:

• container=oci, which tells Podman it runs inside a container
• _CONTAINERS_USERNS_CONFIGURED="", an internal Podman variable set empty to match upstream. Do not set it to a non-empty value: that tells Podman a user namespace is already configured, which breaks rootless Podman
• BUILDAH_ISOLATION=chroot, the default isolation for podman build

Container storage lives in /var/lib/containers for root and in /home/podman/.local/share/containers for the podman user. Mount volumes at these paths to keep images and containers across runs.

As in upstream, root stores images with fuse-overlayfs and also uses the read-only image stores in /var/lib/shared and /usr/lib/containers/storage, while rootless users use the kernel's native overlay and do not need /dev/fuse.

As in the upstream image, nested containers share the outer container's network, IPC, UTS (hostname), user, and cgroup namespaces by default. To change one of these defaults, add a drop-in file to /etc/containers/containers.conf.d/. Drop-in files apply in name order, so a name that sorts after 40-podman-compat.conf wins. For example, nested containers cannot set their own hostname while they share the outer one:

docker run --rm --privileged \
  cgr.dev/ORGANIZATION/podman-fips:latest \
  podman run --rm --hostname nested cgr.dev/chainguard/wolfi-base:latest hostname

Error: invalid config provided: cannot set hostname when running in the host UTS namespace: invalid configuration

Create a drop-in that gives each nested container its own hostname:

cat > 60-private-uts.conf <<EOF
[containers]
utsns = "private"
EOF

Mount it into the container and run the same command:

docker run --rm --privileged \
  -v "$PWD/60-private-uts.conf:/etc/containers/containers.conf.d/60-private-uts.conf:ro" \
  cgr.dev/ORGANIZATION/podman-fips:latest \
  podman run --rm --hostname nested cgr.dev/chainguard/wolfi-base:latest hostname

nested

FIPS Support

The podman-fips image is built with the Microsoft Go toolchain and uses the Chainguard FIPS provider for OpenSSL, configured by openssl-config-fipshardened. Podman's Go standard library cryptography, which includes TLS connections to registries, goes through the OpenSSL FIPS provider. If you configure /etc/containers/policy.json to require OpenPGP signatures, Podman verifies them with gpgme-fips, which runs the FIPS build of GnuPG. The default policy accepts unsigned images, as in upstream.

To see which FIPS module Podman selected, set GODEBUG=cgr_verbose=1:

docker run --rm -e GODEBUG=cgr_verbose=1 \
  cgr.dev/ORGANIZATION/podman-fips:latest \
  podman --version

cgr_fips: openssl
podman version 6.1.4

Checkpoint and restore

podman container checkpoint and podman container restore work when the container has its own cgroups and IPC namespace. Without cgroups, CRIU cannot freeze the container. With the default host IPC namespace, CRIU saves and restores the outer /dev/shm, including Podman's own lock file, and Podman then hangs after the restore, as it does upstream:

docker run --rm --privileged cgr.dev/ORGANIZATION/podman-fips:latest bash -c '
  podman run -d --name sleeper --cgroups=enabled --ipc=private cgr.dev/chainguard/wolfi-base:latest sleep 600 >/dev/null
  podman container checkpoint sleeper >/dev/null
  podman container restore sleeper >/dev/null
  podman inspect --format "{{.State.Status}} restored={{.State.Restored}}" sleeper'

running restored=true

Documentation and Resources

• Podman documentation
• Podman GitHub repository
• containers.conf reference
• Configuration file loading rules
• How to use Podman inside of a container

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.