Skip to content

WinBox CLI connection

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

WinBox CLI Connection

🆕 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.

WinBox CLI (TikConnectionType.WinboxCli) connects to a MikroTik router over the encrypted WinBox channel on TCP port 8291 — the same port and protocol the WinBox application uses — and drives the RouterOS CLI through the WinBox terminal (mepty) handler. This is useful when:

  • WinBox port is the only one open — many hardened routers expose only 8291
  • You want encryption without enabling API-SSL / certificates — WinBox encrypts out of the box
  • Telnet is disabled and you don't want to depend on an external SSH library

Authentication uses EC-SRP5 (Elliptic-Curve Secure Remote Password) with an AES-128-CBC encrypted session — the same mechanism as the WinBox application (with a legacy MD5 fallback for RouterOS older than 6.43). After auth, tik4net opens a terminal session and drives it with the same CLI layer used by the Telnet and MAC-Telnet transports, so all CRUD operations work identically.

Router prerequisites

None beyond the default — the winbox service is enabled on stock RouterOS. Verify with:

/ip/service/print

The winbox row should be enabled (default port 8291).

Basic usage

using System.Linq;
using tik4net;

using (var conn = ConnectionFactory.OpenConnection(
    TikConnectionType.WinboxCli, "192.168.4.1", "admin", ""))
{
    var ifaces = conn.LoadAll<tik4net.Objects.Interface.Interface>().ToList();
    Console.WriteLine($"Found {ifaces.Count} interfaces");
}

Using TikConnectionSetup 

var setup = new TikConnectionSetup("192.168.4.1", "admin", "");

using (var conn = setup.CreateWinboxCliConnection())
{
    var identity = conn.CreateCommand("/system/identity/print").ExecuteScalar();
    Console.WriteLine(identity);
}

// async
using (var conn = await setup.CreateWinboxCliConnectionAsync())
{
    // ...
}

Direct construction

using tik4net.WinboxCli;

var conn = new WinboxCliConnection();
conn.Open("192.168.4.1", "admin", "");

Login timeout

The login waits for the RouterOS shell prompt up to ConnectTimeout (default 15 s), separately from the per-command ReceiveTimeout (default 30 s). Lower it when you wrap Open in your own connect-retry loop so a stuck login fails fast enough to retry:

var conn = new WinboxCliConnection { ConnectTimeout = 10000 };
conn.Open("192.168.4.1", "admin", "");

// via TikConnectionSetup (its ConnectTimeout flows into the connection):
var setup = new TikConnectionSetup("192.168.4.1", "admin", "") { ConnectTimeout = TimeSpan.FromSeconds(10) };
using (var conn2 = setup.CreateWinboxCliConnection()) { /* ... */ }

Capability

CRUD and Listen — WinBox CLI reports Crud | Listen, like all CLI transports (Telnet, MAC-Telnet, WinBox-CLI-MAC), so the callback-based async APIs work in addition to synchronous CRUD. A terminal has no server push, so the async commands are emulated by polling a one-shot snapshot on a background worker:

Call shape Example How it works
Streaming monitor /interface/monitor-traffic, /tool/profile re-issues :put [… <once> as-value] (snapshot modifier per command) every ~500 ms and pushes each polled record to your row callback
Finite command /ping, /tool/traceroute runs once (its own count/duration bounds it), emits the rows, completes
Change listen conn.LoadListenAsync<Interface>(onChange, onDeleted, …) polls the table and diffs snapshots by .id — a changed row fires onChange, a vanished .id fires onDeleted
Async list cmd.LoadAsync<Interface>(…) on a /print runs the read on a background thread, emits each row, completes 
bool hasCrud   = conn.Supports(TikConnectionCapability.Crud);   // true
bool hasListen = conn.Supports(TikConnectionCapability.Listen); // true

TikConnectionCapability.Streaming (ExecuteListWithDuration) is not reported — use the API transport for that. A few commands are interactive-only over a terminal — notably /tool/torch, which repaints a VT100 screen and has no as-value snapshot to poll; those surface a guiding error through the async error callback. Use the API transport's Streaming capability for them.

Notes

  • The connection is fully encrypted (EC-SRP5 + AES-128-CBC) end to end — unlike Telnet and MAC-Telnet, which carry the terminal in plain text after auth.
  • RouterOS 6.43+ uses EC-SRP5; older firmware falls back to legacy MD5 auth automatically. The terminal session itself requires the encrypted (EC-SRP5) channel — terminal-over-legacy throws NotSupportedException (a non-issue for any modern router).
  • CRUD goes through the RouterOS CLI (print as-value), so behaviour matches the other CLI transports, including the same handling of comments, ordering and .id values.
  • This is the terminal-driven WinBox mode. There is also a native-M2 mode (WinboxNative — structured CRUD via WinBox handlers, no terminal) and a MAC-layer variant; all three share the same WinBox M2 channel and auth.

Acknowledgements

The WinBox implementation builds on protocol research by the MikroTik reverse-engineering community:

  • subixonfire/winbox-terminal-protocol (MIT) — primary reference for Curve25519 EC-SRP5 authentication, AES-128/HMAC stream-key derivation, the M2 message (TLV) format and the mepty terminal handler.

See also

Clone this wiki locally