obfs4proxy bridge deployment guide

This guide will help you run an obfs4 bridge to help censored users connect to the Tor network.

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:
   
   obfs4proxy package is available on sid, stretch and jessie. If you're running any of them, sudo apt-get install obfs4proxy should work.
   If not, you can either add deb http://deb.torproject.org/torproject.org obfs4proxy main to your sources.list or ​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 9001
   BridgeRelay 1
   ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
   # For a fixed obfs4 port (i.e. 9002), uncomment the following line.
   #ServerTransportListenAddr obfs4 0.0.0.0:9002
   # 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
   
   #Set your bridge nickname and contact info
   ContactInfo <your-contact-info>
   Nickname pick-a-nickname
   

Don't forget to change contactinfo and nickname values.

• 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)

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

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

• CentOS / RHEL:

  export GOPATH=`mktemp -d`
  go get git.torproject.org/pluggable-transports/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 git.torproject.org/pluggable-transports/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 9001
   BridgeRelay 1
   ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
   # For a fixed obfs4 port (i.e. 9002), uncomment the following line.
   #ServerTransportListenAddr obfs4 0.0.0.0:9002
   # 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
   
   #Set your bridge nickname and contact info
   ContactInfo <your-contact-info>
   Nickname pick-a-nickname
   

Don't forget to change contactinfo and nickname values.

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

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 9001
BridgeRelay 1
ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
# For a fixed obfs4 port (i.e. 9002), uncomment the following line.
#ServerTransportListenAddr obfs4 0.0.0.0:9002
# 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

#Set your bridge nickname and contact info
ContactInfo <your-contact-info>
Nickname pick-a-nickname

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

Don't forget to change contactinfo and nickname values.

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/notice.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

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 9001
BridgeRelay 1
ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
# For a fixed obfs4 port (i.e. 9002), uncomment the following line.
#ServerTransportListenAddr obfs4 0.0.0.0:9002
# 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

#Set your bridge nickname and contact info
ContactInfo <your-contact-info>
Nickname pick-a-nickname

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

User _tor

Don't forget to change contactinfo and nickname values.

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

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.

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