Tutorial: How to setup SSH and WiFi on a Raspberry Pi without a screen (headless)

Raspberry Pis are great hobbyist computers. They’re fairly cheap and provide a friendly introduction to Linux. People use Pis for teaching computer science, developing robotics, as routers, cameras, media servers, and many other applications. In this tutorial I’m going to cover how to setup a Raspbery Pi when you don’t have access to a display. I’ll cover preparing your MicroSD card — including how to install Raspbian, enable SSH, and configure WiFi. Finally I’ll walk through how to secure your Pi from unauthorized users.

Setup

You can follow along with any Raspberry Pi (as of the date I published this article). For this tutorial I used the Raspberry Pi Zero W starter kit sold by CanaKit on Amazon. The kit included the Raspberry Pi Zero W, official Raspberry Pi Zero Case with 3 interchangeable lids, 8 GB MicroSD card (Class 10), power supply, USB adapter, and mini HDMI adapter. The total cost was about $30.

If you haven’t bought a Pi before then I recommend getting a “starter” kit. You don’t need to buy a kit, but generally between the cost of the board, micro SD card, and power supply you might as well just buy the kit. Plus it can be difficult to find a seller that offers just the board.

In addition to the kit I already owned a MicroSD to SD card adapter which I used to mount the MicroSD on my Mac (you’ll need some way of mounting the MicroSD card on your computer).

Install Raspbian on the MicroSD

Raspbian is a Debian-based operating system and officially supported by the Raspberry Pi Foundation. It optimized for the Raspberry Pi ARM processor and has a number of standard software packages such as Java and Python.

The MicroSD card included in my kit came with New Out Of Box Software (NOOBS) pre-installed. If you have access to a display and USB keyboard you could just pop the MicroSD into your Pi and follow the on-screen instructions. However this tutorial is all about how to setup your Pi without an extra display or keyboard handy (i.e. headless).

To prepare the MicroSD I used Etcher, a simple and easy to use SD card burning app, to install Raspbian on the MicroSD directly. Download and install Etcher on your computer and then download the latest image for the Raspbian operating system.

Mount the MicroSD card on your computer (I used my MicroSD to SD card adapter). Then launch Etcher and select the Raspbian image you downloaded, the MicroSD card, and hit “Flash!”. Once it’s finished, don’t eject the drive! We’re not done yet.

Enable SSH

SSH is disabled by default on Raspbian but if you’re running your Pi without a display you’ll almost certainly want it to be enabled. Fortunately all you need to do is create an empty file called ssh in the root directory of the drive.

touch /Volumes/BOOT/ssh

When the Pi boots it’ll see this file and enable SSH.

Generate a new SSH key

Later we’re going to disable password login on the Pi, so now is a good time to create a new SSH key.

ssh-add -t rsa -b 4096 -C "your.email@example.com"

Then add the following to your ~/.ssh/config file:

Host pi
    HostName raspberrypi.local
    AddKeysToAgent yes
    UseKeychain yes
    User pi
    PreferredAuthentications publickey
    IdentityFile /Users/evalentiner/.ssh/id_rsa

This file stores your SSH connection settings for your Raspberry Pi so that you don’t need to type as many characters every time (e.g. ssh pi instead of ssh -i ~/.ssh/id_rsa pi@raspberrypi.local).

Setup WiFi

Next is to setup your Pi so that it will join your WiFi network — otherwise you’ll have no way to SSH into it.

Create a new file in the root directory called wpa_supplicant.conf. This file will be copied to the /etc/wpa_supplicant/ directory.

Add the following lines to your file:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=US

Note that if you’re outside of the US you should change country=US to the appropriate ISO Alpha-2 code.

Then add at least one network using the following format:

# First wifi network
network={
    ssid="Home Wireless"
    psk="password"
}
# Second wifi network
network={
    ssid="Home Wireless 5GHz"
    psk="password"
}

As you can see you can add multiple networks. I recommend to just add one network because the password is in plain-text. We’ll encrpyt this later once we’ve confirmed the Pi can join the network at which point you can add additional networks with encrpyted PSKs.

Securing the Pi

Finally you can eject the MicroSD, insert it into your Pi, and plug it into the power supply. The Pi will boot automatically in a few seconds.

Connect to your Pi over SSH using the default username (pi) and password (raspberry):

ssh pi@raspberrypi.local

Then immediately change the default password using the passwd command. Note that password login is still enabled (but we’ll disable it in just a moment).

Create the file /home/pi/.ssh/authorized_keys. Then copy your SSH public key (generated above) and add it to this file. You can actually do this in a single step using scp. Assuming your SSH key is named id_rsa:

scp ~/.ssh/id_rsa.pub pi@raspberrypi.local:/home/pi/.ssh/authorized_keys

This works because you shouldn’t have any other authorized keys on your Pi yet.

Now disable password login by editing /etc/ssh/sshd_config and changing the line with #PasswordAuthentication yes to PasswordAuthentication no. Then restart your SSH service using sudo service ssh restart.

The last step is to remove the plain-text password from your wpa_supplicant.conf file. To do this just run the wpa_passphrase utility and it’ll spit out an encrypted PSK.

wpa_passphrase ssid password
# network={
# 	ssid="ssid"
# 	#psk="password"
# 	psk=44116ea881531996d8a23af58b376d70f196057429c258f529577a26e727ec1b
# }

Replace the relevant networks lines in your wpa_supplicant.conf file (remember you’ll need to use sudo to edit this file). You can use the wpa_passphrase utility to generate encrpyted PSKs for additional networks and add them to your wpa_supplicant.conf file if you want your Pi to be able to connect to multiple networks.

Wrapping up

At this point your Raspberry Pi should be good to go! The easiest way to test this is by restarting the Pi and checking that you can reconnect. You can do this by running sudo shutdown -r 1 (restart in 1 minute) and then disconnecting from your Pi. After a minute or so your Pi should be restarted and you should be able to connect by using ssh pi. You should also test that you can’t connect over SSH using password authentication; you can test this using:

ssh -o PreferredAuthentications=password \
    -o PubkeyAuthentication=no pi@raspberrypi.local

Now your Raspberry Pi is on your WiFi network and accessible via SSH!