Configuration Guide

Giovanni Pellerano edited this page Dec 25, 2015 · 6 revisions


This guide provide a complete overview of all the Tor2web configuration features and how to properly configure it.

Base Configuration

Node Name

This is the node identifiactor used when t2w need to send feed/debug/abuse notices to node administrators.


Data Dir

This is the path to the Tor2web data directory (default: ./data)

datadir = [PATH]

This directory contains:

/certs [required]
    a directory where tor2web looks for SSL certificates/key

/logs [required]
    a directory where tor2web keeps logs if logging is enabled

/templates [optional, needed for customization purposes] 
    a directory that overrides /usr/share/tor2web/template 

/static [optional, needed for customization purposes] 
    a directory that overrides /usr/share/tor2web/static 

Base Host

This is the base hostname for the current tor2web node. If you run Tor2web on your own domain with your own digital certificate, adjust it to your own domain name. If you run Tor2web under the domain with DNS round robin, the use domain.

basehost =


Tor2web can be configured to run using multiprocessing. It's suggested to configure a number of processes = (number of cores + 1)

The number of request before process replacement can be configured as well; this offer the protection from memory leaks that could be present in tor2web or in external libraries.

processes = 5
requests_per_process = 10000

Listening IPs and Ports

Configure the port running Tor2web

transport = BOTH
# the above transport setting allow you to
# - enable only http: HTTP
# - enable only https: HTTPS
# - enable both http and https with forced redirect over https: BOTH

listen_ipv4 = [LISTENING_IPV4_ADDRESS]
listen_ipv6 = [LISTENING_IPV6_ADDRESS]
listen_port_http = 80
listen_port_https = 443

Tor Configuration

Tor2web must connect, to forward requests to Tor Hidden Services, to a Tor socks proxy that's usually listening on localhost in port 9050

sockshost =
socksport = 9050

Setup Built-in SSL

With Tor2web Tor2web now run with SSL built-in with no need of using NGINX or Apache like in previous versions of the software.

In order to setup SSL:

  • The key file must be provided in PEM format
  • The certificate file must be provided in PEM format, including it's intermediate certificate
  • The DH seed (for PFS ciphers) must be generated and provided accordingly to the Getting Started Guide instruction
  • The ciphers must be configured to work only with PFS enabled ciphers (default).

SSL configuration


The configuration of the intermediate certificate, along with the certificate, require you create a single file with the two PEM format files merged together. The structure of the file is:

  • First the Intermediate Certificate
  • Second the Tor2web wildcard certificate


Logging is a sensitive issues and by default a Tor2web node running in production with no particular problem, must have any kind of logging disabled.

Request Logging

Request logging log all the HTTP requests in apache format. To preserve privacy of users, the source IP address is logged as .

logreqs = False

Debug Logs

Debug logs contain very detailed and verbose logs about Tor2web internal software execution workflow.

It does not provide any kind of privacy sanitization and has to be enabled only in extreme-condition when it's not possible to debug / reproduce a problem on development system.

debugmode = False
debugtostdout = False

Access and Blocklist

Tor2web, in order to be kept online with reduced server takedown risks, require the setup of several blocking acting as a filter.

It's important to underline that Tor2web does not censor or block a website, but just avoid exposing a specific Tor Hidden Service to the internet.

Even in case of URL blocking, Tor2web invite the user to download Tor Browser Bundle and access directly to the Tor Hidden Service on .onion domain.

Configuring Access lists

Tor2web can work in two modes: BLOCKLIST and TRANSLATION. The MODE can be set with the following config statement mode = BLOCKLIST


In BLOCKLIST mode Tor2web blocks access only to configured Hidden Services and urls.

This is the default and only way to use Tor2web as part of the public network.

Blocklist elements are not saved locally in clear-text but as md5 hashes.

The hashed blocklist is read from the file "lists/blocklist_hashed.txt". The blocklist format is just an md5 of the resource. Actually Tor2web permits to filter out entire HSs, i.e.: BLABLABLA.onion

For example, to add TorHS url "BLAHBLAHBLAH.onion" to the blocklist:

echo -e "BLAHBLAHBLAH.onion\c" | md5sum


Then edit lists/blocklist_hashed.txt and add the string a81be903ead77f44a8813c8718154570 .

Importing bulk blocklist

Actually Tor2web permits also to import a cleartext blocklist.

The cleartext blocklist is read from the file "lists/blocklist_cleartext.txt".

When runned Tor2web looks at that file, imports all the urls it found, calculates the hash, makes a merge with the hashed list, and than flushs the cleartext list for security reasons.

The urls inside list/blocklist_cleartex.txt may have the following formats:

  • BLABLABLA.onion
  • BLABLABLA.onion/path/index.hml
Remotely importing blocklist

This feature let you import a remote blocklist, this probably due to the intention of the node administration to delegate to another node administration the maintenance of the blocklist.

# The following configurations parametes permits to enable automatic fetching of blocklists 
# automatic_blocklist_updates_source =
# automatic_blocklist_updates_mode = MERGE
# automatic_blocklist_updates_refresh = 600

The source parameter must contained an url. The mode parameter must contain MERGE if you want local list to be merged with remote one, REPLACE if you want local list to be replaced with remote one. The refresh parameter must contain a integer expressing an interval in seconds.


In TRANSLATION MODE Tor2web allows access only to a configured Hidden Services.

With this mode Tor2web act as a "reverse proxy" for a single server/hostname and it's typically used for applications such as GlobaLeaks. To configure the accessible onion address the "onion" config setting must be used.

The following is an example where is translated to kpvz7ki2v5agwt35.onion/url:

onion = kpvz7ki2v5agwt35.onion

In translation mode Tor2web reads also a file /home/tor2web/lists/hosts_map.txt where you can put host mapping in the following format: po47k4agopleagki.onion kpvz7ki2v5agwt35.onion

Blocking Crawler with robots

Tor2web has to make his best to block and cleanup Tor2web content away from google and others search engines.

The first method to block is to provide always a /robots.txt that does not allow crawling.

Default Tor2web robots.txt is loaded from /usr/share/tor2web/static/robots.txt

overriderobotstxt = True

Blocking Crawlers's User Agents

The second method to block search engine is to blocklist specific User Agents.

Default Tor2web User Agents list is loaded from /usr/share/tor2web/lists/blocked_ua.txt

blockcrawl = True

Notification Settings

Tor2web maintenance require to handle abuse notification and to spot bugs and issues in the software.

This is achieved trough the configuration of notifications.

Abuse Notification

The abuse notification are received when a user visiting a specific URL consider useful to notify to the node maintainer that there is an abuse.

By default Tor2web use a private, non-archived mailing list to receive abuses requests.

smtpmailto_notifications = tor2web-abuse AT lists DOT tor2web DOT org

Exception Handling Notification

In case of non handled software exception tor2web will send alert and notifications.

smtpmailto_exceptions = your email to receive exception handling

Email Account for Notification

Below the configuration for the email account used to send email notification.

The example below use a gmail account.

# Mail configuration for automatic exceptions notification and user abuse notice 
smtpuser =
smtppass = password
smtpmail =
smtpdomain =
smtpport = 587

Misc settings

Redirect Tor users.

Tor2web detects Tor users connecting to Tor2web and redirect them to the TorHS .onion address. To do so, it download from oonionoo the databases of Tor Exit Node once every X seconds, by default 10 minutes.

exit_nodes_list_refresh = 600

Tor2web Mirrors

By default Tor2web shows alternative domains and links in the banner included in proxified pages. The list of alternative domains to show if configurable.

mirror = [,]