Manual:API: Difference between revisions

From MikroTik Wiki
Jump to navigation Jump to search
(Query documentation)
 
(142 intermediate revisions by 7 users not shown)
Line 1: Line 1:
This document describes the operation of MikroTik RouterOS API for RouterOS3. The API (application programming interface) is a way to create your own versions of Winbox. This guide will help you make simplified, or translated control applications for RouterOS v3.
==Summary==


Application Programmable Interface (API) allows users to create custom software solutions to communicate with RouterOS to gather information, adjust configuration and manage router. API closely follows syntax from command line interface (CLI). It can be used to create translated or custom configuration tools to aid ease of use running and managing routers with RouterOS.


== Enabling and Connecting ==
To use API RouterOS version 3.x or newer is required.


* Default API port is 8728. By default API is disabled
By default API uses port #''8728'' and service is enabled. More on service management see in corresponding [[Manual:IP/Services | manual section]]. Corresponding service name is '''api'''
* Enable API
  /ip service enable api
* Now you can initiate TCP connection to the API port of the router


== Protocol ==
== Protocol ==


* Protocol stream is formatted as a sequence of words.
Communication with router is done by sending sentences to the router and receiving one or more sentences in return. Sentence is sequence of words terminated by zero length word. Word is part of sentence encoded in certain way - encoded length and data. Communication happen by sending sentences to the router and receiving replies to sent sentences. Each sentence sent to router using API should contain command as a first word followed by words in no particular order, end of sentence is marked by zero length word. When router receives full sentence (command word, no or more attribute words and zero length word) it is evaluated and executed, then reply is formed and returned.
* Each word is encoded as length, followed by that many bytes of content.
 
* Words are grouped into sentences. End of sentence is terminated by zero length word.
===API words===
* Length is encoded as follows:
 
{| border="1"
Words are part of sentence. Each word has to be encoded in certain way - length of the word followed by word content. Length of the word should be given as count of bytes that are going to be sent.
!Value of length !! Number of bytes !! Encoding
 
Length of the word is encoded as follows:
 
{| cellpadding="2"  
!width="200px" style="background:#cccccc; border-bottom:1px solid gray;"| Value of length  
!width="100px" style="background:#cccccc; border-bottom:1px solid gray;"|# of bytes
!width="250px" style="background:#cccccc; border-bottom:1px solid gray;"|Encoding
|-  
|-  
| 0 <= len <= 0x7F
|style="border-bottom:1px solid gray;" valign="top"| 0 <= len <= 0x7F
| 1
|style="border-bottom:1px solid gray;" valign="top"| 1
| len, lowest byte
|style="border-bottom:1px solid gray;" valign="top"| len, lowest byte
|-   
|-   
| 0x80 <= len <= 0x3FFF
|style="border-bottom:1px solid gray;" valign="top"| 0x80 <= len <= 0x3FFF
| 2
|style="border-bottom:1px solid gray;" valign="top"| 2
| <nowiki>len | 0x8000, two lower bytes</nowiki>
|style="border-bottom:1px solid gray;" valign="top"| <nowiki>len | 0x8000, two lower bytes</nowiki>
|-
|-
| 0x4000 <= len <= 0x1FFFFF
|style="border-bottom:1px solid gray;" valign="top"| 0x4000 <= len <= 0x1FFFFF
| 3
|style="border-bottom:1px solid gray;" valign="top"| 3
| <nowiki>len | 0xC00000, three lower bytes</nowiki>
|style="border-bottom:1px solid gray;" valign="top"| <nowiki>len | 0xC00000, three lower bytes</nowiki>
|-
|-
| 0x200000 <= len <= 0xFFFFFFF
|style="border-bottom:1px solid gray;" valign="top"| 0x200000 <= len <= 0xFFFFFFF
| 4
|style="border-bottom:1px solid gray;" valign="top"| 4
| <nowiki>len | 0xE0000000</nowiki>
|style="border-bottom:1px solid gray;" valign="top"| <nowiki>len | 0xE0000000</nowiki>
|-
| len >= 0x10000000
| 5
| 0xF0 and len as four bytes
|-
|-
|style="border-bottom:1px solid gray;" valign="top"| len >= 0x10000000
|style="border-bottom:1px solid gray;" valign="top"| 5
|style="border-bottom:1px solid gray;" valign="top"| 0xF0 and len as four bytes
|}
|}
* Although this scheme allows encoding of length up to '''0x7FFFFFFFF''', only four byte length is supported.
* Bytes of '''len''' are sent most significant first (network order).
* If first byte of word is '''>= 0xF8''', then it is a reserved control byte. After receiving unknown control byte API client cannot proceed, because it cannot know how to interpret following bytes.
* Currently control bytes are not used.


== Short description of API sentences ==


* Empty sentences are ignored.
* Each word is encoded as length, followed by that many bytes of content;
* Sentences are processed after receiving terminating zero length word.
* Words are grouped into sentences. End of sentence is terminated by zero length word;
* There is a limit on number and size of sentences client can send before it has logged in.
* Scheme allows encoding of length up to '''0x7FFFFFFFFF''', only four byte length is supported;
* Commands
* Bytes of '''len''' are sent most significant first (network order);
** First word is name of command. Examples:
* If first byte of word is '''>= 0xF8''', then it is a reserved control byte. After receiving unknown control byte API client cannot proceed, because it cannot know how to interpret following bytes;
<pre>
* Currently control bytes are not used;
 
