Create a custom live Debian 9 and 10 the pro way

In the following tutorial we create a custom Debian 9 and 10 live installation image by using debian-live. Our live image carries some private software that we want to execute every time someone boots the live cd. The resulting live-cd boots with an USB stick, a CD, and the network by PXE.

Other tutorials achieve the same goal by unpacking hacking existing live-cds and meddling with its files, instead of using the official tool debian-live, which creates fresh up-to-date ISOs from scratch, downloading and caching all packages from a Debian repository, and allowing you to use a version control tool like git over the ISOs files.

In eReuse.org, the project I am working, we want to create a live-cd that, when booted through network to target computers, executes our software (which erases hard-drives, for example). Here you can see the project.

debian-live has a magnificent guide, which I recommend reading to understand the deeps of the software. In this tutorial we streamline it using our project as an example.

Finally note that, as per the official docs, this process should work on any Debian derived distribution, like Ubuntu or Linux Mint, and it even allows you to create one of those distributions from a Debian (ex. creating an Ubuntu live cd from a Debian host computer). I have not tested it, though.

Installation

To execute debian-live you need a Debian-like distribution (it can be a virtual one). We tried creating a Debian 9 from a Debian 9 and a Debian 10 from a Debian 10. Install the software through apt install live-build.

Speed-up the building (optional)

debian-live needs to download many Debian packages every time you execute it. Although it caches them, you will still want to set a close Debian mirror. Paste the following to /etc/live/build.conf (you might have to create the file):

LB_MIRROR_BOOTSTRAP="http://ftp.caliu.cat/debian/"
LB_MIRROR_CHROOT_SECURITY<span data-mce-type="bookmark" style="display: inline-block; width: 0px; overflow: hidden; line-height: 0;" class="mce_SELRES_start"></span>="http://security.debian.org/"
LB_MIRROR_CHROOT_BACKPORTS="http://ftp.caliu.cat/debian/"

Replace ftp.caliu.cat with your best debian mirror. If you don’t know which one to use, the package netselect-apt (just install it through apt) tests the speed of several debian mirrors and selects the best candidate for you.

Generate the ISO

The process of creating the build is as follows:

  1. We execute lb config in a blank directory, generating a bunch of files that represent the file structure of our future ISO. We pass parameters to lb config to personalize the generation of these files.
  2. We keep further personalizing these file structure by manually modifying it: adding scripts that we want to execute in different steps of the ISO generation or when the ISO bootstraps, adding files to the ISO’s user folder, etc.
  3. We execute lb build, which reads those files and scripts and magically builds the ISO, resulting in an expected .iso file.

In the following sections we go in detail through those three steps.

1. lb config: customize the live image

Create a folder that hosts the project. This folder is the root folder of the project and you can set up a control version (git) too, as you would in any normal project.

Execute lb config, creating some folders and files, similar to what we have in our Workbench Live project in GitHub. The files and folders inside the config folder is what we call the ISO skeleton.

