#mactelnet API reference

A MikroTik MAC-Telnet client - a Layer-2 console to a RouterOS device by MAC address, with no IP configured on either side (what Winbox's "Neighbors" console does). The transport is UDP broadcast on port 20561 with the source and destination MAC carried in the packet payload, so it reaches a router that has no address yet - the way to set the first IP on a fresh or just-reset device before switching to the IP-based mikrotik API.

connect runs the full session-start + authentication handshake and returns a logged-in Session; send writes a console command, recv reads whatever output is available, and close ends the session. It drives the router's text CLI (send /ip address add ...\r\n, read the echo), not the binary API.

Authentication auto-detects the router's generation from the salt it offers: legacy 16-byte-salt MD5 (RouterOS < 6.43) or the modern 49-byte EC-SRP (Curve25519; RouterOS 6.43+ and all v7, including factory-fresh devices), via crypto.mtwei*. The local interface's MAC is read from /sys/class/net.

Needs the default jennifer binary (net, and broadcast UDP is Linux-only). Over net (SO_BROADCAST + UDP) + crypto (EC-SRP) + hash (MD5) + binary + encoding + fs + kv (per-session mutable counters).

SECURITY: MAC-Telnet is an unauthenticated-transport, cleartext L2 protocol - the password proof is hashed but the session itself is not encrypted, and any host on the same segment can see the traffic. Use it only on a trusted wire to bootstrap a device, then move to mikrotik.optionsTLS (api-ssl) over IP.

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

#Functions

#mactelnet.close(s as Session)

End the session: tell the router, then release the socket and session state.

Parameters

• s {Session} - the session

Returns {null} - nothing

#mactelnet.closed(s as Session)

Whether the router has closed the session (an END packet was seen).

Parameters

• s {Session} - the session

Returns {bool} - true once the session has ended

#mactelnet.connect(iface as string, mac as string, user as string, password as string)

Open a MAC-Telnet console to a router by MAC address and log in. Runs the full session-start + authentication handshake (auto-detecting MD5 vs EC-SRP from the router's salt) and returns a logged-in Session.

iface is the local interface to reach the router on: its MAC is read from /sys/class/net/<iface>/address, and the broadcast socket is best-effort bound to the interface (SO_BINDTODEVICE) so a multi-homed host sends out that link rather than one the kernel routing table picks. The bind needs root; when unprivileged it is skipped (fine on a single-NIC host, but a multi-homed host should run this with privilege or it may time out on the wrong NIC). mac is the router's MAC. A blank password is valid (a factory-default admin). Throws Error{kind: "mactelnet"} on an unreachable router or a failed login.

Parameters

• iface {string} - local network interface name (e.g. "eth0")
• mac {string} - the router's MAC address
• user {string} - the login user (e.g. "admin")
• password {string} - the login password ("" for none)

Returns {Session} - a logged-in session

#mactelnet.formatMac(b as bytes)

Format 6 raw MAC bytes as a colon-separated lower-case string.

Parameters

• b {bytes} - the 6-byte address

Returns {string} - "aa:bb:cc:dd:ee:ff"

#mactelnet.parseMac(s as string)

Parse a MAC address string ("aa:bb:cc:dd:ee:ff", "-" separators or none also accepted) into its 6 raw bytes.

Parameters

• s {string} - the MAC address text

Returns {bytes} - the 6-byte address

#mactelnet.recv(s as Session, timeoutMs as int)

Read whatever console output has arrived, waiting up to timeoutMs for the first byte. Returns the accumulated text (possibly ""); call it again to read more. ANSI escape sequences from the RouterOS CLI are passed through verbatim.

Parameters

• s {Session} - the session
• timeoutMs {int} - how long to wait for output, in milliseconds

Returns {string} - the console output received

#mactelnet.send(s as Session, text as string)

Send a console command (or any raw input) to the router. Include a trailing "\r\n" to submit a command line. Output is not returned here; read it with recv.

Parameters

• s {Session} - the session
• text {string} - the text to send

Returns {null} - nothing

#Structs

#mactelnet.Session

An open MAC-Telnet console session. sock is the broadcast UDP socket; state is a per-session key/value store holding the mutable send/receive counters and the pending-output buffer (a plain struct field could not persist a mutation across a module call, so the counters live in shared kv state); srcmac / dstmac are the 6-byte local and router MACs; seskey is the random session id.