1MikroTik::API(3)      User Contributed Perl Documentation     MikroTik::API(3)
2
3
4

NAME

6       MikroTik::API - Client to MikroTik RouterOS API
7

VERSION

9       Version 2.0.1
10
11       CAUTION: Dependencies change with version 2.0.0. MikroTik::API now
12       relies on Moo instead of Moose. Please be sure, dependencies are met
13       before upgrading.
14

SYNOPSIS

16           use MikroTik::API;
17
18           my $api = MikroTik::API->new({
19               host => 'mikrotik.example.org',
20               username => 'whoami',
21               password => 'SECRET',
22               use_ssl => 1,
23           });
24
25           my ( $ret_get_identity, @aoh_identity ) = $api->query( '/system/identity/print', {}, {} );
26           print "Name of router: $aoh_identity[0]->{name}\n";
27
28           $api->logout();
29

DESCRIPTION

PUBLIC METHODS

32   new( \%config )
33           my $api = MikroTik::API->new({
34               host => 'mikrotik.example.org',
35               username => 'whoami',
36               password => 'SECRET',
37               autoconnect => 1, # optional (set to 0 if you do not want to connect during construction, default: 1)
38               use_ssl => 1, # optional (0 for non ssl / 1 for ssl)
39               port => 8729, # optonal (needed if you use another port then 8728 for non-ssl or 8729 for ssl)
40               debug => 0, # optional (set beween 0 (none) and 5 (most) for debug messages)
41               timeout => 3, # optional (timeout after 3 seconds during connect)
42               probe_before_talk => 3, # optional (probe connection before each actual command)
43               reconnect_after_failed_probe => 1, # optional (reconnect if probe failed)
44
45           });
46
47   $api->connect()
48       Connect happens on construction if you provide host address
49
50           my $api = MikroTik::API->new();
51
52           $api->set_host('mikrotik.example.org');
53           $api->set_port(1234);
54           $api->set_use_ssl(1);
55
56           $api->connect();
57
58   $api->login()
59       Connect happens on construction if you provide host address, username
60       and password
61
62           my $api = MikroTik::API->new({ host => 'mikrotik.example.org' });
63
64           $api->set_username('whoami');
65           $api->set_password('SECRET');
66
67           $api->login();
68
69   $api->logout()
70           $api->logout();
71
72   $api->cmd( $command, \%attributes )
73           # Set with no key required
74           # /system identity set name=MyNewMikroTik
75           my $returnvalue = $api->cmd( '/system/identity/set', { 'name' => 'MyNewMikroTik' } );
76           print "Name set\n" if ($returnvalue < 2);
77
78           # Set keyed on the name "local"
79           # /interface bridge set local fast-forward=no
80           my $returnvalue = $api->cmd( '/interface/bridge/set', { '.id' => 'local', 'fast-forward' => 'no' } );
81           print "Bridge fast-forward turned off\n" if ($returnvalue < 2);
82
83           # Set keyed on internal key
84           # /interface bridge set *cc fast-forward=no
85           my $returnvalue = $api->cmd( '/interface/bridge/set', { '.id' => '*cc', 'fast-forward' => 'no' } );
86           print "Bridge fast-forward turned off\n" if ($returnvalue < 2);
87
88           # Reset a value
89           # /routing bgp peer set testpeer !keepalive-time
90           my $returnvalue = $api->cmd( '/routing/bgp/peer/set', { '.id' => 'testpeer', 'keepalive-time' => undef } );
91           print "Reset keepalive-time on testpeer\n" if ($returnvalue < 2);
92
93   $api->query( $command, \%attributes, \%conditions )
94           # Get all interfaces of type ether
95           my ( $ret_interface_print, @interfaces ) = $api->query('/interface/print', { '.proplist' => '.id,name' }, { type => 'ether' } );
96           foreach my $interface ( @interfaces ) {
97               print "$interface->{name}\n";
98           }
99
100           # get all default routes that don't have the dynamic attribute
101           my ( $ret_route_print, @routes ) = $api->query('/ip/route', { '.proplist' => '.id,dst-address' }, { 'dst-address' => '0.0.0.0/0', 'dynamic'=>undef } );
102           foreach my $route ( @routes ) {
103               print "$route->{'dst-address'}\n";
104           }
105
106           # get all default routes that don't have the dynamic attribute (alternate using array ref)
107           my ( $ret_route_print, @routes ) = $api->query('/ip/route', { '.proplist' => '.id,dst-address' }, [ 'dst-address=0.0.0.0/0', '-dynamic' ] );
108           foreach my $route ( @routes ) {
109               print "$route->{'dst-address'}\n";
110           }
111
112           # get all default routes along with those with the dynamic attribute (note 'or' operator as last arg)
113           my ( $ret_route_print, @routes ) = $api->query('/ip/route', { '.proplist' => '.id,dst-address' }, [ 'dst-address=0.0.0.0/0', 'dynamic', '#|' ] );
114           foreach my $route ( @routes ) {
115               print "$route->{'dst-address'}\n";
116           }
117
118   $api->get_by_key( $command, $keycolumn )
119           my %interface = $api->get_by_key('/interface/ethernet/print', 'name' );
120           print "$interface{'ether1'}->{running}\n";
121

ACCESSORS

