Red Hat Training
A Red Hat training course is available for RHEL 8
Chapter 4. Creating system images using the image builder command-line interface
Image builder is a tool for creating custom system images. To control Image Builder and create your custom system images, you can use the command-line interface (CLI) or the web console interface. Currently, however, the CLI is the preferred method to use Image Builder.
4.1. Introducing the image builder command-line interface
The image builder command-line interface (CLI) is currently the preferred method to use Image Builder. It offers more functionality than the web console interface. To use the CLI, run the composer-cli
command with the suitable options and subcommands.
The workflow for the command-line interface can be summarized as follows:
- Export (save) the blueprint definition to a plain text file
- Edit this file in a text editor
- Import (push) 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 achieve this procedure, the composer-cli
command offers many subcommands to examine the state of configured blueprints and composes.
To run the composer-cli
commands as non-root, the user must be in the weldr
or root
groups.
To add a user to the
weldr
orroot
groups, run the following commands:$ sudo usermod -a -G weldr user $ newgrp weldr
4.2. Creating an image builder blueprint using the command-line interface
You can create a new 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
- Access to the image builder tool.
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.
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 (import) the blueprint:
# composer-cli blueprints push BLUEPRINT-NAME.toml
Replace BLUEPRINT-NAME with the value you used in previous steps.
NoteTo create images using
composer-cli
as non-root, add your user to theweldr
orroot
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
Check whether the components and versions listed in the blueprint and their dependencies are valid:
# composer-cli blueprints depsolve BLUEPRINT-NAME
If Image Builder is unable to depsolve a package from your custom repositories, follow the steps:
Remove the osbuild-composer cache:
$ sudo rm -rf /var/cache/osbuild-composer/* $ sudo systemctl restart osbuild-composer
4.3. Editing an image builder blueprint with command-line interface
You can edit an existing Image Builder 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
Save (export) 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:
Remove this line, if present:
packages = []
- Increase the version number, for example, fro 0.0.1 to 0.1.0. Remember that 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.
Check if the contents are valid TOML specifications. See the TOML documentation for more information.
NoteTOML documentation is a community product and is not supported by Red Hat. You can report any issues with the tool at https://github.com/toml-lang/toml/issues
- Save the file and close the text editor.
Push (import) the blueprint back into Image Builder:
# composer-cli blueprints push BLUEPRINT-NAME.toml
NoteTo import the blueprint back into Image Builder, supply the file name including the
.toml
extension, while in other commands use only the blueprint name.To verify that the contents uploaded to 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
4.4. Creating a system image with image builder in the command-line interface
You can build a custom image using the Image Builder command-line interface.
Prerequisites
- You have a blueprint prepared for the image. See Creating an image builder blueprint using the command-line interface.
Procedure
Start the compose:
# composer-cli compose start BLUEPRINT-NAME IMAGE-TYPE
Replace BLUEPRINT-NAME with 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).
Wait until the compose process is finished. 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:
Check the compose status:
$ sudo composer-cli compose status
Download the metadata of the image:
$ 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:
$ sudo cat /var/lib/osbuild-composer/jobs/job_UUID.json
You can find the job_UUID.json in the journal.
Additional resources
4.5. Basic Image Builder command-line commands
The 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 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
Replace BLUEPRINT with the name of the blueprint to build, and COMPOSE-TYPE with the output image 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
- composer-cli(1) man page
4.6. Image Builder blueprint format
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.
This part is present only once for the entire blueprint file.
The modules entry lists the package names and versions of packages to be installed into the image.
The group entry describes a group of packages to be installed into the image. Groups use the following package categories:
- Mandatory
- Default
Optional
Blueprints install the mandatory and default packages. There is no mechanism for selecting optional packages.
- Groups to include in the image
[[groups]] name = "group-name"
The group-name is the name of the group, for example, anaconda-tools, widget, wheel or users.
- 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.
Currently there are no differences between packages and modules in the image builder tool. Both are treated as RPM package dependencies.
4.7. 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.
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.ImportantTo generate the
password hash
, you must install python3 on your system.# yum install python3
Replace PASSWORD-HASH with the actual
password hash
. To generate thepassword 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"
NoteThe "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.NoteIf 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.NoteEach 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.NoteCustomizing 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 thesize
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.NoteFrom 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.
NoteYou 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
4.8. Packages installed by image builder
When you create a system image using image builder, by default, the system installs a set of base packages. The base list of packages are the members of the comps core
group. By default, Image Builder uses the core yum
group.
Table 4.1. Default packages to support image type creation
Image type | Default Packages |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
Additional resources
4.9. Enabled services on custom images
When you use image build 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 |
---|---|
| sshd, cloud-init, cloud-init-local, cloud-config, cloud-final |
| sshd, cloud-init, cloud-init-local, cloud-config, cloud-final |
| cloud-init |
| No extra service enables by default |
| No extra service enables by default |
| sshd, chronyd, waagent, cloud-init, cloud-init-local, cloud-config, cloud-final |
| 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