Onion-Location-Header in nginx einrichten

Was der Onion-Location-Header bewirkt

Der Onion-Location-Header ist eine einzelne Zeile in Ihrem Clearnet-Vhost, die dem Tor Browser Ihre Onion-Adresse mitteilt. Besucher, die https://example.com über Tor aufrufen, sehen in der Adressleiste ein violettes Feld mit dem Text .onion available. Mit einem Klick wechseln sie zu Ihrem Onion-Service. Der Header dient ausschließlich der Erkennung. Er erstellt den Onion-Service nicht und verbirgt keine Informationen über Sie.

Diese Anleitung setzt voraus, dass beide Teile bereits vorhanden sind. Sie haben eine Website auf einem VPS hinter nginx und einen funktionierenden v3-Onion-Service, der auf diese Website verweist. Falls der zweite Teil noch fehlt, richten Sie ihn zuerst ein: eine Onion-Website auf einem VPS hosten beschreibt die torrc-Zeilen und die erste Datei hostname. Im Folgenden geht es darum, beide Teile miteinander zu verbinden, ohne Informationen von einem in den anderen zu übertragen.

Voraussetzungen, bevor Tor Browser den Header berücksichtigt

Das Tor Project dokumentiert drei Bedingungen. Alle drei müssen erfüllt sein, sonst wird das Symbol nie angezeigt.

• Der Wert Onion-Location muss eine gültige URL mit einem http:- oder https:-Schema und einem .onion-Hostnamen sein.
• Die Webseite, die den Header definiert, muss über HTTPS ausgeliefert werden.
• Die Webseite, die den Header definiert, darf selbst keine Onion-Site sein.

Die zweite Bedingung führt häufig zu Problemen. Die dritte erklärt, warum Sie diesen Header nie auf dem Onion-VHost setzen. Es gibt eine vierte Regel, die nicht in der Dokumentation beschrieben ist, aber in der Implementierung gilt: Tor Browser verarbeitet den Header nur für das Dokument der obersten Ebene. Der Code vergleicht das Ladeziel mit dem Dokument, bevor er eine Aktion ausführt. Ein Header in der Antwort für ein Stylesheet, ein Bild oder eine API-Anfrage wird daher ignoriert.

Standardmäßig zeigt der Browser das Symbol an und wartet auf einen Klick. Wer eine automatische Weiterleitung wünscht, aktiviert diese unter Settings, dann Privacy and Security und anschließend Onion Services. Dort kann "Prioritize .onion sites when known" auf "Always" gesetzt werden. Sie können dieses Verhalten nicht serverseitig erzwingen. Betrachten Sie den Header als Angebot, nicht als Redirect.

Den Onion-Location-Header in nginx hinzufügen

Der Header gehört in den Server-Block, der TLS für Ihre Clearnet-Domain beendet. Wenn Sie ihn stattdessen in den Port-80-Block eintragen, passiert nichts, weil dieser Block nur eine Weiterleitung ausführt und Regel zwei einen Header auf einer reinen HTTP-Seite ausschließt.

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    add_header Onion-Location http://<your-onion-address>.onion$request_uri always;

    root /srv/example.com/public;
}

$request_uri enthält den Pfad und die Query-Zeichenfolge. Dadurch wird einem Leser auf https://example.com/guides/tor derselbe Pfad auf der Onion-Adresse angeboten. Lassen Sie ihn weg, landet jeder Besucher auf der Startseite der Onion-Adresse statt auf der gerade gelesenen Seite.

always ist wegen einer dokumentierten Einschränkung in nginx erforderlich. add_header fügt das Feld nur bei den Antwortcodes 200, 201, 204, 206, 301, 302, 303, 304, 307 oder 308 hinzu. Ihre 404-Seite ist ein echter Einstiegspunkt aus Suchergebnissen. Ohne always enthält sie überhaupt keinen Header.

