API de redes

Estos endpoints deciden qué interfaces sirve el router con DHCP (IPv4) y con DHCPv6 + anuncios de router (IPv6), qué direcciones entregan los pools, cómo se reparte la delegación de prefijos IPv6 entre las VLAN y qué resolutores DNS reciben los suscriptores. La URL base, la autenticación y el formato de errores se describen en la descripción general de la API.

Cada cambio se verifica antes de que surta efecto: se prueba la configuración de DHCP y se reinicia el servicio, y si alguno de los dos pasos falla se restaura el archivo anterior y la respuesta dice … — rolled back (revertido). Una respuesta 5xx puede incluir broken_data_files, que nombra los archivos de datos del router que no se pueden analizar.

Las interfaces se indican por nombre (vlan110, svlan300.10, bond0…). Para las VLAN, consulte VLAN, direcciones IP y rutas: al agregar una VLAN con una dirección, se sirve automáticamente.

Redes e interfaces

GET /networks

Todas las redes IPv4 configuradas en las interfaces del router, con la red IPv6 de la misma interfaz cuando la tiene.

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

{
  "count": 1,
  "networks": [
    {
      "iface": "vlan110",
      "gateway": "100.64.8.1",
      "subnet": "100.64.8.0",
      "mask": "255.255.255.0",
      "cidr": 24,
      "network": "100.64.8.0/24",
      "bcast": "100.64.8.255",
      "ipv6": "XXXX:XXXX:110::/64",
      "gateway6": "XXXX:XXXX:110::1"
    }
  ]
}

GET /interfaces

Cada red IPv4 y si DHCP realmente la sirve: dhcp_active es verdadero solo cuando la subred está en la configuración de DHCP y la interfaz está en la lista de escucha de DHCP. Lo mismo para DHCPv6 cuando la interfaz tiene una red IPv6.

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

{
  "count": 1,
  "interfaces": [
    {
      "iface": "vlan110",
      "gateway": "100.64.8.1",
      "network": "100.64.8.0/24",
      "cidr": 24,
      "in_dhcp_conf": true,
      "in_dhcp_listen": true,
      "dhcp_active": true,
      "network6": "XXXX:XXXX:110::/64",
      "gateway6": "XXXX:XXXX:110::1",
      "in_dhcp6_conf": true,
      "in_dhcp6_listen": true,
      "dhcp6_active": true
    }
  ]
}

GET /net y GET /net6 dan la misma respuesta.

GET /iface

Todos los enlaces del router (puertos físicos, bonds, VLAN, S-VLAN, C-VLAN, USB, loopback) con su estado, etiqueta VLAN, direcciones y contadores.

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

{
  "interfaces": [
    {
      "name": "vlan110",
      "type": "vlan",
      "status": "UP",
      "parent": "bond0",
      "ips": ["100.64.8.1/24"],
      "ips6": ["XXXX:XXXX:110::1/64"],
      "vlan_id": 108,
      "vlan_proto": "802.1Q",
      "mtu": 1500,
      "speed_mbps": null,
      "rx_bytes": 123456789,
      "tx_bytes": 987654321
    }
  ]
}

type es uno de physical, vlan, svlan, cvlan, usb, loopback. status es UP solo cuando el enlace está activo y además tiene portadora.

DHCP (IPv4)

POST /dhcp/reload

Modifica el router

Reinicia el servidor DHCP (después de probar su configuración).

Prueba la configuración de DHCP y reinicia el servicio DHCP. Cualquier otra ruta /dhcp/… responde 404 Use /dhcp/reload.

curl -X POST -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/dhcp/reload

{ "ok": true, "message": "DHCP reloaded" }

En caso de fallo: 500 con error (DHCP config test failed, la prueba de configuración falló, o DHCP restart failed, el reinicio falló) y detail.

POST /net

Modifica el router

Agrega la subred IPv4 de la interfaz al servidor DHCP y comienza a servirla.

Sirve la red IPv4 ya configurada en una interfaz: su bloque de subred se agrega a la configuración de DHCP y la interfaz a la lista de escucha. Si la subred ya está allí, solo se actualiza la lista de escucha.

Nombre	En	Tipo	Notas
iface	body	string	Interfaz que tiene la dirección IPv4, p. ej. vlan110.
label	body	string	Texto opcional que se escribe como comentario en el bloque de la subred.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"iface":"vlan110","label":"OLT 1 PON 0/1/3"}' \
  http://ROUTER-IP:8880/net

