API de redes

Estes endpoints decidem quais interfaces o roteador atende com DHCP (IPv4) e DHCPv6 + router advertisements (IPv6), quais endereços os pools entregam, como a delegação de prefixo IPv6 é dividida entre as VLANs e quais resolvedores DNS os assinantes recebem. URL base, autenticação e formato de erro estão descritos na visão geral da API.

Toda alteração é verificada antes de ter efeito: a configuração do DHCP é testada e o serviço reiniciado e, se qualquer uma dessas etapas falhar, o arquivo anterior é restaurado e a resposta diz … — rolled back. Uma resposta 5xx pode trazer broken_data_files, com os nomes dos arquivos de dados do roteador que não podem ser interpretados.

As interfaces são indicadas pelo nome (vlan110, svlan300.10, bond0…). Para VLANs, veja VLANs, IPs e rotas — adicionar uma VLAN com endereço passa a atendê-la automaticamente.

Redes e interfaces

GET /networks

Todas as redes IPv4 configuradas nas interfaces do roteador, com a rede IPv6 da mesma interface quando houver.

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 rede IPv4 e se o DHCP realmente a atende: dhcp_active é true somente quando a sub-rede está na configuração do DHCP e a interface está na lista de escuta do DHCP. O mesmo vale para DHCPv6 quando a interface tem uma rede 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 e GET /net6 dão a mesma resposta.

GET /iface

Todos os links do roteador (portas físicas, bonds, VLANs, S-VLANs, C-VLANs, USB, loopback) com seu estado, tag de VLAN, endereços e 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 é um de physical, vlan, svlan, cvlan, usb, loopback. status é UP somente quando o link está ativo e tem portadora (carrier).

DHCP (IPv4)

POST /dhcp/reload

Altera o roteador

Reinicia o servidor DHCP (depois de testar sua configuração).

Testa a configuração do DHCP e reinicia o serviço DHCP. Qualquer outro caminho /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" }

Em caso de falha: 500 com error (DHCP config test failed ou DHCP restart failed) e detail.

POST /net

Altera o roteador

Adiciona a sub-rede IPv4 da interface ao servidor DHCP e começa a atendê-la.

Atende a rede IPv4 já configurada em uma interface: seu bloco de sub-rede é adicionado à configuração do DHCP e a interface à lista de escuta. Se a sub-rede já estiver lá, apenas a lista de escuta é atualizada.

Nome	Em	Tipo	Observações
iface	body	string	Interface que tem o endereço IPv4, p. ex. vlan110.
label	body	string	Texto opcional gravado como comentário no bloco da sub-rede.

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

Erros: 404 quando a interface não tem endereço IPv4; 500 quando o teste da configuração ou o reinício falha (revertido).

DELETE /net

Altera o roteador

Deixa de atender a sub-rede IPv4 da interface e remove seu bloco da configuração do DHCP.

Nome	Em	Tipo	Observações
iface	body	string	Interface que deixa de ser atendida.

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

Erros: 409 enquanto ainda houver clientes registrados na interface (Cannot remove: N client(s) registered on vlan110. Delete them first.); 404 quando a interface não tem endereço IPv4; 500 quando o bloco da sub-rede não é encontrado ou o teste/reinício do DHCP falha.

DHCPv6 e router advertisements

POST /net6

Altera o roteador

Inicia DHCPv6 e router advertisements na rede IPv6 da interface.

Adiciona a rede IPv6 da interface ao DHCPv6, com um pool de endereços derivado da rede (para um /64: ::1000 até ::ffff), e atualiza os router advertisements. Se as outras sub-redes DHCPv6 já têm servidores de nomes e nenhum resolvedor IPv6 global está definido, a nova sub-rede os herda.

Nome	Em	Tipo	Observações
iface	body	string	Interface que tem um endereço 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"
}

Quando não é possível derivar um pool, a resposta traz warning em vez de pool; quando não há resolvedor a herdar, dns é null e uma note informa isso. Erros: 404 No IPv6 address on interface '…'; 500 quando o teste ou o reinício do DHCPv6 falha (revertido).

