↓ Skip to main content
  1. Blog/

Headless Pi: checking SSH is actually enabled before first boot

·1035 words·5 mins
Chris Ramsay
Author
Chris Ramsay
Ultra and mountain runner, maker and amateur astronomer

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 earlierTrixie onwards
First-boot mechanismfirstrun.sh scriptcloud-init
Hooksystemd.run=/boot/firstrun.sh in cmdline.txtcloud-init service reads files from the boot partition
Config files on bootfsfirstrun.shuser-data, meta-data, network-config
Written byImager 1.xImager 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-data

Step 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: true

The 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 seeWhat it means
enable_ssh: true plus your users: blockCustomisation applied. You should be fine.
Your user and hostname, but no enable_sshPartly applied. Add the SSH lines yourself.
Only #cloud-config, no firstrun.shNot applied at all. Write the config by hand (below).
firstrun.sh present and called from cmdline.txtOlder 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
EOF

A few things to watch:

  • #cloud-config must be the first line. Without it, cloud-init ignores the file.
  • Only have one users: key. If Imager partly customised the card, add enable_ssh and ssh_pwauth to its block, because a second users: key overwrites the first.
  • I prefer key-only login (lock_passwd: true, ssh_pwauth: false). If you want a password instead, generate a hash with openssl passwd -6, add passwd: '<hash>' under the user, and set lock_passwd: false and ssh_pwauth: true.

meta-data
#

printf 'instance-id: mypi-001\n' > meta-data

This 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
EOF

Belt 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 ssh

On 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/null

Step 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.local

If 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.log

Troubleshooting at a glance
#

SymptomLikely cause
Connection refusedsshd not running: no enable_ssh and no ssh file
Password prompt, but every password is rejectedsshd is up but the user was never created. Check meta-data and user-data.
No response at allNot 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.

Related