Back to the news overview

Distrobuilder 1.0 has been released



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