# Firewall e portas

Redirecionamentos de porta do VPS, SSH com vencimento e listas de IP permitidos ou excluídos no firewall do host.

Fonte: https://ardumaker.com/pt/docs/firewall-y-puertos/

- Categoria: Servidores e infraestrutura
- Estado: Disponível
- Requisitos: Um VPS da empresa com host atribuído; Para ver e criar redirecionamentos: ser membro da empresa com acesso ao VPS; Para alterar a política de IP: ser admin da empresa
- Ferramentas MCP (Só leem): `listar_redirecciones_vps`, `ver_politica_ip_puertos_vps`
- Ferramentas MCP (Escrevem ou modificam): `crear_redireccion_vps`, `cambiar_politica_ip_puertos_vps`, `cambiar_lista_ip_app`
- Ferramentas MCP (Destrutivas): `eliminar_redireccion_vps`

## O que permite fazer?

- Expor uma porta TCP ou UDP de dentro do VPS em uma porta pública do host, atribuída automaticamente.
- Abrir SSH (porta 22) por um número de horas, com fecho automático ao expirar.
- Decidir que IPs chegam às portas redirecionadas: a todos, só a uma lista ou a todos menos uma lista; para todo o VPS ou para uma porta concreta.
- Ver que redirecionamentos são da plataforma (não são tocados) e quais são seus.

## Quando convém usar?

- Um serviço que não é HTTP (um jogo, um broker MQTT, um servidor VPN) e precisa de uma porta própria.
- Entrar por SSH a partir do seu computador durante uma janela de trabalho.
- Deixar uma porta acessível só a partir do escritório ou do IP de um cliente.

