Chapter 4. Creating system images by using RHEL image builder CLI

PDF

RHEL image builder is a tool for creating custom system images. To control RHEL image builder and create your custom system images, you can use the command-line interface (CLI) or the web console interface.

4.1. Introducing the RHEL image builder command-line interface

You can use the RHEL image builder command-line interface (CLI) to create blueprints, by running the composer-cli command with the suitable options and subcommands.

The workflow for the command-line interface can be summarized as follows:

Create a blueprint or export (save) an existing blueprint definition to a plain text file
Edit this file in a text editor
Import the blueprint text file back into image builder
Run a compose to build an image from the blueprint
Export the image file to download it

Apart from the basic subcommands to create a blueprint, the composer-cli command offers many subcommands to examine the state of configured blueprints and composes.

4.2. Using RHEL image builder as a non-root user

To run the composer-cli commands as non-root, the user must be in the weldr group.

Prerequisites

You have created a user

Procedure

To add a user to the weldr or root groups, run the following commands:
```
$ sudo usermod -a -G weldr user
$ newgrp weldr
```

4.3. Creating a blueprint by using the command-line interface

You can create a new RHEL image builder blueprint using the command-line interface (CLI). The blueprint describes the final image and its customizations, such as packages, and kernel customizations.

Prerequisite

You are logged in as the root user or a user who is a member of the welder group

Procedure

Create a plain text file with the following contents:
```
name = "BLUEPRINT-NAME"
description = "LONG FORM DESCRIPTION TEXT"
version = "0.0.1"
modules = []
groups = []
```
Replace BLUEPRINT-NAME and LONG FORM DESCRIPTION TEXT with a name and description for your blueprint.
Replace 0.0.1 with a version number according to the Semantic Versioning scheme.
For every package that you want to be included in the blueprint, add the following lines to the file:
```
[[packages]]
name = "package-name"
version = "package-version"
```
Replace package-name with the name of the package, such as httpd, gdb-doc, or coreutils.
Optionally, replace package-version with the version to use. This field supports dnf version specifications:
- For a specific version, use the exact version number such as 8.7.0.
- For the latest available version, use the asterisk *.
- For the latest minor version, use formats such as 8.*.
Customize your blueprints to suit your needs. For example, disable Simultaneous Multi Threading (SMT), add the following lines to the blueprint file:
```
[customizations.kernel]
append = "nosmt=force"
```
For additional customizations available, see Supported Image Customizations.
Save the file, for example, as BLUEPRINT-NAME.toml and close the text editor.
Push the blueprint:
```
# composer-cli blueprints push BLUEPRINT-NAME.toml
```
Replace BLUEPRINT-NAME with the value you used in previous steps.
Note
To create images using composer-cli as non-root, add your user to the weldr or root groups.
```
# usermod -a -G weldr user
$ newgrp weldr
```

Verification

List the existing blueprints to verify that the blueprint has been pushed and exists:
```
# composer-cli blueprints list
```
Display the blueprint configuration you have just added:
```
# composer-cli blueprints show BLUEPRINT-NAME
```
Check whether the components and versions listed in the blueprint and their dependencies are valid:
```
# composer-cli blueprints depsolve BLUEPRINT-NAME
```
If RHEL image builder is unable to solve the dependencies of a package from your custom repositories, remove the osbuild-composer cache:
```
$ sudo rm -rf /var/cache/osbuild-composer/*
$ sudo systemctl restart osbuild-composer
```

Additional resources

osbuild-composer is unable to depsolve a package from my custom repository (Red Hat Knowledgebase)
Composing a customized RHEL system image with proxy server (Red Hat Knowledgebase)

4.4. Editing a blueprint with command-line interface

You can edit an existing blueprint in the command-line (CLI) interface to, for example, add a new package, or define a new group, and to create your customized images. For that, follow the steps:

Prerequisites

You have created a blueprint

Procedure

List the existing blueprints:
```
# composer-cli blueprints list
```

Save the blueprint to a local text file:

# composer-cli blueprints save BLUEPRINT-NAME

Edit the BLUEPRINT-NAME.toml file with a text editor and make your changes.
Before finishing the edits, verify that the file is a valid blueprint:
1. Remove the following line from the blueprint, if present:
```
packages = []
```
2. Increase the version number, for example, from 0.0.1 to 0.1.0. Remember that RHEL image builder blueprint versions must use the Semantic Versioning scheme. Note also that if you do not change the version, the patch version component increases automatically.
Save the file and close the text editor.
Push the blueprint back into RHEL image builder:
```
# composer-cli blueprints push BLUEPRINT-NAME.toml
```
Note
To import the blueprint back into RHEL image builder, supply the file name including the .toml extension, while in other commands use only the blueprint name.

Verification