{
  "ok": true,
  "code": 201,
  "message": "Network 100.64.8.0/24 added on vlan110",
  "network": { "iface": "vlan110", "gateway": "100.64.8.1", "network": "100.64.8.0/24", "cidr": 24 },
  "label": "OLT 1 PON 0/1/3"
}

Errores: 404 cuando la interfaz no tiene dirección IPv4; 500 cuando falla la prueba de configuración o el reinicio (se revierte).

DELETE /net

Modifica el router

Deja de servir la subred IPv4 de la interfaz y elimina su bloque de la configuración de DHCP.

Nombre	En	Tipo	Notas
iface	body	string	Interfaz que se dejará de servir.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"iface":"vlan110"}' http://ROUTER-IP:8880/net

{
  "ok": true,
  "code": 200,
  "message": "Network 100.64.8.0/24 removed from vlan110",
  "network": { "iface": "vlan110", "network": "100.64.8.0/24" }
}

Errores: 409 mientras todavía haya clientes registrados en la interfaz (Cannot remove: N client(s) registered on vlan110. Delete them first., es decir, no se puede eliminar porque hay N clientes registrados en vlan110; elimínelos primero); 404 cuando la interfaz no tiene dirección IPv4; 500 cuando no se encuentra el bloque de la subred o falla la prueba/el reinicio de DHCP.

DHCPv6 y anuncios de router

POST /net6

Modifica el router

Inicia DHCPv6 y los anuncios de router en la red IPv6 de la interfaz.

Agrega la red IPv6 de la interfaz a DHCPv6, con un pool de direcciones derivado de la red (para una /64: de ::1000 a ::ffff), y actualiza los anuncios de router. Si las demás subredes DHCPv6 ya tienen servidores de nombres y no hay un resolutor IPv6 global definido, la nueva subred los hereda.

Nombre	En	Tipo	Notas
iface	body	string	Interfaz que tiene una dirección IPv6 global.

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

{
  "ok": true,
  "code": 201,
  "message": "IPv6 network XXXX:XXXX:110::/64 added on vlan110 (DHCPv6 + radvd)",
  "network6": { "iface": "vlan110", "gateway": "XXXX:XXXX:110::1", "prefix": 64, "network": "XXXX:XXXX:110::/64" },
  "radvd": { "ok": true, "message": "radvd reloaded" },
  "pool": "XXXX:XXXX:110::1000 - XXXX:XXXX:110::ffff",
  "dns": "XXXX:XXXX::53"
}

Cuando no se puede derivar un pool, la respuesta incluye warning en lugar de pool; cuando no hay un resolutor que heredar, dns es null y una note lo indica. Errores: 404 No IPv6 address on interface '…' (no hay dirección IPv6 en la interfaz); 500 cuando falla la prueba o el reinicio de DHCPv6 (se revierte).

DELETE /net6

Modifica el router

Detiene DHCPv6 en la interfaz y libera su rango de delegación de prefijos.

Elimina la interfaz de DHCPv6. El bloque subnet6 se elimina a menos que otra interfaz servida use la misma red; el rango de delegación de prefijos de la interfaz se libera.

Nombre	En	Tipo	Notas
iface	body	string	Interfaz que se dejará de servir por IPv6.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"iface":"vlan110"}' http://ROUTER-IP:8880/net6

{
  "ok": true,
  "code": 200,
  "message": "IPv6 network XXXX:XXXX:110::/64 removed from vlan110",
  "radvd": { "ok": true, "message": "radvd reloaded" },
  "removed_pd_pool": { "network6": "XXXX:XXXX:110::/64", "start": "XXXX:XXXX:b:1000::", "end": "XXXX:XXXX:b:10ff::", "size": 256 }
}

POST /net6/pool

Modifica el router

Escribe (o reemplaza) el rango de direcciones DHCPv6 de la subred de la interfaz y reinicia DHCPv6.

Define el rango de direcciones que se entrega en la subred IPv6 de una interfaz. Sin start/end, el rango se deriva de la red. Los parámetros se leen del cuerpo y, después, de la cadena de consulta.

Nombre	En	Tipo	Notas
iface	body or query	string	Interfaz cuyo bloque subnet6 existe (consulte POST /net6).
start	body or query	IPv6	Primera dirección, opcional; debe estar dentro de la red.
end	body or query	IPv6	Última dirección, opcional; debe estar dentro de la red.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"iface":"vlan110"}' http://ROUTER-IP:8880/net6/pool

{
  "ok": true,
  "code": 200,
  "message": "pool added on XXXX:XXXX:110::/64",
  "iface": "vlan110",
  "network": "XXXX:XXXX:110::/64",
  "pool": "XXXX:XXXX:110::1000 - XXXX:XXXX:110::ffff",
  "dns_added": false
}

