How to Customize the Debian Installer on Debian 12 Bookworm

A comprehensive guide to customizing the Debian installer for Debian 12 (Bookworm), including preseed files, boot parameters, and custom components.
by İbrahim Korucuoğlu (@siberoloji) |
Tags:
Categories:

  8 minute read  

Customizing the Debian Installer: A Step-by-Step Guide for Debian 12

The Debian installer is highly customizable, allowing system administrators and tech enthusiasts to create tailored installation experiences. This guide walks you through the process of customizing the Debian installer for Debian 12 (Bookworm), from setting up your development environment to building and testing your custom installer.

Table of Contents

Introduction

Customizing the Debian installer allows you to:

  • Automate installations with preconfigured settings
  • Include specific packages in the base installation
  • Modify the installer’s appearance and branding
  • Add custom installation steps or components
  • Create specialized distributions for specific hardware or use cases

Whether you’re managing a fleet of servers, developing a specialized Debian distribution, or simply streamlining your personal installation process, customizing the Debian installer can save time and ensure consistency.

Setting Up Your Development Environment

Before you begin customizing the Debian installer, you’ll need to set up a proper development environment on a Debian 12 system.

Required Packages

Install the necessary development packages:

sudo apt update
sudo apt install build-essential devscripts git debhelper \
     debian-installer-11-netboot-amd64 debian-archive-keyring \
     debootstrap dosfstools genisoimage isolinux mtools \
     syslinux-common cpio xorriso

Creating a Working Directory

Create a dedicated directory structure for your customization work:

mkdir -p ~/debian-installer-custom/{build,iso,preseed}
cd ~/debian-installer-custom

Obtaining the Debian Installer Source

There are two approaches to obtaining the Debian installer source: using apt-get source or cloning from the Git repository.

Using apt-get source

apt-get source debian-installer

git clone https://salsa.debian.org/installer-team/debian-installer.git
cd debian-installer
git checkout debian/12.0.0

Understanding the Installer Structure

The Debian installer (d-i) consists of several key components:

  • Debian-installer packages: The core installer components
  • udebs: Lightweight versions of Debian packages used during installation
  • preseed files: Configuration files for automated installations
  • boot parameters: Options passed to the kernel at boot time
  • initrd.gz: The initial RAM disk that loads the installer

Key directories in the source include:

  • build: Contains build scripts and configuration
  • source: Contains the installer’s source code
  • doc: Documentation for the installer
  • preseed: Sample preseeding configurations

Common Customization Scenarios

Before diving into specific customization techniques, let’s consider some common scenarios:

1. Automated Network Installations

Ideal for deploying multiple identical systems, this approach uses a preseeded configuration and PXE boot to automate installations over the network.

2. Custom Installation Media

Creating customized ISO images with predefined settings, additional packages, or branded interfaces for distribution or specific deployment scenarios.

3. Specialized Hardware Support

Adding specific drivers or configurations to support unique hardware requirements that aren’t included in the standard Debian installer.

4. Organization-Specific Distributions

Developing custom Debian variants with organization-specific branding, software selections, and configurations.

Creating a Preseeded Installation

Preseeding is one of the simplest yet most powerful ways to customize the Debian installation process. It allows you to provide answers to the installer questions in advance.

Creating a Basic Preseed File

Create a file named preseed.cfg in your working directory:

nano ~/debian-installer-custom/preseed/preseed.cfg

Add the following content for a basic preseeded configuration:

# Preseed file for Debian 12 (Bookworm) installation
# Localization
d-i debian-installer/locale string en_US
d-i keyboard-configuration/xkb-keymap select us

# Network configuration
d-i netcfg/choose_interface select auto
d-i netcfg/get_hostname string debian
d-i netcfg/get_domain string local

# Mirror settings
d-i mirror/country string manual
d-i mirror/http/hostname string deb.debian.org
d-i mirror/http/directory string /debian
d-i mirror/http/proxy string