DELETE /net6

Altera o roteador

Para o DHCPv6 na interface e libera sua faixa de delegação de prefixo.

Remove a interface do DHCPv6. O bloco subnet6 é removido, a menos que outra interface atendida use a mesma rede; a faixa de delegação de prefixo da interface é liberada.

Nome	Em	Tipo	Observações
iface	body	string	Interface que deixa de ser atendida 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

Altera o roteador

Grava (ou substitui) a faixa de endereços DHCPv6 da sub-rede da interface e reinicia o DHCPv6.

Define a faixa de endereços entregue na sub-rede IPv6 de uma interface. Sem start/end, a faixa é derivada da rede. Os parâmetros são lidos do corpo e, depois, da query string.

Nome	Em	Tipo	Observações
iface	body or query	string	Interface cujo bloco subnet6 existe (veja POST /net6).
start	body or query	IPv6	Primeiro endereço opcional; deve estar dentro da rede.
end	body or query	IPv6	Último endereço opcional; deve estar dentro da rede.

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
}

Erros: 400 para um endereço inválido ou fora da rede, ou quando não é possível derivar um pool; 404 quando a interface não tem endereço IPv6 ou não tem bloco subnet6.

POST /net6/lease

Altera o roteador

Altera os tempos de vida de endereços e prefixos DHCPv6 em todas as sub-redes.

Define os tempos de vida válido e preferencial que o DHCPv6 entrega (endereços e prefixos delegados) e atualiza os router advertisements. GET /net6/lease aceita os mesmos parâmetros pela query string.

Nome	Em	Tipo	Observações
valid	body	integer	Tempo de vida válido em segundos, no mínimo 120.
preferred	body	integer	Opcional; padrão é metade de valid, não pode ultrapassá-lo.

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

Delegação de prefixo IPv6

Os prefixos delegados (por padrão /64) vêm de um único pool para todo o roteador, definido na configuração do roteador (pd_pool, pd_len). Cada VLAN recebe uma fatia desse pool (por padrão pd_slice prefixos); os primeiros pd_reserve prefixos ficam reservados para prefixos fixados a clientes individuais.

GET /pd

O pool, sua capacidade, a fatia de cada VLAN, os prefixos fixados e as rotas delegadas que o kernel mantém agora.

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

Altera o roteador

Reserva uma fatia do pool de delegação para a VLAN e começa a delegar prefixos nela.

Ativa a delegação de prefixo em uma interface que já tem DHCPv6 (POST /net6). Chamá-lo novamente com um novo size realoca a fatia.

Nome	Em	Tipo	Observações
iface	body	string	Interface com bloco subnet6.
size	body	integer	Número opcional de prefixos, uma potência de dois (256, 512, 1024…); o padrão é a fatia 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\""
}

Quando a fatia mudou de lugar, são adicionados replaced e warning (os CPEs mantêm o prefixo antigo até a concessão expirar; execute um sync). Erros: 400 quando size não é uma potência de dois; 404 sem bloco subnet6; 507 quando o pool está esgotado (com requested e largest_free_run).

POST /pd/resize

Altera o roteador

Move a VLAN para uma fatia de outro tamanho.

Nome	Em	Tipo	Observações
iface	body	string	Interface que já delega.
size	body	integer	Novo número de prefixos (potência de dois).

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

A resposta é a mesma de POST /pd. Erros: 400 sem size; 404 quando a interface não tem delegação; 409 quando ela já tem esse número de prefixos.

DELETE /pd

Altera o roteador

Para a delegação de prefixo na VLAN e libera sua fatia.

Nome	Em	Tipo	Observações
iface	body	string	Interface na qual a delegação é interrompida.

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

Altera o roteador

Fixa um prefixo delegado a um cliente e recarrega o DHCPv6.

Dá a um cliente (pelo MAC) sempre o mesmo prefixo delegado. Sem prefix, é usado o primeiro prefixo livre da faixa reservada. GET /pd/assign aceita os mesmos parâmetros pela query string.

