Red Hat Satellite 6 Administration

To install Image Builder, the system must meet the following requirements:

You can use Image Builder in a system without internet connectivity. For this configuration to work, you must override the default Red Hat CDN repositories with the repositories that the Satellite Server provided.

To run Image Builder, install the following packages:

[root@host ~]# dnf install -y osbuild-composer composer-cli \
cockpit-composer bash-completion
...output omitted...
Complete!

Then, enable the osbuild-composer service and the command completion feature for the CLI. You can verify the Image Builder installation by listing the available image formats.

[root@host ~]# systemctl enable --now osbuild-composer.socket
Created symlink /etc/systemd/system/sockets.target.wants/osbuild-composer.socket → /usr/lib/systemd/system/osbuild-composer.socket.
[root@host ~]# source /etc/bash_completion.d/composer-cli
[root@host ~]# composer-cli compose types
...output omitted...

The osbuild-composer service does not use the configured system repositories at the /etc/dnf.repos.d directory to create the image. Instead, the service uses JSON format repositories at the /usr/share/osbuild-composer/repositories/ directory. This default directory contains the definition of the baseos and appstream repositories for the aarch64, ppc64le, s390x, and x86_64 architectures. The JSON format repositories use the same parameter names as the DNF repositories, so you can add or update the parameters as needed.

The default repositories are configured to download the packages from Red Hat CDN. If you are running Image Builder in a system that uses Satellite Server, then you might want to override the repositories with the ones that Satellite provides. You can override the repositories by defining the repositories in the /etc/osbuild-composer/repositories directory.

For example, to use the RHEL 8 x86_64 repositories that are configured in a Satellite environment with the https://satellite.example.com endpoint, you can copy the rhel-8.json file from the default directory to the override directory.

First, create the repository override directory, if it does not exist. Then, copy and edit the rhel-8.json file to contain the repositories in the Satellite endpoint. Ensure that the repository definitions have the required information to communicate with Satellite, such as the SSL key and certificate. You can review the content of the /etc/dnf.repos.d file, or use DNF commands to complete the required information.

[root@host ~]# mkdir -p /etc/osbuild-composer/repositories
[root@host ~]# cp /usr/share/osbuild-composer/repositories/rhel-8.json \
/etc/osbuild-composer/repositories/
[root@host ~]# cat /etc/osbuild-composer/repositories/rhel-8.json
{
    "x86_64": [
        {
            "name": "baseos",
            "baseurl": "https://satellite.example.com/pulp/content/Organization/Environment/Base/content/dist/rhel8/8/x86_64/baseos/os",
            "gpgkey": "
            ...output omitted...
            ",
            "rhsm": true,
            "sslcacert": "/path/to/ca-cert.pem",
            "sslclientcert": "/path/to/client-cert.pem",
            "sslclientkey": "/path/to/client-key.pem",
            "sslverify": 1,
            "check_gpg": true
        },
        {
            "name": "appstream",
            "baseurl": "https://satellite.example.com/pulp/content/Organization/Environment/Base/content/dist/rhel8/8/x86_64/baseos/os",
            "gpgkey": "
            ...output omitted...
            ",
            "rhsm": true,
            "sslcacert": "/path/to/ca-cert.pem",
            "sslclientcert": "/path/to/client-cert.pem",
            "sslclientkey": "/path/to/client-key.pem",
            "check_gpg": true
        }
    ]
}

You can create a blueprint by using the definition of an image in a plain text file in TOML syntax. The following example shows commonly used entries of a blueprint.

name = "BLUEPRINT-EXAMPLE"
description = "LONG FORM DESCRIPTION TEXT"
version = "0.0.1"

[[packages]]
name = "package-name"
version = "package-version"

[[groups]]
name = "group-name"

[customizations]
hostname = "HOSTNAME"

[customizations.kernel]
append = "KERNEL-OPTION"

[[customizations.user]]
name = "USER-NAME"
description = "USER-DESCRIPTION"
password = "PASSWORD-HASH"
key = "PUBLIC-SSH-KEY"
home = "/home/USER-NAME/"
shell = "/usr/bin/bash"
groups = ["users", "wheel"]
uid = NUMBER
gid = NUMBER

[customizations.services]
enabled = ["SERVICE1"]
disabled = ["SERVICE2"]

