Part 2b — Machu Picchu: Persistent IPFS node on Raspberry Pi3

Raspberry Pi3 Model B+ configured as IPFS node

version of September 6, 2021

The following is part of an explanation how I installed a Raspberry Pi3 Model B+ to serve as a persistent IPFS node in Machu Picchu. My Vision: Machu Picchu, Tech4Good

• Bonus of October 2024: Raspberry Pi introduced a Hardware Adaptation Top (HAT) to connect directly a SSD to the NVME bus. Much faster and cheaper than a Samsung USB https://www.raspberrypi.com/documentation/accessories/m2-hat-plus.html

This document is composed of 3 parts (and a bonus):

• Part 1 explains the Raspberry Pi and why it interests Machu Picchu. You may want to read it to get acquainted with this Single Board Computer and its very helpful community. It might also give you ideas how to use it for your own project.
• Part 2a is a hands-on list of steps to install and deploy IPFS on the Raspberry Pi. It describes the first steps, until and including when changing the hostname and ssh password.
• Part 2b is the rest of the steps to finish establishing a ssh session and the Solid State Disk, to install and deploy IPFS on the Raspberry Pi. This is what you are reading.

Although I’m doing my best to explain each step, at some point I needed to make assumptions about your knowledge of Linux. If you need more explanations, you might want to do a Google search for more details. Your lifesaver, whenever you are puzzled by an error message in the installation, is to paste in Google the text of the error message followed by “stackexchange”.

List of installation steps

1. Burn the boot micro-SD card and configure it for wi-fi access.
2. Boot and open ssh session.
3. In ssh session, change hostname and password.
4. Initiate new ssh session with the new hostname and password.
5. Update and upgrade all software packages.
6. Prepare the mounting of the SSD.
7. Install IPFS and check IPFS access.

Step 1, 2 and 3 have been described in Part 2a.

4. Initiate new ssh session with the new hostname and password

The new ssh session should use now the Raspberry Pi’s new hostname and password. First, make sure to reset with the command ssh-keygen any previous parameters of ssh session connecting to ipfs-pi.local. It does nothing if you are initiating a ssh session for the first time to this hostname, but indispensable when you reinstall for the subsequent times.

• If you have never connected to a host with that name, your Mac will say failed. Normal.

MBP18VTK:~ kvutien$ ssh-keygen -R ipfs-pi.local
do_known_hosts: hostkeys_foreach failed: No such file or directory

• If like me you have connected to such a host and are re-installing the RPi3, your MacOS will tell you that it has updated its system file named .ssh/known_hosts.

MBP18VTK:~ kvutien$ ssh-keygen -R ipfs-pi.local
# Host ipfs-pi.local found: line 1
/Users/kvutien/.ssh/known_hosts updated.
Original contents retained as /Users/kvutien/.ssh/known_hosts.old

• Now you can establish a ssh session to the RPi3. Your MacOS will inform you that it cannot establish the authenticity of this host and ask you to confirm that you still want to establish this session

MBP18VTK:~ kvutien$ ssh pi@ipfs-pi.local
The authenticity of host 'ipfs-pi.local (2001:7e8:ccdd:e000:f124:2430:a6d:c314)' can't be established.
ECDSA key fingerprint is SHA256:AagTtr9Bcb3VZBsWK2tWFd8CxRfWmCbGyPsA8gsPX4w.
Are you sure you want to continue connecting (yes/no)?

• Answer “yes" and give the new password that you created above with the command passwd. If you have never connected to a host with that name, here is what you will see.

pi@ipfs-pi.local's password: 
Warning: Permanently added 'raspberrypi.local,2001:7e8:ccdd:e000:f124:2430:a6d:c314' (ECDSA) to the list of known hosts.

• If like me your Mac has already connected to such a host, you’ll have a routine ssh session feedback.

Warning: Permanently added 'raspberrypi.local,2001:7e8:ccdd:e000:f124:2430:a6d:c314' (ECDSA) to the list of known hosts.
pi@ipfs-pi.local's password: 
Linux ipfs-pi 5.10.17-v7+ #1414 SMP Fri Apr 30 13:18:35 BST 2021 armv7l
The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Thu Sep  2 11:29:05 2021 from 2001:7e8:ccdd:e000:c007:79fa:be03:ef52

