Distrobuilder 1.1 has been released

20th of August 2020


The distrobuilder team is proud to announce its initial release, distrobuilder 1.1!

This release's highlight is the introduction of VM image building support following LXD's introduction of VM support.

As part of this, distrobuilder also now relies on overlayfs to store deltas while building images (rather than attempting to undo changes).

On top of those two changes, this release also fixes a variety of issues in the different distro source drivers as needed when URLs and files change.

The full list of commits is available below:

  • Advertise the (classic) snap package in the README
  • Fix link to examples dir
  • sources/oracle: Add support for Oracle Linux 8
  • Drop .snapcraf.yaml in favor of snapcraft-pkg-snap repo
  • sources/oracle: Fix Oracle Linux 8
  • managers/yum: Add repo handler
  • managers/dnf: Add repo handler
  • Remove references to "apt_sources"
  • sources: Fix OpenWrt
  • sources: Fix OpenWrt test
  • Fix syntax for custom-manager
  • sources: Fix type in OpenWrt build
  • distrobuilder: Extend pongo2 template usage
  • Add support "flags" in package sets
  • Don't attempt to re-install packages that were installed early
  • managers/apk: Add repo handler
  • sources/alpine: Fix edge builds
  • sources: Support CentOS Stream
  • sources/centos: Fix filename regexes
  • Fix example command in
  • Update - separate LXD and LXC examples
  • sources/void: Update location of checksums
  • sources/alpine: Fix regex
  • shared/definition: Add LXD target
  • shared/definition: Add VM field to target
  • shared/definition: Add GetTypes to filter
  • shared: Export ChrootMount struct
  • *: Pass custom mounts to SetupChroot()
  • *: Support VM filtering
  • distrobuilder: Use overlayfs
  • generators: Pass target to Run* functions
  • doc: Update docs
  • generators: Add lxd-agent generator
  • doc: Add lxd-agent generator
  • generators: Add fstab generator
  • generators: Fix lxd-agent function signatures
  • *: Add VM support
  • vm: Make VM size uint64
  • generators/lxd-agent: Fix systemd unit files
  • vm: Ensure loop device is unmounted before creating image
  • *: Use errors.Wrap() when possible
  • generators: Remove StoreFile and RestoreFiles
  • *: Replace syscall package with unix
  • main: Check VM dependencies
  • *: Use errors.Wrap() when possible
  • managers/pacman: Clean up properly
  • managers: Add preRefresh hook
  • managers/opkg: Use preRefresh hook
  • vm: Handle loop partitions inside containers
  • shared/chroot: Recursively bind /dev
  • main: Add more VM dependencies
  • image/lxd: Rename resulting VM image
  • shared/chroot: Make /dev/fuse read-only
  • shared: Close created files
  • generator/lxd-agent: Fix systemd units path
  • main: Fix build-lxd for VMs
  • chroot: Unmount /dev/fuse
  • shared: Differentiate between build-dir and others
  • chroot: Don't bind-mount /dev
  • chroot: Fix mode for special files in /dev
  • shared/definition: Fix early packages
  • main: Fix file generators
  • generators/lxd-agent: Add trans=virtio option
  • chroot: Remove obsolete code
  • main,shared: Fix undefined image target
  • chroot: Perform package refresh only when needed
  • generators/lxd-agent: Fix openRC service file
  • sources/opensuse: Fix openSUSE
  • sources/opensuse: Fix verification
  • data: Fix core16 initrd
  • generators/lxd-agent: Fix running order
  • lxd-agent: Restart on failure
  • generators/lxd-agent: Fixes ordering issue with lxd-agent
  • managers/apt: Handle repo keys
  • shared/chroot: Create /dev/shm
  • sources/openwrt: Fix snapshot release
  • shared/chroot: Fix /dev/shm file mode
  • sources/funtoo: Fix image and gpg URLs
  • shared/util: Fix checksum matching
  • test: Update checksum matching
  • shared/util: Fix checksum matching
  • test: Update checksum matching
  • cloud-init: Update for virtual machines
  • shared/definition: Add Mode, GID and UID to files
  • generators: Add file access handler
  • generators/dump: Allow changing mode, UID and GID
  • doc/generators: Update dump generator
  • doc/examples/schema: Add mode, gid and uid
  • generators/utils: Fix condition
  • shared: Handle multiple checksums
  • shared/util_test: Update checksum test
  • shared/net: Fix checksum check regression
  • shared/definition: Add Pongo option to files
  • generators/dump: Support pongo2 templates
  • generators/cloud-init: Support pongo2 templates
  • generators/template: Support pongo2 templates
  • doc: Document pongo2
  • Update for change to RunCommandSplit
  • travis: Move to bionic
  • shared/util: preserve xattrs in Pack/PackUpdate
  • sources/opensuse: Fix x86 tarballs
  • sources/centos: Fix CentOS 8 checksum file
  • shared/util: Fix locale when importing GPG keys
  • chroot: Resolve parent directory symlinks
  • shared/chroot: Fix parent directory symlink again
  • sources/oracle: Consider boot images only
  • lxd-agent: Update units
  • lxd-agent: Add udev rules
  • generators/lxd-agent: Add symlink workaround for openSUSE
  • lxd-agent: Fix symlink logic
  • doc/examples: Update Ubuntu example
  • managers/yum: Pass "--allowerasing" flag
  • Revert "managers/yum: Pass "--allowerasing" flag"
  • managers/yum: Use --allowerasing when available
  • sources/centos: Handle list of multiple images
  • sources: Fix apertis test
  • travis: Update Go versions
  • managers: Add luet pms
  • add arch deps
  • sources/apertis: Fix tests
  • doc/building: Document --vm flag
  • doc/generators: Add fstab


