API compatible con MikroTik

Muchos sistemas de facturación para WISP gestionan a los suscriptores comunicándose con routers MikroTik a través de la API de RouterOS (un protocolo binario en el puerto TCP 8728). El DTVSOL Super Router implementa lo suficiente de ese protocolo para que dicho sistema de facturación crea que se comunica con un MikroTik: dtvsold ejecuta un servicio de escucha (el servicio dtvsol-mkapi) que convierte cada comando compatible en una llamada a la propia API HTTP del router en 127.0.0.1:8880.

Alcance: solo DHCP/IPoE — crear, modificar, suspender y eliminar un cliente, y establecer su velocidad. PPPoE se rechaza.

Conexión e inicio de sesión

• Puerto: TCP 8728 de forma predeterminada (el ajuste port).
• Quién puede conectarse: 127.0.0.1 y las redes de la lista de permitidos de la API (el documento allowed_networks). Cuando la lista de permitidos no está vacía, el firewall del router descarta cualquier otro origen.
• Inicio de sesión: /login con =name= y =password= (la forma simple), o la forma anterior con desafío (/login sin atributos devuelve =ret=<challenge>, y luego /login con =name= y =response=). Cualquier otro comando enviado antes de un inicio de sesión exitoso responde !trap not logged in (no ha iniciado sesión).
• Etiquetas: un .tag= en un comando se repite en cada una de sus respuestas.
• Errores: !trap con =message=…, siempre seguido de !done.
• /quit cierra la conexión.

Ajustes

El servicio de escucha lee el documento de configuración mkapi. Modifíquelo con la CLI, que reinicia el servicio:

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

Clave	Predeterminado	Notas
port	8728	Puerto TCP del servicio de escucha.
user	admin	Nombre de usuario que usa el sistema de facturación.
password	—	Contraseña de inicio de sesión. El router se entrega con una contraseña predeterminada de demostración: establezca su propia contraseña antes de exponer el puerto.
identity	MikroTik	Se responde a /system/identity/print. El sistema de facturación también puede cambiarla con /system/identity/set.
model	un nombre de modelo MikroTik	Se responde como board-name y model.
version	una versión de RouterOS	Se responde como version y como versiones de firmware.
serial	un valor de relleno	Se responde como serial-number.

La identidad, el modelo y la versión se parecen a los de un MikroTik a propósito, para que los sistemas de facturación que verifican el nombre o el modelo del dispositivo acepten el router.

IDs (mk-ids)

Un sistema de facturación guarda el .id que RouterOS devuelve para cada lease o cola. El router asigna a cada MAC de cliente un id estable con la forma *1, *2, … y guarda esa correspondencia en el documento de configuración mk-ids, de modo que un set o remove posterior por .id llegue al cliente correcto. El lease y la cola de un cliente tienen el mismo id.

Velocidades y planes

Una velocidad de MikroTik como rate-limit o max-limit se escribe UPLOAD/DOWNLOAD (por ejemplo 10M/50M; un solo valor significa la misma velocidad en ambos sentidos). Se admiten las unidades k, M y G; un número sin unidad son bits por segundo; cualquier valor inferior a 1 Mbit/s se convierte en 1. El router convierte la velocidad en un plan de velocidad llamado mk_<down>m_<up>m (creado con POST /plans si hace falta) y lo asigna al cliente con POST /plan.

Comandos

/ip/dhcp-server/lease/add

Crea un cliente: llama a POST /clients con mac = mac-address, ip = address, hostname = mk-<mac without separators> y comment. Un cliente que ya existe (HTTP 409) se acepta. Con rate-limit, también establece su velocidad. Responde !done con =ret=<id>.

Atributo	Notas
address	Obligatorio. La dirección IPv4 del cliente.
mac-address	Obligatorio.
comment	Opcional.
rate-limit	Opcional. UP/DOWN.

/ip/dhcp-server/lease/set

Busca el cliente por mac-address, luego por .id y luego por address. disabled=yes lo suspende (POST /suspend), disabled=no lo reactiva (POST /resume). Con rate-limit, establece su velocidad. Cliente desconocido: !trap lease not found (lease no encontrado).

/ip/dhcp-server/lease/remove

Busca el cliente igual que set y lo elimina (DELETE /clients/{mac}), olvidando su id.

/ip/dhcp-server/lease/print

Lista todos los clientes (GET /clients) como leases: .id, address, mac-address, host-name, comment, disabled (yes cuando está suspendido), dynamic=false, status=bound.

/queue/simple/add

Busca el cliente cuya IP es la dirección target (10.110.0.2/32 o 10.110.0.2) y establece su velocidad a partir de max-limit. Responde !done con =ret=<id>. Si no existe ese cliente: !trap no client for target … (no hay cliente para el target).

/queue/simple/set

Busca el cliente por mac-address, .id o address, y si no, por target. max-limit establece su velocidad; disabled=yes quita su límite de velocidad (plan none). Desconocido: !trap queue not found (cola no encontrada).

/queue/simple/remove

Busca el cliente igual que set y quita su límite de velocidad (plan none). El cliente en sí no se elimina.

/queue/simple/print

Lista todos los clientes que tienen un plan: .id, name (su hostname), target (<ip>/32).

/system/identity/print

Responde name = el ajuste identity.

/system/identity/set

Guarda name como el nuevo ajuste identity.

/system/resource/print

Responde la version y el model (board-name) configurados, el tiempo de actividad y la memoria reales del router, y valores fijos para el resto (platform=MikroTik, architecture-name=x86_64, cifras de CPU y disco).

/system/routerboard/print

Responde routerboard=true, el model y el serial configurados, firmware-type=dtvsol, y la version configurada como firmware actual y de actualización.

/ip/dhcp-server/print

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

Otros comandos

• Cualquier otro comando que termine en /print responde una lista vacía (!done), para que las consultas de solo lectura de un sistema de facturación no fallen.
• Cualquier comando bajo /ppp/, o que contenga pppoe, responde !trap PPPoE is not supported on this device (DHCP/IPoE only) (PPPoE no es compatible con este dispositivo; solo DHCP/IPoE).
• Cualquier otro comando responde !trap command not supported: <command> (comando no compatible).

Sesión de ejemplo

>>> /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