rpi23-gen-image

Introduction

rpi23-gen-image.sh is an advanced Debian Linux bootstrapping shell script for generating Debian OS images for all Raspberry Pi computers. The script at this time supports the bootstrapping of the Debian (armhf/armel) releases stretch and buster. Raspberry Pi 0/1/2/3/4 images are generated for 32-bit mode only. Raspberry Pi 3 supports 64-bit images that can be generated using custom configuration parameters (templates/rpi3-stretch-arm64-4.14.y).

Build dependencies

The following list of Debian packages must be installed on the build system because they are essentially required for the bootstrapping process. The script will check if all required packages are installed and missing packages will be installed automatically if confirmed by the user.

debootstrap debian-archive-keyring qemu-user-static binfmt-support dosfstools rsync bmap-tools whois git bc psmisc dbus sudo

It is recommended to configure the rpi23-gen-image.sh script to build and install the latest Raspberry Pi Linux kernel. For the Raspberry 3 this is mandatory. Kernel compilation and linking will be performed on the build system using an ARM (armhf/armel/aarch64) cross-compiler toolchain.

The script has been tested using the default crossbuild-essential-armhf and crossbuild-essential-armel toolchain meta packages on Debian Linux stretch build systems. Please check the Debian CrossToolchains Wiki for further information.

Command-line parameters

The script accepts certain command-line parameters to enable or disable specific OS features, services and configuration settings. These parameters are passed to the rpi23-gen-image.sh script via (simple) shell-variables. Unlike environment shell-variables (simple) shell-variables are defined at the beginning of the command-line call of the rpi23-gen-image.sh script.

Command-line examples:

ENABLE_UBOOT=true ./rpi23-gen-image.sh
ENABLE_CONSOLE=false ENABLE_IPV6=false ./rpi23-gen-image.sh
ENABLE_WM=xfce4 ENABLE_FBTURBO=true ENABLE_MINBASE=true ./rpi23-gen-image.sh
ENABLE_HARDNET=true ENABLE_IPTABLES=true /rpi23-gen-image.sh
APT_SERVER=ftp.de.debian.org APT_PROXY="http://127.0.0.1:3142/" ./rpi23-gen-image.sh
ENABLE_MINBASE=true ./rpi23-gen-image.sh
BUILD_KERNEL=true ENABLE_MINBASE=true ENABLE_IPV6=false ./rpi23-gen-image.sh
BUILD_KERNEL=true KERNELSRC_DIR=/tmp/linux ./rpi23-gen-image.sh
ENABLE_MINBASE=true ENABLE_REDUCE=true ENABLE_MINGPU=true BUILD_KERNEL=true ./rpi23-gen-image.sh
ENABLE_CRYPTFS=true CRYPTFS_PASSWORD=changeme EXPANDROOT=false ENABLE_MINBASE=true ENABLE_REDUCE=true ENABLE_MINGPU=true BUILD_KERNEL=true ./rpi23-gen-image.sh
RELEASE=buster BUILD_KERNEL=true ./rpi23-gen-image.sh
RPI_MODEL=3 ENABLE_WIRELESS=true ENABLE_MINBASE=true BUILD_KERNEL=true ./rpi23-gen-image.sh
RELEASE=buster RPI_MODEL=3 ENABLE_WIRELESS=true ENABLE_MINBASE=true BUILD_KERNEL=true ./rpi23-gen-image.sh

Configuration template files

To avoid long lists of command-line parameters and to help to store the favourite parameter configurations the rpi23-gen-image.sh script supports so called configuration template files (CONFIG_TEMPLATE=template). These are simple text files located in the ./templates directory that contain the list of configuration parameters that will be used. New configuration template files can be added to the ./templates directory.

Command-line examples:

CONFIG_TEMPLATE=rpi3stretch ./rpi23-gen-image.sh
CONFIG_TEMPLATE=rpi2stretch ./rpi23-gen-image.sh

Working with the your template:

• A Pipe ("|") represents a logical OR
• A valuetype of boolean represents the options true or false
• Values without a default are required if you want do use that feature. It is possible that not every feature has a (working) sanity check.
• If it's not working as expected, search your option in all the files in this repository (With e.g.grep or notepad++).
• Check if your missing a required option while looking at the code

Supported parameters and settings

APT settings:

General system settings:

User settings:

Keyboard settings:

These options are used to configure keyboard layout in /etc/default/keyboard for console and Xorg. These settings can also be changed inside the running OS using the dpkg-reconfigure keyboard-configuration command.

Networking settings:

ethernet setting go to /etc/systemd/network/eth0.network. wifi settings go to /etc/systemd/network/wlan0.network.

