How to run a Tor bridge relay with obfs4

[steersman]

So, I just spent a few hours figuring this out. I didn't see a single, consolidate set of instructions anywhere on the web, so I thought it'd write it up for others to benefit.

The steps below were created while using FreeNAS 9.10.1-U4 and not any other version. There are a couple of FreeNAS-specific steps, but I suspect most of the steps below can be used in plain FreeBSD.

A couple of steps also refer to bugs that currently exist in FreeNAS 9.10. So, those steps may be unnecessary in the future or for older versions of FreeNAS.

1. Log in to your FreeNAS console and create a jail for Tor.
   1. Name your jail. I named my jail "tor".
      
   2. Enter "DHCP" (without quotes) in the IPv4 textbox. On FreeNAS 9.10.1-U2+, there's a bug (Bug #17016) that prevents the DHCP checkbox from working on the Add Jail form.
   3. In the sysctls box, add allow.raw_sockets=1. I don't remember where, but I've read that this is required for jails (or Tor within a jail?) to access the outside network.
   4. The Tor installer (you'll see later) recommends adding net.inet.ip.random_id=1, too. Though, I haven't played with this, myself. A small description of randome_id can be found here: https://mebsd.com/freebsd-security-hardening/protecting-freebsd-with-sysctl-101.html
   5. I used the defaults for all other jail settings.
2. After the jail has been created, start DHCP. Because of Bug #14638, DHCP won't start automatically on new jails.
   
   1. Open FreeNAS's SSH console for your new jail, lookup the network interface name, and then configure DHCP for that interface:
      # look for an interface named epairXX
ifconfig
# configure DHCP; replace XX with the real interface name
dhclient epairXX
   2. According to other forum threads, restarting FreeNAS should automatically assign an IP address to your jail, but restarting the jail will not.
3. Enable SSH access to your jail by following the docs: http://doc.freenas.org/9.10/jails.html#accessing-a-jail-using-ssh
   1. Theoretically, this isn't a requirement; you could continue to use the SSH console in the FreeNAS UI, but I much prefer using a true SSH client.
4. SSH into your jail with your new SSH credentials.
5. Update FreeBSD ports.
   su
portsnap fetch extract
# honestly, I'm not sure if `fetch update' is necessary, but I did it anyway
portsnap fetch update
6. Install tor and go (to build obfs4proxy), then build and install obfs4proxy (obfs4 build step is from https://github.com/Yawning/obfs4#installation):
   cd /usr/ports/security/tor
make install clean
cd /usr/ports/lang/go
make install clean
# GOPATH is an environment variable required by `go' to store packages, libraries, and such
setenv GOPATH "$HOME/go"
mkdir $GOPATH
cd $GOPATH
go get git.torproject.org/pluggable-transports/obfs4.git/obfs4proxy
cp $GOPATH/bin/obfs4proxy /usr/local/bin
7. Allow the Tor service to run on startup by setting tor_enable="YES" in /etc/rc.conf (similar to how you enabled SSH, above).
8. Create a Tor control password. Tor's control port allows a user to control the Tor process, so you'll want to lock that down. Save the plaintext password and hashed password somewhere safe!
   tor --hash-password <control password>
9. Configure your Tor server by editing /usr/local/etc/tor/torrc. I'm pasting my settings below. You should checkout the Tor manual, yourself, for an explanation of each setting and possibly other settings that might interest you.
   SOCKSPort 0
Log notice file /var/log/tor/notices.log
RunAsDaemon 1
ControlPort 9051
HashedControlPassword <hashed control password>
ORPort 9001
Nickname <relay nickname>
ContactInfo <your name> <your obfuscated email address>
ExitRelay 0
BridgeRelay 1
PublishServerDescriptor 0
## Use obfs4 transport plugin for obfuscation.
ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
ExtORPort auto
10. Start Tor!
    service tor start
11. Open ORPort in your firewall. This step will differ for everyone. Lookup your router's instructions for opening ports in the firewall.
12. Open the Tor log and look for a few important pieces:
    1. [notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. tells you that Tor is reachable.
    2. [notice] Your Tor server's identity key fingerprint is '<relay nickame> <fingerprint>' tells a couple of necessary connection parameters. Take note of the fingerprint!
       
    3. [notice] Registered server transport 'obfs4' at '[::]:<obfs4 port>' tells you that obfs4proxy started and is listening. Take note of the port number!
13. Lookup the obfs4 cert and iat-mode from obfs4_bridgeline.txt. These two pieces of info are required to connect to your bridge. You may also want to edit this file to record your IP address, listening port, and fingerprint for easier sharing later.
    # take note of the cert and iat-mode
cat /var/db/tor/pt_state/obfs4_bridgeline.txt

Now, in your Tor client (e.g. Tor Browser Bundle), provide your bridge's IP address, port, fingerprint, cert, and iat-mode in this format:
obfs4 <ip address>:<obfs4 port> <fingerprint> cert=<cert> iat-mode=<mode>

Boom. You're done. At least this is what worked for me.

Please note: Because I'm running a private bridge, I use PublishServerDescriptor 0 in my torrc and I don't set any bandwidth limits. If you want to donate your bandwidth to the Tor network, set PublishServerDescriptor 1 and please check out the bandwidth-related options from the Tor manual.

 

[steersman]

It's also worth noting that this is not a set-it-and-forget-it thing. The nature of Tor means that it's constantly under attack and therefore constantly on the move. I highly recommend joining at least the tor-announce and possibly the tor-relay mailing list to keep up with Tor.