1. Export (save) the blueprint definition to a plain text file
2. Edit this file in a text editor
3. Import (push) the blueprint text file back into Image Builder
4. Run a compose to build an image from the blueprint
5. Export the image file to download it

Procedure

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

2. 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 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.*.

3. Blueprints can be customized in a number of ways. For this example, Simultaneous Multi Threading (SMT) can be disabled by performing the steps below. For additional customizations available, please see Supported Image Customizations.

   [customizations.kernel]
   append = "nosmt=force"

4. Save the file as BLUEPRINT-NAME.toml and close the text editor.

5. Push (import) the blueprint:

   # composer-cli blueprints push BLUEPRINT-NAME.toml

   Replace BLUEPRINT-NAME with the value you used in previous steps.

6. To verify that the blueprint has been pushed and exists, list the existing blueprints:

   # composer-cli blueprints list

7. Check whether the components and versions listed in the blueprint and their dependencies are valid:

   # composer-cli blueprints depsolve BLUEPRINT-NAME

Procedure

1. Save (export) the blueprint to a local text file:

   # composer-cli blueprints save BLUEPRINT-NAME

2. Edit the BLUEPRINT-NAME.toml file with a text editor of your choice and make your changes.

3. Before finishing with the edits, make sure the file is a valid blueprint:

   1. Remove this line, if present:

      packages = []

   2. Increase the version number. Remember that Image Builder blueprint versions must use the Semantic Versioning scheme. Note also that if you do not change the version, the patch component of version is increased automatically.

   3. Check if the contents are valid TOML specifications. See the TOML documentation for more information.

      Note

      TOML 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

4. Save the file and close the editor.

5. Push (import) the blueprint back into Image Builder:

   # composer-cli blueprints push BLUEPRINT-NAME.toml

   Note that you must supply the file name including the .toml extension, while in other commands you use only the name of the blueprint.

6. To verify that the contents uploaded to Image Builder match your edits, list the contents of blueprint:

   # composer-cli blueprints show BLUEPRINT-NAME

7. Check whether the components and versions listed in the blueprint and their dependencies are valid:

   # composer-cli blueprints depsolve BLUEPRINT-NAME

Procedure

1. 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 image. For possible values, see output of the composer-cli compose types command.

   The compose process starts in the background and the UUID of the compose is shown.

2. Wait until the compose is finished. Please, notice that this may take several minutes.

   To check the status of the compose:

   # composer-cli compose status

   A finished compose shows a status value FINISHED. Identify the compose in the list by its UUID.

3. Once the compose is finished, download the resulting image file:

   # composer-cli compose image UUID

   Replace UUID with the UUID value shown in the previous steps.

   You can also download the logs using the composer-cli compose logs UUID command, or the metadata using the composer-cli compose metadata UUID command.

Procedure

1. Set the image hostname:

   [customizations]
   hostname = "baseimage"

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

3. Group specifications for the resulting system image:

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

   Repeat this block for every group to include.

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

5. Append a kernel boot parameter option to the defaults:

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

6. Define a kernel name to be used in an image:

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

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

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

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

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

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

12. Add files from a git repository to your blueprint:

    [[repos.git]]
    rpmname = "RPM-NAME"
    rpmversion = "RPM-VERSION"
    rpmrelease = "RPM-RELEASE"
    summary = "RPM-SUMMARY"
    repo = "REPO-URL"
    ref = "GIT-REF"
    destination = "SERVICES"

    You can use entries to add files from a git repository to the created image.

    For example, to create an RPM package named server-config-1.0-1.noarch.rpm, add the following information to your blueprint:

    Replace _RPM-NAME with the name of the RPM package to create. This is also the prefix name in the resulting tar archive.

    Replace RPM-VERSION with the version of the RPM package, for example, "1.0.0".

    Replace RPM-RELEASE with the version of the RPM package release, for example, "1".

    Replace RPM-SUMMARY with the summary string for the RPM package.

    Replace REPO-URL with the URL of the get repository to clone and create the archive from it.

    Replace GIT-REF with the git reference to check out, for example, origin/branch-name, git tag, or git commit hash.

    Replace SERVICES with the path to install the directory of the git repository when installing the RPM package.

    As a consequence, the git repository you provided is cloned, the specified git reference is checked out and an RPM package is created to install the files to a destination path, for example, /opt/server/. The RPM includes a summary with the details of the repository and reference used to create it. The RPM package is also included in the image build metadata.

    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.