Chapter 5. Composing a RHEL for Edge image using image builder command-line

You can use image builder to create a customized RHEL for Edge image (OSTree commit).

To access image builder and to create your custom RHEL for Edge image, you can either use the RHEL web console interface or the command-line interface.

For Network-based deployments, the workflow to compose RHEL for Edge images using the CLI, involves the following high-level steps:

  1. Create a blueprint for RHEL for Edge image
  2. Create a RHEL for Edge Commit image
  3. Download the RHEL for Edge Commit image

For Non-Network-based deployments, the workflow to compose RHEL for Edge images using the CLI, involves the following high-level steps:

  1. Create a blueprint for RHEL for Edge image
  2. Create a blueprint for the RHEL for Edge Installer image
  3. Create a RHEL for Edge Container image
  4. Create a RHEL for Edge Installer image
  5. Download the RHEL for Edge image

To perform the steps, use the composer-cli package.

Note

To run the composer-cli commands as non-root, you must be part of the weldr group or you must have administrator access to the system.

5.1. Network-based deployments workflow

This provides steps on how to build OSTree commits. These OSTree commits contain a full operating system, but are not directly bootable. To boot them, you need to deploy them using a Kickstart file.

5.1.1. Creating a RHEL for Edge Commit image blueprint using image builder command-line interface

Create a blueprint for RHEL for Edge Commit image using the CLI.

Prerequisite

  • You do not have an existing blueprint. To verify that, list the existing blueprints: 

    $ sudo composer-cli blueprints list

Procedure

  1. Create a plain text file in the TOML format, with the following content: 

    name = "blueprint-name"
description = "blueprint-text-description"
version = "0.0.1"
modules = [ ]
groups = [ ]

    Where,

    • blueprint-name is the name and blueprint-text-description is the description for your blueprint.
    • 0.0.1 is the version number according to the Semantic Versioning scheme.

    • Modules describe the package name and matching version glob to be installed into the image, for example, the package name = "tmux" and the matching version glob is version = "2.9a".

      Notice that currently there are no differences between packages and modules.

    • Groups are packages groups to be installed into the image, for example the group package anaconda-tools.

      At this time, if you do not know the modules and groups, leave them empty.

  2. Include the required packages and customize the other details in the blueprint to suit your requirements.

    For every package that you want to include in the blueprint, add the following lines to the file: 

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

    Where,

    • package-name is the name of the package, such as httpd, gdb-doc, or coreutils.

    • package-version is the version number of the package that you want to use.

      The package-version supports the following dnf version specifications:

    • For a specific version, use the exact version number such as 8.0.
    • For the latest available version, use the asterisk *.
    • For the latest minor version, use formats such as 8.*.

  3. Push (import) the blueprint to the image builder server: 

    # composer-cli blueprints push blueprint-name.toml

  4. List the existing blueprints to check whether the created blueprint is successfully pushed and exists. 

    # composer-cli blueprints show BLUEPRINT-NAME

  5. Check whether the components and versions listed in the blueprint and their dependencies are valid: 

    # composer-cli blueprints depsolve blueprint-name

Additional resources

5.1.2. Creating a RHEL for Edge Commit image using image builder command-line interface

To create a RHEL for Edge Commit image using image builder command-line interface, ensure that you have met the following prerequisites and follow the procedure.

Prerequisites

  • You have created a blueprint for RHEL for Edge Commit image.

Procedure

  1. Create the RHEL for Edge Commit image. 

    # composer-cli compose start blueprint-name image-type

    Where,

    • blueprint-name is the RHEL for Edge blueprint name.

    • image-type is edge-commit for network-based deployment.

      A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

  2. Check the image compose status. 

    # composer-cli compose status

    The output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes up to 20 minutes to complete.

    To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    To delete an existing image, run: 

    # composer-cli compose delete <UUID>

    After the image is ready, you can download it and use the image on your network deployments.

Additional resources

5.1.3. Creating a RHEL for Edge image update with a parent commit using image builder command-line interface

If you performed a change in an existing blueprint, for example, you added a new package, and want to update an existing RHEL for Edge image with this new package, you can use a parent commit ID to generate an updated RHEL for Edge Commit (.tar) image.

To create a RHEL for Edge image with a parent commit using image builder command line interface, ensure that you have met the following prerequisites and follow the procedure.

Prerequisites

