This page is no longer maintained. Please check out the latest and enhanced version of this guide on Github: Updated Guide for Bitcoin Mainnet!

https://github.com/Stadicus/guides/blob/master/raspibolt/README.md

I like to tinker and build stuff myself. Recently I built my own Bitcoin / Lightning Node with a simple Raspberry Pi. It took several iterations to get it right and it taught me a lot. This is my attempt to share my learnings and encourage you to run a node yourself.

Why am I excited about Bitcoin and Lightning?

Bitcoin as a new technology is an incredibly interesting endeavor, especially because of its interdisciplinary nature. Bitcoin as sound money is going to have a major impact on economic principles and thus society as a whole. In my opinion, a solid, anti-fragile base layer for this future monetary network will be more important than the most novel feature of competing projects. Due to network effects, I can only see one major monetary blockchain — Bitcoin — evolving over time.

At the moment, Bitcoin is more of a store of value and not really suited for small everyday transactions. Due to limitations of the blockchain and the incredible growth of its usage, fees have risen and business models relying on cheap transactions are being priced out. This is fine. Truly decentralized blockchains are a scarce resource and cannot scale to accommodate all global transactions. The current scaling pains are a great motivator to build better technology to scale exponentially, as opposed to just making everything bigger for linear scaling.

This is where the Lightning Network comes in. As one of several new blockchain “extensions”, its promise is to accommodate nearly unlimited transactions, with instant confirmation, minimal fees and increased privacy. It sounds almost too good to be true, but in contrast to ubiquitous ICO with their own token, this technology is well researched, committed to the cypherpunk open-source ethos and leverages the solid underpinnings of Bitcoin.

To preserve the decentralized nature of this monetary system, I think it is important that everybody can run their own trustless Bitcoin node, preferably on cheap hardware like a Raspberry Pi.

This is why I set out to run my RaspiBolt and think that I have now — through numerous iterations — quite a good configuration, that I would like to share as my modest contribution to the community. I am not a system specialist, so please feel free to point out improvements in the comments.

Purpose

My aim is to set up a trustless Bitcoin Core and Lightning node that runs 24/7, is part of and supports the decentralization of the Lightning network by routing payments and can be used to send and receive personal payments using the command line interface.

This server is set up without graphical user interface and is used remotely using the Secure Shell (SSH) command line. In the future, this server should function as my personal backend for desktop and mobile wallets, but I haven’t found a good solution to this yet. So, command line it is for the moment.

Spoiler alert, this is the goal of this guide, simply buying a Blockaccino:

As all components of the Lightning network are still under development, this server is configured for the Bitcoin Testnet. The plan is to regularly update this guide until we hit the mainnet once there is an official and stable Eclair Lightning release available for that. A switch to the mainnet will be straightforward.

Target audience

This guide strives to give simple and foolproof instructions. But the goal is also to do everything ourselves, no shortcuts that involve trust in a 3rd party allowed. This makes this guide quite technical, but I try to make it as straightforward as possible and explain everything for you to gain a basic understanding of the how and why.

Also, please be aware that all Lightning implementations are still in alpha phase and bugs are to be expected. If you like to learn about Linux, Bitcoin and Lightning, this guide is for you.

If you want to learn more about Bitcoin and are curious about the inner workings of the Lightning Network, the following articles in Bitcoin Magazine offer a very good introduction:

1) Hardware Requirements

The following components are necessary:

Raspberry Pi: version 2 or 3

Micro SD card: 8 GB or more, incl. adapter to your regular computer

USB power adapter: 5V/1.2A (more ampere is fine) + Micro USB cable

External hard disk: 500 GB or more with dedicated power supply

Raspberry Pi 3: a tiny computer for less than $40

I used a Raspberry Pi 3 Model B, which is a bit faster than the Pi 2 and has built-in Wifi, and set it up with a 8 GB SD card. To run a Lightning node, the full Bitcoin blockchain must be stored locally, which is ~200 GB and growing. I bought a cheap hard disk enclosure and reused an old 500 GB hard disk that was lying around. I use two power adapters: an old 5v USB mobile phone charger with 1A, and the separate power supply of the hard disk enclosure, as the USB ports of the Raspberry Pi cannot provide enough power to run an external hard disk directly.

2) Write down your passwords

You will need several passwords and I find it easiest to write them all down in the beginning, instead of bumping into them throughout the guide. They should be unique and very secure, at least 12 characters in length. Do not use uncommon special characters, blanks or quotes (‘ or “).

