This article is no longer maintained. Please see up to date instructions on my github page:

https://github.com/seth586/guides/tree/master/FreeNAS

This article is part of a series:

Next: Install electrum personal server in a freenas jail

Goal:

This article outlines how to compile and run Bitcoin Core 0.17.1 (or other release you may wish) on a FreeNAS 11.2 iocage jail, serving public IP and tor connections, with ncurses2 terminal user interface. This will be configured to work with Lightning Lab’s LND in a future article.

Prerequisites:

So, at this point we can assume that you built your home server. Hopefully you were smart enough to follow the hardware recommendation guide. My basic recommendation is this: Make sure you get a server class motherboard that has Internet Protocol Management Interface (IPMI) & supports Error Code Correcting (ECC) ram. I highly recommend 6 hard drives in RAIDZ2 configuration, it is the best space and redundancy for the money. Any amount of drives in RAIDZ1 loses redundancy the moment you have a hard drive failure, and 4 drives in RAIDZ2 only has half the storage capacity of 6 drives in RAIDZ2. If the value proposition is getting pricey, start with smaller hard drives. You can’t add drives to a volume once its setup, however you can replace drives with larger drives, and once all 6 drives are the larger size, you get to increase the size of the volume.

I am assuming you know your way around your router. My example router is a Linksys WRT1900ACv1 running OpenWRT. Your router configuration user interface may be different than explained here.

Lets also assume that you installed FreeNAS on your home server, navigated the FreeNAS forums, read the FreeNAS documentation, and set up a ZFS volume.

Create a Jail:

Think of jails as more efficient virtual machines (VMs). You could just install a bunch of VMs on FreeNAS, run linux on them, and pick your choice on the many varieties of linux guides available online. But running a VM requires a lot more resources than jails, allocating memory just for that VM, etc. Plus, if we mess up, we can delete the jail and start over. Anything we do in the jail should not mess up anything on the host machine. After all, we built a computer with server grade hardware for the uptime!

FreeNAS 11.2 uses iocage to manage jails. Previous versions used warden, which is now considered deprecated. To create a jail, log in to your FreeNAS user interface, and select Jails on the left hand menu. Click the ‘+’ symbol on the top right, and give your jail a name. I decided to call mine bitcoin_node . Under release, select 11.2-RELEASE . Click ‘next’.

Click ‘DHCP Autoconfigure IPv4’, and VNET should automatically be selected. Dynamic Host Configuration Protocol allows your host (your home router) to assign an IP address to your jail. VNET is going to create a virtual Ethernet adapter for your jail. No extra cables required. Now your home router will now see your FreeNAS server and your jail as two separate devices. This comes in very handy later on when we can direct traffic on your router based on the IP address assigned! Click ‘next’

And finally, ‘submit’.

Next, we want to make sure maximum up time for this jail. In the event you have a server reboot, we want the jail to automatically start up as well. Click the ‘⋮’ symbol next to your new jail, and click ‘edit’. Click ‘autostart’, then click ‘save’. Click the ‘⋮’ symbol again, and click ‘start’. Once the start animation goes away, refresh your browser, and you should see the IP address assigned by your router to your new jail.

Congratulations, you just spun up your first jail!

Definitions: IP Range/Subnets/Netmask/MAC/WAN/LAN

As new devices attach and detach from your router, your router will assign different IP addresses. We want to reserve an IP address specifically for our jail. Our router can uniquely identify different ethernet devices based on its ‘media access control’ (MAC) address and reserve an IP address for that MAC address.

Most routers assign 192.168.1.0/24 as the default subnet for private networks. A subnet is a group of computers that share an IP address space. The /24 is called a netmask. A netmask represents a range of IPs. For example, 192.168.1.0/24 represents 254 IP addresses, from 192.168.1.1 to 192.168.1.254. Sometimes /24 is represented as a subnet mask 255.255.255.0. You can play with a subnet mask calculator here.

This subnet, 192.168.1.0/24, represents all of the devices your router logically isolates from the internet. To the internet, you only have 1 IP address that your internet service provider (ISP) assigned to you. Your router logically translates traffic between your home subnet and the internet. Typically your router calls the internet a ‘wide area network’ (WAN) and your home subnet as a ‘local area network’ (LAN).

Optional: Assign a Unique Home Subnet Range

In a later guide we will be setting up a VPN so you can securely access your home network remotely, so for now we’re going to change your home’s subnet to a less common IP range to prevent interfering with remote subnets away from home. We’re doing this now because it prevents having to reconfigure changes we are about to make. Log into your router, and goto Network/Interfaces/LAN

Change the IPv4 address to something like 192.168.XXX.1, where XXX is NOT 0 or 1. I picked 84. You may have to reboot your PC for it to detect the new subnet, and to get a new IP address assigned.

IP Static Lease for our Jail

Now select Network/DHCP and DNS. Here you can see all your LAN devices connected to your router. You should see your bitcoin_node jail listed here, too. Scroll down to ‘static leases’, and create one for our bitcoin_node jail.

Click ‘Save & Apply’.

Forward Port 8333 from the Public Internet Address to our Jail

Your router also provides a ‘firewall’, restricting which ports can communicate between your home subnet and the internet. Think of ports as numerous doors to each IP address. By default your router keeps these doors closed, as much as possible. For other nodes to connect to your node, they need to connect to your public IP address & port, thru the router, to the jail’s subnet IP and port. Opening ports is like opening a door to the world, so we should be careful what ports we open. Consider the following example, I’m just throwing random numbers out for your internet IP address and your home subnet IP assigned to your jail.

(internet IP):(port) — router →(home subnet bitcoincore jail IP):(port)

