Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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.

For Network-based deployments, the workflow to compose RHEL for Edge images by 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 by using the CLI, involves the following high-level steps:

  1. Create a blueprint for RHEL for Edge image

  2. Create a RHEL for Edge image. You can create the following images:

    • RHEL for Edge Commit image.
    • RHEL for Edge Container image.
    • RHEL for Edge Installer image.
  3. 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. Creating images for network-based deployments

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 blueprint for the commit image by using image builder CLI

Create a blueprint for RHEL for Edge Commit image by 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 RHEL 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 by using image builder CLI

To create a RHEL for Edge Commit image by using RHEL 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 an image update with a ref commit by using RHEL image builder CLI

If you performed a change in an existing blueprint, for example, you added a new package, and you want to update an existing RHEL for Edge image with this new package, you can use the --parent argument to generate an updated RHEL for Edge Commit (.tar) image. The --parent argument can be either a ref that exists in the repository specified by the URL argument, or you can use the Commit ID, which you can find in the extracted .tar image file.

Both the ref and Commit ID arguments retrieve a parent for the new commit that you are building. RHEL image builder read information from the parent commit user database that affects parts of the new commit that you are building, but preserves UIDs and GIDs for the package-created system users and groups.

Prerequisites

  • You have updated an existing blueprint for RHEL for Edge image.
  • You have an existing RHEL for Edge image (OSTree commit). See Extracting RHEL for Edge image commit.
  • You made the ref that you are going to build available at the OSTree repository specified by the URL.

Procedure

  1. Create the RHEL for Edge commit image: 

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

    For example:

    • To create a new RHEL for Edge commit based on a parent and with a new ref, run the following command: 

      # composer-cli compose start-ostree --ref rhel/8/x86_64/edge --parent rhel/8/x86_64/edge --url http://10.0.2.2:8080/repo rhel_update edge-commit

    • To create a new RHEL for Edge commit based on the same ref, run the following command: 

      # composer-cli compose start-ostree --ref rhel/8/x86_64/edge --url http://10.0.2.2:8080/repo rhel_update edge-commit

      Where:

      • The --ref argument specifies the same path value that you used to build an OSTree repository.
      • The --parent argument specifies the parent commit. It can be ref to be resolved and pulled, for example rhel/8/x86_64/edge, or the Commit ID that you can find in the extracted .tar file.
      • blueprint-name is the RHEL for Edge blueprint name.
      • The --url argument specifies the URL to the OSTree repository of the commit to embed in the image, for example, http://10.0.2.2:8080/repo.

      • 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 the RHEL for Edge Container (.tar) image type.
        • If you omit the parent ref argument, the system falls back to the ref specified by the --ref argument.

        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>

Next steps

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 by using RHEL 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>

    RHEL 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. Creating images for non-network-based deployments

Build a boot ISO image that installs an OSTree-based system by 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.

5.2.1. Creating a RHEL for Edge Container blueprint by 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 RHEL 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.

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 RHEL 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 by using image builder CLI

To create a RHEL for Edge Container image by using RHEL 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/repo/. By default, the repository folder for a RHEL for Edge Container image is "/repo". See Setting up a web server to install RHEL for Edge image.

      To find the correct URL to use, access the running container and check the nginx.conf file. To find which URL to use, access the running container and check the nginx.conf file. Inside the nginx.conf file, find the root directory entry to search for the /repo/ folder information. Note that, if you do not specify a repository URL when creating a RHEL for Edge Container image (.tar) by using RHEL image builder, the default /repo/ entry is created in the nginx.conf file.

    • 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 by using the command-line interface for non-network-based deployments

To create a RHEL for Edge Installer image that embeds the OSTree commit, use the RHEL image builder command-line interface, and 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 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 the 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/repo. 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 by using RHEL 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>

    RHEL 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 customizations to your blueprint, such as:

  • Adding an additional RPM package
  • Enabling a service
  • Customizing a kernel command line parameter.

