Skip to content

WinBox CLI connection

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

WinBox CLI Connection

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

WinBox CLI supports CRUD operations only — the same as the Telnet and MAC-Telnet transports. Streaming / Listen / Async commands (ExecuteAsync, LoadAsync, Torch) are not supported and will throw NotSupportedException. Use the API or REST transport for those.

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

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. A future native-M2 mode (CRUD via WinBox handlers without a terminal) and MAC-layer WinBox variants are on the roadmap; they will reuse the shared WinBox M2 layer.

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