MikroTik-compatible API

Many WISP billing systems manage subscribers by talking to MikroTik routers over the RouterOS API (a binary protocol on TCP port 8728). The DTVSOL Super Router speaks enough of that protocol for such a billing to believe it is talking to a MikroTik: dtvsold runs a listener (the dtvsol-mkapi service) that turns each supported command into a call to the router’s own HTTP API on 127.0.0.1:8880.

Scope: DHCP/IPoE only — create, change, suspend and delete a client, and set its speed. PPPoE is refused.

Connection and login

• Port: TCP 8728 by default (the port setting).
• Who may connect: 127.0.0.1 and the networks on the API allow-list (the allowed_networks document). When the allow-list is not empty, every other source is dropped by the router’s firewall.
• Login: /login with =name= and =password= (the plain form), or the older challenge form (/login with no attributes returns =ret=<challenge>, then /login with =name= and =response=). Every other command before a successful login answers !trap not logged in.
• Tags: a .tag= on a command is repeated on each of its replies.
• Errors: !trap with =message=…, always followed by !done.
• /quit ends the connection.

Settings

The listener reads the mkapi configuration document. Change it with the CLI, which restarts the service:

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

Key	Default	Notes
port	8728	TCP port of the listener.
user	admin	Login name the billing uses.
password	—	Login password. A demo default ships with the router: set your own password before exposing the port.
identity	MikroTik	Answered to /system/identity/print. Can also be changed by the billing with /system/identity/set.
model	a MikroTik model name	Answered as board-name and model.
version	a RouterOS version	Answered as version and firmware versions.
serial	a placeholder	Answered as serial-number.

The identity, model and version look like a MikroTik’s on purpose, so billings that check the device name or model accept the router.

IDs (mk-ids)

A billing keeps the .id RouterOS returns for each lease or queue. The router gives each client MAC a stable id of the form *1, *2, … and keeps the mapping in the mk-ids configuration document, so a later set or remove by .id reaches the right client. Both a client’s lease and its queue have the same id.

Speeds and plans

A MikroTik rate such as rate-limit or max-limit is written UPLOAD/DOWNLOAD (for example 10M/50M; one value means the same both ways). Units k, M and G are understood; a bare number is bits per second; anything below 1 Mbit/s becomes 1. The router turns the rate into a speed plan named mk_<down>m_<up>m (created with POST /plans if needed) and assigns it to the client with POST /plan.

Commands

/ip/dhcp-server/lease/add

Creates a client: calls POST /clients with mac = mac-address, ip = address, hostname = mk-<mac without separators> and comment. A client that already exists (HTTP 409) is accepted. With rate-limit, also sets its speed. Replies !done with =ret=<id>.

Attribute	Notes
address	Required. The client’s IPv4 address.
mac-address	Required.
comment	Optional.
rate-limit	Optional. UP/DOWN.

/ip/dhcp-server/lease/set

Finds the client by mac-address, then .id, then address. disabled=yes suspends it (POST /suspend), disabled=no resumes it (POST /resume). With rate-limit, sets its speed. Unknown client: !trap lease not found.

/ip/dhcp-server/lease/remove

Finds the client as for set and deletes it (DELETE /clients/{mac}), forgetting its id.

/ip/dhcp-server/lease/print

Lists every client (GET /clients) as leases: .id, address, mac-address, host-name, comment, disabled (yes when suspended), dynamic=false, status=bound.

/queue/simple/add

Finds the client whose IP is the target address (10.110.0.2/32 or 10.110.0.2) and sets its speed from max-limit. Replies !done with =ret=<id>. No such client: !trap no client for target ….

/queue/simple/set

Finds the client by mac-address, .id or address, else by target. max-limit sets its speed; disabled=yes removes its speed limit (plan none). Unknown: !trap queue not found.

/queue/simple/remove

Finds the client as for set and removes its speed limit (plan none). The client itself is not deleted.

/queue/simple/print

Lists every client that has a plan: .id, name (its hostname), target (<ip>/32).

/system/identity/print

Answers name = the identity setting.

/system/identity/set

Stores name as the new identity setting.

/system/resource/print

Answers the configured version and model (board-name), the router’s real uptime and memory, and fixed values for the rest (platform=MikroTik, architecture-name=x86_64, CPU and disk figures).

/system/routerboard/print

Answers routerboard=true, the configured model and serial, firmware-type=dtvsol, and the configured version as the current and upgrade firmware.

/ip/dhcp-server/print

Answers one DHCP server: .id=*1, name=dhcp1, disabled=false.

Other commands

• Any other command ending in /print answers an empty list (!done), so read-only probes from a billing do not fail.
• Any command under /ppp/, or containing pppoe, answers !trap PPPoE is not supported on this device (DHCP/IPoE only).
• Anything else answers !trap command not supported: <command>.

Example session

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