### Configure ISO Boot Parameters

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/20-bootc/05-sources-of-configuration.md

Example of an iso.yaml file used for the `bootc-generic-iso` image type. Specifies the ISO label and GRUB2 boot entries, including kernel parameters for installation.

```yaml
label: "Fedora-bootc-Installer"
grub2:
  entries:
    - name: "Install Fedora (bootc)"
      linux: "/images/pxeboot/vmlinuz inst.stage2=hd:LABEL=Fedora-bootc-Installer console=tty0 inst.text selinux=0"
      initrd: "/images/pxeboot/initrd.img"
```

--------------------------------

### Example Containerfile for Fedora Bootc Installer ISO

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/20-bootc/10-isos.md

This Containerfile demonstrates how to build a Fedora bootable ISO installer. It installs necessary packages for Anaconda, configures EFI bootloaders, and defines ISO and Anaconda configurations.

```Dockerfile
FROM quay.io/fedora/fedora-bootc:rawhide

RUN dnf install -qy \
    anaconda \
    anaconda-install-img-deps \
    anaconda-dracut \
    dracut-config-generic \
    dracut-network \
    net-tools \
    grub2-efi-x64-cdboot \
    plymouth \
    default-fonts-core-sans \
    default-fonts-other-sans \
    google-noto-sans-cjk-fonts

# these are necessary build tools. if you use a separate build container then
# these tools should be installed there
RUN dnf install -qy \
    xorrisofs \
    squashfs-tools

RUN dnf clean all

RUN mkdir -p /boot/efi && cp -ra /usr/lib/efi/*/*/EFI /boot/efi

# ---

# some configuration for our ISO

RUN mkdir -p /usr/lib/image-builder/bootc

COPY <<EOT /usr/lib/image-builder/bootc/iso.yaml
label: "Fedora-bootc-Installer"
grub2:
  entries:
    - name: "Install Fedora (bootc)"
      linux: "/images/pxeboot/vmlinuz inst.stage2=hd:LABEL=Fedora-bootc-Installer console=tty0 inst.graphical selinux=0 rhgb quiet"
      initrd: "/images/pxeboot/initrd.img"
EOT

# some configuration for anaconda

COPY <<EOT /usr/share/anaconda/interactive-defaults.ks
bootc --source-imgref registry:quay.io/fedora/fedora-bootc:rawhide --target-imgref quay.io/fedora/fedora-bootc:rawhide
EOT

# ---
```

--------------------------------

### Install Dependencies and Build from Source

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/00-installation.md

Install necessary development tools and dependencies, clone the repository, build the image-builder binary, and then run it from the source checkout. This is recommended for development or hacking on the source code.

```bash
$ sudo dnf install go git-core osbuild osbuild-depsolve-dnf osbuild-ostree osbuild-lvm2 osbuild-luks2
# ...
$ git clone github.com/osbuild/image-builder-cli
# ...
$ cd image-builder-cli
$ go build ./cmd/image-builder
# ...
$ sudo ./image-builder build --distro fedora-43 minimal-raw-xz
```

--------------------------------

### Build Bootc Installer ISO

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Constructs a bootc installer ISO. Requires both `--bootc-ref` for the installer environment and `--bootc-installer-payload-ref` for the bootable container to be installed. Both containers must be pre-pulled.

```bash
sudo podman pull quay.io/centos-bootc/centos:stream10
```

```bash
sudo image-builder build --bootc-ref localhost/anaconda:latest --bootc-installer-payload-ref quay.io/centos-bootc/centos:stream10 bootc-installer
```

--------------------------------

### Install image-builder using Go build

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Install the image-builder CLI directly using Go commands. This can be run directly or installed into the GOPATH.

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

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

--------------------------------

### Install osbuild prerequisites

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Ensure the required 'osbuild' RPM packages, including 'osbuild' and 'osbuild-depsolve-dnf', are installed on the system.

```console
$ sudo dnf install osbuild osbuild-depsolve-dnf
```

--------------------------------

### Enable COPR and Install Image Builder CLI

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/00-installation.md

Enable the OSBuild COPR repository to get builds from the main branch, which provides more recent versions of image-builder. Then, install the package using DNF.

```bash
$ sudo dnf copr enable @osbuild/image-builder
# ...
$ sudo dnf install image-builder
# ...
$ sudo image-builder build --distro fedora-43 minimal-raw-xz
# ...
```

--------------------------------