Nome	Em	Tipo	Observações
mac	body	string	O MAC de um cliente registrado.
prefix	body	IPv6 prefix	Opcional; deve ter o comprimento delegado e estar dentro do pool. O comprimento pode ser omitido.

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

Erros: 404 cliente desconhecido; 400 prefixo inválido ou fora do pool; 409 prefixo fixado a outro cliente; 507 nenhum prefixo livre na faixa reservada.

DELETE /pd/assign

Altera o roteador

Remove o prefixo fixado de um cliente e recarrega o DHCPv6.

Nome	Em	Tipo	Observações
mac	body	string	Cliente cujo prefixo fixado é removido.

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

Erros: 404 quando o cliente não tem prefixo fixado.

POST /pd/sync

Altera o roteador

Reconcilia as rotas de prefixos delegados do kernel com as concessões DHCPv6 (a menos que dry=1).

Executa agora o reconciliador de rotas delegadas e retorna sua saída. Qualquer método em /pd/sync o executa.

Nome	Em	Tipo	Observações
dry	query	1	Apenas informa o que mudaria.

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

Resolvedores DNS

Os resolvedores que os assinantes recebem por DHCP e DHCPv6: um padrão global e substituições opcionais por VLAN.

GET /dns

O que cada VLAN atendida realmente recebe, de onde vem (per-vlan, global ou none) e quais VLANs atendidas não recebem nenhum resolvedor.

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

Altera o roteador

Define os resolvedores e/ou o domínio globais para DHCP e DHCPv6 e reinicia os serviços DHCP.

Nome	Em	Tipo	Observações
v4	body	string or list	Resolvedores IPv4, separados por vírgula ou em uma lista JSON.
v6	body	string or list	Resolvedores IPv6.
domain	body	string	Domínio de busca.
apply	body	string	Opcional: all remove as substituições por VLAN para que todas as VLANs sigam o padrão; missing não altera mais nada.
iface	body	string	Se informado, define em vez disso uma substituição por VLAN (o mesmo que POST /dns/{iface}).

Pelo menos um de v4, v6, domain é obrigatório.

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

Com apply, applied_to lista as VLANs cujas substituições foram removidas. Sem ele, um warning e uma lista shadowing indicam as VLANs cujos próprios resolvedores IPv6 encobrem o novo padrão.

POST /dns/{iface}

Altera o roteador

Grava uma substituição de resolvedores por VLAN e reinicia o(s) serviço(s) DHCP.

Nome	Em	Tipo	Observações
iface	path	string	Interface VLAN atendida, p. ex. vlan130.
v4	body	string or list	Resolvedores IPv4 desta VLAN.
v6	body	string or list	Resolvedores IPv6 desta 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"
}

Erros: 400 sem v4/v6 ou com um endereço inválido; 404 quando a interface, sua rede ou seu bloco de sub-rede não existe.

DELETE /dns/{iface}

Altera o roteador

Remove a substituição da VLAN, para que ela volte a herdar os resolvedores globais.

Nome	Em	Tipo	Observações
iface	path	string	Interface 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" }
}

Erros: 404 quando a VLAN não tem substituição.

DELETE /dns

Altera o roteador

Apaga os resolvedores globais (ou o domínio); as VLANs sem substituição passam a não receber nenhum.

Nome	Em	Tipo	Observações
global	body	string	v4, v6, domain ou all (all também remove os resolvedores IPv6 existentes).
iface	body	string	Alternativamente, a VLAN cuja substituição deve ser removida.

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

Erros: 400 quando não é informado nem global nem uma interface, ou global tem outro valor; 404 quando nada desse tipo estava definido.

Equivalentes na API de ações

Ação	Parâmetros de consulta	Equivale a
action=networks	—	GET /networks
action=interfaces	—	GET /interfaces
action=iface-list	—	GET /iface (sem os 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 ou clear_domain=1	Define apenas os resolvedores/domínio 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, ou iface + v4/v6	POST /dns, POST /dns/{iface}
action=dns-del	iface, ou global=v4|v6|domain|all	DELETE /dns/{iface}, DELETE /dns