Como adicionar Onion-Location no nginx

O que o cabeçalho Onion-Location faz

O cabeçalho Onion-Location é uma linha no seu vhost clearnet que anuncia o seu endereço onion ao Tor Browser. Um visitante que acede a https://example.com através do Tor vê um botão roxo na barra de endereços com o texto .onion available. Com um clique, passa para o seu serviço onion. É um mecanismo de descoberta, e nada mais. O cabeçalho não cria o serviço onion nem oculta qualquer informação sobre si.

Este guia pressupõe que as duas partes já existem. Tem um site num VPS atrás do nginx e tem um serviço onion v3 funcional a apontar para esse site. Se ainda não tiver a segunda parte, configure-a primeiro: alojar um site onion num VPS explica as linhas do torrc e o primeiro ficheiro hostname. O objetivo a seguir é associar as duas partes sem fazer uma aparecer na outra.

O que o Tor Browser exige antes de aceitar o cabeçalho

O Tor Project documenta três condições. As três devem ser cumpridas. Caso contrário, a pílula nunca aparece.

• O valor de Onion-Location deve ser um URL válido com um esquema http: ou https: e um hostname .onion.
• A página Web que define o cabeçalho deve ser servida por HTTPS.
• A página Web que define o cabeçalho não pode ser um site onion.

A segunda condição é a que mais causa problemas. A terceira explica por que nunca deve definir este cabeçalho no vhost onion. Existe uma quarta regra que não aparece na documentação textual, mas está presente na implementação: o Tor Browser só processa o cabeçalho no documento de nível superior. O código compara o destino do carregamento com o documento antes de fazer qualquer ação. Por isso, um cabeçalho devolvido por uma folha de estilos, uma imagem ou uma resposta de API é ignorado.

Por predefinição, o browser mostra a pílula e aguarda um clique. Para ativar um salto automático, o utilizador deve abrir Settings, depois Privacy and Security e, em seguida, Onion Services, onde pode definir "Prioritize .onion sites when known" como "Always". Não é possível forçar esse comportamento no lado do servidor. Trate o cabeçalho como uma opção, não como um redirecionamento.

Adicione o cabeçalho Onion-Location no nginx

O cabeçalho deve ficar no bloco server que termina o TLS do seu domínio clearnet. Se o colocar no bloco da porta 80, nada acontece, porque esse bloco apenas emite um redirecionamento e a regra dois exclui um cabeçalho definido numa página HTTP simples.

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 transporta o caminho e a query string, para que um leitor em https://example.com/guides/tor receba o mesmo caminho no onion. Se o omitir, todos os visitantes vão parar à página inicial do onion em vez da página que estavam a ler.

always é importante devido a um limite documentado do nginx. add_header adiciona o campo apenas quando o código de resposta é 200, 201, 204, 206, 301, 302, 303, 304, 307 ou 308. A sua página 404 é um ponto de entrada real a partir dos resultados de pesquisa e, sem always, não transporta qualquer cabeçalho.

A segunda armadilha do nginx é a herança, que falha silenciosamente. As diretivas add_header são herdadas do nível de configuração anterior apenas quando não existem diretivas add_header no nível atual. Assim, um bloco location /assets/ { add_header Cache-Control ...; } descarta o Onion-Location definido no nível server para todos os URLs dentro dele. Se definir cabeçalhos por localização em qualquer ponto, repita a linha Onion-Location dentro de cada um desses blocos. Como o nginx escolhe um bloco server e location merece uma leitura se esse comportamento for novo para si.

Recarregue a configuração e verifique uma página normal e uma página inexistente:

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

Ambos os comandos devem mostrar uma linha onion-location:. O segundo comando é a prova de que always está a funcionar. Se o segundo não produzir saída, a flag está em falta ou um bloco location está a ocultar a diretiva.

A tag HTML meta quando não é possível definir cabeçalhos

Hosts estáticos e alguns painéis de CDN não permitem adicionar um cabeçalho de resposta arbitrário. O mesmo valor funciona como um elemento meta no cabeçalho do documento, porque o navegador lê os mesmos dados do cabeçalho do documento, quer tenham chegado por HTTP, quer através de uma tag http-equiv.

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

