layout	title	nav_order
default	Raspberry Pi	20

Raspberry Pi

{: .no_toc }

We configure the Raspberry Pi and install the Linux operating system.

Preparing the operating system

The node runs headless, that means without keyboard or display, so the operating system Raspbian Buster Lite is used.

Download the Raspbian Buster Lite{:target="_blank"} disk image
Write the disk image to your SD card with this guide{:target="_blank"}

Enable Secure Shell

Without keyboard or screen, no direct interaction with the Pi is possible during the initial setup. After writing the image to the microSD card, create an empty file called “ssh” (without extension) in the main directory of the card. This causes the Secure Shell (ssh) to be enabled from the start and we will be able to login remotely.

Create a file ssh in the boot partition of the microSD card

Prepare Wifi

You can run your RaspiBolt over Wifi. To avoid using a network cable for the initial setup, you can pre-configure the wireless settings:

Create a file wpa_supplicant.conf in the boot partition of the microSD card with the following content. Note that the network name (ssid) and password need to be in double-quotes (like psk="password")
```
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=[COUNTRY_CODE]
network={
  ssid="[WIFI_SSID]"
  psk="[WIFI_PASSWORD]"
}
```
Replace [COUNTRY_CODE] with the ISO2 code{:target="_blank"} of your country (eg. US)
Replace [WIFI_SSID] and [WIFI_PASSWORD] with the credentials for your own WiFi.

Start your Pi

Safely eject the sd card from your computer
Insert the sd card into the Pi
If you did not already setup Wifi: connect the Pi to your network with an ethernet cable
Start the Pi by connecting it to the power adapter using the USB-C cable

Connecting to the Raspberry Pi

Find it

The Pi is starting and gets a new address from your home network. Finding it can be a bit tricky without a screen. If you're lucky, you don't need to know this address and can just connect using mDNS.

On your regular computer, open the Terminal (also known as "command line"). Here are a few links with additional details for Windows{:target="_blank"}, MacOS{:target="_blank"} and Linux{:target="_blank"}.

Try to ping the Raspberry Pi local hostname (press Ctrl-C to interrupt)

$ ping raspberrypi.local
> PING raspberrypi.local (192.168.1.192) 56(84) bytes of data.
> 64 bytes from 192.168.1.192 (192.168.1.192): icmp_seq=1 ttl=64 time=88.1 ms
> 64 bytes from 192.168.1.192 (192.168.1.192): icmp_seq=2 ttl=64 time=61.5 ms

If you get a response like above, mDNS works within your local network. Proceed directly to the next section.
If the ping command fails or does not return anything, you need to manually look for your Pi. As this is a common challenge, just follow the official Raspberry Pi guideance on how to find your IP Address{:target="_blank"}.
You should now be able to reach your Pi, either with the hostname raspberrypi.local or an IP address like 192.168.0.20.

Access with Secure Shell

Now it’s time to connect to the Pi via SSH and get to work. For that, a Secure Shell (SSH) client is needed.

If you need to provide connection details, use the following settings:

host name: raspberrypi.local or the ip address like 192.168.0.20
port: 22
username: pi
password: raspberry.

Install and start the SSH client for your operating system:

Windows: PuTTY (Website{:target="_blank"})
MacOS and Linux: from the Terminal, use the native command:
- ssh pi@raspberrypi.local or
- ssh pi@192.168.0.20

🔍 more: using SSH with Raspberry Pi{:target="_blank"}

The command line

We are going to work on the command line of the Pi, which may be new to you. Find some basic information below, it will help you navigate and interact with your Pi.

You enter commands and the Pi answers by printing the results below your command. To make it clear where a command begins, every command in this guide starts with the $ sign. The system response is marked with the > character.

In the following example, just enter ls -la and press the enter/return key:

$ ls -la
> example system response
# This is a comment, don't enter this on the command line

Auto-complete commands: When you enter commands, you can use the Tab key for auto-completion, eg. for commands, directories or filenames.
Command history: by pressing ⬆️ (arrow up) and ⬇️ (arrow down) on your keyboard, you can recall your previously entered commands.
Common Linux commands: For a very selective reference list of Linux commands, please refer to the FAQ page.
Use admin privileges: Our regular user has no admin privileges. If a command needs to edit the system configuration, we need to use the sudo ("superuser do") command as prefix. Instead of editing a system file with nano /etc/fstab, we use sudo nano /etc/fstab.

