Skip to content

Home

Jump to bottom
Daniel Frantík edited this page Aug 30, 2026 · 61 revisions

tik4net

tik4net is a .NET library for talking to MikroTik RouterOS devices. It scales from raw API access up to a fully typed O/R mapper, all behind one ITikConnection interface. Tested and debugged against RouterOS 7.24 (latest stable) — every transport is verified against a live router on that version.

Three lines get you connected (quick start), and the same three lines reach the router over any of 11 transports — the binary API, REST, Telnet, SSH, the WinBox channel, and the MAC-layer variants that need no IP address on the router at all. You pick the way in that the router already has enabled, instead of reconfiguring it first; switching is one enum value and the rest of your code is untouched. (tik4net is the only .NET library that speaks MAC-Telnet and the WinBox protocols.)

You also pick the level you work at, and the three levels share one connection, so you can drop a level for a single call without leaving the model: raw sentences in the transport's own language, an ADO.NET-shaped command/parameter API, or a typed O/R mapper over 169 RouterOS menus. Even at the lowest level the library still does the dirty work — response parsing, terminal and paging behaviour, quoting, both API login handshakes, tagging replies back to their caller, uniform error semantics — and what a transport can do is answered by its own typed interface — a Rest connection has no SafeModeTake to call, so the mistake is a compile error rather than a runtime one, with capability flags for what depends on the router itself. Around that: change tracking, Safe Mode, streaming and async monitors, unit tests without a router, MNDP discovery and an MCP server. You pay for none of it to print the router's identity.

⚠️ Alpha — ships in v4.0.0-alpha: tested and functional, but the API may still change before the final 4.0 release. See Connection types & capabilities.

Upgrading from 3.x? 4.0 flips two connection defaults (AllowInvalidCertificate, SendTagWithSyncCommand), makes entity properties nullable and merges the tik4net.objects package into tik4net — see Upgrading from 3.x to 4.0.

Install

dotnet add package tik4net            # low-level API + high-level O/R mapper — start here
dotnet add package tik4net.testing    # unit-testing support (TikFakeConnection)
dotnet add package tik4net.ssh        # SSH transport — separate package because of Renci.SshNet

Coming from 3.x? The O/R mapper ships inside tik4net — remove any separate tik4net.objects reference. See Upgrading from 3.x to 4.0.

Quick start — read the router identity

The simplest possible program: open a connection and print one value.

using tik4net;

// TikConnectionSetup is the entry point: it carries every option and opens the transport you name.
// TikConnectionType.Api works for the old and the new (v6.43+) login alike.
var setup = new TikConnectionSetup(TikRouterAddress.FromHost(HOST), USER, PASS);

using (ITikConnection connection = setup.Create(TikConnectionType.Api))
{
  ITikCommand cmd = connection.CreateCommand("/system/identity/print");
  Console.WriteLine(cmd.ExecuteScalar());
}

Swap TikConnectionType.Api for Rest, Ssh, Telnet, MacTelnet or one of the WinBox types and nothing else in your code changes.

Read a list of typed entities (high-level API)

The recommended way to read/write data is the strongly-typed O/R mapper.

using tik4net;
using tik4net.Objects;

using (ITikConnection connection = setup.Create(TikConnectionType.Api))
{
  foreach (var log in connection.LoadAll<Log>())
    Console.WriteLine("{0}[{1}]: {2}", log.Time, log.Topics, log.Message);
}

Create / update / delete (CRUD)

// Create an address-list item via the high-level API
using (ITikConnection connection = setup.Create(TikConnectionType.Api))
{
  var newAddressList = new FirewallAddressList()
  {
    Address = ipAddress,
    List = listName,
  };
  connection.Save(newAddressList);
  Console.WriteLine("Created item with id {0}", newAddressList.Id);
}

The same thing with the low-level and ADO.NET-like APIs, plus update/delete for all three levels, is on the CRUD examples for all APIs page.

📋 One task on every transport and API level