Die zweite nginx-Falle ist die Vererbung. Sie schlägt ohne Fehlermeldung fehl. add_header-Direktiven werden nur dann von der vorherigen Konfigurationsebene geerbt, wenn auf der aktuellen Ebene keine add_header-Direktiven vorhanden sind. Ein location /assets/ { add_header Cache-Control ...; }-Block verwirft daher das auf Server-Ebene definierte Onion-Location für jede URL darunter. Wenn Sie an einer beliebigen Stelle Header pro Location festlegen, wiederholen Sie die Zeile Onion-Location in jedem dieser Blöcke. Wie nginx einen Server- und einen Location-Block auswählt sollten Sie einmal lesen, wenn dieses Verhalten für Sie neu ist.

Laden Sie die Konfiguration neu und prüfen Sie sowohl eine normale als auch eine nicht vorhandene Seite:

sudo nginx -t && sudo systemctl reload nginx
curl -sI https://example.com/ | grep -i onion-location
curl -sI https://example.com/no-such-page | grep -i onion-location

Beide Befehle sollten eine Zeile mit onion-location: ausgeben. Der zweite Befehl beweist, dass always funktioniert. Wenn der zweite Befehl keine Ausgabe liefert, fehlt das Flag oder ein location-Block überschreibt die Direktive.

Das HTML-Meta-Tag, wenn Sie keine Header setzen können

Statische Hosts und einige CDN-Dashboards erlauben es nicht, einen beliebigen Response-Header hinzuzufügen. Derselbe Wert funktioniert als Meta-Element im Dokumentkopf, weil der Browser ihn über dieselben Dokument-Headerdaten liest, unabhängig davon, ob er über HTTP oder als http-equiv-Tag übermittelt wurde.

<meta http-equiv="onion-location" content="http://<your-onion-address>.onion" />

Die drei Anforderungen gelten weiterhin. Die Seite mit dem Tag muss HTTPS verwenden und darf keine Onion-Adresse sein. Der Unterschied besteht darin, dass das Tag eine feste Adresse ohne Pfad enthält, weil keine serverseitige Variable erweitert werden kann. Jede Seite mit diesem Tag verweist auf die Onion-Startseite. Das ist der Preis für diesen Fallback. Verwenden Sie daher den Header, sobald Sie den Server kontrollieren.

Den Onion-Dienst über einen eigenen nginx-vhost ausliefern

Die Clearnet-Site und der Onion-Dienst dürfen nicht denselben Server-Block verwenden. Der Tor Browser sendet Host: <your-onion-address>.onion. Wenn kein Server-Block diesen Namen übernimmt, verwendet nginx den Standardserver. Das ist Ihr Clearnet-vhost. Jede URL, die dieser vhost erzeugt, enthält dann Ihren Domainnamen.

Verweisen Sie den Hidden Service auf einen Port, der nur über das Loopback-Interface erreichbar ist:

HiddenServiceDir /var/lib/tor/onion_site/
HiddenServicePort 80 127.0.0.1:8080

Geben Sie diesem Port anschließend einen eigenen vhost:

server {
    listen 127.0.0.1:8080;
    server_name <your-onion-address>.onion;

    absolute_redirect off;
    port_in_redirect off;

    root /srv/example.com/public;
}

listen 127.0.0.1:8080 hält diesen vhost von Ihrer öffentlichen IP-Adresse fern. Dadurch kann jemand, der die VPS-Adresse scannt, den Dienst nicht abrufen und byteweise mit der Clearnet-Kopie vergleichen. absolute_redirect off veranlasst nginx, relative Location-Werte auszugeben. Dadurch liefert die Weiterleitung auf den abschließenden Schrägstrich eines Verzeichnisses Location: /guides/ und keine vollständige URL. nginx erstellt absolute Weiterleitungen bereits aus dem Host-Header und nicht aus server_name, weil server_name_in_redirect standardmäßig auf off gesetzt ist. Eine relative Weiterleitung beseitigt diese Frage jedoch vollständig.

Warum leitet die Onion-Seite Besucher weiterhin auf die Clearnet-Site weiter?