### Containerfile for Bootc ISO

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/20-bootc/10-isos.md

This section shows the necessary RUN and COPY commands to prepare a Containerfile for building a bootc ISO. It includes user setup, systemd configurations, and initramfs generation.

```dockerfile
RUN echo "install:x:0:0:root:/root:/usr/libexec/anaconda/run-anaconda" >> /etc/passwd && \
    echo "install::14438:0:99999:7:::\" >> /etc/shadow && \
    passwd -d root

RUN mv /usr/share/anaconda/list-harddrives-stub /usr/bin/list-harddrives && \
    mv /etc/yum.repos.d /etc/anaconda.repos.d && \
    ln -s /lib/systemd/system/anaconda.target /etc/systemd/system/default.target && \
    rm -v /usr/lib/systemd/system-generators/systemd-gpt-auto-generator

RUN ln -s /usr/lib/systemd/system/anaconda-shell@.service /usr/lib/systemd/system/autovt@.service

RUN mkdir /usr/lib/systemd/logind.conf.d
COPY <<EOT /usr/lib/systemd/logind.conf.d/anaconda-shell.conf
[Login]
ReserveVT=2
EOT

RUN mkdir "$(realpath /root)" && \
    kernel=$(kernel-install list --json pretty | jq -r '.[] | select(.has_kernel == true) | .version') && \
    DRACUT_NO_XATTR=1 dracut --force -v --zstd --reproducible --no-hostonly \
        --add "anaconda" \
        "/usr/lib/modules/${kernel}/initramfs.img" "${kernel}"

RUN mkdir /etc/systemd/user/pipewire.service.d/
COPY <<EOT /etc/systemd/user/pipewire.service.d/allowroot.conf
[Unit]
ConditionUser=
EOT

RUN mkdir /etc/systemd/user/pipewire.socket.d/
COPY <<EOT /etc/systemd/user/pipewire.socket.d/allowroot.conf
[Unit]
ConditionUser=
EOT
```

--------------------------------

### Build image with Red Hat subscriptions

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Build an image and include Red Hat subscriptions by passing a JSON file with registration details using the --registrations option. Ensure 'subscription-manager' is installed in the image.

```console
$ cat > registrations.json <<EOF
{
  "redhat": {
    "subscription": {
      "activation_key": "replace-with_activation_key",
      "organization": "replace-with_org",
      "server_url": "replace-with_server_url",
      "base_url": "replace_with-base_url",
      "insights": true,
      "rhc": true,
      "proxy": "replace-with_proxy"
    }
  }
}
EOF
$ sudo image-builder build qcow2 --registrations registrations.json --distro centos-9
```

--------------------------------

### Build Image with Blueprint Customizations

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Builds an image using a TOML blueprint file for customizations. This example adds packages, enables services, creates a user with an SSH key, and sets the hostname.

```toml
packages = [
    { name = "nginx" },
    { name = "haproxy" },
]

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

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

[[customizations.user]]
name = "user"
key = "ssh-ed25519 AAAAC..."

```

```console
$ sudo image-builder build --blueprint blueprint.toml --distro fedora-43 server-qcow2
# ...

```

--------------------------------

### Install prerequisites for compilation

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Install the necessary RPM packages, specifically 'gpgme-devel', required for compiling the application without Go build tags.

```console
$ sudo dnf install gpgme-devel
```

--------------------------------

### Build image for a different architecture

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Build an image for a foreign architecture (e.g., riscv64) by installing 'qemu-user-static' and specifying the architecture with the --arch flag. This process is slower than native building.

```console
$ sudo image-builder build --arch=riscv64 minimal-raw --distro fedora-43
```

--------------------------------

### Schedule Basic Image Build with Koji

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/30-build-systems.md

Use this command to schedule a basic OS image build in Koji. Ensure the `koji-image-builder-cli` package is installed.

```bash
koji image-builder-build \
  --scratch \
  f43-image-builder \
  Fedora-IoT-Raw \
  43 \
  minimal-raw-xz
```

--------------------------------

### Configure Btrfs Filesystem with Subvolumes

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/20-bootc/05-sources-of-configuration.md

Example demonstrating the use of the btrfs filesystem with defined subvolumes for root, home, and var. Requires btrfs support on the build host and container kernel.

