Skip to content

WinBox Native MAC connection

Jump to bottom
Daniel Frantík edited this page Jun 17, 2026 · 3 revisions

WinBox Native (M2) over MAC Connection 🆕 4.x ⚠️ Alpha-preview

🆕 New in tik4net 4.0 — first released as v4.0.0-alpha. Alpha: API and behaviour are stable for testing but may still change before the final 4.0 release. See Connection types & capabilities.

Alpha-preview. Same maturity caveat as WinBox Native: the API ↔ M2 mapping is reconstructed from the WinBox .jg catalog and covers common tables, but exotic tables/verbs may need a PathOverride/FieldOverride. On top of that this transport rides the MAC layer, which is slower and lossier than TCP (UDP with per-packet ACKs). For production prefer the API; when you need the WinBox channel without an IP route, the encrypted WinBox CLI over MAC is the more battle-tested option.

WinBox Native over MAC (TikConnectionType.WinboxNativeMac) is the same structured M2 CRUD engine as WinBox Native — getall / get / set / add / remove / move handlers, no CLI screen-scraping — but the M2 messages travel over the MAC layer (UDP port 20561, client_type=0x0f90) instead of TCP 8291, so it works without an IP route to the router.

It is to WinBox Native exactly what WinBox CLI over MAC is to WinBox CLI: identical protocol above the channel, only the carrier differs. Authentication is the same EC-SRP5 + AES-128-CBC handshake, tunnelled in MAC DATA packets (the MAC transport does not implement the legacy MD5 path, so it requires RouterOS 6.43+).

Router prerequisites

Enable the MAC WinBox server (this is separate from the MAC-Telnet server):

/tool/mac-server/mac-winbox set allowed-interface-list=all

The router's MAC address is discovered automatically via MNDP (see MNDP); set RouterMac to skip the discovery wait (below).

Basic usage

using System.Linq;
using tik4net;

// MNDP discovers the router MAC automatically (takes up to 5 s)
using (var conn = ConnectionFactory.OpenConnection(
    TikConnectionType.WinboxNativeMac, "192.168.4.1", "admin", ""))
{
    var ifaces = conn.LoadAll<tik4net.Objects.Interface.Interface>().ToList();
    foreach (var i in ifaces)
        conn.CreateCommandAndParameters("/interface/set", ".id", i.Id, "comment", "managed").ExecuteNonQuery();
}

Bypass MNDP with a known MAC address

MNDP discovery waits up to 5 seconds and is environment-sensitive (it relies on Layer-2 broadcast reaching the host). If you already know the router's MAC, skip the wait — and avoid discovery failures — by setting RouterMac:

using tik4net.WinboxNativeMac;

var conn = new WinboxNativeMacConnection { RouterMac = "AA:BB:CC:DD:EE:FF" };
conn.Open("192.168.4.1", "admin", "");

Direct construction also exposes the same knobs as the TCP native transport — ConnectTimeout, CatalogCachePath, and the PathOverride / FieldOverride mapping overrides (set them before Open):

using tik4net.WinboxNativeMac;

var conn = new WinboxNativeMacConnection
{
    RouterMac        = "AA:BB:CC:DD:EE:FF",
    ConnectTimeout   = 15000,
    CatalogCachePath = @"C:\ProgramData\myapp\winbox-cache",
};
conn.PathOverride("/ppp/secret", new[] { 27, 101 });
conn.Open("192.168.4.1", "admin", "");

The API ↔ WinBox mapping

This is identical to the TCP native transport — handler/field numbers are read live from the router's version-matched .jg catalog (cached under CatalogCachePath), and only the stable English text bridge is shipped. The mapping problem, how tik4net solves it, the session overrides, the catalog cache, and the error-translation table are all documented once on the WinBox Native page — everything there applies here unchanged.

The only practical difference is catalog load cost: the .jg set is fetched over the MAC channel at connect time (more round-trips than TCP). It is best-effort — if a slow/lossy MAC link can't complete the load, the built-in seeds and normalizer still resolve common paths, and an unresolved path throws the usual guiding TikNoSuchCommandException. A warm on-disk cache (shared with the TCP native transport, keyed by router version) removes the cost on subsequent connects.

Capability

CRUD and Listen (Crud | Listen | SafeMode) — same as the TCP native transport. The callback-based async APIs (ExecuteAsync / LoadAsync / LoadListenAsync) work and cover streaming monitors, async lists, and change-listen exactly as described on WinBox Native. Polling over the MAC layer is slow (per-packet ACKs) — prefer the TCP native transport or the SSL API for high-rate monitoring when an IP route is available.

bool hasCrud     = conn.Supports(TikConnectionCapability.Crud);     // true
bool hasListen   = conn.Supports(TikConnectionCapability.Listen);   // true
bool hasSafeMode = conn.Supports(TikConnectionCapability.SafeMode); // true

Safe Mode

Supported via the same native M2 commands as the TCP transport: SafeModeTake() / SafeModeRelease() work over the MAC channel (SafeModeUnroll() throws — native WinBox has no in-place unroll; drop the connection to roll back). See Safe Mode.

Notes

  • Encrypted end to end (EC-SRP5 + AES-128-CBC) — unlike MAC-Telnet, which is plain text after auth.
  • The MAC WinBox server (/tool/mac-server/mac-winbox) is independent of the MAC-Telnet server (/tool/mac-server); enable the one you need.
  • Slower and lossier than TCP — every M2 frame is carried in MAC DATA packets with per-packet ACKs, and the .jg catalog load adds round-trips. Set RouterMac to skip MNDP, and use the TCP WinBox Native transport whenever an IP route is available.
  • Requires RouterOS 6.43+ (EC-SRP5). The MAC transport does not implement the legacy MD5 path.

Acknowledgements

Combines the WinBox M2 mapping research behind WinBox Native with the MAC-layer framing / EC-SRP5-over-MAC work behind the MAC-Telnet and WinBox CLI over MAC transports.

See also

Clone this wiki locally