We can pass parameters to lb config to customize the ISO for us; for example to set a 32 or a 64 bit OS. We write those parameters to a bash file to fasten execution and be able to commit them to our CVS. In the folder of the project, execute cp /usr/share/doc/live-build/examples/auto/* auto/. This copies three new files inside auto. Open auto/config to read the following:

#!/bin/sh

set -e

lb config noauto \
        "${@}"

If we compare it to the Workbench-Live project file auto/config file, we can see many options missing:

#!/bin/sh

set -e

lb config noauto \
    --mode debian \
    --architectures i386 \
    --debian-installer false \
    --archive-areas "main contrib non-free" \
    --apt-indices false \
    --memtest none \
    "${@}"

Those lines personalize the ISO skeleton lb config generates. You can type the ones you see fit in your file —just ensure you add a backslash at the end of each line, as we do. This is what our commands do (in order of appearance):

  1. Enforce installing Debian. Theoretically, you can change debian for ubuntu and it should work (we didn’t try it).
  2. Use a 32 bit architecture (by default it uses the one of your machine), so it can be used in almost any computer.
  3. Don’t include the Debian installer (reduce ISO weight).
  4. Allow and auto-install propietary software, like many WiFi or graphic drivers that are not free or open source.
  5. Don’t add apt indices (delete apt update information and enforce performing apt update before performing apt install, reducing ISO weight).
  6. Remove memtest (reduce ISO weight).

You can see which options lb config accepts by executing man lb config. Once done adding options, save the file and execute again lb config. It will automatically read the configuration options from the file and generate a new skeleton.

Know more about auto scripts here.

2. Customizing the skeleton

The config folder is where the skeleton of the ISO exists. It is where lb config dumps the files and what lb build uses to generate the ISO. Here we can add or change files to deep personalize our ISO. Some insights:

  • The folder config/includes.chroot contains the file structure of the new ISO. If you create a folder called opt inside, it will be the /opt folder inside the ISO.
  • The default user of the image is called user. The image automatically performs login with this user after booting. The home directory of the user is config/includes.chroot/home/user, which translates to just /home/user in the live-cd.
  • debian-live executes script files inside config/hooks/live in different moments of the building process. We call them hooks. Use them to execute code that modifies the ISO while it is being built.
    • For example, our script config/hooks/live/0100-workbench.hook.chroot installs our python software in the ISO, so the resulting .iso has our software pre-installed. Note how our script is accessing /opt/workbench, which is a folder we created in config/includes.chroot/opt/workbench, containing our python code.
    • When writing the script, think that it is executing inside the live-cd’s OS and not in the host machine you are using to build the live-cd: as we mentioned, our script directly accesses /opt/workbench and not config/includes.chroot.... This happens because of the arcane magic of chroot.
  • Use package-lists to easy install packages inside the live-cd. For example, from the official docs: echo vlc >> config/package-lists/my.list.chroot makes lb build to install vlc in the live-cd’s OS. my.list.chroot is just a new empty file we create. Separate each package to install by a line:
    package1
    package2
    package3
    

You can know more about customizing the skeleton and hooks from the official guide.

3. lb build: build the ISO from the skeleton

Once you finish to configure the ISO, execute sudo lb clean; sudo lb build and grab a coffee, as it takes a while. After this, you should get the *.iso file. See below the chapter Problem solving otherwise.

You can try the image with Virtualbox; use Etcher (or similar) to copy it to a pen-drive, or burn it to a CD/DVD. In a following guide I will explain how we set up a PXE environment to load this ISO through network.

lb clean: clean the working directory

lb clean cleans the directory from files lb build creates, but not the ones lb config creates. lb build caches a few stages from the building process, so you want to execute lb clean if you change the skeleton of the ISO. The default setting for lb clean is to erase the cache up to the skeleton generation —it does not erase by default the cache of downloaded packages (and I have never had the need for it).

Problem solving

If lb build failed, consider the following:

  • You have a 100% stable connection to a Debian mirror. debian-live doesn’t like at all unstable connections when downloading packages.
  • The Debian mirror is up-to-date. It happened to me. Just try another Debian mirror.
  • Don’t try to create a netboot image; it didn’t work for me. We use regular (hybrid) ISOs as netboot images and it works well. We will explain it in another post.
  • If you added scripts ensure they executed well. You can see in the output of lb build what your scripts print, including errors.

Committing our work

Which kind of developers we are if we don’t use CVS? Some details before committing the project:

  • Execute cp /usr/share/doc/live-build/examples/gitignore .gitignore to get a suitable .gitignore.
  • Execute lb clean to avoid any file created by lb build ends up committed.

Happy coding 🙂

17 thoughts on “Create a custom live Debian 9 and 10 the pro way

  1. This was an amazing tutorial! It helped me so much!

    You are right when you say “There are many tutorials explaining how….Too many when there is a software that does it in a better and official way”

    The DebianLive wiki could use some work 😀

    Thank you!

    1. Glad to know; thank you for the comment. 🙂

      You are right when you say “There are many tutorials explaining how….Too many when there is a software that does it in a better and official way”

      Definitely. That was our process too before: many lines of bash hacks…

  2. can i use preconfigured user data /etc/(pasword*, group*, shadow) to override booting process which “add live user”? it should be in config/includes.chroot/etc/(pasword, group*, shadow*), isn’t it?

  3. Hello!

    I was wondering, how can you change the Graphical Install banner? I’ve been looking around for a bit now.

    Thanks!

    1. Hello again! I was going back through this post and went to the comments section, only to find this one. I thought to myself ‘Oh, the fella was having the same issue I had!’, only to realize it was I who actually posted the comment.

      Thank-you for the reply! The information is correct, although that file is responsible for the splash that is displayed at ‘first glance’ when the ISO is booted into.

      What I was trying to change back then was the banner at the top of the Debian GUI installer. Luckily, I found a way to do it!

      The actual resources for the image are inside of the ISO (obviously), at /usr/share/graphics. There are two files, logo_debian.png and logo_debian_dark.png. The formatting is: 800×75 px.

      Therefore, you can use the same method of “emulating” as in includes.chroot, only this time it will be inside of includes.installer.

      So you would create yourProject/config/includes.installer/usr/share/graphics and inside of this folder place your two banners (light and dark mode). Make sure proper permissions are set for the files (if you’re like me and you’re making the OS inside of VBox and transferring the files from a Windows host).

      1. Hi. I am creating my own debian distro and I was wondering, how to change the loading gradient in the debian installer? Can you help me with this??

  4. Thank you for this tutorial. It really helped me out repackaging a twice-modified Debian image I had been stuck on.

  5. Under bullseye this tuto doesn’t help me : the command lb config doesn’t read the file auto/config and the file iso created is a basic iso. To create a custom iso successfully I did: (for exemple)
    lb config –architecture amd64 –bootappend-live “boot=live components ip=frommedia persistence locales=fr_FR.UTF-8 keyboard-layouts=fr” –archive-areas “main contrib non-free” –debug –otheroptions …
    All the options on one line obviously.

    1. Can you try executing “lb config” at the root folder of the example project? Which distro and version are you using? And thanks for the comment! 🙂

  6. Is there a way to have this as unattended install as well ? as a image ? a sample tutorial would be perfect . I need it for the latest Debian and for UEFI installs.

    Thanks in advance.

  7. Hi Bustawin, Please have you tried using debian-cd to build a custom cd based on Debian buster?

  8. Hi Bustawin,

    I am trying to add my own repository in the normal iso file but i am not able to do so. When i am adding my directory in config/chroot.include/var/vpn , I can see that the /var/vpn folder is only getting created for the live image.

    Is there any way to include /var/vpn path in the normal iso build as well?

Leave a Reply to Gerard Cancel reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.