```yaml
mount_configuration: "units"
partition_table:
  type: "gpt"
  partitions:
    - size: "1 MiB"
      bootable: true
      type: "21686148-6449-6e6F-744e-656564454649"
    - size: "200 MiB"
      type: "c12a7328-f81f-11d2-ba4b-00a0c93ec93b"
      payload_type: "filesystem"
      payload:
        type: "vfat"
        mountpoint: "/boot/efi"
        label: "ESP"
        fstab_options: "defaults,uid=0,gid=0,umask=077,shortname=winnt"
        fstab_freq: 0
        fstab_passno: 2
    - size: "2 GiB"
      type: "bc13c2ff-59e6-4262-a352-b275fd6f7172"
      payload_type: "filesystem"
      payload:
        type: "ext4"
        label: "boot"
        mountpoint: "/boot"
        fstab_options: "defaults"
        fstab_freq: 0
        fstab_passno: 0
    - size: "4 GiB"
      type: "44479540-f297-41b2-9af7-d131d5f0458a"
      payload_type: "btrfs"
      payload:
        subvolumes:
          - name: "root"
            mountpoint: "/"
          - name: "home"
            mountpoint: "/home"
          - name: "var"
            mountpoint: "/var"
```

--------------------------------

### List Image Types with JSON Format

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Lists available image types and formats the output as JSON, which is useful for programmatic consumption. This example shows how to get the first item in the JSON array.

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

```

--------------------------------

### Define Filesystem Partitions with XFS

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/20-bootc/05-sources-of-configuration.md

Example of defining multiple partitions with XFS filesystems, including boot, boot/efi, and root partitions. Specifies mount points, labels, and fstab options.

```yaml
mount_configuration: "units"
partition_table:
  type: "gpt"
  partitions:
    - size: "1 MiB"
      type: "21686148-6449-6e6F-744e-656564454649"
      bootable: true
    - size: "200 MiB"
      type: "c12a7328-f81f-11d2-ba4b-00a0c93ec93b"
      payload_type: "filesystem"
      payload:
        type: "vfat"
        mountpoint: "/boot/efi"
        label: "ESP"
        fstab_options: "defaults,uid=0,gid=0,umask=077,shortname=winnt"
        fstab_freq: 0
        fstab_passno: 2
    - size: "2 GiB"
      type: "bc13c2ff-59e6-4262-a352-b275fd6f7172"
      payload_type: "filesystem"
      payload:
        type: "xfs"
        label: "boot"
        mountpoint: "/boot"
    - payload_type: "filesystem"
      payload:
        type: "xfs"
        label: "root"
        mountpoint: "/"
```

--------------------------------

### Install image-builder using DNF

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Install the image-builder package on Fedora and CentOS systems from official repositories or COPR for development snapshots.

```console
$ dnf install image-builder
```

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

```console
$ dnf copr enable @osbuild/osbuild rhel-10-x86_64
$ dnf copr enable @osbuild/image-builder rhel-10-x86_64
$ dnf install image-builder
```

--------------------------------

### Install Image Builder CLI on Fedora/CentOS/RHEL

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/00-installation.md

Use this command to install the image-builder package on systems that use DNF package manager. This is the standard installation method for supported distributions.

```bash
$ sudo dnf install image-builder
# ...
$ sudo image-builder build --distro fedora-43 minimal-raw-xz
# ...
```

--------------------------------

### Get Image Builder Version Information

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Prints version information for the `image-builder` binary and its dependencies. The output format can be changed with `--format`, supporting `yaml` (default) and `json`.

```console
$ image-builder version
image-builder:
  version: 0.5
  commit: abc123
  dependencies:
    images: v0.100.0
    osbuild: "105"

```

```console
$ image-builder version --format=json
{
  "image-builder": {
    "version": "0.5",
    "commit": "abc123",
    "dependencies": {
      "images": "v0.100.0",
      "osbuild": "105"
    }
  }
}

```

--------------------------------

### Display Image Builder Version Information

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Use the `image-builder version` command to display the installed version, commit hash, and dependency versions. The output can be formatted as YAML (default) or JSON.

```console
$ image-builder version
image-builder:
  version: 0.5
  commit: abc123
  dependencies:
    images: v0.100.0
    osbuild: "105"
```

--------------------------------

### Combine Filters for Image Types

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Combines multiple filters to narrow down the list of available image types, for example, by type and distribution.

```console
$ image-builder list --filter type:qcow2 --filter distro:fedora-43
# ... list ...

