Building debian images

- so many ways-

By Riku Voipio -

What's a disk image

  • Disk images are files replicating contents of a hard drive or another storage media
  • Bootable disk images can boot a computer after copying to a storage media

my motivation

  • At work we use linaro-media-create (LMC)
  • It merges a generic distro rootfs with hardware specific bits “hwpack” to a SD card image
  • The idea was not distribute the images, but let people do it themself
  • Turns out users really like downloading premade images over running LMC

motivation #2

  • LMC is not as good for us at used to be
  • The usecase is now a opposite of some of our goals:
  • “Single upstream kernel for a range of boards”
  • LMC doesn't support new platforms (like ones)
  • We still use LMC but instead of developing it, we hack around it
  • Hence, I started looking for alternatives

Some findings

Images vs installer

  • SPEED: D-I automated install 14min, cloud servers in seconds
  • Convenience: “Just dd this file to a SD card”
  • Easier to build an image than to add support to a strange platform to D-I

What do image builders do

  1. Create partitions to a loopback file
  2. Format filesystems
  3. Run debootstrap
  4. Install extra packages
  5. Add users and set credentials
  6. Do Hardcoded/Default customizations
  7. Run user specified customizations
  8. Install kernel
  9. Install bootloader

Under hood

  • losetup: loopback mount
  • parted: partitioning tool
  • debootstrap: installs basic debian
  • kpartx: automated loopback partition mounting
  • qemu: disk image format conversion and cross-arch emulation
  • cloud-init: “firstboot preseed” - cloud image personalization

Image builder tour

Because there is no official way, everyone writes their own image build tool

“everyone should use D-I”

Debian Installer is the official™ way to install Debian.

Debian Installer

  • YES WE CAN create images with D-I
  • Either manually or automated with preseeding
  • Drawback: Installed with booting - virtualization to rescue
  • Images are customized with a preseed file
  • Easy tool for virtualized install is virt-inst

Debian-Installer example

apt install virtinst libvirt-bin
virsh net-start
sudo virt-install --connect qemu:///system --name Debian8 --ram 1024 \
 --file debian.img --file-size=8 --initrd-inject=preseed.cfg \
 --virt-type kvm --os-variant debianwheezy --extra-args="auto" \

Debian-Installer limitations

  • Platform needs to be supported by D-I
  • When preseeding is not enough, a custom D-I is needed
  • Barrier to customize D-I can be daunting
  • Doesn't anonymize image - shared ssh host keys etc
  • Image generation took 14Min


live-build example

apt install live-build
lb config -b hdd --linux-packages linux-image-4.0-custom -m
echo task-kde-desktop >> config/package-lists/my.list.chroot 
sudo lb build


  • Packaged in Debian but the one used is in github
  • Builds the most official Debian images for Amazon, Google, and other cloud providers
  • Written in python, extendable via plugins and has tests
  • sudo apt install bootstrap-vz
    git clone
    ./bootstrap-vz ./manifests/examples/kvm/wheezy-virtio.yml

bootstrap-vz configuration

  name: gce
  workspace: /target
  name: disk
  description: Debian {system.release} {system.architecture}
  release: jessie
  architecture: amd64
  bootloader: grub
  charmap: UTF-8
  locale: en_US
  timezone: UTC
  backing: raw
    type: msdos
      filesystem: ext4
      size: 10GiB
  - main
  - contrib
  - non-free
  google_cloud_sdk: {}


  • debootstrap wrapper for disk image building
  • Explicit cross-arch support with --foreign option
  • No configuration file, just command line
  • DYI customization scripts

vmdebootstrap example

sudo vmdebootstrap \
 --owner $(whoami) --verbose \
 --mirror \
 --arch armhf \
 --foreign /usr/bin/qemu-arm-static \
 --enable-dhcp \
 --configure-apt \
 --no-extlinux \
 --no-kernel \
 --root-password=rootme \
 --package u-boot \
 --package linux-image-armmp \
 --distribution sid \
 --serial-console-command "'/sbin/getty -L ttyO0 115200 vt100'" \
 --customize "" \
 --bootsize 50m --boottype vfat \
 --image bbb.img

For Openstack

More image builders in Debian archive

  • Xen-tools: Build debian and other distro Xen< guests
  • rootstrap: Originally for UML but makes generic images
  • linaro-media-create: Combines a rootfs with kernel/bootloader to a bootable image
  • grml-debootstrap: GRML projects images creation tool
  • 10 tools so far, did I miss any in Debian?

Even more image builders outside...

How are they done

debian-installershell, C
vmdebootstrappython, shell
diskimage-buildershell, python

subjective conclusion

subjective conclusions #2

  • For many tools, main developer = main user
  • Each tool is tailored for the developers usecase and personal taste
  • Any tool that wants come more widely used needs to be really nice to use

Shortcomings in the tools

  • Hackable user setup: default passwords!
  • Use-case specific hardcoded customizations
  • Hardcoded/restricted partitiong
  • Missing first-boot customizations
  • Unupgradeable kernel, bootloader
  • Copying bits from the host system
  • Cool features only in some tools
  • Example: automatically grow rootfs size to media size on first boot
  • Underdocumentation - how to add an new bootloader etc

Can we fix it?


Just kidding!

Suggestions for discussions

  • Release official Debian images in line with installers
  • Provide link to tool / command line / config used to build the image
  • packages for things like first-boot customization
  • Customizations should in general be packages, not part of the image creating tool
  • Any other key requirements?

Time for discussions