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