123   $api->get_host(), $api->set_host( $hostname )
124   $api->get_port(), $api->set_port( $portnumber )
125   $api->get_username(), $api->set_username( $username )
126   $api->get_password(), $api->set_password( $password )
127   $api->get_use_ssl(), $api->set_use_ssl( $zero_or_one )
128   $api->get_ssl_verify(), $api->set_ssl_verify( $zero_or_one )
129   $api->get_new_auth_method(), $api->set_new_auth_method( $zero_or_one )
130       DEPRECATED: does not have any effect any longer. Login looks up wether
131       new method is possible and falls back to old method. This parameter
132       will be removed in future.  Auth method changed in RouterOS v6.43+
133       (https://wiki.mikrotik.com/wiki/Manual:API#Initial_login) and reduces
134       login by one call but sends password in plaintext.
135
136   $api->get_autoconnect(), $api->set_autoconnect( $zero_or_one )
137   $api->get_socket(), $api->set_socket( $io_socket )
138       If you need to use an existing socket for the API connection.
139
140           my $socket = IO::Socket::INET->new();
141           $api->set_socket( $socket );
142
143   $api->get_debug(), $api->set_debug( $int )
144           $api->set_debug(0); # no debug
145           $api->set_debug(5); # verbose debug to STDOUT
146
147   $api->get_timeout(), $api->set_timeout( $seconds )
148       Abort connect after $seconds of no reply from MikroTik. This _will not_
149       affect lost connections. Use probe_before_talk for this.
150
151   $api->get_probe_before_talk(), $api->set_probe_before_talk( $seconds )
152       Use this attribute to enable a test command with timeout to ensure that
153       the connection is still alive before sending the actual command.  This
154       is very useful for long lasting connections that may get disconnected
155       while idling. A broken connection will not be recognized otherwise,
156       because the socket still exists and the command will last forever. The
157       advantage over a common timeout for all commands is that long lasting
158       commands are still possible. Set this to 0 if you use many consequent
159       commands and reenable it after completion.
160
161           $api->set_probe_before_talk(0); # no probing of connection before sending command and read reply
162           $api->set_probe_before_talk(5); # a simple command will be sent and after 5 seconds of no reply, the connection is assumed as broken
163
164   $api->get_reconnect_after_failed_probe(),
165       $api->set_reconnect_after_failed_probe( $zero_or_one )
166       If connection is recognized as broken then either reconnect or die
167       otherwise.
168

SEMI-PUBLIC METHODS

170       can be useful for advanced users, but too complex for daily use
171
172   $api->talk( \@sentence )
173   $api->raw_talk( \@sentence )

ABOUT

175   Contributors
176       Object-Orientated Rebuild of prior contributions, based on:
177
178       •   initial release from cheesegrits in MikroTik forum:
179           http://forum.mikrotik.com/viewtopic.php?p=108530#p108530
180
181       •   added "timeout parameter" and fixes by elcamlost:
182           https://github.com/elcamlost/mikrotik-perl-api/commit/10e5da1fd0ccb4a249ed3047c1d22c97251f666e
183
184       •   SSL support by akschu:
185           https://github.com/akschu/MikroTikPerl/commit/9b689a7d7511a1639ffa2118c8e549b5cec1290d
186
187       •   upgrade to v2.0.0 by Steffen Winkler
188
189   Design decisions
190       •   Use of Moo for OO
191
192       •   higher compilation time of Moo based lib negligible because of slow
193           I/O operations
194
195       •   Change from Moose to Moo with version 2.0.0 because of XS
196           dependencies of Moose
197

AUTHOR

199       Martin Gojowsky, "martin at gojowsky.de"
200

BUGS

202       Please report any bugs or feature requests to "bug-mikrotik-api at
203       rt.cpan.org", or through the web interface at
204       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MikroTik-API>.  I will
205       be notified, and then you'll automatically be notified of progress on
206       your bug as I make changes.
207
208   Known issues
209       •   Quite high compile time because of using Moo. Use of a persistent
210           running framework recommended.
211

TODO

213       •   Add a parameter talk_timeout as an alternative for
214           probe_before_talk that enables an actual timeout for each command.
215

SUPPORT

217       You can find documentation for this module with the perldoc command.
218
219           perldoc MikroTik::API
220
221       You can also look for information at:
222
223       •   RT: CPAN's request tracker (report bugs here)
224
225           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MikroTik-API>
226
227       •   AnnoCPAN: Annotated CPAN documentation
228
229           <http://annocpan.org/dist/MikroTik-API>
230
231       •   CPAN Ratings
232
233           <http://cpanratings.perl.org/d/MikroTik-API>
234
235       •   Search CPAN
236
237           <http://search.cpan.org/dist/MikroTik-API/>
238

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

241       Copyright 2015 Martin Gojowsky.
242
243       This program is distributed under the MIT (X11) License:
244       <http://www.opensource.org/licenses/mit-license.php>
245
246       Permission is hereby granted, free of charge, to any person obtaining a
247       copy of this software and associated documentation files (the
248       "Software"), to deal in the Software without restriction, including
249       without limitation the rights to use, copy, modify, merge, publish,
250       distribute, sublicense, and/or sell copies of the Software, and to
251       permit persons to whom the Software is furnished to do so, subject to
252       the following conditions:
253
254       The above copyright notice and this permission notice shall be included
255       in all copies or substantial portions of the Software.
256
257       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
258       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
259       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
260       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
261       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
262       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
263       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
264
265
266
267perl v5.36.0                      2023-01-20                  MikroTik::API(3)