Chapter 4. Creating system images using the image builder command-line interface

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

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.

Select a package group

[[packages]]
name = "package_group_name"

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

Set the image hostname

[customizations]
hostname = "baseimage"

User specifications for the resulting system image

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

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

Important

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

# yum install python3

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

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

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

Replace the other placeholders with suitable values.

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

Repeat this block for every user to include.

Group specifications for the resulting system image

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

Repeat this block for every group to include.

Set an existing users SSH key

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

Note

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

Append a kernel boot parameter option to the defaults

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

By default, image builder builds a default kernel into the image. But, you can customize the kernel with the following configuration in blueprint

[customizations.kernel]
name = "KERNEL-rt"

Define a kernel name to use in an image

[customizations.kernel.name]
name = "KERNEL-NAME"

Set the timezone and the Network Time Protocol (NTP) servers for the resulting system image

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

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

Set the locale settings for the resulting system image

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

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

Set the firewall for the resulting system image

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

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

Customize the firewall services

Review the available firewall services.

$ firewall-cmd --get-services

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

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

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

Note

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

Set which services to enable during the boot time

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

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

Note

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

Specify a custom filesystem configuration

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

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

• consistency with existing setups

  To customize the filesystem configuration in your blueprint:

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

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

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

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

    Note

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

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

    Note

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

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

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

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

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

    Note

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

    For example:

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