Between others. You can use several image customizations within blueprints. By using the customizations, you can add packages and groups to the image that are not available in the default packages. To use these options, configure the customizations in the blueprint and import (push) it to RHEL image builder.

Additional resources

5.3.1. Selecting a distribution

You can use the distro field to specify the distribution to use when composing your images or solving dependencies in the blueprint. If the distro field is left blank, the blueprint automatically uses the host’s operating system distribution. If you do not specify a distribution, the blueprint uses the host distribution. When you upgrade the host operating system, blueprints without a specified distribution build images by using the upgraded operating system version.

You can build images for older major versions on a newer system. For example, you can use a RHEL 10 host to create RHEL 9 and RHEL 8 images. However, you cannot build images for newer major versions on an older system.

Important

You cannot build an operating system image that differs from the RHEL image builder host. For example, you cannot use a RHEL system to build Fedora or CentOS images.

  • Customize the blueprint with the RHEL distribution to always build the specified RHEL image: 

    name = "blueprint_name"
description = "blueprint_version"
version = "0.1"
distro = "different_minor_version"

    For example: 

    name = "tmux"
description = "tmux image with openssh"
version = "1.2.16"
distro = "rhel-9.5"

Replace "different_minor_version" to build a different minor version, for example, if you want to build a RHEL 8.10 image, use distro = "rhel-810". On RHEL 8.10 image, you can build minor versions such as RHEL 8.9 and earlier releases.

5.3.2. Selecting a package group

Customize the blueprint with package groups. The groups list describes the groups of packages that you want to install into the image. The package groups are defined in the repository metadata. Each group has a descriptive name that is used primarily for display in user interfaces, and an ID that is commonly used in Kickstart files. In this case, you must use the ID to list a group. Groups have three different ways of categorizing their packages: mandatory, default, and optional. Only mandatory and default packages are installed in the blueprints. It is not possible to select optional packages.

The name attribute is a required string and must match exactly the package group id in the repositories.

Note

Currently, there are no differences between packages and modules in osbuild-composer. Both are treated as an RPM package dependency.

  • Customize your blueprint with a package: 

    [[groups]]
name = "group_name"

    Replace group_name with the name of the group. For example, anaconda-tools: 

    [[groups]]
name = "anaconda-tools"

5.3.3. Setting the image hostname

The customizations.hostname is an optional string that you can use to configure the final image hostname. This customization is optional, and if you do not set it, the blueprint uses the default hostname.

  • Customize the blueprint to configure the hostname: 

    [customizations]
hostname = "baseimage"

5.3.4. Specifying additional users

Add a user to the image, and optionally, set their SSH key. All fields for this section are optional except for the name.

Procedure

  • Customize the blueprint to add a user to the 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
    [[customizations.user]]
name = "admin"
description = "Administrator account"
password = "$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L..."
key = "PUBLIC SSH KEY"
home = "/srv/widget/"
shell = "/usr/bin/bash"
groups = ["widget", "users", "wheel"]
uid = 1200
gid = 1200
expiredate = 12345

    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.

    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 the other placeholders with suitable values.

    Enter the name value and omit any lines you do not need.

    Repeat this block for every user to include.

5.3.5. Specifying additional groups

Specify a group for the resulting system image. Both the name and the gid attributes are mandatory.

  • Customize the blueprint with a group: 

    [[customizations.group]]
name = "GROUP-NAME"
gid = NUMBER

    Repeat this block for every group to include. For example: 

    [[customizations.group]]
name = "widget"
gid = 1130

5.3.6. Setting SSH key for existing users

You can use customizations.sshkey to set an SSH key for the existing users in the final image. Both user and key attributes are mandatory.

  • Customize the blueprint by setting an SSH key for existing users: 

    [[customizations.sshkey]]
user = "root"
key = "PUBLIC-SSH-KEY"

    For example: 

    [[customizations.sshkey]]
user = "root"
key = "SSH key for root"
    Note

    You can only configure the customizations.sshkey customization for existing users. To create a user and set an SSH key, see the Specifying additional users customization.