```

--------------------------------

### List and Build Fedora 43 x86_64 Image

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Demonstrates listing available x86_64 image types for Fedora 43 and then building a server-qcow2 image.

```console
$ image-builder list --filter arch:x86_64 --filter distro:fedora-43
fedora-43 type:container arch:x86_64
fedora-43 type:iot-bootable-container arch:x86_64
fedora-43 type:iot-commit arch:x86_64
fedora-43 type:iot-container arch:x86_64
fedora-43 type:iot-installer arch:x86_64
fedora-43 type:iot-qcow2 arch:x86_64
fedora-43 type:iot-raw-xz arch:x86_64
fedora-43 type:iot-simplified-installer arch:x86_64
fedora-43 type:minimal-installer arch:x86_64
fedora-43 type:minimal-raw-xz arch:x86_64
fedora-43 type:minimal-raw-zst arch:x86_64
fedora-43 type:server-ami arch:x86_64
fedora-43 type:server-oci arch:x86_64
fedora-43 type:server-openstack arch:x86_64
fedora-43 type:server-ova arch:x86_64
fedora-43 type:server-qcow2 arch:x86_64
fedora-43 type:server-vagrant-libvirt arch:x86_64
fedora-43 type:server-vagrant-virtualbox arch:x86_64
fedora-43 type:server-vhd arch:x86_64
fedora-43 type:server-vmdk arch:x86_64
fedora-43 type:workstation-live-installer arch:x86_64
fedora-43 type:wsl arch:x86_64
$ sudo image-builder build --distro fedora-43 server-qcow2
# ...

```

--------------------------------

### Build image with osbuild manifest and SBOM

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Build an image and include an osbuild manifest and an SPDX SBOM document in the output directory. Use the --with-manifest and --with-sbom flags.

```console
$ sudo image-builder build qcow2 --distro centos-9 --with-manifest --with-sbom
```

--------------------------------

### Build Bootc Image with Custom Buildroot

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Allows specifying a separate container for the build environment using `--bootc-build-ref`, while `--bootc-ref` defines the image's filesystem. Both containers must be pre-pulled.

```bash
sudo podman pull quay.io/centos-bootc/centos:stream10
```

```bash
sudo podman pull quay.io/toolbx-images/centos-toolbox:stream10
```

```bash
sudo image-builder build --bootc-ref localhost/anaconda:latest --bootc-build-ref quay.io/toolbx-images/centos-toolbox:stream10 qcow2
```

--------------------------------

### Build Bootc ISO using image-builder CLI

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/20-bootc/10-isos.md

Commands to build the bootc ISO image from a Containerfile and then build the bootable ISO.

```bash
sudo podman build -t localhost/iso -f Containerfile
sudo image-builder build --bootc-ref localhost/iso --bootc-default-fs ext4 bootc-generic-iso
```

--------------------------------

### Build an image with specified type and distribution

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Build an image of a specific type (e.g., qcow2) for a given distribution (e.g., centos-9). The output will be stored in a directory named after the image details.

```console
$ sudo image-builder build qcow2 --distro centos-9
```

--------------------------------

### Build Ostree-based IoT Image

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Builds an ostree-based disk image for Fedora IoT using a specified ostree URL and reference. The buildroot is package-based and influenced by the --distro argument.

```console
$ sudo image-builder build --ostree-url https://d2ju0wfl996cmc.cloudfront.net/ --ostree-ref fedora/x86_64/stable/iot iot-raw-xz

```

--------------------------------

### Build Ostree-based Image

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Ostree-based images require `--ostree-url` and `--ostree-ref` arguments. Building without them results in an error.

```bash
sudo image-builder build iot-raw-xz
```

```text
No distro name specified, selecting "fedora-43" based on host, use --distro to override
[|] Manifest generation step
Message: Building manifest for fedora-43-iot-raw-xz
error: options validation failed for image type "iot-raw-xz": ostree.url: required
$
```

--------------------------------

### Build image using a blueprint file

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Build an image using a previously defined blueprint file. Pass the blueprint file path using the --blueprint argument after the image type.

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

--------------------------------

### Run Unit Tests

Source: https://github.com/osbuild/image-builder-cli/blob/main/HACKING.md

Execute the unit tests for the image-builder project. The -short flag skips integration tests.

```console
$ go test -short ./...
```

--------------------------------

### Describe Image Configuration

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Outputs structured information about an image without building it, listing packages and partition tables. Use `--distro` to specify a distribution and version, and `--arch` to specify the architecture.

```console
$ image-builder describe minimal-raw-xz
@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

