1. Creating Custom Images With Image Builder
  2. Blueprint Format

B Blueprint Format

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

A blueprint contains the specifications for an Image Builder custom image. The general types of information that you can add to a blueprint are package related information and other customizations. Elements in a typical blueprint file include: 1) basic metadata information, 2) package listing, and 3) other customizations. All configuration entries in a blueprint use the parameter = "value" format convention.

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 the blueprint name, an optional description, and a version. The version follows the semantic versioning scheme in https://semver.org/. You define the metadata only one time in the entire blueprint.

Important:

The metadata information is required in any blueprint. 

name = "Blueprint name"
description = "Description of the blueprint"
version = "Version number"

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. Containers and groups require different information and would use other parameters. Each package, module, container, or group listing must have its own heading, as shown in the following example:

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

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

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

Customizations

Customizations are blueprint specifications in addition to package lists. While a customization would typically appear under the heading [[customization]], more specific customizations append a keyword to the heading for better identification. Customizations typically include more parameters than package information entries.

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

Note:

A custom group refers to a UNIX group, which is different from a group of packages to be downloaded. Therefore, a custom UNIX group definition has its own blueprint heading that's distinct from a package group heading.

[[customizations]]
hostname = "system1"

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

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

[[customizations.groups]]
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/.