Install a Raspberry Pi device

How to get a Pi up and running in less than 15 minutes.

Install Raspbian

Headless setup

The following instructions are for macOS. Consult the official Raspberry Pi installation guide for Linux and Windows instructions.

wget -O
# The ZIP file contains an image file.
diskutil list

# Pick the disk that we want to use as the output file with dd (see below).

# Unmount the target disk.
diskutil unmountDisk "$of"

# Requires sudo (admin) to format the disk.
sudo dd bs=1m if="$if" of="$of" conv=sync

Before removing the SD card, we need to enable ssh support, which is disabled by default. To enable remote access, you must write an empty file named ssh to the boot partition.

cd /Volumes/boot
sudo touch ssh
cd ~

Now we’re ready to eject the disk and boot up the Raspberry Pi device.

sudo diskutil eject "$of"

Monitor-enabled setup

Initial configuration

Give it a couple of minutes the first time it boots.

The default admin account is pi, with the password raspberry. Be sure to change this.

sudo raspi-config
# Select "Change User Password" (1)

Command line alternative:



First, ensure your Raspbian configuration is current.

sudo raspi-config
# Select "Update" (8)

Use apt-get to upgrade your installation. Note that dist-upgrade is recommended instead of upgrade for Raspbian, according to the official documentation.

sudo apt-get update
# Use `dist-upgrade` instead of `upgrade`.
sudo apt-get dist-upgrade

If you start to run out of disk space, run this to clean up apt:

sudo apt-get clean

Verify that nothing went wrong.

dpkg -C
apt-mark showhold

To clean up and remove old packages, use autoremove, but inspect each package manually, rather than running automatically with the -y flag.

sudo apt-get autoremove
sudo apt-get autoclean

It doesn’t hurt to reboot after applying updates.

sudo reboot

Optionally, update the firmware and kernel modules.

sudo rpi-update
sudo reboot

Here’s how to check the kernel version.

uname -a

Enable automatic updates

Automatic updates are an essential part of Linux security. The preferred method on Debian is to use unattended-upgrades.

sudo apt-get install unattended-upgrades apt-listchanges
sudo dpkg-reconfigure -plow unattended-upgrades

Alternatively, you can use the root crontab method.

sudo su
crontab -e
0 0 * * 0 apt-get update && sudo apt-get upgrade -y

SSH key-based authentication

Key pairs are two cryptographically secure keys. One is private, and one is public. Refer to the Securing your Raspberry Pi guide for more information.

mkdir ~/.ssh
cd ~/.ssh
nano authorized_keys
# Paste your public key

Once you can log into the Pi using only SSH keys, it’s recommended to disable password-based authentication.

sudo nano /etc/ssh/sshd_config

There are three lines that need to be changed to no, if they are not set that way already:

PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no

Save the file and either restart the ssh system with sudo service ssh reload or reboot.

Dynamic DNS

Get a free subdomain at FreeDNS. Copy their update key and set a cron entry to run hourly.

crontab -e

Use the “Direct URL” method.

0 * * * * curl >> ~/freedns.log 2>&1


Fail2ban, written in Python, is a scanner that examines the log files produced by the Raspberry Pi, and checks them for suspicious activity. It catches things like multiple brute-force attempts to log in, and can inform any installed firewall to stop further login attempts from suspicious IP addresses.

If you’re exposing port 22 for SSH, it’s recommended to install fail2ban. If you’re simply using OpenVPN via PiVPN, then fail2ban isn’t required.

sudo apt-get install fail2ban


Load the default configuration with the setup script.

curl -sSL | bash

We recommend using the CloudFlare service for DNS, rather than Google

Set it to update automatically, every Sunday at 4 AM, for example.

crontab -e
0 4 * * 0 pihole -up >> ~/pihole.log 2>&1

Note: We recommend DNS on the router and enabling Pi-Hole ad-blocking per device, rather than using Pi-Hole DNS directly on the router. This software can cause issues with some devices and it can make re-configuration of a fresh Raspberry Pi device install cumbersome.


Load the default configuration with the setup script.

curl -L | bash

If not already enabled, PiVPN will suggest that you turn on automatic updates.

Use port 1194 over UDP instead of TCP. UDP is faster for tunneling. Ensure that UDP port forwarding is used in the router configuration.

Opt to enable OpenVPN 2.4.

Use 256-bit encryption.

Since we’ve enabled dynamic DNS, we can choose a public DNS name instead of using an IP address for the VPN.

Select CloudFlare as the DNS provider.

The install log gets saved to /etc/pivpn.

Run pivpn add to add user profiles. Create user profilers per computer.

Profiles get saved to /home/pi/ovpns.

You can get a list of profile with pivpn list.

Pi-Hole and PiVPN can be installed together. The setup process is easier if you install Pi-Hole first then PiVPN. After both are installed, edit the /etc/dnsmasq.conf file to allow DNS resolution from the VPN interface: listen-address=, XXX, Note here that is the address for Pi-Hole.

If PiVPN isn’t working with the OpenVPN client, check to make sure that dynamic DNS is working, using ping to the VPN domain/IP address. This can look like a problem with frequent disconnect and reconnect attempts in the Tunnelblick client, for example.