Procedure

  1. Create the RHEL for Edge image. 

    # composer-cli compose start-ostree --ref rhel/8/x86_64/edge --parent parent-OSTree-REF --url _URL blueprint-name image-type

    Where,

    • --ref is the same path value that you used to build an OSTree repository.
    • --parent is the parent OSTree Ref, for example rhel/9/x86_64/edge.
    • blueprint-name is the RHEL for Edge blueprint name.
    • -url is the URL to the OSTree repository of the commit to embed in the image, for example, http://10.0.2.2:8080/repository/.

    • image-type is edge-commit for network-based deployment.

      Note

      The --parent argument can only be used for the RHEL for Edge Commit (.tar) image type. Using the --url and --parent arguments together results in errors with other image types.

      A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

  2. Check the image compose status. 

    # composer-cli compose status

    The output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes a few minutes to complete.

    (Optional) To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    (Optional) To delete an existing image, run: 

    # composer-cli compose delete <UUID>

After the image creation is complete, to upgrade an existing OSTree deployment, you need:

Additional resources

5.1.4. Downloading a RHEL for Edge image using the image builder command-line interface

To download a RHEL for Edge image using image builder command line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

  • You have created a RHEL for Edge image.

Procedure

  1. Review the RHEL for Edge image status. 

    # composer-cli compose status

    The output must display the following: 

    $ <UUID> FINISHED date blueprint-name blueprint-version image-type

  2. Download the image. 

    # composer-cli compose image <UUID>

    Image builder downloads the image as a tar file to the current directory.

    The UUID number and the image size is displayed alongside. 

    $ <UUID>-commit.tar: size MB

The image contains a commit and a json file with information metadata about the repository content.

Additional resources

5.2. Non-network-based deployments workflow

To build a boot ISO image that installs an OSTree-based system using the "RHEL for Edge Container" and the "RHEL for Edge Installer" images and that can be later deployed to a device in disconnected environments, follow the steps.

5.2.1. Creating a RHEL for Edge Container blueprint using image builder CLI

To create a blueprint for RHEL for Edge Container image, perform the following steps:

Procedure

  1. Create a plain text file in the TOML format, with the following content: 

    name = "blueprint-name"
description = "blueprint-text-description"
version = "0.0.1"
modules = [ ]
groups = [ ]

    Where,

    • blueprint-name is the name and blueprint-text-description is the description for your blueprint.
    • 0.0.1 is the version number according to the Semantic Versioning scheme.

    • Modules describe the package name and matching version glob to be installed into the image, for example, the package name = "tmux" and the matching version glob is version = "2.9a".

      Notice that currently there are no differences between packages and modules.

    • Groups are packages groups to be installed into the image, for example the group package anaconda-tools.

      At this time, if you do not know the modules and groups, leave them empty.

  2. Include the required packages and customize the other details in the blueprint to suit your requirements.

    For every package that you want to include in the blueprint, add the following lines to the file: 

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

    Where,

    • package-name is the name of the package, such as httpd, gdb-doc, or coreutils.

    • package-version is the version number of the package that you want to use.

      The package-version supports the following dnf version specifications:

    • For a specific version, use the exact version number such as 8.0.
    • For the latest available version, use the asterisk *.
    • For the latest minor version, use formats such as 8.*.

  3. Push (import) the blueprint to the image builder server: 

    # composer-cli blueprints push blueprint-name.toml

  4. List the existing blueprints to check whether the created blueprint is successfully pushed and exists. 

    # composer-cli blueprints show BLUEPRINT-NAME

  5. Check whether the components and versions listed in the blueprint and their dependencies are valid: 

    # composer-cli blueprints depsolve blueprint-name

Additional resources

5.2.2. Creating a RHEL for Edge Installer blueprint using image builder CLI

You can create a blueprint to build a RHEL for Edge Installer (.iso) image, and specify user accounts to automatically create one or more users on the system at installation time. See Creating an administrative user account for a RHEL for Edge image blueprint. It creates a user on the system at installation time.

Warning

When you create a user in the blueprint with the customizations.user customization, the blueprint creates the user under the /usr/lib/passwd directory and the password, under the /usr/etc/shadow directory. Note that you cannot change the password in further versions of the image in a running system using OSTree updates. The users you create with blueprints must be used only to gain access to the created system. After you access the system, you need to create users, for example, using the useradd command.

To create a blueprint for RHEL for Edge Installer image, perform the following steps:

Procedure

  1. Create a plain text file in the TOML format, with the following content: 

    name = "blueprint-installer"
description = "blueprint-for-installer-image"
version = "0.0.1"