Os três requisitos continuam a aplicar-se. A página que contém a tag tem de usar HTTPS e não pode ser um onion. A diferença é que a tag contém um único endereço fixo, sem caminho, porque não existe uma variável no servidor para expandir. Todas as páginas que a contêm disponibilizam a página inicial do onion. Esse é o custo do fallback; por isso, prefira o cabeçalho quando tiver controlo sobre o servidor.

Sirva o onion a partir do seu próprio vhost do nginx

O site clearnet e o onion não podem partilhar um bloco de servidor. O Tor Browser envia Host: <your-onion-address>.onion. Se nenhum bloco de servidor assumir esse nome, o nginx recorre ao servidor predefinido. Esse servidor é o seu vhost clearnet, e todos os URLs gerados por esse vhost usam o seu domínio.

Aponte o hidden service para uma porta à qual apenas a interface de loopback responde:

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

Depois atribua a essa porta o seu próprio 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 mantém este vhost fora do seu IP público. Assim, alguém que faça uma pesquisa ao endereço do VPS não consegue obtê-lo e compará-lo byte a byte com a cópia clearnet. absolute_redirect off faz o nginx emitir valores Location relativos. Dessa forma, o redirecionamento para a barra final de um diretório devolve Location: /guides/, e não um URL completo. O nginx já cria redirecionamentos absolutos a partir do cabeçalho Host, e não de server_name, porque server_name_in_redirect assume off por predefinição. Ainda assim, um redirecionamento relativo elimina completamente essa questão.

Por que a página onion ainda envia os visitantes para o site clearnet?

O nginx raramente é a origem do vazamento. A aplicação é. Tudo o que cria uma URL absoluta a partir de um endereço de site configurado usará o seu domínio, independentemente do vhost que tenha atendido o pedido.

• Uma tag de link rel="canonical" apontada para https://example.com/.... Esta é a causa mais comum e expõe a página clearnet exata a qualquer pessoa que consulte o código-fonte.
• Redirecionamentos gerados pelo framework, e não pelo nginx, como SECURE_SSL_REDIRECT do Django ou as opções home e siteurl do WordPress.
• og:url e as outras meta tags de cartões sociais.
• Entradas de sitemap e RSS, que são absolutas por especificação.
• Páginas de erro da aplicação, que normalmente incluem um link "voltar à página inicial" criado a partir da mesma definição.

A correção depende da sua stack e não existe uma solução genérica. A verificação é genérica. Obtenha a página onion através do Tor e procure o seu domínio na resposta.

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

--socks5-hostname envia o nome para a porta SOCKS do tor para resolução, o que é necessário porque nada na sua máquina consegue resolver localmente um nome .onion. A porta 9050 é a predefinida para um daemon tor instalado através de um pacote. Um resultado vazio indica sucesso. Qualquer ocorrência indica uma página que fornece o seu domínio clearnet a todos os visitantes onion. Execute o comando na página inicial e depois numa URL que produza um 404.

Verifique a cadeia de redirecionamento separadamente, porque o corpo de um redirecionamento normalmente está vazio:

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

Um valor Location que nomeie example.com indica que um redirecionamento está a enviar o visitante onion de volta para a clearnet, através de um nó de saída, num pedido que ele acreditava permanecer dentro do Tor.

Não apresente o certificado clearnet no onion

Um endereço onion v3 é derivado da chave pública do próprio serviço. Por isso, o Tor autentica e cifra o circuito para esse serviço específico antes de enviar qualquer pedido HTTP. Usar HTTP simples dentro de um serviço onion é a configuração normal. Isso não é o mesmo que usar HTTP simples na Internet.

Se criar o vhost onion copiando o vhost clearnet, também copia ssl_certificate. Nesse caso, o onion apresenta um certificado cujos nomes alternativos do sujeito incluem example.com. Ocorrem dois problemas. O navegador apresenta um erro de incompatibilidade de nome, porque o URL é o endereço onion e o certificado não o abrange. Além disso, cada visitante que prossegue recebe uma declaração assinada de que estes dois sites estão no mesmo computador. Mantenha o vhost onion num ficheiro próprio, com o seu próprio server_name. Isso também evita interferências do plugin nginx do Certbot, porque esse plugin altera o bloco de servidor correspondente ao domínio para o qual é solicitado um certificado.

Qual pacote do Tor usar e como manter segura a chave do serviço

