RaspiXUD Guide

This guide is written for market makers & traders to turn a Raspberry Pi into an always-on xud node.

RaspiXUD setup (plants are optional)

Two options are available:

  1. Light setup using Neutrino and Infura. This keeps the setup light-weight & cheap, but requires to trust entities like Infura.

  2. Full setup using bitcoind, litecoind and geth. Requires more resources and an SSD, but keeps the setup trustless.

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.

Reference Shopping List (Spain)

Pi Basic Setup

  1. Download Ubuntu 64-bit for the Pi on 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.

  2. Insert the microSD card into your computer and follow the flash instructions.

  3. 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 edit
    sudo nano ./etc/netplan/wireless.yaml
    # strip down the file to the bare minmum for the Pi to get an IP automatically assigned by your router
    network:
    version: 2
    wifis:
    wlan0:
    dhcp4: yes
    dhcp6: no
    access-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 now
    addresses: [192.168.1.42/24]
    gateway4: 192.168.1.1
    nameservers:
    addresses: [192.168.1.1, 8.8.8.8]
    # CTRL+S, CTRL+X.
  4. 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.

  5. Follow the inital setup instructions. Default user + password is ubuntu. You will be asked to change the password on first login.

  6. Update ubuntu via sudo apt update && sudo apt upgrade

  7. Install docker following the official instructions (select arm64 in step 4 of "Set up the repository"). At the time of writing, ubuntu 19.10 was still not supported in the official docker repos. If you see an error along the lines 'docker-ce' has no installation candidate, run this to set up the repository instead:

    sudo add-apt-repository \
    "deb [arch=arm64] https://download.docker.com/linux/ubuntu \
    disco \
    stable"
  8. Add new user xud:

ubuntu@ubuntu:~$ sudo adduser xud
Adding 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 successfully
Changing the user information for xud
Enter the new value, or press ENTER for the default
Full Name []:
Room Number []:
Work Phone []:
Home Phone []:
Other []:
Is the information correct? [Y/n] ubuntu@ubuntu:~$ Y
  1. Add the xud user 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 xud
    ubuntu@ubuntu:~$ sudo usermod -aG docker xud
    # switch to user xud
    ubuntu@ubuntu:~$ sudo su - xud
    xud@ubuntu:~$ docker run hello-world
    Hello from Docker!
    This message shows that your installation appears to be working correctly.
  2. Looking good! Optionally, add an alias to enter your xud environment by simply typing "xud":

    xud@ubuntu:~$ sudo nano ~/.bash_aliases
    # add the line
    alias xud='bash ~/xud.sh'
    # CTRL+S, CTRL+X. Then run
    xud@ubuntu:~$ source ~/.bashrc
  3. Connect 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 with
    xud@ubuntu:~$ ls -la /dev/ | grep sd
    crw------- 1 root root 2, 61 Dec 3 16:27 ptysd
    brw-rw---- 1 root disk 8, 0 Dec 3 16:27 sda
    brw-rw---- 1 root disk 8, 1 Dec 3 16:27 sda1 #this is your USB Stick
    crw------- 1 root root 3, 61 Dec 3 16:27 ttysd
    # set it to automount via fstab
    xud@ubuntu:~$ sudo nano /etc/fstab
    # add the line
    /dev/sda1 /media/USB ext4 defaults 0 2
    # CTRL+S, CTRL+X. Then mount it
    xud@ubuntu:~$ sudo mkdir /media/USB
    xud@ubuntu:~$ sudo mount -a
    # check if mounting worked
    xud@ubuntu:~$ df -h
    # make sure xud can use it
    xud@ubuntu:~$ sudo chown xud:xud /media/USB
  4. Light setup - DONE! Continue here.

Pi Full Setup

  1. Connect the SSD to your Pi4 and set it up:

    # let's check the SSD's path
    xud@ubuntu:~$ ls -la /dev/ | grep sd
    crw------- 1 root root 2, 61 Dec 3 16:27 ptysd
    brw-rw---- 1 root disk 8, 0 Dec 3 16:27 sda
    brw-rw---- 1 root disk 8, 1 Dec 3 16:27 sda1 #this is your USB Stick
    brw-rw---- 1 root disk 8, 16 Jan 28 10:45 sdb
    brw-rw---- 1 root disk 8, 17 Jan 28 10:45 sdb1 #this is your SSD
    crw------- 1 root root 3, 61 Dec 3 16:27 ttysd
    # set it to automount via fstab
    xud@ubuntu:~$ sudo nano /etc/fstab
    # add the line
    /dev/sdb1 /media/SSD ext4 defaults 0 2
    # CTRL+S, CTRL+X. Then mount it
    xud@ubuntu:~$ sudo mkdir /media/SSD
    xud@ubuntu:~$ mount -a
    # check if mounting worked
    xud@ubuntu:~$ df -h
    # make sure xud can use it without sudo privileges
    xud@ubuntu:~$ sudo chown xud:xud /media/SSD
  2. Let's do a quick performance test of the SSD. If you are close to these values, you are good to go, whereas <50MB/s (write/read) would be too slow:

    xud@ubuntu:~$ sudo dd if=/dev/zero of=/media/SSD/deleteme.dat bs=32M count=64 oflag=direct
    64+0 records in
    64+0 records out
    2147483648 bytes (2.1 GB, 2.0 GiB) copied, 12.8709 s, 167 MB/s
    xud@ubuntu:~$ sudo dd if=/media/SSD/deleteme.dat of=/dev/null bs=32M count=64 iflag=direct
    64+0 records in
    64+0 records out
    2147483648 bytes (2.1 GB, 2.0 GiB) copied, 15.5791 s, 138 MB/s
    xud@ubuntu:~$ sudo rm /media/SSD/deleteme.dat
  3. 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 8GB
    xud@ubuntu:~$ sudo fallocate -l 8G /media/SSD/swapfile
    # mark it as swap file
    xud@ubuntu:~$ sudo chmod 600 /media/SSD/swapfile && sudo mkswap /media/SSD/swapfile
    # enable it
    xud@ubuntu:~$ sudo swapon /media/SSD/swapfile
    # set it to automount via fstab
    xud@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 & reboot
    xud@ubuntu:~$ sudo swapon --show
    NAME TYPE SIZE USED PRIO
    /media/SSD/swapfile file 8G 0B -2
    xud@ubuntu:~$ sudo reboot
    # after reboot, let's check if the swapfile is still active
    xud@ubuntu:~$ sudo swapon --show
    NAME TYPE SIZE USED PRIO
    /media/SSD/swapfile file 8G 0B -2
  4. Full setup - DONE! Continue here.