kirillius
/
mikrotik-java
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improved README formatting a bit

This commit is contained in:
GideonLeGrange 2015-03-30 17:03:44 +02:00
parent 0219fe43d8
commit f9a166afaa
1 changed files with 16 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
README.md
View File

@ -1,18 +1,16 @@
mikrotik-java # mikrotik-java
=============
A Java client library implementation for the Mikrotik RouterOS API. 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. 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.
Versions ## Versions
--------
This library uses [semantic versioning](http://semver.org/) This library uses [semantic versioning](http://semver.org/)
**The current stable version is 2.0.3.** **The current stable version is 2.0.3.**
### Changes in version 2.0.3: ### Changes in version 2.0.2:
* Fixed bug #18 - An empty username in ```login()``` caused the API to hang. * Fixed bug #18 - An empty username in ```login()``` caused the API to hang.
@ -32,8 +30,7 @@ Previous 1.1 versions:
* 1.1.2 added support for handling multi-line results, like for example /file print. * 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. * 1.1 added TLS (SSL) support to encrypt API traffic.
Getting the API ## Getting the API
---------------
I recommend using the Maven artifact from Maven Central using this dependency: I recommend using the Maven artifact from Maven Central using this dependency:
@ -46,16 +43,15 @@ I recommend using the Maven artifact from Maven Central using this dependency:
``` ```
You can also clone or fork the repository, or download the source as a zip or tar.gz from [Releases](https://github.com/GideonLeGrange/mikrotik-java/releases) You can also clone or fork the repository, or download the source as a zip or tar.gz from [Releases](https://github.com/GideonLeGrange/mikrotik-java/releases)
Contributing ## Contributing
------------
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. 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.
# Examples
Examples
========
These examples should illustrate how to use this library. Please note that I assume that the user is proficient in Java and understands the Mikrotik command line syntax. These examples should illustrate how to use this library. Please note that I assume that the user is proficient in Java and understands the Mikrotik command line syntax.
## Opening a connection
Here is a simple example: Connect to a router and reboot it. Here is a simple example: Connect to a router and reboot it.
```java ```java
@ -76,6 +72,8 @@ To open an encrypted (TLS) connection is as simple, assuming the default API-SSL
ApiConnection con = ApiConnection.connectTLS("10.0.1.1"); // connect to router using TLS ApiConnection con = ApiConnection.connectTLS("10.0.1.1"); // connect to router using TLS
``` ```
### Connection timeouts
By default, the API will generate an exception if it cannot connect to the specified router. This can take place immediately (typically if the router returns a 'Connection refused' error), but can also take up to 60 seconds if the router host is firewalled or if there are other network problems. This 60 seconds is the 'default connection timeout' an can be overridded by passing the preferred timeout to the APi as last parameter in a ```connect()``` or ```connectTLS()``` call. Here is the non-TLS example: By default, the API will generate an exception if it cannot connect to the specified router. This can take place immediately (typically if the router returns a 'Connection refused' error), but can also take up to 60 seconds if the router host is firewalled or if there are other network problems. This 60 seconds is the 'default connection timeout' an can be overridded by passing the preferred timeout to the APi as last parameter in a ```connect()``` or ```connectTLS()``` call. Here is the non-TLS example:
```java ```java
@ -90,8 +88,8 @@ Connecting using TLS is similar:
Note that ```ApiConnection.DEFAULT_PORT``` and ```ApiConnection.DEFAULT_TLS_PORT``` are provided to allow users who use the default ports to safely use the overloaded timeout method. Note that ```ApiConnection.DEFAULT_PORT``` and ```ApiConnection.DEFAULT_TLS_PORT``` are provided to allow users who use the default ports to safely use the overloaded timeout method.
### Notes about TLS:
#### Notes about TLS:
* Currently only anonymous TLS is supported, not certificates. * 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. * 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.
@ -99,8 +97,7 @@ Note that ```ApiConnection.DEFAULT_PORT``` and ```ApiConnection.DEFAULT_TLS_PORT
In following examples the connection, login and disconnection code will not be repeated. In following examples the connection, login and disconnection code will not be repeated.
Reading data ## Reading data
------------
A simple example that returns a result: Print all interfaces. A simple example that returns a result: Print all interfaces.
@ -136,8 +133,7 @@ The same query, but we only want certain result fields names: Print all interfac
List<Map<String, String>> rs = con.execute("/interface/print where type=vlan return name"); List<Map<String, String>> rs = con.execute("/interface/print where type=vlan return name");
``` ```
Writing data ## Writing data
------------
Creating, modifying and deleting configuration objects is of course possible. Creating, modifying and deleting configuration objects is of course possible.
@ -165,8 +161,7 @@ And now remove the object:
con.execute("/interface/gre/remove .id=gre1"); con.execute("/interface/gre/remove .id=gre1");
``` ```
Asynchronous commands ## Asynchronous commands
---------------------
We can run some commands asynchronously in order to continue receiving updates: We can run some commands asynchronously in order to continue receiving updates:
@ -200,8 +195,7 @@ con.cancel(tag);
From version 2.0.0 of the API the error() and completed() methods are part of the ResultListener interface. From version 2.0.0 of the API the error() and completed() methods are part of the ResultListener interface.
Command timeouts ## Command timeouts
----------------
Command timeouts can be used to make sure that synchronous commands either return or fail within a specific time. Command timeouts are separate from the connection timeout used in ```connect()``` and ```connectTLS()```, and can be set using ```setTimeout()```. Here is an example: Command timeouts can be used to make sure that synchronous commands either return or fail within a specific time. Command timeouts are separate from the connection timeout used in ```connect()``` and ```connectTLS()```, and can be set using ```setTimeout()```. Here is an example:
@ -215,13 +209,11 @@ It is important to note that command timeouts can be set before ```login()``` is
The default command timeout, if none is set by the user, is 60 seconds. The default command timeout, if none is set by the user, is 60 seconds.
References # References
==========
The RouterOS API is documented here: http://wiki.mikrotik.com/wiki/Manual:API The RouterOS API is documented here: http://wiki.mikrotik.com/wiki/Manual:API
Licence # Licence
=======
This library is released under the Apache 2.0 licence. See the [Licence.md](Licence.md) file This library is released under the Apache 2.0 licence. See the [Licence.md](Licence.md) file