Important note: If you have already used this hostname and password before you reinstalled the OS, and if you forgot to reset the ssh key using ssh-keygen, your MacOS will complain loudly of a possible security threat and refuse to establish the ssh session.

5. Update and upgrade all software packages

In this first ssh session with the new hostname and password, let's get the latest OS and software updates. This is a recommended practice every time you install from scratch a Linux distribution.

pi@ipfs-pi:~ $ sudo apt update -y
...
pi@ipfs-pi:~ $ sudo apt upgrade -y
... (can be very verbose)
pi@ipfs-pi:~ $  sudo apt autoremove
...

6. Prepare the mounting of the SSD

Now we can plug the Samsung SSD (Solid State Disk) and start installing IPFS on it. We need some care with Raspbian file permissions here because we are playing at quite a low level of the file system, as a casual user pi, and some commands need to be given as user root. Follow carefully the explanations.

• Plug the Samsung SSD on one USB port of the RPi3.
• Using ssh on Terminal, use the lsblk command to list storage ("block") devices. The SSD is seen as sda (Storage Device A) and its first partition is sda1.

• Check the disk partitions of sda using fdisk ("format disk", a command to be issued as root)

pi@ipfs-pi:~ $ sudo fdisk -l | grep sda
Disk /dev/sda: 465.8 GiB, 500107862016 bytes, 976773168 sectors
/dev/sda1        2048 976770112 976768065 465.8G  7 HPFS/NTFS/exFAT

• To read the SSD, which is formatted as exfat, install on the RPi3 the exfat driver that handles this format exfat in a virtual file system of Linux (exfat-fuse and exfat-utils):

• Create a mount point under the /mnt folder, by creating a folder xdisk, under which all the contents of the SSD will be reachable.

pi@ipfs-pi:~ $ sudo mkdir /mnt/xdisk
pi@ipfs-pi:~ $ ls -ls /mnt
total 4
4 drwxr-xr-x 2 root root 4096 Aug 31 14:09 xdisk

• Change permissions of folder xdisk. This is needed because the folder xdisk belongs to user root of group root. As it is now, we as user pi, have no write permission in this folder. To prove it, let's try and create a file test.txt as user pi. It will be refused. Now create this same file as root using sudo. It will succeed.

pi@ipfs-pi:~ $ touch /mnt/xdisk/test.txt
touch: cannot touch '/mnt/xdisk/test.txt': Permission denied
pi@ipfs-pi:~ $ sudo touch /mnt/xdisk/test.txt
pi@ipfs-pi:~ $ ls -ls /mnt/xdisk
total 0
0 -rw-r--r-- 1 root root 0 Sep  2 13:44 test.txt

This is not very practical because user pi (and other users) will not be allowed to write any content to the SSD. We need to change file permission with sudo chmod. We add write permission to all users and groups to the folder /mnt/xdisk. We check with the command ls -ls that everybody has read-write-execute access to xdisk.

pi@ipfs-pi:~ $ sudo chmod a+w /mnt/xdisk
pi@ipfs-pi:~ $ ls -ls /mnt
total 4
4 drwxrwxrwx 2 root root 4096 Sep  2 13:44 xdisk

Let’s verify that the result we desire is indeed achieved. Delete (as owner root) the file test.txt we created above, using the command sudo rm. Create it again as user pi. Observe that this action is not refused anymore and that the owner of this file is now user pi.

pi@ipfs-pi:~ $ sudo rm /mnt/xdisk/test.txt
pi@ipfs-pi:~ $ ls -ls /mnt/xdisk
total 0
pi@ipfs-pi:~ $ touch /mnt/xdisk/test.txt
pi@ipfs-pi:~ $ ls -ls /mnt/xdisk
total 0
0 -rw-r--r-- 1 pi pi 0 Sep  2 13:54 test.txt

• Write something as user pi into the file with the Linux editor nano, for example "This is a test" and check the content with the command cat. Observe that the string "This is a test" is indeed the content of test.txt.

pi@ipfs-pi:~ $ nano /mnt/xdisk/test.txt
...
pi@ipfs-pi:~ $ cat /mnt/xdisk/test.txt
This is a test

Until now, we have played with this folder as if it were any Linux folder, without mounting the SSD. Let’s empty the folder because we’ll now use it as a mounting point for the SSD, and for this purpose the folder must be empty.