O pacote tor disponível no arquivo do Ubuntu funciona para este caso e não exige configuração adicional. Ele fica atrás da série estável atual. Portanto, para um serviço que pretende manter em execução, use o repositório Debian do próprio Tor Project e deixe que o apt o atualize juntamente com os restantes pacotes. Em agosto de 2026, os passos documentados são estes:

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

Escreva /etc/apt/sources.list.d/tor.sources, substituindo a suite pelo codinome da sua versão, obtido em 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

O pacote deb.torproject.org-keyring mantém a chave de assinatura atualizada. Assim, o repositório não deixa de ser validado daqui a um ano. Escolha uma fonte e mantenha-se nela. O pacote do arquivo e o pacote do repositório têm versões diferentes. Se ambos estiverem ativados, o apt alternará entre eles durante as atualizações.

O diretório HiddenServiceDir contém a identidade do serviço. O ficheiro hs_ed25519_secret_key nesse diretório é o endereço onion, porque o endereço é a parte pública desse par de chaves. Se perder o ficheiro, o endereço desaparece permanentemente. Não existe uma autoridade que possa emiti-lo novamente. Se copiar o ficheiro para um local sem proteção, qualquer pessoa que tenha essa cópia poderá executar o seu serviço onion.

O tor recusa-se a usar um diretório que possa ser lido por outros utilizadores. Verifique o modo e o proprietário antes de verificar qualquer outra coisa:

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

A listagem deve mostrar drwx------, com o proprietário e o grupo debian-tor em Debian e Ubuntu. Se as permissões forem mais amplas, o tor regista uma linha como Permissions on directory /var/lib/tor/onion_site/ are too permissive. e o serviço não inicia. Corrija isso com sudo chown -R debian-tor:debian-tor /var/lib/tor/onion_site, seguido de sudo chmod 700 /var/lib/tor/onion_site, reinicie com sudo systemctl restart tor e consulte o resultado com sudo journalctl -u tor@default -n 30.

Faça uma cópia de segurança desse diretório como faria com uma chave privada: fora do servidor e encriptada. Nunca o versione no repositório que contém o seu site. Se o mesmo servidor também precisar de acesso administrativo através do Tor, aceder ao SSH através de um serviço onion é uma separação mais limpa do que expor um caminho de gestão no site público.

Analytics e recursos de terceiros expõem mais do que o cabeçalho

Esta é a parte mais importante e não tem relação com Onion-Location. Cada recurso de terceiros referenciado pela sua página gera uma solicitação que o navegador do visitante faz para fora da rede onion e de volta à clearnet através de um nó de saída. Uma fonte de um CDN público, um script de analytics alojado externamente, um reprodutor de vídeo incorporado ou um widget de comentários: cada um informa esse terceiro de que alguém está a carregar a sua página numa sessão que o leitor encaminhou deliberadamente através do Tor.

Há duas consequências. O terceiro fica a saber da visita. Além disso, como a sua cópia na clearnet carrega os mesmos recursos dos mesmos fornecedores, qualquer pessoa com visibilidade de um dos lados pode associar as duas propriedades sem esforço.

Sirva tudo a partir da mesma origem. Aloje as suas fontes localmente. Remova a tag de analytics alojada externamente ou mova-a para o seu próprio servidor, onde analytics alojado num VPS mantém a solicitação dentro da rede onion. Espere que as predefinições do Tor Browser bloqueiem ou reduzam muitos dos dados que qualquer ferramenta de analytics tenta recolher. Esse é o resultado correto. Se uma página não puder funcionar sem um script de terceiros, não publique essa página na rede onion.

Liste o que uma página realmente solicita:

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

Cada linha apresentada por este comando é um URL absoluto que a sua página solicita ao navegador. Tudo o que não for o seu próprio endereço onion é uma solicitação de saída para a clearnet que está a pedir aos leitores para fazerem em seu nome.

O modelo de ameaças, em termos claros

O Onion-Location facilita encontrar um serviço onion, e é só isso que faz. Ele não torna o operador anónimo, porque o seu domínio clearnet continua associado a registos do registrador, registos DNS, um certificado publicado nos logs de Certificate Transparency e uma conta de VPS com os seus dados de faturação. Também não torna o onion anónimo, porque acabou de publicar, a partir desse domínio clearnet, uma declaração pública duradoura de que os dois endereços correspondem ao mesmo site. O benefício é do leitor: quem chega através do Tor pode permanecer dentro do Tor, sem um nó de saída no caminho e sem uma consulta DNS ao seu domínio. Se o seu objetivo é ter um serviço onion ao qual ninguém consiga associá-lo, não publique este cabeçalho e não execute as duas cópias na mesma máquina.