[ A ] User password for “pi”

[ B ] User password for “root”(can be the same as for “pi”)

[ C ] User password for “bitcoin”

[ D ] Bitcoin wallet password

[ E ] Bitcoin RPC password

[ F ] Eclair API password

Store a copy of your passwords somewhere safe (preferably in a password manager like KeePass or LastPast) and keep your original notes out of sight once your system is up and running.

3) Installing the operating system

The node runs headless, without keyboard or display, so the operating system Raspbian Stretch Lite is used. Download the Zip file and follow the installation guide on the Raspberry Pi website.

Enable Secure Shell

As no direct interaction with the Pi is possible during the initial setup, the remote SSH connection needs to be enabled beforehand. After writing the image to the Micro SD card, create an empty file called “ssh” (without extension) on the main directory of the card, so SSH will be enabled from the start. The SD card can now be inserted into the Pi.

Prepare Wifi

If you want to avoid connecting a network cable when first starting the Pi, you can pre-configure the wireless settings:

Create a file “wpa_supplicant.conf” on the MicroSD card with the following content:

country=[COUNTRY_CODE]

ctrl_interface=/var/run/wpa_supplicant GROUP=netdev

update_config=1 network={

ssid=[WIFI_SSID]

psk=[WIFI_PASSWORD]

}

Replace [COUNTRY_CODE] with the ISO2 code of your country (eg. US )

with the ISO2 code of your country (eg. ) Replace [WIFI_SSID] and [WIFI_PASSWORD] for your own WiFi.

Note: if you connect via network cable, you can also configure the Wifi later.

Start your Pi

For the initial setup, the Pi needs to be connected to the home network using a network cable (it can run on Wifi later). With the SD card inserted and a network cable plugged in, start the Pi by connecting it to the mobile phone charger using the Micro USB cable.

4) Connecting to the network

The node is starting and getting a new address from your home network. This address can change over time. To make the Pi reachable from the internet, we assign it a fixed address.

Accessing your router

The fixed address is configured in your network router: this can be the cable modem or the Wifi access point. So we first need to access the router. To find out its address,

start the Command Prompt on a computer that is connected to your home network (in Windows, click on the Start Menu and type cmd directly or in the search box, and hit Enter)

directly or in the search box, and hit Enter) enter the command ipconfig (or ifconfig on Mac / Linux)

(or on Mac / Linux) look for “Default Gateway” and note the address (eg. “192.168.0.1")

👉 additional information: accessing your router.

Now open your web browser and access your router by entering the address, like a regular web address. You need so sign in, and now you can look up all network clients in your home network. One of these should be listed as “raspberrypi”, together with its address (eg. “192.168.0.240”).

Client list in my ASUS router

👉 don’t know your router password? Try routerpasswords.com.

⚠️ If your router still uses the initial password: change it!

Setting a fixed address

We now need to set the fixed (static) IP address for the Pi. Normally, you can find this setting under “DHCP server”. The manual address should be the same as the current address, just change the last part to a lower number (e.g. 192.168.0.240 → 192.168.0.20).

Static IP address assignment in my ASUS router

👉 need additional information? Google “[your router brand] configure static dhcp ip address”

Port Forwarding

Next, “Port Forwarding” needs to be configured. Different applications use different network ports, and the router needs to know to which internal network device the traffic of a specific port has to be directed. The port forwarding needs to be set up as follows:

👉 additional information: setting up port forwarding.

Save and apply these router settings, we will check them later. Disconnect the Pi from the power supply, wait a few seconds, and plug it in again. The node should now get the new fixed IP address.

5) Working on the Raspberry Pi

We are going to work in the command line of the Pi, entering commands and getting results back. To make it clear where a command begins, every command in this guide you need to enter starts with the $ sign. In the following example, just enter “ls -la” and press the enter/return key:

$ ls -la

When you enter commands, you can use the “Tab” key for autocompletion, eg. for commands, directories or filenames.

If you are using Windows and the PuTTY / KiTTY 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.

Connecting

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

Windows: PuTTY (Website)

Mac OS: built-in SSH client (see this article)

Linux: just use the native command, eg. ssh pi@192.168.0.20

Use the following SSH connection settings:

- Host Name: the static address you set in the router, eg. 192.168.0.20

- Port: 22

Accept the server authentication and log in with the username “pi” and password “raspberry”.

👉 additional information: using SSH with Raspberry Pi

Raspi-Config

