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

Updated README for 3.0

This commit is contained in:
Gideon le Grange 2016-02-02 22:40:54 +02:00
parent 8882226684
commit d7ca193625
1 changed files with 20 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
README.md
View File

@ -12,9 +12,9 @@ This library uses [semantic versioning](http://semver.org/)
### Changes in version 3.0: ### Changes in version 3.0:
Version 3.0 addresses the problems the API has around TLS encryption. To do this, the way secure connections are implemented is changed, to put the power to do this in the hands of the user. This means that: Version 3.0 addresses the problems the API has around TLS encryption. To do this, the way secure connections are implemented is changed so that the user has complete control over creating TLS sockets. To this end:
* The `connectTLS` API methods were removed.
* A new method, `connect(SocketFactory fact, String host, int port, int timeout)`, was added to allow for better user control over sockets and especially encrypyion. * A new method, `connect(SocketFactory fact, String host, int port, int timeout)`, was added to allow for better user control over sockets and especially encrypyion.
* The `connectTLS` API methods were removed.
Further changes include: Further changes include:
* The deprecated `disconnect()` method is removed. * The deprecated `disconnect()` method is removed.
@ -46,12 +46,12 @@ I recommend using the Maven artifact from Maven Central using this dependency:
<version>3.0</version> <version>3.0</version>
</dependency> </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)
Alternatively, you can download the pre-built jar file, or a zip or tar.gz file with the source for the latest release [here](https://github.com/GideonLeGrange/mikrotik-java/releases/latest)
## 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. General questions 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. General questions are also welcome.
are also welcome.
# Examples # Examples
@ -67,40 +67,32 @@ con.execute("/system/reboot"); // execute a command
con.disconnect(); // disconnect from router con.disconnect(); // disconnect from router
``` ```
The above example shows a convenient and easy way of creating an unencrypted connection using the default ports. Encrypting API traffic is however recommended, and to do this you need to open a TLS connection to the router. This is done by passing an instance of the `SocketFactory` you wish to use to construct the TLS socket to the API:
To encrypt API traffic (recommended) you need to open a TLS connection to the router. This is done by passing an instance of the `SocketFactory` you wish to use to construct the
TLS socket to the API:
```java ```java
ApiConnection con = ApiConnection.connect(SSLSocketFactory.getDefault(), Config.HOST, ApiConnection.DEFAULT_TLS_PORT, ApiConnection.DEFAULT_CONNECTION_TIMEOUT); ApiConnection con = ApiConnection.connect(SSLSocketFactory.getDefault(), "10.0.1.1", ApiConnection.DEFAULT_TLS_PORT, ApiConnection.DEFAULT_CONNECTION_TIMEOUT);
``` ```
Besides allowing the user to specify the socket factory, it also gives full control over the TCP Port and connection timeout. In the above example, an instance of the default SSL socket factory is passed to the API. This will work as long as the router's certificate has been added to your local key store. Besides allowing the user to specify the socket factory, the above method also gives full control over the TCP Port and connection timeout.
### Connection timeouts ### 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()``` call. For example:
```java ```java
ApiConnection con = ApiConnection.connect("10.0.1.1", ApiConnection.DEFAULT_PORT, 2000); // connect to router on the default API port and fail in 2 seconds ApiConnection con = ApiConnection.connect(SSLSocketFactory.getDefault(), "10.0.1.1", ApiConnection.DEFAULT_TLS_PORT, 2000); // connect to router on the default API port and fail in 2 seconds
``` ```
Connecting using TLS is similar: ### Constants
Some constants are provided in `ApiConnection` to make it easier for users to construct connections with default ports and timeouts:
```java Constant | Use for | Value
ApiConnection con = ApiConnection.connectTLS("10.0.1.1", ApiConnection.DEFAULT_TLS_PORT, 2000); // connect to router on the default TLS API port and fail in 2 seconds ---------|---------|------
``` DEFAULT_PORT | Default TCP `port` value for unencrypyted connections | 8728
DEFAULT_TLS_PORT | Default TCP `port` value for encrypyted connections | 8729
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. DEFAULT_CONNECTION_TIMEOUT | Default connection `timeout` value (ms) | 60000
### Notes about 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. In all cases it is assumed that an `ApiConnection` has been established, `login()` has been called, and that the connection is called `con`.
In following examples the connection, login and disconnection code will not be repeated.
## Reading data ## Reading data
@ -202,7 +194,7 @@ From version 2.0.0 of the API the error() and completed() methods are part of th
## 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 can be set using ```setTimeout()```. Here is an example:
```java ```java
ApiConnection con = ApiConnection.connect("10.0.1.1"); // connect to router ApiConnection con = ApiConnection.connect("10.0.1.1"); // connect to router
@ -210,6 +202,7 @@ con.setTimeout(5000); // set command timeout to 5 seconds
con.login("admin","password"); // log in to router con.login("admin","password"); // log in to router
con.execute("/system/reboot"); // execute a command con.execute("/system/reboot"); // execute a command
``` ```
It is important to note that command timeouts can be set before ```login()``` is called, and can therefore influence the behaviour of login. It is important to note that command timeouts can be set before ```login()``` is called, and can therefore influence the behaviour of login.
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.