# Account setup
d-i passwd/root-login boolean true
d-i passwd/make-user boolean true
d-i passwd/root-password password r00tpassw0rd
d-i passwd/root-password-again password r00tpassw0rd
d-i passwd/user-fullname string Debian User
d-i passwd/username string user
d-i passwd/user-password password userpassw0rd
d-i passwd/user-password-again password userpassw0rd

# Clock and time zone setup
d-i clock-setup/utc boolean true
d-i time/zone string UTC

# Partitioning
d-i partman-auto/method string regular
d-i partman-auto/choose_recipe select atomic
d-i partman-partitioning/confirm_write_new_label boolean true
d-i partman/choose_partition select finish
d-i partman/confirm boolean true
d-i partman/confirm_nooverwrite boolean true

# Package selection
tasksel tasksel/first multiselect standard
d-i pkgsel/include string openssh-server build-essential
d-i pkgsel/upgrade select full-upgrade

# Boot loader installation
d-i grub-installer/only_debian boolean true
d-i grub-installer/bootdev string default

# Finishing up
d-i finish-install/reboot_in_progress note

Integrating the Preseed File

To include your preseed file in the installer image:

  1. Create a directory for your custom ISO:
mkdir -p ~/debian-installer-custom/iso/preseed
  1. Copy the preseed file:
cp ~/debian-installer-custom/preseed/preseed.cfg ~/debian-installer-custom/iso/preseed/

Customizing Boot Parameters

Boot parameters provide another way to customize the installer behavior. You can modify the default boot parameters in the isolinux configuration files.

Modifying isolinux.cfg

  1. Extract the original Debian ISO (download it first if needed):
