System container image builder for LXC and LXD
Switch branches/tags
Nothing to show
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
distrobuilder Add support for Alpine edge Jun 27, 2018
doc/examples examples: arch -> architecture Jul 6, 2018
generators tests: Use testify Jul 3, 2018
image tests: Use testify Jul 3, 2018
managers managers: Add portage Apr 3, 2018
shared tests: Use testify Jul 3, 2018
sources Fix bad root permissions in Alpine Jul 7, 2018
testdata shared: Add file verification Feb 15, 2018
.travis.yml Bump Go to 1.11 Oct 3, 2018
AUTHORS initial commit Feb 6, 2018
COPYING initial commit Feb 6, 2018
Makefile tests: Run deadcode and vet Feb 20, 2018 Update Oct 4, 2018


System container image builder for LXC and LXD


Type Service Status
CI Jenkins Build Status
Project status CII Best Practices CII Best Practices

Command line options

The following are the command line options of distrobuilder. You can use distrobuilder to create container images for both LXC and LXD.

$ distrobuilder
System container image builder for LXC and LXD

  distrobuilder [command]

Available Commands:
  build-dir   Build plain rootfs
  build-lxc   Build LXC image from scratch
  build-lxd   Build LXD image from scratch
  help        Help about any command
  pack-lxc    Create LXC image from existing rootfs
  pack-lxd    Create LXD image from existing rootfs

      --cache-dir   Cache directory
      --cleanup     Clean up cache directory (default true)
  -h, --help        help for distrobuilder
  -o, --options     Override options (list of key=value)

Use "distrobuilder [command] --help" for more information about a command.

How to use

In the following, we see how to create a container image for LXD.


Currently, there are no binary packages of distrobuilder. Therefore, you will need to compile it from source. To do so, first install the Go programming language, and some other dependencies.

sudo apt update
sudo apt install -y golang-go debootstrap rsync gpg squashfs-tools

Second, download the source code of the distrobuilder repository (this repository). The source will be placed in $HOME/go/src/

go get -d -v

Third, enter the directory with the source code of distrobuilder and run make to compile the source code. This will generate the executable program distrobuilder, and it will be located at $HOME/go/bin/distrobuilder.

cd $HOME/go/src/

Creating a container image

To create a container image, first create a directory where you will be placing the container images, and enter that directory.

mkdir -p $HOME/ContainerImages/ubuntu/
cd $HOME/ContainerImages/ubuntu/

Then, copy one of the example yaml configuration files for container images into this directory. In this example, we are creating an Ubuntu container image.

cp $HOME/go/src/ ubuntu.yaml

Finally, run distrobuilder to create the container image. We are using the build-lxd option to create a container image for LXD.

sudo $HOME/go/bin/distrobuilder build-lxd ubuntu.yaml

If the command is successful, you will get an output similar to the following. The lxd.tar.xz file is the description of the container image. The rootfs.squasfs file is the root filesystem (rootfs) of the container image. The set of these two files is the container image.

multipass@dazzling-termite:~/ContainerImages/ubuntu$ ls -l
total 121032
-rw-r--r-- 1 root      root            560 Oct  3 13:28 lxd.tar.xz
-rw-r--r-- 1 root      root      123928576 Oct  3 13:28 rootfs.squashfs
-rw-rw-r-- 1 multipass multipass      3317 Oct  3 13:19 ubuntu.yaml

Adding the container image to LXD

To add the container image to a LXD installation, use the lxc image import command as follows.

multipass@dazzling-termite:~/ContainerImages/ubuntu$ lxc image import lxd.tar.xz rootfs.squashfs --alias mycontainerimage
Image imported with fingerprint: ae81c04327b5b115383a4f90b969c97f5ef417e02d4210d40cbb17a038729a27

Let's see the container image in LXD. The ubuntu.yaml had a setting to create an Ubuntu 17.10 (artful) image. The size is 118MB.

$ lxc image list mycontainerimage
|      ALIAS       | FINGERPRINT  | PUBLIC |  DESCRIPTION  |  ARCH  |   SIZE   |         UPLOAD DATE          |
| mycontainerimage | ae81c04327b5 | no     | Ubuntu artful | x86_64 | 118.19MB | Oct 3, 2018 at 12:09pm (UTC) |

Launching a container from the container image

To launch a container from the freshly created container image, use lxc launch as follows. Note that you do not specify a repository of container images (like ubuntu: or images:) because the image is located locally.

$ lxc launch mycontainerimage c1
Creating c1
Starting c1