API de proteção

Endpoints que protegem e expõem o próprio DTVSOL Super Router: quem pode acessar as portas de gerência, quem o fail2ban baniu, quais portas públicas são redirecionadas para assinantes, as regras de encaminhamento por MAC, o DHCP option 82 (circuit ID / remote ID do relay) e o próprio agente SNMP do roteador.

Autenticação, formato de erro e códigos de status estão descritos na visão geral da API.

Lista de permitidos de gerência

A porta da API (8880 por padrão) e a porta do monitor de OLT (8881 por padrão) ficam atrás de uma única lista de permitidos. Enquanto a lista está vazia, as duas portas ficam abertas para qualquer origem ("status": "open (no restrictions)"); assim que ela tem uma rede, só novas conexões vindas das redes da lista são aceitas nessas portas, e qualquer outra nova conexão é descartada. As regras são salvas, então sobrevivem a uma reinicialização.

Perigo

Adicione a rede da qual você gerencia o roteador antes de qualquer outra coisa, ou a sua próxima requisição pode ser recusada.

GET /protect

As redes permitidas.

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/protect

{
  "port": 8880,
  "count": 1,
  "networks": [
    { "network": "XXX.XXX.XXX.0/24", "comment": "NOC", "added": "2026-09-27 10:00:00" }
  ],
  "status": "protected"
}

POST /protect

Altera o roteador

Adiciona uma rede à lista de permitidos e recarrega as regras de proteção das portas.

Nome	Em	Tipo	Observações
network	body	string	Um endereço IPv4 ou address/0..32. Um endereço sozinho é gravado como /32. Obrigatório.
comment	body	string	Texto livre.

curl -X POST http://ROUTER-IP:8880/protect \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"network": "XXX.XXX.XXX.0/24", "comment": "NOC"}'

{
  "ok": true,
  "code": 201,
  "message": "Network XXX.XXX.XXX.0/24 allowed",
  "networks": [ { "network": "XXX.XXX.XXX.0/24", "comment": "NOC", "added": "2026-09-27 10:00:00" } ]
}

Erros: 400 Invalid network: …, 409 Network … already allowed. GET /protect/add?network=…&comment=… faz o mesmo com parâmetros de consulta.

DELETE /protect

Altera o roteador

Remove uma rede da lista de permitidos e recarrega as regras de proteção das portas. Remover a última abre as portas para todos.

Nome	Em	Tipo	Observações
network	body	string	Como foi adicionada; um endereço sozinho significa /32.

curl -X DELETE http://ROUTER-IP:8880/protect \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"network": "XXX.XXX.XXX.0/24"}'

{ "ok": true, "code": 200, "message": "Network XXX.XXX.XXX.0/24 removed", "networks": [] }

404 Network … not found quando ela não está na lista. GET /protect/delete?network=… faz o mesmo com parâmetros de consulta.

fail2ban

O fail2ban bane origens que falham repetidamente na autenticação (a API registra toda chave rejeitada).

GET /fail2ban

Se o fail2ban está rodando, e os contadores e endereços banidos de cada jail.

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/fail2ban

{
  "running": true,
  "jails": [
    { "jail": "sshd", "currently_banned": 2, "total_banned": 7, "banned_ips": ["XXX.XXX.XXX.1", "XXX.XXX.XXX.7"] }
  ]
}

Quando o fail2ban não está ativo: {"running": false, "jails": []}.

POST /fail2ban

Altera o roteador

Retira o banimento de um endereço em todas as jails.

Nome	Em	Tipo	Observações
unban	body	string	O endereço IPv4 ou IPv6 a desbanir.

curl -X POST http://ROUTER-IP:8880/fail2ban \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"unban": "XXX.XXX.XXX.1"}'

{ "ok": true, "code": 200, "message": "Unbanned XXX.XXX.XXX.1", "detail": "" }

400 Invalid IP; 500 Unban failed (com detail) quando o fail2ban recusa.

Redirecionamento de portas

