Chapter 5. Composing a RHEL for Edge image using image builder command-line

You can use image builder to create a customized RHEL for Edge image (OSTree commit).

To access image builder and to create your custom RHEL for Edge image, you can either use the RHEL web console interface or the command-line interface.

For Network-based deployments, the workflow to compose RHEL for Edge images using the CLI, involves the following high-level steps:

  1. Create a blueprint for RHEL for Edge image
  2. Create a RHEL for Edge Commit image
  3. Download the RHEL for Edge Commit image

For Non-Network-based deployments, the workflow to compose RHEL for Edge images using the CLI, involves the following high-level steps:

  1. Create a blueprint for RHEL for Edge image
  2. Create a blueprint for the RHEL for Edge Installer image
  3. Create a RHEL for Edge Container image
  4. Create a RHEL for Edge Installer image
  5. Download the RHEL for Edge image

To perform the steps, use the composer-cli package.

Note

To run the composer-cli commands as non-root, you must be part of the weldr group or you must have administrator access to the system.

5.1. Network-based deployments workflow

This provides steps on how to build OSTree commits. These OSTree commits contain a full operating system, but are not directly bootable. To boot them, you need to deploy them using a Kickstart file.

5.1.1. Creating a RHEL for Edge Commit image blueprint using image builder command-line interface

Create a blueprint for RHEL for Edge Commit image using the CLI.

Prerequisite

  • You do not have an existing blueprint. To verify that, list the existing blueprints: 

    $ sudo composer-cli blueprints list

Procedure

  1. Create a plain text file in the TOML format, with the following content: 

    name = "blueprint-name"
description = "blueprint-text-description"
version = "0.0.1"
modules = [ ]
groups = [ ]

    Where,

    • blueprint-name is the name and blueprint-text-description is the description for your blueprint.
    • 0.0.1 is the version number according to the Semantic Versioning scheme.

    • Modules describe the package name and matching version glob to be installed into the image, for example, the package name = "tmux" and the matching version glob is version = "2.9a".

      Notice that currently there are no differences between packages and modules.

    • Groups are packages groups to be installed into the image, for example the group package anaconda-tools.

      At this time, if you do not know the modules and groups, leave them empty.

  2. Include the required packages and customize the other details in the blueprint to suit your requirements.

    For every package that you want to include in the blueprint, add the following lines to the file: 

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

    Where,

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

    • package-version is the version number of the package that you want to use.

      The package-version supports the following dnf version specifications:

    • For a specific version, use the exact version number such as 9.0.
    • For the latest available version, use the asterisk *.
    • For the latest minor version, use formats such as 9.*.

  3. Push (import) the blueprint to the image builder server: 

    # composer-cli blueprints push blueprint-name.toml

  4. List the existing blueprints to check whether the created blueprint is successfully pushed and exists. 

    # composer-cli blueprints show BLUEPRINT-NAME

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

    # composer-cli blueprints depsolve blueprint-name

Additional resources

5.1.2. Creating a RHEL for Edge Commit image using image builder command-line interface

To create a RHEL for Edge Commit image using image builder command-line interface, ensure that you have met the following prerequisites and follow the procedure.

Prerequisites

  • You have created a blueprint for RHEL for Edge Commit image.

Procedure

  1. Create the RHEL for Edge Commit image. 

    # composer-cli compose start blueprint-name image-type

    Where,

    • blueprint-name is the RHEL for Edge blueprint name.

    • image-type is edge-commit for network-based deployment.

      A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

  2. Check the image compose status. 

    # composer-cli compose status

    The output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes up to 20 minutes to complete.

    To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    To delete an existing image, run: 

    # composer-cli compose delete <UUID>

    After the image is ready, you can download it and use the image on your network deployments.

Additional resources

5.1.3. Creating a RHEL for Edge image update with a ref commit using image builder command-line interface

