From b328ba77fd0c54dc3e9b23b6a25e23f6bb51cd18 Mon Sep 17 00:00:00 2001
From: David Baucum <david@baucum.me>
Date: Tue, 26 Feb 2019 16:32:23 -0500
Subject: [PATCH] Add documentation for serving Mastodon as a tor service

---
 .../en/administration/optional-features.md    | 105 +++++++++++++++++-
 1 file changed, 104 insertions(+), 1 deletion(-)

diff --git a/content/en/administration/optional-features.md b/content/en/administration/optional-features.md
index 9a2ca2ef..cec3566e 100644
--- a/content/en/administration/optional-features.md
+++ b/content/en/administration/optional-features.md
@@ -63,7 +63,110 @@ Now new statuses will be written to the ElasticSearch index. The last step is im
 
 ## Hidden services
 
-TODO
+Mastodon can be served through Tor as an onion service. This will give you a *.onion address that can only be used while connected to the Tor network.
+
+### Installing Tor
+
+First Tor's Debian archive needs to be added to apt.
+
+```
+deb https://deb.torproject.org/torproject.org stretch main
+deb-src https://deb.torproject.org/torproject.org stretch main
+```
+
+Next add the gpg key.
+
+```bash
+curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import
+```
+
+Finally install the required packages.
+
+```bash
+apt install tor deb.torproject.org-keyring
+```
+
+### Configure Tor
+
+Edit the file at `/etc/tor/torrc` and add the following configuration.
+
+```bash
+HiddenServiceDir /var/lib/tor/mastodon/
+HiddenServiceVersion 3
+HiddenServicePort 80 127.0.0.1:80
+```
+
+Restart tor.
+
+```bash
+sudo service tor restart
+```
+
+Your tor hostname can now be found at `/var/lib/tor/mastodon/hostname`. This will work _if_ you are serving Mastodon over port 80 and _if_ it is the only site you are serving on your web server.
+
+### Configuring a multi-host server
+
+If you have multiple domains on your web server you will need to tell your web server how to serve the tor hostname. In the configuration file for your Mastodon web configuration add an additional hostname entry. e.g. for Nginx
+
+```bash
+server {
+  …
+  servername mastodon.myhosting.com qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7.onion
+  …
+}
+```
+
+### Serve Tor over http
+
+While it may be tempting to serve your Tor version of Mastodon over https it is not good idea. See [this](https://blog.torproject.org/facebook-hidden-services-and-https-certs) blog post from the Tor Project about why https certificates do not add value. Since you cannot get an SSL cert for an onion domain, you will also be plagued with certificate errors when trying to use your Mastodon instance.
+
+The solution is to serve your Mastodon instance over http, but only for Tor.
+
+Consider the following example Nginx configuration.
+
+```
+server {
+  listen 80;
+  server_name mastodon.myhosting.com;
+  return 301 https://$host$request_uri;
+}
+
+server {
+  listen 443 ssl http2;
+  server_name mastodon.myhomsting.com;
+  …
+}
+```
+
+Add a new server entry that duplicates the ssl entry, but defines it to use port 80 with your onion hostname.
+
+```
+server {
+  listen 80;
+  server_name mastodon.myhosting.com;
+  return 301 https://$host$request_uri;
+}
+
+server {
+  listen 80;
+  server_name qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7qKnFwnNH2oH4QhQ7CoRf7HYj8wCwpDwsa8ohJmcPG9JodMZvVA6psKq7.onion;
+  …
+}
+
+server {
+  listen 443 ssl http2;
+  server_name mastodon.myhosting.com;
+  …
+}
+```
+
+Restart your web server.
+
+```bash
+service nginx restart
+```
+
+You can also see [this Server Fault](https://serverfault.com/a/373661) answer for a more [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) solution.
 
 ## Login via LDAP/PAM/CAS/SAML