/raspberian-firstboot

A lightly modified Raspbian-light image supporting first boot customization.

Primary LanguageGoMIT LicenseMIT

raspberian-firstboot

A lightly modified Raspbian-light image with first boot customization.

Our goal is easy boot time customization of the standard Raspberry Pi OS - just edit a simple bash script.

Download the image from the Releases tab.

Why would I use this image?

The standard Raspbian-lite image allows you to customize the wireless settings and enable SSHd before flashing it to an SD card. Unfortunately, there is no way to further customize the OS during the first boot, nothing like cloud-init or userdata. Without a display and keyboard, complex "headless" deployments are impossible.

With this image, you can run a custom script on first boot and:

  • Set a unique hostname. (simple example)
  • Configure HDMI, audio, and network settings. (example)
  • Install apt software packages. (example)
  • Setup an automatic reverse SSH tunnel for remote management. (example)
  • Bootstrap a configuration management tool like Ansible/Chef/Puppet to prevent configuration drift.
  • Deploy your IoT fleet with custom UUIDs and configurations.

Quick Start

There are two ways to use the image, pick one:

  • A. Download the image, customize the image with firstboot scripts, then flash the customized image to your SD card.

  • B. Download the image, flash the image to your SD card, then customize the SD card with firstboot scripts.

Quick Start A

  1. Download the latest image from the Releases tab. Note we currenlty only support the raspbian-lite image.
  2. Mount the /boot volume OF THE IMAGE YOU JUST DOWNLOADED. This usually happens automatically if you "open" the image on Windows, MacOS, or Linux.
  3. NOTE: references below to /mnt will be /Volumes on macos and under "My Computer" on Windows.
  4. Create a /mnt/boot/firstboot.sh script with your custom contents examples here.
  5. Optionally add additional custom configuration files or small binaries to /mnt/boot (the /boot partiton is small - keep your total additions under ~160MB).
  6. Remember, you can also add a /mnt/boot/wpa_supplicant.conf file for wifi configuration.
  7. Unmount the /boot volume: umount /mnt on linux, diskutil unmount /Volumes/boot on macos, right-click for Windows.
  8. Flash the customized image to your SD card. We recommend using Balena Etcher for writing images on all platforms. Folks have run into issues with the official Raspberry Pi Imager.
  9. Boot your Pi... /boot/firstboot.sh will be executed and renamed to /boot/firstboot.sh.done.

Quick Start B

  1. Download the latest image from the Releases tab. Note we currenlty only support the raspbian-lite image.
  2. Flash the downloaded image to your SD card. We recommend using Balena Etcher for writing images on all platforms. Folks have run into issues with the official Raspberry Pi Imager.
  3. Mount the /boot volume OF YOUR THE SD CARD YOU JUST FLASHED. This usually happens automatically if you "open" the SD card volume on Windows, MacOS, or Linux.
  4. NOTE: references below to /mnt will be /Volumes on macos and under "My Computer" on Windows.
  5. Create a /mnt/boot/firstboot.sh script with your custom contents examples here.
  6. Optionally add additional custom configuration files or small binaries to /mnt/boot (the /boot partiton is small - keep your total additions under ~160MB).
  7. Remember, you can also add a /mnt/boot/wpa_supplicant.conf file for wifi configuration.
  8. Unmount the /boot volume: umount /mnt on linux, diskutil unmount /Volumes/boot on macos, right-click for Windows.
  9. Boot your Pi... /boot/firstboot.sh will be executed and renamed to /boot/firstboot.sh.done.

What changes were made to the standard Raspbian-lite image?

  1. firstboot.service is installed in /lib/systemd/system/firstboot.service
  2. firstboot.service is enabled: cd /etc/systemd/system/multi-user.target.wants && ln -s /lib/systemd/system/firstboot.service .
  3. Nothing else!

How to reproduce this image yourself

Note: these are the steps used to produce the images in the Releases section of this repo. Once you have created a generic image with these steps, you can proceed to customize it by following the Quick Start.

  1. This requires modifying the second partition of the Raspbian image, which requires Linux for ext4 support.
  2. Source image is obtained from the official Raspberry Pi download page.
  3. Be sure to verify the SHA hash!
  4. Mount the second partition of the source image - the mount command will require an --offset flag, as described here.
    • Note: the mount_offset_tool helps calculate the --offset on linux.
    • Example usage (thanks @tgelite):
$ cd mount_offset_tool/
$ go run main.go /media/share/2021-01-11-raspios-buster-armhf-lite.img
/media/share/2021-01-11-raspios-buster-armhf-lite.img1 mount command:
  mount -v -o offset=4194304,loop /media/share/2021-01-11-raspios-buster-armhf-lite.img /mnt
/media/share/2021-01-11-raspios-buster-armhf-lite.img2 mount command:
  mount -v -o offset=272629760,loop /media/share/2021-01-11-raspios-buster-armhf-lite.img /mnt

 * Alternatively, you can mount it with `guestmount` (thanks @bastien-roucaries):

$ guestmount -v -a 2021-01-11-raspios-buster-armhf-lite-firstboot.img -m /dev/sda2 -m /dev/sda1:/boot /mnt
later, unmount with: $ guestunmount /mnt
  1. Install firstboot.service in /mnt/lib/systemd/system/firstboot.service
  2. Enable firstboot.service for systemd: cd /mnt/etc/systemd/system/multi-user.target.wants && ln -s /lib/systemd/system/firstboot.service .
  3. Unmount the second partition of the source image.
  4. Carefully test & validate the image before distributing!