RaspiXUD Guide
This guide is written for market makers & traders to turn a Raspberry Pi into an always-on xud node.
Two options are available:
If you are not sure, we recommend to start with the light setup. If you opt for the Pi4 4GB, you can switch to the full setup at any time.
Pi3 B+: 42,95 €
Pi3 B+ Power Supply: 6,65 €
32GB MicroSD card: 15 €
A performant microSD card is important; not the right place to save some bucks.
For more options, check this storage benchmark list.
USB stick for backups: 3,99 €
Any >1GB USB stick will do.
A NAS/Samba share works too.
Pi4 (4GB): 59,95 €
Pi4 Power Supply: 8,95 €
Pi4 Cooling Case: 15,95 €
Needed! The Pi4 is a hottie.
32GB MicroSD card: 15 €
A performant microSD card is important; not the right place to save some bucks.
For more options, check this storage benchmark list.
USB stick for backups: 3,99 €
Any >1GB USB stick will do.
A NAS/Samba share works too.
1TB external SSD: 180 €
For full setup only, not needed for light setup!
For more options, check this storage benchmark list.
Download Ubuntu 20.04 64-bit for the Pi onto your computer. Any other 64-bit (also called
arm64,aarch64,armv8) linux os for the Pi is fine. 32-bit (armv7) is currently not supported. This guide was written assumingUbuntu 20.04 LTS.Insert the microSD card into your computer and follow the flash instructions.
Optional: If you don't have a screen, usb keyboard and even an ethernet cable available, you can pre-configure Wifi for a headless setup.
# on your linux computer, cd to the mounted microSD card partition "writable" and copy the wifi sample file. If you can't see any partition called "writable", then you are probably running something other than linux and need to figure out how to mount an ext4 filesystem.sudo cp ./usr/share/doc/netplan/examples/wireless.yaml ./etc/netplan/# open the file to editsudo nano ./etc/netplan/wireless.yaml# strip down the file to the bare minmum for the Pi to get an IP automatically assigned by your routernetwork:version: 2wifis:wlan0:dhcp4: yesdhcp6: noaccess-points:"<YOUR WIFI SSID>":password: "<YOUR WIFI PASSWORD>"# if you can't access your router to read out your Pi's IP, you can also configure a static IP nowaddresses: [192.168.1.42/24]gateway4: 192.168.1.1nameservers:addresses: [192.168.1.1, 8.8.8.8]# CTRL+S, CTRL+X.Insert the microSD card into your Pi, connect it to your router via ethernet cable and to a power supply. Connecting a screen via HDMI and a USB keyboard makes life easier, but checking the assigned IP in your router and SSHing in from your computer works too.
Follow the inital setup instructions. Default user + password is
ubuntu. You will be asked to change the password on first login.Update ubuntu via
sudo apt update && sudo apt upgradeIf you are using Ubuntu 20.04 LTS, install docker by running
sudo apt install docker.io. Otherwise if you are using any version besides Ubuntu 20.04, follow the official instructions (selectarm64in step 4 of "Set up the repository") to install docker.Add new user
xud:ubuntu@ubuntu:~$ sudo adduser xudAdding user `xud' ...Adding new group `xud' (1001) ...Adding new user `xud' (1001) with group `xud' ...Creating home directory `/home/xud' ...Copying files from `/etc/skel' ...New password:Retype new password:passwd: password updated successfullyChanging the user information for xudEnter the new value, or press ENTER for the defaultFull Name []:Room Number []:Work Phone []:Home Phone []:Other []:Is the information correct? [Y/n] ubuntu@ubuntu:~$ YAdd the
xuduser to the sudo group (advanced users can skip this and use another user to run sudo commands), the docker group and test if docker is working:ubuntu@ubuntu:~$ sudo usermod -aG sudo xudubuntu@ubuntu:~$ sudo usermod -aG docker xud# switch to user xudubuntu@ubuntu:~$ sudo su - xudxud@ubuntu:~$ docker run hello-worldHello from Docker!This message shows that your installation appears to be working correctly.Looking good! Optionally, add an alias to enter your xud environment by simply typing "xud":
xud@ubuntu:~$ sudo nano ~/.bash_aliases# add the linealias xud='bash ~/xud.sh'# CTRL+S, CTRL+X. Then runxud@ubuntu:~$ source ~/.bashrcConnect the USB stick to your Pi and set it up. It is very important to do this for a mainnet setup (given you do not want to loose money)!
# check the USB stick's path withxud@ubuntu:~$ ls -la /dev/ | grep sdcrw------- 1 root root 2, 61 Dec 3 16:27 ptysdbrw-rw---- 1 root disk 8, 0 Dec 3 16:27 sdabrw-rw---- 1 root disk 8, 1 Dec 3 16:27 sda1 #this is your USB Stickcrw------- 1 root root 3, 61 Dec 3 16:27 ttysd# set it to automount via fstabxud@ubuntu:~$ sudo nano /etc/fstab# add the line/dev/sda1 /media/USB ext4 defaults 0 2# CTRL+S, CTRL+X. Then mount itxud@ubuntu:~$ sudo mkdir /media/USBxud@ubuntu:~$ sudo mount -a# check if mounting workedxud@ubuntu:~$ df -h# make sure xud can use itxud@ubuntu:~$ sudo chown xud:xud /media/USBFrom here the light and full setup require different settings. Continue choosing one.
If you are using a Pi model with 2GB of RAM or more, you can continue here. If you are using a Pi model with <2GB of RAM, we will have to catch a temporary RAM spike when creating the xud environment by creating a swap file (overflow RAM) of 2GB on the internal sd card:
# create the swap filexud@ubuntu:~$ sudo fallocate -l 2G /home/xud/swapfile# mark it as swap filexud@ubuntu:~$ sudo chmod 600 /home/xud/swapfile && sudo mkswap /home/xud/swapfile# enable itxud@ubuntu:~$ sudo swapon /home/xud/swapfile# set it to automount via fstabxud@ubuntu:~$ sudo nano /etc/fstab# add the line/home/xud/swapfile none swap sw 0 0# # CTRL+S, CTRL+X. Let's verify it's working & rebootxud@ubuntu:~$ sudo swapon --showNAME TYPE SIZE USED PRIO/home/xud/swapfile file 2G 0B -2xud@ubuntu:~$ sudo reboot# after reboot, let's check if the swapfile is still activexud@ubuntu:~$ sudo swapon --showNAME TYPE SIZE USED PRIO/home/xud/swapfile file 2G 0B -2
Light setup - DONE! Continue here.
Connect the SSD to your Pi4 and set it up:
# let's check the SSD's pathxud@ubuntu:~$ ls -la /dev/ | grep sdcrw------- 1 root root 2, 61 Dec 3 16:27 ptysdbrw-rw---- 1 root disk 8, 0 Dec 3 16:27 sdabrw-rw---- 1 root disk 8, 1 Dec 3 16:27 sda1 #this is your USB Stickbrw-rw---- 1 root disk 8, 16 Jan 28 10:45 sdbbrw-rw---- 1 root disk 8, 17 Jan 28 10:45 sdb1 #this is your SSDcrw------- 1 root root 3, 61 Dec 3 16:27 ttysd# set it to automount via fstabxud@ubuntu:~$ sudo nano /etc/fstab# add the line/dev/sdb1 /media/SSD ext4 defaults 0 2# CTRL+S, CTRL+X. Then mount itxud@ubuntu:~$ sudo mkdir /media/SSDxud@ubuntu:~$ mount -a# check if mounting workedxud@ubuntu:~$ df -h# make sure xud can use it without sudo privilegesxud@ubuntu:~$ sudo chown xud:xud /media/SSD
Let's do a quick performance test of the SSD. If you are close to these values, you are good to go, whereas <100 MB/s would be too slow:
xud@ubuntu:~$ sudo dd if=/dev/zero of=/media/SSD/deleteme.dat bs=32M count=64 oflag=direct64+0 records in64+0 records out2147483648 bytes (2.1 GB, 2.0 GiB) copied, 12.8709 s, 167 MB/sxud@ubuntu:~$ sudo dd if=/media/SSD/deleteme.dat of=/dev/null bs=32M count=64 iflag=direct64+0 records in64+0 records out2147483648 bytes (2.1 GB, 2.0 GiB) copied, 15.5791 s, 138 MB/sxud@ubuntu:~$ sudo rm /media/SSD/deleteme.dat
Important: geth needs loads of RAM when syncing, so we need to create a swap file (overflow RAM) of 8GB on the external SSD:
# create a swap file on the SSD, we recommend a size of 8GBxud@ubuntu:~$ sudo fallocate -l 8G /media/SSD/swapfile# mark it as swap filexud@ubuntu:~$ sudo chmod 600 /media/SSD/swapfile && sudo mkswap /media/SSD/swapfile# enable itxud@ubuntu:~$ sudo swapon /media/SSD/swapfile# set it to automount via fstabxud@ubuntu:~$ sudo nano /etc/fstab# add the line/media/SSD/swapfile none swap sw 0 0# # CTRL+S, CTRL+X. Let's verify it's working & rebootxud@ubuntu:~$ sudo swapon --showNAME TYPE SIZE USED PRIO/media/SSD/swapfile file 8G 0B -2xud@ubuntu:~$ sudo reboot# after reboot, let's check if the swapfile is still activexud@ubuntu:~$ sudo swapon --showNAME TYPE SIZE USED PRIO/media/SSD/swapfile file 8G 0B -2
Full setup - DONE! Continue here.
