Um túnel SSH local criado com ssh -L 5432:localhost:5432 user@server abre a porta 5432 na sua máquina e reencaminha cada ligação, cifrada dentro do SSH, para o PostgreSQL do servidor. A base de dados continua a escutar apenas no localhost remoto, sem nenhuma porta exposta à Internet, e o seu cliente liga-se a 127.0.0.1 como se fosse local.

Como funciona ssh -L 5432:localhost:5432, passo a passo

A sintaxe de -L é [bind_address:]local_port:dest_host:dest_port, e o host de destino é resolvido a partir do servidor SSH, não da sua máquina. É por isso que o localhost do meio significa “a máquina remota”. A referência completa está na página oficial do manual do ssh.

# Foreground tunnel, no remote shell
ssh -N -L 5432:localhost:5432 [email protected]

# In another terminal, connect as if PostgreSQL were local
psql -h 127.0.0.1 -p 5432 -U app db_name
  • -L 5432:localhost:5432: escuta na porta local 5432 e entrega o tráfego na porta 5432 do servidor.
  • -N: não executa nenhum comando remoto; a ligação existe apenas para transportar o túnel.
  • -f (opcional): envia o ssh para segundo plano após a autenticação.

Se a base de dados correr noutro host da rede interna, altere o destino: ssh -N -L 5432:db.internal:5432 admin@bastion. O troço entre o bastion e db.internal deixa de ser cifrado pelo SSH, por isso faça isto apenas numa rede de confiança. Por predefinição, o ssh associa a porta local à interface de loopback; não a exponha em 0.0.0.0 nem ative GatewayPorts a menos que saiba quem mais consegue chegar à sua máquina.

Se um PostgreSQL local já estiver a ocupar a porta 5432, o ssh indica bind: Address already in use. Escolha outra porta local, como -L 15432:localhost:5432, e ligue-se com -p 15432.

LocalForward em ~/.ssh/config: o túnel SSH sem memorizar flags

LocalForward é a diretiva do ssh_config equivalente a -L: primeiro a porta local, depois o destino host:port, separados por um espaço.

Host db-prod
    HostName server.example.com
    User admin
    IdentityFile ~/.ssh/id_ed25519
    LocalForward 15432 localhost:5432
    ExitOnForwardFailure yes
    ServerAliveInterval 30

Com este bloco, basta escrever ssh -N db-prod. Três escolhas no exemplo:

  1. Porta local 15432: evita o conflito com um PostgreSQL que já esteja a escutar na porta 5432 da sua máquina.
  2. ExitOnForwardFailure yes: se a porta local estiver ocupada, o ssh termina em vez de abrir uma sessão que parece normal mas não tem túnel.
  3. ServerAliveInterval 30: envia um keepalive a cada 30 segundos para que uma ligação morta seja detetada mais cedo.

O OpenSSH é rigoroso com as permissões: ~/.ssh a 700 e a chave privada a 600. Todas as diretivas estão listadas na documentação oficial do ssh_config.

Verificar que o túnel SSH local escuta e liga

O sintoma clássico de um túnel avariado é Connection refused no cliente da base de dados; antes de mexer no PostgreSQL, teste cada extremidade isoladamente.

# On your machine: is anything listening on the local port?
ss -ltn | grep 15432              # Linux
lsof -iTCP:15432 -sTCP:LISTEN     # macOS

# On the server: is PostgreSQL listening on loopback?
ss -ltn | grep 5432

# Debug ssh itself
ssh -v -N db-prod

Com -v verá se o servidor recusa o reencaminhamento com uma mensagem administratively prohibited. No sshd_config, AllowTcpForwarding no desativa os túneis; verifique também se há blocos Match que o restrinjam para utilizadores específicos.

Túnel SSH local a partir do telemóvel: o que muda em relação ao computador

