# Túneis SSH

Túnel SSH persistente entre dois VPS com autossh: um serviço do receptor fica no localhost do iniciador sem ser exposto.

Fonte: https://ardumaker.com/pt/docs/tuneles-ssh/

- Categoria: Servidores e infraestrutura
- Estado: Disponível
- Requisitos: Dois VPS (da mesma empresa para o fluxo automático); Ser membro da empresa com acesso aos dois VPS; Sistemas com systemd e um OpenSSH compatível (consulte com `ver_funciones_vps`, função “Túneis SSH entre VPS”)
- Ferramentas MCP (Só leem): `ver_estado_receptor_tunel_vps`, `listar_claves_receptor_tunel_vps`, `ver_estado_iniciador_tunel_vps`, `listar_tuneles_vps`, `ver_tunel_vps`
- Ferramentas MCP (Escrevem ou modificam): `configurar_receptor_tunel_vps`, `agregar_clave_receptor_tunel_vps`, `configurar_iniciador_tunel_vps`, `crear_tunel_vps`, `controlar_tunel_vps`
- Ferramentas MCP (Destrutivas): `configurar_tunel_entre_vps`, `eliminar_receptor_tunel_vps`, `eliminar_clave_receptor_tunel_vps`, `eliminar_iniciador_tunel_vps`, `eliminar_tunel_vps`

## O que permite fazer?

- Usar a partir de um VPS um serviço que escuta noutro (uma base, uma API interna) como se estivesse em `localhost`, sem o publicar na internet.
- Montar tudo em uma única chamada (`configurar_tunel_entre_vps`), ou passo a passo.
- Autorizar ou revogar as chaves que podem entrar no receptor.
- Arrancar, parar ou reiniciar cada túnel, e ver o seu estado em tempo real.

## Quando convém usar?

- Uma app em um VPS precisa da base de dados que vive noutro.
- Separar uma API interna do seu frontend sem abrir portas públicas do serviço.

## Como funciona na ArduMaker?

É um reencaminhamento **local** (`ssh -L`) que corre no **iniciador**: o que escuta na `puerto_remoto` do receptor fica disponível em `localhost:puerto_local` dentro do iniciador. Não funciona ao contrário e não expõe nada à internet.

### Os passos

1. **Receptor** (`configurar_receptor_tunel_vps`): cria um usuário dedicado ao túnel, configura o `sshd` para aceitar esse usuário na porta 2222 (sem terminal, sem X11, sem agente, só reencaminhamento TCP) e publica a 2222 com um redirecionamento. Corre em segundo plano.
2. **Iniciador** (`configurar_iniciador_tunel_vps`): instala o `autossh` e gera um par de chaves ed25519. Também em segundo plano.
3. **Chave**: a chave pública do iniciador é autorizada no receptor (`agregar_clave_receptor_tunel_vps`).
4. **Túnel** (`crear_tunel_vps`): cria no iniciador um serviço systemd `ardutunnel_<nombre>` que corre `autossh -L <local>:<destino>:<porta>` contra o receptor, ativa-o e arranca-o.

`configurar_tunel_entre_vps` faz os quatro passos e também arranca o túnel. Espera que cada papel termine de se instalar (até alguns minutos); se um não terminar a tempo, para com `tunel_rol_instalando` e pode ser retomado com `desde`. Um papel já instalado não é reinstalado, uma chave já autorizada é reutilizada e um túnel com esse nome e porta local já criado é devolvido tal como está.

## O que muda realmente?

### No receptor

- Um usuário de túnel com as suas chaves autorizadas em um bloco próprio de `authorized_keys`.
- Um arquivo de configuração do `sshd` gerido pela ArduMaker que acrescenta a porta 2222 com o seu bloco `Match LocalPort` (a 22 continua declarada). Não deve ser editado à mão: é reescrito por inteiro sempre que muda um papel.
- Um redirecionamento público para a 2222 do VPS.

### No iniciador

- O pacote `autossh` e um par de chaves ed25519 do usuário de túnel.
- Um serviço `ardutunnel_<nombre>.service` por túnel, com `Restart=always`, ativado no arranque.
- Um `known_hosts` próprio dos túneis: a primeira chave do receptor fica fixada e, se depois mudar, o túnel não liga.

## Portas e link

| Dado | Valor |
| --- | --- |
| Porta do receptor no VPS | 2222 |
| Porta pública | O `host_port` do redirecionamento para a 2222 (`public_port`) |
| Host | O `dnsip` do receptor |
| Cadeia de link | `<usuario>@<dnsip> -p <public_port>` |