In general ''words'' can be described like this <<''encoded word length''><''word content''>>. ''Word content'' can be separated in 5 parts: ''[[Manual:API#Command_word| command word]]'', ''[[Manual:API#Attribute_word |attribute word]]'', ''[[Manual:API#API_attribute_word|API attribute word]]''. ''[[Manual:API#Query_word|query word]]'' and ''[[Manual:API#Reply_word|reply word]]''
 
====Command word====
First word in sentence has to be command followed by attribute words and zero length word or terminating word. Name of command word should begin with '/'. Names of commands closely follow CLI, with spaces replaced with '/'. There are commands that are specific to API;
 
Command word structure in strict order:
* encoded length
* content prefix ''/''
* CLI converted command
 
 
API specific commands:
login
cancel
 
Command word content examples:
  /login
  /login
/ip/address/getall
 
  /user/active/listen
  /user/active/listen
  /interface/vlan/remove
  /interface/vlan/remove
  /system/reboot
  /system/reboot
</pre>
 
** Names of commands closely follow console, with spaces replaced by '/'. There are commands that are specific to API, like <tt>getall</tt> or <tt>login</tt>.
====Attribute word====
** Name of command should begin with '/'.
Each ''command word'' has its own list of ''attribute words'' depending on content.
** Next, command arguments can be specified. Examples:
 
''Atribute word'' structure consists of 5 parts in this order:
* encoded length
* content prefix equals sign - ''=''
* attribute name
* separating equals sign - ''=''
* value of attribute if there is one. It is possible that attribute does not have a value
 
{{Note|Value can hold multiple ''equal'' signs in the value of ''attribute word'' since the way word is encoded}}
 
{{Note| Value can be empty}}
 
 
Examples without encoded length prefix:
  =address=10.0.0.1
  =address=10.0.0.1
  =name=iu=c3Eeg
  =name=iu=c3Eeg
  =disable-running-check=yes
  =disable-running-check=yes
** Command argument should begin with '=' followed by name of argument, followed by another '=', followed by value of argument.
** There are API specific arguments, such as <tt>.id</tt>. Names of API specific arguments begin with dot.
** Argument value can be empty and can contain '='.
** Command sentence can have parameters that are specific to and processed by API protocol. These parameters should begin with '.' followed by name of parameter, followed by '=', followed by value of parameter.
** Currently the only such parameter is 'tag'.
** Order of arguments and API parameters is not important and cannot be relied on
** First word of reply begins with '!'.
** Each command generates at least one reply (if connection does not get terminated).
** Last reply for every command is reply that has first word <tt>!done</tt>.
** Errors and exceptional conditions begin with <tt>!trap</tt>.
** Data replies begin with <tt>!re</tt>


{{Warning | Order of attribute words and API parameters is not important and should not be relied on}}
====API attribute word====
API attribute word structure is in strict  order:
* encoded length
* content prefix with dot ''.''
*attribute name
*name postfixed with equals ''=''sign
*attribute value
Currently the only such API attribute is ''tag''.
{{Note| If sentence contain ''API attribute word '' tag then each returned sentence in reply from router to that tagged sentence will be tagged with same tag.}}
====Query word====
Senteces can have additional query paramteres that restrict their scope. They are explained in detail [[API#Queries|in separate section]].
Example of sentence using query word attributes:
/interface/print
?type=ether
?type=vlan
?#|!
* Query words begin with '?'.
* Currently only ''print'' command handles query words.
{{Warning| Order of query words is significant}}
====Reply word====
It is sent only by the router. It is only sent in response to full sentence send by the client.
* First word of reply begins with '!';
* Each sentence sent generates at least one reply (if connection does not get terminated);
* Last reply for every sentence is reply that has first word <tt>!done</tt>;
* Errors and exceptional conditions begin with <tt>!trap</tt>;
* Data replies begin with <tt>!re</tt>
* If API connection is closed, RouterOS sends <tt>!fatal</tt> with reason as reply and then closes the connection;
=== API sentences ===
API sentence is main object of communication using API.
* Empty sentences are ignored.
* Sentence is processed after receiving zero length word.
* There is a limit on number and size of sentences client can send before it has logged in.
* Order of attribute words should not be relied on. As order and count is changeable by ''.proplist'' attribute.
* Sentence structure is as follows:
** First word should contain ''command word'';
** Should contain ''zero length word'' to terminate the sentence;
** Can contain none or several ''attribute words''. There is no particular order at what attribute words has to be sent in the sentence, order is not important for ''attribute words'';
** Can contain none or several ''query words''. Order of ''query words'' in the sentence is important.
{{Note| ''Zero length word'' terminates the sentence. If it is not provided router will not start to evaluate sent words and will consider all the input as part of the same sentence.}}


== Initial login ==
== Initial login ==


Login method pre-v6.43:
<tt>
<tt>
{| style="width: 500px"
{| style="width: 500px"
Line 94: Line 172:
|}
|}
</tt>
</tt>
{{Warning| this login method is deprecated and no longer supported in versions above 6.45.1.}}
{{Note| that each command and response ends with an empty word.}}


* First, clients sends <tt>/login</tt> command.
* First, clients sends <tt>/login</tt> command.
* Note that each command and response ends with an empty word.
* Reply contains <tt>=ret=''challenge''</tt> argument.
* Reply contains <tt>=ret=''challenge''</tt> argument.
* Client sends second <tt>/login</tt> command, with <tt>=name=''username''</tt> and <tt>=response=''response''</tt>.
* Client sends second <tt>/login</tt> command, with <tt>=name=''username''</tt> and <tt>=response=''response''</tt>.
* In case of error, reply contains <tt>=ret=''error message''</tt>.
* In case of error, reply contains <tt>=ret=''error message''</tt>.
* In case of successful login client can start to issue commands.
Login method post-v6.43:
<tt>
{| style="width: 500px"
{{apic|/login}}
{{apic|1==name=admin}}
{{apic|1==password=}}
{{apic|}}
{{apis|!done}}
{{apis|}}
|}
</tt>
* Now client sends username and password in first message.
* Password is sent in plain text.
* in case of error, reply contains <tt>=message=''error message''</tt>.
* In case of successful login client can start to issue commands.
* In case of successful login client can start to issue commands.


Line 128: Line 227:
* <tt>print</tt>
* <tt>print</tt>
** API <tt>print</tt> command differs from the console counterpart in the following ways:
** API <tt>print</tt> command differs from the console counterpart in the following ways:
*** arguments that modify list of returned properties (<tt>detail</tt>, <tt>breif</tt>, ...) have no effect in the API.
*** <tt>where</tt> argument is not supported. Items can be filtered using query words (see below).
*** <tt>where</tt> argument is not supported. Items can be filtered using query words (see below).
*** <tt>.proplist</tt> argument is a comma separated list of property names that should be included for the returned items.
*** <tt>.proplist</tt> argument is a comma separated list of property names that should be included for the returned items.
Line 134: Line 232:
**** order of returned properties is not defined.
**** order of returned properties is not defined.
**** if list contains duplicate entries, handling of such entries is not defined.
**** if list contains duplicate entries, handling of such entries is not defined.
**** if propery is present in .proplist, but absent from the item, then that item does not have this property value (?name will evaluate to false for that item).
**** if propery is present in <tt>.proplist</tt>, but absent from the item, then that item does not have this property value (?name will evaluate to false for that item).
**** if <tt>.proplist</tt> is absent, all possible properties are included, even those that have slow access time (such as file contents and perfomance counters).
**** if <tt>.proplist</tt> is absent, all properties are included as requested by print command, even those that have slow access time (such as file contents and perfomance counters). Thus use of <tt>.proplist</tt> is encouraged. Omission of <tt>.proplist</tt> may have high perfomance penalty if =detail= argument is set.


=== Queries ===
=== Queries ===


<tt>print</tt> command accepts query words that limit set of returned items. This feature appeared in the 3.21 version.
<tt>print</tt> command accepts query words that limit set of returned sentences. This feature is available since RouterOS 3.21.
* Query words begin with '?'
* Query words begin with '?'.
{|
* Order of query words is significant. Query is evaluated starting from the first word.
* Query is evaluated for each item in the list. If query succeeds, item is processed, if query fails, item is ignored.
* Query is evaluated using a stack of boolean values. Initially stack contains infinite amount of 'true' values. At the end of evaluation, if stack contains at least one 'false' value, query fails.
* Query words operate according to the following rules:
{| cellpadding="2"
!width="300px" style="background:#cccccc; border-bottom:1px solid gray;"| Query
!width="450px" style="background:#cccccc; border-bottom:1px solid gray;"| Desciption
|-
|-
| <tt>?name</tt>
|style="border-bottom:1px solid gray;" valign="top"| '''?name'''
| succeeds for items that have value of property <tt>name</tt>
|style="border-bottom:1px solid gray;" valign="top"|pushes 'true' if item has value of property ''name'', 'false' if it does not.
|-
|-
| <tt>?-name</tt>
|style="border-bottom:1px solid gray;" valign="top"|'''?-name'''
| succeeds for items that do not have value of property <tt>name</tt>
|style="border-bottom:1px solid gray;" valign="top"| pushes 'true' if item does not have value of property ''name'', 'false' otherwise.
|-
|-
| <tt>?name=''x''</tt><br><tt>?=name=''x''</tt>
|style="border-bottom:1px solid gray;" valign="top"|'''?''name''=''x'''''<br>'''?=''name''=''x'''''
| succeeds for items that have value of property <tt>name</tt> equal to ''x''
|style="border-bottom:1px solid gray;" valign="top"| pushes 'true' if property ''name'' has value equal to ''x'', 'false' otherwise.
|-
|-
| <tt>?<name=''x''</tt>
|style="border-bottom:1px solid gray;" valign="top"|'''?<name=''x'''''
| succeeds for items that have value of property <tt>name</tt> less than ''x''
|style="border-bottom:1px solid gray;" valign="top"| pushes 'true' if property ''name'' has value less than ''x'', 'false' otherwise.
|-
|-
| <tt>?>name=''x''</tt>
|style="border-bottom:1px solid gray;" valign="top"|'''?>name=''x'''''
| succeeds for items that have value of property <tt>name</tt> greater than ''x''
|style="border-bottom:1px solid gray;" valign="top"| pushes 'true' if property ''name'' has value greater than ''x'', 'false' otherwise.
|-
|-
| <tt>?#''rule''</tt>
|style="border-bottom:1px solid gray;" valign="top"|'''?#''operations'''''
| specifies result transformation rule. By default no transformation is done. Does not produce result.
|style="border-bottom:1px solid gray;" valign="top"| applies operations to the values in the stack.
* operation string is evaluated left to right.
* sequence of decimal digits followed by any other character or end of word is interpreted as a stack index. top value has index 0.
* index that is followed by a character pushes copy of value at that index.
* index that is followed by the end of word replaces all values with the value at that index.
* '''<tt>!</tt> ''' character replaces top value with the opposite.
* '''<tt>&</tt>''' pops two values and pushes result of logical 'and' operation.
* '''<tt>|</tt>''' pops two values and pushes result of logical 'or' operation.
* '''<tt>.</tt>''' after an index does nothing.
* '''<tt>.</tt>''' after another character pushes copy of top value.
|}
 
 
{{Warning | Regular expressions are not supported in API, so do not try to send query with '''~''' symbol}}
 
Examples:
* Get all ethernet and VLAN interfaces:
/interface/print
?type=ether
?type=vlan
?#|
* Get all routes that have non-empty comment:
/ip/route/print
?>comment=
 
* [http://forum.mikrotik.com/viewtopic.php?f=2&t=72298 Forum thread with detailed explanation of use of queries]
 
=== OID ===
 
<tt>print</tt> command can return OID values for properties that are available in SNMP. This feature appeared in 3.23 version.
 
In console, OID values can be seen by running 'print oid' command. In API, these properties have name that ends with ".oid", and can be retrieved by adding their name to the value of '.proplist'. An example:
 
<tt>
{| style="width: 500px"
{{apic|/system/resource/print}}
{{apic|1==.proplist=uptime,cpu-load,uptime.oid,cpu-load.oid}}
{{apic|}}
{{apis|!re}}
{{apis|1==uptime=01:22:53}}
{{apis|1==cpu-load=0}}
{{apis|1==uptime.oid=.1.3.6.1.2.1.1.3.0}}
{{apis|1==cpu-load.oid=.1.3.6.1.2.1.25.3.3.1.2.1}}
{{apis|}}
{{apis|!done}}
{{apis|}}
|}
|}
</tt>
===!trap===
When for some reason API sentence fails trap is sent in return accompanied with '''message''' attribute and on some occasions '''category''' argument.


For every item that is considered by <tt>print</tt> command, query is evaluated, and item is reported
====message====
only when result of the evaluation is succesful.
When API sentence fails some generic message or message from used internal process is return to give more details about failure
Each query word except '?#' produces either 'true' value (on success) or 'false' value.
Query is succesful if there are no results with value 'false'.


* Transformation rule is evaluated left to right.
<<< /ip/address/add
* During evaluation, current list of result values is numbered from last to first, starting from 0.
<<< =address=192.168.88.1
* Sequence of decimal digits followed by any other character or end of word is interpreted as an index of return value.
<<< =interface=asdf
* index that is followed by a character adds value at that index as the last value (new index 0)
<<<
* index that is followed by the end of word replaces all values with the value at that index.
>>> !trap
* '!' character replaces last value with the opposite
>>> =category=1
* '&' replaces two last values with 'true' if both of them are 'true', and with 'false' otherwise
>>> =message=input does not match any value of interface
* '|' replaces two last values with 'false' if both of them are 'false', and with 'true' otherwise
 
* '.' after index does nothing
====category====
* '.' after another character duplicates the last value
if it is a general error, it is categorized and error category is returned. possible values for this attribute are
*0 - missing item or command
*1 - argument value failure
*2 - execution of command interrupted
*3 - scripting related failure
*4 - general failure
*5 - API related failure
*6 - TTY related failure
*7 - value generated with :return command


== Command examples ==
== Command examples ==
Line 350: Line 508:
== Example client ==
== Example client ==


* this is simple API client in Python
* this is simple API client in Python2
* example for [[Manual:API_Python3|Python3]]
* usage: api.py ''ip-address'' ''username'' ''password''
* usage: api.py ''ip-address'' ''username'' ''password''
* after that type words from keyboard, terminating them with newline
* after that type words from keyboard, terminating them with newline
Line 358: Line 517:
#!/usr/bin/python
#!/usr/bin/python


import sys, posix, time, md5, binascii, socket, select
import sys, posix, time, md5, binascii, socket, select, ssl


class ApiRos:
class ApiRos:
Line 365: Line 524:
         self.sk = sk
         self.sk = sk
         self.currenttag = 0
         self.currenttag = 0
       
 
     def login(self, username, pwd):
     def login(self, username, pwd):
         for repl, attrs in self.talk(["/login"]):
 
         for repl, attrs in self.talk(["/login", "=name=" + username,
                                      "=password=" + pwd]):
          if repl == '!trap':
            return False
          elif '=ret' in attrs.keys():
        #for repl, attrs in self.talk(["/login"]):
             chal = binascii.unhexlify(attrs['=ret'])
             chal = binascii.unhexlify(attrs['=ret'])
        md = md5.new()
            md = md5.new()
        md.update('\x00')
            md.update('\x00')
        md.update(pwd)
            md.update(pwd)
        md.update(chal)
            md.update(chal)
        self.talk(["/login", "=name=" + username,
            for repl2, attrs2 in self.talk(["/login", "=name=" + username,
                   "=response=00" + binascii.hexlify(md.digest())])
                   "=response=00" + binascii.hexlify(md.digest())]):
              if repl2 == '!trap':
                return False
        return True


     def talk(self, words):
     def talk(self, words):
Line 407: Line 575:
             if w == '': return r
             if w == '': return r
             r.append(w)
             r.append(w)
           
 
     def writeWord(self, w):
     def writeWord(self, w):
         print "<<< " + w
         print "<<< " + w
Line 430: Line 598:
             self.writeStr(chr((l >> 8) & 0xFF))
             self.writeStr(chr((l >> 8) & 0xFF))
             self.writeStr(chr(l & 0xFF))
             self.writeStr(chr(l & 0xFF))
         elif l < 0x10000000:      
         elif l < 0x10000000:
             l |= 0xE0000000        
             l |= 0xE0000000
             self.writeStr(chr((l >> 24) & 0xFF))
             self.writeStr(chr((l >> 24) & 0xFF))
             self.writeStr(chr((l >> 16) & 0xFF))
             self.writeStr(chr((l >> 16) & 0xFF))
             self.writeStr(chr((l >> 8) & 0xFF))
             self.writeStr(chr((l >> 8) & 0xFF))
             self.writeStr(chr(l & 0xFF))
             self.writeStr(chr(l & 0xFF))
         else:                      
         else:
             self.writeStr(chr(0xF0))
             self.writeStr(chr(0xF0))
             self.writeStr(chr((l >> 24) & 0xFF))
             self.writeStr(chr((l >> 24) & 0xFF))
Line 443: Line 611:
             self.writeStr(chr(l & 0xFF))
             self.writeStr(chr(l & 0xFF))


     def readLen(self):            
     def readLen(self):
         c = ord(self.readStr(1))  
         c = ord(self.readStr(1))
         if (c & 0x80) == 0x00:    
         if (c & 0x80) == 0x00:
             pass                  
             pass
         elif (c & 0xC0) == 0x80:  
         elif (c & 0xC0) == 0x80:
             c &= ~0xC0            
             c &= ~0xC0
             c <<= 8                
             c <<= 8
             c += ord(self.readStr(1))  
             c += ord(self.readStr(1))
         elif (c & 0xE0) == 0xC0:  
         elif (c & 0xE0) == 0xC0:
             c &= ~0xE0            
             c &= ~0xE0
             c <<= 8                
             c <<= 8
             c += ord(self.readStr(1))  
             c += ord(self.readStr(1))
             c <<= 8                
             c <<= 8
             c += ord(self.readStr(1))  
             c += ord(self.readStr(1))
         elif (c & 0xF0) == 0xE0:  
         elif (c & 0xF0) == 0xE0:
             c &= ~0xF0            
             c &= ~0xF0
             c <<= 8                
             c <<= 8
             c += ord(self.readStr(1))  
             c += ord(self.readStr(1))
             c <<= 8                
             c <<= 8
             c += ord(self.readStr(1))  
             c += ord(self.readStr(1))
             c <<= 8                
             c <<= 8
             c += ord(self.readStr(1))  
             c += ord(self.readStr(1))
         elif (c & 0xF8) == 0xF0:  
         elif (c & 0xF8) == 0xF0:
             c = ord(self.readStr(1))    
             c = ord(self.readStr(1))
             c <<= 8                
             c <<= 8
             c += ord(self.readStr(1))  
             c += ord(self.readStr(1))
             c <<= 8                
             c <<= 8
             c += ord(self.readStr(1))  
             c += ord(self.readStr(1))
             c <<= 8                
             c <<= 8
             c += ord(self.readStr(1))  
             c += ord(self.readStr(1))
         return c                  
         return c


     def writeStr(self, str):      
     def writeStr(self, str):
         n = 0;                    
         n = 0;
         while n < len(str):        
         while n < len(str):
             r = self.sk.send(str[n:])
             r = self.sk.send(str[n:])
             if r == 0: raise RuntimeError, "connection closed by remote end"
             if r == 0: raise RuntimeError, "connection closed by remote end"
             n += r                
             n += r


     def readStr(self, length):    
     def readStr(self, length):
         ret = ''                  
         ret = ''
         while len(ret) < length:  
         while len(ret) < length:
             s = self.sk.recv(length - len(ret))
             s = self.sk.recv(length - len(ret))
             if s == '': raise RuntimeError, "connection closed by remote end"
             if s == '': raise RuntimeError, "connection closed by remote end"
             ret += s
             ret += s
         return ret
         return ret
def open_socket(dst, port, secure=False):
  s = None
  res = socket.getaddrinfo(dst, port, socket.AF_UNSPEC, socket.SOCK_STREAM)
  af, socktype, proto, canonname, sockaddr = res[0]
  skt = socket.socket(af, socktype, proto)
  if secure:
    s = ssl.wrap_socket(skt, ssl_version=ssl.PROTOCOL_TLSv1_2, ciphers="ADH-AES128-SHA256") #ADH-AES128-SHA256
  else:
    s = skt
  s.connect(sockaddr)
  return s


def main():
def main():
     s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
     s = None
     s.connect((sys.argv[1], 8728))
    dst = sys.argv[1]
     apiros = ApiRos(s);            
    user = "admin"
     apiros.login(sys.argv[2], sys.argv[3]);
    passw = ""
    secure = False
    port = 0
 
    # use default username and pasword if not specified
    if len(sys.argv) == 4:
      user = sys.argv[2]
      passw = sys.argv[3]
     elif len(sys.argv) == 3:
      user = sys.argv[2]
 
    if (port==0):
      port = 8729 if secure else 8728
 
    s = open_socket(dst, port, secure)
    if s is None:
      print ('could not open socket')
      sys.exit(1)
 
     apiros = ApiRos(s);
     if not apiros.login(user, passw):
      return


     inputsentence = []
     inputsentence = []
Line 518: Line 720:


if __name__ == '__main__':
if __name__ == '__main__':
  if len(sys.argv) == 1:
    print "Usage: %s IP [user] [pass] [--secure]" % str(sys.argv[0])
  else:
     main()
     main()
</pre>
</pre>


Line 554: Line 761:
</pre>
</pre>


== Other example clients ==
== See also ==
*[[API command notes]]
*[http://forum.mikrotik.com/viewtopic.php?f=2&t=72298| Forum topic explaining query in detail]
==== API examples ====
 
API implementations in different languages, provided by different sources. They are not ordered in any particular order.
 
=====in the Wiki =====


==== In the Wiki ====
*[[API_PHP_package|in PHP]]


*[[API_PHP_class|in PHP]]
*[[API Delphi|in Delphi]] #1
*[[API_Delphi_Client|in Delphi]] #2
 
* [[API_in_Swift|Swift]]
*[[API_in_C| in C]] #1
*[[Librouteros| in C]] #2
*[[API_in_C_using_winsock | in C using winsock]]
*[[API_In_CPP|API in C++]]
*[[API_in_C_Sharp|in C#]]
*[[API_in_C_Sharp|in C#]]
*[[API Delphi|in Delphi]]


==== From the MikroTik Forum ====
*[[API_ActionScript_3_class|in Flash Actionscript 3]]
*[[API_Ruby_class|in Ruby on rails]]
*[[API_in_VB_dot_NET|in VB .NET]]
*[[API_in_Java|in java]] see java client on github from Gideon LeGrange
*[[MikroNode|in NodeJS]]
*[[Manual:API_Python3|Python3]]
*[[API_rust| in RUST]] GPL v3
*[[API_in_Go| in GO]] by andredossantos
 
===== on the MikroTik Forum =====
 
* [http://forum.mikrotik.com/viewtopic.php?f=9&t=22744 in Perl] by Hugh
* [http://forum.mikrotik.com/viewtopic.php?f=9&t=28821 in Delphi] by Rodolfo
* [http://forum.mikrotik.com/viewtopic.php?f=9&t=31555 in Delphi #2] by Chupaka
* [http://forum.mikrotik.com/viewtopic.php?f=9&t=51861 in NodeJS] by Trakkasure
* [http://forum.mikrotik.com/viewtopic.php?f=2&t=51584 in VB] by lucho512
* [http://forum.mikrotik.com/viewtopic.php?f=9&t=56869 on  PHP for sparks framework] by vthinkteam
* [http://forum.mikrotik.com/viewtopic.php?f=9&t=108989#p540866 for Windows PowerShell] by navidrasi
 
===== External sources =====
 
*[https://github.com/danikf/tik4net in .NET (C#)  high-level api solution] [http://forum.mikrotik.com/viewtopic.php?f=9&t=99954 forum thread] [https://github.com/danikf/tik4net/wiki additional info] by danikf
*[https://sourceforge.net/projects/netrouteros/ in PHP] by boen_robot
*[https://github.com/haakonnessjoen/librouteros-api in C] by Håkon Nessjøen
*[https://github.com/GideonLeGrange/mikrotik-java in Java] by Gideon LeGrange
*[https://github.com/comtihon/erotik in Erlang] by Valery Comtihon
*[https://github.com/go-routeros/routeros in GO] by André Luiz dos Santos
*[https://github.com/LaiArturs/RouterOS_API in Python3] by Arturs Laizans
*[https://github.com/aymanalqadhi/tikpp in C++17] by Ayman Al-Qadhi


* [http://forum.mikrotik.com/viewtopic.php?f=9&t=22744 in Perl]
* [http://forum.mikrotik.com/viewtopic.php?f=9&t=28821 in Delphi]
* [http://forum.mikrotik.com/viewtopic.php?p=103407#p103407 in Java]


[[Category:API]]
[[Category:API|A]]
[[Category:Manual|A]]
[[Category:System|A]]
[[Category:Case Studies|A]]

Latest revision as of 07:01, 14 October 2020

Summary

Application Programmable Interface (API) allows users to create custom software solutions to communicate with RouterOS to gather information, adjust configuration and manage router. API closely follows syntax from command line interface (CLI). It can be used to create translated or custom configuration tools to aid ease of use running and managing routers with RouterOS.

To use API RouterOS version 3.x or newer is required.

By default API uses port #8728 and service is enabled. More on service management see in corresponding manual section. Corresponding service name is api

Protocol

Communication with router is done by sending sentences to the router and receiving one or more sentences in return. Sentence is sequence of words terminated by zero length word. Word is part of sentence encoded in certain way - encoded length and data. Communication happen by sending sentences to the router and receiving replies to sent sentences. Each sentence sent to router using API should contain command as a first word followed by words in no particular order, end of sentence is marked by zero length word. When router receives full sentence (command word, no or more attribute words and zero length word) it is evaluated and executed, then reply is formed and returned.

API words

Words are part of sentence. Each word has to be encoded in certain way - length of the word followed by word content. Length of the word should be given as count of bytes that are going to be sent.

Length of the word is encoded as follows:

Value of length # of bytes Encoding
0 <= len <= 0x7F 1 len, lowest byte
0x80 <= len <= 0x3FFF 2 len | 0x8000, two lower bytes
0x4000 <= len <= 0x1FFFFF 3 len | 0xC00000, three lower bytes
0x200000 <= len <= 0xFFFFFFF 4 len | 0xE0000000
len >= 0x10000000 5 0xF0 and len as four bytes


  • Each word is encoded as length, followed by that many bytes of content;
  • Words are grouped into sentences. End of sentence is terminated by zero length word;
  • Scheme allows encoding of length up to 0x7FFFFFFFFF, only four byte length is supported;
  • Bytes of len are sent most significant first (network order);
  • If first byte of word is >= 0xF8, then it is a reserved control byte. After receiving unknown control byte API client cannot proceed, because it cannot know how to interpret following bytes;
  • Currently control bytes are not used;

In general words can be described like this <<encoded word length><word content>>. Word content can be separated in 5 parts: command word, attribute word, API attribute word. query word and reply word

Command word

First word in sentence has to be command followed by attribute words and zero length word or terminating word. Name of command word should begin with '/'. Names of commands closely follow CLI, with spaces replaced with '/'. There are commands that are specific to API;

Command word structure in strict order:

  • encoded length
  • content prefix /
  • CLI converted command


API specific commands:

login
cancel

Command word content examples:

/login
/user/active/listen
/interface/vlan/remove
/system/reboot

Attribute word

Each command word has its own list of attribute words depending on content.

Atribute word structure consists of 5 parts in this order:

  • encoded length
  • content prefix equals sign - =
  • attribute name
  • separating equals sign - =
  • value of attribute if there is one. It is possible that attribute does not have a value
Icon-note.png

Note: Value can hold multiple equal signs in the value of attribute word since the way word is encoded


Icon-note.png

Note: Value can be empty



Examples without encoded length prefix:

=address=10.0.0.1
=name=iu=c3Eeg
=disable-running-check=yes
Icon-warn.png

Warning: Order of attribute words and API parameters is not important and should not be relied on


API attribute word

API attribute word structure is in strict order:

  • encoded length
  • content prefix with dot .
  • attribute name
  • name postfixed with equals =sign
  • attribute value

Currently the only such API attribute is tag.

Icon-note.png

Note: If sentence contain API attribute word tag then each returned sentence in reply from router to that tagged sentence will be tagged with same tag.


Query word

Senteces can have additional query paramteres that restrict their scope. They are explained in detail in separate section.

Example of sentence using query word attributes:

/interface/print
?type=ether
?type=vlan
?#|!


  • Query words begin with '?'.
  • Currently only print command handles query words.
Icon-warn.png

Warning: Order of query words is significant


Reply word

It is sent only by the router. It is only sent in response to full sentence send by the client.

  • First word of reply begins with '!';
  • Each sentence sent generates at least one reply (if connection does not get terminated);
  • Last reply for every sentence is reply that has first word !done;
  • Errors and exceptional conditions begin with !trap;
  • Data replies begin with !re
  • If API connection is closed, RouterOS sends !fatal with reason as reply and then closes the connection;

API sentences

API sentence is main object of communication using API.

  • Empty sentences are ignored.
  • Sentence is processed after receiving zero length word.
  • There is a limit on number and size of sentences client can send before it has logged in.
  • Order of attribute words should not be relied on. As order and count is changeable by .proplist attribute.
  • Sentence structure is as follows:
    • First word should contain command word;
    • Should contain zero length word to terminate the sentence;
    • Can contain none or several attribute words. There is no particular order at what attribute words has to be sent in the sentence, order is not important for attribute words;
    • Can contain none or several query words. Order of query words in the sentence is important.
Icon-note.png

Note: Zero length word terminates the sentence. If it is not provided router will not start to evaluate sent words and will consider all the input as part of the same sentence.


Initial login

Login method pre-v6.43:

Template:Apic

Template:Apic

Template:Apis

Template:Apis

Template:Apis

Template:Apic

Template:Apic

Template:Apic

Template:Apic

Template:Apis

Template:Apis

Icon-warn.png

Warning: this login method is deprecated and no longer supported in versions above 6.45.1.


Icon-note.png

Note: that each command and response ends with an empty word.


  • First, clients sends /login command.
  • Reply contains =ret=challenge argument.
  • Client sends second /login command, with =name=username and =response=response.
  • In case of error, reply contains =ret=error message.
  • In case of successful login client can start to issue commands.


Login method post-v6.43:

Template:Apic

Template:Apic

Template:Apic

Template:Apic

Template:Apis

Template:Apis

  • Now client sends username and password in first message.
  • Password is sent in plain text.
  • in case of error, reply contains =message=error message.
  • In case of successful login client can start to issue commands.

Tags

  • It is possible to run several commands simultaneously, without waiting for previous one to complete. If API client is doing this and needs to differentiate command responses, it can use 'tag' API parameter in command sentences.
  • If you include 'tag' parameter with non-empty value in command sentence, then 'tag' parameter with exactly the same value will be included in all responses generated by this command.
  • If you do not include 'tag' parameter or it's value is empty, then all responses for this command will not have 'tag' parameter.

Command description

  • /cancel
    • optional argument: =tag=tag of command to cancel, without it cancels all running commands
    • does not cancel itself
    • all canceled commands are interruped and in the usual case generate '!trap' and '!done' responses
    • please note that /cancel is separate command and can have it's own unique '.tag' parameter, that is not related to '=tag' argument of this command
  • listen
    • listen command is avaliable where console print command is available, but it does not have expected effect everywhere (i.e. may not work)
    • !re sentences are generated as something changes in particular item list
    • when item is deleted or dissapears in any other way, the '!re' sentence includes value '=.dead=yes'
    • This command does not terminate. To terminate it use /cancel command.
  • getall
    • getall command is available where console print command is available. Since version 3.21 getall is an alias for print.
    • replies contain =.id=Item internal number property.
  • print
    • API print command differs from the console counterpart in the following ways:
      • where argument is not supported. Items can be filtered using query words (see below).
      • .proplist argument is a comma separated list of property names that should be included for the returned items.
        • returned items may have additional properties.
        • order of returned properties is not defined.
        • if list contains duplicate entries, handling of such entries is not defined.
        • if propery is present in .proplist, but absent from the item, then that item does not have this property value (?name will evaluate to false for that item).
        • if .proplist is absent, all properties are included as requested by print command, even those that have slow access time (such as file contents and perfomance counters). Thus use of .proplist is encouraged. Omission of .proplist may have high perfomance penalty if =detail= argument is set.

Queries

print command accepts query words that limit set of returned sentences. This feature is available since RouterOS 3.21.

  • Query words begin with '?'.
  • Order of query words is significant. Query is evaluated starting from the first word.
  • Query is evaluated for each item in the list. If query succeeds, item is processed, if query fails, item is ignored.
  • Query is evaluated using a stack of boolean values. Initially stack contains infinite amount of 'true' values. At the end of evaluation, if stack contains at least one 'false' value, query fails.
  • Query words operate according to the following rules:
Query Desciption
?name pushes 'true' if item has value of property name, 'false' if it does not.
?-name pushes 'true' if item does not have value of property name, 'false' otherwise.
?name=x
?=name=x
pushes 'true' if property name has value equal to x, 'false' otherwise.
?<name=x pushes 'true' if property name has value less than x, 'false' otherwise.
?>name=x pushes 'true' if property name has value greater than x, 'false' otherwise.
?#operations applies operations to the values in the stack.
  • operation string is evaluated left to right.
  • sequence of decimal digits followed by any other character or end of word is interpreted as a stack index. top value has index 0.
  • index that is followed by a character pushes copy of value at that index.
  • index that is followed by the end of word replaces all values with the value at that index.
  • ! character replaces top value with the opposite.
  • & pops two values and pushes result of logical 'and' operation.
  • | pops two values and pushes result of logical 'or' operation.
  • . after an index does nothing.
  • . after another character pushes copy of top value.


Icon-warn.png

Warning: Regular expressions are not supported in API, so do not try to send query with ~ symbol


Examples:

  • Get all ethernet and VLAN interfaces:
/interface/print
?type=ether
?type=vlan
?#|
  • Get all routes that have non-empty comment:
/ip/route/print
?>comment=

OID

print command can return OID values for properties that are available in SNMP. This feature appeared in 3.23 version.

In console, OID values can be seen by running 'print oid' command. In API, these properties have name that ends with ".oid", and can be retrieved by adding their name to the value of '.proplist'. An example:

Template:Apic

Template:Apic

Template:Apic

Template:Apis

Template:Apis

Template:Apis

Template:Apis

Template:Apis

Template:Apis

Template:Apis

Template:Apis

!trap

When for some reason API sentence fails trap is sent in return accompanied with message attribute and on some occasions category argument.

message

When API sentence fails some generic message or message from used internal process is return to give more details about failure

<<< /ip/address/add
<<< =address=192.168.88.1
<<< =interface=asdf
<<< 
>>> !trap
>>> =category=1
>>> =message=input does not match any value of interface

category

if it is a general error, it is categorized and error category is returned. possible values for this attribute are

  • 0 - missing item or command
  • 1 - argument value failure
  • 2 - execution of command interrupted
  • 3 - scripting related failure
  • 4 - general failure
  • 5 - API related failure
  • 6 - TTY related failure
  • 7 - value generated with :return command

Command examples

/system/package/getall

Template:Bapi Template:Apic Template:Apic Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis |- | ... more !re sentences ... |- Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Eapi

/user/active/listen

Template:Bapi Template:Apic Template:Apic Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis |- | ... more !re sentences ... |- Template:Eapi

/cancel, simultaneous commands

Template:Bapi Template:Apic Template:Apic Template:Apis Template:Apis Template:Apis Template:Apic Template:Apic Template:Apic Template:Apic Template:Apis Template:Apis Template:Apih Template:Apic Template:Apic Template:Apic Template:Apih Template:Apic Template:Apic Template:Apic Template:Apic Template:Apic Template:Apih Template:Apis Template:Apis Template:Apis Template:Apih Template:Apic Template:Apic Template:Apic Template:Apic Template:Apic Template:Apih Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apih Template:Apis Template:Apis Template:Apis Template:Apih Template:Apic Template:Apic Template:Apic Template:Apih Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apih Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apih Template:Apis Template:Apis Template:Apis Template:Apih Template:Apic Template:Apic Template:Apic Template:Apic Template:Apih Template:Apis Template:Apis Template:Apis Template:Apis Template:Apis Template:Apih Template:Apis Template:Apis Template:Apis Template:Apih Template:Apis Template:Apis Template:Apis Template:Eapi

Example client

  • this is simple API client in Python2
  • example for Python3
  • usage: api.py ip-address username password
  • after that type words from keyboard, terminating them with newline
  • Since empty word terminates sentence, you should press enter twice after last word before sentence will be sent to router.

#!/usr/bin/python

import sys, posix, time, md5, binascii, socket, select, ssl

class ApiRos:
    "Routeros api"
    def __init__(self, sk):
        self.sk = sk
        self.currenttag = 0

    def login(self, username, pwd):

        for repl, attrs in self.talk(["/login", "=name=" + username,
                                      "=password=" + pwd]):
          if repl == '!trap':
            return False
          elif '=ret' in attrs.keys():
        #for repl, attrs in self.talk(["/login"]):
            chal = binascii.unhexlify(attrs['=ret'])
            md = md5.new()
            md.update('\x00')
            md.update(pwd)
            md.update(chal)
            for repl2, attrs2 in self.talk(["/login", "=name=" + username,
                   "=response=00" + binascii.hexlify(md.digest())]):
              if repl2 == '!trap':
                return False
        return True

    def talk(self, words):
        if self.writeSentence(words) == 0: return
        r = []
        while 1:
            i = self.readSentence();
            if len(i) == 0: continue
            reply = i[0]
            attrs = {}
            for w in i[1:]:
                j = w.find('=', 1)
                if (j == -1):
                    attrs[w] = ''
                else:
                    attrs[w[:j]] = w[j+1:]
            r.append((reply, attrs))
            if reply == '!done': return r

    def writeSentence(self, words):
        ret = 0
        for w in words:
            self.writeWord(w)
            ret += 1
        self.writeWord('')
        return ret

    def readSentence(self):
        r = []
        while 1:
            w = self.readWord()
            if w == '': return r
            r.append(w)

    def writeWord(self, w):
        print "<<< " + w
        self.writeLen(len(w))
        self.writeStr(w)

    def readWord(self):
        ret = self.readStr(self.readLen())
        print ">>> " + ret
        return ret

    def writeLen(self, l):
        if l < 0x80:
            self.writeStr(chr(l))
        elif l < 0x4000:
            l |= 0x8000
            self.writeStr(chr((l >> 8) & 0xFF))
            self.writeStr(chr(l & 0xFF))
        elif l < 0x200000:
            l |= 0xC00000
            self.writeStr(chr((l >> 16) & 0xFF))
            self.writeStr(chr((l >> 8) & 0xFF))
            self.writeStr(chr(l & 0xFF))
        elif l < 0x10000000:
            l |= 0xE0000000
            self.writeStr(chr((l >> 24) & 0xFF))
            self.writeStr(chr((l >> 16) & 0xFF))
            self.writeStr(chr((l >> 8) & 0xFF))
            self.writeStr(chr(l & 0xFF))
        else:
            self.writeStr(chr(0xF0))
            self.writeStr(chr((l >> 24) & 0xFF))
            self.writeStr(chr((l >> 16) & 0xFF))
            self.writeStr(chr((l >> 8) & 0xFF))
            self.writeStr(chr(l & 0xFF))

    def readLen(self):
        c = ord(self.readStr(1))
        if (c & 0x80) == 0x00:
            pass
        elif (c & 0xC0) == 0x80:
            c &= ~0xC0
            c <<= 8
            c += ord(self.readStr(1))
        elif (c & 0xE0) == 0xC0:
            c &= ~0xE0
            c <<= 8
            c += ord(self.readStr(1))
            c <<= 8
            c += ord(self.readStr(1))
        elif (c & 0xF0) == 0xE0:
            c &= ~0xF0
            c <<= 8
            c += ord(self.readStr(1))
            c <<= 8
            c += ord(self.readStr(1))
            c <<= 8
            c += ord(self.readStr(1))
        elif (c & 0xF8) == 0xF0:
            c = ord(self.readStr(1))
            c <<= 8
            c += ord(self.readStr(1))
            c <<= 8
            c += ord(self.readStr(1))
            c <<= 8
            c += ord(self.readStr(1))
        return c

    def writeStr(self, str):
        n = 0;
        while n < len(str):
            r = self.sk.send(str[n:])
            if r == 0: raise RuntimeError, "connection closed by remote end"
            n += r

    def readStr(self, length):
        ret = ''
        while len(ret) < length:
            s = self.sk.recv(length - len(ret))
            if s == '': raise RuntimeError, "connection closed by remote end"
            ret += s
        return ret


def open_socket(dst, port, secure=False):
  s = None
  res = socket.getaddrinfo(dst, port, socket.AF_UNSPEC, socket.SOCK_STREAM)
  af, socktype, proto, canonname, sockaddr = res[0]
  skt = socket.socket(af, socktype, proto)
  if secure:
    s = ssl.wrap_socket(skt, ssl_version=ssl.PROTOCOL_TLSv1_2, ciphers="ADH-AES128-SHA256") #ADH-AES128-SHA256
  else:
    s = skt
  s.connect(sockaddr)
  return s

def main():
    s = None
    dst = sys.argv[1]
    user = "admin"
    passw = ""
    secure = False
    port = 0

    # use default username and pasword if not specified
    if len(sys.argv) == 4:
      user = sys.argv[2]
      passw = sys.argv[3]
    elif len(sys.argv) == 3:
      user = sys.argv[2]

    if (port==0):
      port = 8729 if secure else 8728

    s = open_socket(dst, port, secure)
    if s is None:
      print ('could not open socket')
      sys.exit(1)

    apiros = ApiRos(s);
    if not apiros.login(user, passw):
      return

    inputsentence = []

    while 1:
        r = select.select([s, sys.stdin], [], [], None)
        if s in r[0]:
            # something to read in socket, read sentence
            x = apiros.readSentence()

        if sys.stdin in r[0]:
            # read line from input and strip off newline
            l = sys.stdin.readline()
            l = l[:-1]

            # if empty line, send sentence and start with new
            # otherwise append to input sentence
            if l == '':
                apiros.writeSentence(inputsentence)
                inputsentence = []
            else:
                inputsentence.append(l)

if __name__ == '__main__':
  if len(sys.argv) == 1:
    print "Usage: %s IP [user] [pass] [--secure]" % str(sys.argv[0])
  else:
    main()



Example run:

debian@localhost:~/api-test$ ./api.py 10.0.0.1 admin ''
<<< /login
<<< 
>>> !done
>>> =ret=93b438ec9b80057c06dd9fe67d56aa9a
>>> 
<<< /login
<<< =name=admin
<<< =response=00e134102a9d330dd7b1849fedfea3cb57
<<< 
>>> !done
>>> 
/user/getall

<<< /user/getall
<<< 
>>> !re
>>> =.id=*1
>>> =disabled=no
>>> =name=admin
>>> =group=full
>>> =address=0.0.0.0/0
>>> =netmask=0.0.0.0
>>> 
>>> !done
>>> 

See also

API examples

API implementations in different languages, provided by different sources. They are not ordered in any particular order.

in the Wiki
on the MikroTik Forum
External sources