For security reasons, the user "bitcoin" cannot use the sudo command.
Using the Nano text editor: We use the Nano editor to create new text files or edit existing ones. It's not complicated, but to save and exit is not intuitive.
- Save: hit Ctrl-O (for Output), confirm the filename, and hit the Enter key
- Exit: hit Ctrl-X
Copy / Paste: If you are using Windows and the PuTTY SSH client, you can copy text from the shell by selecting it with your mouse (no need to click anything), and paste stuff at the cursor position with a right-click anywhere in the ssh window.

In other Terminal programs, copy/paste usually works with Ctrl-Shift-C and Ctrl-Shift-V.

Working on the Raspberry Pi

You are now on the command line of your own Bitcoin node. Let's start with the configuration.

Raspi-Config

Enter the following command:

$ sudo raspi-config

First, on 1 change your password to your password [A].
Next, choose Update 8 to get the latest configuration tool
Network Options 2:
- you can give your node a cute hostname like “raspibolt”
- configure your Wifi connection
Boot Options 3:
- choose Desktop / CLI → B1 Console and
- Wait for network at boot
Advanced 7: run Expand Filesystem
Exit by selecting <Finish>, and <No> as no reboot is necessary

Important: if you connected using the hostname raspberrypi.local, you now need to use the new hostname (e.g. raspibolt.local)

The following two potential error messages are expected:

After changing the hostname, e.g. to raspibolt, a reboot is required to get rid of this error message. It can be safely ignored for now.
```
sudo: unable to resolve host raspberrypi: Name or service not known
```
The raspi-config automatically sets your location, but does not generate the corresponding locale files:
```
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
...
LC_NUMERIC = "de_CH.UTF-8",
...
are supported and installed on your system.
```
This error is safe to ignore. If you want to get rid of it, note the setting for LC_NUMERIC (e.g. de_CH.UTF-8), select this locale in the following configuration screen and configure it as default.
```
$ sudo dpkg-reconfigure locales
```
If the above fix does not remove the locale error, it is probably your host machine that you use to SSH from pushing its locale onto the Pi. What you need to do is very simple: make Pi stop accepting locale over SSH regardless of origin. You do that by editing sshd_config file in nano editor:

  $ sudo nano /etc/ssh/sshd_config

All you need to do now is find the AcceptEnv LANG LC_* and make sure to comment it out so it looks like this:

  #AcceptEnv LANG LC_*

Now CTRL+X (save) and exit, and the error will be gone.

Software update

It is important to keep the system up-to-date with security patches and application updates. The “Advanced Packaging Tool” (apt) makes this easy.

💡 Do this regularly every few months to get security related updates.

$ sudo apt update
$ sudo apt full-upgrade

Make sure that all necessary software packages are installed:

$ sudo apt install htop git curl bash-completion jq qrencode dphys-swapfile hdparm --install-recommends

Add users

This guide uses the main user "admin" instead of "pi" to make it more reusable with other platforms.

Create the new user "admin", set password [A] and add it to the group "sudo"
```
$ sudo adduser admin
$ sudo adduser admin sudo
```
And while you’re at it, change the password of the “root” admin user to your password [A].
```
$ sudo passwd root
```

The bitcoin and lightning processes will run in the background (as a "daemon") and use the separate user “bitcoin” for security reasons. This user does not have admin rights and cannot change the system configuration.

Enter the following command, set your password [A] and confirm all questions with the enter/return key.
```
$ sudo adduser bitcoin
```
For convenience, the user "admin" is also a member of the group "bitcoin", giving it read-only privileges to configuration files.
```
$ sudo adduser admin bitcoin
```
Restart your RaspiBolt.
```
$ sudo reboot
```

Attach external drive

To store the blockchain, we need a lot of space. As a server installation, the Linux native file system Ext4 is the best choice for the external hard disk, so we will format the hard disk, erasing all previous data. The external hard disk is then attached to the file system and can be accessed as a regular folder (this is called “mounting”).

🚨 Existing data on this drive will be deleted!

Log in as "admin"

Do not yet connect the external drive to your Pi, we need to check some things first.
Start your Raspberry Pi by unplugging it and connecting the power cable again.
Log in using SSH, but now with the user admin, your password [A] and the new hostname (e.g. raspibolt.local) or the IP address.
```
$ ssh admin@raspibolt.local
```
To change system configuration and files that don't belong to the "admin", you have to prefix commands with sudo. You will be prompted to enter your admin password from time to time for increased security.

