API de enrutamiento (BGP y OSPF)

El router ejecuta BGP y OSPF por medio de BIRD 2. Estos endpoints leen y cambian sus ajustes de enrutamiento; el router escribe a partir de ellos la configuración de BIRD, la verifica con BIRD y la carga. Cómo funciona: BGP y OSPF. Los equivalentes en la CLI son dtvsol bgp … y dtvsol ospf …. Autenticación y errores: consulte la descripción general de la API.

Un cambio que podría dejar al router sin conexión (todas las operaciones excepto los blackholes, confirm y undo) se carga con un temporizador de 120 segundos mientras BGP u OSPF está encendido: responde "pending": true y un deadline, y se deshace por sí solo a menos que POST /bgp/confirm llegue antes. Mientras un cambio espera, los demás cambios responden 409.

Lectura

GET /bgp

Los ajustes (sin las contraseñas), cada par con su sesión tal como la tiene BIRD, OSPF con sus vecinos, y lo que está mal.

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

{
  "ok": true,
  "enabled": true,
  "asn": 65010,
  "router_id": "XXX.XXX.XXX.2",
  "announce": ["XXX.XXX.XXX.0/22", "XXXX:XXXX::/32"],
  "blackhole": [],
  "peers": [
    {
      "name": "isp-a", "ip": "XXX.XXX.XXX.1", "asn": 64500, "type": "upstream",
      "routes": "default", "role": "primary", "enabled": true, "description": "",
      "password_set": false, "blackhole_community": "64500:666",
      "state": "Established", "up": true, "since": "10:00:05.123", "info": "Established",
      "last_error": null, "received": 1, "sent": 2, "filtered": 0, "best": 1
    }
  ],
  "ospf": {
    "enabled": true, "area": "0.0.0.0", "originate_default": true, "accept_default": false,
    "interfaces": [{"name": "vlan20", "cost": 10, "passive": false, "neighbors_full": 1}],
    "neighbors": [{"proto": "ospf4", "router_id": "10.0.0.3", "state": "Full/DR", "iface": "vlan20", "ip": "10.0.0.3"}],
    "protocols": [{"name": "ospf4", "state": "up", "info": "Running", "since": "10:00:00.000"}]
  },
  "installed": true,
  "bird_error": null,
  "problems": [],
  "settings": { },
  "kernel_metric": 32,
  "pending": null
}

Campo	Significado
peers[].state	El estado BGP de BIRD (Established cuando la sesión está activa; Active, Connect, Idle… en otro caso), o null mientras BGP está apagado.
peers[].received, sent	Rutas recibidas del par y enviadas a él, sumadas sobre sus canales.
peers[].last_error	El último error de la sesión según BIRD (p. ej. Socket: Connection refused).
ospf.interfaces[].neighbors_full	Vecinos OSPF en estado Full en la interfaz.
installed	BIRD está instalado.
bird_error	Por qué no se pudo consultar a BIRD, o null.
problems	Lo que está mal en los ajustes (un cambio que deja alguno se rechaza).
peers[].bfd, bfd_state	BFD en la sesión, y su estado (Up, Down, Init…) o null.
rpki	{enabled, status: {data, age_s, vrps, stale}}: RPKI activo o no, y los datos validados (su antigüedad en segundos, cuántos orígenes de ruta).
pending	El cambio que espera su confirmación: {deadline, what, by} (deadline en segundos Unix), o null.

GET /bgp?config=1

La configuración que recibe BIRD, como texto, con las contraseñas reemplazadas por ********: {"ok": true, "config": "…", "file": "/etc/bird/bird.conf"}.

Cambios

POST /bgp/{op}

Cada cambio es POST /bgp/<op> con un cuerpo JSON. La respuesta es {"ok": true, "message": "…", "pending": true|false, "deadline": …}, o {"ok": false, "error": "…"} con 400 (entrada incorrecta o ajustes con problemas; no se cambió nada), 404 (operación desconocida), 409 (hay un cambio esperando, o BIRD no está instalado) o 500.

