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)
- 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
$ cd /Volumes/boot # this path may vary
$ touch ssh
Assuming wifi is needed, wifi credentials need to go in a file called
$ vi wpa_supplicant.conf
This file needs to contain the following:
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
With Ubuntu Server, the default hostname, username and password are all
For the first login (assuming Bonjour / Avahi is working),
ssh firstname.lastname@example.org, and enter the default password when prompted.
$ ssh email@example.com
$ # or ssh firstname.lastname@example.org
Change the hostname and add ssh keys
To change the hostname, edit
/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
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 email@example.com:.ssh/authorized_keys
$ # alternatively, on the pi:
$ vi .ssh/authorized_keys # and paste the public key
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.
$ ssh firstname.lastname@example.org
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:
(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 🧑💻