Installation Guide

Giovanni Pellerano edited this page Jan 10, 2017 · 20 revisions


This guide will provide you the basic procedure to setup Tor2web


The requirements to setup a Tor2web node are as follow:

  • A Domain Name (you can use your own)
  • DNS Servers
  • Wildcard digital certificate
  • Ubuntu/Debian Linux Server
  • Public IP address with available free TCP port 80 and 443


Describe different way to implement Tor2web architectures.

One domain/certificate, one node

This is the simpler situation and it was the very early model of Tor2web 1.0 based on Apache+Privoxy hack.

It is not used anymore, but in future (with implementation of and ) it may have a revival due to the reduced constraint in running it even without a wildcard certificate.

One domain/certificate, many nodes

The first and early Tor2web architecture is distributed on the basis of DNS. It means that there is one domain, one wildcard digital certificates shared among trusted people.

This architecture is the one used today, but it cannot have scalability for several reasons:

  • One DNS takedown would takedown the overall network
  • There is only one person managing the DNS
  • There is only one digital certificate with all the issues related to sharing private key only with trusted persons

However it's the early model of Tor2web and the most simple.

Many domain, one/many nodes

This architectural model it's still not implemented within Tor2web software but it represent the future evolution of the system.

With this architecture there are many Tor2web administrators using multiple domains, multiple servers and multiple digital certificates. All the cluster of servers around a domain/certificate couple, are aware of the other clusters and distribute the load across various networks. This is the future of Tor2web, now in research, described on

Operating system

TODO: Notes on installation on different operating systems with description of the main needed packages.

Install Preliminary Utilities

mkdir ~/tor2web-buildenv
cd ~/tor2web-buildenv

sudo apt-get update && apt-get upgrade
sudo apt-get install python-software-properties python-pip python-dev build-essential wget vim libffi-dev

Install Tor

Build Tor with Tor2web mode and some patches

In order to improve Tor2web performance and fix certain specific Tor2web issues it's important to rebuild tor. Note that this custom Tor build must not be used for anything different from Tor2web due to the fact that it does not provide anonymity.

This build procedure expect to work on an debian or ubuntu system and it's based on standard howto on section "Building Tor from Source".

sudo vim /etc/apt/sources.list
deb-src +DISTRIBUTION+ main

Apply vim regexp to substitute your distribution (in this example ubuntu trusty):


Now setup tor's apt source pgp keys and download tor's sources:

mkdir -p ~/tor2web-buildenv/debian-packages
cd ~/tor2web-buildenv/debian-packages
gpg --keyserver --recv 886DDD89
gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -
sudo apt-get update
sudo apt-get install
sudo apt-get update
sudo apt-get install fakeroot devscripts
sudo apt-get build-dep tor
sudo apt-get source tor
cd tor-*

Now we enable Tor2web mode build-time required flags:

vim debian/rules


dh_auto_configure \
        $(confflags) \
        --prefix=/usr \
        --mandir=\$${prefix}/share/man \
        --infodir=\$${prefix}/share/info \
        --localstatedir=/var \
        --sysconfdir=/etc \
        --disable-silent-rules \


dh_auto_configure \
        $(confflags) \
        --prefix=/usr \
        --mandir=\$${prefix}/share/man \
        --infodir=\$${prefix}/share/info \
        --localstatedir=/var \
        --sysconfdir=/etc \
        --disable-silent-rules \
        --enable-gcc-warnings-advisory \

Apply manually a small patch to pass make check-TESTS of debian built (TODO: fix test.c error):

vim src/or/config.c


V(Tor2webMode,                 BOOL,     "0"),


V(Tor2webMode,                 BOOL,     "1"),

Now build and install the modified Tor:

debuild -rfakeroot -uc -us
cd ..
sudo dpkg -i tor*.deb

Mark Tor packages to prevent automagical updates:

sudo apt-mark hold tor tor-dbg tor-geoipdb

Et voilà, tor it's now ready for Tor2web.

Install and configure Tor2web

Install Tor2web

chmod +x

Configure Tor2web

Now that Tor2web is installed you need to configure it by creating a conf file at path /etc/tor2web.conf.

A skeleton for the configuration file can be found at /usr/share/tor2web/data/conf/tor2web-default.conf

To understand how to edit the configuration file please take care of the comments inside of the example file and of the indication on the reference guide available here

In addition you will need to install and configure tor2web ssl certificates, intermediate certificates and keys inside /home/tor2web/certs directory.

As a quick example to create self-signed ones, you can use the following commands:

cd /home/tor2web/certs/
openssl genrsa -out tor2web-key.pem 4096
openssl req -new -key tor2web-key.pem -out tor2web-csr.pem
openssl x509 -req -days 365 -in tor2web-csr.pem -signkey tor2web-key.pem -out tor2web-cert.pem

The configuration directive to setup the TLS/SSL certificates are the following:

ssl_key = /home/tor2web/certs/tor2web-key.pem
ssl_cert = /home/tor2web/certs/tor2web-cert.pem
ssl_intermediate = /home/tor2web/certs/tor2web-intermediate.pem

Please, be sure to load the SSL/TLS intermediate certificate given by your CA, or many browser will gives our bad security warning when connecting.

If you are installing on Ubuntu <= 14.04 uou need to issue also the following command required for PFS enabled DHE SSL ciphers:

cd /home/tor2web/certs/
openssl dhparam -out tor2web-dh.pem 2048

Start Tor2web

/etc/init.d/tor2web start

Check Tor2web Status

/etc/init.d/tor2web status

netstat -natp | grep -e LISTEN | grep -e ':80' -e ':443'

Setup Tor2web to run automatically

When all the previous steps are fine and you are confident with the configuration, Tor2web can be configured to start automatically on boot

update-rc.d tor2web defaults # Set Tor2web to automatically start on-boot