The Ultimate RPi Installation Guide

Raspberry Pi installation

Setting up SD Card

1. Download an OS image file

For example:

• MINIBIAN: http://minibianpi.wordpress.com/download/
• RASPBIAN: https://www.raspberrypi.org/software/operating-systems/

2. Put image on SD Card

Unzip the downloaded OS.

Stick SD Card in (duh)

mac

• First open terminal
• Find the disk that you are going to write to

diskutil list

!!! Be careful that you find the right disk, you can overwrite the harddrive of your computer easily when you pick the wrong one !!! To make it easier, and to avoid wiping external drives, make sure you have nothing else plugged in aside from your SD Card.

• Find the disk name that reads something like /dev/disk<number> that doesn't have a partition on it named something like Macintosh HD. For example /dev/disk2
• You need to unmount the SD Card before imaging (replace <number> with the disk number found in the first step)

sudo diskutil unmountDisk /dev/disk<number>

• Then to image the disk with your image put in the following command (replace the minibian.img with the full path to your downloaded image file, and the <number> with the disk number that you found in the 1st step)

sudo dd bs=4m if=minibian.img of=/dev/rdisk<number>

linux

• Find the disk that you are going to write to, find its path, for example /dev/sdb/

You can do this using software like gparted or Disks (on Gnome), or use the command line tools df.

df -h

!!! Be careful that you find the right disk, you can overwrite the harddrive of your computer easily when you pick the wrong one !!! To make it easier, and to avoid wiping external drives, make sure you have nothing else plugged in aside from your SD Card.

• Unmount this disk

umount /dev/path/to/disk

• Write the image to the disk

sudo dd bs=4M if=minibian.img of=/dev/sdc status=progress

3. Insert SD

4. Power the RPi, wait for crazy blinking to stop

Connecting to the Pi

Connect to the Pi using the default login details:

The default MINIBIAN login user is root and the passwd is raspberry.
Or for RASPBIAN the default login is pi with password raspberry.

With a screen + keyboard + mouse

To connect to the Pi, you can attach a screen + keyboard + mouse, so you can go through the setup process step by step.
Connect the screen before you start the pi.

Also connect the Pi to an ethernet cable, that will allow you to install new software.

Using SSH

(Connecting to the Pi through the terminal)

Enable SSH on the Pi

You can do this in two ways:

With a screen + keyboard

• Connect the Pi to a screen and keyboard.
• Run: sudo raspi-config
• Select Interfacing Options
• Navigate to and select SSH
• Choose Yes
• Select Ok
• Choose Finish

or

Before putting the SD in the Pi

Mac

• cd /Volumes/boot/
• touch ssh

Linux

• cd /media/USERNAME/boot
• touch ssh

Done!

• put the SD card back in the Pi and boot it up

Read more here: https://www.raspberrypi.org/documentation/remote-access/ssh/

Connect the Pi to your local network

To connect to the Pi with SSH, you will need to connect it to a network.
It will not connect by automatically to any Wifi network by default.
You will need to connect it to a router, or other network with an ethernet cable first.

Figure out what's the IP of the Pi

You can do that using ifconfig (while being logged into the Pi using a screen + keyboard) or nmap (from your own computer).

ifconfig

nmap -sP 192.168.1.1-255

For Mac users: you will need to install nmap manually from here. Easiest installation method is with the OSX Binaries.

Use SSH to login into the Pi

You can login using the ip address of the pi, or using the hostname of the machine.

ssh root@192.168.1.73
ssh pi@192.168.2.15
ssh pi@raspberrypi.local

With an ethernet cable

You can alternatively connect it directly to your personal machine via an ethernet cable - steps to do that can be found here.

Change the hostname

The hostname is the name of the Pi.

Change the hostname

You can change this name, by editing these two files:

sudo nano /etc/hostname
sudo nano /etc/hosts

Change /etc/hosts into:

127.0.0.1       localhost
::1             localhost ip6-localhost ip6-loopback
ff02::1         ip6-allnodes
ff02::2         ip6-allrouters

127.0.1.1       newhostname

Reboot the Pi after you made these changes!

Reach your Pi using its hostname

You can use the hostname to ssh into the Pi, if you are in the same local network as your Pi:

ssh username@hostname.local

You can use this hostname also in the browser, to access the webserver on the Pi. Try to visit:

hostname.local
hostname.lan

THIS IS IT!

Well done, you now have a Pi installation, the guideline stops here, anything past this point is just a matter of what the Pi will be used for.

Extras

All the following steps are optional and depend on the use of the RPi.

Make user accounts and file permissions

The Pi is installed now what do we do?

Use your Pi as a wireless hotspot

If you want to just install an hotspot: follow this guide: https://www.raspberrypi.com/documentation/computers/configuration.html#setting-up-a-routed-wireless-access-point and if you want it just local skip the "masquerdate" section.

rtl8812BU antenna drivers installation

Update rpi's kernel

sudo apt-get update && sudo apt-get install --reinstall raspberrypi-bootloader raspberrypi-kernel
sudo apt-get install raspberrypi-kernel-headers
sudo apt-get install -y bc build-essential dkms git

Install driver for antenna

Follow this https://github.com/morrownr/88x2bu-20210702#user-content-installation-steps

After the driver installation, change settings of the driver (https://github.com/morrownr/88x2bu#user-content-driver-options)

sudo ./edit-options.sh

in the first lines, change the value:

rtw_vht_enable = 2
rtw_power_mgnt=0

then

sudo reboot

check if the antenna is installed

iwconfig

It should appear “wlan1” and characteristics of the antenna

Disable the inner wireless interface

sudo nano /boot/config.txt

Paste:

dtoverlay=disable-wifi

Check if the antenna is the only interface:

iwconfig

Now again

sudo reboot

and configure in "master mode" the antenna

sudo iwconfig wlan0 mode master

Create the access point

follow: https://www.raspberrypi.com/documentation/computers/configuration.html#setting-up-a-routed-wireless-access-point

With these setting in hostapd.conf:

interface=wlan0
ssid=NAMEYOUCHOOSEN
driver=nl80211
hw_mode=a
channel=44
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wmm_enabled=1

To debug:

sudo /usr/sbin/hostapd /etc/hostapd/hostapd.conf

But after:

sudo systemctl enable hostapd

WebServer

If the hotspot works, install a webserver(nginx) and its fancy version: Install NGINX Fancyindex

Expand filesystem (optional)

This is optional. Indeed, depending on the application, the little room left on the minibian image might be just enough to add a couple software and config files. However, it is necessary if the kernel needs to be updated, as the process needs a bit more space than what we have by default. Also, you can repeat the process again at later stage if you need more space than the suggested 2GB total size in the example below. Just make sure you do not exceed the size of your medium/sdcard.

• install parted utility

apt update
apt install parted

• check that, indeed, it's a bit tight in there. The following command will show that the main system partition (partition 2 formatted as ext4) is roughly 700-800MB:

parted /dev/mmcblk0 --script print

• run the same command with unit s, to get more precise information (sectors)

parted /dev/mmcblk0 --script unit s print

• Note down the Start value of the partition Number 2. Here is an example:

 Number  Start     End       Size      Type     File system  Flags
  1      16s       125055s   125040s   primary  fat16
  2      125056s   1626111s  1501056s  primary  ext4

The value to remember in this example would be 125056s.

• Delete partition 2, you will get an error and complaining about the need to reboot, IGNORE THIS

parted /dev/mmcblk0 --script rm 2

• Double check that partition 2 is gone:

parted /dev/mmcblk0 --script print

• Create a new partition that starts exactly at the point 125056s but goes until 2GB. Adjust the command with your own value. Ignore the warning for now.

parted /dev/mmcblk0 --script mkpart primary 125056s 2GiB

• Check that new partition has been created

parted /dev/mmcblk0 --script print

• Reboot to make the system aware of the changes

reboot

• ssh back in and finally resize the filesystem to benefit from the expanded partition

resize2fs /dev/mmcblk0p2

Base system

• flavouring

echo "BMO" > /etc/hostname
hostname -F /etc/hostname

• don't bloat the system

echo -e 'APT::Install-Recommends "0";\nAPT::Install-Suggests "0";' > /etc/apt/apt.conf.d/90norecommend

• update system

apt update
apt upgrade

• DO NOT REBOOT YET At time of writing the upgrade makes kernel.img disappears from /boot, resulting in an unbootable RPi3
• update to latest kernel

apt install rpi-update
rpi-update
reboot

• Support for several terminals (needed when sshing from X using non-xterm terminals like urxvt)

apt install ncurses-term

• what time is it

dpkg-reconfigure tzdata

Comfy environment (optional)

Now you can install all your comfy l33t command line tools and whatnot, fav editors, etc. This is just an example of what I (aymeric) always put on top of my pi, YMMV:

• comfy tools and stuff

ln -s /usr/bin/vim.tiny /usr/bin/vim
apt install tmux tcsh git
chsh -s /bin/tcsh root

• create /root/.tcshrc

if ($?prompt) then
      set prompt = "%N@%m:%~ %# "
      set promptchars = "%#"
      set filec
      set history = 1000
      set savehist = (1000 merge)
      set autolist = ambiguous
      set autoexpand
      set autorehash
      if ( $?tcsh ) then
              bindkey "^W" backward-delete-word
              bindkey -k up history-search-backward
              bindkey -k down history-search-forward
      endif
endif

• logout and log back in

Wifi as client

Note: this is to use the wifi on the RPi as *client*, read further "Access Point with Captive Portal" for using wifi as hotspot.

RPi 2

FIXME

RPi 3

Instructions on how to setup Wifi on the RasperryPi 3 can be found here.

Web Server

• nginx, what else :)