If you performed a change in an existing blueprint, for example, you added a new package, and you want to update an existing RHEL for Edge image with this new package, you can use the --parent argument to generate an updated RHEL for Edge Commit (.tar) image. The --parent argument must be a ref that exists in the repository specified by the URL argument. The --ref argument enables you to specify an existing ref that retrieves a parent for the new commit that you are building. You must specify the parent commit as a ref value to be resolved and pulled, not as a commit ID, for example rhel/9/x86_64/edge. When you specify the parent commit as a ref value, image builder can read information from the parent commit that will affect parts of the new commit that you are building. As a result, image builder reads the parent commit’s user database and preserves UIDs and GIDs for the package-created system users and groups.

To create a RHEL for Edge image with a parent argument using image builder CLI, ensure that you have met the following prerequisites and follow the procedure.

Prerequisites

  • You have updated an existing blueprint for RHEL for Edge image.
  • You have an existing RHEL for Edge image (OSTree commit). See Extracting RHEL for Edge image commit.
  • The ref being built is available at the OSTree repository specified by the URL.

Procedure

  1. Create the RHEL for Edge commit image: 

    # composer-cli compose start-ostree --ref rhel/9/x86_64/edge --parent parent-OSTree-REF --url URL blueprint-name image-type

    For example:

    • To create a new RHEL for Edge commit based on a parent and with a new ref, run the following command:: 

      # composer-cli compose start-ostree --ref rhel/9/x86_64/edge --parent rhel/9/x86_64/edge --url http://10.0.2.2:8080/repo rhel_update edge-commit

    • To create a new RHEL for Edge commit based on the same ref, run the following command: 

      # composer-cli compose start-ostree --ref rhel/9/x86_64/edge --url http://10.0.2.2:8080/repo rhel_update edge-commit

      Where:

      • The --ref argument specifies the same path value that you used to build an OSTree repository.
      • The --parent argument specifies the parent commit as a ref to be resolved and pulled, not as a commit ID, for example rhel/9/x86_64/edge.
      • blueprint-name is the RHEL for Edge blueprint name.
      • The --url argument specifies the URL to the OSTree repository of the commit to embed in the image, for example, http://10.0.2.2:8080/repo.

      • image-type is edge-commit for network-based deployment.

        Note
        • The --parent argument can only be used for the RHEL for Edge Commit (.tar) image type. Using the --url and --parent arguments together results in errors with the RHEL for Edge Container (.tar) image type.
        • If you omit the parent ref argument, the system falls back to the ref specified by the --ref argument.

        A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

  2. Check the image compose status. 

    # composer-cli compose status

    The output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes a few minutes to complete.

    (Optional) To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    (Optional) To delete an existing image, run: 

    # composer-cli compose delete <UUID>

After the image creation is complete, to upgrade an existing OSTree deployment, you need:

Additional resources

5.1.4. Downloading a RHEL for Edge image using the image builder command-line interface

To download a RHEL for Edge image using image builder command line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

  • You have created a RHEL for Edge image.

Procedure

  1. Review the RHEL for Edge image status. 

    # composer-cli compose status

    The output must display the following: 

    $ <UUID> FINISHED date blueprint-name blueprint-version image-type

  2. Download the image. 

    # composer-cli compose image <UUID>

    Image builder downloads the image as a tar file to the current directory.

    The UUID number and the image size is displayed alongside. 

    $ <UUID>-commit.tar: size MB

The image contains a commit and a json file with information metadata about the repository content.

Additional resources

5.2. Non-network-based deployments workflow

To build a boot ISO image that installs an OSTree-based system using the "RHEL for Edge Container" and the "RHEL for Edge Installer" images and that can be later deployed to a device in disconnected environments, follow the steps.

5.2.1. Creating a RHEL for Edge Container blueprint by using image builder CLI

To create a blueprint for RHEL for Edge Container image, perform the following steps:

Procedure

  1. Create a plain text file in the TOML format, with the following content: 

    name = "blueprint-name"
