MikroTik RouterOS

The MikroTik adapter manages MikroTik devices running RouterOS v7 over the RouterOS REST API. It covers 13 feature domains, all using the same stage-and-apply contract as the other gateway adapters. MikroTik can serve as a firewall brain, a managed switch fabric, or a wireless controller (CAPsMAN), making it one of the most versatile adapters in the platform.

Fact	Detail
Maturity	Production
Gold-standard contract	DG ✓ CB ✓ RR ✓ TS ✓ SSRF ✓ RG ✓
Feature domains	13
RouterOS version	v7.1+ (REST API required)

What it manages

Domain	Backend coverage	UI tabs
System	System info, identity, clock, reboot, scheduled tasks	Yes
Interfaces	Interface list, bridge, VLAN, bond, enable/disable	Yes
IP	Addresses, ARP, address pools	Yes
DHCP	Server and client, leases, static mappings	Yes
Firewall	Filter rules, NAT, mangle, address lists	Yes (round 1)
DNS	Static entries, resolver config	Yes
VPN	IPsec, WireGuard, L2TP/PPTP server	Yes
Hotspot	Hotspot server, profiles, users	Yes
Queues	Simple and tree queues	Yes
CAPsMAN	AP provisioning, configurations, data paths	No UI yet
PPP/PPPoE	PPP users, PPPoE server	No UI yet
BGP/OSPF	BGP peers/instances, OSPF neighbors/instances, static routes	No UI yet
IPsec/Security	IPsec policies, proposals, peers; SNMP trap targets; SNMPv3 users	No UI yet

All 13 domains are reachable via the API. The 4 domains without UI (CAPsMAN, PPP/PPPoE, BGP/OSPF, IPsec/Security) are round-3 UI candidates.

Additional capabilities

• Firmware lifecycle - channel switch (stable / long-term / testing / development), check-for-updates, download, download-and-install (triggers reboot), cancel; per-package disable / enable / uninstall via /system/package.
• Config backup / restore - list .backup / .rsc / .npk artefacts, per-artefact metadata, download contents, upload text export, delete-by-name.
• Topology / neighbor discovery - /ip/neighbor enumeration with LLDP / CDP / MNDP deduplication; /ip/neighbor/discovery-settings CRUD; build_topology() returns the same {nodes, edges, warnings} envelope as Omada so the frontend graph renderer is vendor-agnostic.
• SNMP - trap-target add/remove (idempotent on the singleton comma-list); SNMPv3 user CRUD with response redaction on add/update (RouterOS sometimes echoes auth passwords back).

Frontend pages

GatewayDetailPage renders 13 tabs when controller.vendor === 'mikrotik':

System, Interfaces, IP, DHCP, Firewall, DNS, VPN, Hotspot, Queues, Firmware, Backup, Topology, SNMP.

The remaining 4 backend domains (CAPsMAN, PPP/PPPoE, BGP/OSPF, IPsec/Security) require direct API calls until the UI build-out is complete.

Backend route prefixes

/api/v1/gateway-mikrotik-system/{controller_id}/...
/api/v1/gateway-mikrotik-interfaces/{controller_id}/...
/api/v1/gateway-mikrotik-ip/{controller_id}/...
/api/v1/gateway-mikrotik-dhcp/{controller_id}/...
/api/v1/gateway-mikrotik-firewall/{controller_id}/...
/api/v1/gateway-mikrotik-dns/{controller_id}/...
/api/v1/gateway-mikrotik-vpn/{controller_id}/...
/api/v1/gateway-mikrotik-hotspot/{controller_id}/...
/api/v1/gateway-mikrotik-queues/{controller_id}/...
/api/v1/gateway-mikrotik-capsman/{controller_id}/...
/api/v1/gateway-mikrotik-ppp/{controller_id}/...
/api/v1/gateway-mikrotik-routing/{controller_id}/...
/api/v1/gateway-mikrotik-security/{controller_id}/...

Example: GET /api/v1/gateway-mikrotik-system/<controller_id>/info

Connection requirements

The MikroTik adapter uses the RouterOS v7 REST API, which must be enabled on the device.

Enabling the REST API on RouterOS v7

# Enable the REST API service (defaults to port 80/443)
/ip/service/enable www
/ip/service/enable www-ssl

# Or set a non-default port
/ip/service/set www port=8080

The REST API is available at http[s]://<router-ip>/rest/. FreeSDN uses HTTPS when the host URL starts with https://.

Credentials

Field	Value
credential_type	username_password
username	RouterOS administrator username
password	Administrator password

Tip

Create a dedicated group in RouterOS with policy=read,write,api,!sensitive and add a freesdn user to that group. This avoids running under the admin full-access account and makes the access scope explicit. For read-only monitoring, use policy=read,api and leave ADAPTER_READ_ONLY=true.

Controller URL

https://mikrotik.example.com

Or with a non-standard port:

https://192.168.1.1:8443

Adding the controller

Credentials are passed directly in the controller create body - there is no separate credential-store step for MikroTik. ControllerCreate accepts username and password inline; it has no credential_id field.

# Create the controller record (credentials inline)
curl -X POST https://<freesdn-host>/api/v1/controllers/ \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mikrotik-prod",
    "controller_type": "mikrotik",
    "site_id": "<site-uuid>",
    "host": "mikrotik.example.com",
    "port": 443,
    "use_ssl": true,
    "username": "freesdn",
    "password": "<routeros-password>"
  }'

# Trigger discovery
curl -X POST https://<freesdn-host>/api/v1/discovery/controllers/<controller-id> \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>"

Note

All collection endpoints require a trailing slash (/api/v1/controllers/, /api/v1/credentials/). The API is started with redirect_slashes=False, so omitting the trailing slash on a POST returns 404 rather than redirecting.

Enabling write operations

1. Set ADAPTER_READ_ONLY=false in your environment file.
2. Restart the API: docker compose --env-file .env.pro up -d api.
3. Stage a change in the FreeSDN UI. The change is held in pending_changes; nothing is sent to the router yet.
4. Review in Pending Changes and approve with force: true.

Caution

BGP/OSPF changes and IPsec policy changes affect routing adjacencies and VPN tunnels immediately upon apply. Review staged changes carefully before confirming. Firewall filter rule changes affect live traffic.

SNMPv3 secret redaction

RouterOS v7 sometimes echoes authentication passwords back in the REST response body when you create or update an SNMPv3 user. The adapter calls redact_secrets() (from app.core.redaction) on all such responses before they reach the API caller or audit log. The redaction pass covers ~90 sensitive key patterns (89 exact keys + 1 prefix pattern, camelCase-aware), so nested credentials in complex responses are also caught.

RouterOS v6 compatibility

The REST API (/rest/) was introduced in RouterOS v7. RouterOS v6 and earlier expose only an API socket (port 8728/8729), which is a different binary protocol. The FreeSDN MikroTik adapter requires RouterOS v7.1 or later.

Known limitations

• CAPsMAN, PPP/PPPoE, BGP/OSPF, and IPsec/Security domains have no frontend UI yet - API-only for now.

See also

• Adapter Overview - maturity tiers and the full vendor matrix
• OPNsense - alternative firewall brain with REST API auth and IDS/IPS
• Omada (TP-Link) - the limb adapter commonly paired with MikroTik