apt-get install nginx

• Go to http://192.168.1.20 (replace with the correct IP of your RPi), you should see the default Debian/nginx landing page
• For serving static documents, the default config can be kept and files just need to be put in:

/var/www/html

TODO: fcgiwrap, proxies (for nodejs or else).

Make USB soundcard the default soundcard

Built-in RPi audio is notoriously shitty, also, no line/mic in, so if your application needs sound, it might be worth getting one of these notoriously shitty (and cheap) USB soundcard, that will still beat the notoriously shitty built-in audio.

• First install some basic audio software in case you started from a blank minimal debian install

apt install alsa-base alsa-utils

• Edit /etc/modprobe.d/alsa-base.conf (create it if needed) and put:

options snd-usb-audio index=0
options snd_bcm2835 index=1

• reboot!

Drop free USB audio with jack

(only concerns systems with noticeable audio drops when using external USB soundcard/DAC/ADC)

A few years ago RPi2 got infamous for their dodgy USB implementation that led to audio drops. One popular fix was to force the USB port to 1.1 (add dwc_otg.speed=1 to /boot/cmdline.txt). This was supposedly fixed, but the RPi3 seems to have issues as well, and none of the old tricks apply. However, using jack seems to provide a drop/glitch free experience:

• Install jack

apt install jackd2

• Default raspbian jack binary is compiled with dbus support, but we do not have or want to run X. To avoid having to run X, edit /etc/dbus-1/system.conf. Make sure you replace username with the correct user who will run jack, and make sure you point to the right sound card. Audio0 is the first/default soundcard, Audio1, the second, etc.

<policy user="username">
  <allow own="org.freedesktop.ReserveDevice1.Audio0"/>
</policy>

• when you start jack, do it like this (adjust jackd flags as needed, this is minimal):

DBUS_SESSION_BUS_ADDRESS=unix:path=/run/dbus/system_bus_socket jackd -R -dalsa

• start your jack compatible application, for instance:

pd -jack

Access Point with Captive Portal

• Misc stuff to install

apt-get install dnsmasq wireless-tools hostapd

• Make your wifi key work (sorry you'll have to figure this one on your own, too many different devices, avoid mini dongles, they're usually shit with staging drivers only, "old" large USB wifi dongles (b/g not n) are usually the most reliable). However, here are some instructions for getting the built-in brcmfmac wifi chip found in the RPi3:

RPi3: built-in brcmfmac wifi chip

apt-get install firmware-brcm80211
rmmod brcmfmac
modprobe brcmfmac

Fixed IP

• Give fixed IP to wlan0 interface, edit /etc/network/interfaces and add at the end:

auto wlan0
iface wlan0 inet static
  address 10.10.10.10
  netmask 255.255.255.0

