Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Installing RHEL image builder

Before using RHEL image builder, you must install it.

2.1. RHEL image builder system requirements
Copy link

The host that runs RHEL image builder must meet the following requirements:

Expand
Table 2.1. RHEL image builder system requirements
ParameterMinimal Required Value

System type

A dedicated host or virtual machine. Note that RHEL image builder is not supported in containers, including Red Hat Universal Base Images (UBI).

Processor

2 cores

Memory

4 GiB

Disk space

20 GiB of free space in the ` /var/cache/` filesystem

Access privileges

root

Network

Internet connectivity to the Red Hat Content Delivery Network (CDN).

Note

If you do not have internet connectivity, use RHEL image builder in isolated networks. For that, you must override the default repositories to point to your local repositories to not connect to Red Hat Content Delivery Network (CDN). Ensure that you have your content mirrored internally or use Red Hat Satellite.

2.2. Installing RHEL image builder
Copy link

Install RHEL image builder to have access to all the osbuild-composer package functionalities.

Prerequisites

  • You are logged in to the RHEL host on which you want to install RHEL image builder.
  • The host is subscribed to Red Hat Subscription Manager (RHSM) or Red Hat Satellite.
  • You have enabled the BaseOS and AppStream repositories to be able to install the RHEL image builder packages.

Procedure

  1. Install RHEL image builder and other necessary packages: 

    # dnf install osbuild-composer composer-cli cockpit-composer
    Copy to Clipboard Toggle word wrap
    • osbuild-composer - A service to build customized RHEL operating system images.
    • composer-cli- This package enables access to the CLI interface.
    • cockpit-composer - This package enables access to the Web UI interface. The web console is installed as a dependency of the cockpit-composer package.

  2. Enable and start RHEL image builder socket: 

    # systemctl enable --now osbuild-composer.socket
    Copy to Clipboard Toggle word wrap

  3. If you want to use RHEL image builder in the web console, enable and start it. 

    # systemctl enable --now cockpit.socket
    Copy to Clipboard Toggle word wrap

    The osbuild-composer and cockpit services start automatically on first access.

  4. Load the shell configuration script so that the autocomplete feature for the composer-cli command starts working immediately without logging out and in: 

    $ source /etc/bash_completion.d/composer-cli
    Copy to Clipboard Toggle word wrap

Verification

  • Verify that the installation works by running composer-cli: 

    # composer-cli status show
    Copy to Clipboard Toggle word wrap

Troubleshooting

You can use a system journal to track RHEL image builder activities. Additionally, you can find the log messages in the file.

  • To find the journal output for traceback, run the following commands: 

    $ journalctl | grep osbuild
    Copy to Clipboard Toggle word wrap

  • To show the local worker, such as the osbuild-worker@.service, a template service that can start multiple service instances: 

    $ journalctl -u osbuild-worker*
    Copy to Clipboard Toggle word wrap

  • To show the running services: 

    $ journalctl -u osbuild-composer.service
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat