API compatível com MikroTik

Muitos sistemas de cobrança de provedores WISP gerenciam assinantes conversando com roteadores MikroTik pela RouterOS API (um protocolo binário na porta TCP 8728). O DTVSOL Super Router fala o suficiente desse protocolo para que esse sistema de cobrança acredite estar falando com um MikroTik: o dtvsold roda um listener (o serviço dtvsol-mkapi) que transforma cada comando suportado em uma chamada à API HTTP do próprio roteador em 127.0.0.1:8880.

Escopo: somente DHCP/IPoE — criar, alterar, suspender e excluir um cliente, e definir a sua velocidade. PPPoE é recusado.

Conexão e login

• Porta: TCP 8728 por padrão (a configuração port).
• Quem pode se conectar: 127.0.0.1 e as redes da lista de permitidos da API (o documento allowed_networks). Quando a lista de permitidos não está vazia, qualquer outra origem é descartada pelo firewall do roteador.
• Login: /login com =name= e =password= (a forma simples), ou a forma antiga por desafio (/login sem atributos retorna =ret=<challenge>, depois /login com =name= e =response=). Qualquer outro comando antes de um login bem-sucedido responde !trap not logged in.
• Tags: um .tag= em um comando é repetido em cada uma das suas respostas.
• Erros: !trap com =message=…, sempre seguido de !done.
• /quit encerra a conexão.

Configurações

O listener lê o documento de configuração mkapi. Altere-o com a CLI, que reinicia o serviço:

dtvsol mkapi                     # show the settings and the service state
dtvsol mkapi set user billing password YOUR_PASSWORD port 8728
dtvsol mkapi set identity router-1 model CCR2004-1G-12S+2XS version 7.15.3

Chave	Padrão	Observações
port	8728	Porta TCP do listener.
user	admin	Nome de login que o sistema de cobrança usa.
password	—	Senha de login. O roteador vem com um padrão de demonstração: defina a sua própria senha antes de expor a porta.
identity	MikroTik	Resposta a /system/identity/print. Também pode ser alterada pelo sistema de cobrança com /system/identity/set.
model	um nome de modelo MikroTik	Respondido como board-name e model.
version	uma versão do RouterOS	Respondida como version e como versões de firmware.
serial	um valor fictício	Respondido como serial-number.

A identidade, o modelo e a versão parecem os de um MikroTik de propósito, para que sistemas de cobrança que verificam o nome ou o modelo do equipamento aceitem o roteador.

IDs (mk-ids)

Um sistema de cobrança guarda o .id que o RouterOS retorna para cada lease ou queue. O roteador dá a cada MAC de cliente um id estável no formato *1, *2, … e guarda o mapeamento no documento de configuração mk-ids, para que um set ou remove posterior por .id chegue ao cliente certo. A lease e a queue de um cliente têm o mesmo id.

Velocidades e planos

Uma taxa MikroTik como rate-limit ou max-limit é escrita UPLOAD/DOWNLOAD (por exemplo 10M/50M; um só valor significa o mesmo nos dois sentidos). As unidades k, M e G são entendidas; um número sem unidade é em bits por segundo; qualquer valor abaixo de 1 Mbit/s vira 1. O roteador transforma a taxa em um plano de velocidade chamado mk_<down>m_<up>m (criado com POST /plans se necessário) e o atribui ao cliente com POST /plan.

Comandos

/ip/dhcp-server/lease/add

Cria um cliente: chama POST /clients com mac = mac-address, ip = address, hostname = mk-<mac without separators> e comment. Um cliente que já existe (HTTP 409) é aceito. Com rate-limit, também define a sua velocidade. Responde !done com =ret=<id>.

Atributo	Observações
address	Obrigatório. O endereço IPv4 do cliente.
mac-address	Obrigatório.
comment	Opcional.
rate-limit	Opcional. UP/DOWN.

/ip/dhcp-server/lease/set

Encontra o cliente por mac-address, depois por .id, depois por address. disabled=yes o suspende (POST /suspend), disabled=no o reativa (POST /resume). Com rate-limit, define a sua velocidade. Cliente desconhecido: !trap lease not found.

/ip/dhcp-server/lease/remove

Encontra o cliente como no set e o exclui (DELETE /clients/{mac}), esquecendo o seu id.

/ip/dhcp-server/lease/print

Lista todos os clientes (GET /clients) como leases: .id, address, mac-address, host-name, comment, disabled (yes quando suspenso), dynamic=false, status=bound.

/queue/simple/add

Encontra o cliente cujo IP é o endereço target (10.110.0.2/32 ou 10.110.0.2) e define a sua velocidade a partir de max-limit. Responde !done com =ret=<id>. Se não existe esse cliente: !trap no client for target ….

/queue/simple/set

Encontra o cliente por mac-address, .id ou address, e senão por target. max-limit define a sua velocidade; disabled=yes remove o seu limite de velocidade (plano none). Desconhecido: !trap queue not found.

/queue/simple/remove

Encontra o cliente como no set e remove o seu limite de velocidade (plano none). O cliente em si não é excluído.

/queue/simple/print

Lista todos os clientes que têm um plano: .id, name (o seu hostname), target (<ip>/32).

/system/identity/print

Responde name = a configuração identity.

/system/identity/set

Grava name como a nova configuração identity.

/system/resource/print

Responde a version e o model (board-name) configurados, o uptime e a memória reais do roteador, e valores fixos para o resto (platform=MikroTik, architecture-name=x86_64, números de CPU e disco).

/system/routerboard/print

Responde routerboard=true, o model e o serial configurados, firmware-type=dtvsol, e a version configurada como firmware atual e de atualização.

/ip/dhcp-server/print

Responde um único servidor DHCP: .id=*1, name=dhcp1, disabled=false.

Outros comandos

• Qualquer outro comando terminado em /print responde uma lista vazia (!done), para que consultas somente de leitura de um sistema de cobrança não falhem.
• Qualquer comando sob /ppp/, ou que contenha pppoe, responde !trap PPPoE is not supported on this device (DHCP/IPoE only).
• Qualquer outra coisa responde !trap command not supported: <command>.

Exemplo de sessão

>>> /login  =name=billing  =password=YOUR_PASSWORD
<<< !done
>>> /ip/dhcp-server/lease/add  =address=10.110.0.2  =mac-address=AA:BB:CC:DD:EE:FF  =rate-limit=10M/50M
<<< !done  =ret=*1
>>> /ip/dhcp-server/lease/set  =.id=*1  =disabled=yes
<<< !done
>>> /ppp/secret/add  =name=user1
<<< !trap  =message=PPPoE is not supported on this device (DHCP/IPoE only)
<<< !done