• Replace /etc/dnsmasq.conf with:

interface=wlan0
dhcp-range=10.10.10.11,10.10.10.254,12h
address=/#/10.10.10.10
no-resolv

• edit the /etc/hostapd/hostapd.conf file (adjust depending on driver/hardware)

interface=wlan0
driver=nl80211
ssid=WiFeels
hw_mode=g
channel=6

TODO: Add a note on the hw_mode and channel options.

• make hostapd starts at boot

update-rc.d hostapd defaults

• Edit /etc/default/hostapd and add

DAEMON_CONF="/etc/hostapd/hostapd.conf"

• Reboot
• If you have followed the Web Server extra, you can join the "WiFeels" wifi network and point your browser to http://itdoesnot.matter/whatyoutype and you will see the Debian/nginx landing page.

TODO: Add more info/config for proper portal detection/redirection (mostly for mobile phones and Apple devices).

Align Partitions

Only do it for production RPi setups and when the final medium/sdcard is chosen because it is hardware dependent. Skipping this part won't affect anything. In fact, most (if not all) standard RPi installations do not have proper partition alignment and most people do not know about it or care. To know why you should care and how it will affect performances, read https://superuser.com/questions/225936/what-does-it-mean-to-align-partitions.

Note: this operation can be done at any stage. So it can be skipped for now and done later if needed.

The partition that matters the most is /dev/mmcblk0p2, the one that contains the whole OS. On the RPi, it is possible to check if this partition is aligned:

parted /dev/mmcblk0 align-check optimal 2

The result is likely to be negative:

 2 not aligned

To fix this, the easiest way is to move the partition just a tiny bit and let parted do the math for correct alignment. There is catch though, because the partition will be moved, the data needs to be moved as well, and therefore the operation cannot be done live on the RPi, it must be done from another machine with the sdcard attached (directly or with a USB reader).

