How to setup a headless Raspberry Pi

Because remembering all the steps is hard.

Summary of steps

• Write a disk image to the SD card
• Add wifi credentials and enable ssh
• Change the Pi’s hostname and add ssh key(s)
• Reboot
• Verify passwordless authentication works
• Disable password authentication

Write a disk image to the SD card.

The Raspberry Pi Imager makes this super simple.

I normally choose either Raspberry Pi OS Lite (formerly Raspbian Lite) or Ubuntu Server.

Setup wifi and enable ssh

On the boot partition, there are two things to do.

To enable ssh, create a blank file called ssh :

$ cd /Volumes/boot # this path may vary
$ touch ssh

Assuming wifi is needed, wifi credentials need to go in a file called wpa_supplicant.conf .

$ vi wpa_supplicant.conf

This file needs to contain the following:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB
network={
 ssid="SSID"
 psk="PASSWORD"
}

Swap SSID and PASSWORD for your wifi credentials. You may also need to change the country code.

Once complete, insert the SD card in the Pi and boot it.

Hostnames and usernames

With Raspberry Pi OS, the default hostname is raspberrypi, the default username is pi, and the default password is raspberry.

With Ubuntu Server, the default hostname, username and password are all ubuntu .

For the first login (assuming Bonjour / Avahi is working), ssh username@hostname.local, and enter the default password when prompted.

$ ssh pi@raspberrypi.local
$ # or ssh ubuntu@ubuntu.local

Change the hostname and add ssh keys

To change the hostname, edit /etc/hostname and /etc/hosts. In each file, replace the default hostname with the new hostname.

$ sudo vi /etc/hostname
$ sudo vi /etc/hosts

To setup ssh keys, we need to make a ~/.ssh directory(if it doesn’t already exist). Restricting permissions isn’t a bad idea.

$ cd ~
$ mkdir .ssh
$ chmod 700 .ssh

Then add the local dev machine’s public key to the file ~/.ssh/authorized_keys .

If this doesn’t already exist then use scp from the local machine:

$ # make sure to run this on the local machine, not the pi
$ scp ~/.ssh/id_rsa.pub pi@raspberrypi.local:.ssh/authorized_keys
$ # alternatively, on the pi:
$ vi .ssh/authorized_keys # and paste the public key

Reboot

Now reboot the Pi:

$ sudo reboot now

The ssh connection will be dropped, and you’ll have to wait for the reboot. Once rebooted, we should be able to connect to the Pi using the new hostname, without the password.

Login again

$ ssh pi@newhostname.local

Make sure this works without a password before disabling password authentication.

Disable password authentication

After checking that ssh authentication works without using a password, we want to disable password authentication.

Now edit the ssh config

$ sudo vi /etc/ssh/sshd_config

The config needs this line:

PasswordAuthentication no

(Normally by default it has # PasswordAuthentication yes before editing)

Now restart sshd:

sudo systemctl restart sshd.service

We can verify that this works as expected by logging out and logging in again (or if we want to be extra careful staying logged in and trying to login in a new ssh session).

Ready to go

Once password authentication has been enabled, we should notice a warning message about ssh is no longer shown on login.

We probably want to install updates next:

$ sudo apt update && sudo apt upgrade

And then start hacking 🧑‍💻