To verify that the contents uploaded to RHEL image builder match your edits, list the contents of blueprint:
```
# composer-cli blueprints show BLUEPRINT-NAME
```
Check whether the components and versions listed in the blueprint and their dependencies are valid:
```
# composer-cli blueprints depsolve BLUEPRINT-NAME
```

Additional resources

Supported Image Customizations

4.5. Creating a system image with RHEL image builder in the command-line interface

You can build a customized RHEL image by using the RHEL image builder command-line interface. For that, you must specify a blueprint and an image type. Optionally, you can also specify a distribution. If you do not specify a distribution, it will use the same distribution and version as the host system. The architecture is also the same as the one on the host.

Prerequisites

You have a blueprint prepared for the image. See Creating a RHEL image builder blueprint using the command-line interface.

Procedure

Optional: List the image formats you can create:
```
# composer-cli compose types
```
Start the compose:
```
# composer-cli compose start BLUEPRINT-NAME IMAGE-TYPE
```
Replace BLUEPRINT-NAME with the name of the blueprint, and IMAGE-TYPE with the type of the image. For the available values, see the output of the composer-cli compose types command.
The compose process starts in the background and shows the composer Universally Unique Identifier (UUID).
The image creation can take up to ten minutes to complete.
To check the status of the compose:
```
# composer-cli compose status
```
A finished compose shows the FINISHED status value. To identify your compose in the list, use its UUID.
After the compose process is finished, download the resulting image file:
```
# composer-cli compose image UUID
```
Replace UUID with the UUID value shown in the previous steps.

Verification

After you create your image, you can check the image creation progress using the following commands:

Download the metadata of the image to get a .tar file of the metadata for the compose:
```
$ sudo composer-cli compose metadata UUID
```
Download the logs of the image:
```
$ sudo composer-cli compose logs UUID
```
The command creates a .tar file that contains the logs for the image creation. If the logs are empty, you can check the journal.
Check the journal:
```
$ journalctl | grep osbuild
```
Check the manifest of the image:
```
$ sudo cat /var/lib/osbuild-composer/jobs/job_UUID.json
```
You can find the job_UUID.json in the journal.

Additional resources

Tracing RHEL image builder (Red Hat Knowledgebase)

4.6. Basic RHEL image builder command-line commands

The RHEL image builder command-line interface offers the following subcommands.

Blueprint manipulation

List all available blueprints

# composer-cli blueprints list

Show a blueprint contents in the TOML format

# composer-cli blueprints show <BLUEPRINT-NAME>

Save (export) blueprint contents in the TOML format into a file BLUEPRINT-NAME.toml

# composer-cli blueprints save <BLUEPRINT-NAME>

Remove a blueprint

# composer-cli blueprints delete <BLUEPRINT-NAME>

Push (import) a blueprint file in the TOML format into RHEL image builder

# composer-cli blueprints push <BLUEPRINT-NAME>

Composing images from blueprints

List the available image types

# composer-cli compose types

Start a compose

# composer-cli compose start <BLUEPRINT> <COMPOSE-TYPE>

List all composes

# composer-cli compose list

List all composes and their status

# composer-cli compose status

Cancel a running compose

# composer-cli compose cancel <COMPOSE-UUID>

Delete a finished compose

# composer-cli compose delete <COMPOSE-UUID>

Show detailed information about a compose

# composer-cli compose info <COMPOSE-UUID>

Download image file of a compose

# composer-cli compose image <COMPOSE-UUID>

See more subcommands and options

# composer-cli help

Additional resources

The composer-cli(1) man page on your system

4.7. RHEL image builder blueprint format

RHEL image builder blueprints are presented to the user as plain text in the TOML format.

The elements of a typical blueprint file include the following:

The blueprint metadata

name = "<BLUEPRINT-NAME>"
description = "<LONG FORM DESCRIPTION TEXT>"
version = "<VERSION>"

The BLUEPRINT-NAME and LONG FORM DESCRIPTION TEXT field are a name and description for your blueprint.

The VERSION is a version number according to the Semantic Versioning scheme, and is present only once for the entire blueprint file.

Groups to include in the image

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

The group entry describes a group of packages to be installed into the image. Groups use the following package categories:

Mandatory
Default
Optional
The group-name is the name of the group, for example, anaconda-tools, widget, wheel or users. Blueprints install the mandatory and default packages. There is no mechanism for selecting optional packages.

Packages to include in the image

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

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

package-version is a version to use. This field supports dnf version specifications:

For a specific version, use the exact version number such as 8.7.0.
For latest available version, use the asterisk *.
For a latest minor version, use a format such as 8.*.
Repeat this block for every package to include.

Note

There are no differences between packages and modules in the RHEL image builder tool. Both are treated as RPM package dependencies.

4.8. 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

Blueprint import fails after adding filesystem customization "size" (Red Hat Knowledgebase)

4.8.1. Selecting a distribution

