Chapter 3. Creating system images with 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

Start a compose

# composer-cli compose start BLUEPRINT COMPOSE-TYPE

Replace BLUEPRINT with 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

The blueprint metadata

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

Replace BLUEPRINT-NAME and LONG FORM DESCRIPTION TEXT with a name and description for your blueprint.

Replace VERSION with a version number according to the Semantic Versioning scheme.

This part is present only once for the whole blueprint file.

The entry modules describe the package names and matching version glob to be installed into the image.

The entry group describes a group of packages to be installed into the image. Groups categorize their packages in:

• Mandatory
• Default

• Optional

  Blueprints installs the mandatory packages. There is no mechanism for selecting optional packages.

Groups to include in the image

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

Replace group-name with the name of the group, such as anaconda-tools, widget, wheel or users.

Packages to include in the image

[[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 a version to use. This field supports dnf version specifications:

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

Repeat this block for every package to include.

Procedure

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

Note

The GID is optional and must already exist in the image, be created by a package, or be created by the blueprint [[customizations.group]] entry.

Important

To generate the hash, you must install python3 on your system. The following command will install the python3 package.

# yum install python3

Replace PASSWORD-HASH with the actual password hash. To generate the 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.

Leave out any of the lines as needed, only the user name is required.

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

This option is only applicable for existing users. To create a user and set an ssh key, use the User specifications for the resulting system image customization.

Append a kernel boot parameter option to the defaults

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

Define a kernel name to be used 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 language and keyboard options is mandatory. You can add multiple 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"]

You can use the numeric ports, or theirs names from the /etc/services file to enable lists.

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 names available in the /etc/services file.

You can optionally customize the firewall services for the system image that you plan to create.

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 so that the image works correctly and this setup cannot be overridden.

Note

Each time a build starts, it clones the repository. If you refer to a repository with a large amount of history, it might take a while to clone and use a significant amount of disk space. Also, the clone is temporary and is removed once the RPM package is created.