How to Build a Custom Debian ISO Image on Debian 12 Bookworm

Creating a custom Debian ISO image can be a powerful way to tailor a Debian system for specific needs—be it for offline installation, automation, or distributing a pre-configured environment to others. Whether you’re a systems administrator, developer, or just a power user, understanding how to build your own ISO image offers greater flexibility and control over the Debian environment.

This guide will walk you through the process of building a custom Debian ISO image using a toolset that works well with Debian 12 Bookworm. We’ll focus on using live-build, a tool officially supported by the Debian project.

Why Build a Custom Debian ISO?

Before diving into the process, let’s briefly look at why you might want to build a custom Debian ISO:

• Pre-configured environments: Embed packages, configurations, and settings specific to your use case.
• Automated deployments: Use preseed files for unattended installation.
• Offline installation media: Ideal for environments with limited or no internet access.
• Security and compliance: Strip out unnecessary components and ensure consistency across installations.
• Branding or educational purposes: Create a custom look and feel for your own distribution.

Prerequisites

Before starting, ensure you are running Debian 12 Bookworm and have administrative privileges.

1. Update Your System

sudo apt update && sudo apt upgrade -y

2. Install Required Packages

We will need the following packages:

sudo apt install live-build debootstrap squashfs-tools xorriso isolinux syslinux-utils wget -y

Step-by-Step Guide to Build a Custom Debian ISO

Step 1: Set Up the Working Directory

Choose a directory where you will configure and build the ISO image:

mkdir ~/debian-custom-iso
cd ~/debian-custom-iso

Step 2: Configure the Build Environment

Use the lb config command to initialize your configuration directory:

lb config \
  --distribution bookworm \
  --binary-images iso-hybrid \
  --archive-areas "main contrib non-free non-free-firmware" \
  --debian-installer live

Explanation of key options:

• --distribution: Specifies the Debian release.
• --binary-images iso-hybrid: Generates an ISO that can be burned to a CD/DVD or written to a USB stick.
• --archive-areas: Includes optional areas of the Debian archive.
• --debian-installer: Includes the Debian installer for installation options.

Step 3: Customize Your Build

This is the most flexible part of the process. You can include packages, add configuration files, change boot themes, and more.

a. Add Custom Packages

You can specify which packages should be installed in the live environment by editing or creating config/package-lists/custom.list.chroot:

mkdir -p config/package-lists
nano config/package-lists/custom.list.chroot

Add your desired packages (one per line). For example:

vim
curl
git
net-tools
gnome-core

Save and exit the file.

b. Add Preseed Configuration (Optional)

To enable unattended installations, create a preseed file:

mkdir -p config/includes.installer
nano config/includes.installer/preseed.cfg

Here, define your preseed directives. For example:

d-i debian-installer/locale string en_US
d-i console-setup/ask_detect boolean false
d-i keyboard-configuration/layoutcode string us

This step is optional but useful for automation.

c. Include Custom Files

If you want to copy custom files into the ISO, use the config/includes.chroot/ directory:

mkdir -p config/includes.chroot/etc/skel
echo "Welcome to your custom Debian ISO!" > config/includes.chroot/etc/skel/README

This would place a README in every new user’s home directory.

d. Add Hooks for Custom Scripts

Hooks are scripts that run during the build process. Create one like this:

mkdir -p config/hooks
nano config/hooks/00-custom-setup.chroot

Add commands you want to run during the chroot phase:

#!/bin/bash
echo "Running custom setup..."
apt-get update
apt-get install -y htop

Make it executable:

chmod +x config/hooks/00-custom-setup.chroot

Step 4: Build the ISO Image

Now that everything is configured, you’re ready to build the image:

sudo lb build

This process may take some time depending on your internet speed and selected packages.

Output

Once complete, you should see a file like:

live-image-amd64.hybrid.iso

You can test this ISO using a virtual machine (like VirtualBox or QEMU), or write it to a USB drive:

sudo dd if=live-image-amd64.hybrid.iso of=/dev/sdX bs=4M status=progress && sync

Replace /dev/sdX with your USB device path—be careful, as this will erase all data on that device.

Optional: Clean the Build Environment

If you need to rebuild from scratch, clean up with:

sudo lb clean

Troubleshooting Tips

1. Missing Packages or Dependencies

Make sure your system has all the required package sources enabled in /etc/apt/sources.list, especially contrib, non-free, and non-free-firmware.

2. ISO Fails to Boot

Check that isolinux and syslinux are correctly configured. Also, ensure your hardware or VM supports the architecture and boot method.

3. Customizations Not Showing

Ensure files are placed in the correct directories (e.g., includes.chroot, package-lists, etc.) and the naming conventions are correct (e.g., *.list.chroot for packages).

Best Practices

• Test frequently: Use virtual machines to test incremental changes.
• Use version control: Keep your config/ directory under Git for reproducibility.
• Document your changes: This helps when maintaining or sharing the project.
• Automate the build: Consider scripting the entire build process if you need to generate multiple ISOs regularly.

Conclusion

Building a custom Debian ISO image on a Debian 12 Bookworm system is both a practical and empowering skill. Whether you’re preparing specialized installation media for enterprise deployments, educational purposes, or personal use, tools like live-build offer the flexibility to tailor Debian to your exact requirements.

By customizing packages, configurations, and installation methods, you ensure consistency and control across multiple systems. The steps outlined here provide a foundational method to get started. With more experimentation, you can further refine your ISO to meet increasingly specific use cases.

If you’re aiming for even more automation, consider integrating tools like Ansible for post-install provisioning, or exploring more advanced Debian tools like vmdebootstrap, refracta, or debian-cd for different build scenarios.