The following instructions are for macOS. Consult the official Raspberry Pi installation guide for Linux and Windows instructions.
- Download the latest Raspbian Lite image.
- Insert the SD card. Don’t worry about formatting it with Disk Utility.
wget https://downloads.raspberrypi.org/raspbian_lite_latest -O raspbian.zip unzip raspbian.zip # The ZIP file contains an image file. if="2018-11-13-raspbian-stretch-lite.img"
diskutil list # Pick the disk that we want to use as the output file with dd (see below). of="/dev/rdisk2" # 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"
- Download NOOBS.
- Extract and copy to a FAT32 formatted SD card.
- When booting the Pi, keep the Ethernet disconnected until the install completes.
- Enable VNC with
- Edit the boot configuration for desired VNC resolution.
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
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
sudo apt-get autoremove sudo apt-get autoclean
It doesn’t hurt to reboot after applying updates.
Optionally, update the firmware and kernel modules.
sudo rpi-update sudo reboot
Here’s how to check the kernel version.
Enable automatic updates
Automatic updates are an essential part of Linux security. The preferred method on Debian is to use
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
Get a free subdomain at FreeDNS. Copy their update key and set a
cron entry to run hourly.
Use the “Direct URL” method.
0 * * * * curl http://freedns.afraid.org/dynamic/update.php?KEY >> ~/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 https://install.pi-hole.net | bash
We recommend using the CloudFlare 18.104.22.168 service for DNS, rather than Google 22.214.171.124.
Set it to update automatically, every Sunday at 4 AM, for example.
0 4 * * 0 pihole -up >> ~/pihole.log 2>&1
Note: We recommend 126.96.36.199 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 https://install.pivpn.io | 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
pivpn add to add user profiles. Create user profilers per computer.
Profiles get saved to
You can get a list of profile with
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=127.0.0.1, XXX, 10.8.0.1. Note here that
10.8.0.1 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.