Nginx ist nur selten die undichte Stelle. Die Anwendung ist es. Alles, was eine absolute URL aus einer konfigurierten Site-Adresse erstellt, verwendet Ihre Domain, unabhängig davon, welcher vhost die Anfrage verarbeitet hat.

• Ein rel="canonical"-Link-Tag, das auf https://example.com/... verweist. Das ist der häufigste Fall. Jeder, der den Quelltext anzeigt, sieht darin die genaue Clearnet-Seite.
• Weiterleitungen, die das Framework statt Nginx erzeugt, beispielsweise Django mit SECURE_SSL_REDIRECT oder WordPress mit den Optionen home und siteurl.
• og:url und die übrigen Meta-Tags für Social Cards.
• Sitemap- und RSS-Einträge, die laut Spezifikation absolute URLs enthalten.
• Fehlerseiten der Anwendung, die normalerweise einen Link „Zur Startseite“ enthalten, der aus derselben Einstellung erstellt wurde.

Die Lösung hängt von Ihrem Stack ab. Eine allgemeingültige Lösung gibt es nicht. Die Prüfung ist jedoch allgemeingültig. Rufen Sie die Onion-Seite über Tor ab und suchen Sie in der Antwort nach Ihrer Domain.

curl -s --socks5-hostname 127.0.0.1:9050 http://<your-onion-address>.onion/ \
  | grep -i 'example\.com'

--socks5-hostname übergibt den Namen zur Auflösung an den SOCKS-Port von Tor. Das ist erforderlich, weil kein Dienst auf Ihrem Rechner einen .onion-Namen lokal auflösen kann. Port 9050 ist der Standard für einen paketierten Tor-Daemon. Ein leeres Ergebnis bedeutet, dass die Prüfung erfolgreich war. Jeder Treffer zeigt eine Seite an, die Ihre Clearnet-Domain an jeden Onion-Besucher weitergibt. Führen Sie die Prüfung zuerst für die Startseite und anschließend für eine URL aus, die einen 404-Fehler erzeugt.

Prüfen Sie die Weiterleitungskette separat, weil der Antworttext einer Weiterleitung normalerweise leer ist:

curl -sI --socks5-hostname 127.0.0.1:9050 http://<your-onion-address>.onion/guides \
  | grep -i '^location'

Ein Location-Wert mit example.com bedeutet, dass eine Weiterleitung Ihren Onion-Besucher über einen Exit-Node zurück ins Clearnet schickt, obwohl der Besucher davon ausging, dass die Anfrage innerhalb von Tor bleibt.

Präsentieren Sie Ihr Clearnet-Zertifikat nicht auf der Onion-Adresse

Eine Onion-Adresse der Version v3 wird aus dem öffentlichen Schlüssel des Dienstes abgeleitet. Tor authentifiziert und verschlüsselt den Datenverkehr zu genau diesem Dienst, bevor eine HTTP-Anfrage gesendet wird. Unverschlüsseltes HTTP innerhalb eines Onion-Dienstes ist die normale Konfiguration. Das ist nicht dasselbe wie unverschlüsseltes HTTP über das Internet.

Wenn Sie den Onion-VHost erstellen, indem Sie den Clearnet-VHost kopieren, übernehmen Sie auch ssl_certificate. Die Onion-Adresse präsentiert dann ein Zertifikat, dessen Subject Alternative Names example.com aufführen. Dabei treten zwei Probleme auf. Der Browser meldet eine Namensabweichung, weil die URL die Onion-Adresse enthält und das Zertifikat diese nicht abdeckt. Außerdem erhält jeder Besucher, der die Warnung umgeht, eine signierte Aussage darüber, dass diese beiden Websites auf demselben Computer betrieben werden. Legen Sie den Onion-VHost in einer eigenen Datei mit einem eigenen server_name an. Dadurch bleibt er außerdem vom Certbot-nginx-Plugin getrennt, da dieses Plugin den Server-Block bearbeitet, der zur Domain gehört, für die Sie ein Zertifikat anfordern.

Welches Tor-Paket Sie verwenden und wie Sie den Servicesschlüssel schützen