You are now on the command line of your own Bitcoin node. First we finish the Pi configuration. Enter the following command:

$ sudo raspi-config

First, with (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 name (like “RaspiBolt”) and configure your Wifi connection (Pi 3 only)

Boot Options (3): choose “Desktop / CLI” → “Console”

Localisation (4): set your timezone

Advanced (7): run “Expand Filesystem” and set “Memory Split” to 16

Exit by selecting <Finish>, and <No> as no reboot is necessary

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:

$ sudo apt-get update

$ sudo apt-get upgrade

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

Disabling Swap File

The usage of a swap file can degrade your SD card very quickly. Therefore, we will disable it completely.

$ sudo swapoff --all

$ sudo apt-get remove dphys-swapfile

Adding the service user “bitcoin”

Bitcoin Core 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 [C] and confirm all questions with the enter/return key.

$ sudo adduser bitcoin

And while you’re at it, change the password of the “root” admin user to your password [B].

$ sudo passwd root

Mounting external hard disk

The external hard disk is attached to the file system and can be accessed as a regular folder (this is called “mounting”). The hard disk should be empty and formatted.

Now plug your hard disk into the running Pi, power the drive up and enter the following commands in the command line to identify the partition:

Identify the partition and note the UUID at the left (eg. “12345678”) and the FSTYPE (eg. “exfat”, “ntfs”, “vfat”…)

$ sudo lsblk -o UUID,NAME,FSTYPE,SIZE,LABEL,MODEL

$ sudo apt-get install ntfs-3g

Open the file “/etc/fstab” in the Nano text editor

$ sudo nano /etc/fstab

For FSTYPE “ ntfs ”, add the following (one line), but use the “UUID” noted above, then use Ctrl+O to save, confirm with Enter and use Ctrl+X to exit

UUID= 12345678 /mnt/hdd ntfs defaults,auto,umask=002,gid=bitcoin,users,rw 0 0

”, add the following (one line), but use the “UUID” noted above, then use to save, confirm with Enter and use to exit …or, for FSTYPE “ ext4 ”, add the following:

UUID= 12345678 /mnt/hdd ext4 defaults 0 0

”, add the following: Create the directory to add the hard disk and set the correct owner

$ sudo mkdir /mnt/hdd

Mount all drives, view mounted partitions. Is “/mnt/hdd” listed?

$ sudo mount -a

$ df /mnt/hdd

Navigate to the hard disk and create the directory for Bitcoin testnet.

$ cd /mnt/hdd

$ sudo mkdir bitcoin_testnet

$ ls -l

If this command gives you an error, chances are that your external hard disk is mounted as “read only”. Several readers had issues with that. This must be fixed before proceeding.

Please note that we mounted using umask=002,gid=bitcoin , which gives only the user “bitcoin” write access. User “pi” can only read and must use sudo when writing to the disk.

👉 If your drive is “read-only”, let me know on reddit. As soon as I figure a way to provide an easy, generic approach, I’ll update this guide.

👉 additional information: external storage configuration

6) Hardening your Pi

The following steps need admin privileges and must be executed logged in as the user “pi”.

Enabling the Uncomplicated Firewall

The Pi will be visible from the internet and therefore needs to be secured against attacks. A firewall controls what traffic is permitted and closes possible security holes.

The line ufw allow from 192.168.0.0/24 … below assumes that the IP address of your Pi is something like 192.168.0.??? , the ??? being any number from 0 to 255. If your IP address is 12.34.56.78 , you must adapt this line to ufw allow from 12.34.56.0/24 … .

$ sudo apt-get install ufw

$ sudo su

$ ufw default deny incoming

$ ufw default allow outgoing

$ ufw allow from 192.168.0.0/24 to any port 22 comment 'allow SSH from local LAN'

$ ufw allow 9735 comment 'allow Lightning'

$ ufw allow 18333 comment 'allow Bitcoin testnet'

$ ufw reject 8333 comment 'deny Bitcoin mainnet'

$ ufw enable

$ systemctl enable ufw

$ ufw status

$ exit

👉 additional information: UFW Essentials

fail2ban

The SSH login to the Pi must be especially protected. The firewall blocks all login attempts from outside your network, but additional steps should be taken to prevent an attacker — maybe from inside your network — to just try out all possible password.

The first measure is to install “fail2ban”, a service that cuts off any system with five failed login attempts for ten minutes. This makes a brute-force attack unfeasible, as it would simply take too long.