@keeb/mikrotik-routeros

Manage a MikroTik RouterOS device (router or CRS/CCR switch) over its REST API. The extension decomposes the box into per-object, typed resources you can query with CEL, and exposes a small, safe set of control methods.

Built and tested against a CRS309-1G-8S+ running RouterOS 7.12.2.

Models

Type	discover writes	Control methods
@keeb/mikrotik-routeros/system	resource, routerboard, health, identity	set_identity, reboot
@keeb/mikrotik-routeros/interface	one port per interface	enable_port, disable_port, set_comment
@keeb/mikrotik-routeros/bridge	bridge, bridgePort, vlan	— (read-only)
@keeb/mikrotik-routeros/ip	address, route, dns	— (read-only)

Bridge and IP are intentionally read-only: mutating L2/L3 on a switch you're managing over the network is the fast path to locking yourself out. The write surface is limited to per-port admin state, the device identity, and reboot.

RouterOS values are strings. The REST API returns every field as a string ("disabled": "false", "cpu-load": "0"). Resource schemas store them as strings; write CEL predicates accordingly, e.g. attributes.running == "true".

Setup

RouterOS REST uses HTTP Basic auth. Store the password in a vault and reference it from the model's password global argument; a factory-default device is user admin with an empty password.

swamp extension pull @keeb/mikrotik-routeros

# Store the admin password (leave empty for a factory-default box)
swamp vault create local_encryption mikrotik
swamp vault put mikrotik admin_password

# One model instance per subsystem you want to manage
swamp model create @keeb/mikrotik-routeros/system crs-system \
  --global-arg baseUrl=http://192.168.88.1/rest \
  --global-arg username=admin \
  --global-arg 'password=${{ vault.mikrotik.admin_password }}'

swamp model @keeb/mikrotik-routeros/system method run discover crs-system

Examples

# Which ports are up?
swamp data query crs-ports 'attributes.running == "true"' --select name,macAddress

# Disable an unused port, then re-enable it
swamp model @keeb/mikrotik-routeros/interface method run disable_port crs-ports \
  --arg name=sfp-sfpplus3
swamp model @keeb/mikrotik-routeros/interface method run enable_port crs-ports \
  --arg name=sfp-sfpplus3

# Label a port
swamp model @keeb/mikrotik-routeros/interface method run set_comment crs-ports \
  --arg name=sfp-sfpplus8 --arg comment="uplink to workstation"

# Rename the device
swamp model @keeb/mikrotik-routeros/system method run set_identity crs-system \
  --arg name=crs309-rack

Connection global arguments

Arg	Required	Default	Description
baseUrl	yes	—	REST root, e.g. http://192.168.88.1/rest
username	no	admin	HTTP Basic username
password	no	""	HTTP Basic password (resolve from a vault)

RouterOS enables the www (HTTP) service by default; enable www-ssl on the device and use an https:// baseUrl if you want TLS.

License

MIT — see LICENSE.txt.