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

1. Download the latest image from the Releases tab. Note we currenlty only support the raspbian-lite image.
2. Mount the /boot volume on Windows, MacOS, or Linux (usually this happens automatically if you "open" the image).
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.
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

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.
5. Install firstboot.service in /mnt/lib/systemd/system/firstboot.service
6. Enable firstboot.service for systemd: cd /mnt/etc/systemd/system/multi-user.target.wants && ln -s /lib/systemd/system/firstboot.service .
7. Unmount the second partition of the source image.
8. Carefully test & validate the image before distributing!