You can use the distro field to select the distribution to use when composing your images, or solving dependencies in the blueprint. If distro is left blank it will use the host distribution. If you do not specify a distribution, the blueprint uses the host distribution. In case you upgrade the host operating system, the blueprints with no distribution set build images using the new operating system version. You cannot build an operating system image that differs from the RHEL image builder host.

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-8.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.

4.8.2. Selecting a package group

Customize the blueprint with packages 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"
```

4.8.3. Embedding a container

You can customize your blueprint to embed the latest RHEL container. The containers list contains objects with a source, and optionally, the tls-verify attribute.

The container list entries describe the container images to be embedded into the image.

source - Mandatory field. It is a reference to the container image at a registry. This example uses the registry.access.redhat.com registry. You can specify a tag version. The default tag version is latest.
name - The name of the container in the local registry.
tls-verify - Boolean field. The tls-verify boolean field controls the transport layer security. The default value is true.

The embedded containers do not start automatically. To start it, create systemd unit files or quadlets with the files customization.

To embed a container from registry.access.redhat.com/ubi9/ubi:latest and a container from your host, add the following customization to your blueprint:

[[containers]]
source = "registry.access.redhat.com/ubi9/ubi:latest"
name =  "local-name"
tls-verify = true

[[containers]]
source = "localhost/test:latest"
local-storage = true

You can access protected container resources by using a containers-auth.json file. See Container registry credentials.

4.8.4. 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"
```

4.8.5. 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.

4.8.6. 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

4.8.7. 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.

4.8.8. 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"

4.8.9. Building RHEL images by using the real-time kernel

To build a RHEL image by using the real-time kernel (kernel-rt), you need to override a repository so that you can then build an image in which kernel-rt is correctly selected as the default kernel. Use the .json from the /usr/share/osbuild-composer/repositories/ directory. Then, you can deploy the image that you built to a system and use the real time kernel features.

Note

The real-time kernel runs on AMD64 and Intel 64 server platforms that are certified to run Red Hat Enterprise Linux.

Prerequisites

Your system is registered and RHEL is attached to a RHEL for Real Time subscription. See Installing RHEL for Real Time using dnf.

Procedure

Create the following directory:

# mkdir /etc/osbuild-composer/repositories/

Copy the content from the /usr/share/osbuild-composer/repositories/rhel-8.version.json file to the new directory:
```
# cp /usr/share/osbuild-composer/repositories/rhel-8.version.json /etc/osbuild-composer/repositories
```

Edit the /etc/osbuild-composer/repositories/rhel-8.version.json file to include the RT kernel repo:

# grep -C 6 kernel-rt /etc/osbuild-composer/repositories/rhel-8.version.json
      "baseurl": "https://cdn.redhat.com/content/dist/rhel8/8.version/x86_64/appstream/os",
      "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nm………..=\n=UZd/\n-----END PGP PUBLIC KEY BLOCK-----\n",
      "rhsm": true,
      "check_gpg": true
    },
    {
      "name": "kernel-rt",
      "baseurl": "https://cdn.redhat.com/content/dist/rhel8/8.version/x86_64/rt/os",
      "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINBEr………fg==\n=UZd/\n-----END PGP PUBLIC KEY BLOCK-----\n",
      "rhsm": true,
      "check_gpg": true
    },

Restart the service:
```
# systemctl restart osbuild-composer
```
Confirm that the kernel-rt has been included into the .json file:
```
# composer-cli sources list
# composer-cli sources info kernel-rt
```
You will see the URL that you have previously configured.

Create a blueprint. In the blueprint, add the "[customizations.kernel]" customization. The following is an example that contains the "[customizations.kernel]" in the blueprint:

name = "rt-kernel-image"
description = ""
version = "2.0.0"
modules = []
groups = []
distro = "rhel-8_version_"
[[customizations.user]]
name = "admin"
password = "admin"
groups = ["users", "wheel"]
[customizations.kernel]
name = "kernel-rt"
append = ""

Push the blueprint to the server:

# composer-cli blueprints push rt-kernel-image.toml

Build your image from the blueprint you created. The following example builds a (.qcow2) image:
```
# composer-cli compose start rt-kernel-image qcow2
```
Deploy the image that you built to the system where you want to use the real time kernel features.

Verification

After booting a VM from the image, verify that the image was built with the kernel-rt correctly selected as the default kernel.
```
$ cat /proc/cmdline
BOOT_IMAGE=(hd0,got3)/vmlinuz-5.14.0-362.24.1..el8_version_.x86_64+rt...
```

4.8.10. 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.

