How to add a Tor Hidden Service (.onion) to your website running on Ubuntu/Debian Linux

---

Frequently Asked Questions

Q: I hear most hosts block Tor! Won't I get banned if I run Tor to add a hidden service to my site?

A: Short answer: NO, you will be fine.

Hosting providers generally only disallow Tor exit nodes, which are Tor nodes that are configured to act as an open proxy for the Tor network, allowing anonymous traffic to flow through the Tor node's public IP address(es), which can include abusive traffic.

Some hosting providers may block Tor relays despite the fact they don't generate any abusive traffic. This can be either due to the risk of getting your server's IP blacklisted by incompetent service administrators who blanket ban all IP addresses linked to Tor (including non-exit relays) - or due to the constant, high volume of traffic that a relay can generate.

To run a hidden service, you DO NOT need to run a relay nor exit. By default, Tor comes with a locked down configuration with everything disabled, to ensure that when you install Tor, it only acts as a relay/exit if you specifically configure it to do so.

A Tor node for just a hidden service acts as a client on the Tor network, it doesn't require any ports to be opened/forwarded, and it should produce only minimal background traffic. The only non-negligible traffic that the Tor node should generate, will be from serving requests to your visitors who are using your website's Hidden Service.

This means you can run a hidden service on almost all hosting providers without any complaints or abuse problems.

Q: How can I tell if someone is browsing my site / service using the hidden service?

A: If you have access logs enabled, their IP address will appear as 127.0.0.1 or 0.0.0.0. They'll also generally send your onion address in the Host field.

Q: Do I need an SSL certificate for my onion address?

A: No. Hidden service traffic is end-to-end encrypted by nature. Your .onion address is actually a public key, and your server holds the private key in the HiddenServiceDir (usually inside a folder under /var/lib/tor), ensuring all traffic is encrypted between clients and your server automatically, by nature of the Tor hidden service protocol.

---

---

Requirements

This guide assumes that your server is running on a Debian-based Linux distro such as Ubuntu Server, Debian, Linux Mint, or other Debian distros (if your package manager is apt / aptitude then it's probably Debian based)

• A Debian-based Linux server (dedicated or virtual) - Generally Ubuntu Server or Debian
• Root access to the server
• A configured web server (this guide covers Nginx and Caddy)
• At least 256mb of RAM minimum (may work with less)
• Basic knowledge of the Linux terminal

Tor runs on other operating systems such as Windows, BSD, Mac OSX, and non-Debian based Linux distros, but this guide will not be covering installation for non-Debian based platforms.

You should also become root - all commands should be ran under the root user unless otherwise stated.

To become root - if you're not already, enter the following command, including the -

sudo su -

You should now be logged in as root. Your terminal prompt may look something like this:

root@yourserver: ~/ #

Install Tor

Install apt-transport-https + gpg

TorProject uses https (SSL) for their package repositories. On many Ubuntu/Debian Linux distributions, the package required for using https apt repos isn't installed.

You may also need the gpg to import their package signing key.

To ease the process of adding TorProject's official apt repository, you should also make sure that software-properties-common is installed.

Run the following commands to install gpg, software-properties-common and apt-transport-https - it won't hurt anything if you've already got them installed:

apt update
apt install -y gpg apt-transport-https software-properties-common

Import TorProject's GPG public signing key

Next, you'll need to download and import TorProject's package signing GPG public key. TorProject signs their pre-built Tor packages with their signing private key, which allows you to verify that the packages are safe and haven't been tampered with, by verifying their signature using their public key. The signature verification is done automatically by apt.

If you receive warnings that the key has been revoked or is expired, then you should check the official TorProject install instructions to find the latest key.

To install the TorProject public signing key:

curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import

gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | apt-key add -

Add the TorProject apt repository

The tool apt-add-repository allows you to easily add a new apt repository, and will automatically fill out your distro and version to obtain the correct package for your OS.

We also add the -s argument to add the deb-src repo alongside the deb repo, as recommended by TorProject

To add TorProject's apt repository:

apt-add-repository -s https://deb.torproject.org/torproject.org

Install Tor

Now that your system is setup to download the Tor server packages from TorProject, we can install Tor :)