O Mosh não faz reencaminhamento de portas: transporta a sessão por UDP, por predefinição nas portas 60000-61000, e usa o SSH apenas para iniciar o mosh-server. Um túnel -L precisa de uma ligação SSH clássica aberta durante todo o tempo em que o utiliza, e o iOS e o Android podem suspender as apps que passam para segundo plano.

Método de acessoReencaminha portas?O que exigeMelhor utilização
ssh -L num computadorSim, TCP dentro do SSHPorta 22 acessível e AllowTcpForwarding ativadoClientes gráficos de bases de dados, migrações a partir da sua máquina
Mosh no iOS/AndroidNãoUDP 60000-61000 e mosh-server no hostUma shell que sobrevive à passagem do wi-fi para os dados móveis
psql no servidor, dentro do tmuxNão é necessárioSessão SSH ou Mosh e psql instaladoConsultas rápidas a partir do telemóvel
Rede mesh (Prialo, Tailscale)Não; acesso direto por IP privadoUm agente em cada dispositivoAcesso regular sem portas abertas nem túneis

A partir do telemóvel, o caminho prático costuma ser ligar-se com Mosh, entrar no tmux e executar o psql no próprio servidor. Com um terminal SSH e Mosh para telemóvel como o termi1, a sessão sobrevive às mudanças de rede, o tmux mantém a consulta longa que deixou a correr e o teclado integrado disponibiliza Ctrl, Tab e as setas para percorrer o histórico do psql ou sair com Ctrl+D. A IA transforma “liga-te à base de dados da app” no comando e escreve-o no prompt sem carregar em Enter; nas ligações marcadas como produção, o Production Guard trava tudo o que apague ou altere dados. O SFTP integrado permite descarregar um ficheiro de pg_dump sem sair da sessão.

Quando não usar um túnel SSH local (-L)

Um túnel -L é uma solução pontual para uma pessoa e uma sessão; fora desse caso, costuma haver uma opção melhor.

  • Acesso permanente ou partilhado: se várias pessoas precisam da base de dados todos os dias, uma rede privada sem portas abertas como o Prialo ou o Tailscale é melhor do que manter túneis individuais.
  • Sessões Mosh: o Mosh não reencaminha portas; se precisar do túnel, abra uma ligação SSH separada.
  • Associar a 0.0.0.0 ou usar GatewayPorts: transforma o seu portátil numa porta de entrada para a base de dados para toda a rede local.
  • Servidores com AllowTcpForwarding no: é uma política do administrador, não um erro a contornar.
  • Consultas pontuais a partir do telemóvel: executar o psql no servidor é mais simples do que manter um túnel ativo.

Perguntas frequentes

O que significa localhost em ssh -L 5432:localhost:5432?

Em ssh -L 5432:localhost:5432, localhost é resolvido pelo servidor SSH, não pela sua máquina. Por isso, aponta para o PostgreSQL que escuta na interface de loopback do host remoto. Para chegar a outra máquina da rede interna, substitua-o pelo nome ou pelo IP privado desse host.

Como executo um túnel SSH local em segundo plano?

Um túnel SSH local corre em segundo plano com ssh -f -N -L 15432:localhost:5432 admin@server: -f envia o ssh para segundo plano após a autenticação e -N dispensa a shell remota. Para o fechar, encontre o processo com pgrep -f 15432 e termine-o com kill.

O Mosh consegue reencaminhar portas como um túnel SSH?

O Mosh não consegue reencaminhar portas: não suporta reencaminhamento de portas nem reencaminhamento X11 e transporta a sessão por UDP, por predefinição nas portas 60000-61000. Reencaminhar uma porta exige uma ligação SSH normal, que pode correr em paralelo com a sessão Mosh ao mesmo tempo.

Um túnel SSH local para uma base de dados de produção é seguro?

Um túnel SSH local para produção cifra o tráfego e evita expor a porta da base de dados à Internet, mas qualquer processo na sua máquina pode usar a porta reencaminhada enquanto esta estiver aberta. Associe-a apenas a 127.0.0.1, feche-a quando terminar e use um utilizador da base de dados com privilégios mínimos.