I set up most of my Raspberry Pis headless. They go into a weatherproof box, up a pole or behind a cupboard, and I never want to plug a screen into one. Raspberry Pi Imager lets you set a username, Wi-Fi details and “Enable SSH” before it writes the card. In theory, the Pi comes up on the network on first boot and you just ssh in.
In practice, I’ve lost count of how often that hasn’t happened. The Pi boots, gets an IP address, and refuses SSH connections. The only fix then has been to dig out a micro-HDMI cable.
This post covers how to check the card before it goes in the Pi, and what to do when Imager hasn’t done its job.
What changed: cloud-init#
Raspberry Pi OS based on Debian Trixie has replaced the old first-boot mechanism with cloud-init.
| Bookworm and earlier | Trixie onwards | |
|---|---|---|
| First-boot mechanism | firstrun.sh script | cloud-init |
| Hook | systemd.run=/boot/firstrun.sh in cmdline.txt | cloud-init service reads files from the boot partition |
Config files on bootfs | firstrun.sh | user-data, meta-data, network-config |
| Written by | Imager 1.x | Imager 2.x |
Either way, everything lives as plain text on the FAT32 boot partition (bootfs). Any PC can read it, so you can check it after flashing and before ejecting the card.
Step 1: Re-mount the card and look#
Imager ejects the card when it finishes writing, so pull it out and push it back in. On Linux it mounts at /media/$USER/bootfs. On macOS it’s /Volumes/bootfs.
cd /media/$USER/bootfs
# Show the active lines of user-data (drops blank lines and "# " comments,
# but keeps the #cloud-config header)
grep -Ev '^\s*$|^\s*# ' user-data
# Any sign of the older firstrun mechanism?
ls firstrun.sh
grep -o 'systemd.run=[^ ]*' cmdline.txt
# cloud-init needs a hyphenated instance-id
cat meta-dataStep 2: Read the result#
A customised card should have a user-data that looks something like this (hash shortened):
#cloud-config
hostname: mypi
manage_etc_hosts: true
users:
- name: pi-admin
groups: users,adm,sudo,...
shell: /bin/bash
lock_passwd: false
passwd: $6$...
enable_ssh: true
ssh_pwauth: trueThe line that matters is enable_ssh: true. It’s a Raspberry Pi OS–specific extension, not available on generic cloud-init images, and it turns on sshd at first boot.
What I actually found, on a card freshly written with “Enable SSH” ticked:
$ grep -Ev '^\s*$|^\s*# ' user-data
#cloud-config
$ ls firstrun.sh
ls: cannot access 'firstrun.sh': No such file or directory
$ grep -o 'systemd.run=[^ ]*' cmdline.txt
$The template user-data that ships with the image is entirely commented out, and there’s no firstrun.sh either. Imager hadn’t applied any of the customisation: no user, no hostname, no Wi-Fi, no SSH. That card would have booted to a Pi with no user and no way in.
Here’s how to read each pattern:
| What you see | What it means |
|---|---|
enable_ssh: true plus your users: block | Customisation applied. You should be fine. |
Your user and hostname, but no enable_ssh | Partly applied. Add the SSH lines yourself. |
Only #cloud-config, no firstrun.sh | Not applied at all. Write the config by hand (below). |
firstrun.sh present and called from cmdline.txt | Older mechanism. Check with grep -i ssh firstrun.sh. |
Step 3: Write the config by hand#
This turns out to be quicker than going back through Imager, and you know exactly what’s on the card.
user-data#
cat > user-data <<'EOF'
#cloud-config
hostname: mypi
manage_etc_hosts: true
users:
- name: pi-admin
groups: users,adm,dialout,audio,netdev,video,plugdev,input,gpio,spi,i2c,render,sudo
shell: /bin/bash
sudo: ALL=(ALL) NOPASSWD:ALL
lock_passwd: true
ssh_authorized_keys:
- ssh-ed25519 AAAA...your-public-key... you@desktop
enable_ssh: true
ssh_pwauth: false
EOFA few things to watch:
#cloud-configmust be the first line. Without it, cloud-init ignores the file.- Only have one
users:key. If Imager partly customised the card, addenable_sshandssh_pwauthto its block, because a secondusers:key overwrites the first. - I prefer key-only login (
lock_passwd: true,ssh_pwauth: false). If you want a password instead, generate a hash withopenssl passwd -6, addpasswd: '<hash>'under the user, and setlock_passwd: falseandssh_pwauth: true.
meta-data#
printf 'instance-id: mypi-001\n' > meta-dataThis is a sneaky one. cloud-init uses instance-id to decide whether this is a first boot. If the key is wrong (for example instance_id with an underscore), it can treat every boot as already configured and skip your user-data entirely. The SSH server then comes up, but your password is never accepted, because the user was never created.
network-config (Wi-Fi only)#
Wired Ethernet uses DHCP by default, so skip this if you’re on a cable.
cat > network-config <<'EOF'
network:
version: 2
wifis:
renderer: NetworkManager
wlan0:
dhcp4: true
regulatory-domain: GB
access-points:
"YourSSID":
password: "YourPassphrase"
optional: true
EOFBelt and braces: the ssh file#
The old trick still works: an empty file called ssh on the boot partition enables sshd on boot, whatever happened to the rest of the config.
touch sshOn its own it isn’t enough any more, because there’s no default pi/raspberry user. SSH would be up, with nobody to log in as. Combined with the user-data above, though, it’s a cheap safety net.
Eject#
sync
cd ~
umount /media/$USER/bootfs /media/$USER/rootfs 2>/dev/nullStep 4: First boot#
The first boot takes a minute or two longer than usual while cloud-init does its work. Then:
ssh pi-admin@mypi.localIf mDNS doesn’t find it, get the IP address from your router’s DHCP leases. Once you’re in, confirm everything applied cleanly:
cloud-init status --long
sudo cat /var/log/cloud-init-output.logTroubleshooting at a glance#
| Symptom | Likely cause |
|---|---|
Connection refused | sshd not running: no enable_ssh and no ssh file |
| Password prompt, but every password is rejected | sshd is up but the user was never created. Check meta-data and user-data. |
| No response at all | Not on the network. Check network-config and the Wi-Fi country. |
Why does Imager skip it?#
I haven’t pinned it down for certain, but there are two common causes. One is answering “No” at the “Would you like to apply OS customisation settings?” prompt. The other is using an older Imager (1.x) with a Trixie image, where the old firstrun.sh approach no longer applies. rpi-imager --version will tell you which version you’ve got.
Either way, the lesson for me is to always re-mount and check bootfs before the card goes into the Pi. It takes thirty seconds and saves hunting for a micro-HDMI cable.