pi@ipfs-pi:~ $ rm /mnt/xdisk/test.txt
pi@ipfs-pi:~ $ ls -ls /mnt/xdisk
total 0

• Mount the SSD (device /dev/sda1) at the mounting point /mnt/xdisk. Check with the command df ("disk free") that it is recognized by the file system.

pi@ipfs-pi:~ $ sudo mount /dev/sda1 /mnt/xdisk
FUSE exfat 1.3.0
pi@ipfs-pi:~ $ df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/root        29G  1.4G   27G   5% /
devtmpfs        430M     0  430M   0% /dev
tmpfs           462M     0  462M   0% /dev/shm
tmpfs           462M  6.2M  456M   2% /run
tmpfs           5.0M  4.0K  5.0M   1% /run/lock
tmpfs           462M     0  462M   0% /sys/fs/cgroup
/dev/mmcblk0p1  253M   49M  204M  20% /boot
tmpfs            93M     0   93M   0% /run/user/1000
/dev/sda1       466G   54M  466G   1% /mnt/xdisk

Note: if you have an error message when you sudo mount the SSD (fuse: device not found, try ‘modprobe fuse’ first) then restart the Rpi (sudo shutdown now -r). The ssh connection will be closed so you need to establish it again (ssh pi@ipfs-pi). This is because installing fuse means updating some kernel modules and sometimes it requires a reboot to run the new kernel.

We have one last thing to do with the file system before installing IPFS. Edit fstab (it is the system configuration file that contains all available disks, disk partitions and their options, that are static parameters of the file system) to make the SSD mount on reboot. For this doing, get the PARTUUID of the external drive (your own drive will have a different PARTUUID).

pi@ipfs-pi:~ $ sudo blkid | grep sda1
/dev/sda1: LABEL="Samsung_T5" UUID="344C-FEA0" TYPE="exfat" PARTUUID="cab80be4-01"

• Edit the file etc/fstab . Do it for example with the editor nano (type the command sudo nano /etc/fstab) and in nano copy-paste the following line

• Restart the RPi3 and initiate a new ssh session.

pi@ipfs-pi:~ $ sudo shutdown now -r
Connection to ipfs-pi.local closed by remote host.
Connection to ipfs-pi.local closed.
MBP18VTK:~ kvutien$ ssh pi@ipfs-pi.local
...
pi@ipfs-pi.local's password:
...

• Check that the command df -T sees the auto-mounted SSD. Here we see the SSD as device /dev/sda1, its file system is fuseblk and it is mounted on /mnt/xdisk.

From now on, the SSD is automatically mounted at boot time if it is plugged in. If it is plugged only after boot, type sudo mount -a and the file system will follow the instruction in fstab to will mount it at /mnt/xdisk.

7. Install IPFS and check IPFS access

We can now start installing IPFS. It is the easiest part.

• Check that git is installed already on the RPi3, if not, install it.

pi@ipfs-pi:~ $ git version
-bash: git: command not found
pi@ipfs-pi:~ $ sudo apt install git
Reading package lists... Done
...

• In the SSD (use cd /mnt/xdisk), as user root, clone with git the IPFS installation script. When you cloned the script, git should have stored it into a folder that matches the name of the git repository (ipfs-rpi)

• Go into the cloned folder ipfs-rpi and start the installation script (this installation script is very clever: I’ll do another Medium post to explain it).

• Successful IPFS installation. Retrieve and display from IPFS the welcome file.

That’s all folks, you may close the RPi 3 enclosure and have fun.

BTW, once you succeeded installing the IPFS node using the 32-bit image of Raspbian, how about trying to do it again, with a 64-bit image (https://kvutien-yes.medium.com/machu-picchu-bonus-64-bit-persistent-ipfs-node-on-raspberry-pi3-a9dc6c42f852)?

Bonus of November 2021: Boot from USB

Since 2020, the Raspberry foundation official boot loader can boot from an USB drive. https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#raspberry-pi-3b

This YouTube video shows how to configure the boot sequence of the Raspberry Pi to boot from the USB drive: https://www.youtube.com/watch?v=zp9-1GHVfi0

Booting from an SSD drive means that this drive is also used as the swap disk, which is 2–3 times faster than using an SD card. This is precious when running on 512 MB of RAM, like a Raspberry Pi Zero 2W.