Tor Project | Compile and run WebTunnel from the source

This guide will help you set up a WebTunnel bridge compiled from the source to help censored users connect to the Tor network.

0. Configure your domain and web server

Before you proceed with the instructions below, it's necessary to configure your domain and web server first. Refer to the first part of the WebTunnel guide to see how to set up your web server.

1. Install Golang

To build the WebTunnel server binary, you need to install Golang. You can install Go on Debian by running:

$ sudo apt install golang

2. Clone and compile

Clone the WebTunnel git repository:

$ git clone https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/webtunnel

And compile the WebTunnel server binary:

$ cd webtunnel/main/server
$ go build

Finally, copy the binary to another location:

$ sudo cp server /usr/local/bin/webtunnel

3. Install Tor

On a Debian-like system, install Tor from the Tor Debian repository.

$ sudo apt install apt-transport-https lsb-release

And run these commands to enable the Tor Debian repository:

$ CODENAME=$(lsb_release -cs)

$ cat <<EOF > /etc/apt/sources.list.d/tor.list
   deb     [signed-by=/usr/share/keyrings/tor-archive-keyring.gpg] https://deb.torproject.org/torproject.org $CODENAME main
   deb-src [signed-by=/usr/share/keyrings/tor-archive-keyring.gpg] https://deb.torproject.org/torproject.org $CODENAME main
EOF

Import the Tor Project keyring:

$ wget -qO- https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --dearmor | sudo tee /usr/share/keyrings/tor-archive-keyring.gpg >/dev/null

Finally, update your package list and install Tor:

$ sudo apt update && sudo apt install tor deb.torproject.org-keyring -y

4. Edit your torrc

Edit your Tor config file, usually located at /etc/tor/torrc and replace its contents with:

url=https://yourdomain/path with your WebTunnel url including your domain and secret path;
<address@email.com> with your contact email address;
Nickname WebTunnetTest with the nickname of your bridge.

BridgeRelay 1
ORPort 127.0.0.1:auto
AssumeReachable 1
ServerTransportPlugin webtunnel exec /usr/local/bin/webtunnel
ServerTransportListenAddr webtunnel 127.0.0.1:15000
ServerTransportOptions webtunnel url=https://yourdomain/path
ExtORPort auto
ContactInfo <address@email.com>
Nickname WebTunnelTest
SocksPort 0

5. Restart Tor

Enable and Start tor:

$ sudo systemctl enable --now tor.service

Or restart it if it was running already, so configurations take effect:

$ sudo systemctl restart tor.service

6. Edit and reload AppArmor tor permission

To allow tor to run your WebTunnel binary, edit the AppArmor system_tor profile at /etc/apparmor.d/system_tor and add an entry allowing tor to execute WebTunnel:

  # During startup, tor (as root) tries to open various things such as
  # directories via check_private_dir().  Let it.
  /usr/local/bin/webtunnel ix,

Reload the AppArmor profile:

$ sudo apparmor_parser -r /etc/apparmor.d/system_tor

After modifying the profile and reloading it, test to see if the tor process can now execute /usr/local/bin/webtunnel without any AppArmor denials. Check the system logs (e.g., dmesg or /var/log/syslog) to ensure the error doesn't reappear.

7. Monitor your logs

To confirm your bridge is running with no issues, you should see something like this (usually in /var/log/syslog or run sudo journalctl -e -u tor@default):

[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] Tor has successfully opened a circuit. Looks like client functionality is working.
[notice] Bootstrapped 100%: Done

You can monitor your WebTunnel 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.

8. Final notes

Your WebTunnel bridge will by default be automatically distributed via the Bridges website, also known as the HTTPS distributor. This default applies unless an operator explicitly configures the BridgeDistribution setting in the torrc file to a different option. If set to any option other than HTTPS, the bridge will not be distributed to users. If you are having trouble setting up your bridge, have a look at our help section.

If your bridge is now running, you can test it by copying and pasting your bridge line into Tor Browser. To build your WebTunnel bridge line, you need to copy your bridge FINGERPRINT, but don't confuse it with your hashed fingerprint, which is the fingerprint that you will find on the Tor Relay Search website. If you copy the hashed fingerprint instead of your bridge fingerprint, you won't be able to connect. You can find your bridge fingerprint in the /var/lib/tor/fingerprint file. Remember to copy only the fingerprint and do not include the bridge nickname.

Finally, you can replace the URL contents with your domain and secret path. You can find this in your torrc line under ServerTransportOptions.

Now, just replace the content below to create your WebTunnel bridge line:

webtunnel 10.0.0.2:443 FINGERPRINT url=https://yourdomain/path

Back to previous page: WebTunnel Bridge - Edit this page