5.3.7. Appending a kernel argument

You can append arguments to the boot loader kernel command line. By default, RHEL image builder builds a default kernel into the image. However, you can customize the kernel by configuring it in the blueprint.

  • Append a kernel boot parameter option to the defaults: 

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

    For example: 

    [customizations.kernel]
name = "kernel-debug"
append = "nosmt=force"

5.3.8. Setting time zone and NTP

You can customize your blueprint to configure the time zone and the Network Time Protocol (NTP). Both timezone and ntpservers attributes are optional strings. If you do not customize the time zone, the system uses Universal Time, Coordinated (UTC). If you do not set NTP servers, the system uses the default distribution.

  • Customize the blueprint with the timezone and the ntpservers you want: 

    [customizations.timezone]
timezone = "TIMEZONE"
ntpservers = "NTP_SERVER"

    For example: 

    [customizations.timezone]
timezone = "US/Eastern"
ntpservers = ["0.north-america.pool.ntp.org", "1.north-america.pool.ntp.org"]
    Note

    Some image types, such as Google Cloud, already have NTP servers set up. You cannot override it because the image requires the NTP servers to boot in the selected environment. However, you can customize the time zone in the blueprint.

5.3.9. Customizing the locale settings

You can customize the locale settings for your resulting system image. Both language and the keyboard attributes are mandatory. You can add many other languages. The first language you add is the primary language and the other languages are secondary.

Procedure

  • Set the locale settings: 

    [customizations.locale]
languages = ["LANGUAGE"]
keyboard = "KEYBOARD"

    For example: 

    [customizations.locale]
languages = ["en_US.UTF-8"]
keyboard = "us"

  • To list the values supported by the languages, run the following command: 

    $ localectl list-locales

  • To list the values supported by the keyboard, run the following command: 

    $ localectl list-keymaps

5.3.10. Customizing firewall

Set the firewall for the resulting system image. By default, the firewall blocks incoming connections, except for services that enable their ports explicitly, such as sshd.

If you do not want to use the [customizations.firewall] or the [customizations.firewall.services], either remove the attributes, or set them to an empty list []. If you only want to use the default firewall setup, you can omit the customization from the blueprint.

Note

The Google and OpenStack templates explicitly disable the firewall for their environment. You cannot override this behavior by setting the blueprint.

Procedure

  • Customize the blueprint with the following settings to open other ports and services: 

    [customizations.firewall]
ports = ["PORTS"]

    Where ports is an optional list of strings that contain ports or a range of ports and protocols to open. You can configure the ports by using the following format: port:protocol format. You can configure the port ranges by using the portA-portB:protocol format. For example: 

    [customizations.firewall]
ports = ["22:tcp", "80:tcp", "imap:tcp", "53:tcp", "53:udp", "30000-32767:tcp", "30000-32767:udp"]

    You can use numeric ports, or their names from the /etc/services to enable or disable port lists.

  • Specify which firewall services to enable or disable in the customizations.firewall.service section: 

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

  • You can check the available firewall services: 

    $ firewall-cmd --get-services

    For example: 

    [customizations.firewall.services]
enabled = ["ftp", "ntp", "dhcp"]
disabled = ["telnet"]
    Note

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

5.3.11. Enabling or disabling 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 you cannot override this setup. The [customizations.services] settings in the blueprint do not replace these services, but add the services to the list of services already present in the image templates.

  • Customize which services to enable during the boot time: 

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

    For example: 

    [customizations.services]
enabled = ["sshd", "cockpit.socket", "httpd"]
disabled = ["postfix", "telnetd"]

5.3.12. Specifying a custom file system configuration

You can specify a custom file system 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
Note

The OSTree systems do not support the file system customizations, because OSTree images have their own mount rule, such as read-only. The following image types are not supported:

  • image-installer
  • edge-installer
  • edge-simplified-installer