POST /bgp/set

Los ajustes BGP de este router. Cualquiera de:

Nombre	En	Tipo	Notas
asn	body	integer	Su número de AS.
router_id	body	string	Una dirección IPv4 de este router (BGP y OSPF).
enabled	body	boolean	BGP encendido o apagado.
rpki	body	boolean	RPKI activo o no: descarta de los proveedores con tabla completa las rutas con un origen probado como falso (el temporizador del validador lo sigue).

POST /bgp/peer-add

Agrega un par, o cambia el par con ese nombre. En un cambio, los campos que no se envían quedan como están (también la contraseña).

Nombre	En	Tipo	Notas
name	body	string	De 1 a 32 letras, dígitos, -, _. Obligatorio.
ip	body	string	La dirección IPv4 o IPv6 del par. Obligatorio.
asn	body	integer	El AS del par. Obligatorio.
type	body	string	upstream (predeterminado) o ibgp (otro Super Router, su propio AS).
routes	body	string	Proveedores: default (solo la ruta por defecto; el predeterminado) o full (la tabla completa).
role	body	string	Proveedores: primary (predeterminado) o backup.
password	body	string	Contraseña TCP MD5; se guarda cifrada, nunca se muestra.
blackhole_community	body	string	La comunidad de blackhole del proveedor, as:n (p. ej. 65535:666). Vacía la elimina.
max_prefix	body	integer	Límite de prefijos (predeterminado: 16 para una ruta por defecto, 1 500 000 IPv4 / 400 000 IPv6 para una tabla completa).
multihop	body	integer	Para un par que no está conectado directamente: el TTL.
bfd	body	boolean	BFD en la sesión (el par también usa BFD): un par caído se detecta en menos de un segundo.
enabled	body	boolean	Predeterminado true.
description	body	string	Hasta 80 caracteres.

POST /bgp/peer-del

{"name": "…"}: elimina el par.

POST /bgp/peer-enable

{"name": "…"}: vuelve a iniciar la sesión del par.

POST /bgp/peer-disable

{"name": "…"}: detiene la sesión del par, conservando el par.

POST /bgp/announce-add

{"prefix": "XXX.XXX.XXX.0/22"}: un bloque IPv4 público de /8 a /24, o IPv6 de /16 a /48.

POST /bgp/announce-del

{"prefix": "…"}: deja de anunciarlo.

POST /bgp/blackhole-add

{"ip": "XXX.XXX.XXX.66"}: una dirección pública, enviada como /32 (/128) con la comunidad de blackhole de cada proveedor, y descartada por este router. Se carga de inmediato, sin el temporizador.

POST /bgp/blackhole-del

{"ip": "…"}: quita el blackhole.

POST /bgp/ospf-set

Cualquiera de:

Nombre	En	Tipo	Notas
enabled	body	boolean	OSPF encendido o apagado.
area	body	string	Un número o un cuádruple con puntos; 0.0.0.0 por defecto.
originate_default	body	boolean	Comunica a los routers OSPF nuestra ruta por defecto (de BGP).
accept_default	body	boolean	Toma una ruta por defecto de OSPF.

POST /bgp/ospf-iface-add

{"name": "vlan20", "cost": 10, "passive": false}: agrega una interfaz de este router a OSPF, o la cambia. passive: su red se anuncia, no se busca ningún vecino en ella.

POST /bgp/ospf-iface-del

{"name": "…"}: quita la interfaz de OSPF.

POST /bgp/confirm

Conserva el cambio que está esperando.

POST /bgp/undo

Deshace de inmediato el cambio que está esperando.

curl -s -X POST "http://ROUTER-IP:8880/bgp/peer-add" -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "isp-a", "ip": "XXX.XXX.XXX.1", "asn": 64500, "routes": "default", "role": "primary"}'
curl -s -X POST "http://ROUTER-IP:8880/bgp/confirm" -H "X-API-Key: YOUR_API_KEY"