4.8.11. 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
```

4.8.12. 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.

4.8.13. 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"]

4.8.14. Specifying a partition mode

Use the partitioning_mode variable to select how to partition the disk image that you are building. You can customize your image with the following supported modes:

auto-lvm: It uses the raw partition mode, unless there are one or more filesystem customizations. In that case, it uses the LVM partition mode.
lvm: It always uses the LVM partition mode, even when there are no extra mountpoints.
raw: It uses raw partitions even when there are one or more mountpoints.
You can customize your blueprint with the partitioning_mode variable by using the following customization:
```
[customizations]
partitioning_mode = "lvm"
```

4.8.15. Specifying 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

Note

The OSTree systems do not support the filesystem 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 filesystem customizations, because these image types do not create partitioned operating system images:

edge-commit
edge-container
tar
container

For release distributions before RHEL 8.10 and 9.4, 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.4 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 filesystem 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 filesystem 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 filesystem configuration in your blueprint and therefore create images with the required disk layout. The default filesystem 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.

4.8.15.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.

4.8.15.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 filesystem 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.

4.9. Packages installed by RHEL image builder

When you create a system image 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 4.1. Default packages to support image type creation
Image type	Default 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`	attr, audit, basesystem, bash, bash-completion, chrony, clevis, clevis-dracut, clevis-luks, container-selinux, coreutils,criu, cryptsetup, curl, dnsmasq, dosfstools, dracut-config-generic, dracut-network, e2fsprogs, firewalld, fuse-overlayfs, fwupd, glibc, glibc-minimal-langpack, gnupg2, greenboot, gzip, hostname, ima-evm-utils, iproute, iptables, iputils, keyutils, less, lvm2, NetworkManager, NetworkManager-wifi, NetworkManager-wwan, nss-altfiles, openssh-clients, openssh-server, passwd, pinentry, platform-python, podman, policycoreutils, policycoreutils-python-utils, polkit, procps-ng, redhat-release, rootfiles, rpm, rpm-ostree, rsync, selinux-policy-targeted, setools-console, setup, shadow-utils, shadow-utils, skopeo, slirp4netns, sudo, systemd, tar, tmux, traceroute, usbguard, util-linux, vim-minimal, wpa_supplicant, xz
`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`	`anaconda-dracut, curl, dracut-config-generic, dracut-network, hostname, iwl100-firmware, iwl1000-firmware, iwl105-firmware, iwl135-firmware, iwl2000-firmware, iwl2030-firmware, iwl3160-firmware, iwl5000-firmware, iwl5150-firmware, iwl6000-firmware, iwl6050-firmware, iwl7260-firmware, kernel, less, nfs-utils, openssh-clients, ostree, plymouth, prefixdevname, rng-tools, rpcbind, selinux-policy-targeted, systemd, tar, xfsprogs, 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

RHEL image builder description

4.10. Enabled services on custom images

When you use image builder to configure a custom image, the default services that the image uses are determined by the following:

The RHEL release on which you use the osbuild-composer utility
The image type

For example, the ami image type enables the sshd, chronyd, and cloud-init services by default. If these services are not enabled, the custom image does not boot.

Table 4.2. Enabled services to support image type creation
Image type	Default enabled Services
`ami`	sshd, cloud-init, cloud-init-local, cloud-config, cloud-final
`openstack`	sshd, cloud-init, cloud-init-local, cloud-config, cloud-final
`qcow2`	cloud-init
`rhel-edge-commit`	No extra service enables by default
`tar`	No extra service enables by default
`vhd`	sshd, chronyd, waagent, cloud-init, cloud-init-local, cloud-config, cloud-final
`vmdk`	sshd, chronyd, vmtoolsd, cloud-init

Note: You can customize which services to enable during the system boot. However, the customization does not override services enabled by default for the mentioned image types.

Additional resources

Supported Image Customizations

Chapter 4. Creating system images by using RHEL image builder CLI

4.1. Introducing the RHEL image builder command-line interface

4.2. Using RHEL image builder as a non-root user

4.3. Creating a blueprint by using the command-line interface

4.4. Editing a blueprint with command-line interface

4.5. Creating a system image with RHEL image builder in the command-line interface

4.6. Basic RHEL image builder command-line commands

4.7. RHEL image builder blueprint format

4.8. Supported image customizations

4.8.1. Selecting a distribution

4.8.2. Selecting a package group

4.8.3. Embedding a container

4.8.4. Setting the image hostname

4.8.5. Specifying additional users

4.8.6. Specifying additional groups

4.8.7. Setting SSH key for existing users

4.8.8. Appending a kernel argument

4.8.9. Building RHEL images by using the real-time kernel

4.8.10. Setting time zone and NTP

4.8.11. Customizing the locale settings

4.8.12. Customizing firewall

4.8.13. Enabling or disabling services

4.8.14. Specifying a partition mode

4.8.15. Specifying a custom filesystem configuration

4.8.15.1. Specifying customized files in the blueprint

4.8.15.2. Specifying customized directories in the blueprint

4.9. Packages installed by RHEL image builder

4.10. Enabled services on custom images

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links