The version entry defines the version of the blueprint. The blueprint version control uses the Semantic Versioning scheme, so you must follow the MAJOR.MINOR.PATCH format to define your blueprint version.

The name, description, and version entries can be defined only once in a blueprint. Other entries, such as packages and customizations, can be defined as many times as required. You can define the exact version of a package (1.2.3), define the major version but not the minor version (1.*), or define the latest version available (*).

Some customizations might have prerequisites, such as the gid entry in the customizations.user section. This entry requires the existence of the group in the groups section of the blueprint.

Use the composer-cli blueprints push command to import the blueprint definition to the osbuild-composer service. You can list the imported blueprints by using the composer-cli blueprints list command, and view them with the composer-cli blueprints show command.

[root@host ~]# composer-cli blueprints push blueprint-example.toml
[root@host ~]# composer-cli blueprints list
BLUEPRINT-EXAMPLE
[root@host ~]# composer-cli blueprints show webserver
name = "BLUEPRINT-EXAMPLE"
description = "LONG FORM DESCRIPTION TEXT"
version = "0.0.1"

[[packages]]
name = "package-name"
version = "package-version"
...output omitted...

You can delete an existing blueprint by using the composer-cli blueprints delete command. However, you might want to edit the text file and push a new blueprint version. It is recommended to update the blueprint version manually. If you do not update it, then the osbuild-composer service updates it automatically by increasing the patch version.

Use the composer-cli blueprints depsolve command to review the packages that are installed as dependencies, and also to test connectivity to the configured repositories.

[root@host ~]# composer-cli blueprints depsolve BLUEPRINT-EXAMPLE
blueprint: BLUEPRINT-EXAMPLE v0.0.1
    setup-2.13.7-6.el9.noarch
    libeconf-0.4.1-2.el9.x86_64
    ...output omitted...

If the repositories are not correctly configured, then you might see an error that the osbuild-composer service cannot download the repository metadata. When this error occurs, correct the repository file, remove the cache directory, and restart the service.

[root@host ~]# composer-cli blueprints depsolve BLUEPRINT-EXAMPLE
ERROR: BlueprintsError: BLUEPRINT-EXAMPLE: DNF error occured: RepoError: Error occurred when setting up repo: Failed to download metadata for repo '0': Cannot download repomd.xml: Cannot download repodata/repomd.xml: All mirrors were tried
blueprint: BLUEPRINT-EXAMPLE v1.0.0
[root@host ~]# vi blueprint-example.toml
[root@host ~]# rm -rf /var/cache/osbuild-composer/
[root@host ~]# systemctl restart osbuild-composer

Use the composer-cli compose start BLUEPRINT FORMAT-TYPE command to create an image from a blueprint. The composer-cli compose start command starts the compose process in the background. You can view the process's progress by running the composer-cli compose status command. This command shows a list of the compose processes' status in the system.

[root@host ~]# composer-cli compose start BLUEPRINT-EXAMPLE tar
[root@host ~]# composer-cli compose status
64c8e9fb-... RUNNING  Wed Aug 10 18:13:15 2022 BLUEPRINT-EXAMPLE 0.0.1 tar
[root@host ~]# composer-cli compose status
64c8e9fb-... FINISHED Wed Aug 10 18:19:03 2022 BLUEPRINT-EXAMPLE 0.0.1 tar

Use the following commands to monitor the image compose process and to view logs.

[root@host ~]# journalctl | grep osbuild 
[root@host ~]# composer-cli compose info 64c8e9fb-fa1d-4b67-a193-c61c8614742f 
[root@host ~]# composer-cli compose logs 64c8e9fb-fa1d-4b67-a193-c61c8614742f 
[root@host ~]# less /var/lib/osbuild-composer/jobs/64c8e9fb-....json 

After the compose process finishes, download the image.

[root@host ~]# composer-cli compose image 64c8e9fb-fa1d-4b67-a193-c61c8614742f
64c8e9fb-fa1d-4b67-a193-c61c8614742f-root.tar.xz
[root@host ~]# ls -lh
total 388460
-rw-------. 1 root root 380M Aug 10 18:21 64c8e9fb-...-root.tar.xz
-rw-r--r--. 1 root root  277 Aug 10 17:43 webserver-blueprint.toml