Image specs for the raspi build.
Go to file
Diederik de Haas 1b194afcc9
Fix bug introduced when 'fixing' SC2086 (quotes)
The 'ROOTFLAGS' parameter should NOT be quoted as it then introduces an
(empty) extra argument to 'mount', causing a boot failure.
Thanks to 'mjt' for the help and identifying the issue.

Lessons learned:
1) Don't blindly follow the *suggestions* that shellcheck makes
2) Test your changes (properly) before submitting/merging them

ad 1) I find shellcheck a very useful tool, but it doesn't (and likely
can't) understand the full context. The developer does (or should) and
should evaluate each suggestion whether it's applicable in this case.

ad 2) This should've been obvious and certainly for me.
I'm normally very dilligent and test all my changes, but I got sloppy
this time and did not. With logical consequences.
2022-11-15 15:17:40 +01:00
debian Fix shellcheck issue SC2086 (quotes) 2022-11-14 22:38:56 +01:00
rootfs Fix bug introduced when 'fixing' SC2086 (quotes) 2022-11-15 15:17:40 +01:00
.gitignore Add raspi_*_bookworm.yaml to .gitignore 2022-11-01 16:05:31 +01:00
LICENSE Initial commit 2017-10-08 22:48:29 +02:00
Makefile Merge branch 'master' into pythonize 2021-11-20 14:01:01 +01:00
README.md Mention bookworm in addition to buster and bullseye. 2021-12-09 00:07:11 +01:00
generate-recipe.py Add 'bluez-firmware' package to images 2022-11-11 12:53:54 +01:00
raspi_master.yaml Fix issues reported by 'yamllint' 2022-11-11 20:50:40 +01:00

README.md

Raspberry Pi image specs

This repository contains the files with which the images referenced at https://wiki.debian.org/RaspberryPiImages have been built.

Option 1: Downloading an image

See https://wiki.debian.org/RaspberryPiImages for where to obtain the latest pre-built image.

Option 2: Building your own image

If you prefer, you can build a Debian Raspberry Pi image yourself. If you are reading this document online, you should first clone this repository:

git clone --recursive https://salsa.debian.org/raspi-team/image-specs.git
cd image-specs

For this you will first need to install the following packages on a Debian Bullseye (11) or higher system:

  • binfmt-support
  • bmap-tools
  • debootstrap
  • dosfstools
  • fakemachine (optional, only available on amd64)
  • kpartx
  • qemu-utils
  • qemu-user-static
  • time
  • vmdb2 (>= 0.17)
  • python3

To install these (as root):

   apt install -y vmdb2 dosfstools qemu-utils qemu-user-static debootstrap binfmt-support time kpartx bmap-tools python3
   apt install -y fakemachine

If debootstrap still fails with exec format error, try running dpkg-reconfigure qemu-user-static. This calls /var/lib/dpkg/info/qemu-user-static.postinst which uses binfmt-support to register the executable format with /usr/bin/qemu-$fmt-static

This repository includes a master YAML recipe (which is basically a configuration file) for all of the generated images, diverting as little as possible in a parametrized way. The master recipe is raspi_master.yaml.

A Makefile is supplied to drive the build of the recipes into images. If fakemachine is installed, it can be run as an unprivileged user. Otherwise, because some steps of building the image require root privileges, you'll need to execute make as root.

The argument to make is constructed as follows: raspi_<model>_<release>.<result-type>

Whereby <model> is one of 1, 2, 3 or 4, <release> is either buster, bullseye, or bookworm; and <result-type> is img or yaml.

Model 1 should be used for the Raspberry Pi 0, 0w and 1, models A and B. Model 2 for the Raspberry Pi 2 models A and B. Model 3 for all models of the Raspberry Pi 3 and model 4 for all models of the Raspberry Pi 4. So if you want to build the default image for a Raspberry Pi 3B+ with Bullseye, you can just issue:

   make raspi_3_bullseye.img

This will first create a raspi_3_bullseye.yaml file and then use that yaml recipe to build the image with vmdb2.

You can also edit the yaml file to customize the built image. If you want to start from the platform-specific recipe, you can issue:

make raspi_3_bullseye.yaml 

The recipe drives vmdb2, the successor to vmdebootstrap. Please refer to its documentation for further details; it is quite an easy format to understand.

Copy the generated file to a name descriptive enough for you (say, my_raspi_bullseye.yaml). Once you have edited the recipe for your specific needs, you can generate the image by issuing the following (as root):

vmdb2 --rootfs-tarball=my_raspi_bullseye.tar.gz --output \
my_raspi_bullseye.img my_raspi_bullseye.yaml --log my_raspi_bullseye.log

This is, just follow what is done by the _build_img target of the Makefile.

Installing the image onto the Raspberry Pi

Plug an SD card which you would like to entirely overwrite into your SD card reader.

Assuming your SD card reader provides the device /dev/mmcblk0 (Beware If you choose the wrong device, you might overwrite important parts of your system. Double check it's the correct device!), copy the image onto the SD card:

bmaptool copy raspi_3_bullseye.img.xz /dev/mmcblk0

Alternatively, if you don't have bmap-tools installed, you can use dd with the compressed image:

xzcat raspi_3_bullseye.img | dd of=/dev/mmcblk0 bs=64k oflag=dsync status=progress

Or with the uncompressed image:

dd if=raspi_3_bullseye.img of=/dev/mmcblk0 bs=64k oflag=dsync status=progress

Then, plug the SD card into the Raspberry Pi, and power it up.

The image uses the hostname rpi0w, rpi2, rpi3, or rpi4 depending on the target build. The provided image will allow you to log in with the root account with no password set, but only logging in at the physical console (be it serial or by USB keyboard and HDMI monitor).