The Ultimate RPi Installation Guide
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)
Basic Setup
MINIBIAN installation
Setting up SD Card
- Download MINIBIAN image: http://minibianpi.wordpress.com/download/
- Put image on SD Card:
- Stick SD Card in (duh)
mac
- First open terminal
- Find the disk that you are going to write to
diskutil list
- 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
'To make it easier, and to avoid wiping external drives, make sure you have nothing else plugged in aside from your SD Card'
- 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
sudo dd bs=4M if=minibian.img of=/dev/sdc status=progress
- Insert SD, Power the RPi, wait for crazy blinking to stop
Connecting to the Pi
To connect to the Pi, 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 by ethernet first. You can alternatively connect it directly to your personal machine via an ethernet cable - steps to do that can be found here.
If connecting to a normal network :
- Figure out what's the RPi IP (adjust mask to reflect own network)
nmap -sP 192.168.1.1-255
mac : you will need to install nmap manually from here. Easiest installation method is with the OSX Binaries.
- ssh into RPi (default MINIBIAN passwd is raspberry)
ssh root@192.168.1.73
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
- 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
Wifi
Instructions on how to setup Wifi on the RasperryPi 3 can be found here.
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
THIS IS IT!
Well done, you now have a minimal RPi installation, the guideline stops here, anything past this point is just a matter of what the RPi will be used for.
Extras
All the following steps are optional and depend on the use of the RPi.
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).
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:
apt install firmware-brcm80211 rmmod brcmfmac modprobe brcmfmac
- 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
- 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:
- 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).
- 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
Restore image
Regardless which method you used, you can restore of copy an image