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

You can install image-builder in Fedora from the repositories:

$ dnf install image-builder

As this project is under development right now we provide up-to-date development snapshots of the main branch through COPR:

$ dnf copr enable @osbuild/image-builder
$ dnf install image-builder

You can also install 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

Lastly you can use a container:

$ sudo podman run --privileged ghcr.io/osbuild/image-builder-cli

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

Cross architecture building

When qemu-user-static is installed images can be build for foreign architectures. To do this, pass --arch, e.g.:

$ sudo image-builder build --arch=riscv64 minimal-raw --distro fedora-41

building is about 8x-10x slower than native building but still fast enough to be usable.

Note that this feature is considered experimental currently.

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)

Text control

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

$ image-builder list-images --format=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"
    }
  }
]

Modifying the set of used repositories

There are various ways to add extra repositories or override the default base repositories. Most users will want to use the blueprint systems for this. Repositories that are part of the blueprint will get added to the installed image but are not used at build time to install third-party packages.

To change repositories during image build time the command line options --data-dir, --extra-repo and --force-repo can be used. The repositories there will only added during build time and will not be available in the installed system (use the above blueprint options if that the goal).

Note that both options are targeting advanced users/use-cases and when used wrongly can result in failing image builds or non-booting systems.

Using the data-dir switch

When using the --data-dir flag image-builder will look into the /repositories directory for a file called .json that contains the repositories for the .

This .json file is a simple architecture-> repositories mapping that looks like this example.

Adding extra repositories during the build

To add one or more extra repositories during the build use: --extra-repo <baseurl>, e.g. --extra-repo file:///path/to/repo. This will make the content of the repository available during image building and the dependency solver will pick packages from there as appropriate (e.g. if that repository contains a libc or kernel with a higher version number it will be picked over the default repositories).

Overriding the default base repositories during build

To completely replace the default base repositories during a build the option --force-repo=file:///path/to/repos can be used.

Note that the repositories defined there will be used for all dependency solving and there is no safeguards, i.e. one can point to a fedora-42 repository url and try to build a centos-9 image type and the system will happily try its best (and most likely fail). Use with caution.

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 "--data-dir" switch and place them under "repositories/name-version.json", e.g. for: "--data-dir /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