Errores: 400 para una dirección no válida o fuera de la red, o cuando no se puede derivar un pool; 404 cuando la interfaz no tiene dirección IPv6 o no tiene bloque subnet6.

POST /net6/lease

Modifica el router

Cambia los tiempos de vida de direcciones y prefijos DHCPv6 para todas las subredes.

Define los tiempos de vida válido y preferido que entrega DHCPv6 (direcciones y prefijos delegados) y actualiza los anuncios de router. GET /net6/lease acepta los mismos parámetros desde la cadena de consulta.

Nombre	En	Tipo	Notas
valid	body	integer	Tiempo de vida válido en segundos, como mínimo 120.
preferred	body	integer	Opcional; por defecto es la mitad de valid y no puede superarlo.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"valid":86400,"preferred":43200}' http://ROUTER-IP:8880/net6/lease

{
  "ok": true,
  "code": 200,
  "message": "DHCPv6 lifetimes updated",
  "changed": ["default-lease-time = 86400", "preferred-lifetime = 43200", "dhcp-renewal-time = 21600", "dhcp-rebinding-time = 34560"],
  "radvd": { "ok": true, "message": "radvd reloaded" },
  "note": "existing leases keep their old lifetime until the client next renews"
}

Delegación de prefijos IPv6

Los prefijos delegados (por defecto /64) provienen de un único pool para todo el router definido en la configuración del router (pd_pool, pd_len). Cada VLAN recibe una porción de ese pool (por defecto pd_slice prefijos); los primeros pd_reserve prefijos se reservan para prefijos fijados a clientes individuales.

GET /pd

El pool, su capacidad, la porción de cada VLAN, los prefijos fijados y las rutas delegadas que el kernel tiene en este momento.

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

{
  "pool": "XXXX:XXXX:a::/48",
  "prefix_len": 64,
  "usable": true,
  "reserved_for_pinned": 4096,
  "default_slice": 256,
  "capacity": {
    "prefixes_total": 65536,
    "prefixes_reserved": 4096,
    "prefixes_used": 256,
    "prefixes_free": 61184,
    "largest_free_run": 61184,
    "vlans_at_default_slice": 240,
    "vlans_free_at_default_slice": 239
  },
  "per_vlan": {
    "vlan110": { "network6": "XXXX:XXXX:110::/64", "index": 4096, "slice": 0, "start": "XXXX:XXXX:a:1000::", "end": "XXXX:XXXX:a:10ff::", "len": 64, "size": 256 }
  },
  "pinned": [{ "mac": "AA:BB:CC:DD:EE:FF", "hostname": "cpe-1", "prefix6": "XXXX:XXXX:a:5::/64" }],
  "live_routes": ["XXXX:XXXX:a:1000::/64 via fe80::1 dev vlan110 proto dhcp metric 1024"],
  "live_count": 1
}

POST /pd

Modifica el router

Reserva una porción del pool de delegación para la VLAN y comienza a delegar prefijos en ella.

Habilita la delegación de prefijos en una interfaz que ya tiene DHCPv6 (POST /net6). Llamarlo de nuevo con un size nuevo reasigna la porción.

Nombre	En	Tipo	Notas
iface	body	string	Interfaz con un bloque subnet6.
size	body	integer	Número opcional de prefijos, una potencia de dos (256, 512, 1024…); por defecto es la porción configurada.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"iface":"vlan110","size":256}' http://ROUTER-IP:8880/pd

{
  "ok": true,
  "code": 201,
  "message": "prefix delegation enabled on vlan110",
  "iface": "vlan110",
  "network": "XXXX:XXXX:110::/64",
  "pool": "XXXX:XXXX:a:1000:: - XXXX:XXXX:a:10ff::",
  "prefix_len": 64,
  "capacity": 256,
  "next": "set the CPE Site Prefix Type to \"Delegated\""
}

Cuando la porción se movió, se agregan replaced y warning (los CPE conservan su prefijo anterior hasta que vence la concesión; ejecute una sincronización). Errores: 400 cuando size no es una potencia de dos; 404 sin bloque subnet6; 507 cuando el pool está agotado (con requested y largest_free_run).

POST /pd/resize

Modifica el router

Mueve la VLAN a una porción de otro tamaño.

Nombre	En	Tipo	Notas
iface	body	string	Interfaz que ya delega.
size	body	integer	Nuevo número de prefijos (potencia de dos).

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"iface":"vlan110","size":1024}' http://ROUTER-IP:8880/pd/resize

