Translation(s): English - Français - Italiano


Netbooting and Firmware

This page describes how to include non-free firmware within Debian netboot images.

There are a lot of changes in Debian 12 when it comes to non-free firmware. The installer team started updating this page to give better directions.

It would probably make sense to:

  • delete instructions for older releases (the Debian 12 entry mentions what was required regarding apt-set/non-free);
  • keep a specific set of “how to build your own firmware cpio.gz with a selection of packages” instructions;
  • update the download URL with s/testing/stable/ once Debian 12 is released (not hardcoding the codename so that instructions are valid for any further releases — but maybe using the codename and letting users do the substitution would be best).

Introduction

Some network cards annoyingly do not have their firmware in ROM, but rather load it from the host operating system. This is not too much of a problem until you realise that much of the firmware is non-free.

Since Debian 12 and the 2022 General Resolution about non-free firmware, the Social Contract has been updated to mention that non-free firmware is allowed on official media. While non-free-firmware packages are getting added to images like the netinst, they are not getting used during debian-installer builds, which generate the netboot material.

Historically, the generic Debian Installer solution has been to put firmware on an external medium so that the installer can find them (see “Loading Missing Firmware” in the installation guide). This is still a valid solution as of Debian 12.

Netboot users have a different option though, which is adding firmware directly to the netboot initramfs (which doesn't feature firmware): an initramfs is essentially a concatenation of gzipped cpio archives which are extracted into a ramdisk and used as an early userspace by the Linux kernel. Debian Installer's initrd.gz is in fact a single gzipped cpio archive containing all the files the installer needs at boot time. By simply appending another gzipped cpio archive - containing the firmware files we are missing - we get the show on the road!

Simple Method for Debian 12 Bookworm and above (non-free-firmware)

Debian distributes a firmware cpio.gz which can be directly concatenated to the initramfs. It includes firmware packages (most of them found in non-free-firmware) that the installer can spot and deploy in the installer's context and in the system being installed. It also includes metadata (Contents-firmware, dep11/) to help the installer detect as many firmware packages as possible (not only based on kernel logs), and configure the system appropriately.

Example #1: add debs from firmware.cpio.gz

# cd to the directory where you have your initrd
cd /tftpboot/debian-installer/amd64
[ -f initrd.gz.orig ] || cp -p initrd.gz initrd.gz.orig
[ -f firmware.cpio.gz ] || wget https://cdimage.debian.org/cdimage/firmware/testing/current/firmware.cpio.gz
cat initrd.gz.orig firmware.cpio.gz > initrd.gz

Example #2 : Download netboot, add debs from firmware.cpio.gz (PXE ready)

cd /srv/
mkdir tftp
cd /srv/tftp
wget http://ftp.debian.org/debian/dists/bookworm/main/installer-amd64/current/images/netboot/netboot.tar.gz
tar -xzvf netboot.tar.gz
rm netboot.tar.gz
ln -s debian-installer/amd64/grubx64.efi .
ln -s debian-installer/amd64/grub .
cd /srv/tftp/debian-installer/amd64
[ -f initrd.gz.orig ] || cp -p initrd.gz initrd.gz.orig
[ -f firmware.cpio.gz ] || wget https://cdimage.debian.org/cdimage/firmware/bookworm/current/firmware.cpio.gz
cat initrd.gz.orig firmware.cpio.gz > initrd.gz

Preseed Configuration

Historically, it was necessary to enable the non-free component via apt-setup, so that firmware packages receive security updates (should there be any).

This was done by preseeding the following:

Starting with Debian 12, the installer uses metadata to configure apt-setup automatically (with main in all cases, adding non-free-firmware when non-free firmware packages are deployed). It's still possible to use preseed to be extra sure the non-free-firmware component is configured:

New Simple Method for Debian 8 Jessie and above

Debian now also distribute a firmware cpio.gz which can be directly concatenated to the initramfs. This simplifies things.

Example #1: add debs from firmware.cpio.gz

# cd to the directory where you have your initrd
cd /tftpboot/debian-installer/i386
[ -f initrd.gz.orig ] || cp -p initrd.gz initrd.gz.orig
[ -f firmware.cpio.gz ] || wget http://cdimage.debian.org/cdimage/unofficial/non-free/firmware/stable/current/firmware.cpio.gz
cat initrd.gz.orig firmware.cpio.gz > initrd.gz

Preseed Configuration

Remember, you will need to enable the non-free repository to ensure that the firmware packages receive security updates (should there be any).

This can be done by preseeding the following:

Examples for Debian 7 "Wheezy"

Features in the debian-installer available since debian 6.0 (squeeze) release give us a simple method of adding firmware to the debian-installer initramfs.

Initial testing with the Wheezy debian-installer beta 4 shows that the squeeze method still works. Wheezy examples with updated URLs follow:

Wheezy Example #1 : add single firmware deb

FWTMP=/tmp/d-i_firmware
rm -rf $FWTMP
mkdir  -p $FWTMP/firmware
cd $FWTMP/firmware
wget http://http.debian.net/debian/pool/non-free/f/firmware-nonfree/firmware-bnx2_0.36+wheezy.1_all.deb
cd ../
pax -x sv4cpio -w firmware | gzip -c >firmware.cpio.gz

# cd to the directory where you have your initrd
cd /tftpboot/debian-installer/i386
[ -f initrd.gz.orig ] || cp -p initrd.gz initrd.gz.orig
cat initrd.gz.orig $FWTMP/firmware.cpio.gz > initrd.gz

Stable Example #2 : add debs from firmware.tar.gz

FWTMP=/tmp/d-i_firmware
rm -rf $FWTMP
mkdir  -p $FWTMP/firmware
cd $FWTMP

wget http://cdimage.debian.org/cdimage/unofficial/non-free/firmware/stable/current/firmware.tar.gz

tar -C firmware -zxf firmware.tar.gz

pax -x sv4cpio -s'%firmware%/firmware%' -w firmware | gzip -c >firmware.cpio.gz

# cd to the directory where you have your initrd
cd /tftpboot/debian-installer/i386
[ -f initrd.gz.orig ] || cp -p initrd.gz initrd.gz.orig
cat initrd.gz.orig $FWTMP/firmware.cpio.gz > initrd.gz

Wheezy Preseed Configuration

Remember, you will need to enable the non-free repository to ensure that the firmware packages receive security updates (should there be any).

This can be done by preseeding the following:

Examples for Debian 6.0 "Squeeze"

New features in the Squeeze version of debian-installer give us a simpler method of adding firmware to the debian-installer initramfs.

Squeeze Example #1 : add single firmware deb

FWTMP=/tmp/d-i_firmware
rm -rf $FWTMP
mkdir  -p $FWTMP/firmware
cd $FWTMP/firmware
wget http://http.debian.net/debian/pool/non-free/f/firmware-nonfree/firmware-bnx2_0.28+squeeze1_all.deb
cd ../
pax -x sv4cpio -w firmware | gzip -c >firmware.cpio.gz

# cd to the directory where you have your initrd
cd /tftpboot/debian-installer/i386
[ -f initrd.gz.orig ] || cp -p initrd.gz initrd.gz.orig
cat initrd.gz.orig $FWTMP/firmware.cpio.gz > initrd.gz

Oldstable Example #2 : add debs from firmware.tar.gz

FWTMP=/tmp/d-i_firmware
rm -rf $FWTMP
mkdir  -p $FWTMP/firmware
cd $FWTMP

wget http://cdimage.debian.org/cdimage/unofficial/non-free/firmware/oldstable/current/firmware.tar.gz

tar -C firmware -zxf firmware.tar.gz

pax -x sv4cpio -s'%firmware%/firmware%' -w firmware | gzip -c >firmware.cpio.gz

# cd to the directory where you have your initrd
cd /tftpboot/debian-installer/i386
[ -f initrd.gz.orig ] || cp -p initrd.gz initrd.gz.orig
cat initrd.gz.orig $FWTMP/firmware.cpio.gz > initrd.gz

Squeeze Preseed Configuration

Remember, you will need to enable the non-free repository to ensure that the firmware packages receive security updates (should there be any).

This can be done by preseeding the following:

Potential Issues

On some network clients, using large initrd.gz, Grub will throw an "Out of memory" error after selecting "Install". One workaround is to compress the initrd into an .xz compressed file saving up to 50% of space.

[ -f initrd.gz.orig ] || cp -p initrd.gz initrd.gz.orig
[ -f firmware.cpio.gz ] || wget https://cdimage.debian.org/cdimage/firmware/bookworm/current/firmware.cpio.gz
cat initrd.gz.orig firmware.cpio.gz > initrd.gz

gzip -cd initrd.gz | xz -9 --check=crc32 > initrd.xz

Edit debian-installer/amd64/grub/grub.cfg and debian-installer/amd64/boot-screens/txt.cfg menus consequently to use initrd.xz.

See Also


CategoryNetwork CategoryProprietarySoftware CategoryDebianInstaller CategorySystemAdministration