Make sure USB3 is performant

The Raspberry Pi 4 supports USB3 drives, but is very picky. A lot of USB3 adapters for external drives are not compatible and need a manual workaround to be usable. We will now check if your drive works well as-is, or if additional configuration is needed.

🔍 more: Raspberry Pi forum: bad performance with USB3 SSDs{:target="_blank"}

First, lets get some information about your drive from the kernel messages. Clear the kernel buffer, and follow the new messages (let the last command run):
```
$ sudo dmesg -C
$ sudo dmesg -w
```

Connect your external drive to the blue USB3 ports of the running Raspberry Pi, preferably with a good cable that came with the drive.

Once the system recognizes it, details are automatically displayed by the dmesg command.

[  726.547907] usb 2-1: new SuperSpeed Gen 1 USB device number 3 using xhci_hcd
[  726.579304] usb 2-1: New USB device found, idVendor=152d, idProduct=0578, bcdDevice= 3.01
[  726.579321] usb 2-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[  726.579333] usb 2-1: Product: USB 3.0 Device
[  726.579346] usb 2-1: Manufacturer: USB 3.0 Device
[  726.579357] usb 2-1: SerialNumber: 000000005B3E
[  726.582254] usb 2-1: UAS is blacklisted for this device, using usb-storage instead
[  726.582350] usb 2-1: UAS is blacklisted for this device, using usb-storage instead
[  726.582364] usb-storage 2-1:1.0: USB Mass Storage device detected
[  726.582674] usb-storage 2-1:1.0: Quirks match for vid 152d pid 0578: 1800000
[  726.582783] scsi host0: usb-storage 2-1:1.0
[  727.598422] scsi 0:0:0:0: Direct-Access     INTENSO  SATA III SSD     0301 PQ: 0 ANSI: 6
[  727.599182] sd 0:0:0:0: Attached scsi generic sg0 type 0
[  727.605796] sd 0:0:0:0: [sda] 937703088 512-byte logical blocks: (480 GB/447 GiB)
[  727.606519] sd 0:0:0:0: [sda] Write Protect is off
[  727.606536] sd 0:0:0:0: [sda] Mode Sense: 47 00 00 08
[  727.607982] sd 0:0:0:0: [sda] Disabling FUA
[  727.607998] sd 0:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA
[  727.611337]  sda: sda1
[  727.614890] sd 0:0:0:0: [sda] Attached SCSI disk

Make a note of the values shown for idVendor and idProduct (in this case "152d" and "0578"). Then, exit dmesg with Ctrl-C.

List all block devices with additional information. The list shows the devices (e.g. sda) and the partitions they contain (e.g. sda1).

Make a note of the partition name you want to use (in this case "sda1").

$ lsblk -o NAME,MOUNTPOINT,UUID,FSTYPE,SIZE,LABEL,MODEL
> NAME        MOUNTPOINT UUID                                 FSTYPE   SIZE LABEL  MODEL
> sda                                                                447.1G        SATA_III_SSD
> └─sda1                 9ec0b784-d448-4757-a3b2-8abd57c544f3 ext4   447.1G
> mmcblk0                                                             14.9G
> ├─mmcblk0p1 /boot      5203-DB74                            vfat     256M boot
> └─mmcblk0p2 /          2ab3f8e1-7dc6-43f5-b0db-dd5759d51d4e ext4    14.6G rootfs

If your external drive (e.g. sda) does not contain any partitions (e.g. no sda1), create a partition first using as described here: https://superuser.com/questions/643765/creating-ext4-partition-from-console
Now, let's test the read performance of your drive. Make sure to use the right partition name (used with the /dev/ prefix).
```
$ sudo hdparm -t --direct /dev/sda1

/dev/sda1:
Timing O_DIRECT disk reads:   2 MB in 31.18 seconds =  65.69 kB/sec
```
In this case, the performance is really bad: 65 kB/sec is so 1990's. If the measured speed is more than 50 MB/s, you can skip the rest of this section and go directly to formatting the external drive.

