API de roteamento (BGP e OSPF)

O roteador executa o BGP e o OSPF por meio do BIRD 2. Estes endpoints leem e alteram as suas configurações de roteamento; a partir delas o roteador escreve a configuração do BIRD, verifica-a com o BIRD e a carrega. Como funciona: BGP e OSPF. Os equivalentes na CLI são dtvsol bgp … e dtvsol ospf …. Autenticação e erros: veja a visão geral da API.

Uma alteração que poderia deixar o roteador isolado (toda operação, exceto os blackholes, confirm e undo) é carregada com um temporizador de 120 segundos enquanto o BGP ou o OSPF está ligado: ela responde "pending": true e um deadline, e é desfeita sozinha, a menos que POST /bgp/confirm venha antes. Enquanto uma alteração aguarda, as outras alterações respondem 409.

Leitura

GET /bgp

As configurações (sem as senhas), cada peer com a sua sessão como o BIRD a tem, o OSPF com os seus vizinhos, e o que está errado.

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	O estado BGP no BIRD (Established quando a sessão está ativa; Active, Connect, Idle… caso contrário), ou null enquanto o BGP está desligado.
peers[].received, sent	Rotas recebidas do peer e enviadas a ele, somadas sobre os seus canais.
peers[].last_error	O último erro da sessão no BIRD (por exemplo Socket: Connection refused).
ospf.interfaces[].neighbors_full	Vizinhos OSPF no estado Full na interface.
installed	O BIRD está instalado.
bird_error	Por que não foi possível consultar o BIRD, ou null.
problems	O que está errado nas configurações (uma alteração que deixa algum problema é recusada).
peers[].bfd, bfd_state	BFD na sessão, e o estado dele (Up, Down, Init…) ou null.
rpki	{enabled, status: {data, age_s, vrps, stale}}: RPKI ligado ou não, e os dados validados (idade em segundos, quantas origens de rota).
pending	A alteração que aguarda a confirmação: {deadline, what, by} (deadline em segundos Unix), ou null.

GET /bgp?config=1

A configuração que o BIRD recebe, como texto, com as senhas substituídas por ********: {"ok": true, "config": "…", "file": "/etc/bird/bird.conf"}.

Alterações

POST /bgp/{op}

Toda alteração é POST /bgp/<op> com um corpo JSON. A resposta é {"ok": true, "message": "…", "pending": true|false, "deadline": …}, ou {"ok": false, "error": "…"} com 400 (entrada errada ou configurações com problemas — nada foi alterado), 404 (operação desconhecida), 409 (uma alteração está aguardando, ou o BIRD não está instalado) ou 500.

POST /bgp/set

As configurações BGP deste roteador. Qualquer um de:

Nome	Em	Tipo	Observações
asn	body	integer	O seu número de AS.
router_id	body	string	Um endereço IPv4 deste roteador (BGP e OSPF).
enabled	body	boolean	BGP ligado ou desligado.
rpki	body	boolean	RPKI ligado ou desligado: descarta das operadoras com tabela completa as rotas com origem comprovadamente falsa (o timer do validador acompanha).

POST /bgp/peer-add

Adiciona um peer, ou altera o peer com esse nome. Numa alteração, os campos não enviados ficam como estão (a senha também).

Nome	Em	Tipo	Observações
name	body	string	1–32 letras, dígitos, -, _. Obrigatório.
ip	body	string	O endereço IPv4 ou IPv6 do peer. Obrigatório.
asn	body	integer	O AS do peer. Obrigatório.
type	body	string	upstream (padrão) ou ibgp (outro Super Router, o seu próprio AS).
routes	body	string	Operadoras: default (só a rota padrão; o padrão) ou full (a tabela completa).
role	body	string	Operadoras: primary (padrão) ou backup.
password	body	string	Senha TCP MD5; armazenada criptografada, nunca exibida.
blackhole_community	body	string	A community de blackhole da operadora, as:n (por exemplo 65535:666). Vazio a remove.
max_prefix	body	integer	Limite de prefixos (padrão: 16 para uma rota padrão, 1.500.000 IPv4 / 400.000 IPv6 para uma tabela completa).
multihop	body	integer	Para um peer que não está diretamente conectado: o TTL.
bfd	body	boolean	BFD na sessão (o peer também usa BFD): um peer caído é percebido em menos de um segundo.
enabled	body	boolean	Padrão true.
description	body	string	Até 80 caracteres.

POST /bgp/peer-del

{"name": "…"} — remove o peer.

POST /bgp/peer-enable

{"name": "…"} — inicia de novo a sessão do peer.

POST /bgp/peer-disable

{"name": "…"} — para a sessão do peer, mantendo o peer.

POST /bgp/announce-add

{"prefix": "XXX.XXX.XXX.0/22"} — um bloco IPv4 público de /8 a /24, ou IPv6 de /16 a /48.

POST /bgp/announce-del

{"prefix": "…"} — para de anunciá-lo.

POST /bgp/blackhole-add

{"ip": "XXX.XXX.XXX.66"} — um endereço público, enviado como /32 (/128) com a community de blackhole de cada operadora, e descartado por este roteador. Carregado na hora, sem o temporizador.

POST /bgp/blackhole-del

{"ip": "…"} — remove o blackhole.

POST /bgp/ospf-set

Qualquer um de:

Nome	Em	Tipo	Observações
enabled	body	boolean	OSPF ligado ou desligado.
area	body	string	Um número ou quatro números separados por pontos; 0.0.0.0 por padrão.
originate_default	body	boolean	Informa aos roteadores OSPF a nossa rota padrão (do BGP).
accept_default	body	boolean	Aceita uma rota padrão do OSPF.

POST /bgp/ospf-iface-add

{"name": "vlan20", "cost": 10, "passive": false} — adiciona uma interface deste roteador ao OSPF, ou a altera. passive: a rede dela é anunciada, nenhum vizinho é procurado nela.

POST /bgp/ospf-iface-del

{"name": "…"} — remove a interface do OSPF.

POST /bgp/confirm

Mantém a alteração que está aguardando.

POST /bgp/undo

Desfaz na hora a alteração que está aguardando.

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"