Blueprint Format

B Blueprint Format

Blueprint content consists of basic metadata information, package information, and customizations.

A blueprint provides the specification for an Image Builder custom image. Elements in a typical blueprint file include: 1) basic metadata, 2) package listings, and 3) other customizations. All configuration entries in a blueprint are defined using the parameter = "value" format.

Metadata and package information are defined at the root of the blueprint.

Basic Metadata Information

The blueprint's metadata provides general information about the blueprint itself. The metadata is entered at the top of the file and consists of:

name: The name of the blueprint (required).
description: A description for the blueprint (optional).
version: A version number for the blueprint (required). The version follows the semantic versioning scheme in https://semver.org/.
distro: The required distro in the Image Builder repository, which the image is based on (optional). If the distro value is empty, the image is based on the host image distro.

name = "myblueprint"
        description = "My Blueprint"
        version = "0.0.2"
        distro = "ol-8"

Package Information

Package information is a general term that identifies a list of packages, modules, containers, and groups. Each entry has a corresponding heading in the format [[heading]].

The parameters under each heading depend on what the heading describes. For example package and module lists require the name and version of the package. The version format follows dnf version specifications. For example, the version for a major release is specified as n.n.n, such as 8.7.0. To specify the latest package version, enter an asterisk (*) in place of the version number. For a minor release, type major-number.*, such as 8.*.

Containers and groups require different information and use different parameters. Each package, module, container, or group listing must have its own heading, as shown in the following example:

[[packages]]
name = "tmux"
version = "3.5"

[[packages]]
name = "python3"
version = "3.9.18"

[[groups]]
name = "graphical-admin-tools"

Packages: Are defined in a [[packages]] block. Each entry requires the package name and version.
Package groups: Are defined in a [[groups]] block. Each entry requires only the name of the package group.

Note:

A package group is a set of related packages defined as such in a repository. Therefore, a package group has its own blueprint heading [[groups]], to distinguish it from an individual package.

Customizations

Customizations include any other specifications for the image that aren't associated with packages. For example: users, groups, and keys.

Customizations are defined under the heading [customizations], with more specific customizations appending a keyword to the heading for better identification, for example [[customizations.locale]]. Customizations typically include more parameters than package information entries.

The following example shows customizations for the image's hostname, locale, time zone, and groups.

[customizations]
hostname = "system1"

[[customizations.locale]]
languages = ["en_GB.utf8"]
keyboard = "gb"

[[customizations.timezone]]
timezone = "Europe/Dublin"
ntpservers = ["uk.pool.ntp.org"]

[[customizations.group]]
name = "students"

Other custom entries that you can define include the following:

Users: Contains all the required details that apply to the specific user account, such as the user's name, home directory, the user's default shell, groups to which the user is assigned, and so on.
SSH key: Contains the particular user's name and the public SSH key that you create for the user. This key is added to the user's authorized_keys file.
Kernel: Contains arguments to append to the bootloader's command line.
Firewall ports: Contain the list of ports that you want to open. The ports are specified by using the port:protocol format, for example, 22:tcp.
Firewall services: A separate listing that contains a list of services that you enable and disable for the image. To identify which services you can enable or disable, run the firewall-cmd --get-services command.
Systemd services: Similar to firewall services, this entry contains a list of systemd services that you enable and disable for an image.

The preceding list is partial. For a complete list of blueprint entries, see https://osbuild.org/docs/user-guide/blueprint-reference/.