description = "blueprint-text-description"
version = "0.0.1"
modules = [ ]
groups = [ ]

    Where,

    • blueprint-name is the name and blueprint-text-description is the description for your blueprint.
    • 0.0.1 is the version number according to the Semantic Versioning scheme.

    • Modules describe the package name and matching version glob to be installed into the image, for example, the package name = "tmux" and the matching version glob is version = "2.9a".

      Notice that currently there are no differences between packages and modules.

    • Groups are packages groups to be installed into the image, for example the group package anaconda-tools.

      At this time, if you do not know the modules and groups, leave them empty.

  2. Include the required packages and customize the other details in the blueprint to suit your requirements.

    For every package that you want to include in the blueprint, add the following lines to the file: 

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

    Where,

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

    • package-version is the version number of the package that you want to use.

      The package-version supports the following dnf version specifications:

    • For a specific version, use the exact version number such as 9.0.
    • For the latest available version, use the asterisk *.
    • For the latest minor version, use formats such as 9.*.

  3. Push (import) the blueprint to the image builder server: 

    # composer-cli blueprints push blueprint-name.toml

  4. List the existing blueprints to check whether the created blueprint is successfully pushed and exists. 

    # composer-cli blueprints show BLUEPRINT-NAME

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

    # composer-cli blueprints depsolve blueprint-name

Additional resources

5.2.2. Creating a RHEL for Edge Installer blueprint using image builder CLI

You can create a blueprint to build a RHEL for Edge Installer (.iso) image, and specify user accounts to automatically create one or more users on the system at installation time. See Creating an administrative user account for a RHEL for Edge image blueprint. It creates a user on the system at installation time.

Warning

When you create a user in the blueprint with the customizations.user customization, the blueprint creates the user under the /usr/lib/passwd directory and the password, under the /usr/etc/shadow directory. Note that you cannot change the password in further versions of the image in a running system using OSTree updates. The users you create with blueprints must be used only to gain access to the created system. After you access the system, you need to create users, for example, using the useradd command.

To create a blueprint for RHEL for Edge Installer image, perform the following steps:

Procedure

  1. Create a plain text file in the TOML format, with the following content: 

    name = "blueprint-installer"
description = "blueprint-for-installer-image"
version = "0.0.1"

[[customizations.user]]
name = "user"
description = "account"
password = "user-password"
key = "user-ssh-key "
home = "path"
groups = ["user-groups"]

    Where,

    • blueprint-name is the name and blueprint-text-description is the description for your blueprint.
    • 0.0.1 is the version number according to the Semantic Versioning scheme.

  2. Push (import) the blueprint to the image builder server: 

    # composer-cli blueprints push blueprint-name.toml

  3. List the existing blueprints to check whether the created blueprint is successfully pushed and exists. 

    # composer-cli blueprints show blueprint-name

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

    # composer-cli blueprints depsolve blueprint-name

Additional resources

5.2.3. Creating a RHEL for Edge Container image by using image builder CLI

To create a RHEL for Edge Container image using image builder command-line interface, ensure that you have met the following prerequisites and follow the procedure.

Prerequisites

  • You have created a blueprint for RHEL for Edge Container image.

Procedure

  1. Create the RHEL for Edge Container image. 

    # composer-cli compose start-ostree --ref rhel/9/x86_64/edge --url URL-OSTree-repository blueprint-name image-type

    Where,

    • --ref is the same value that customer used to build ostree repository

    • --url is the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repo/. By default, the repository folder for a RHEL for Edge Container image is "/repo". See Setting up a web server to install RHEL for Edge image.

      To find the correct URL to use, access the running container and check the nginx.conf file. To find which URL to use, access the running container and check the nginx.conf file. Inside the nginx.conf file, find the root directory entry to search for the /repo/ folder information. Note that, if you do not specify a repository URL when creating a RHEL for Edge Container image (.tar) using image builder, the default /repo/ entry is created in the nginx.conf file.

    • blueprint-name is the RHEL for Edge blueprint name.

    • image-type is edge-container for non-network-based deployment.

      A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

  2. Check the image compose status. 

    # composer-cli compose status

    The output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes up to 20 minutes to complete.

    To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    To delete an existing image, run: 

    # composer-cli compose delete <UUID>

    After the image is ready, it can be used for non-network deployments. See Creating a RHEL for Edge Container image for non-network-based deployments.