Additionally, the following image types do not support file system customizations, because these image types do not create partitioned operating system images:

  • edge-commit
  • edge-container
  • tar
  • container

However, the following image types have support for file system customization:

  • simplified-installer
  • edge-raw-image
  • edge-ami
  • edge-vsphere

With some additional exceptions for OSTree systems, you can choose arbitrary directory names at the /root level of the file system, for example: ` /local`,` /mypartition`, /$PARTITION. In logical volumes, these changes are made on top of the LVM partitioning system. The following directories are supported: /var,` /var/log`, and /var/lib/containers on a separate logical volume. The following are exceptions at root level:

  • "/home": {Deny: true},
  • "/mnt": {Deny: true},
  • "/opt": {Deny: true},
  • "/ostree": {Deny: true},
  • "/root": {Deny: true},
  • "/srv": {Deny: true},
  • "/var/home": {Deny: true},
  • "/var/mnt": {Deny: true},
  • "/var/opt": {Deny: true},
  • "/var/roothome": {Deny: true},
  • "/var/srv": {Deny: true},
  • "/var/usrlocal": {Deny: true},

For release distributions before RHEL 8.10 and 9.5, the blueprint supports the following mountpoints and their sub-directories:

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

From the RHEL 9.5 and 8.10 release distributions onward, you can specify arbitrary custom mountpoints, except for specific paths that are reserved for the operating system.

You cannot specify arbitrary custom mountpoints on the following mountpoints and their sub-directories:

  • /bin
  • /boot/efi
  • /dev
  • /etc
  • /lib
  • /lib64
  • /lost+found
  • /proc
  • /run
  • /sbin
  • /sys
  • /sysroot
  • /var/lock
  • /var/run

You can customize the file system in the blueprint for the /usr custom mountpoint, but its subdirectory is not allowed.

Note

Customizing mount points is only supported from RHEL 8.5 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. Beginning with RHEL 8.6, for the osbuild-composer-46.1-1.el8 RPM and later version, the physical partitions are no longer available and file system customizations create logical volumes.

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 file system configuration in your blueprint and therefore create images with the required disk layout. The default file system layout remains unchanged - if you use plain images without file system customization, and cloud-init resizes the root partition.

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

You can use the custom file blueprint customization to create new files or to replace existing files. The parent directory of the file you specify must exist, otherwise, the image build fails. Ensure that the parent directory exists by specifying it in the [[customizations.directories]] customization.

Warning

If you combine the files customizations with other blueprint customizations, it might affect the functioning of the other customizations, or it might override the current files customizations.

5.3.12.1. Specifying customized files in the blueprint

With the [[customizations.files]] blueprint customization you can:

  • Create new text files.
  • Modifying existing files. WARNING: this can override the existing content.
  • Set user and group ownership for the file you are creating.
  • Set the mode permission in the octal format.

You cannot create or replace the following files:

  • /etc/fstab
  • /etc/shadow
  • /etc/passwd
  • /etc/group

You can create customized files and directories in your image, by using the [[customizations.files]] and the [[customizations.directories]] blueprint customizations. You can use these customizations only in the /etc directory.

Note

These blueprint customizations are supported by all image types, except the image types that deploy OSTree commits, such as edge-raw-image, edge-installer, and edge-simplified-installer.

Warning

If you use the customizations.directories with a directory path which already exists in the image with mode, user or group already set, the image build fails to prevent changing the ownership or permissions of the existing directory.

5.3.12.2. Specifying customized directories in the blueprint

With the [[customizations.directories]] blueprint customization you can:

  • Create new directories.
  • Set user and group ownership for the directory you are creating.
  • Set the directory mode permission in the octal format.
  • Ensure that parent directories are created as needed.

With the [[customizations.files]] blueprint customization you can:

  • Create new text files.
  • Modifying existing files. WARNING: this can override the existing content.
  • Set user and group ownership for the file you are creating.
  • Set the mode permission in the octal format.
Note