Das Paket tor im Ubuntu-Archiv eignet sich dafür und benötigt keine zusätzliche Einrichtung. Es liegt hinter der aktuellen stabilen Serie zurück. Für einen Dienst, den Sie dauerhaft betreiben möchten, verwenden Sie daher das eigene Debian-Repository des Tor Project und lassen Sie apt das Paket zusammen mit allen anderen Paketen aktualisieren. Im August 2026 lauten die dokumentierten Schritte wie folgt:

sudo apt install apt-transport-https
wget -qO- https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc \
  | gpg --dearmor \
  | sudo tee /usr/share/keyrings/deb.torproject.org-keyring.gpg >/dev/null

Schreiben Sie /etc/apt/sources.list.d/tor.sources und ersetzen Sie die Suite durch den Release-Codenamen Ihrer Version aus lsb_release -c:

Types: deb deb-src
URIs: https://deb.torproject.org/torproject.org/
Suites: noble
Components: main
Signed-By: /usr/share/keyrings/deb.torproject.org-keyring.gpg

sudo apt update
sudo apt install tor deb.torproject.org-keyring

Das Paket deb.torproject.org-keyring hält den Signaturschlüssel aktuell. Dadurch schlägt die Verifizierung des Repositorys nicht ein Jahr später fehl. Wählen Sie eine Quelle und bleiben Sie bei dieser. Das Archivpaket und das Repository-Paket enthalten unterschiedliche Versionen. Wenn beide Quellen aktiviert sind, wechselt apt bei Aktualisierungen zwischen ihnen.

Das Verzeichnis HiddenServiceDir enthält die Identität Ihres Dienstes. Die Datei hs_ed25519_secret_key in diesem Verzeichnis ist Ihre Onion-Adresse, weil die Adresse die öffentliche Hälfte dieses Schlüsselpaares ist. Wenn Sie die Datei verlieren, ist auch die Adresse dauerhaft verloren, da keine Stelle sie erneut ausstellen kann. Wenn Sie die Datei unvorsichtig kopieren, kann jeder Besitzer der Kopie Ihren Onion-Dienst ausführen.

tor verweigert die Verwendung eines Verzeichnisses, das andere Benutzer lesen können. Prüfen Sie zuerst die Zugriffsrechte und den Eigentümer:

sudo ls -ld /var/lib/tor/onion_site
sudo -u debian-tor cat /var/lib/tor/onion_site/hostname

Die Ausgabe sollte auf Debian und Ubuntu drwx------ mit Eigentümer und Gruppe debian-tor anzeigen. Wenn die Zugriffsrechte weiter gefasst sind, schreibt tor eine Meldung wie Permissions on directory /var/lib/tor/onion_site/ are too permissive. in das Log, und der Dienst startet nicht. Korrigieren Sie die Rechte mit sudo chown -R debian-tor:debian-tor /var/lib/tor/onion_site und anschließend sudo chmod 700 /var/lib/tor/onion_site, starten Sie den Dienst mit sudo systemctl restart tor neu und prüfen Sie das Ergebnis mit sudo journalctl -u tor@default -n 30.

Sichern Sie dieses Verzeichnis wie einen privaten Schlüssel: außerhalb des Servers und verschlüsselt. Übernehmen Sie es niemals in das Repository, in dem sich Ihre Website befindet. Wenn derselbe Server auch administrativen Zugriff über Tor benötigt, ist SSH über einen Onion-Dienst erreichbar machen eine sauberere Trennung, als einen Verwaltungszugang auf der öffentlichen Website bereitzustellen.

Analytics und Drittanbieter-Assets verraten mehr als der Header

Das ist der wichtigste Punkt und hat nichts mit Onion-Location zu tun. Jedes Asset eines Drittanbieters, auf das Ihre Seite verweist, führt dazu, dass der Browser des Besuchers eine Anfrage aus dem Onion-Netzwerk heraus und über einen Exit-Node zurück ins Clearnet sendet. Eine Schriftart von einem öffentlichen CDN, ein gehostetes Analytics-Skript, ein eingebetteter Videoplayer oder ein Kommentar-Widget teilt dem jeweiligen Drittanbieter mit, dass jemand Ihre Seite lädt – in einer Sitzung, die der Leser absichtlich über Tor geleitet hat.

