commit 1505dabdf82300cf32c307cc6bc8db8a82f72465
Author: gus <g...@torproject.org>
Date: Tue Dec 8 09:03:06 2020 -0500
Update how to setup tor with a webserver. Fix #157
---
content/onion-services/setup/contents.lr | 130 ++++++++++++++++++++++++-------
1 file changed, 101 insertions(+), 29 deletions(-)
diff --git a/content/onion-services/setup/contents.lr
b/content/onion-services/setup/contents.lr
index 464596f..50fed1c 100644
--- a/content/onion-services/setup/contents.lr
+++ b/content/onion-services/setup/contents.lr
@@ -19,77 +19,149 @@ cta: Get Started
html: two-columns-page.html
---
body:
-
-This guide shows you how to set up an onion service for your website.
+This guide shows you how to set up an onion service for your website.
+For the technical details of how the onion service protocol works, see our
onion service protocol page.
## Step 0: Get a working Tor
-As part of this guide, we will assume you have a functional Tor in your
machine. Tor should be up and running correctly for this guide to work. You
should also know where Tor's configuration files are.
-
-To setup Tor, Windows users can follow the [Windows
howto](https://2019.www.torproject.org/docs/tor-doc-windows.html.en), OS X
users should follow the [OS X
howto](https://2019.www.torproject.org/docs/tor-doc-osx.html.en), and
Linux/BSD/Unix users should follow the [Unix
howto](https://2019.www.torproject.org/docs/tor-doc-unix.html.en).
+As part of this guide, we will assume you have a functional Tor in your
machine.
+To set up Tor, please follow the [Tor installation
guide](https://community.torproject.org/onion-services/setup/install/).
+Tor should be up and running correctly for this guide to work.
+You should also know where Tor's configuration files are.
## Step 1: Get a web server working
-As a first step you should setup a web server locally, like nginx or lighttpd.
Setting up a web server can be complex.
-We're not going to cover how to set up a web server here. If you get stuck or
want to do more, find a friend who can help you.
+As a first step, you should set up a web server locally, like Nginx, Apache,
or your favorite web server.
+Setting up a web server can be complex.
+If you get stuck or want to do more, find a friend who can help you or connect
with any of the forums online that offer help.
+
+As an example, we will cover how to set up an onion site with Nginx and Apache
on Debian.
We recommend you install a new separate web server for your onion service.
-You need to configure your web server so it doesn't give away any information
about you, your computer, or your location.
-This is not an easy task and in the end of this document we will offer more
resources on how to make this possible.
+On this page, the commands to manage the web server are based on Debian-like
operating systems and may differ from other systems.
+Check your web server and operating system documentation.
+
+### Apache
+
+Apache is available in the main repository of multiple Linux and *BSD
distributions.
+To install `apache2` package:
+
+`$ sudo apt install apache2`
-Once your web server is set up, make sure it works: open your browser and go
to http://localhost:8080/, where 8080 is the webserver port you chose during
setup (you can choose any port, 8080 is just an example).
+### Nginx
+
+Nginx is available in the main repository of multiple Linux and *BSD
distributions.
+To install `nginx` package:
+
+`$ sudo apt install nginx`
+
+By default, the web server will be running on `localhost:80` at the end of the
installation.
+If you get an error message, something has gone wrong and you cannot continue
until you've figured out why this didn't work.
+
+Once your web server is set up, make sure it works: open your browser and go
to http://localhost/.
Then try putting a file in the main html directory, and make sure it shows up
when you access the site.
## Step 2: Configure your Tor onion service
The next step is opening the config file of Tor (torrc) and doing the
appropriate configurations to setup an onion service.
Depending on your operating system and setup, your Tor configuration file can
be at a different location or look different.
-You will need to put the following two lines in your torrc:
- HiddenServiceDir /var/lib/tor/hidden_service/
- HiddenServicePort 80 127.0.0.1:8080
+You will need to put the following two lines in your `torrc` file:
+ HiddenServiceDir /var/lib/tor/my_website/
+ HiddenServicePort 80 127.0.0.1:80
The `HiddenServiceDir` line specifies the directory which should contain
information and cryptographic keys for your onion service.
You will want to change the `HiddenServiceDir` line, so that it points to an
actual directory that is readable/writeable by the user that will be running
Tor.
-The `HiddenServicePort` line specifies a _virtual port_ (that is, the port
that people visiting your onion service will be using), and in the above case
it says that any traffic incoming to port 80 of your onion service should be
redirected to `127.0.0.1:8080` (which is where the web server from step 1 is
listening).
+The `HiddenServicePort` line specifies a _virtual port_ (that is, the port
that people visiting your onion service will be using), and in the above case
it says that any traffic incoming to port 80 of your onion service should be
redirected to `127.0.0.1:80` (which is where the web server from step 1 is
listening).
+
+**Tip:** A good practice to avoid leaking an onion service to a local network
is to run onion services over Unix sockets instead of a TCP socket.
+You will need to edit and put the following two lines in your `torrc` file:
+
+```
+HiddenServiceDir /var/lib/tor/my-website/
+HiddenServicePort 80 unix:/var/run/tor-my-website.sock
+```
## Step 3: Restart Tor and check that it worked
Now save your `torrc` and restart Tor.
+`$ sudo systemctl tor restart`
+
If Tor starts up again, great. Otherwise, something is wrong. First look at
your logfiles for hints.
-It will print some warnings or error messages. That should give you an idea
what went wrong.
-Typically, there are typos in the torrc or wrong directory permissions (See
the [logging FAQ](https://www.torproject.org/docs/faq#Logs) entry if you don't
know how to enable or find your log file.)
+It will print some warnings or error messages. That should give you an idea of
what went wrong.
+Typically, there are typos in the `torrc` or wrong directory permissions (See
the [logging FAQ](https://www.torproject.org/docs/faq#Logs) entry if you don't
know how to enable or find your log file.)
-When Tor starts, it will automatically create the `HiddenServiceDir` that you
specified (if necessary). Make sure this is the case.
+When Tor starts, it will automatically create the `HiddenServiceDir` that you
specified (if necessary).
+Make sure this is the case.
## Step 4: Test that your onion service works
Now to get your onion service address, go to your `HiddenServiceDir`
directory, and find a file named `hostname`.
-The `hostname` file in your hidden service configuration directory contains
the hostname for your new onion v3 hidden service.
-The other files are your hidden service keys, so it is imperative that these
are kept private.
+The `hostname` file in your onion service configuration directory contains the
hostname for your new onion v3 service.
+The other files are your onion service keys, so it is imperative that these
are kept private.
If your keys leak, other people can impersonate your onion service, deeming it
compromised, useless, and dangerous to visit.
-Now you can connect to your onion service using Tor Browser, and you should
get the html page you setup back in step 1.
+Now you can connect to your onion service using Tor Browser, and you should
get the html page you setup back in **Step 1**.
If it doesn't work, look in your logs for some hints, and keep playing with it
until it works.
-## Step 5: More tips
+It is important to note that an onion service configured like this will be
readable by anybody who knows or discovers the address.
+You can make onion services require authentication, and only users with a
private key will access the service.
+Read more about [Client
authorization](https://community.torproject.org/onion-services/advanced/client-auth/)
documentation.
-If you plan to keep your service available for a long time, you might want to
make a backup copy of the `private_key` file somewhere.
+## (Optional) Step 5: Running multiple onion services
-If you want to forward multiple virtual ports for a single onion service, just
add more `HiddenServicePort` lines. If you want to run multiple onion services
from the same Tor client, just add another `HiddenServiceDir` line. All the
following `HiddenServicePort` lines refer to this `HiddenServiceDir` line,
until you add another `HiddenServiceDir` line:
+If you want to forward multiple virtual ports for a single onion service, just
add more `HiddenServicePort` lines.
+If you want to run multiple onion services from the same Tor client, just add
another `HiddenServiceDir` line.
+All the following `HiddenServicePort` lines refer to this `HiddenServiceDir`
line, until you add another `HiddenServiceDir` line:
- HiddenServiceDir /usr/local/etc/tor/hidden_service/
- HiddenServicePort 80 127.0.0.1:8080
+ HiddenServiceDir /var/lib/tor/onion_service/
+ HiddenServicePort 80 127.0.0.1:80
- HiddenServiceDir /usr/local/etc/tor/other_hidden_service/
+ HiddenServiceDir /var/lib/tor/other_onion_service/
HiddenServicePort 6667 127.0.0.1:6667
HiddenServicePort 22 127.0.0.1:22
-
-You can use [stem](https://stem.torproject.org/) to [automate the management
of your onion
services](https://stem.torproject.org/tutorials/over_the_river.html).
+If you're running multiple onion sites on the same web server, remember to
edit your web server virtual host file and add the onion address for each
website.
+For example, in Nginx and using Tor with Unix sockets, the configuration would
look like this:
+
+```
+server {
+ listen unix:/var/run/tor-my-website.sock;
+ server_name <your-onion-address>.onion;
+ access_log /var/log/nginx/my-website.log;
+ index index.html;
+ root /path/to/htdocs;
+}
+```
+
+Or in Apache with Tor service listening on port 80:
+
+```
+ <VirtualHost *:80>
+ ServerName <your-onion-address.onion>
+ DocumentRoot /path/to/htdocs
+ ErrorLog ${APACHE_LOG_DIR}/my-website.log
+ </VirtualHost>
+```
- * To set up an Onion Service on Raspbian have a look at Alec Muffett's
[Enterprise Onion Toolkit](https://github.com/alecmuffett/eotk).
+## Step 6: Security advice and more tips
+
+The default version of onion services is version 3 and it has 56 characters
long.
+Onion services version 2 is being deprecated and will be retired soon from the
Tor network, after 0.4.6.x Tor release, in July 2021.
+Please read the blog post [Onion Service version deprecation
timeline](https://blog.torproject.org/v2-deprecation-timeline) for more
information.
+
+Some onion site operators may not want to disclose their onion service
location.
+Therefore, you need to configure your web server so it doesn't give away any
information about you, your computer, or your location.
+That is not an easy task, and these resources will help on how to make this
possible:
+
+ * [Operational
Security](https://community.torproject.org/onion-services/advanced/opsec/).
* [Onion services best
practices](https://riseup.net/en/security/network-security/tor/onionservices-best-practices)
by Riseup Collective.
+ * [OnionScan](https://onionscan.org/) is a tool to check if your onion site
is leaking information that could compromise your anonymity like your server IP
address.
+
+Finally, if you plan to keep your service available for a long time, you might
want to make a backup copy of the `private_key` file somewhere.
+
+Now that you have an onion site working, you may want to deploy
[Onion-Location](https://community.torproject.org/onion-services/advanced/onion-location/),
or use tools like Docker, [Ansible](https://galaxy.ansible.com/systemli/onion)
or [stem](https://stem.torproject.org/tutorials/over_the_river.html) to
automate the management of your onion services.
+If you have a static website, but never installed Nginx or Apache, another
project to try is [OnionShare](https://onionshare.org), where running an onion
site will be easier: guided with a graphic interface and with minimal
configuration.
_______________________________________________
tor-commits mailing list
tor-commits@lists.torproject.org
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits
