`mikrotik` API reference

A MikroTik RouterOS API client over net (not SSH). Connect to a router's binary API (plain TCP 8728, or api-ssl 8729 over TLS), log in, and run commands. The wire protocol is sentence-based: a sentence is a run of length-prefixed words ending in a zero-length word; talk sends a command sentence (/interface/print) with =key=value attribute words and folds each !re reply sentence into a row map. talkQuery / printWhere add ?... query words to filter rows on the router. print is read sugar, run is for mutating commands (returning the !done's =ret=, e.g. a new item id).

Login is plaintext (=name= / =password=, RouterOS 6.43+ and all v7), with an automatic MD5 challenge-response fallback for pre-6.43 routers. A !trap or !fatal reply throws Error{kind: "mikrotik"}. Needs the default jennifer binary (net). Over net + hash (MD5 fallback) + encoding + the bitwise operators.

SECURITY: mikrotik.options uses cleartext TCP (port 8728), so the credentials and every command are readable on the wire. Use mikrotik.optionsTLS (api-ssl, port 8729) on any untrusted network. A CONNECT_TIMEOUT_MS deadline bounds the dial and every read, and a server-declared word length is capped at MAX_WORD_BYTES (64 MiB), so a wedged or hostile router cannot hang or OOM the program.

Import with import "mikrotik.j" as mikrotik;. See the mikrotik guide for prose and examples.

Functions

`mikrotik.cancel(session as Session, tag as string)`

Stop a streaming command started with listen by issuing /cancel naming its tag. Fire-and-forget: the resulting !trap (interrupted) and !done for the stream, plus the /cancel's own reply, are drained by the receiveReply loop (which then returns {} and lets the loop exit).

Parameters

session {Session} - the session
tag {string} - the stream tag returned by listen

`mikrotik.close(session as Session)`

Close the session's connection.

Parameters

session {Session} - the session

`mikrotik.connect(opts as Options)`

Connect to a router and log in.

Parameters

opts {Options} - the connection options

Returns {Session} - the logged-in session

Throws

{Error} - kind "mikrotik" on a login failure

`mikrotik.listen(session as Session, command as string, params as map of string to string)`

Start a streaming command (one that pushes !re sentences over time, e.g. "/interface/monitor" or "/ping") and return its auto-generated tag. Does NOT read a reply - the stream has no !done until it is stopped. Pull each pushed reply with receiveReply($s, tag) (typically from a spawned loop), and stop it with cancel($s, tag).

Parameters

session {Session} - the session
command {string} - the streaming API command
params {map of string to string} - attribute words for the command ({} for none)

Returns {string} - the tag naming this stream (feed it to receiveReply / cancel)

`mikrotik.options(host as string, user as string, password as string)`

Plain-TCP options (port 8728). SECURITY: this transport is cleartext - the login exchange and every command travel unencrypted, so an on-path attacker reads the router's admin credentials. Prefer optionsTLS (api-ssl, port 8729) on any network you do not fully trust; use options only on a loopback or an otherwise-secured link.

Parameters

host {string} - the router host
user {string} - the API username
password {string} - the API password

Returns {Options} - the options

`mikrotik.optionsTLS(host as string, user as string, password as string)`

api-ssl (TLS) options (port 8729).

Parameters

host {string} - the router host
user {string} - the API username
password {string} - the API password

Returns {Options} - the options

`mikrotik.print(session as Session, path as string)`

Read sugar: run path + "/print" with no attributes.

Parameters

session {Session} - the session
path {string} - the menu path (e.g. "/interface")

Returns {list of map of string to string} - the reply rows

Throws

{Error} - kind "mikrotik" on a !trap / !fatal reply

`mikrotik.printWhere(session as Session, path as string, queries as list of string)`

Read sugar: run path + "/print" filtered by query words (no attributes) - printWhere($s, "/interface", ["?type=ether"]) returns only the ether ports.

Parameters

session {Session} - the session
path {string} - the menu path (e.g. "/interface")
queries {list of string} - raw query words, each starting with "?"

Returns {list of map of string to string} - the matching reply rows

Throws

{Error} - kind "mikrotik" on a bad query word or a !trap / !fatal reply

`mikrotik.receiveReply(session as Session, tag as string)`

Block until the next pushed reply for tag arrives and return it as a =key=value field map. Returns an empty map when the stream has ended (a !done for the tag - e.g. after cancel), which is the loop's stop signal. Replies carrying a different tag are skipped (they belong to another stream on the same session). A cancel-induced !trap (category "interrupted") is absorbed; any other !trap / !fatal throws.

Parameters

session {Session} - the session
tag {string} - the stream tag returned by listen

Returns {map of string to string} - the next reply's fields, or {} at stream end

Throws

{Error} - kind "mikrotik" on a genuine !trap / !fatal reply

`mikrotik.run(session as Session, command as string, attrs as map of string to string)`

Run a mutating command (add / set / remove) and return the !done =ret= value (e.g. the new item's id for add; "" when there is none).

Parameters

session {Session} - the session
command {string} - the API command (e.g. "/ip/address/add")
attrs {map of string to string} - attribute words

Returns {string} - the =ret= value, or ""

Throws

{Error} - kind "mikrotik" on a !trap / !fatal reply

`mikrotik.talk(session as Session, command as string, attrs as map of string to string)`

Run a command with attribute words and return the !re reply rows (each a =key=value map). The general call - reads, adds, sets, and removes all go through it.

Parameters

session {Session} - the session
command {string} - the API command (e.g. "/interface/print")
attrs {map of string to string} - attribute words ({} for none)

Returns {list of map of string to string} - the reply rows

Throws

{Error} - kind "mikrotik" on a !trap / !fatal reply

`mikrotik.talkQuery(session as Session, command as string, attrs as map of string to string, queries as list of string)`

Like talk, but also sends RouterOS query words to filter the reply on the router. Each query word is raw and starts with ?: ?type=ether (property equals), ?disabled (property present), ?>mtu=1000 (greater), plus the stack operators ?#! / ?#& / ?#| for compound queries. Attribute words still apply (e.g. =.proplist=name,type to trim the columns). The general filtered read the higher-level helpers build on.

Parameters

session {Session} - the session
command {string} - the API command (e.g. "/interface/print")
attrs {map of string to string} - attribute words ({} for none)
queries {list of string} - raw query words, each starting with "?"

Returns {list of map of string to string} - the matching reply rows

Throws

{Error} - kind "mikrotik" on a bad query word or a !trap / !fatal reply

`mikrotik.talkTagged(session as Session, command as string, attrs as map of string to string, tag as string)`

Like talk, but attaches a .tag=<id> word so the router echoes the tag on every reply, letting a caller correlate this command's replies. Pass tag: "" to auto-generate a unique tag. The reply is still collected to !done (a one-shot command); for a command that pushes replies over time use listen + receiveReply.

Parameters

session {Session} - the session
command {string} - the API command (e.g. "/interface/print")
attrs {map of string to string} - attribute words ({} for none)
tag {string} - the correlation tag, or "" to auto-generate one

Returns {list of map of string to string} - the reply rows

Throws

{Error} - kind "mikrotik" on a !trap / !fatal reply

`mikrotik.withPort(o as Options, port as int)`

Copy options with a different port.

Parameters

o {Options} - the options
port {int} - the port

Returns {Options} - a fresh options

Structs

`mikrotik.Options`

Connection options.

Field	Type	Description
`host`	`string`	the router host
`port`	`int`	the API port (8728 plain, 8729 api-ssl)
`user`	`string`	the API username
`password`	`string`	the API password
`tls`	`bool`	whether to use api-ssl (TLS)

`mikrotik.Session`

An open, logged-in API session.

Field	Type	Description
`socket`	`net.Conn`	the underlying (plain or TLS) connection

#mikrotik API reference

#Functions

#mikrotik.cancel(session as Session, tag as string)

#mikrotik.close(session as Session)

#mikrotik.connect(opts as Options)

#mikrotik.listen(session as Session, command as string, params as map of string to string)

#mikrotik.options(host as string, user as string, password as string)

#mikrotik.optionsTLS(host as string, user as string, password as string)

#mikrotik.print(session as Session, path as string)

#mikrotik.printWhere(session as Session, path as string, queries as list of string)

#mikrotik.receiveReply(session as Session, tag as string)

#mikrotik.run(session as Session, command as string, attrs as map of string to string)

#mikrotik.talk(session as Session, command as string, attrs as map of string to string)

#mikrotik.talkQuery(session as Session, command as string, attrs as map of string to string, queries as list of string)

#mikrotik.talkTagged(session as Session, command as string, attrs as map of string to string, tag as string)

#mikrotik.withPort(o as Options, port as int)

#Structs

#mikrotik.Options

#mikrotik.Session

`mikrotik` API reference

Functions

`mikrotik.cancel(session as Session, tag as string)`

`mikrotik.close(session as Session)`

`mikrotik.connect(opts as Options)`

`mikrotik.listen(session as Session, command as string, params as map of string to string)`

`mikrotik.options(host as string, user as string, password as string)`

`mikrotik.optionsTLS(host as string, user as string, password as string)`

`mikrotik.print(session as Session, path as string)`

`mikrotik.printWhere(session as Session, path as string, queries as list of string)`

`mikrotik.receiveReply(session as Session, tag as string)`

`mikrotik.run(session as Session, command as string, attrs as map of string to string)`

`mikrotik.talk(session as Session, command as string, attrs as map of string to string)`

`mikrotik.talkQuery(session as Session, command as string, attrs as map of string to string, queries as list of string)`

`mikrotik.talkTagged(session as Session, command as string, attrs as map of string to string, tag as string)`

`mikrotik.withPort(o as Options, port as int)`

Structs

`mikrotik.Options`

`mikrotik.Session`