API de protección

Endpoints que protegen y exponen el propio DTVSOL Super Router: quién puede acceder a los puertos de administración, a quién ha bloqueado fail2ban, qué puertos públicos se reenvían a los suscriptores, las reglas de reenvío por MAC, la opción 82 de DHCP (circuit ID / remote ID del relay) y el agente SNMP del propio router.

La autenticación, el formato de los errores y los códigos de estado se describen en la descripción general de la API.

Lista de acceso de administración

El puerto de la API (8880 de forma predeterminada) y el puerto del monitor de OLT (8881 de forma predeterminada) están protegidos por una misma lista de acceso. Mientras la lista está vacía, ambos puertos están abiertos a cualquier origen ("status": "open (no restrictions)"); en cuanto contiene una red, solo se aceptan en esos puertos las conexiones nuevas desde las redes de la lista y se descarta cualquier otra conexión nueva. Las reglas se guardan para que sobrevivan a un reinicio.

Peligro

Agregue la red desde la que administra el router antes que cualquier otra cosa, o su siguiente solicitud podría ser rechazada.

GET /protect

Las 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

Modifica el router

Agrega una red a la lista de acceso y recarga las reglas de protección de puertos.

Nombre	En	Tipo	Notas
network	body	string	Una dirección IPv4 o address/0..32. Una dirección sin prefijo se guarda como /32. Obligatorio.
comment	body	string	Texto libre.

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" } ]
}

Errores: 400 Invalid network: … (red no válida), 409 Network … already allowed (la red ya está permitida). GET /protect/add?network=…&comment=… hace lo mismo con parámetros de consulta.

DELETE /protect

Modifica el router

Elimina una red de la lista de acceso y recarga las reglas de protección de puertos. Al eliminar la última, los puertos quedan abiertos a todos.

Nombre	En	Tipo	Notas
network	body	string	Tal como se agregó; una dirección sin prefijo 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 (red no encontrada) cuando no está en la lista. GET /protect/delete?network=… hace lo mismo con parámetros de consulta.

fail2ban

fail2ban bloquea los orígenes que fallan la autenticación repetidamente (la API registra cada clave rechazada).

GET /fail2ban

Si fail2ban está en ejecución, y los contadores y las direcciones bloqueadas 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"] }
  ]
}

Cuando fail2ban no está activo: {"running": false, "jails": []}.

POST /fail2ban

Modifica el router

Levanta el bloqueo de una dirección en todas las jails.

Nombre	En	Tipo	Notas
unban	body	string	La dirección IPv4 o IPv6 que se desbloqueará.

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 (IP no válida); 500 Unban failed (falló el desbloqueo, con detail) cuando fail2ban lo rechaza.

Reenvío de puertos

Reenvíos de puertos entrantes (DNAT) desde una dirección y un puerto públicos hacia la dirección y el puerto de un suscriptor. /portforward es un alias de /pf con exactamente el mismo comportamiento. Un reenvío se identifica por protocolo + dirección pública + puerto público. Los reenvíos cuya dirección de cliente está en una VLAN desactivada se conservan, pero no se aplican hasta que la VLAN se vuelva a activar.

GET /pf

Los reenvíos guardados y las reglas NAT activas que los implementan.

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

Modifica el router

Agrega un reenvío de puerto y reconstruye las reglas de reenvío. También POST /portforward.

Nombre	En	Tipo	Notas
proto	body	string	tcp (predeterminado) o udp.
public_ip	body	string	Dirección IPv4 pública; vacío significa cualquier dirección del router.
public_port	body	integer	1–65535. Obligatorio.
client_ip	body	string	La dirección IPv4 del suscriptor. Obligatorio.
client_port	body	integer	1–65535. Obligatorio.
comment	body	string	Texto libre.

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" }
}

Errores: 400 (proto must be tcp or udp, Invalid public_ip, Ports must be 1..65535, Invalid client_ip: protocolo, dirección pública, puertos o dirección de cliente no válidos); 409 A forward for that proto/public_ip:port already exists (ya existe un reenvío para ese protocolo/dirección pública:puerto).

DELETE /pf

Modifica el router

Elimina un reenvío de puerto y reconstruye las reglas de reenvío. También DELETE /portforward.

Nombre	En	Tipo	Notas
proto	body	string	tcp (predeterminado) o udp.
public_ip	body	string	Tal como se agregó; vacío para “cualquier dirección”.
public_port	body	integer	Tal como se agregó.

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 (ningún reenvío coincide) cuando no hay coincidencias.

Vista del firewall

Vistas de solo lectura de las reglas de reenvío por MAC que el router mantiene para los clientes registrados.

GET /firewall

Las reglas MAC de la cadena de reenvío, cada una con el cliente al que pertenece.

Nombre	En	Tipo	Notas
network	query	string	Solo los clientes cuya dirección está en esta red IPv4 (a.b.c.d/nn); en ese caso se omiten las reglas sin un cliente conocido.

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": "" } }
  ]
}

Sin filtro, una regla cuya MAC no corresponde a un cliente registrado tiene "client": null.

GET /firewall/full

La cadena de reenvío completa tal como la lista el kernel (en modo detallado, con contadores y números de línea), una cadena de texto por línea.

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", "…"] }

Opción 82 de DHCP

Cuando las solicitudes DHCP llegan a través de un relay (por ejemplo una OLT) que añade la opción 82, el circuit ID y el remote ID del relay identifican el puerto del suscriptor.

GET /option82

Las concesiones (leases) que contienen datos de la opción 82, si la captura en el registro está habilitada y las últimas líneas capturadas del registro (hasta 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

Modifica el router

Agrega (o elimina) el include de registro de la opción 82 en la configuración del servidor DHCP y recarga DHCP.

Nombre	En	Tipo	Notas
enable	body	boolean	true para registrar la opción 82 en cada confirmación de concesión, false para dejar de hacerlo.

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)" }

Si el servidor DHCP rechaza la configuración, el cambio se revierte y la respuesta es 400 con detail; la lectura de la opción 82 desde las concesiones sigue funcionando. Al deshabilitarla, la respuesta es "message": "Option 82 capture disabled".

Agente SNMP

El agente SNMP de solo lectura del propio router (v2c, UDP 161, IPv4 e IPv6), que utilizan los sistemas de monitoreo externos para graficar el tráfico por interfaz y por cliente.

GET /snmp

Si el agente está en ejecución y su configuración. La community en sí nunca se devuelve, solo si está configurada.

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": [ "…" ]
}

La respuesta también contiene algunos campos de texto informativos que describen lo que publica el agente.

POST /snmp

Modifica el router

Reescribe la configuración del agente SNMP, habilita el agente en el arranque y lo reinicia.

Los campos que se omiten conservan su valor actual.

Nombre	En	Tipo	Notas
community	body	string	Community de solo lectura: de 1 a 64 caracteres de A-Z a-z 0-9 _ . : -.
location	body	string	Texto de ubicación del sistema.
contact	body	string	Texto de contacto del 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 }

Errores: 400 Invalid community (A-Z a-z 0-9 _.:- , max 64) (community no válida); 500 cuando no se pudo guardar la configuración o el agente no logró reiniciarse (snmpd restart failed, con detail).

Equivalentes en la API de acciones

Las mismas operaciones mediante GET /api?action=…, con todos los parámetros en la cadena de consulta (consulte la API de acciones).

Acción	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