```ini
ExecStart=/usr/bin/autossh -M 0 -N \
  -o "ServerAliveInterval=30" -o "ServerAliveCountMax=3" \
  -o "StrictHostKeyChecking=accept-new" -o "ExitOnForwardFailure=yes" \
  -L <puerto_local>:localhost:<puerto_remoto> \
  -i <clave_del_tunel> -p <public_port> <usuario>@<dnsip>
```

`ver_estado_receptor_tunel_vps` devolve a cadeia de link e um exemplo de uso para ligar a partir de outra máquina com `ssh -N -L`.

## Esquema

**Um túnel entre dois VPS**

```text
App no iniciador (localhost:<puerto_local>)
  ↓
autossh (serviço ardutunnel_<nombre>)
  ↓
Redirecionamento do receptor (<dnsip>:<public_port> → 2222)
  ↓
sshd do receptor :2222 (só o usuário de túnel, só reencaminhamento)
  ↓
Serviço do receptor (localhost:<puerto_remoto>)
```

## Resultado esperado

- `ver_tunel_vps` mostra o túnel com o estado em tempo real do seu serviço systemd.
- `listar_tuneles_vps` lista os túneis do iniciador; `ver_estado_iniciador_tunel_vps` traz a sua chave pública e o número de túneis.
- A partir do iniciador, o serviço responde em `localhost:<puerto_local>`.

```bash
systemctl status ardutunnel_mi-base
nc -vz localhost 15432
```

## Erros e resolução

| Resposta | Causa | O que fazer |
| --- | --- | --- |
| 409 `tunel_rol_instalando` | Um papel ainda está sendo instalado | Pedir de novo; retoma a partir daí |
| `tunel_rol_fallido` | A instalação de um papel falhou | Ver o estado do papel e tentar de novo |
| `tunel_mismo_vps` | Receptor e iniciador são o mesmo VPS | Usar dois VPS diferentes |
| 409 porta local em uso | Outro túnel do iniciador já usa essa `local_port` | Escolher outra porta |
| 409 `Key already registered` | A chave já está autorizada | Nada a fazer |
| O túnel não liga | A chave do receptor mudou, ou a chave do iniciador não está autorizada | Rever `ver_logs_systemd_vps` do serviço `ardutunnel_<nombre>` |

> **PRECAUCION:** `eliminar_iniciador_tunel_vps` apaga **todos** os túneis do VPS de uma vez, e `eliminar_receptor_tunel_vps` remove o usuário de túnel e as suas chaves: os túneis que entravam deixam de funcionar. `controlar_tunel_vps` com `stop` corta o que estiver a passar pelo túnel.

Se um passo do fluxo falhar, desfaz-se o que é possível; os pacotes instalados ficam e são indicados em `residuo` (reinstalar não muda nada). O fluxo aceita `idempotency_key` e `simular`.

## Relação com MCP

Sim, nos perfis `/mcp` e `/mcp/vps`. Instalar um papel devolve um `operacion_id`: `ver_operacion` diz quando está pronto.

| Ferramenta | Tipo |
| --- | --- |
| `configurar_tunel_entre_vps` | Escrita (fluxo completo) |
| `ver_estado_receptor_tunel_vps`, `listar_claves_receptor_tunel_vps`, `ver_estado_iniciador_tunel_vps`, `listar_tuneles_vps`, `ver_tunel_vps` | Leitura |
| `configurar_receptor_tunel_vps`, `configurar_iniciador_tunel_vps`, `agregar_clave_receptor_tunel_vps`, `crear_tunel_vps` | Escrita |
| `controlar_tunel_vps` | Escrita (com `stop` corta o tráfego) |
| `eliminar_tunel_vps`, `eliminar_clave_receptor_tunel_vps`, `eliminar_receptor_tunel_vps`, `eliminar_iniciador_tunel_vps` | Destrutiva |

Referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs) e exemplos em [/mcp/tuneles](https://ardumaker.com/pt/mcp/tuneles).

## Funcionalidades relacionadas

- [Firewall e portas](https://ardumaker.com/pt/docs/firewall-y-puertos/)
- [Serviços systemd](https://ardumaker.com/pt/docs/systemd/)
- [PostgreSQL](https://ardumaker.com/pt/docs/postgresql/)
- [Servidores VPS](https://ardumaker.com/pt/docs/vps/)