A Java client library implementation for the Mikrotik RouterOS API.

This project provides a Java client to manipulate Mikrotik routers using the remote API. Simple things must be easy to do, and complex things must be possible.

The current stable version is 2.0.0. This version is not backwards compatible with version 1.x.

• Changed ResultListener to receive errors and completion notifications.

Previous versions:

• 1.1.5 fixed even more comamnd line parsing bugs.
• 1.1.4 fixed command line parsing bugs #7 and #8.
• 1.1.3 fixed severe command line parsing bugs, #3, #4 and #5.
• 1.1.2 added support for handling multi-line results, like for example /file print.
• 1.1 added TLS (SSL) support to encrypt API traffic.

The latest development version is 2.0.0 which is available using the 2.0.0 branch.

You can clone or fork the repository. Alternatively, you can get the jar from Maven Central.

I welcome contributions, be it bug fixes or other improvements. If you fix or change something, please submit a pull request. If you want to report a bug, please open an issue.

Here is a simple example: Connect to a router and reboot it.

ApiConnection con = ApiConnection.connect("10.0.1.1"); // connect to router
con.login("admin","password"); // log in to router
con.execute("/system/reboot"); // execute a command
con.disconnect(); // disconnect from router

If your router does not use the default API port, the port can be specified when connecting:

ApiConnection con = ApiConnection.connect("10.0.1.1", 1337); // connect to router on port 1337

To open an encrypted (TLS) connection is as simple, assuming the default API-SSL port is used:

ApiConnection con = ApiConnection.connectTLS("10.0.1.1"); // connect to router using TLS

• Currently only anonymous TLS is supported, not certificates.
• There is a compatibility problem between the current versions of RouterOS supporting API over TLS and the Java Cryptography Extension (JCE) in Java 7 and earlier. TLS encryption works in Java 8 and later. For more information, feel free to contact me.

In following examples the connection, login and disconnection code will not be repeated.

A simple example that returns a result: Print all interfaces.

List<Map<String, String>> rs = con.execute("/interface/print");
for (Map<String,String> r : rs) {
  System.out.println(r);
}

The same query, but with the results filtered: Print all interfaces of type 'vlan'.

List<Map<String, String>> rs = con.execute("/interface/print where type=vlan");

The same query, but we only want certain result fields names Print all interfaces of type 'vlan' and return their name.

List<Map<String, String>> rs = con.execute("/interface/print where type=vlan return name");

Creating, modifying and deleting configuration objects is of course possible.

This example shows how to create a new GRE interface:

con.execute("/interface/gre/add remote-address=192.168.1.1 name=gre1 keepalive=10");

Change the IP address in the object created by the above example:

con.execute("/interface/gre/set .id=gre1 remote-address=10.0.1.1"); 

And now remove the object:

con.execute("/interface/gre/remove .id=gre1"); 

We can run some commands asynchronously in order to continue receiving updates:

This example shows how to run '/interface wireless monitor' and have the result sent to a listener object, which prints it:

String tag = con.execute("/interface/wireless/monitor .id=wlan1 return signal-to-noise", 
      new ResultListener() {

            public void receive(Map<String, String> result) {
                System.out.println(result);
            }

           public void error(MikrotikApiException e) {
               System.out.println("An error occurred: " + e.getMessage());
           }

           public void completed() {
                System.out.println("Asynchronous command has finished"); 
           }
            
        }
  );

The above command will run and send results asynchronously as they become available, until it is canceled. The command (identified by the unique String returned) is canceled like this:

con.cancel(tag);

From version 2.0.0 of the API the error() and completed() methods are part of the ResultListener interface.

The RouterOS API is documented here: http://wiki.mikrotik.com/wiki/Manual:API

This library is released under the Apache 2.0 licence. See the Licence.md file