```

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

```

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

```

--------------------------------

### Build Bootc Image with Container

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Builds a bootc-based image using a specified container. The container must be pulled into local storage first. The `--bootc-ref` argument specifies the container for the image's filesystem.

```bash
sudo podman pull quay.io/centos-bootc/centos:stream10
```

```bash
sudo image-builder build --bootc-ref quay.io/centos-bootc/centos:stream10 qcow2
```

--------------------------------

### Specify Default Filesystem for Bootc Image

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

When a bootc container lacks default filesystem configuration, use `--bootc-default-fs` to specify it. This is necessary for certain operations like mounting partitions.

```bash
sudo image-builder build --bootc-ref quay.io/fedora/fedora-bootc:rawhide qcow2
```

```text
[|] Manifest generation step
Message: Building manifest for bootc-based-qcow2
error: no default fs set: mount "/boot" requires a filesystem but none set
```

```bash
sudo image-builder build --bootc-ref quay.io/fedora/fedora-bootc:rawhide --bootc-default-fs ext4 qcow2
```

--------------------------------

### Build Image Using Blueprint

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/10-repositories.md

Builds an image using a specified blueprint file that includes custom repository configurations.

```shell
$ sudo image-builder build --distro fedora-43 --blueprint blueprint.toml minimal-raw-xz
```

--------------------------------

### Compile image-builder using Make

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Compile the image-builder application using the provided Makefile. This is an alternative to using the standard 'go build' command.

```console
$ make build
```

--------------------------------

### Experimental Cross-Architecture Build

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Attempts to build an image for a different architecture than the host system using the '--arch' flag. Note that this is experimental and may be slower.

```console
$ sudo image-builder build --distro fedora-43 --arch s390x server-qcow2
WARNING: using experimental cross-architecture building to build "s390x"
# ... progress ...

```

--------------------------------

### Build Minimal Raw XZ Image

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Builds a minimal raw xz image for the specified distribution. This command typically requires root privileges.

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

```

--------------------------------

### Define a blueprint for image customization

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Create a TOML or JSON file to define custom configurations for an image, such as adding users with specific properties. This blueprint is then passed to the build command.

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

--------------------------------

### Schedule Image Build with Repositories in Koji

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/30-build-systems.md

Schedule an image build in Koji, passing specific repositories for the build environment. This is common for distributions like Fedora.

```bash
koji image-builder-build \
  --scratch \
  f43-image-builder \
  Fedora-IoT-Raw \
  43 \
  minimal-raw-xz \
  --repo 'https://kojipkgs.fedoraproject.org/compose/rawhide/latest-Fedora-Rawhide/compose/Everything/$arch/os/'
```

--------------------------------

### Build image-builder with Profiling

Source: https://github.com/osbuild/image-builder-cli/blob/main/HACKING.md

Build the image-builder with optional profiling support enabled by setting the DEBUG environment variable.

```console
$ DEBUG=1 make build
```

--------------------------------

### Build and upload image to AWS

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Build an image and automatically upload it to AWS by providing all necessary cloud parameters, including region, bucket name, and AMI name. This applies to image types like 'ami'.

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

--------------------------------

### Generate SBOM for built image

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Include an SPDX-based Software Bill of Materials (SBOM) document in the output directory by using the --with-sbom flag during the image build process.

```console
$ sudo image-builder build --with-sbom ...
```

--------------------------------

### List Available Image Types with force-repo-dir

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/10-repositories.md

Lists available image types using custom repositories defined in a local directory. Only distributions with defined repositories in the specified directory are shown.

```shell
$ image-builder --force-repo-dir=./repo list
rhel-10.0 type:ami arch:x86_64
rhel-10.0 type:azure-cvm arch:x86_64
rhel-10.0 type:azure-rhui arch:x86_64
rhel-10.0 type:azure-sap-rhui arch:x86_64
rhel-10.0 type:azure-sapapps-rhui arch:x86_64
rhel-10.0 type:ec2 arch:x86_64
rhel-10.0 type:ec2-ha arch:x86_64
rhel-10.0 type:ec2-sap arch:x86_64
# ...
```

--------------------------------

### List buildable images

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Command to display a list of all image types that can be built by the image-builder CLI. Output includes image type, format, and architecture.

```console
$ image-builder list
```

--------------------------------

