distrobuilder

distrobuilder is an image building tool designed for LXC and Incus. It creates LXC/Incus images or plain root file systems using declarative YAML image definitions.

Key capabilities include:

• Using pre-built official images as a base.
• Defining source images, package managers, and OS releases/architectures.
• Specifying packages to install or remove for specific variants.
• Generating additional files and executing arbitrary actions during the build process.
• Building images from ISO files (useful for licensed OSs that cannot be distributed via official servers).
• Building images for use on the Linux Containers image server.

Actions are triggered after specific lifecycle steps in the build process. They are processed in the following order:

1. post-unpack: Runs immediately after the root file system has been unpacked.
2. post-update: Runs after the package manager has updated all packages (this requires packages.update to be set to true).
3. post-packages: Runs after the package manager has installed the requested packages.
4. post-files: Runs after the files section has been processed.

Important constraints for post-files:

• By default, post-files only runs for the following commands: build-lxc, build-incus, pack-lxc, and pack-incus.
• To enable post-files when using the build-dir command, you must explicitly use the --with-post-files flag.

The repositories list allows you to add extra package sources.

• name: The name of the repository.
• url: The repository URL. For some managers like yum, this field can contain the full content of a repository configuration file.
• type: Required only if the package manager supports multiple repository managers.
• key: A GPG armored key ring used for verification.
• Filters: Use architectures, releases, or variants to filter which repositories are applied.

Navigation (toctree)

Every documentation page should be part of a navigation hierarchy. To include subpages in the navigation, use the toctree directive in the parent page:

```{toctree}
:hidden:

subpage1
subpage2

### Orphan Pages
If a page is not included in any `toctree` (an "orphan"), the build will issue a warning. To suppress this warning for a page that intentionally exists outside the navigation, add this to the top of the file:

```yaml
---
orphan: true
---

A package set allows you to group packages and define an action for them.

• packages: A list of package names.
• action: Must be either install or remove.
• flags: An array of flags that are appended to the command specific flags (and global flags) when executing the action. For example, you can use this to pass --no-install-recommends during an installation.
• Filters: You can restrict a set to specific architectures, releases, or variants.

Generators are used to create, modify, or remove files inside the rootfs of an image. In your image definition YAML, generators must be listed under the files key. You can apply filters to each entry using architectures, releases, or variants to ensure a generator only runs on specific target platforms.

If you set pongo: true, the values for path, content, and source will be rendered using the Pongo2 templating engine.

files:
    - generator: <string>
      name: <string>
      path: <string>
      content: <string>
      template:
          properties: <map>
          when: <array>
      templated: <boolean>
      mode: <string>
      gid: <string>
      uid: <string>
      pongo: <boolean>
      source: <string>
      architectures: <array>
      releases: <array>
      variants: <array>

Both build-lxc and build-incus support the --compression flag.

Supported methods:

• bzip2
• gzip
• lzip
• lzma
• lzo
• lzop
• xz (default)
• zstd

Compression levels: You can specify a compression level by appending -N to the method name, where N is an integer (e.g., gzip-9).

You can use filters to control when specific sections of a configuration are executed or applied. Filters work by checking the current environment against a provided list. For a section to run, it must satisfy all active filters (logical AND).

There are three types of filters available:

• releases: A list of allowed release versions.
• architectures: A list of allowed CPU architectures.
• variants: A list of allowed variants (e.g., cloud).

If you define multiple filters, the section will only be applied if the current release is in the releases list, AND the architecture is in the architectures list, AND the variant is in the variants list.

releases:
- v1
- v2
architectures:
- x86_64
variants:
- cloud

To verify a downloaded rootfs tarball (especially when using insecure HTTP sources), use the keys and keyserver fields:

• keys: A list of GPG keys provided as either fingerprints or armored keys. Using armored keys avoids reliance on a keyserver.
• keyserver: The keyserver used to fetch keys. Defaults to hkps.pool.sks-keyservers.net.

Distrobuilder uses mappings to translate between the architecture names used by Incus/LXD and the architecture names used by the distribution's source files (e.g., mapping x86_64 to amd64).

You can configure this in two ways:

1. Custom Mappings: Use the architectures field to provide a manual map of source architectures to target architectures.
2. Preset Mappings: Use the architecture_map field to apply a predefined mapping optimized for a specific distribution.

The resulting mapped architecture can be accessed via the Image.ArchitectureMapped property in code or the image.architecture_mapped key in the definition file.

mappings:
    architectures:
        i686: i386
        x86_64: amd64
        armv7l: armhf
        aarch64: arm64
        ppc: powerpc
        ppc64: powerpc64
        ppc64le: ppc64el

Lists

• Unordered lists: Use - for items. Use * for nested levels.
• Numbered lists: Use 1. for every item to allow the renderer to handle automatic numbering.
• Definition lists: Use the following format:

  Term
  : Definition

Tables

While standard Markdown tables work, the rST list-table syntax is preferred for complex cells (e.g., cells containing multiple paragraphs):

```{list-table}
:header-rows: 1

* - Header 1
  - Header 2
* - Cell 1

    Multi-line
    content
* - Cell 2
  - Cell 3

### Admonitions (Notes)
Use specific note types to highlight information. Use them sparingly:
- `{note}`: General information.
- `{tip}`: Helpful advice.
- `{important}`: Critical information.
- `{caution}`: **Only use this for clear hazards of hardware damage or data loss.**

The build-lxc command creates an LXC image from scratch. It outputs two files: rootfs.tar.xz and meta.tar.xz. Note that after the build completes, the temporary rootfs is destroyed.

To create an LXC image from an existing rootfs without deleting the rootfs, use the pack-lxc command instead.

distrobuilder build-lxc <filename|-> [target dir] [--compression=COMPRESSION] [flags]