You cannot create or replace the following files:

  • /etc/fstab
  • /etc/shadow
  • /etc/passwd
  • /etc/group

The following customizations are available:

  • Customize the file system configuration in your blueprint: 

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

    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"
minsize = 1073741824

  • Define the mount point size by using units. For example: 

    [[customizations.filesystem]]
mountpoint = "/opt"
minsize = "20 GiB"
    [[customizations.filesystem]]
mountpoint = "/boot"
minsize = "1 GiB"

  • Define the minimum partition by setting minsize. For example: 

    [[customizations.filesystem]]
mountpoint = "/var"
minsize = 2147483648

  • Create customized directories under the /etc directory for your image by using [[customizations.directories]]: 

    [[customizations.directories]]
path = "/etc/directory_name"
mode = "octal_access_permission"
user = "user_string_or_integer"
group = "group_string_or_integer"
ensure_parents = boolean

    The blueprint entries are described as following:

    • path - Mandatory - enter the path to the directory that you want to create. It must be an absolute path under the /etc directory.
    • mode - Optional - set the access permission on the directory, in the octal format. If you do not specify a permission, it defaults to 0755. The leading zero is optional.
    • user - Optional - set a user as the owner of the directory. If you do not specify a user, it defaults to root. You can specify the user as a string or as an integer.
    • group - Optional - set a group as the owner of the directory. If you do not specify a group, it defaults to root. You can specify the group as a string or as an integer.
    • ensure_parents - Optional - Specify whether you want to create parent directories as needed. If you do not specify a value, it defaults to false.

  • Create customized file under the /etc directory for your image by using [[customizations.directories]]: 

    [[customizations.files]]
path = "/etc/directory_name"
mode = "octal_access_permission"
user = "user_string_or_integer"
group = "group_string_or_integer"
data = "Hello world!"

    The blueprint entries are described as following:

    • path - Mandatory - enter the path to the file that you want to create. It must be an absolute path under the /etc directory.
    • mode Optional - set the access permission on the file, in the octal format. If you do not specify a permission, it defaults to 0644. The leading zero is optional.
    • user - Optional - set a user as the owner of the file. If you do not specify a user, it defaults to root. You can specify the user as a string or as an integer.
    • group - Optional - set a group as the owner of the file. If you do not specify a group, it defaults to root. You can specify the group as a string or as an integer.
    • data - Optional - Specify the content of a plain text file. If you do not specify a content, it creates an empty file.

5.4. Packages installed by RHEL image builder

When you create a system image by using RHEL image builder, the system installs a set of base package groups.

Note

When you add additional components to your blueprint, ensure that the packages in the components you added do not conflict with any other package components. Otherwise, the system fails to solve dependencies and creating your customized image fails. You can check if there is no conflict between the packages by running the command: 

# composer-cli blueprints depsolve BLUEPRINT-NAME

By default, RHEL image builder uses the Core group as the base list of packages.

Table 5.1. Default packages to support image type creation
Image typeDefault Packages

ami

checkpolicy, chrony, cloud-init, cloud-utils-growpart, @Core, dhcp-client, gdisk, insights-client, kernel, langpacks-en, net-tools, NetworkManager, redhat-release, redhat-release-eula, rng-tools, rsync, selinux-policy-targeted, tar, yum-utils

openstack

@core, langpacks-en

qcow2

@core, chrony, dnf, kernel, yum, nfs-utils, dnf-utils, cloud-init, python3-jsonschema, qemu-guest-agent, cloud-utils-growpart, dracut-norescue, tar, tcpdump, rsync, dnf-plugin-spacewalk, rhn-client-tools, rhnlib, rhnsd, rhn-setup, NetworkManager, dhcp-client, cockpit-ws, cockpit-system, subscription-manager-cockpit, redhat-release, redhat-release-eula, rng-tools, insights-client

tar

policycoreutils, selinux-policy-targeted

vhd

@core, langpacks-en

vmdk

@core, chrony, cloud-init, firewalld, langpacks-en, open-vm-tools, selinux-policy-targeted

