image-builder CLI

Build images from the command line in a convenient way.

Run via container

$ sudo podman run --privileged \
   -v ./output:/output \
   ghcr.io/osbuild/image-builder-cli:latest \
   build \
   --distro fedora-41 \
   minimal-raw

Installation

This project is under development right now and we provide up-to-date development snapshots in the following way:

A COPR RPM build https://copr.fedorainfracloud.org/coprs/g/osbuild/image-builder/

Via the go build system:

$ go run github.com/osbuild/image-builder-cli/cmd/image-builder@main

or install it into $GOPATH/bin

$ go install github.com/osbuild/image-builder-cli/cmd/image-builder@main

We plan to provide rpm packages in fedora as well.

Compilation

You can compile the application in cmd/image-builder with the normal go command or use

$ make build

To compile without go build tags you will need to install the required RPMs:

$ sudo dnf install gpgme-devel

Prerequisites

Make sure to have the required osbuild RPMs installed:

$ sudo dnf install osbuild osbuild-depsolve-dnf

Examples

Listing

To see the list of buildable images run:

$ image-builder list-images
...
centos-9 type:qcow2 arch:x86_64
...
rhel-10.0 type:ami arch:x86_64
...

Building

To actually build an image run:

$ sudo image-builder build qcow2 --distro centos-9
...

this will create a directory centos-9-qcow2-x86_64 under which the output is stored.

With the --with-manifest option an osbuild manifest will be placed in the output directory too.

With the --with-sbom option an SPDX SBOM document will be placed in the output directory too.

Blueprints

Blueprints are supported, first create a config.toml and put e.g. the following content in:

[[customizations.user]]
name = "alice"
password = "bob"
key = "ssh-rsa AAA ... user@email.com"
groups = ["wheel"]

Note that both toml and json are supported for the blueprint format.

See https://osbuild.org/docs/user-guide/blueprint-reference/ for the full blueprint reference.

Then just pass them as an additional argument after the image type:

$ sudo image-builder build qcow2 --blueprint ./config.toml --distro centos-9
...

SBOMs

It is possible to generate spdx based SBOM (software bill of materials) documents as part of the build. Just pass --with-sbom and it will put them into the output directory.

Cloud integration

When building an image type that can be uploaded to the cloud (e.g. an "ami") image-builder will automatically upload if all cloud parameters are provided, e.g.

$ image-builder build ami --distro centos-9 \
    --aws-region us-east-1 \
	--aws-bucket example-bucket \
	--aws-ami-name my-image-1

Images can also be uploaded with the image-builder upload command after they are built.

Filtering

When listing images, it is possible to filter:

$ image-builder list-images --filter ami
...
centos-9 type:ami arch:x86_64
...
rhel-8.5 type:ami arch:aarch64
...
rhel-10.0 type:ami arch:aarch64

or be more specific

$ image-builder list-images --filter "arch:x86*" --filter "distro:*centos*"
centos-9 type:ami arch:x86_64
...
centos-9 type:qcow2 arch:x86_64
...

The following filters are currently supported, shell-style globbing is supported:

• distro: the distro name (e.g. fedora-41)
• arch: the architecture name (e.g. x86_64)
• type: the image type name (e.g. qcow2)
• bootmode: the bootmode (legacy, UEFI, hybrid)

Output control

The output can also be switched, supported are "text", "json":

$ image-builder list-images --output=json
[
  {
    "distro": {
      "name": "centos-9"
    },
    "arch": {
      "name": "aarch64"
    },
    "image_type": {
      "name": "ami"
    }
  },
...
  {
    "distro": {
      "name": "rhel-10.0"
    },
    "arch": {
      "name": "x86_64"
    },
    "image_type": {
      "name": "wsl"
    }
  }
]

FAQ

Q: Does this require a backend. A: The osbuild binary is used to actually build the images but beyond that no setup is required, i.e. no daemons like osbuild-composer.

Q: Can I have custom repository files? A: Sure! The repositories are encoded in json in "-.json", files, e.g. "fedora-41.json". See these examples. Use the "--datadir" switch and place them under "repositories/name-version.json", e.g. for: "--datadir /my-project --distro foo-1" a json file must be put under "/my-project/repositories/foo-1.json.

Q: What is the relation to bootc-image-builder? A: Both projects are very close. The bootc-image-builder focuses on providing image-based artifacts while image-builder works with traditional package based inputs. We expect the two projects to merge eventually and they already share a lot of code.

Project

• Website: https://www.osbuild.org
• Bug Tracker: https://github.com/osbuild/image-builder-cli/issues
• Discussions: https://github.com/orgs/osbuild/discussions
• Matrix (chat): Image Builder channel on Fedora Chat
• Changelog: https://github.com/osbuild/image-builder-cli/releases

Repository

• web: https://github.com/osbuild/image-builder-cli
• https: https://github.com/osbuild/image-builder-cli.git
• ssh: git@github.com:osbuild/image-builder-cli.git