Usage

After installation you probably want to use image-builder. A general workflow would be to find the image type you want to build and then build it.

Let's take a look at the available x86_64 image types for Fedora 41 and build one of them.

$ image-builder list --filter arch:x86_64 --filter distro:fedora-41
fedora-41 type:ami arch:x86_64
fedora-41 type:container arch:x86_64
fedora-41 type:image-installer arch:x86_64
fedora-41 type:iot-bootable-container arch:x86_64
fedora-41 type:iot-commit arch:x86_64
fedora-41 type:iot-container arch:x86_64
fedora-41 type:iot-installer arch:x86_64
fedora-41 type:iot-qcow2-image arch:x86_64
fedora-41 type:iot-raw-image arch:x86_64
fedora-41 type:iot-simplified-installer arch:x86_64
fedora-41 type:live-installer arch:x86_64
fedora-41 type:minimal-raw arch:x86_64
fedora-41 type:oci arch:x86_64
fedora-41 type:openstack arch:x86_64
fedora-41 type:ova arch:x86_64
fedora-41 type:qcow2 arch:x86_64
fedora-41 type:vhd arch:x86_64
fedora-41 type:vmdk arch:x86_64
fedora-41 type:wsl arch:x86_64
$ sudo image-builder build --distro fedora-41 qcow2
# ...

image-builder list

The list command for image-builder lists the available built-in image types that can be built for the built-in distributions.

$ image-builder list
# ... long list ...

Format

The output format used by list can be swapped with the --format flag. Available types are text (for display in a terminal) and json which can be useful to consume programmatically:

$ image-builder list --format=json | jq '.[0]'
{
  "distro": {
    "name": "centos-9"
  },
  "arch": {
    "name": "aarch64"
  },
  "image_type": {
    "name": "ami"
  }
}

Filtering

list output can be filtered with the --filter argument.

Distribution

To filter on a given distribution, one can use --filter with the distro: prefix:

$ image-builder list --filter distro:fedora-41
# ... long list ...

Type

To filter on a given image type the type: prefix:

$ image-builder list --filter type:qcow2
# ... long list ...

Architecture

To filter on a given architecture use the arch: prefix:

$ image-builder list --filter arch:aarch64
# ... long list ...

Combinations

Filters can be combined to narrow the list further.

$ image-builder list --filter type:qcow2 --filter distro:fedora-41
# ... list ...

image-builder build

The build command builds images of a given image type, for example:

$ sudo image-builder build minimal-raw
# ... progress ...

The build command requires root privileges in many cases as image-builder needs access to loopback devices and mount.

By default the build command uses the same distribution and version as the host system, you can pass another distribution and version with the --distro argument:

$ sudo image-builder build --distro fedora-43 minimal-raw
# ... progress ...

When passed --arch image-builder will try to do an experimental cross-architecture build. Note that not all image types are available for all architectures.

Cross-architecture builds are much slower than being able to build on native hardware. However, if no native hardware is available they might be an acceptable compromise.

$ sudo image-builder build --arch s390x qcow2
WARNING: using experimental cross-architecture building to build "s390x"
# ... progress ...

image-builder describe

The describe command outputs structured information about an image without building it. It lists the packages that would be used to build the images and the partition tables.

$ image-builder describe minimal-raw
@WARNING - the output format is not stable yet and may change
distro: fedora-43
type: minimal-raw-zst
arch: x86_64
os_version: "43"
bootmode: uefi
partition_type: gpt
default_filename: disk.raw.zst
build_pipelines:
  - build
payload_pipelines:
  - os
  - image
  - zstd
packages:
  build:
    include:
      - coreutils
      - dosfstools
      - e2fsprogs
      - glibc
      - policycoreutils
      - python3
      - rpm
      - selinux-policy-targeted
      - systemd
      - xz
      - zstd
    exclude: []
  os:
    include:
      - '@core'
      - NetworkManager-wifi
      - brcmfmac-firmware
      - dosfstools
      - dracut-config-generic
      - e2fsprogs
      - efibootmgr
      - grub2-efi-x64
      - initial-setup
      - iwlwifi-mvm-firmware
      - kernel
      - libxkbcommon
      - realtek-firmware
      - selinux-policy-targeted
      - shim-x64
    exclude:
      - dracut-config-rescue
      - firewalld

By default the describe command uses the same distribution and version as the host system, you can pass another distribution and version with the --distro argument:

$ image-builder describe --distro fedora-43 minimal-raw
# ... output ...

When passed --arch image-builder will show the description for that architecture:

$ image-builder describe --arch aarch64 minimal-raw
# ... output ...

image-builder manifest

The manifest command outputs an osbuild manifest for an image. This manifest contains all the steps performed to assemble the eventual image but the image itself is not created.

$ image-builder manifest minimal-raw
# ... json ...

By default the manifest command uses the same distribution and version as the host system, you can pass another distribution and version with the --distro argument:

$ image-builder manifest --distro fedora-43 minimal-raw
# ... json ...

When passed --arch image-builder will show the manifest for that architecture:

$ image-builder manifest --arch aarch64 minimal-raw
# ... output ...

Blueprints

Images can be customized with blueprints. For example we could build the qcow2 we built above with some customizations applied.

We'll be adding the nginx, and haproxy packages and enabling their services so they start on boot. We'll also add a user by the name user with an ssh key and set the hostname of the machine:

$ cat blueprint.toml
packages = [
    { name = "nginx" },
    { name = "haproxy" },
]

[customizations]
hostname = "mynewmachine.home.arpa"

[customizations.services]
enabled = ["nginx", "haproxy"]

[[customizations.user]]
name = "user"
key = "ssh-ed25519 AAAAC..."
$ sudo image-builder build --blueprint blueprint.toml --distro fedora-41 qcow2
# ...