Lib.rs

› 异步
#api #api-bindings #client-connect #mikrotik #router-os #port #events

bin+lib mikrotik_api

Rust 库和连接到 Mikrotik RouterOS API 的最小客户端，通常暴露在端口 8728 上

由 Nic0w

2 个不稳定版本

0.3.0 2022 年 9 月 29 日
0.2.1 2022 年 9 月 11 日

#1110 in 异步

自定义许可证

73KB
2K SLoC

用于 RouterOS 自有 API 的库和最小客户端

Mikrotik RouterOS 在 TCP/8278 端口上暴露了一个半文本 API，由单词和句子组成。此 API 允许高级用户通过类似于 CLI 中的语法请求有关路由器状态的数据、设置配置、监听某些事件等。

有关 API 的更深入描述，请参阅官方 Mikrotik 维基。

虽然实现起来可能看起来很简单，但处理所有用例中涉及一些复杂性。例如，可以发送多个 'listen' 命令，这些命令将流式传输事件，同时请求更简单的、由一次性响应组成的数据。本质上，该 API 高度异步，并在事件流之间多路复用对请求的响应；这些特性使得 Rust 生态系统特别适合此类工作！

库

基于 tokio 且完全异步的库，允许处理所有 API 的用例

  • 像 /system/identity/print 这样的简单请求，只有一次性回答
  • 像 /interfaces/print 这样的简单请求，具有类似数组的回答
  • 像 /user/active/listen 这样的简单请求，用于监听事件
  • 使用 /cancel 取消流式命令

还有很多工作要做，比如支持查询词等。

用法

库只公开一个函数：connect，该函数将在提供的地址上建立 TCP 连接。如果成功，将返回一个 MikrotikAPI<Disconnected> 对象。然后需要执行 authenticate 来获取 MikrotikAPI<Authenticated> 对象。

然后有八个函数可用

  • system_resources 将调用 /system/resource/print
  • interfaces 将检索具有所有属性的接口列表（/interfaces/print）
  • active_users 返回一个关于用户活动（登录和登出）事件的 Stream。
  • interface_changes 返回一个关于接口变化（上、下等）事件的 Stream。
  • cancel 根据标签取消一个流式命令。
  • generic_oneshot_call 允许调用任何端点并提供一个一次性答案。得益于类型推断，答案会返回到用户选择的对象中。示例：
#[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 将执行相同的任务，但适用于提供多个（但有限）答案的端点。
  • generic_streaming_call 为支持 listen 命令的任何端点提供一个 Stream 的 Response。示例：
#[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;

客户端

目前它更像是一个库使用示例，而不是有实际目的的示例。

mikrotik_api 0.1.0

USAGE:
   client --address <ADDRESS> --login <LOGIN> --password <PASSWORD> <SUBCOMMAND>

OPTIONS:
   -A, --address <ADDRESS>      <HOST>:<PORT>
   -h, --help                   Print help information
   -L, --login <LOGIN>          
   -P, --password <PASSWORD>    
   -V, --version                Print version information

SUBCOMMANDS:
   active-users    
   help            Print this message or the help of the given subcommand(s)
   identify

目前它包含三个子命令

  • identify：将打印您的路由器的名称及其资源（使用 --full）
  • active-users：将监听用户活动并以类似日志的方式显示事件
  • custom，最好的是，允许调用各种任意命令（一次性、数组列表、流式）。示例，实时监听日志事件
$ target/release/client -A 192.168.88.1:8728 -L admin -P "P@ssw0rd" custom --listen "/log/listen"
2022-09-07T21:38:04.659Z INFO [client::custom] New event:
{
    ".id": "*1CB36",
    "time": "21:38:04",
    "message": "user admin logged in from 192.168.88.10 via web",
    "topics": "system,info,account",
}
2022-09-07T21:38:05.559Z INFO [client::custom] New event:
{
    "topics": "firewall,info",
    ".id": "*1CB37",
    "time": "21:38:05",
    "message": "BLOCKED input: in:wan(vlan42) out:(unknown 0), src-mac aa:bb:cc:dd:ee:ff, proto TCP (SYN), 1.2.3.4:42845->4.3.2.1:24032, len 40",
}

免责声明

此软件按原样提供，不提供任何保证。我与 Mikrotik 没有任何关联，也不负责您在使用此软件时可能对路由器造成的任何损害。

依赖关系

约5-12MB
约122K SLoC