NAME

API::MikroTik - Non-blocking interface to MikroTik API

SYNOPSIS

  my $api = API::MikroTik->new();

  # Blocking
  my $list = $api->command(
      '/interface/print',
      {'.proplist' => '.id,name,type'},
      {type        => ['ipip-tunnel', 'gre-tunnel'], running => 'true'}
  );
  if (my $err = $api->error) { die "$err\n" }
  printf "%s: %s\n", $_->{name}, $_->{type} for @$list;


  # Non-blocking
  my $tag = $api->command(
      '/system/resource/print',
      {'.proplist' => 'board-name,version,uptime'} => sub {
          my ($api, $err, $list) = @_;
          ...;
      }
  );
  Mojo::IOLoop->start();

  # Subscribe
  $tag = $api->subscribe(
      '/interface/listen' => sub {
          my ($api, $err, $el) = @_;
          ...;
      }
  );
  Mojo::IOLoop->timer(3 => sub { $api->cancel($tag) });
  Mojo::IOLoop->start();

  # Errors handling
  $api->command(
      '/random/command' => sub {
          my ($api, $err, $list) = @_;

          if ($err) {
              warn "Error: $err, category: " . $list->[0]{category};
              return;
          }

          ...;
      }
  );
  Mojo::IOLoop->start();

  # Promises
  $api->cmd_p('/interface/print')
      ->then(sub { my $res = shift }, sub { my ($err, $attr) = @_ })
      ->finally(sub { Mojo::IOLoop->stop() });
  Mojo::IOLoop->start();

DESCRIPTION

Both blocking and non-blocking interface to a MikroTik API service. With queries, command subscriptions and Promises/A+ (courtesy of an I/O loop). Based on Mojo::IOLoop and would work alongside EV.

ATTRIBUTES

API::MikroTik implements the following attributes.

error

  my $last_error = $api->error;

Keeps an error from last "command" call. Empty string on successful commands.

host

  my $host = $api->host;
  $api     = $api->host('border-gw.local');

Host name or IP address to connect to. Defaults to 192.168.88.1.

ioloop

  my $loop = $api->ioloop;
  $api     = $api->loop(Mojo::IOLoop->new());

Event loop object to use for blocking operations, defaults to Mojo::IOLoop object.

password

  my $pass = $api->password;
  $api     = $api->password('secret');

Password for authentication. Empty string by default.

port

  my $port = $api->port;
  $api     = $api->port(8000);

API service port for connection. Defaults to 8729 and 8728 for TLS and clear text connections respectively.

timeout

  my $timeout = $api->timeout;
  $api        = $api->timeout(15);

Timeout in seconds for sending request and receiving response before command will be canceled. Default is 10 seconds.

tls

  my $tls = $api->tls;
  $api    = $api->tls(1);

Use TLS for connection. Enabled by default.

user

  my $user = $api->user;
  $api     = $api->user('admin');

User name for authentication purposes. Defaults to admin.

METHODS

cancel

  # subscribe to a command output
  my $tag = $api->subscribe('/ping', {address => '127.0.0.1'} => sub {...});

  # cancel command after 10 seconds
  Mojo::IOLoop->timer(10 => sub { $api->cancel($tag) });

  # or with callback
  $api->cancel($tag => sub {...});

Cancels background commands. Can accept a callback as last argument.

cmd

  my $list = $api->cmd('/interface/print');

An alias for "command".

cmd_p

  my $promise = $api->cmd_p('/interface/print');

An alias for "command_p".

command

  my $command = '/interface/print';
  my $attr    = {'.proplist' => '.id,name,type'};
  my $query   = {type => ['ipip-tunnel', 'gre-tunnel'], running => 'true'};

  my $list = $api->command($command, $attr, $query);
  die $api->error if $api->error;
  for (@$list) {...}

  $api->command('/user/set', {'.id' => 'admin', comment => 'System admin'});

  # Non-blocking
  $api->command('/ip/address/print' => sub {
      my ($api, $err, $list) = @_;

      return if $err;

      for (@$list) {...}
  });

  # Omit attributes
  $api->command('/user/print', undef, {name => 'admin'} => sub {...});

  # Errors handling
  $list = $api->command('/random/command');
  if (my $err = $api->error) {
      die "Error: $err, category: " . $list->[0]{category};
  }

Executes a command on a remote host and returns Mojo::Collection with hashrefs containing elements returned by a host. You can append a callback for non-blocking calls.

In a case of error it may return extra attributes to !trap or !fatal API replies in addition to error messages in an "error" attribute or an $err argument. You should never rely on defines of the result to catch errors.

For a query syntax refer to API::MikroTik::Query.

command_p

  my $promise = $api->command_p('/interface/print');

  $promise->then(
  sub {
      my $res = shift;
      ...
  })->catch(sub {
      my ($err, $attr) = @_;
  });

Same as "command", but always performs requests non-blocking and returns a Mojo::Promise object instead of accepting a callback. Mojolicious v7.54+ is required for promises functionality.

subscribe

  my $tag = $api->subscribe('/ping',
      {address => '127.0.0.1'} => sub {
        my ($api, $err, $res) = @_;
      });

  Mojo::IOLoop->timer(
      3 => sub { $api->cancel($tag) }
  );

Subscribe to an output of commands with continuous responses such as listen or ping. Should be terminated with "cancel".

DEBUGGING

You can set the API_MIKROTIK_DEBUG environment variable to get some debug output printed to stderr.

Also, you can change connection timeout with the API_MIKROTIK_CONNTIMEOUT variable.

COPYRIGHT AND LICENSE

Andre Parker, 2017-2018.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

SEE ALSO

https://wiki.mikrotik.com/wiki/Manual:API, https://github.com/anparker/api-mikrotik

cpanm API::MikroTik

perl -MCPAN -e shell
install API::MikroTik