Otherwise we need to configure the USB driver to ignore the UAS interface of your drive. This configuration must be passed to the Linux kernel on boot:
- Open the cmdline.txt file of the bootloader.
```
$ sudo nano /boot/cmdline.txt
```
- At the start of the line of parameters, add the text usb-storage.quirks=aaaa:bbbb:u where aaaa is the "idVendor" and bbbb is the "idProduct" value. Make sure that there is a single space character ( ) between our addition and the next parameter. Save and exit.
```
usb-storage.quirks=152d:0578:u ..............
```
- Reboot the Raspberry Pi with the external drive still attached.
```
$ sudo reboot
```
- After you logged in as "admin" again, let's test the read performance once more.
```
$ sudo hdparm -t --direct /dev/sda1

/dev/sda1:
Timing O_DIRECT disk reads: 510 MB in  3.01 seconds = 169.59 MB/sec
```
- You should see a significant increase in performance. If the test still shows a very slow read speed, your drive or USB adapter might not be compatible with the Raspberry Pi. In that case I recommend visiting the Raspberry Pi Troubleshooting forum{:target="_blank"} or simply try out hardware alternatives.

Format external drive and mount

Format the partition on the external drive with Ext4 (use [NAME] from above, e.g sda1)
```
$ sudo mkfs.ext4 /dev/[NAME]
```
List the devices once more and copy the UUID into a text editor on your local computer.
```
$ lsblk -o NAME,MOUNTPOINT,UUID,FSTYPE,SIZE,LABEL,MODEL
```
Edit the fstab file and add the following as a new line at the end, replacing 123456 with your own UUID.
```
$ sudo nano /etc/fstab
```
```
UUID=123456 /mnt/ext ext4 rw,nosuid,dev,noexec,noatime,nodiratime,auto,nouser,async,nofail 0 2
```
🔍 more: complete fstab guide{:target="_blank"}
Create the directory to add the hard disk and set the correct owner
```
$ sudo mkdir /mnt/ext
```

Mount all drives and check the file system. Is “/mnt/ext” listed?

$ sudo mount -a
$ df -h /mnt/ext
> Filesystem      Size  Used Avail Use% Mounted on
> /dev/sda1       440G   73M  417G   1% /mnt/ext

Create bitcoin directory

Set the owner

$ sudo chown -R bitcoin:bitcoin /mnt/ext/

Switch to user "bitcoin", navigate to the external drive and create the bitcoin directory.

$ sudo su - bitcoin
$ cd /mnt/ext
$ mkdir bitcoin
$ ls -la
> total 28
> drwxr-xr-x 4 bitcoin bitcoin  4096 Dec 12 17:43 .
> drwxr-xr-x 4 root    root     4096 Dec 12 17:38 ..
> drwxr-xr-x 2 bitcoin bitcoin  4096 Dec 12 17:43 bitcoin
> drwx------ 2 bitcoin bitcoin 16384 Dec 12 17:30 lost+found

Create a testfile in the new directory and delete it.
```
$ touch bitcoin/test.file
$ rm bitcoin/test.file
```
If this command gives you an error, chances are that your external hard disk is mounted as “read only”. This must be fixed before proceeding. If you cannot fix it, consider reformatting the external drive.
Exit the "bitcoin" user session
```
$ exit
```

🔍 more: external storage configuration{:target="_blank"}

Move swap file

The usage of a swap file can degrade your SD card very quickly. Therefore, we will move it to the external drive.

Edit the configuration file and replace existing entries with the ones below. Save and exit.

$ sudo nano /etc/dphys-swapfile

CONF_SWAPFILE=/mnt/ext/swapfile

# comment or delete the CONF_SWAPSIZE line. It will then be created dynamically
#CONF_SWAPSIZE=

Recreate new swapfile on ssd (will be active after reboot)
```
$ sudo dphys-swapfile install
```

Next: Security >>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

raspibolt_20_pi.md

raspibolt_20_pi.md

Raspberry Pi

Table of contents

Preparing the operating system

Enable Secure Shell

Prepare Wifi

Start your Pi

Connecting to the Raspberry Pi

Find it

Access with Secure Shell

The command line

Working on the Raspberry Pi

Raspi-Config

Software update

Add users

Attach external drive

Log in as "admin"

Make sure USB3 is performant

Format external drive and mount

Create bitcoin directory

Move swap file

Files

raspibolt_20_pi.md

Latest commit

History

raspibolt_20_pi.md

File metadata and controls

Raspberry Pi

Table of contents

Preparing the operating system

Enable Secure Shell

Prepare Wifi

Start your Pi

Connecting to the Raspberry Pi

Find it

Access with Secure Shell

The command line

Working on the Raspberry Pi

Raspi-Config

Software update

Add users

Attach external drive

Log in as "admin"

Make sure USB3 is performant

Format external drive and mount

Create bitcoin directory

Move swap file