To install Tor:

apt update
apt install -y tor

Prepare your web server

Configuring Nginx

Locate the Nginx site config which you want to point the hidden service to.

The default Nginx site config is /etc/nginx/sites-enabled/default - so for this example we're going to use that.

Open up the file /etc/nginx/sites-enabled/default in your editor of choice (If you're not sure, use nano)

nano /etc/nginx/sites-enabled/default

Add the following 2 lines in your server { block, below your existing listen statements (see example screenshot):

listen 8181;
listen [::]:8181;

Save and close the file. If you're using nano, hold CTRL and press X, press Y to agree to saving the file, and then press enter when it asks for the filename.

Now restart Nginx so that it starts listening on 8181:

systemctl restart nginx

Configuring Caddy

Open your Caddyfile, normally at /etc/caddy/Caddyfile

nano /etc/caddy/Caddyfile

Add a space after your existing domain(s), and add :8181 to make Caddy listen on port 8181 without automatic HTTPS or hostname locking. For example:

hs-example.privex.cc:443 :8181

Configuring Tor

Enabling a Hidden Service (.onion) in /etc/tor/torrc

Open up the file /etc/tor/torrc in your editor of choice (If you're not sure, use nano)

nano /etc/tor/torrc

Use your arrow keys to scroll down until you see the HiddenService section.

Add the following lines anywhere within that section (see the screenshot for an example):

HiddenServiceDir /var/lib/tor/mywebsite/
HiddenServicePort 80 127.0.0.1:8181

Save and close the file. If you're using nano, hold CTRL and press X, press Y to agree to saving the file, and then press enter when it asks for the filename.

Now, restart Tor

systemctl restart tor

Find out and test your hidden service URL (.onion address)

Assuming that you set your HiddenServiceDir to /var/lib/tor/mywebsite/ - use cat to read the hostname file within your hidden service folder:

cat /var/lib/tor/mywebsite/hostname

In our case, the following onion address was outputted:

╭─root at hs-test in ~ using
╰─○ cat /var/lib/tor/mywebsite/hostname
k2um5kmvdhvxfwzsaa2vlc5nx422u2zlenwjwapl47pdyf3y577xr4ad.onion

Open up Tor browser, and enter your onion address into the URL bar.

It may take up to 60 seconds to load for the first time.

Once it loads, you should see your website :)

Additional web server configuration

Add your onion address to your web server's list of domains

For nginx, add your .onion domain to your existing server_name - which is a space separated list of domains that this site config is responsible for.

For Caddy, you should not add your .onion domain, as Caddy will attempt to obtain SSL for it - which will not work, as onion addresses are not supported by LetsEncrypt. Simply use :8181 as previously shown in the guide.

Add an Onion-Location header or meta tag to inform Tor users about your hidden service

The best way to setup Onion-Location is by adding a header in your web server.

For Nginx, you should add the following to each location { block, replacing YOUR_ADDRESS.onion with your actual onion address:

add_header Onion-Location "http://YOUR_ADDRESS.onion$request_uri" always;

Test your Onion-Location by browsing to your normal website

WARNING: TorBrowser will not trust the Onion-Location header or meta tag if your site does not have HTTPS (SSL). This is to protect against malicious Tor exit nodes advertising fake attacker-controlled hidden services by intercepting non-HTTPS requests.

Once you've finished configuring your web server, restart the web server, and then browse to your normal internet website using Tor browser.

Assuming your web server is advertising the header correctly (or you've added the meta tag), and your domain is using HTTPS (SSL), you should see a purple .onion available button in the address bar.

Click on the purple button, and it should bring you to your hidden service.

If your Onion-Location is configured correctly, then this will work from any page on your website, for example if a user is browsing /articles/setup-tor-hidden-service-website on your normal internet domain, when they click the purple onion service button, they'll be brought to /articles/setup-tor-hidden-service-website on your onion hidden service domain seamlessly.

---