Surgem aqui duas perguntas relacionadas, e cada uma tem a sua própria resposta. A diferença entre Tor e uma VPN determina o que usa para o seu próprio tráfego, uma decisão separada daquilo que publica. Se os leitores numa rede censurada não conseguirem sequer aceder ao site clearnet, nunca verão o cabeçalho. Nesse caso, bridges e transportes conectáveis são mais importantes do que qualquer outro aspeto desta página.

Verifique toda a configuração uma vez

Execute estes comandos pela ordem indicada. Cada um apresenta um resultado que pode consultar.

1. curl -sI https://example.com/ | grep -i onion-location apresenta o cabeçalho.
2. O mesmo comando contra um URL que devolve 404 também o apresenta.
3. curl -s --socks5-hostname 127.0.0.1:9050 http://<your-onion-address>.onion/ devolve a sua página.
4. Procurar o seu domínio clearnet nessa saída não devolve resultados.
5. O Tor Browser em https://example.com apresenta o indicador .onion available.

Se os passos 1 a 4 forem concluídos com sucesso e o passo 5 não, a causa está quase sempre no local onde o cabeçalho é servido, e não no próprio cabeçalho. Confirme se o browser carregou realmente a página HTTPS, e não um redirecionamento em cache. Em seguida, execute curl -sI contra o URL exato que abriu, porque um bloco location nesse caminho específico pode estar a descartar a diretiva definida ao nível do servidor.

FAQ

Porque é que o Tor Browser não mostra o indicador ".onion available"?

Confirme primeiro os três requisitos documentados. O valor tem de ser um URL completo com um esquema http: ou https: e um anfitrião .onion. Por isso, um endereço sem esquema falha e não apresenta nenhum erro. A página tem de ser servida por HTTPS. Assim, um cabeçalho definido no bloco de redirecionamento da porta 80 nunca é lido. Além disso, a própria página não pode ser um onion. Depois, verifique o nginx: qualquer add_header dentro do bloco location correspondente descarta todos os add_header definidos ao nível do servidor. Sem a flag always, o cabeçalho não aparece nas respostas 404 e 500. Execute curl -sI contra o URL exato que carregou no browser e confirme que o cabeçalho está efetivamente a ser enviado.

Preciso de um certificado TLS para o meu site onion?

Não. Um endereço onion v3 é derivado da chave pública do serviço. Por isso, o circuito é autenticado para esse serviço específico e cifrado de ponta a ponta antes de qualquer pedido HTTP ser enviado. HTTP simples dentro de um serviço onion é a configuração normal. O que deve evitar é apresentar no onion o certificado do seu site clearnet. A lista de nomes alternativos do certificado contém o seu domínio. Isso provoca um aviso de incompatibilidade de nomes no browser e confirma a todos os visitantes que os dois sites estão na mesma máquina.

A publicação de Onion-Location torna o meu site anónimo?

Não. O cabeçalho é uma declaração pública do seu domínio clearnet de que um determinado endereço onion lhe pertence, e qualquer pessoa pode obtê-lo. O benefício é do leitor, que pode passar para o onion e retirar o nó de saída e a consulta DNS do seu percurso. Como operador, não obtém anonimato e associa permanentemente os dois endereços. Um serviço onion que não possa ser associado a si deve ser publicado noutro local, em hardware que não partilhe nada com o site clearnet.

Posso usar a meta tag em vez do cabeçalho HTTP?

Sim, quando não pode definir cabeçalhos de resposta, que é a situação habitual num host estático. Coloque <meta http-equiv="onion-location" content="http://youraddress.onion" /> no cabeçalho do documento. Aplicam-se os mesmos três requisitos. A página tem de usar HTTPS e não pode ser um onion. A única diferença real é que a tag contém um endereço fixo sem caminho, enquanto o cabeçalho do nginx pode acrescentar $request_uri e disponibilizar ao visitante a mesma página no onion, em vez da página inicial.