Crate mikrotik_api

Expand description

§Library and minimal client for RouterOS’ proprietary API

Mikrotik RouterOS exposes on port TCP/8278 a semi-textual API composed of words and sentences. This API allow power-users to request data about the router state, set configuration, listen to some events, … using a syntax similar to the one used in the CLI.

For a more in-depth description of the API, please see the official Mikrotik wiki.

§The library

Based on tokio and fully asynchronous, the library allows to deal with all the API’s uses cases :

simple requests with one-off answers, like /system/identity/print,
simple requests with array-like answers, like /interfaces/print,
simple requests to listen to events, like /user/active/listen,
cancel streaming commands with /cancel

§Usage

The library exposes only one function: connect, that makes a TCP connection to the provided address. If successful, a MikrotikAPI<Disconnected> object is returned. It is then necessary to authenticate to get a MikrotikAPI<Authenticated> object. Eight functions are then available:

system_resources will make a call to /system/resource/print
interfaces will retrieve a list of interfaces with all their properties (/interfaces/print)
active_users returns a Stream of events regarding user activity (login & logout)
interface_changes returns a Stream of events regarding changes to interfaces (up, down, …)
cancel cancels a streaming command given its tag
generic_oneshot_call allows to call any endpoint providing a one-off answer. Thanks to type inference, answer is returned in the user’s object of choice. Example:

#[derive(Debug, Deserialize)]
struct Identity {
  pub name: String,
}
let identity = api
  .generic_oneshot_call::<Identity>("/system/identity/print", None)
  .await
  .unwrap();
println!("Name: '{}'", identity.name);

generic_array_call will do the same job but for endpoints providing multiples (but finite) answers
generic_streaming_call will provide a Stream of Response for any endpoint supporting the listen command. Example:

#[derive(Debug, Deserialize)]
struct Interface {
  pub name: String,

  #[serde(default)]
  pub running: bool
}

let mut tag: u16 = 0;

let changes = api
  .generic_streaming_call::<Interface>("/interface/listen", None, &mut tag); //`tag` allows us to cancel the stream later on.

tokio::spawn(changes.for_each(|item| async move {

  if let Reponse::Reply(iface) = item {

      let up_down = if iface.running { "up" } else { "down" };

      println!("Interface {} is {}", iface.name, up_down);
  }

})).await;

Structs§

Authenticated: API in authenticated state: user has access to the full api.
Disconnected: API in disconnected state: socket is connected but user has not yet completed its authentification.
Interface: Reply from /system/interface/print command
InterfaceChange: Incomplete reply from /system/interface/listen command That may in fact be the same struct as Interface
MikrotikAPI: Struct to interact with Mikrotik RouterOS API on port 8728
SystemResources: Reply from /system/resource/print command

Enums§

ActiveUser: An event to describe user activity in terms of logins and logouts
InterfaceMTU: Enum to represent the mtu field that can take either a number value or a text: ‘auto’
Response: A response to a command, sent by the router.

Functions§

connect: Given an address, opens a connection to the remote API service the returned object is in a Disconnected state