La respuesta es la misma que la de POST /pd. Errores: 400 sin size; 404 cuando la interfaz no tiene delegación; 409 cuando ya tiene esa cantidad de prefijos.

DELETE /pd

Modifica el router

Detiene la delegación de prefijos en la VLAN y libera su porción.

Nombre	En	Tipo	Notas
iface	body	string	Interfaz en la que se dejará de delegar.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"iface":"vlan110"}' http://ROUTER-IP:8880/pd

{
  "ok": true,
  "code": 200,
  "message": "prefix delegation removed from vlan110",
  "note": "delegated routes are withdrawn as their leases expire"
}

POST /pd/assign

Modifica el router

Fija un prefijo delegado fijo a un cliente y recarga DHCPv6.

Entrega a un cliente (por MAC) el mismo prefijo delegado cada vez. Sin prefix, se toma el primer prefijo libre de la banda reservada. GET /pd/assign acepta los mismos parámetros desde la cadena de consulta.

Nombre	En	Tipo	Notas
mac	body	string	La MAC de un cliente registrado.
prefix	body	IPv6 prefix	Opcional; debe tener la longitud delegada y estar dentro del pool. La longitud puede omitirse.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF","prefix":"XXXX:XXXX:a:5::/64"}' \
  http://ROUTER-IP:8880/pd/assign

{
  "ok": true,
  "code": 200,
  "message": "pinned XXXX:XXXX:a:5::/64 to AA:BB:CC:DD:EE:FF",
  "mac": "AA:BB:CC:DD:EE:FF",
  "prefix6": "XXXX:XXXX:a:5::/64"
}

Errores: 404 cliente desconocido; 400 prefijo no válido o fuera del pool; 409 prefijo fijado a otro cliente; 507 no hay prefijos libres en la banda reservada.

DELETE /pd/assign

Modifica el router

Elimina el prefijo fijado de un cliente y recarga DHCPv6.

Nombre	En	Tipo	Notas
mac	body	string	Cliente cuyo prefijo fijado se elimina.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF"}' http://ROUTER-IP:8880/pd/assign

{ "ok": true, "code": 200, "message": "unpinned XXXX:XXXX:a:5::/64 from AA:BB:CC:DD:EE:FF" }

Errores: 404 cuando el cliente no tiene un prefijo fijado.

POST /pd/sync

Modifica el router

Concilia las rutas de prefijos delegados del kernel con las concesiones DHCPv6 (a menos que se use dry=1).

Ejecuta ahora el conciliador de rutas delegadas y devuelve su salida. Cualquier método en /pd/sync lo ejecuta.

Nombre	En	Tipo	Notas
dry	query	1	Solo informar lo que cambiaría.

curl -X POST -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/pd/sync?dry=1"

{
  "ok": true,
  "code": 200,
  "dry_run": true,
  "output": ["…the reconciler's report, one line per entry…"]
}

Resolutores DNS

Los resolutores que los suscriptores reciben por DHCP y DHCPv6: un valor global predeterminado y, opcionalmente, valores específicos por VLAN.

GET /dns

Lo que realmente recibe cada VLAN servida, de dónde proviene (per-vlan, global o none) y qué VLAN servidas no reciben ningún resolutor.

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

{
  "global": { "ipv4": "XXX.XXX.XXX.53, XXX.XXX.XXX.53", "ipv6": "XXXX:XXXX::53", "domain": "example.net" },
  "per_vlan": { "ipv4": { "100.64.9.0": "XXX.XXX.XXX.53" }, "ipv6": {} },
  "effective": [
    { "iface": "vlan110", "enabled": true, "ipv4": "XXX.XXX.XXX.53, XXX.XXX.XXX.53", "ipv4_source": "global", "ipv6": "XXXX:XXXX::53", "ipv6_source": "global" }
  ],
  "serving_no_resolver": []
}

POST /dns

Modifica el router

Define los resolutores globales y/o el dominio para DHCP y DHCPv6 y reinicia los servicios DHCP.

Nombre	En	Tipo	Notas
v4	body	string or list	Resolutores IPv4, separados por comas o como lista JSON.
v6	body	string or list	Resolutores IPv6.
domain	body	string	Dominio de búsqueda.
apply	body	string	Opcional: all descarta los valores específicos por VLAN para que todas las VLAN sigan el valor predeterminado; missing no cambia nada más.
iface	body	string	Si se indica, en su lugar define un valor específico para esa VLAN (igual que POST /dns/{iface}).

