mhycy / node-routeros-client

MikroTik RouterOS API client for node.js.

@mhycy/routeros-client

MikroTik RouterOS API client for node.js.

Table of Contents

• @mhycy/routeros-client
  • Table of Contents
  • Install
  • Usage
  • API
    • module.createClient(options)
    • Class: module.CommandBuilder
      • new mooduel.CommandBuilder(command, [callback])
      • CommandBuilder.addAttr(name, value)
      • CommandBuilder.setAttrs(attrs)
      • CommandBuilder.exists(name)
      • CommandBuilder.doesntExists(name)
      • CommandBuilder.equal(name, value)
      • CommandBuilder.lessThan(name, value)
      • CommandBuilder.greaterThan(name, value)
      • CommandBuilder.operation(operation)
    • Class: module.Client
      • new module.Client(options)
      • Event: 'receive'
      • Client.socket
      • Client.close()
      • Client.sendSentences(sentences)
      • Client.sendSentencesAsync(sentences)
      • Client.command(command)
      • Client.login(name, password)
      • Client.setLogger(logger)
    • module.Logger
    • module.Utils

Install

$ npm install @mhycy/routeros-client

Usage

const RouterClient = require('@mhycy/routeros-client');

const USER = "admin";
const PASSWD = "test"

// connect options
const connectOptions = {
  host: '192.168.1.254',
  // port: 8728,
  // encoding: 'gbk',
  debug: true
};

// create client instance
const client = RouterClient.createClient(connectOptions);

// async request
(async function() {
  // login helper function
  await client.login(USER, PASSWD);

  // login use command builder
  await client.command("/login").setAttrs({
    name: USER,
    password: PASSWD
  }).send();
  
  // get interfaces that 'type' attribute equal 'pppoe-out'
  await client.command("/interface/print")
          .equal("type", "pppoe-out")
          .send();

  client.close();
})();

API

module.createClient(options)

Helper for new module.Client(options)

Class: module.CommandBuilder

Command sentences chainable query builder.

Query word see offical wiki: Mikrotik-Wiki-API

Example:

let sentences = new CommandBuilder("/interface/print")
                      .equal('type', 'pppoe-out')
                      .get();
/* sentences
[
  '/interface/print',
  '?type=pppoe-out'
]
*/

new mooduel.CommandBuilder(command, [callback])

• command <string> command word. Example: /interface/print
• callback <Function> use for .get() method. Defualt: (sentences) => { return sentences; }
  • sentences <array> sentences array.

Create a new CommandBuilder object.

Example:

new CommandBuilder('/login', (sentences) => {
  console.log(sentences);
})
.setAttrs({
  name: 'admin',
  password: 'test'
})
.get();

// console.log output
// [
//   '/login',
//   '=name=admin',
//   '=password=test',
// ]

CommandBuilder.addAttr(name, value)

• name <string> attribute name.
• value <string> attributes value.

Add an attribute value to exists attributes object.

Example:

let sentences = new CommandBuilder('/login')
      .setAttr(name, 'admin')
      .setAttr(password, 'test')
      .get();

CommandBuilder.setAttrs(attrs)

• attrs <object> attributes object.

Overwrite attributes object.

Example:

let sentences = new CommandBuilder('/login')
      .setAttrs({
        name: 'admin',
        password: 'test'
      })
      .get();

CommandBuilder.exists(name)

• name <string> property name.

Query word ?name, check property name exists.

CommandBuilder.doesntExists(name)

• name <string> property name.

Query word ?-name, check property name doesn't exists.

CommandBuilder.equal(name, value)

• name <string> property name.
• value <string> attributes value.

Query word ?name=value, check property name has value equal to value.

CommandBuilder.lessThan(name, value)

• name <string> property name.
• value <string> attributes value.

Query word ?<name=value, check property name has value less than value.

CommandBuilder.greaterThan(name, value)

• name <string> property name.
• value <string> attributes value.

Query word ?>name=value, check property name has value greater than value.

CommandBuilder.operation(operation)

• operation <string> operation word < |, &, !, . > .

Operation word see Mikrotik-Wiki-API.

Class: module.Client

new module.Client(options)

• options
  • host <string> Router hostname or ip
  • port <number> api port, doesn't support ssl. Default: 8728.
  • encoding <string> sentences enc/dec encoding, it equal windows environment encode. (MikroTik WinBox used it) Default: gbk.
  • debug <boolean> if true print debug infomation to console. Default: false.

  Create a new Client object.

  Event: 'receive'

  • <object> sentences decode object.

  // '!done'
  {
    status: true
  }
  
  // '!re'
  // ......
  // '!re'
  // ......
  {
    'status': true,
    'replies': [
      {
        '.id': '*9',
        name: 'pppoe-out1',
        type: 'pppoe-out',
        'link-downs': '0',
        'rx-byte': '0',
        'tx-byte': '0',
        'rx-packet': '0',
        'tx-packet': '0',
        'rx-drop': '0',
        'tx-drop': '0',
        'tx-queue-drop': '0',
        'rx-error': '0',
        'tx-error': '0',
        'fp-rx-byte': '0',
        'fp-tx-byte': '0',
        'fp-rx-packet': '0',
        'fp-tx-packet': '0',
        running: 'false',
        'tx-queue-drop': '0',
        'rx-error': '0',
        'tx-error': '0',
        'fp-rx-byte': '0',
        'fp-tx-byte': '0',
        'fp-rx-packet': '0',
        'fp-tx-packet': '0',
        running: 'true',
        disabled: 'false',
        comment: 'ChinaNet 500M'
      }
    ]
  }
  
  // '!trap'
  // '=message=invalid user name or password (6)'
  {
    status: false,
    message: 'invalid user name or password (6)'
  }
  
  // '!fatal',
  // 'not logged in',
  {
    status: false,
    message: 'not logged in'
  }

  Client.socket

  <net.Socket> instance.

  Client.close()

  Close Client.socket. Call <net.Socket.end()> to close.

  Client.sendSentences(sentences)

  • sentences <array> sentences array.

  Direct write a sentences, you need set listener to listen Event::receive by your self.

  Client.sendSentencesAsync(sentences)

  • sentences <array> sentences array.

  Return: <Promise>

  Promise resolve an object. see: Usage

  Client.command(command)

  • command <string> command words. Example: /login or /interface/print

  Return: <CommandBuilder>

  Return chainable query builder. CommandBuilder.get() method will send sentences request. (Use: Client.sendSentencesSync())

  Client.login(name, password)

  • name <string> user name.
  • password <string> user password.

  Return: <Promise>

  Promise resolve an object. see: Usage

  Client.setLogger(logger)

  • logger <object> new logger instance.

  Logger instance need implementing some method. see src/logger.js source code.

  module.Logger

  Module logger, export api see src/logger.js source code.

  module.Utils

  Module utilities, export api see src/utils.js source code.