Mastodon Onion Routing and Security Boundaries FAQ
Operating a federated platform like Mastodon over Tor allows community members to access services through a private *.onion address reachable solely through the Tor network. When administrators choose to expose an instance to both the public Internet and Tor simultaneously, link routing, proxy configuration, and domain boundaries require careful isolation. Below are answers to frequent technical questions regarding configuration architecture and network isolation boundaries drawn from the official Onion services - Mastodon documentation.
How is Tor configured to route incoming traffic to Mastodon?
On Debian systems, admins configure Tor by adding the Tor repository (such as the stretch main archive) and importing the Tor project GPG key before installing tor and deb.torproject.org-keyring. Routing itself is managed inside the /etc/tor/torrc configuration file using three key directives:
HiddenServiceDir /var/lib/tor/onion_service/to specify where Tor stores service keys and generated hostnames.HiddenServiceVersion 3to enforce version 3 onion service cryptography.HiddenServicePort 80 127.0.0.1:80to forward inbound port 80 traffic to the local web proxy loopback.
Once saved, restarting Tor via sudo service tor restart generates the onion address, which can be retrieved directly from /var/lib/tor/onion_service/hostname. The onion address also functions as a wildcard domain, meaning subdomains like mastodon. can be prefixed or omitted depending on whether you host other services under the address.
How should Nginx be organized to keep configuration clean across endpoints?
Because Nginx must serve both clearnet traffic and onion traffic, repeating directives creates administrative overhead. The recommended pattern extracts the core Mastodon parameters into a shared snippet at /etc/nginx/snippets/mastodon.conf. As explored in our NGINX Open Source Profile: Codebase Health and Proxy Architecture, modular proxy files keep server declarations DRY (Don't Repeat Yourself).
This snippet file excludes the listen, server_name, include, and SSL directives. Instead, it holds general connection and proxy rules, including:
Referrer-Policy "same-origin";keepalive_timeout 70;sendfile on;client_max_body_size 80m;root /home/mastodon/live/public;error_page 500 501 502 503 504 /500.html;- Logging paths like
/var/log/nginx/mastodon_access.logand/var/log/nginx/mastodon_error.log warn;
In the main Nginx virtual hosts, you include this shared snippet within both your clearnet server blocks and the dedicated onion server block listening on port 80. You also declare the onion address under ALTERNATE_DOMAINS in Mastodon's .env.production file so the application recognizes the secondary routing host.
Why do web server restarts trigger bucket size errors?
When you add long version 3 onion addresses to Nginx, restarting the web server via service nginx restart may trigger an error stating that Nginx could not build server_names_hash, you should increase server_names_hash_bucket_size: 64. Because onion hostnames contain long hash strings, the default hash allocation inside Nginx often lacks sufficient space to index the domain name.
To resolve this, open nginx.conf and uncomment the directive server_names_hash_bucket_size 64;. If server restart attempts still fail after setting the parameter to 64, administrators can increase the bucket size up to 128.
How can administrators advertise onion availability to clearnet browsers?
To alert Tor-capable browsers that an onion service exists, administrators can send two specific response headers from the web server:
- Onion-Location: Placed inside the shared snippet, this header specifies the onion hostname alongside
$request_uri. Supporting browsers read this header and inform visitors that an onion equivalent is accessible. - Alt-Svc: Advertises an alternative service routing path. According to the Onion services - Mastodon documentation, an example header configuration is
add_header Alt-Svc 'h2="qKnF…sKq7.onion:443"; ma=86400; persist=1';. Because the TLS connection does not terminate at the onion service in that scenario, HTTPS can use a standard non-onion TLS certificate. While port 443 is shown in the documentation example, it is not strictly required and can be configured differently.
Should Mastodon onion services be served over HTTP or HTTPS?
While clearnet instances rely on automated certificates (as covered in our Installing Mastodon from Source on Ubuntu: Step-by-Step Guide), running HTTPS over Tor is rarely ideal. No Certificate Authority provides onion certificates for free, making them mostly useful for large corporations that issue certificates containing their own company details. Furthermore, Tor Project guidance explains that HTTPS certificates provide minimal security benefits over onion services, which already feature end-to-end encryption by design.
However, serving Tor over plain HTTP introduces usability gotchas. The Mastodon frontend includes redirects that force visitors toward an HTTPS URL. When this happens, users browsing over Tor must manually remove the https:// prefix and replace it with HTTP to remain on the onion address.
What security and privacy boundaries fail across simultaneous clearnet and Tor setups?
Operating an instance across clearnet and Tor simultaneously does not create a completely isolated environment for privacy-conscious users. Mastodon continues to offer various resources, including uploaded images, through the primary clearnet domain. If visitors connect via the onion service expecting total network disconnection from public endpoints, fetching remote media and images anchored to the clearnet domain can undermine their intended precautions.
Sources
Published October 30, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.