Se requiere al menos uno de v4, v6, domain.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"v4":"XXX.XXX.XXX.53,XXX.XXX.XXX.53","v6":"XXXX:XXXX::53","domain":"example.net"}' \
  http://ROUTER-IP:8880/dns

{
  "ok": true,
  "code": 200,
  "message": "resolvers updated",
  "changed": ["ipv4 -> XXX.XXX.XXX.53, XXX.XXX.XXX.53", "domain -> example.net", "ipv6 -> XXXX:XXXX::53"],
  "note": "clients pick this up at their next DHCP renewal",
  "status": { "ipv4": "XXX.XXX.XXX.53, XXX.XXX.XXX.53", "ipv6": "XXXX:XXXX::53", "domain": "example.net" }
}

Con apply, applied_to enumera las VLAN cuyos valores específicos se descartaron. Sin él, warning y una lista shadowing nombran las VLAN cuyos propios resolutores IPv6 ocultan el nuevo valor predeterminado.

POST /dns/{iface}

Modifica el router

Escribe un valor específico de resolutores para una VLAN y reinicia el o los servicios DHCP.

Nombre	En	Tipo	Notas
iface	path	string	Interfaz VLAN servida, p. ej. vlan130.
v4	body	string or list	Resolutores IPv4 para esta VLAN.
v6	body	string or list	Resolutores IPv6 para esta VLAN.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"v4":"XXX.XXX.XXX.53"}' http://ROUTER-IP:8880/dns/vlan130

{
  "ok": true,
  "code": 200,
  "message": "resolvers set on vlan130",
  "iface": "vlan130",
  "override": { "ipv4": "XXX.XXX.XXX.53" },
  "note": "overrides the global resolvers for this VLAN only"
}

Errores: 400 sin v4/v6 o con una dirección no válida; 404 cuando la interfaz, su red o su bloque de subred no existe.

DELETE /dns/{iface}

Modifica el router

Elimina el valor específico de la VLAN para que vuelva a heredar los resolutores globales.

Nombre	En	Tipo	Notas
iface	path	string	Interfaz VLAN.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/dns/vlan130

{
  "ok": true,
  "code": 200,
  "message": "override removed from vlan130",
  "removed": ["ipv4"],
  "now_inherits": { "ipv4": "XXX.XXX.XXX.53, XXX.XXX.XXX.53", "ipv6": "XXXX:XXXX::53", "domain": "example.net" }
}

Errores: 404 cuando la VLAN no tiene un valor específico.

DELETE /dns

Modifica el router

Borra los resolutores globales (o el dominio); las VLAN sin un valor específico dejan entonces de recibir resolutores.

Nombre	En	Tipo	Notas
global	body	string	v4, v6, domain o all (all también elimina los resolutores IPv6 existentes).
iface	body	string	Como alternativa, la VLAN cuyo valor específico se eliminará.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"global":"domain"}' http://ROUTER-IP:8880/dns

{
  "ok": true,
  "code": 200,
  "message": "global resolvers cleared: domain",
  "cleared": ["domain"],
  "global_now": { "ipv4": "XXX.XXX.XXX.53, XXX.XXX.XXX.53", "ipv6": "XXXX:XXXX::53", "domain": null },
  "serving_no_resolver": []
}

Errores: 400 cuando no se indica ni global ni una interfaz, o cuando global tiene otro valor; 404 cuando no había nada de ese tipo definido.

Equivalentes en la API de acciones

Acción	Parámetros de consulta	Equivale a
action=networks	—	GET /networks
action=interfaces	—	GET /interfaces
action=iface-list	—	GET /iface (sin los contadores)
action=reload	—	POST /dhcp/reload
action=add-net	iface, label	POST /net
action=remove-net	iface	DELETE /net
action=net6-add	iface	POST /net6
action=net6-del	iface	DELETE /net6
action=net6-pool	iface, start, end	POST /net6/pool
action=net6-lease	valid, preferred	POST /net6/lease
action=net6-dns	servers, domain o clear_domain=1	Define solo los resolutores/el dominio de DHCPv6
action=pd-list	—	GET /pd
action=pd-add	iface, size	POST /pd
action=pd-resize	iface, size	POST /pd/resize
action=pd-del	iface	DELETE /pd
action=pd-assign	mac, prefix	POST /pd/assign
action=pd-unassign	mac	DELETE /pd/assign
action=pd-sync	dry=1	POST /pd/sync
action=dns-list	—	GET /dns
action=dns-set	v4, v6, domain, apply, o iface + v4/v6	POST /dns, POST /dns/{iface}
action=dns-del	iface, o global=v4|v6|domain|all	DELETE /dns/{iface}, DELETE /dns