Additional resources

5.2.4. Creating a RHEL for Edge Installer image using command-line interface for non-network-based deployments

To create a RHEL for Edge Installer image that embeds the OSTree commit, using image builder command-line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

  • You have created a blueprint for RHEL for Edge Installer image.
  • You have created a RHEL for Edge Edge Container image and deployed it using a web server.

Procedure

  1. Begin to create the RHEL for Edge Installer image. 

    # composer-cli compose start-ostree --ref rhel/9/x86_64/edge --url URL-OSTree-repository blueprint-name image-type

    Where,

    • ref is the same value that customer used to build ostree repository
    • URL-OSTree-repository is the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repo. See Creating a RHEL for Edge Container image for non-network-based deployments.
    • blueprint-name is the RHEL for Edge Installer blueprint name.

    • image-type is edge-installer.

      A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

  2. Check the image compose status. 

    # composer-cli compose status

    The command output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes a few minutes to complete.

    To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    To delete an existing image, run: 

    # composer-cli compose delete <UUID>

    After the image is ready, you can use it for non-network deployments. See Installing the RHEL for Edge image for non-network-based deployments.

5.2.5. Downloading a RHEL for Edge Installer image using the image builder CLI

To download a RHEL for Edge Installer image using image builder command line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

  • You have created a RHEL for Edge Installer image.

Procedure

  1. Review the RHEL for Edge image status. 

    # composer-cli compose status

    The output must display the following: 

    $ <UUID> FINISHED date blueprint-name blueprint-version image-type

  2. Download the image. 

    # composer-cli compose image <UUID>

    Image builder downloads the image as an .iso file to the current directory.

    The UUID number and the image size is displayed alongside. 

    $ <UUID>-boot.iso: size MB

The resulting image is a bootable ISO image.

Additional resources

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

Note

These customizations are not supported when using image builder in the web console.

Select a distribution
name = "blueprint_name"
description = "blueprint_version"
version = "0.1"
distro = "different_minor_version"

Replace "different_minor_version" to build a different minor version, for example, if you want to build a RHEL 9.0, use distro = "rhel-90". On a RHEL 9.1, you can build minor versions such as RHEL 9.1, RHEL 8.7 and earlier releases. 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 will build images using the new OS version.

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. 

# dnf 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 user 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. 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
Firewall customization

Set the firewall for the resulting system image. By default, the firewall blocks all access, except for services that enable their ports explicitly, such as sshd. The following blueprint can be used to open other ports or services.

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. This cannot be overridden by the blueprint. 

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

Customize the firewall services

services is an optional object with the following attributes containing services to enable or disable for firewalld:

  • enabled - An optional list of strings for services to enable.

  • disabled - An optional list of strings for services to disable.

    Check 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"]

    For example: 

    [customizations.firewall.services]
enabled = ["ftp", "ntp", "dhcp"]
disabled = ["telnet"]

    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:

    Note

    The filesystem customization is not supported for OSTree systems, because OSTree images have their own mount rule, such as read-only. 

    [[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"
Create customized directories and files for your image under the /etc directory

To create customized files and directories in your image, use the [[customizations.files]] and the [[customizations.directories]] blueprint customizations. Currently, 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.

Create a custom directory blueprint customization

With the [[customizations.directories]] blueprint customization, you can create customized directories in the /etc directory of your image.

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.

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.

To customize a directory configuration in your blueprint, create a file with the following content, for example: 

[[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 a custom file blueprint customization

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. If you are not sure about the customizations, use the appropriate blueprint customization.

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

To customize a file in your blueprint, create a file with the following content, for example: 

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

Additional resources

5.4. Additional resources