123.234.165.254:8333 —router — ->192.168.1.123:8333

To make this exception rule in your router’s firewall, we will forward port 8333 to our bitcoincore jail. Login to your openWRT router, and select Network/Firewall/Port Forwards.

Make a new rule, I’ll call it bitcoin_node, using TCP protocol, from external WAN zone port 8333 to internal zone LAN ip address of our bitcoin_node jail at port 8333. Make sure you select the correct IP address assigned to your jail!

Click ‘Save & Apply’.

Your jail’s networking is now configured. Lets install some software!

Secure Socket Shell (SSH) in to the Jail & Compile Bitcoin & Install

SSH is a way to manage your server remotely over a network. When you don’t plug in a monitor & keyboard directly into the server, it’s called a ‘headless’ server. The most popular SSH client is called PuTTY, download it here. Connect to your FreeNAS’ IP address, and log in with your credentials.

Type:

# iocage list

You should see your bitcoin_node jail listed.

iocage console bitcoin_node

You’re in! Lets start installing stuff!

# pkg install autoconf automake boost-libs git gmake libevent libtool libzmq4 openssl pkgconf wget nano tor python3

Go to https://github.com/bitcoin/bitcoin/releases, find the tar.gz release we want to install. The latest release is 0.17.1 at https://github.com/bitcoin/bitcoin/archive/v0.17.1.tar.gz



# tar xzvf v0.17.1.tar.gz # wget https://github.com/bitcoin/bitcoin/archive/v0.17.1.tar.gz # tar xzvf v0.17.1.tar.gz

To see whats in the current directory, type ls (the lack of a / means were in root, you can navigate to root by typing cd /root )

You can see our downloaded file, v0.17.1.tar.gz and the unpacked directory bitcoin-0.17.1 , lets change to that bitcoin directory and configure for compiling.

# cd bitcoin-0.17.1

# sh

# ./contrib/install_db4.sh `pwd`

# export BDB_PREFIX='/root/bitcoin-0.17.1/db4'

# ./autogen.sh

# ./configure MAKE=gmake BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" BDB_CFLAGS="-I${BDB_PREFIX}/include" --without-gui --without-miniupnpc

# gmake check

# gmake install

This process may take a while. Once its done and installed, we need to add a rc.d script to automatically start the bitcoin daemon on start. Read more about FreeBSD rc.d scripting here. FreeBSD ports maintains a startup script we can use at https://github.com/freebsd/freebsd-ports/blob/master/net-p2p/bitcoin/files/bitcoind.in (click on the RAW link to get a direct link to the file)



# wget

# mv bitcoind.in bitcoind

# chmod +x bitcoind # cd /etc/rc.d/# wget https://raw.githubusercontent.com/freebsd/freebsd-ports/master/net-p2p/bitcoin/files/bitcoind.in # mv bitcoind.in bitcoind# chmod +x bitcoind

Lets edit the startup script for our local environment:

nano bitcoind

The %%PREVIX%% variables need to be changed to local paths, and the users needs to be changed to _tor :

command="/usr/local/bin/bitcoind"

: ${bitcoind_user:="_tor"}

: ${bitcoind_group:="_tor"}

: ${bitcoind_config_file:="/root/.bitcoin/bitcoin.conf"}

Now that out startup script is installed, lets enable it in /etc/rc.conf:

sysrc 'bitcoind_enable=yes'

Lets make bitcoin’s configuration file:

mkdir /var/db/bitcoin

mkdir /root/.bitcoin

nano /root/.bitcoin/bitcoin.conf

Add the following lines:

datadir=/var/db/bitcoin

server=1

txindex=1

To save in nano, press CTRL+O, the exit, CTRL+X

Bitcoind Tor Hidden Service

IP addresses are like street addresses, they offer no anonymity. Tor is a network that disguises your actual IP address by encrypting & bouncing data around its network, preventing tracebacks. We will configure bitcoind to communicate on the Tor network as a hidden service, as well as over IP.

# sysrc 'tor_enable=yes'

# nano /usr/local/etc/tor/torrc

Add the following lines to tor’s configuration file

ControlPort 9051

CookieAuthentication 1

CookieAuthFileGroupReadable 1

Save and exit.

Reboot Jail & Verify

Go back to your freenas GUI for your jails. Stop, then start your bitcoin jail. SSH back into your jail, and check the running processes:

# ps auxww

You should see tor and bitcoind running. Use bitcoin-cli to call some information from bitcoind over its Remote Procedure Call (RPC) interface. RPC is how software interacts and operates with the node. getnetworkinfo will reveal your tor address.

# bitcoin-cli getblockchaininfo

# bitcoin-cli getnetworkinfo

Optional: Bitcoind-ncurses2 Terminal User Interface

This is a pretty cool terminal user interface (TUI) that communicates to your node over its RPC interface. It shows interesting data about what your node is doing, among other features.



# pkg install py36-pip python3

# git clone

# pip-3.6 install -r bitcoind-ncurses2/requirements.txt

# python3 /root/bitcoind-ncurses2/main.py --datadir /var/db/bitcoin # cd /root# pkg install py36-pip python3# git clone https://github.com/esotericnonsense/bitcoind-ncurses2 # pip-3.6 install -r bitcoind-ncurses2/requirements.txt# python3 /root/bitcoind-ncurses2/main.py --datadir /var/db/bitcoin

Use CTRL+Z to suspend

Edit: 9/18/2018: Version 0.17.0rc3 superseded by 0.16.3

Edit: 12/18/2019: Update to version 0.17.0.1 & compiles with ZeroMQ for compatibility with Lightning Lab’s lnd.