Daraus ergeben sich zwei Folgen. Der Drittanbieter erfährt von dem Besuch. Außerdem kann jeder, der eine der beiden Seiten einsehen kann, die beiden Angebote ohne großen Aufwand einander zuordnen, weil Ihre Clearnet-Kopie dieselben Assets von denselben Anbietern lädt.

Stellen Sie alle Inhalte vom selben Origin bereit. Hosten Sie Ihre Schriftarten selbst. Entfernen Sie den gehosteten Analytics-Tag oder verschieben Sie ihn auf Ihren eigenen Server. Dort hält selbst gehostetes Analytics auf einem VPS die Anfrage innerhalb des Onion-Netzwerks. Rechnen Sie damit, dass die Standardeinstellungen des Tor Browser viele Daten blockieren oder reduzieren, die ein Analytics-Tool erfassen möchte. Das ist das gewünschte Ergebnis. Wenn eine Seite ohne ein Skript eines Drittanbieters nicht funktioniert, veröffentlichen Sie diese Seite nicht im Onion-Netzwerk.

Listen Sie auf, welche Ressourcen eine Seite tatsächlich abruft:

curl -s --socks5-hostname 127.0.0.1:9050 http://<your-onion-address>.onion/ \
  | grep -oE '(src|href)="https?://[^"]+"' | sort -u

Jede ausgegebene Zeile ist eine absolute URL, die Ihre Seite vom Browser abrufen lässt. Alles, was nicht Ihre eigene Onion-Adresse ist, stellt eine ausgehende Clearnet-Anfrage dar, die Sie Ihre Leser in Ihrem Namen ausführen lassen.

Das Bedrohungsmodell, klar formuliert

Onion-Location macht einen Onion-Dienst leicht auffindbar. Mehr tut es nicht. Es anonymisiert Sie nicht als Betreiber, weil Ihre Clearnet-Domain weiterhin Registrardaten, DNS-Einträge, ein in den Certificate-Transparency-Logs veröffentlichtes Zertifikat und ein VPS-Konto mit Ihren Abrechnungsdaten dahinter aufweist. Auch den Onion-Dienst anonymisiert es nicht, weil Sie gerade von dieser Clearnet-Domain aus dauerhaft öffentlich bekannt gegeben haben, dass beide Adressen dieselbe Website sind. Der Vorteil liegt beim Leser: Wer über Tor ankommt, kann innerhalb von Tor bleiben, ohne Exit-Node im Pfad und ohne DNS-Abfrage für Ihre Domain. Wenn Ihr Ziel ein Onion-Dienst ist, über den niemand eine Verbindung zu Ihnen herstellen kann, veröffentlichen Sie diesen Header nicht und betreiben Sie die beiden Kopien nicht auf einem Rechner.

Hier treten zwei verwandte Fragen auf, die jeweils eine eigene Antwort haben. Der Unterschied zwischen Tor und einem VPN entscheidet, was Sie für Ihren eigenen Datenverkehr verwenden. Das ist eine separate Entscheidung von der Frage, was Sie veröffentlichen. Wenn Leser in einem zensierten Netzwerk die Clearnet-Website überhaupt nicht erreichen können, sehen sie den Header nie. Dann sind Bridges und pluggable transports wichtiger als alles andere auf dieser Seite.

Die gesamte Einrichtung einmal prüfen

Führen Sie diese Befehle in der angegebenen Reihenfolge aus. Jeder Befehl liefert eine sichtbare Antwort.

1. curl -sI https://example.com/ | grep -i onion-location gibt den Header aus.
2. Derselbe Befehl gibt den Header auch für eine URL aus, die 404 zurückgibt.
3. curl -s --socks5-hostname 127.0.0.1:9050 http://<your-onion-address>.onion/ gibt Ihre Seite zurück.
4. Eine Suche nach Ihrer Clearnet-Domain in dieser Ausgabe liefert keine Treffer.
5. Der Tor Browser auf https://example.com zeigt das .onion available-Symbol.