[[customizations.user]]
name = "user"
description = "account"
password = "user-password"
key = "user-ssh-key "
home = "path"
groups = ["user-groups"]

    Where,

    • blueprint-name is the name and blueprint-text-description is the description for your blueprint.
    • 0.0.1 is the version number according to the Semantic Versioning scheme.

  2. Push (import) the blueprint to the image builder server: 

    # composer-cli blueprints push blueprint-name.toml

  3. List the existing blueprints to check whether the created blueprint is successfully pushed and exists. 

    # composer-cli blueprints show blueprint-name

  4. Check whether the components and versions listed in the blueprint and their dependencies are valid: 

    # composer-cli blueprints depsolve blueprint-name

Additional resources

5.2.3. Creating a RHEL for Edge Container image using image builder CLI

To create a RHEL for Edge Container image using image builder command-line interface, ensure that you have met the following prerequisites and follow the procedure.

Prerequisites

  • You have created a blueprint for RHEL for Edge Container image.

Procedure

  1. Create the RHEL for Edge Container image. 

    # composer-cli compose start-ostree --ref rhel/8/x86_64/edge --url URL-OSTree-repository blueprint-name image-type

    Where,

    • --ref is the same value that customer used to build ostree repository
    • --url is the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repository/. See Setting up a web server to install RHEL for Edge image.
    • blueprint-name is the RHEL for Edge blueprint name.

    • image-type is edge-container for non-network-based deployment.

      A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

  2. Check the image compose status. 

    # composer-cli compose status

    The output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes up to 20 minutes to complete.

    To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    To delete an existing image, run: 

    # composer-cli compose delete <UUID>

    After the image is ready, it can be used for non-network deployments. See Creating a RHEL for Edge Container image for non-network-based deployments.

Additional resources

5.2.4. Creating a RHEL for Edge Installer image using command-line interface for non-network-based deployments

To create a RHEL for Edge Installer image that embeds the OSTree commit, using image builder command-line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

  • You have created a blueprint for RHEL for Edge Installer image.
  • You have created a RHEL for Edge Edge Container image and deployed it using a web server.

Procedure

  1. Begin to create the RHEL for Edge Installer image. 

    # composer-cli compose start-ostree --ref rhel/8/x86_64/edge --url URL-OSTree-repository blueprint-name image-type

    Where,

    • ref is the same value that customer used to build ostree repository
    • URL-OSTree-repository is the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repository/. See Creating a RHEL for Edge Container image for non-network-based deployments.
    • blueprint-name is the RHEL for Edge Installer blueprint name.

    • image-type is edge-installer.

      A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

  2. Check the image compose status. 

    # composer-cli compose status

    The command output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes a few minutes to complete.

    To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    To delete an existing image, run: 

    # composer-cli compose delete <UUID>

    After the image is ready, you can use it for non-network deployments. See Installing the RHEL for Edge image for non-network-based deployments.

5.2.5. Downloading a RHEL for Edge Installer image using the image builder CLI

To download a RHEL for Edge Installer image using image builder command line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

  • You have created a RHEL for Edge Installer image.

Procedure

  1. Review the RHEL for Edge image status. 

    # composer-cli compose status

    The output must display the following: 

    $ <UUID> FINISHED date blueprint-name blueprint-version image-type

  2. Download the image. 

    # composer-cli compose image <UUID>

    Image builder downloads the image as an .iso file to the current directory.

    The UUID number and the image size is displayed alongside. 

    $ <UUID>-boot.iso: size MB

The resulting image is a bootable ISO image.

Additional resources

5.3. Supported image customizations

You can customize your image by adding to your blueprint an additional RPM package, by enabling a service, or by customizing a kernel command line parameter. You can use several image customizations within blueprints. To make use of these options, you must configure the customizations in the blueprint and import (push) it to image builder.

Note

These customizations are not supported when using image builder in the web console.

Select a package group
[[packages]]
name = "package_group_name"

Replace "package_group_name" with the name of the group. For example, "@server with gui".

Set the image hostname
[customizations]
hostname = "baseimage"
User specifications for the resulting system image
[[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

The GID is optional and must already exist in the image. Optionally, a package creates it, or the blueprint creates the GID by using the [[customizations.group]] entry.

Important

To generate the password hash, you must install python3 on your system. 

# yum install python3

Replace PASSWORD-HASH with the actual password hash. To generate the password hash, use a command such as: 

$ python3 -c 'import crypt,getpass;pw=getpass.getpass();print(crypt.crypt(pw) if (pw==getpass.getpass("Confirm: ")) else exit())'

Replace PUBLIC-SSH-KEY with the actual public key.

Replace the other placeholders with suitable values.

You must enter the name. You can omit any of the lines that you do not need.

Repeat this block for every user to include.

Group specifications for the resulting system image
[[customizations.group]]
name = "GROUP-NAME"
gid = NUMBER

Repeat this block for every group to include.

Set an existing users SSH key
[[customizations.sshkey]]
user = "root"
key = "PUBLIC-SSH-KEY"
Note

The "Set an existing users SSH key" customization is only applicable for existing users. To create a user and set an SSH key, see the User specifications for the resulting system image customization.

Append a kernel boot parameter option to the defaults
[customizations.kernel]
append = "KERNEL-OPTION"
By default, image builder builds a default kernel into the image. But, you can customize the kernel with the following configuration in blueprint
[customizations.kernel]
name = "KERNEL-rt"
Define a kernel name to use in an image
[customizations.kernel.name]
name = "KERNEL-NAME"
Set the timezone and the Network Time Protocol (NTP) servers for the resulting system image
[customizations.timezone]
timezone = "TIMEZONE"
ntpservers = "NTP_SERVER"

If you do not set a timezone, the system uses Universal Time, Coordinated (UTC) as default. Setting NTP servers is optional.

Set the locale settings for the resulting system image
[customizations.locale]
languages = ["LANGUAGE"]
keyboard = "KEYBOARD"

Setting both the language and the keyboard options is mandatory. You can add many other languages. The first language you add will be the primary language and the other languages will be secondary.

Set the firewall for the resulting system image
[customizations.firewall]
port = ["PORTS"]

To enable lists, you can use numeric ports, or their names from the /etc/services file.

Customize the firewall services

Review the available firewall services. 

$ firewall-cmd --get-services

In the blueprint, under section customizations.firewall.service, specify the firewall services that you want to customize. 

[customizations.firewall.services]
enabled = ["SERVICES"]
disabled = ["SERVICES"]

The services listed in firewall.services are different from the service-names available in the /etc/services file.

Note

If you do not want to customize the firewall services, omit the [customizations.firewall] and [customizations.firewall.services] sections from the blueprint.

Set which services to enable during the boot time
[customizations.services]
enabled = ["SERVICES"]
disabled = ["SERVICES"]

You can control which services to enable during the boot time. Some image types already have services enabled or disabled to ensure that the image works correctly and this setup cannot be overridden. The [customizations.services] customization in the blueprint do not replace these services, but add them to the list of services already present in the image templates.

Note

Each time a build starts, it clones the repository of the host system. If you refer to a repository with a large amount of history, it might take some time to clone and it uses a significant amount of disk space. Also, the clone is temporary and the build removes it after it creates the RPM package.

Specify a custom filesystem configuration

You can specify a custom filesystem configuration in your blueprints and therefore create images with a specific disk layout, instead of the default layout configuration. By using the non-default layout configuration in your blueprints, you can benefit from:

  • security benchmark compliance
  • protection against out-of-disk errors
  • improved performance

  • consistency with existing setups

    To customize the filesystem configuration in your blueprint: 

    [[customizations.filesystem]]
mountpoint = "MOUNTPOINT"
size = MINIMUM-PARTITION-SIZE

    The blueprint supports the following mountpoints and their sub-directories:

    • / - the root mount point
    • /var
    • /home
    • /opt
    • /srv
    • /usr
    • /app
    • /data

    • /boot - Supported from RHEL 8.7 and RHEL 9.1 onward.

      Note

      Customizing mount points is only supported from RHEL 8.5 and RHEL 9.0 distributions onward, by using the CLI. In earlier distributions, you can only specify the root partition as a mount point and specify the size argument as an alias for the image size.

      If you have more than one partition in the customized image, you can create images with a customized file system partition on LVM and resize those partitions at runtime. To do this, you can specify a customized filesystem configuration in your blueprint and therefore create images with the desired disk layout. The default filesystem layout remains unchanged - if you use plain images without file system customization, and cloud-init resizes the root partition.

      Note

      From 8.6 onward, for the osbuild-composer-46.1-1.el8 RPM and later version, the physical partitions are no longer available and filesystem customizations create logical volumes.

      The blueprint automatically converts the file system customization to a LVM partition.

      The MINIMUM-PARTITION-SIZE value has no default size format. The blueprint customization supports the following values and units: kB to TB and KiB to TiB. For example, you can define the mount point size in bytes: 

      [[customizations.filesystem]]
mountpoint = "/var"
size = 1073741824

      You can also define the mount point size by using units.

      Note

      You can only define the mount point size by using units for the package version provided for RHEL 8.6 and RHEL 9.0 distributions onward.

      For example: 

      [[customizations.filesystem]]
mountpoint = "/opt"
size = "20 GiB"

or

[[customizations.filesystem]]
mountpoint = "/boot"
size = "1 GiB"

Additional resources

5.4. Additional resources