The default location of network configuration files in the Debian stretch release was changed to /lib/systemd/network.`

Networking settings (DHCP):

Networking settings (ethernet static):

The following static networking parameters are only supported if ENABLE_ETH_DHCP was set to false.

Networking settings (WIFI):

Networking settings (WIFI static):

The following static networking parameters are only supported if ENABLE_WIFI_DHCP was set to false.

Basic system features:

Advanced system features:

SSH settings:

Kernel settings:

Reduce disk usage:

The following list of parameters is ignored if ENABLE_REDUCE=false.

Encrypted root partition:

On first boot, you will be asked to enter you password several time

See cryptsetup options for a more information about opttion values(https://wiki.archlinux.org/index.php/Dm-crypt/Device_encryption)

Build settings:

Understanding the script

The functions of this script that are required for the different stages of the bootstrapping are split up into single files located inside the bootstrap.d directory. During the bootstrapping every script in this directory gets executed in lexicographical order:

All the required configuration files that will be copied to the generated OS image are located inside the files directory. It is not recommended to modify these configuration files manually.

Custom packages and scripts

Debian custom packages, i.e. those not in the debian repositories, can be installed by placing them in the packages directory. They are installed immediately after packages from the repositories are installed. Any dependencies listed in the custom packages will be downloaded automatically from the repositories. Do not list these custom packages in APT_INCLUDES.

Scripts in the custom.d directory will be executed after all other installation is complete but before the image is created.

Logging of the bootstrapping process

All information related to the bootstrapping process and the commands executed by the rpi23-gen-image.sh script can easily be saved into a logfile. The common shell command script can be used for this purpose:

script -c 'APT_SERVER=ftp.de.debian.org ./rpi23-gen-image.sh' ./build.log

Flashing the image file

After the image file was successfully created by the rpi23-gen-image.sh script it can be copied to the microSD card that will be used by the RPi 0/1/2/3 computer. This can be performed by using the tools bmaptool or dd. Using bmaptool will probably speed-up the copy process because bmaptool copies more wisely than dd.

Flashing examples:

bmaptool copy ./images/buster/2017-01-23-rpi3-buster.img /dev/mmcblk0
dd bs=4M if=./images/buster/2017-01-23-rpi3-buster.img of=/dev/mmcblk0

If you have set ENABLE_SPLITFS, copy the -frmw image on the microSD card, then the -root one on the USB drive:

bmaptool copy ./images/buster/2017-01-23-rpi3-buster-frmw.img /dev/mmcblk0
bmaptool copy ./images/buster/2017-01-23-rpi3-buster-root.img /dev/sdc

QEMU emulation

Start QEMU full system emulation:

qemu-system-arm -m 2048M -M vexpress-a15 -cpu cortex-a15 -kernel kernel7.img -no-reboot -dtb vexpress-v2p-ca15_a7.dtb -sd ${IMAGE_NAME}.qcow2 -append "root=/dev/mmcblk0p2 rw rootfstype=ext4 console=tty1"

Start QEMU full system emulation and output to console:

qemu-system-arm -m 2048M -M vexpress-a15 -cpu cortex-a15 -kernel kernel7.img -no-reboot -dtb vexpress-v2p-ca15_a7.dtb -sd ${IMAGE_NAME}.qcow2 -append "root=/dev/mmcblk0p2 rw rootfstype=ext4 console=ttyAMA0,115200 init=/bin/systemd" -serial stdio

Start QEMU full system emulation with SMP and output to console:

qemu-system-arm -m 2048M -M vexpress-a15 -cpu cortex-a15 -smp cpus=2,maxcpus=2 -kernel kernel7.img -no-reboot -dtb vexpress-v2p-ca15_a7.dtb -sd ${IMAGE_NAME}.qcow2 -append "root=/dev/mmcblk0p2 rw rootfstype=ext4 console=ttyAMA0,115200 init=/bin/systemd" -serial stdio

Start QEMU full system emulation with cryptfs, initramfs and output to console:

qemu-system-arm -m 2048M -M vexpress-a15 -cpu cortex-a15 -kernel kernel7.img -no-reboot -dtb vexpress-v2p-ca15_a7.dtb -sd ${IMAGE_NAME}.qcow2 -initrd "initramfs-${KERNEL_VERSION}" -append "root=/dev/mapper/secure cryptdevice=/dev/mmcblk0p2:secure rw rootfstype=ext4 console=ttyAMA0,115200 init=/bin/systemd" -serial stdio

External links and references

• Debian worldwide mirror sites
• Debian Raspberry Pi 2 Wiki
• Debian CrossToolchains Wiki
• Official Raspberry Pi Firmware on github
• Official Raspberry Pi Kernel on github
• U-BOOT git repository
• Xorg DDX driver #FFFFFF#FFFFFF#FFFFFF
• RPi3 Wireless interface firmware
• Collabora RPi2 Kernel precompiled