Build a bootc Image from inspectah Output

After running inspectah scan on a host, you have a tarball containing everything needed to rebuild that system as a bootc container image. The recommended workflow uses inspectah build, which handles extraction, subscription cert mounting, and podman build invocation automatically. A manual workflow is also available.

Prerequisites

• A completed inspectah scan output tarball (e.g., hostname-20260312-143000.tar.gz)
• Podman installed on your build machine
• RHEL only: valid subscription certificates (see RHEL Subscription Cert Handling). Not needed for Fedora or CentOS Stream.

Build with inspectah build (recommended)

inspectah build extracts the tarball, validates its contents, detects subscription requirements, and runs podman build with the correct flags:

inspectah build hostname-20260312-143000.tar.gz --tag my-bootc-image:v1

This handles everything: tarball extraction, archive safety validation, RHEL subscription cert mounting (when needed), and podman invocation. The build context is cleaned up automatically on completion.

RHEL subscription handling

inspectah build automatically detects whether subscription certificates are needed:

• Building on a subscribed RHEL host: uses the host’s ambient subscription via RHEL pass-through. No extra flags needed.
• Building on macOS, Fedora, or CI: mounts subscription material from the tarball’s subscription/ directory. This requires scanning with --preserve subscription:

# On the RHEL host: preserve subscription material
sudo inspectah scan --preserve subscription --ack-sensitive

# On your workstation: build with the bundled certs
inspectah build hostname-*.tar.gz --tag my-bootc-image:v1

Preview before building

Use --dry-run to see the exact podman command without executing it:

inspectah build hostname-*.tar.gz --tag my-bootc-image:v1 --dry-run

Keep the build context

By default, the extracted build context is cleaned up after the build. To keep it for inspection:

inspectah build hostname-*.tar.gz --tag my-bootc-image:v1 --keep-context

The extracted directory is written to ~/.cache/inspectah/builds/.

Pass flags to podman

Pass additional arguments to podman build after --:

inspectah build hostname-*.tar.gz --tag my-bootc-image:v1 -- --no-cache --platform linux/arm64

Manual workflow with podman build

If you prefer manual control or need to edit the Containerfile before building, use the manual workflow.

Extract the tarball

tar xzf hostname-20260312-143000.tar.gz
cd hostname-20260312-143000/

The extracted directory contains:

Path	Description
Containerfile	The bootc image definition generated by inspectah
config/	Configuration files to layer into the image
subscription/	RHEL subscription certificates and config (when scanned with --preserve subscription)
audit-report.md	Storage, drift, and configuration audit
README.md	Build/deploy commands and FIXME checklist

Review the Containerfile

Before building, review the generated Containerfile for accuracy:

cat Containerfile

Look for:

• Base image – confirm the FROM line references the correct bootc base image for your distro.
• Package list – check that dnf install lines include the packages you expect. Remove anything unnecessary.
• FIXME comments – inspectah flags items that need manual review. Search for FIXME and resolve each one before building.
• Configuration files – COPY lines should reference files present in the config/ directory.

Build the image

Run podman build from the extracted output directory:

podman build -f Containerfile -t my-bootc-image:latest .

This works directly for Fedora and CentOS Stream images, whose packages are available from public repositories.

For RHEL images, mount subscription certificates into the build so dnf can access Red Hat’s package repositories:

podman build \
  -f Containerfile \
  -t my-bootc-image:latest \
  -v ./subscription/entitlement:/etc/pki/entitlement:ro \
  -v ./subscription/rhsm:/etc/rhsm:ro \
  .

Build output streams to your terminal. A successful build ends with the image ID and tag.

Force rebuild without cache

To rebuild from scratch, ignoring cached layers:

podman build --no-cache -f Containerfile -t my-bootc-image:latest .

RHEL Subscription Cert Handling

Building a RHEL-based bootc image requires valid subscription certificates so that dnf install can access Red Hat’s package repositories during the build.

Where certificates come from

When you scan a RHEL host with --preserve subscription, inspectah collects subscription material and stores it in the tarball under subscription/:

subscription/
├── entitlement/          # Cert/key pairs (e.g., 123.pem, 123-key.pem)
├── rhsm/
│   ├── ca/               # CA certificates (redhat-uep.pem)
│   └── rhsm.conf         # RHSM configuration
└── redhat.repo           # Red Hat repo definition

These are the same certificates found on the host at:

• /etc/pki/entitlement/*.pem – entitlement certificate and key pairs
• /etc/rhsm/ca/ – CA certificates
• /etc/rhsm/rhsm.conf – subscription manager configuration
• /etc/yum.repos.d/redhat.repo – Red Hat repository definition

Without --preserve subscription, subscription material is not collected.

Using inspectah build (recommended)

inspectah build handles subscription cert mounting automatically. It detects whether the build host has an ambient RHEL subscription and either uses pass-through or mounts the tarball’s bundled certs:

inspectah build snapshot.tar.gz --tag my-bootc-image:v1

No manual -v flags needed.

Manual cert mounting

If using the manual podman build workflow, mount the subscription directories as read-only bind mounts:

podman build \
  -f Containerfile \
  -t my-bootc-image:latest \
  -v ./subscription/entitlement:/etc/pki/entitlement:ro \
  -v ./subscription/rhsm:/etc/rhsm:ro \
  .

Building on a RHEL host

If you’re building directly on a subscribed RHEL system, podman can use the host’s live certificates via RHEL pass-through. inspectah build detects this automatically. For manual builds, mount the host’s certificates:

podman build \
  -f Containerfile \
  -t my-bootc-image:latest \
  -v /etc/pki/entitlement:/etc/pki/entitlement:ro \
  -v /etc/rhsm:/etc/rhsm:ro \
  .

Building RHEL images on non-RHEL hosts

You can build RHEL bootc images on macOS (via Podman Desktop), Fedora, or any Linux with podman – as long as you have valid RHEL subscription certs.

The workflow:

1. Run inspectah scan --preserve subscription --ack-sensitive on the RHEL host
2. Copy the tarball to your workstation
3. Build with inspectah build or extract and mount the bundled certs manually

If you extracted the tarball and lost the bundled certs, copy them from the source RHEL host:

scp root@rhel-host:/etc/pki/entitlement/*.pem ./subscription/entitlement/
scp -r root@rhel-host:/etc/rhsm ./subscription/rhsm/

Checking certificate expiry

RHEL subscription certificates expire. inspectah build checks expiry automatically and warns when certificates are expired or expiring within 14 days.

For manual checks:

openssl x509 -enddate -noout -in subscription/entitlement/*.pem

If certificates are expired, re-register the source host with subscription-manager and re-run inspectah scan --preserve subscription to get fresh certs.

Fedora and CentOS Stream

For Fedora and CentOS Stream images, no subscription certificates are needed. Run inspectah build or podman build without subscription flags:

inspectah build snapshot.tar.gz --tag my-bootc-image:v1

Cross-Architecture Builds

To build for a different architecture than your host, use --platform:

podman build \
  --platform linux/arm64 \
  -f Containerfile \
  -t my-bootc-image:arm64 \
  .

Common platform values:

Platform	Use case
linux/amd64	Standard x86_64 servers and cloud instances
linux/arm64	ARM servers, AWS Graviton, Apple Silicon VMs

Cross-architecture builds require QEMU user-mode emulation. On Fedora/RHEL:

sudo dnf install qemu-user-static

On macOS with Podman Desktop, QEMU emulation is included automatically.

Push to a Registry

After building, tag and push the image to your container registry:

# Log in to your registry
podman login registry.example.com

# Tag the image for your registry
podman tag my-bootc-image:latest registry.example.com/my-bootc-image:v1.0

# Push to the registry
podman push registry.example.com/my-bootc-image:v1.0

For RHEL users: authenticate with your Red Hat account to push to Red Hat’s registry:

podman login registry.redhat.io

Troubleshooting

dnf errors during build (“repository not found”)

If building a RHEL-based image, subscription certificates may be missing or expired. Check:

1. Is the Containerfile using a RHEL base image (FROM registry.redhat.io/...)? If so, you need subscription certs mounted.
2. Did you pass the -v flags to mount entitlement/ and rhsm/?
3. Are the certificates still valid? Run openssl x509 -enddate -noout -in entitlement/*.pem.

Fix: Mount valid certificates as shown in RHEL Subscription Cert Handling.

For Fedora and CentOS Stream images, this error typically means the base image’s repository configuration is incorrect or network access is blocked.

“unauthorized” pulling the base image

RHEL base images require registry authentication:

podman login registry.redhat.io

Use your Red Hat account credentials (the same as access.redhat.com).

Fedora and CentOS Stream base images are on public registries and do not require authentication.

Registry push fails (“not logged in”)

Log in to the target registry before pushing:

podman login registry.example.com

Missing packages in the built image

Review the generated Containerfile. inspectah captures the package list from the source system, but some packages may not be available in the target base image’s repositories. Check FIXME comments in the Containerfile for flagged items.

Build context too large or slow

If the extracted output directory is large, podman sends the full context to the build daemon. Use a .containerignore file to exclude unnecessary files:

audit-report.md
README.md
*.tar.gz

Next Steps

After building your bootc image:

1. Test the image – Use bootc-image-builder to create a VM or ISO, or deploy directly to bare metal with bootc switch.
2. Review the audit report – audit-report.md in the tarball documents storage requirements, version drift, and configuration decisions.
3. Check the README – README.md in the tarball includes a FIXME checklist for manual review items.