Distrobuilder 1.0 has been released

21st of October 2019


The distrobuilder team is proud to announce its initial release, distrobuilder 1.0!

Distrobuilder is a tool which produces root filesystems, LXC and LXD images.

It's the replacement of the LXC template scripts and has slowly been taking over the generation of the many pre-built images that LXC and LXD consume, finally taking over all of them a few months ago.

It's written in Go, shares some logic with LXD and directly generates artifacts suitable for consumption by LXC/LXD or ready to host on an image server.

Rather than relying on shell scripts, it's using a declarative input (YAML) and a number of sources, generators and managers to suit most Linux distributions and use cases.

It can be seen at work here building the many images that we publish daily.

Main components

Image details

This first section covers the usual suspects, the image name, distribution, release, description and architecture.


  name: ubuntu-disco-x86_64
  distribution: ubuntu
  release: disco
  description: Ubuntu {{ image.release }}
  architecture: x86_64

Image sources

The image sources are distribution specific logic (in Go) to either retrieve a suitable minimal base image or produce one from scratch using commonly available tooling (like debootstrap).


  downloader: openwrt-http
    - 0x6768C55E79B032D77A28DA5F0F20257417E1CE16
    - 0x54CC74307A2C6DC9CE618269CD84BCED626471F1
    - 0x6D9278A33A9AB3146262DCECF93525A88B699029

Packages and package managers

Distrobuilder currently supports:

  • apk
  • apt
  • dnf
  • ego
  • equo
  • opkg
  • pacman
  • portage
  • xbps
  • yum
  • zypper

They perform package installation/removal, cleanup, updates and add/remove of package repositories.


    manager: yum
    update: true
    cleanup: true

     - packages:
        - cronie
        - cronie-noanacron
        - curl
        - dhclient
        - initscripts
        - openssh-clients
        - passwd
        - policycoreutils
        - rootfiles
        - rsyslog
        - vim-minimal
       action: install

     - packages:
        - NetworkManager
       action: install
        - 8

     - packages:
        - cloud-init
       action: install
        - cloud


