A Step-By-Step Guide
Deep Dive: Boot Your Raspberry Pi Headless On Linux
You Won’t Get Far Without a Successful Setup
Big surprise: The most important resource to start with a Raspberry Pi is, of course, the Pi itself. Unfortunately, it needs more requirements for a working setup. But great news — an extra monitor and keyboard are not one of them, as one convenient feature of the tiny computer is the capability of a headless boot.
My guide explains how you easily set up your Pi and enable WIFI. To follow the terminal commands, it’s better if you work on a Linux OS.
Besides listing the plain instructions, I dive into every configuration in a beginner-friendly way. If you understand what you are doing, you can help yourself better whether something goes wrong. Then even with the best guide — problems always occur.
Sounds good? I think so too.
So let’s get started.
If you are just interested in a short summary, jump to the end.
Requirements
- Raspberry Pi
- Raspberry Pi Power Supply
- MicroSD card with Raspberry Pi OS installed (How-To video)
I used a Raspberry Pi Zero W and Raspberry Pi OS Lite, but my guide should work for all newer models and all Raspberry Pi OS.
For the OS, I recommend the Pi OS Lite because the standard one offers additional features you don’t need for a headless setup (like a desktop environment).
Necessary to Connect at All: SSH
SSH is your best mate if you want to work headless with your Pi.
SSH stands for Secure Shell and is a network protocol allowing remote access and secure connections to other devices. It’s usually enabled on Port 22.
Via SSH, we can connect to our Pi from our actual PC — it’s like having a terminal open on the Pi but the terminal is displayed on our monitor. So you can execute commands as if you were working on the Pi itself. All we need is the IP of the device to which we want to connect, a user, and a password.
To enable the SSH service, you need to create a file called ‘ssh’ in the boot folder of your SD card. To do so, navigate to the boot partition of your SD card (/boot) and run the following command:
$ touch ssh
Remove the file extension if you created the file via file manager!
If your file has an extension, it won’t work since the SSH script of the Pi OS looks for a file called ‘ssh’. Just this way, SSH is enabled, and the file is removed—no other way.
The One to Connect To: A User
For security reasons, the developers disabled the default user on Pis. Luckily, creating one ourselves is easy.
To do so, we create a file called ‘userconf.txt’ that contains a username and an encrypted password in the format YoUrUsErNaMe:YoUrPaSsWoRd.
Go again into the boot partition of your SD card and create the file with the following command (replace placeholders):
$ echo "YoUrUsErNaMe:$(echo 'YoUrPaSsPhRaSe' | openssl passwd -6 -stdin)" > userconf.txt
The following short table explains the commands:
If you open ‘userconf.txt’, you will see your username and your encrypted password separated by a colon. Thanks to Linux for getting this done with a one-line command!
For a deeper insight into the magic of employed command, click here.
Last but Not Least: Configure WiFi
The last file we need to create is ‘wpa_supplicant.conf’ — the file where we must specify the most.
A supplicant is a hard- or software application that requests authentication from an access point (like a Server or Router) to establish a secure connection to a network.
In our case, the wpa_supplicant is a software supplicant which submits the content of the file ‘wpa_supplicant.conf’ to the router when the Pi boots. To the contents belong, among others, the wifi name and password. Finally, the router authenticates the credentials and, if correct, grants the Raspberry Pi access to our local area network.
So, let’s create the file (again in the boot partition) by opening an editor. I choose vim to do so:
$ vim wpa_supplicant.conf
Then input the following content on the opening screen:
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=DE
network={
ssid="YoUrWiFiNaMe"
psk="YoUrWiFiPaSsWoRd"
key_mgmt=WPA-PSK
}
Let’s look at the content in more detail:
For more information on wpa_supplicant and the network settings, check the official raspberry documentation and wpa_supplicant.conf.examples under /usr/share/doc/wpa_supplicant in your Linux.
Tatataa, that’s all we need for setup!
Checking WiFi and Connecting Via SSH
After creating the 3 files in the boot partition of your SD card, plug the card into your Pi, and let’s see if the Pi connects to your WIFI.
Give the Pi some seconds to boot. Afterward, we scan our network to see if everything works out as expected. For scanning, we use a powerful toolkit named nmap. Nmap offers tons of different network scans, and we will use the ping scan to get a list of all devices in the network.
But first of all, you need to know your IP address because nmap needs the subnet range it is supposed to scan. Type in the following command to get your IP (just the first is relevant):
$ hostname -I
The subnet you belong to is YoUrIp/24. For example, if your IP is 192.168.10.7, you belong to the subnet 192.168.10.0/24. All other devices in your WIFI have an IP between 192.168.10.0 and 192.168.10.255. If nothing goes wrong, your Pi’s IP will be there too.
Run nmap with the following command (replace your IP):
$ sudo nmap -sn YoUrIp/24
If everything works out, you detect your Pi in the list of found hosts.
Woohoo!
Now, log in to your Pi with SSH (replace username and IP):
$ ssh YoUrUsErNaMe@IPofPi
Submit your password when prompted and start exploring fancy projects!
You find more information on remote access in the official documentation.
Summary for Busy People
In /boot of your SD card, create the following 3 files:
1. ssh
It’s an empty file with no file extension.
2. userconf.txt
It contains your username and encrypted password in the format ‘YoUrUsErNaMe:YoUrPaSsPhRaSe’. Encryption is possible with the command:
echo ‘YoUrPaSsPhRaSe’ | openssl passwd -6 -stdin
3. wpa_supplicant.conf
Place this in wpa_supplicant.conf:
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=DE
network={
ssid="YoUrWiFiNaMe"
psk="YoUrWiFiPaSsWoRd"
key_mgmt=WPA-PSK
}
Then, plug your SD card into your Pi, wait about 1 minute, and scan the network for your Pi.
Get your IP with hostname -I.
Scan your network with nmap -sn YOURIP/24.
If your Pi is listed, log in via SSH with YoUrUsErNaMe@IPofPi.
Conclusion
As you see, a headless setup for the Pi is not tricky. Still, you can encounter a lot of problems. And without a monitor, debugging is like diving into the blue.
Don’t give up if it’s not working the first time; it didn’t work out for me in the beginning too. I placed the files in the wrong boot folder (in /rootfs/boot/ …… aaargh ….. ) and needed at least an hour to solve my mistake. But I did it — and so will you. Sooner or later.
I hope my explanations provide a good base for debugging and help you to understand the purpose behind every necessary instruction.
Looking for an easy task to get familiar with the Pis pins and their basic coding? Learn how to blink a LED in my tutorial.
Or are you already interested in more advanced projects? Check how to build your own simple automatic plant watering system.