### Generate Image Build Manifest

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Outputs an osbuild manifest for an image, detailing all assembly steps without creating the image. Use `--distro` to specify distribution and version, and `--arch` to specify the architecture.

```console
$ image-builder manifest minimal-raw-xz
# ... json ...

```

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

```

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

```

--------------------------------

### Build Image Using extra-repo

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/10-repositories.md

Builds an image using both built-in repositories and the specified extra repository URL. This is useful for adding supplementary packages.

```shell
$ sudo image-builder build --distro fedora-43 --extra-repo https://some/base/url minimal-raw-xz
```

--------------------------------

### Build Image Using Only force-repo

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/10-repositories.md

Builds an image using only the specified repository URL, overriding all built-in repositories. Ensure the provided URL contains all necessary packages.

```shell
$ sudo image-builder build --distro fedora-43 --force-repo https://some/base/url minimal-raw-xz
```

--------------------------------

### List Available Image Types

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Lists all available built-in image types that can be built for supported distributions. Use filters to narrow down the results.

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

```

--------------------------------

### Build image-builder CLI

Source: https://github.com/osbuild/image-builder-cli/blob/main/HACKING.md

Build the image-builder command-line interface executable.

```console
$ go build ./cmd/image-builder/
```

--------------------------------

### Schedule Image Build with Ostree Commit and Reference in Koji

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/30-build-systems.md

Schedule an image build in Koji for image types that require an ostree commit. This includes specifying the ostree URL and reference.

```bash
koji image-builder-build \
    --scratch \
    f43-image-builder \
    Fedora-Minimal \
    43 \
    iot-installer \
    --repo 'https://kojipkgs.fedoraproject.org/compose/rawhide/latest-Fedora-Rawhide/compose/Everything/$arch/os/' \
    --ostree-url 'https://kojipkgs.fedoraproject.org/compose/iot/repo/' \
    --ostree-ref 'fedora/rawhide/$arch/iot'
```

--------------------------------

### Run image-builder via container

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Execute the image-builder CLI within a privileged container. Mount the local output directory to persist built images.

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

--------------------------------

### Run image-builder via container (no build command)

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Execute the image-builder CLI within a privileged container. This command is a basic container run without specific build arguments.

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

--------------------------------

### Build Image for a Different Distribution

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Builds an image for a specified distribution and version, overriding the host system's default. This is useful when the host is not the target distribution.

```console
$ sudo image-builder build --distro centos-10 qcow2
# ... progress ...

```

--------------------------------

### Build Image using Containerized Image Builder CLI

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/00-installation.md

Run the image-builder CLI within a privileged container. This method is useful for building images directly from the main branch and supports x86_64 and aarch64 architectures. Ensure an 'output' directory is created for storing the built image.

```bash
$ mkdir output
$ sudo podman run \
    --privileged \
    --rm \
    -it \
    -v ./output:/output \
    ghcr.io/osbuild/image-builder-cli:latest \
    build --distro fedora-43 minimal-raw-xz
# ...
```

--------------------------------

### Run Integration Tests

Source: https://github.com/osbuild/image-builder-cli/blob/main/HACKING.md

Execute all tests, including integration tests, for the image-builder project.

```console
$ go test ./...
```

--------------------------------

### Override Default Repositories During Build

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Completely replace the default base repositories for a build using the `--force-repo` option. Use with caution as it bypasses safeguards and can lead to build failures.

```console
--force-repo=file:///path/to/repos
```

--------------------------------

### Define Red Hat subscription for image registration

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Create a JSON file to specify Red Hat subscription details, including activation key, organization, server URL, and proxy settings. This is used to add subscriptions to the built image.

```json
{
  "redhat": {
    "subscription": {
      "activation_key": "replace-with_activation_key",
      "organization": "replace-with_org",
      "server_url": "replace-with_server_url",
      "base_url": "replace_with-base_url",
      "insights": true,
      "rhc": true,
      "proxy": "replace-with_proxy"
    }
  }
}
```

--------------------------------

### Repository Directory Structure for image-builder

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/10-repositories.md

Defines the expected directory layout for custom repository definitions. Files must be YAML or JSON and match distribution names.

```shell
repo
├── rhel-10.0.yaml
└── rhel-10.1.yaml
```

--------------------------------

### Disk Partition Layout Configuration (YAML)

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/20-bootc/05-sources-of-configuration.md

Defines the partition table and mount configuration for a disk image. Use this to specify custom partition sizes, types, and mount points. The BIOS boot partition is currently required by bootupd.

```yaml
mount_configuration: "units"
partition_table:
  type: "gpt"
  partitions:
    - size: "1 MiB"
      type: "21686148-6449-6e6F-744e-656564454649"
      bootable: true
    - size: "200 MiB"
      type: "c12a7328-f81f-11d2-ba4b-00a0c93ec93b"
      payload_type: "filesystem"
      payload:
        type: "vfat"
        mountpoint: "/boot/efi"
        label: "ESP"
        fstab_options: "defaults,uid=0,gid=0,umask=077,shortname=winnt"
        fstab_freq: 0
        fstab_passno: 2
    - size: "2 GiB"
      type: "bc13c2ff-59e6-4262-a352-b275fd6f7172"
      payload_type: "filesystem"
      payload:
        type: "ext4"
        label: "boot"
        mountpoint: "/boot"
        fstab_options: "defaults"
        fstab_freq: 0
        fstab_passno: 0
    - size: "4 GiB"
      type: "44479540-f297-41b2-9af7-d131d5f0458a"
      payload_type: "filesystem"
      payload:
        type: "ext4"
        label: "root"
        mountpoint: "/"
        fstab_options: "defaults"
        fstab_freq: 0
        fstab_passno: 0