Wenn die Schritte 1 bis 4 erfolgreich sind, Schritt 5 jedoch nicht, liegt die Ursache fast immer dort, wo der Header ausgeliefert wird, und nicht im Header selbst. Prüfen Sie, ob der Browser tatsächlich die HTTPS-Seite geladen hat und nicht eine zwischengespeicherte Weiterleitung. Führen Sie anschließend curl -sI für die exakt geöffnete URL aus, weil ein location-Block für diesen Pfad die Direktive auf Serverebene verwerfen kann.

FAQ

Warum zeigt der Tor Browser das ".onion available"-Symbol nicht an?

Prüfen Sie zuerst die drei dokumentierten Voraussetzungen. Der Wert muss eine vollständige URL mit einem http:- oder https:-Schema und einem .onion-Host sein. Eine Adresse ohne Schema schlägt daher fehl, ohne eine Fehlermeldung auszugeben. Die Seite muss über HTTPS ausgeliefert werden. Ein Header, der in Ihrem Redirect-Block für Port 80 gesetzt wird, wird daher nie gelesen. Außerdem darf die Seite selbst kein Onion-Service sein. Prüfen Sie anschließend nginx: Jeder add_header innerhalb des passenden location-Blocks verwirft alle add_header auf Serverebene. Ohne das always-Flag fehlt der Header außerdem in 404- und 500-Antworten. Führen Sie curl -sI für die genaue URL aus, die Sie im Browser geladen haben, und bestätigen Sie, dass der Header tatsächlich übertragen wird.

Benötige ich ein TLS-Zertifikat für meine Onion-Site?

Nein. Eine Onion-Adresse der Version v3 wird aus dem öffentlichen Schlüssel des Dienstes abgeleitet. Dadurch wird die Verbindung zu genau diesem Dienst authentifiziert und Ende zu Ende verschlüsselt, bevor eine HTTP-Anfrage gesendet wird. Unverschlüsseltes HTTP innerhalb eines Onion-Services ist die normale Konfiguration. Sie dürfen jedoch nicht Ihr Clearnet-Zertifikat auf dem Onion-Service ausliefern. Die Liste der Subject Alternative Names enthält Ihre Domain. Dadurch zeigt der Browser eine Warnung wegen einer Namensabweichung an und bestätigt jedem Besucher, dass beide Sites auf einem Rechner betrieben werden.

Macht die Veröffentlichung von Onion-Location meine Site anonym?

Nein. Der Header ist eine öffentliche Erklärung Ihrer Clearnet-Domain, dass eine bestimmte Onion-Adresse Ihnen gehört. Jeder kann ihn abrufen. Der Vorteil liegt beim Leser. Er kann in das Onion wechseln und den Exit-Knoten sowie die DNS-Abfrage aus seinem Übertragungsweg entfernen. Als Betreiber gewinnen Sie dadurch keine Anonymität. Außerdem verknüpfen Sie die beiden Adressen dauerhaft. Ein Onion-Service, der nicht zu Ihnen zurückverfolgt werden darf, sollte an anderer Stelle veröffentlicht werden, auf Hardware, die nichts mit der Clearnet-Site gemeinsam hat.

Kann ich anstelle des HTTP-Headers das Meta-Tag verwenden?

Ja, wenn Sie keine Response-Header setzen können. Das ist bei einem statischen Host üblich. Fügen Sie <meta http-equiv="onion-location" content="http://youraddress.onion" /> in den Dokumentkopf ein. Es gelten dieselben drei Voraussetzungen. Die Seite muss daher über HTTPS ausgeliefert werden und darf kein Onion-Service sein. Der wesentliche Unterschied besteht darin, dass das Tag eine feste Adresse ohne Pfad enthält. Der nginx-Header kann dagegen $request_uri anhängen und dem Besucher dieselbe Seite auf dem Onion-Service statt der Startseite anbieten.