sudo mount -o loop debian-12.0.0-amd64-netinst.iso /mnt
mkdir -p ~/debian-installer-custom/iso/
cp -r /mnt/* ~/debian-installer-custom/iso/
sudo umount /mnt
  1. Edit the isolinux configuration:
nano ~/debian-installer-custom/iso/isolinux/isolinux.cfg
  1. Find the default install entry and modify it to include your preseed file:
label install
    menu label ^Install
    kernel /install.amd/vmlinuz
    append vga=788 initrd=/install.amd/initrd.gz auto=true priority=critical file=/cdrom/preseed/preseed.cfg ---

Modifying the Installer Appearance

You can customize the look and feel of the Debian installer by modifying its theme components.

Changing the Installer Theme

  1. Extract the current theme:
mkdir -p ~/debian-installer-custom/theme
cd ~/debian-installer-custom/theme
ar x /usr/share/debian-installer-11-netboot-amd64/initrd.gz
gunzip initrd.gz
mkdir initrd-extract
cd initrd-extract
cpio -id < ../initrd
  1. Find and modify theme files:
find . -name "*.theme"
  1. For example, to modify the colors of the installer, edit the newt theme file:
nano ./usr/lib/newt/palette
  1. Replace content with:
root=white,blue
border=white,blue
window=white,blue
shadow=black,black
title=white,blue
button=black,white
actbutton=white,red
compactbutton=black,white
checkbox=black,white
actcheckbox=white,red
entry=black,white
disentry=gray,blue
label=black,white
listbox=black,white
actlistbox=white,red
sellistbox=white,blue
actsellistbox=white,red
textbox=black,white
acttextbox=black,red
helpline=white,blue
roottext=white,blue
emptyscale=black,blue
fullscale=black,white
disabledentry=gray,blue
  1. Repackage the initrd:
cd ~/debian-installer-custom/theme/initrd-extract
find . | cpio -H newc -o > ../new-initrd
cd ..
gzip -9 new-initrd
mv new-initrd.gz ~/debian-installer-custom/iso/install.amd/initrd.gz

Customizing the Boot Menu

You can also customize the boot menu appearance by modifying the isolinux files:

nano ~/debian-installer-custom/iso/isolinux/menu.cfg

Change the menu title and appearance:

menu title Custom Debian 12 Installer
menu background splash.png
menu color title * #FFFFFFFF *
menu color border * #00000000 #00000000 none
menu color sel  * #ffffffff #76a1d0ff *
menu color hotsel 1;7;37;40 #ffffffff #76a1d0ff *
menu color tabmsg * #ffffffff #00000000 *
menu color help  37;40 #ffdddd00 #00000000 none

Adding Custom Components

For more advanced customizations, you might want to add custom components to the installer.

Creating a Custom udeb Package

  1. Create a directory structure for your custom component:
mkdir -p ~/debian-installer-custom/custom-component/DEBIAN
  1. Create the control file:
nano ~/debian-installer-custom/custom-component/DEBIAN/control

Add the following content:

Package: custom-component
Version: 1.0
Architecture: all
Maintainer: Your Name <your.email@example.com>
Description: Custom component for Debian installer
 This package adds custom functionality to the Debian installer.
  1. Add your custom scripts and files to the appropriate directories:
mkdir -p ~/debian-installer-custom/custom-component/usr/lib/debian-installer
  1. Build the udeb package:
cd ~/debian-installer-custom
dpkg-deb --build custom-component
mv custom-component.deb custom-component.udeb
  1. Add your custom udeb to the installer:
mkdir -p ~/debian-installer-custom/iso/pool/main/c/custom-component
cp custom-component.udeb ~/debian-installer-custom/iso/pool/main/c/custom-component/

Building Your Custom Installer

Once you’ve made all your customizations, it’s time to build your custom installation ISO:

cd ~/debian-installer-custom/iso
xorriso -as mkisofs -r -J -joliet-long -l -cache-inodes \
    -isohybrid-mbr /usr/lib/ISOLINUX/isohdpfx.bin \
    -partition_offset 16 -A "Custom Debian Installer" \
    -b isolinux/isolinux.bin -c isolinux/boot.cat \
    -no-emul-boot -boot-load-size 4 -boot-info-table \
    -o ../custom-debian-12-installer.iso .

Testing Your Custom Installer

It’s crucial to thoroughly test your custom installer before using it in production:

  1. Test in a virtual machine first:
qemu-system-x86_64 -m 2048 -boot d -cdrom ~/debian-installer-custom/custom-debian-12-installer.iso

  1. Watch for any errors during the installation process.

  2. Verify that all your customizations work as expected.

Troubleshooting Common Issues

Problem: Preseed File Not Found

Symptoms: The installer doesn’t use your preseed settings

Solution:

  • Verify the path to your preseed file in the boot parameters
  • Check that the preseed file is properly included in the ISO
  • Ensure the preseed file has the correct syntax

Problem: Custom Components Not Loading

Symptoms: Your custom components don’t appear during installation

Solution:

  • Check that your udeb package is correctly built
  • Verify that it’s properly included in the ISO structure
  • Examine the installer logs (press Alt+F4 during installation to see logs)

Problem: Boot Process Fails

Symptoms: The installer doesn’t boot properly

Solution:

  • Verify that you’ve correctly modified the isolinux configuration
  • Check that you haven’t corrupted any critical boot files
  • Rebuild the ISO with verbose output to catch any errors

Conclusion

Customizing the Debian installer allows you to create tailored installation experiences for various use cases. From simple preseeding to advanced component customization, the modular nature of the Debian installer provides flexibility for system administrators and developers.

By following this guide, you should now be able to:

  • Create preseeded installations for automated deployments
  • Customize the installer’s appearance to match your organization’s branding
  • Add custom components to extend the installer’s functionality
  • Build and test your custom installation media

Remember that while customization offers great flexibility, it’s important to thoroughly test your custom installer before deploying it in production environments. Regular updates to your customization process will also be necessary as new Debian releases become available.

For further assistance and community support, the Debian Installer team maintains excellent documentation, and the Debian community forums are always available for troubleshooting and advice.


<  How to Build a Custom Debian ISO Image on Debian 12 Bookworm How to Set Up a Debian-based Server Farm on Debian 12 Bookworm  >