obfs4proxy bridge deployment guide

This guide will help you run an obfs4 bridge to help censored users connect to the Tor network. The requirements are 1) 24/7 Internet connectivity and 2) the ability to expose TCP ports to the Internet (make sure that NAT doesn't get in the way).

If you're a censored user and need a bridge to connect, please see How to use a PT bridge.

Note: If you're running platforms that are not listed on this page, you should probably ​compile obfs4 from source.

Debian / Ubuntu

Follow the steps below to deploy obfs4proxy on Debian / Ubuntu:

1. Install Tor:
   
   Get the latest version of Tor. If you're on Debian stable, sudo apt-get install tor should give you the latest stable version of Tor.
   

• Note: Ubuntu users need to get it from Tor repository. Please see ​"Download instructions for Ubuntu".
  

2. Install obfs4proxy:
   
   On ​Debian, the obfs4proxy package is available in sid, buster, and stretch. On ​Ubuntu, bionic, cosmic, disco, and eoan have the package. If you're running any of them, sudo apt-get install obfs4proxy should work.
   If not, you can ​build it from source.
   

3. Edit your Tor config file, usually located at /etc/tor/torrc and add the following lines:
   
   

   #Bridge config
   RunAsDaemon 1
   ORPort auto
   BridgeRelay 1
   ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
   # For a fixed obfs4 port (e.g. 34176), uncomment the following line.
   #ServerTransportListenAddr obfs4 0.0.0.0:34176
   # Local communication port between Tor and obfs4. Always set this to "auto". "Ext" means
   # "extended", not "external". Don't try to set a specific port number, nor listen on 0.0.0.0.
   ExtORPort auto
   
   # Contact information that allows us to get in touch with you in case of
   # critical updates or problems with your bridge.  This is optional, so you
   # don't have to provide an email address if you don't want to.
   ContactInfo <address@email.com>
   # Pick a nickname that you like for your bridge.
   Nickname PickANickname
   

Don't forget to change the ContactInfo and Nickname options.

• If you decide to use a fixed obfs4 port smaller than 1024 (for example 80 or 443), you will need to give obfs4 CAP_NET_BIND_SERVICE capabilities to bind the port with a non-root user:

sudo setcap cap_net_bind_service=+ep /usr/bin/obfs4proxy

• Under Debian, you will also need to set NoNewPrivileges=no in /lib/systemd/system/tor@default.service and /lib/systemd/system/tor@.service and then run systemctl daemon-reload. (bug #18356)

• Note that both Tor's OR port and its obfs4 port must be reachable. If your bridge is behind a firewall or NAT, make sure to open both ports.

4. Restart tor: systemctl restart tor.
   
5. Monitor your logs (usually in /var/log/tor/log or /var/log/syslog), to confirm your bridge is running with no issues.
   
   You should see something like this:
   
   

   [notice] Your Tor server's identity key fingerprint is '<NICKNAME> <FINGERPRINT>'
   [notice] Your Tor bridge's hashed identity key fingerprint is '<NICKNAME> <HASHED FINGERPRINT>'
   [notice] Registered server transport 'obfs4' at '[::]:46396'
   [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
   [notice] Bootstrapped 100%: Done
   [notice] Now checking whether ORPort <redacted>:9001 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
   [notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.
   

Remember to open the random port associated with your bridge. You can find it in your tor log; in the above example it is 46396. To use a fixed port, uncomment the ​ServerTransportListenAddr option in your torrc. You can use ​our reachability test to see if your obfs4 port is reachable from the Internet.

CentOS / RHEL / OpenSUSE

Follow the steps below to deploy obfs4proxy on CentOS / RHEL:

1. Install tor and dependencies

• Redhat / RHEL:

  yum install epel-release
  yum install git golang tor
  

• OpenSUSE:

  zypper install tor go git
  

2. Build obfs4proxy and move it into place. (Heavily outdated versions of git can make go get fail, so try upgrading to a more recent git version if you're running into this problem.)

• CentOS / RHEL:

  export GOPATH=`mktemp -d`
  go get gitlab.com/yawning/obfs4.git/obfs4proxy
  sudo cp $GOPATH/bin/obfs4proxy /usr/local/bin/
  chcon --reference=/usr/bin/tor /usr/local/bin/obfs4proxy
  

• OpenSUSE:

  export GOPATH=`mktemp -d`
  go get gitlab.com/yawning/obfs4.git/obfs4proxy
  sudo cp $GOPATH/bin/obfs4proxy /usr/local/bin/
  

3. Edit your Tor config file, usually located at /etc/tor/torrc and add the following lines:

   #Bridge config
   RunAsDaemon 1
   ORPort auto
   BridgeRelay 1
   ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
   # For a fixed obfs4 port (e.g. 34176), uncomment the following line.
   #ServerTransportListenAddr obfs4 0.0.0.0:34176
   # Local communication port between Tor and obfs4. Always set this to "auto". "Ext" means
   # "extended", not "external". Don't try to set a specific port number, nor listen on 0.0.0.0.
   ExtORPort auto
   
   # Contact information that allows us to get in touch with you in case of
   # critical updates or problems with your bridge.  This is optional, so you
   # don't have to provide an email address if you don't want to.
   ContactInfo <address@email.com>
   # Pick a nickname that you like for your bridge.
   Nickname PickANickname
   

Don't forget to change the ContactInfo and Nickname options.

• Note that both Tor's OR port and its obfs4 port must be reachable. If your bridge is behind a firewall or NAT, make sure to open both ports.

4. Restart tor: systemctl restart tor.

5. Monitor your logs (usually in your syslog), to confirm your bridge is running with no issues.
   
   You should see something like this:

[notice] Your Tor server's identity key fingerprint is '<NICKNAME> <FINGERPRINT>'
[notice] Your Tor bridge's hashed identity key fingerprint is '<NICKNAME> <HASHED FINGERPRINT>'
[notice] Registered server transport 'obfs4' at '[::]:46396'
[notice] Tor has successfully opened a circuit. Looks like client functionality is working.
[notice] Bootstrapped 100%: Done
[notice] Now checking whether ORPort <redacted>:9001 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
[notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.

Remember to open the random port associated with your bridge. You can find it in your tor log; in the above example it is 46396. To use a fixed port, uncomment the ​ServerTransportListenAddr option in your torrc. You can use ​our reachability test to see if your obfs4 port is reachable from the Internet.

FreeBSD

Follow the steps below to deploy obfs4proxy on FreeBSD:

1. Install packages

pkg install obfs4proxy-tor tor ca_root_nss

2. Edit your Tor config file, usually located at /usr/local/etc/tor and add the following lines

#Bridge config
RunAsDaemon 1
ORPort auto
BridgeRelay 1
ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
# For a fixed obfs4 port (e.g. 34176), uncomment the following line.
#ServerTransportListenAddr obfs4 0.0.0.0:34176
# Local communication port between Tor and obfs4. Always set this to "auto". "Ext" means
# "extended", not "external". Don't try to set a specific port number, nor listen on 0.0.0.0.
ExtORPort auto

# Contact information that allows us to get in touch with you in case of
# critical updates or problems with your bridge.  This is optional, so you
# don't have to provide an email address if you don't want to.
ContactInfo <address@email.com>
# Pick a nickname that you like for your bridge.
Nickname PickANickname

Log notice file /var/log/tor/notices.log

Don't forget to change the ContactInfo and Nickname options.

• Note that both Tor's OR port and its obfs4 port must be reachable. If your bridge is behind a firewall or NAT, make sure to open both ports.

3. Ensure that the random_id sysctl setting is enabled:

echo "net.inet.ip.random_id=1" >> /etc/sysctl.conf
sysctl net.inet.ip.random_id=1

4. Start the tor daemon and make sure it starts at boot:

sysrc tor_enable=YES
service tor start

5. Monitor your logs (/var/log/tor/notices.log), to confirm your bridge is running with no issues.
   
   You should see something like this:

[notice] Your Tor server's identity key fingerprint is '<NICKNAME> <FINGERPRINT>'
[notice] Your Tor bridge's hashed identity key fingerprint is '<NICKNAME> <HASHED FINGERPRINT>'
[notice] Registered server transport 'obfs4' at '[::]:46396'
[notice] Tor has successfully opened a circuit. Looks like client functionality is working.
[notice] Bootstrapped 100%: Done
[notice] Now checking whether ORPort <redacted>:9001 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
[notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.

Remember to open the random port associated with your bridge. You can find it in your tor log; in the above example it is 46396. To use a fixed port, uncomment the ​ServerTransportListenAddr option in your torrc. You can use ​our reachability test to see if your obfs4 port is reachable from the Internet.

6. To get the fastest package updates, switch from the "quarterly" package repo to the "latest" repo.

Create the following folder:

mkdir -p /usr/local/etc/pkg/repos

Create the file /usr/local/etc/pkg/repos/FreeBSD.conf with the following content:

FreeBSD: { enabled: no }

FreeBSDlatest: {
  url: "pkg+https://pkg.FreeBSD.org/${ABI}/latest",
  mirror_type: "srv",
  signature_type: "fingerprints",
  fingerprints: "/usr/share/keys/pkg",
  enabled: yes
}

OpenBSD

Follow the steps below to deploy obfs4proxy on OpenBSD:

1. Install packages

pkg_add tor obfs4proxy

2. Edit your Tor config file, usually located at /etc/tor/torrc and add the following lines

#Bridge config
RunAsDaemon 1
ORPort auto
BridgeRelay 1
ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
# For a fixed obfs4 port (e.g. 34176), uncomment the following line.
#ServerTransportListenAddr obfs4 0.0.0.0:34176
# Local communication port between Tor and obfs4. Always set this to "auto". "Ext" means
# "extended", not "external". Don't try to set a specific port number, nor listen on 0.0.0.0.
ExtORPort auto

# Contact information that allows us to get in touch with you in case of
# critical updates or problems with your bridge.  This is optional, so you
# don't have to provide an email address if you don't want to.
ContactInfo <address@email.com>
# Pick a nickname that you like for your bridge.
Nickname PickANickname

Log notice file /var/log/tor/notices.log

User _tor

Don't forget to change the ContactInfo and Nickname options.

• Note that both Tor's OR port and its obfs4 port must be reachable. If your bridge is behind a firewall or NAT, make sure to open both ports.

3. Start the tor daemon and make sure it starts at boot:

rcctl enable tor
rcctl start tor

4. Monitor your logs (/var/log/tor/notices.log), to confirm your bridge is running with no issues.
   
   You should see something like this:

[notice] Your Tor server's identity key fingerprint is '<NICKNAME> <FINGERPRINT>'
[notice] Your Tor bridge's hashed identity key fingerprint is '<NICKNAME> <HASHED FINGERPRINT>'
[notice] Registered server transport 'obfs4' at '[::]:46396'
[notice] Tor has successfully opened a circuit. Looks like client functionality is working.
[notice] Bootstrapped 100%: Done
[notice] Now checking whether ORPort <redacted>:9001 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
[notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.

Remember to open the random port associated with your bridge. You can find it in your tor log; in the above example it is 46396. To use a fixed port, uncomment the ​ServerTransportListenAddr option in your torrc. You can use ​our reachability test to see if your obfs4 port is reachable from the Internet.

Post-install

Congrats!

• If you get to this point, it means that your obfs4 bridge is running and is being distributed by BridgeDB to censored users. If you want to connect to your bridge manually, you will need to know the bridge's obfs4 certificate. See the file /var/lib/tor/pt_state/obfs4_bridgeline.txt and paste the entire bridge line into Tor Browser:

  Bridge obfs4 <IP ADDRESS>:<PORT> <FINGERPRINT> cert=<CERTIFICATE> iat-mode=0
  

  You'll need to replace <IP ADDRESS>, <PORT>, and <FINGERPRINT> with the actual values, which you can find in the tor log. Make sure to use <FINGERPRINT>, not <HASHED FINGERPRINT>; and that <PORT> is the one from the log line Registered server transport 'obfs4', not the one from the line Now checking whether ORPort ... is reachable.

• Finally, you can monitor your obfs4 bridge's usage on ​Relay Search. Just enter your bridge's <HASHED FINGERPRINT> in the form and click "Search". After having set up the bridge, it takes approximately three hours for the bridge to show up in Relay Search.

Getting Help

If you run into problems while setting up your relay you can ask your questions on the public tor-relays mailing list:

• ​https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-relays

This is a great resource for asking (and answering) questions, and generally getting to know other relay operators. Make sure to check out the archives!

• irc.oftc.net #tor-relays

This is a great place to meet relay operators, and have real-time discussions