> **INFO:** Para um site não é preciso abrir portas: os domínios entram pela 443 do host e chegam ao nginx do VPS. Ver [Nginx](https://ardumaker.com/pt/docs/nginx).

## Como funciona na ArduMaker?

### Redirecionamentos de porta

1. Indica-se a porta de dentro do VPS (`container_port`) e o protocolo (`tcp` por padrão, ou `udp`).
2. Se já existe um redirecionamento para essa porta e protocolo, devolve-se o mesmo: não se duplica.
3. O host escolhe uma porta livre (`host_port`) e cria o redirecionamento para o VPS.
4. No firewall do host (`ufw`) essa porta é aberta a toda a internet, salvo se a porta estiver restrita ou houver uma política de IP global, que o novo redirecionamento herda.
5. De fora chega-se com `<dnsip do VPS>:<host_port>`.

### Portas que nunca ficam públicas

- PostgreSQL (5432), MySQL/MariaDB (3306) e Redis (6379, ou a porta onde foi instalado, e a sua porta TLS): o redirecionamento é criado, mas só é alcançável pela rede interna da plataforma. Para abrir uma base ao exterior usa-se o acesso externo de Apps, com a sua lista de IP.
- A porta do agente da ArduMaker está reservada: a criação rejeita-a.
- O redirecionamento para a 443 do VPS é do nginx do VPS: nunca é aberto à internet nem a outros VPS.

### SSH com vencimento

Um redirecionamento para a porta 22 aceita `closed_in_hs`: passadas essas horas, a plataforma apaga-o sozinha e registra-o no registro do VPS. A listagem mostra `is_ssh: true` e as horas que faltam. Sem `closed_in_hs`, o SSH fica aberto até ser apagado.

### Política de IP

| Modo | Regra no firewall do host | Uso |
| --- | --- | --- |
| `todos` | `allow <porta>` | Aberto a qualquer um (o habitual) |
| `solo` | Um `allow from <ip>` por IP; o resto cai no `deny` padrão | Lista branca; além disso fecha-se o acesso a partir de outros VPS do host |
| `excluir` | `deny from <ip>` à frente e o `allow` geral | Bloquear IPs concretos |

- `alcance: "global"` aplica-se a todos os redirecionamentos do VPS; `alcance: "puerto"` a um `host_port` e prevalece sobre a global.
- As listas aceitam IPv4 e IPv6, com ou sem prefixo. Por padrão, até 20 entradas e prefixos não mais amplos que /24 (IPv4) ou /48 (IPv6). Nunca `0.0.0.0/0` nem `::/0`, nem loopback, multicast ou link-local.
- Aplica-se no momento: primeiro acrescentam-se as regras novas e depois apagam-se as velhas, para não deixar um buraco aberto nem cortar todos de repente.
- As portas da plataforma não são tocadas. A porta de uma app de Apps é alterada pelo caminho de Apps (mesma lista; `excluir` não está disponível aí).

## O que muda realmente?

- No host: o redirecionamento (um dispositivo de proxy para o VPS) e as suas regras de `ufw`. Nada muda dentro do VPS.
- Ao apagar um redirecionamento, primeiro restauram-se as suas regras de IP e esquecem-se as suas políticas, e depois remove-se a regra geral.
- A política fica guardada com o seu estado (`aplicada`, `pendiente` ou `fallida`) e vê-se em `ver_politica_ip_puertos_vps`.
- Cada criação, exclusão ou alteração de política fica no registro de atividade do VPS.

## IP real e portas da plataforma

O filtro por IP vive no host, **antes** do redirecionamento: aí vê-se o IP real do cliente. O serviço dentro do VPS, por outro lado, vê as links de um redirecionamento TCP como se viessem de `127.0.0.1`. Se a sua app precisa do IP do cliente, convém publicá-la como web (por nginx), onde chega em `X-Real-IP`.

| Classificação (`motivo_plataforma`) | O que é | Editável? |
| --- | --- | --- |
| `agente` | Agente da ArduMaker | Não (não é listado) |
| `nginx_del_vps` | Entrada web para a 443 do VPS | No |
| `tailnet` | Bases de dados e Redis, só rede interna | No |
| `apps` | Criada por Apps (acesso externo ou URL de uma app) | A partir de Apps |
| (vazio) | Sua | Sim |

## Esquema

**Uma link TCP a uma porta redirecionada**

```text
Cliente (<dnsip>:<host_port>)
  ↓
Firewall do host (ufw) (todos / solo / excluir; vê o IP real)
  ↓
Redirecionamento (host_port → container_port)
  ↓
Serviço no VPS (vê a link a partir de 127.0.0.1)
```

## Resultado esperado

- `crear_redireccion_vps` devolve `name` (o `device_name` para o apagar), `host_port`, `container_port`, `protocol`, `is_public_for_ip` e `solo_tailscale` (true se a porta ficou só na rede interna).
- `listar_redirecciones_vps` acrescenta a cada um `de_plataforma`, `editable`, `gestionado_por` e `motivo_plataforma`, e o `ip_host` (o `dnsip`) para ligar.
- `ver_politica_ip_puertos_vps` devolve a política global e, por porta, a própria e a `efectiva`.

```bash
nc -vz <dnsip> <host_port>
ssh -p <host_port> usuario@<dnsip>
```

## Erros e resolução

| Resposta | Causa | O que fazer |
| --- | --- | --- |
| `container_port <n> is reserved` | Porta reservada do agente | Usar outra porta |
| 400 ao criar | Porta não positiva, protocolo diferente de tcp/udp, `closed_in_hs` não positivo, ou o host sem portas livres | Corrigir o argumento |
| 409 `redireccion_de_plataforma` | O redirecionamento foi criado por Apps | Removê-lo a partir da app |
| 404 `redirect_not_found` | Esse `host_port` ou `device_name` não é deste VPS | Listar primeiro |
| 400 `ips_requeridas` | `solo` ou `excluir` sem IP | Acrescentar pelo menos uma |
| 400 `lista_ip_invalida` / `lista_ip_demasiado_amplia` | Entrada que não é IP ou faixa demasiado ampla; `data.invalid` diz quais | Corrigir a lista |
| 409 `modo_no_soportado` | `excluir` sobre a porta de uma app | Usar `solo` ou `todos` |
| 424 `regla_no_aplicada` | O firewall do host falhou; a política ficou `fallida` | Repetir a mesma chamada |
| 403 | Um membro tentou alterar a política | Pedir a um admin |

Criar um redirecionamento é seguro de repetir: se já existe para essa porta e protocolo, devolve-se o mesmo. Alterar a política também (aplicar a mesma lista não muda nada). Apagar um redirecionamento corta na hora as links que o usam.

## Relação com MCP

Sim, nos perfis `/mcp` e `/mcp/vps`.

| Ferramenta | Tipo | Permissão |
| --- | --- | --- |
| `listar_redirecciones_vps` | Leitura | Membro |
| `ver_politica_ip_puertos_vps` | Leitura | Membro |
| `crear_redireccion_vps` | Escrita (aceita `idempotency_key`) | Membro |
| `cambiar_politica_ip_puertos_vps` | Escrita | Admin da empresa |
| `eliminar_redireccion_vps` | Destrutiva | Membro |
| `cambiar_lista_ip_app` | Escrita | Lista de IP do acesso externo de uma app; exige os IPs escritos |

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

## Funcionalidades relacionadas

- [Nginx](https://ardumaker.com/pt/docs/nginx/)
- [Túneis SSH](https://ardumaker.com/pt/docs/tuneles-ssh/)
- [Usuários Linux](https://ardumaker.com/pt/docs/usuarios-linux/)
- [PostgreSQL](https://ardumaker.com/pt/docs/postgresql/)
- [Servidores VPS](https://ardumaker.com/pt/docs/vps/)