The same task written at all three API levels, and run over every one of the 11 transports — find a row, keep its .id, write back. 29 complete, copy-and-run programs, one per tab: each states what it needs enabled on the router, what goes in, what comes out and what to watch out for on that transport. (29 rather than 33: the low level does not exist on REST or native WinBox, and those four tabs say why.)

Start here if you want a program you can paste and run rather than a snippet to assemble.

Asynchronous / streaming commands (e.g. torch)

using (ITikConnection connection = setup.Create(TikConnectionType.Api))
{
  ITikCommand torch = connection.LoadWithCallback<ToolTorch>(
    torchItem => Console.WriteLine(torchItem.ToString()),
    error => Console.WriteLine(error.ToString()),
    connection.CreateParameter("interface", interfaceName),
    connection.CreateParameter("port", "any"),
    connection.CreateParameter("src-address", "0.0.0.0/0"),
    connection.CreateParameter("dst-address", "0.0.0.0/0"));

  Console.ReadLine();
  torch.Cancel();
}

Where to go next

Choosing the three API levels

Features

  • Easy to use — a few lines of code
  • R/W access and reading data
  • Support for parallel async commands (like torch)
  • ITikConnection as the single unified entry point to the router — plus a typed interface per transport (ITikApiConnection, ITikCliConnection, ITikRestConnection, …), so a transport's limits are compile errors rather than surprises
  • Low-level API like other simple MikroTik API libraries
  • ADO.NET-like strongly-typed API (connection, commands, parameters)
  • High-level O/R-mapper-like API
    1. Strongly-typed objects for MikroTik entities (QueueTree, FirewallMangle, …) — 169 menus covered, with typed value types and non-CRUD helpers
    2. Support for ordering lists of entities on the router
    3. Support for merging collections with the state on the router (prepare the expected state, only the necessary operations are performed)
  • Unit-testing support via tik4net.testing — TikFakeConnection tests all API levels without a live router
  • 🆕 Change tracking — Save diffs against the load-time snapshot and sends only changed fields; no-op saves skip the API call entirely
  • 🆕 Safe Mode — SafeModeTake() / SafeModeRelease() / SafeModeUnroll() with automatic rollback-on-disconnect (lockout protection)
  • 🆕 MCP server — run any command over any transport from an AI assistant (Claude Code/Desktop), with per-transport RAW protocol trace
  • tik4mcp — standalone admin-grade MikroTik MCP server built on tik4net; multi-router inventory, RBAC, guardrails, and a production-oriented toolset for AI-assisted network management
  • Clean design, clear, well-documented code

Connection transports

All transports sit behind the same ITikConnection interface — see connection types & capabilities for the full capability matrix, and how ExecuteXxx is translated per transport.

Transport
Api / ApiSsl binary MikroTik API protocol, TCP 8728 / 8729 — the reference transport, with the full feature set
Rest / RestSsl HTTP REST API (RouterOS 7.1+), TCP 80 / 443 — stateless, so no Safe Mode
Telnet plain-text CLI, TCP 23
Ssh encrypted CLI over an SSH shell, TCP 22 — separate tik4net.ssh package
MacTelnet Layer-2 CLI, UDP 20561 — no IP route needed (EC-SRP5 auth)
WinboxCli encrypted CLI over the WinBox channel, TCP 8291 — EC-SRP5 + AES, no certificates
WinboxCliMac the same encrypted WinBox CLI over the MAC layer, UDP 20561
WinboxNative ⚠️ structured CRUD via native WinBox M2 calls, TCP 8291 — no terminal
WinboxNativeMac ⚠️ the same native M2 CRUD over the MAC layer, UDP 20561

⚠️ The two native WinBox transports are experimental: they address every field by number and the name mapping is reconstructed from the router's own catalog rather than from a published contract. For production work over the WinBox channel prefer WinboxCli / WinboxCliMac, which drive the router's own CLI and need no mapping at all.

For the MikroTik protocol itself, see the MikroTik API manual.

Clone this wiki locally