Distrobuilder can generate common files like hostname/hosts, some amount of init system configuration files, cloud-init templates and more generating templating for LXD containers.


 - path: /etc/hostname
   generator: hostname

 - path: /etc/hosts
   generator: hosts

 - path: /etc/resolvconf/resolv.conf.d/original
   generator: remove

 - path: /etc/resolvconf/resolv.conf.d/tail
   generator: remove

 - path: /etc/machine-id
   generator: remove


Actions are effectively a number of hook points at which a provided shell scripts can be run. Those hooks currently are:

  • post-unpack (after the source image was retrieved and unpacked)
  • post-files (after the files were generated)
  • post-updates (after the package updates were applied)
  • post-packages (after any additional package was installed/removed)


  - trigger: post-packages
    action: |-
      set -eux

      # Make sure the locale is built and functional
      echo en_US.UTF-8 UTF-8 >> /etc/locale.gen
      locale-gen en_US.UTF-8 UTF-8
      update-locale LANG=en_US.UTF-8

      # Cleanup underlying /run
      mount -o bind / /mnt
      rm -rf /mnt/run/*
      umount /mnt

      # Cleanup temporary shadow paths
      rm /etc/*-

  - trigger: post-packages
    action: |-
      set -eux

      # Enable cloud-init units
      systemctl enable cloud-init

     - cloud

Architecture maps

One of those tiny internal details, but pretty much every Linux distribution has its own name for the various hardware architecture. Distrobuilder has maps for the most ones, translating between kernel architectures and the name used by the distribution.

This allows for consistent architecture naming in the output, to line up with the patterns used by LXC and LXD.


  architecture_map: debian


Packages, Files and Actions can all be set to only apply to specific image variants, distribution releases or OS architectures, making it possible to have a single YAML file for an entire Linux distribution. Some examples of this can be found in the previous examples.


All the production YAML files for our image server can be found here.

Those are all pretty featureful and will generally be used to generate multiple releases of the distribution for multiple architectures and often for two variants (standard and cloud-init enabled).

Supported distributions

Distrobuilder can build images for the following distributions:

  • Alpine Linux
  • Alt Linux
  • Apertis
  • ArchLinux
  • CentOS
  • Debian (and derivatives, Devuan, Kali, Mint and Ubuntu)
  • Fedora
  • Funtoo
  • Gentoo
  • OpenSUSE
  • OpenWRT
  • Oracle
  • Plamo
  • Sabayon
  • Ubuntu Core
  • Void Linux

On top of this, a generic docker-http source can also be used to use a Docker image as the base for a LXC/LXD image.

Adding a new distribution is usually pretty straightforward and just requires adding a new package manager wrapper and logic to fetch a minimal source image or to produce that image directly.

Architecture support

Distrobuilder supports and is actively used on:

  • aarch64
  • armv7l (with and without hard floating point)
  • i686
  • ppc64le
  • x86_64
  • s390x

Only native image building is supported at this point, no support for cross-building through qemu-user-static or similar tooling.


A common issue with the older shell scripts in lxc-templates was the lack of validation of the downloaded packages and other artifacts instrumental to the image building process. This was often caused by lack of HTTPS servers to download those files from combined with difficulty of dealing with GPG for the very many distributions we had to support.

Distrobuilder changes that model by using pre-built minimal images downloaded over HTTPS or GPG validated (with support for key retrieval or in-line keyring), then either adding on top of that base image or using the base image to produce a whole new image using the distribution's native tooling.

How to get it

This new LXD release is already available for you to try on our demo service.

Installing it

Using the snap

A snap package is available with both stable and edge releases.

It can be installed with:

snap install distrobuilder --classic

Or to have the latest upstream snapshot:

snap install distrobuilder --classic --edge

From source

The release tarballs can be found on our download page. Those include a snapshot of all the Go dependencies needed to build distrobuilder.

Alternatively, the current upstream code can be built with:

go get