edge-commit

redhat-release, glibc, glibc-minimal-langpack, nss-altfiles, dracut-config-generic, dracut-network, basesystem, bash, platform-python, shadow-utils, chrony, setup, shadow-utils, sudo, systemd, coreutils, util-linux, curl, vim-minimal, rpm, rpm-ostree, polkit, lvm2, cryptsetup, pinentry, e2fsprogs, dosfstools, keyutils, gnupg2, attr, xz, gzip, firewalld, iptables, NetworkManager, NetworkManager-wifi, NetworkManager-wwan, wpa_supplicant, traceroute, hostname, iproute, iputils, openssh-clients, procps-ng, rootfiles, openssh-server, passwd, policycoreutils, policycoreutils-python-utils, selinux-policy-targeted, setools-console, less, tar, rsync, usbguard, bash-completion, tmux, ima-evm-utils, audit, podman, containernetworking-plugins, container-selinux, skopeo, criu, slirp4netns, fuse-overlayfs, clevis, clevis-dracut, clevis-luks, greenboot, greenboot-default-health-checks, fdo-client, fdo-owner-cli, sos,

edge-container

dnf, dosfstools, e2fsprogs, glibc, lorax-templates-generic, lorax-templates-rhel, lvm2, policycoreutils, python36, python3-iniparse, qemu-img, selinux-policy-targeted, systemd, tar, xfsprogs, xz

edge-installer

aajohan-comfortaa-fonts, abattis-cantarell-fonts, alsa-firmware, alsa-tools-firmware, anaconda, anaconda-install-env-deps, anaconda-widgets, audit, bind-utils, bitmap-fangsongti-fonts, bzip2, cryptsetup, dbus-x11, dejavu-sans-fonts, dejavu-sans-mono-fonts, device-mapper-persistent-data, dnf, dump, ethtool, fcoe-utils, ftp, gdb-gdbserver, gdisk, gfs2-utils, glibc-all-langpacks, google-noto-sans-cjk-ttc-fonts, gsettings-desktop-schemas, hdparm, hexedit, initscripts, ipmitool, iwl3945-firmware, iwl4965-firmware, iwl6000g2a-firmware, iwl6000g2b-firmware, jomolhari-fonts, kacst-farsi-fonts, kacst-qurn-fonts, kbd, kbd-misc, kdump-anaconda-addon, khmeros-base-fonts, libblockdev-lvm-dbus, libertas-sd8686-firmware, libertas-sd8787-firmware, libertas-usb8388-firmware, libertas-usb8388-olpc-firmware, libibverbs, libreport-plugin-bugzilla, libreport-plugin-reportuploader, libreport-rhel-anaconda-bugzilla, librsvg2, linux-firmware, lklug-fonts, lldpad, lohit-assamese-fonts, lohit-bengali-fonts, lohit-devanagari-fonts, lohit-gujarati-fonts, lohit-gurmukhi-fonts, lohit-kannada-fonts, lohit-odia-fonts, lohit-tamil-fonts, lohit-telugu-fonts, lsof, madan-fonts, metacity, mtr, mt-st, net-tools, nmap-ncat, nm-connection-editor, nss-tools, openssh-server, oscap-anaconda-addon, pciutils, perl-interpreter, pigz, python3-pyatspi, rdma-core, redhat-release-eula, rpm-ostree, rsync, rsyslog, sg3_utils, sil-abyssinica-fonts, sil-padauk-fonts, sil-scheherazade-fonts, smartmontools, smc-meera-fonts, spice-vdagent, strace, system-storage-manager, thai-scalable-waree-fonts, tigervnc-server-minimal, tigervnc-server-module, udisks2, udisks2-iscsi, usbutils, vim-minimal, volume_key, wget, xfsdump, xorg-x11-drivers,xorg-x11-fonts-misc,xorg-x11-server-utils,xorg-x11-server-Xorg, xorg-x11-xauth