```

--------------------------------

### Add Extra Repository During Build

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Use the `--extra-repo` option to add one or more external repositories during the image build process. This allows the dependency solver to pick packages from these repositories.

```console
--extra-repo file:///path/to/repo
```

--------------------------------

### Persist container-built images to host

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Mount a local directory into the container to save images built by image-builder. This ensures images are available on the host system.

```console
$ mkdir output
$ sudo podman run --privileged -v ./output:/output ghcr.io/osbuild/image-builder-cli
```

--------------------------------

### List Images in JSON Format

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Control the output format of the `image-builder list` command using the `--format` option. JSON output provides structured data for programmatic use.

```console
$ image-builder list --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"
    }
  }
]
```

--------------------------------

### Extract Version from JSON Output

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

When using `--format=json` with `image-builder version`, you can pipe the output to tools like `jq` to extract specific version information.

```console
$ image-builder version --format=json | jq '.["image-builder"].version'
"0.5"
```

--------------------------------

### Blueprint Repository Configuration

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/10-repositories.md

Defines custom repositories within a blueprint TOML file. These repositories are included in the final artifact, not used during the build process.

```toml
[[customizations.repositories]]
id = "example"
name="Example repo"
baseurls=[ "https://example.com/yum/download" ]
gpgcheck=true
gpgkeys = [ "https://example.com/public-key.asc" ]
enabled=true
```

--------------------------------

### Filter Image List by Architecture and Distribution

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Combine multiple `--filter` options to narrow down the image list by architecture and distribution. Supports shell-style globbing for more flexible matching.

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

--------------------------------

### YAML Repository Definition for image-builder

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/20-advanced/10-repositories.md

Specifies repositories for different architectures in YAML format. Includes base URL, GPG key, and GPG checking options.

```yaml
x86_64:
  - name: "BaseOS"
    baseurl: "https://some/base/url"
    gpgkey: |
      ----BEGIN PGP PUBLIC KEY BLOCK-----
      ...
      -----END PGP PUBLIC KEY BLOCK-----
    check_gpg: true
aarch64:
  - name: "BaseOS"
    baseurl: "https://some/base/url"
    gpgkey: |
      ----BEGIN PGP PUBLIC KEY BLOCK-----
      ...
      -----END PGP PUBLIC KEY BLOCK-----
    check_gpg: true
```

--------------------------------

### Filter Image Types by Distribution

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Filters the list of available image types to show only those for a specific distribution, using the 'distro:' prefix.

```console
$ image-builder list --filter distro:fedora-43
# ... long list ...

```

--------------------------------

### Filter Image List by AMI Type

Source: https://github.com/osbuild/image-builder-cli/blob/main/README.md

Use the `--filter` option to list images of a specific type, such as AMI. Shell-style globbing is supported for filter values.

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

--------------------------------

### Filter Image Types by Architecture

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Filters the list of available image types to show only those for a specific architecture, using the 'arch:' prefix.

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

```

--------------------------------

### Filter Image Types by Type

Source: https://github.com/osbuild/image-builder-cli/blob/main/doc/01-usage.md

Filters the list of available image types to show only those matching a specific image type, using the 'type:' prefix.

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

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.