Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
This guide provide a complete overview of all the Tor2web configuration features and how to properly configure it.
This is the node identifiactor used when t2w need to send feed/debug/abuse notices to node administrators.
nodename = [UNIQUE_IDENTIFIER]
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
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 Tor2web.org domain with DNS round robin, the use tor2web.org domain.
basehost = tor2web.org
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
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 = 127.0.0.1 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).
cipher_list = DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA
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 log all the HTTP requests in apache format. To preserve privacy of users, the source IP address is logged as 127.0.0.1 .
logreqs = False
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:
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 = https://ahmia.fi/bannedMD5.txt # 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 antani.gov/url is translated to kpvz7ki2v5agwt35.onion/url:
mode = TRANSLATION 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:
name1.tor2web.org po47k4agopleagki.onion name2.tor2web.org 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
Tor2web maintenance require to handle abuse notification and to spot bugs and issues in the software.
This is achieved trough the configuration of notifications.
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 = email@example.com smtppass = password smtpmail = firstname.lastname@example.org smtpdomain = smtp.gmail.com smtpport = 587
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
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 = [tor2web.org, onion.to]