Redirecionamentos de porta de entrada (DNAT) de um endereço e porta públicos para o endereço e porta de um assinante. /portforward é um alias de /pf, com exatamente o mesmo comportamento. Um redirecionamento é identificado por protocolo + endereço público + porta pública. Redirecionamentos cujo endereço de cliente está em uma VLAN desligada são mantidos, mas não aplicados até que a VLAN seja ligada de novo.

GET /pf

Os redirecionamentos salvos e as regras de NAT ativas que os implementam.

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/pf

{
  "count": 1,
  "forwards": [
    { "proto": "tcp", "public_ip": "XXX.XXX.XXX.10", "public_port": 8080, "client_ip": "100.64.0.2", "client_port": 80, "comment": "camera", "created": "2026-09-27 10:00:00" }
  ],
  "live": ["-A PREROUTING -d XXX.XXX.XXX.10/32 -p tcp -m tcp --dport 8080 … -j DNAT --to-destination 100.64.0.2:80"]
}

GET /portforward

Alias de GET /pf.

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/portforward

POST /pf

Altera o roteador

Adiciona um redirecionamento de porta e reconstrói as regras de redirecionamento. Também POST /portforward.

Nome	Em	Tipo	Observações
proto	body	string	tcp (padrão) ou udp.
public_ip	body	string	Endereço IPv4 público; vazio significa qualquer endereço do roteador.
public_port	body	integer	1–65535. Obrigatório.
client_ip	body	string	O endereço IPv4 do assinante. Obrigatório.
client_port	body	integer	1–65535. Obrigatório.
comment	body	string	Texto livre.

curl -X POST http://ROUTER-IP:8880/pf \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"proto": "tcp", "public_ip": "XXX.XXX.XXX.10", "public_port": 8080, "client_ip": "100.64.0.2", "client_port": 80, "comment": "camera"}'

{
  "ok": true,
  "code": 201,
  "message": "Port forward added",
  "forward": { "proto": "tcp", "public_ip": "XXX.XXX.XXX.10", "public_port": 8080, "client_ip": "100.64.0.2", "client_port": 80, "comment": "camera", "created": "2026-09-27 10:00:00" }
}

Erros: 400 (proto must be tcp or udp, Invalid public_ip, Ports must be 1..65535, Invalid client_ip); 409 A forward for that proto/public_ip:port already exists.

DELETE /pf

Altera o roteador

Remove um redirecionamento de porta e reconstrói as regras de redirecionamento. Também DELETE /portforward.

Nome	Em	Tipo	Observações
proto	body	string	tcp (padrão) ou udp.
public_ip	body	string	Como foi adicionado; vazio para “qualquer endereço”.
public_port	body	integer	Como foi adicionada.

curl -X DELETE http://ROUTER-IP:8880/pf \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"proto": "tcp", "public_ip": "XXX.XXX.XXX.10", "public_port": 8080}'

{ "ok": true, "code": 200, "message": "Port forward removed" }

404 No forward matching tcp/XXX.XXX.XXX.10:8080 quando nenhum corresponde.

Visão do firewall

Visões somente leitura das regras de encaminhamento por MAC que o roteador mantém para os clientes cadastrados.

GET /firewall

As regras de MAC na chain de encaminhamento, cada uma com o cliente a que pertence.

Nome	Em	Tipo	Observações
network	query	string	Só os clientes cujo endereço está nesta rede IPv4 (a.b.c.d/nn); as regras sem cliente conhecido ficam então de fora.

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/firewall?network=100.64.0.0/22"

{
  "count": 1,
  "mac_rules": [
    { "mac": "AA:BB:CC:DD:EE:FF", "iface": "vlan100", "client": { "ip": "100.64.0.2", "hostname": "client-aabbccddeeff", "comment": "" } }
  ]
}

Sem filtro, uma regra cujo MAC não é de um cliente cadastrado tem "client": null.

GET /firewall/full

A chain de encaminhamento inteira como o kernel a lista (detalhada, com contadores e números de linha), uma string por linha.

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/firewall/full

{ "forward_chain": ["Chain FORWARD (policy ACCEPT 0 packets, 0 bytes)", "num   pkts bytes target     prot opt in     out     source               destination", "…"] }

DHCP option 82

Quando as requisições DHCP chegam por um relay (por exemplo uma OLT) que adiciona a option 82, o circuit ID e o remote ID do relay identificam a porta do assinante.

GET /option82

As concessões que trazem dados de option 82, se a captura para o log está ativada, e as últimas linhas capturadas no log (até 50).

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/option82

{
  "count": 1,
  "from_leases": [
    { "ip": "100.64.0.2", "circuit_id": "0:1:2", "remote_id": "\"olt-1\"", "mac": "AA:BB:CC:DD:EE:FF" }
  ],
  "capture_enabled": true,
  "recent_log": ["… DTVSOL-OPT82 ip=100.64.0.2 circuit=00:01:02 remote=…"]
}

POST /option82

Altera o roteador

Adiciona (ou remove) o include de log da option 82 na configuração do servidor DHCP e recarrega o DHCP.

Nome	Em	Tipo	Observações
enable	body	boolean	true para registrar a option 82 a cada commit de concessão, false para parar.

curl -X POST http://ROUTER-IP:8880/option82 \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"enable": true}'

{ "ok": true, "code": 200, "message": "Option 82 capture enabled (logged to journal + parsed by /option82)" }

Se o servidor DHCP rejeitar a configuração, a alteração é revertida e a resposta é 400 com detail; ler a option 82 a partir das concessões continua funcionando. Desativar responde "message": "Option 82 capture disabled".

Agente SNMP

O próprio agente SNMP somente leitura do roteador (v2c, UDP 161, IPv4 e IPv6), usado por sistemas de monitoramento externos para gerar gráficos de tráfego por interface e por cliente.

GET /snmp

Se o agente está rodando e as suas configurações. A community em si nunca é retornada — só se há uma definida.

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/snmp

{
  "running": true,
  "enabled": "enabled",
  "listen": "udp/161 (IPv4+IPv6)",
  "community_set": true,
  "sys_location": "POP 1",
  "sys_contact": "noc@example.net",
  "per_client_count": 120,
  "sample": [ "…" ]
}

A resposta também contém alguns campos de texto informativos que descrevem o que o agente publica.

POST /snmp

Altera o roteador

Reescreve a configuração do agente SNMP, ativa o agente na inicialização e o reinicia.

Os campos omitidos mantêm o valor atual.

Nome	Em	Tipo	Observações
community	body	string	Community somente leitura: de 1 a 64 caracteres de A-Z a-z 0-9 _ . : -.
location	body	string	Texto de localização do sistema.
contact	body	string	Texto de contato do sistema.

curl -X POST http://ROUTER-IP:8880/snmp \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"community": "YOUR_COMMUNITY", "location": "POP 1", "contact": "noc@example.net"}'

{ "ok": true, "code": 200, "message": "SNMP configured", "detail": null }

Erros: 400 Invalid community (A-Z a-z 0-9 _.:- , max 64); 500 quando as configurações não puderam ser salvas ou o agente não conseguiu reiniciar (snmpd restart failed, com detail).

Equivalentes na API de ações

As mesmas operações por GET /api?action=…, com todos os parâmetros na query string (veja a API de ações).

Ação	Parâmetros de consulta	Equivale a
action=protect-list	—	GET /protect
action=protect-add	network, comment	POST /protect
action=protect-delete	network	DELETE /protect
action=fail2ban-status	—	GET /fail2ban
action=fail2ban-unban	ip	POST /fail2ban
action=pf-list	—	GET /pf
action=pf-add	proto, public_ip, public_port, client_ip, client_port, comment	POST /pf
action=pf-del	proto, public_ip, public_port	DELETE /pf
action=firewall	network	GET /firewall
action=firewall-full	—	GET /firewall/full
action=option82	—	GET /option82
action=snmp-status	—	GET /snmp
action=snmp-set	community, location, contact	POST /snmp