edge-simplified-installer

attr, basesystem, binutils, bsdtar, clevis-dracut, clevis-luks, cloud-utils-growpart, coreos-installer, coreos-installer-dracut, coreutils, device-mapper-multipath, dnsmasq, dosfstools, dracut-live, e2fsprogs, fcoe-utils, fdo-init, gzip, ima-evm-utils, iproute, iptables, iputils, iscsi-initiator-utils, keyutils, lldpad, lvm2, passwd, policycoreutils, policycoreutils-python-utils, procps-ng, rootfiles, setools-console, sudo, traceroute, util-linux

image-installer

aajohan-comfortaa-fonts, abattis-cantarell-fonts, alsa-firmware, alsa-tools-firmware, anaconda, anaconda-dracut, anaconda-install-env-deps, anaconda-widgets, audit, bind-utils, bitmap-fangsongti-fonts, bzip2, cryptsetup, curl, dbus-x11, dejavu-sans-fonts, dejavu-sans-mono-fonts, device-mapper-persistent-data, dmidecode, dnf, dracut-config-generic, dracut-network, efibootmgr, ethtool, fcoe-utils, ftp, gdb-gdbserver, gdisk, glibc-all-langpacks, gnome-kiosk, google-noto-sans-cjk-ttc-fonts, grub2-tools, grub2-tools-extra, grub2-tools-minimal, grubby, gsettings-desktop-schemas, hdparm, hexedit, hostname, initscripts, ipmitool, iwl1000-firmware, iwl100-firmware, iwl105-firmware, iwl135-firmware, iwl2000-firmware, iwl2030-firmware, iwl3160-firmware, iwl5000-firmware, iwl5150-firmware, iwl6000g2a-firmware, iwl6000g2b-firmware, iwl6050-firmware, iwl7260-firmware, jomolhari-fonts, kacst-farsi-fonts, kacst-qurn-fonts, kbd, kbd-misc, kdump-anaconda-addon, kernel, khmeros-base-fonts, less, libblockdev-lvm-dbus, libibverbs, libreport-plugin-bugzilla, libreport-plugin-reportuploader, librsvg2, linux-firmware, lklug-fonts, lldpad, lohit-assamese-fonts, lohit-bengali-fonts, lohit-devanagari-fonts, lohit-gujarati-fonts, lohit-gurmukhi-fonts, lohit-kannada-fonts, lohit-odia-fonts, lohit-tamil-fonts, lohit-telugu-fonts, lsof, madan-fonts, mtr, mt-st, net-tools, nfs-utils, nmap-ncat, nm-connection-editor, nss-tools, openssh-clients, openssh-server, oscap-anaconda-addon, ostree, pciutils, perl-interpreter, pigz, plymouth, prefixdevname, python3-pyatspi, rdma-core, redhat-release-eula, rng-tools, rpcbind, rpm-ostree, rsync, rsyslog, selinux-policy-targeted, sg3_utils, sil-abyssinica-fonts, sil-padauk-fonts, sil-scheherazade-fonts, smartmontools, smc-meera-fonts, spice-vdagent, strace, systemd, tar, thai-scalable-waree-fonts, tigervnc-server-minimal, tigervnc-server-module, udisks2,udisks2-iscsi,usbutils,vim-minimal, volume_key, wget, xfsdump, xfsprogs, xorg-x11-drivers, xorg-x11-fonts-misc, xorg-x11-server-utils, xorg-x11-server-Xorg, xorg-x11-xauth, xz,

edge-raw-image

dnf, dosfstools, e2fsprogs, glibc, lorax-templates-generic, lorax-templates-rhel, lvm2, policycoreutils, python36, python3-iniparse, qemu-img, selinux-policy-targeted, systemd, tar, xfsprogs, xz

gce

@core, langpacks-en, acpid, dhcp-client, dnf-automatic, net-tools, python3, rng-tools, tar, vim

Additional resources

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.

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.

© 2024 Red Hat, Inc.