• take the sdcard from the RPi (after turning it off....)
• put it in the sdcard slot or USB sdcard adapter of another machine where gparted (a GUI equivalent of parted). You can do that manually with parted, resize3fs, e2image, etc, but it's kind of a PITA to do it manually in this particular case.
• Select your sdcard on the top right menu. In the examples below I will assume the sdcard is sdc, make sure you point to the right block device it will likely be different on yours.
• Select the second partition (we only need to align this one) and right-click to select resize.
• Make it so that you shrink the total size of 2MiB and that you add 1MiB empty at the beginning and 1MiB at the end.
• Right-click apply on the operation list. There will be a bunch of scary warnings, ignore them (assuming you're really working on the sdcard and not your own disk!).
• Wait, when done, quit gparted and verify alignement:

parted /dev/sdc align-check optimal 2  # will return "2 aligned" :)

Pinning

Pinning is a Debian specific method to mix packages from different versions of Debian. While this is not officially supported by Debian (ie, if you encounter an error with a software/package running on a pinned system, your bug report will be closed), it may be useful from time to time to install packages from the testing version of Debian that usually significantly more recent than the ones in the stable version of Debian.

• Create the file /etc/apt/preferences with the following content:

Package: *
Pin: release a=stable
Pin-Priority: 900

Package: *
Pin: release a=testing
Pin-Priority: 800

• Edit the apt source file, /etc/apt/sources.list, so that it looks like this:

# Stable

deb http://mirrordirector.raspbian.org/raspbian jessie main firmware non-free
deb http://archive.raspberrypi.org/debian jessie main

# Testing

deb http://mirrordirector.raspbian.org/raspbian/ stretch main contrib non-free rpi

• Update the local package cache:

apt update

• To install whateversoftware from Debian stable, proceed as usual (same behaviour as before pinning):

apt install whateversoftware

• To install a more recent whateversoftware from Debian testing:

apt install whateversoftware -t testing

Read-only system

TODO

Making and Sharing images

This is done off the RPi, so turn it off and take the sdcard out, then back into an adapter into any UNIX-like OS running machine that you can find:

Backup an image: Option 1 - I'm soooo lazy

In this method we make a full dump of sdcard, which can be a storage waste if you only have partitioned, say 2GB of the sdcard, as you will then make an image of the full capacity of the sdcard. For instance if you're RPi image has only 3GB of partitions, but your sdcard potential full size if 16GB, using this method will create a 16GB file. BUT because we compress the image on the fly with xz, then it will in fact be not more as the partitions size, because the empty space will compress to virtually nothing. However if you need to uncompress the full image at some point, for whatever reason, you will need a diskspace of 16GB.

• figure out which block device represents your sdcard (hint: run dmesg after plugging the sdcard). In this example we assume it is /dev/sdc, make sure you use the correct block device.
• copy the raw content of the sdcard and compress it on the fly into the resulting image my-raspberry-pi.img.xz:

dd bs=4M if=/dev/sdc status=progress | xz > my-raspberry-pi.img.xz

Note: xz compression is very powerful and will create very tiny images, but compression time can be quite slow, if you're in a hurry or slow computer, and do not mind 50% efficiency loss, use gzip instead of xz in the command above. Alternatively if your processor has multiple core, using multithreading with xz can make it on run almost as fast as a direct raw copy. Use the flag -T to set the number of threads, for instance -T 8 will make it use 8 threads.

Backup an image: Option 1 - I'm soooo anal

If you want to distribute your image, it might be more elegant and proper to make an image that is not bigger than what is really being used on the sdcard itself. There are two main reasons for that:

1. the method above is hardware specific meaning that no two sdcard capacity are exactly the same. For instance one 8GB sdcard might be a bit bigger than another. If your backup'ed sdcard is smaller than your target sdcard, that's fine, but if it is the other way around, when your image to the target, dd will complain that it ran out of space. If you've only used small partitions and grew them only as you needed, carefully managing the sdcard space, this will not be an issue as the truncated part will most likely be unpartitioned space where there is nothing of value. However if you've created an extra partition growing the partition of your OS to the max capacity of the sdcard and started to use it, well, there are quite some chance, that cutting into this space will not only result in a damaged partition (recoverable) and data loss (unrecoverable).
2. Another, more practical reason, is that if you need to share or manipulate the image of your RPi OS uncompressed it will be obviously more practical to work with a smaller file than with a larger one.

• figure out which block device represents your sdcard (hint: run dmesg after plugging the sdcard). In this example we assume it is /dev/sdc, make sure you use the correct block device.
• copy the raw content of the sdcard into the resulting image my-raspberry-pi.img:

dd bs=4M if=/dev/sdc status=progress of=my-raspberry-pi.img

• figure out how much space is used by partitions on the image:

fdisk -lu my-raspberry-pi.img

• Example of the command output, your result will be different.

Disk my-raspberry-pi.img: 7.5 GiB, 8053063680 bytes, 15728640 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x95f9e2e9

Device                Boot   Start     End Sectors Size Id Type
my-raspberry-pi.img1            16  124927  124912  61M  b W95 FAT32
my-raspberry-pi.img2        129024 4198399 4069376   2G 83 Linux

• Note the end sector of the last partition, here the last partition is my-raspberry-pi.img2 and the last sector is 4198399.
• Add 1 sector to this value (to be on the safe size we will trim a bit less than needed), and mutiply by 512 to obtain the size in bytes: (4198399 + 1) * 512 = 2149580800.
• truncate the image at this value, adjust to your own value:

truncate my-raspberry-pi.img --size 2149580800

• Finally compress the image to make the sharing/storing less demanding (read note about xz compression in previous method):

xz my-raspberry-pi.img

Restore image

Regardless which method you used, you can restore or copy an image like this. In the commands below the target block device is /dev/sdc, make sure you adjust to the correct one on your system so that you do not overwrite another disk!

• if the image is not compressed:

dd bs=4M if=my-raspberry-pi.img of=/dev/sdc status=progress

• if the image is compressed (xz):

xzcat tgc.img.xz | dd bs=4M of=/dev/sdc status=progress

• if the image is compressed (gzip):

zcat tgc.img.xz | dd bs=4M of=/dev/sdc status=progress

TODO

• Read about overclocking settings and apply if necessary
• Some devices trigger an alternative browser to sign-in when it figures out it is a captive portal, it is useless for us, but bot sure if there is a way to redirect it back to the main browser (spotted on some Android devices, but not all)