diff --git a/.gitignore b/.gitignore index ae4703f..dee2255 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,6 @@ nbactions.xml .classpath .project + +# Maven +pom.xml.versionsBackup diff --git a/README.md b/README.md index fc92253..2364de4 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,21 @@ 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 ``` +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 + 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 +``` + +Connecting using TLS is similar: + +```java + ApiConnection con = ApiConnection.connect("10.0.1.1", ApiConnection.DEFAULT_TLS_PORT, 2000); // connect to router on the default TLS API port and fail in 2 seconds +``` + +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: * 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. @@ -185,6 +200,21 @@ con.cancel(tag); From version 2.0.0 of the API the error() and completed() methods are part of the ResultListener interface. +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: + +```java +ApiConnection con = ApiConnection.connect("10.0.1.1"); // connect to router +con.setTimeout(5000); // set command timeout to 5 seconds +con.login("admin","password"); // log in to router +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. + +The default command timeout, if none is set by the user, is 60 seconds. + References ========== diff --git a/src/main/java/examples/Config.java b/src/main/java/examples/Config.java index 67dcab9..7497b21 100644 --- a/src/main/java/examples/Config.java +++ b/src/main/java/examples/Config.java @@ -7,7 +7,7 @@ package examples; public class Config { - public static final String HOST = "10.0.1.134"; + public static final String HOST = "192.168.1.34"; public static final String USERNAME = "admin"; public static final String PASSWORD = ""; diff --git a/src/main/java/examples/Example.java b/src/main/java/examples/Example.java index 33dea60..ff25eae 100644 --- a/src/main/java/examples/Example.java +++ b/src/main/java/examples/Example.java @@ -9,7 +9,7 @@ import me.legrange.mikrotik.ApiConnection; abstract class Example { protected void connect() throws Exception { - con = ApiConnection.connect(Config.HOST); + con = ApiConnection.connect(Config.HOST, ApiConnection.DEFAULT_PORT, 2000); con.login(Config.USERNAME, Config.PASSWORD); } diff --git a/src/main/java/examples/Example2.java b/src/main/java/examples/Example2.java index 5391d56..95f63a8 100644 --- a/src/main/java/examples/Example2.java +++ b/src/main/java/examples/Example2.java @@ -19,6 +19,7 @@ public class Example2 extends Example { } private void test() throws MikrotikApiException { + con.setTimeout(50); List> results = con.execute("/interface/print"); for (Map result : results) { System.out.println(result); diff --git a/src/main/java/examples/Example9.java b/src/main/java/examples/Example9.java new file mode 100644 index 0000000..5870a9c --- /dev/null +++ b/src/main/java/examples/Example9.java @@ -0,0 +1,28 @@ +package examples; + +import java.util.List; +import java.util.Map; +import me.legrange.mikrotik.MikrotikApiException; + +/** + * Example 9: Test special characters in usernames + * + * @author gideon + */ +public class Example9 extends Example { + + public static void main(String... args) throws Exception { + Example9 ex = new Example9(); + ex.connect(); + ex.test(); + ex.disconnect(); + } + + private void test() throws MikrotikApiException, InterruptedException { + List> res = con.execute("/user/add name=çãáõ"); + for (Map r : res) { + System.out.println(r); + } +// con.execute("/ip/firewall/filter/add chain=forward hotspot=!auth protocol=tcp src-port=8000-8084"); + } +} diff --git a/src/main/java/me/legrange/mikrotik/ApiConnection.java b/src/main/java/me/legrange/mikrotik/ApiConnection.java index 29fa64c..47ac836 100644 --- a/src/main/java/me/legrange/mikrotik/ApiConnection.java +++ b/src/main/java/me/legrange/mikrotik/ApiConnection.java @@ -11,6 +11,28 @@ import me.legrange.mikrotik.impl.ApiConnectionImpl; * @author GideonLeGrange */ public abstract class ApiConnection { + + /** default TCP port used by Mikrotik API */ + public static final int DEFAULT_PORT = 8728; + /** default TCP TLS port used by Mikrotik API */ + public static final int DEFAULT_TLS_PORT = 8729; + /** default connection timeout to use when opening the connection */ + public static final int DEFAULT_CONNECTION_TIMEOUT = 60000; + /** default command timeout used for synchronous commands */ + public static final int DEFAULT_COMMAND_TIMEOUT = 60000; + + /** + * Create a new API connection to the give device on the supplied port, using anonymous TLS for encryption. + * @param host The host to which to connect. + * @param port The TCP port to use. + * @param timeout The connection timeout to use when opening the connection. + * @return The ApiConnection + * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem connecting + */ + public static ApiConnection connectTLS(String host, int port, int timeout) throws MikrotikApiException { + return ApiConnectionImpl.connect(host, port, true, timeout); + } + /** * Create a new API connection to the give device on the supplied port, using anonymous TLS for encryption. @@ -20,7 +42,7 @@ public abstract class ApiConnection { * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem connecting */ public static ApiConnection connectTLS(String host, int port) throws MikrotikApiException { - return ApiConnectionImpl.connect(host, port, true); + return ApiConnectionImpl.connect(host, port, true, DEFAULT_CONNECTION_TIMEOUT); } @@ -31,9 +53,20 @@ public abstract class ApiConnection { * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem connecting */ public static ApiConnection connectTLS(String host) throws MikrotikApiException { - return ApiConnectionImpl.connect(host, DEFAULT_TLS_PORT, true); + return ApiConnectionImpl.connect(host, DEFAULT_TLS_PORT, true, DEFAULT_CONNECTION_TIMEOUT); } + /** + * Create a new API connection to the give device on the supplied port + * @param host The host to which to connect. + * @param port The TCP port to use. + * @param timeout The connection timeout to use when opening the connection. + * @return The ApiConnection + * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem connecting + */ + public static ApiConnection connect(String host, int port, int timeout) throws MikrotikApiException { + return ApiConnectionImpl.connect(host, port, false, timeout); + } /** * Create a new API connection to the give device on the supplied port @@ -43,7 +76,7 @@ public abstract class ApiConnection { * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem connecting */ public static ApiConnection connect(String host, int port) throws MikrotikApiException { - return ApiConnectionImpl.connect(host, port, false); + return ApiConnectionImpl.connect(host, port, false, DEFAULT_CONNECTION_TIMEOUT); } /** @@ -99,10 +132,18 @@ public abstract class ApiConnection { * @param tag The tag of the command to cancel * @throws me.legrange.mikrotik.MikrotikApiException Thrown if there is a problem canceling the command */ public abstract void cancel(String tag) throws MikrotikApiException; + + + /** set the command timeout. The command timeout is used to time out API + * commands after a specific time. + * + * Note: This is not the same as the timeout value passed in the connect() and + * connectTLS() methods. This timeout is specific to synchronous commands, that + * timeout is applied to opening the API socket. + * + * @param timeout The time out in milliseconds. + * @throws MikrotikApiException Thrown if the timeout specified is invalid. + */ + public abstract void setTimeout(int timeout) throws MikrotikApiException; - /** default TCP port used by Mikrotik API */ - private static final int DEFAULT_PORT = 8728; - /** default TCP TLS port used by Mikrotik API */ - private static final int DEFAULT_TLS_PORT = 8729; - } \ No newline at end of file diff --git a/src/main/java/me/legrange/mikrotik/impl/ApiConnectionImpl.java b/src/main/java/me/legrange/mikrotik/impl/ApiConnectionImpl.java index bee6bcb..2fa6ae8 100644 --- a/src/main/java/me/legrange/mikrotik/impl/ApiConnectionImpl.java +++ b/src/main/java/me/legrange/mikrotik/impl/ApiConnectionImpl.java @@ -5,7 +5,9 @@ import java.io.DataOutputStream; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.net.InetAddress; +import java.net.InetSocketAddress; import java.net.Socket; +import java.net.SocketAddress; import java.net.UnknownHostException; import java.util.Arrays; import java.util.LinkedList; @@ -34,32 +36,22 @@ public final class ApiConnectionImpl extends ApiConnection { * @param host The host to which to connect. * @param port The TCP port to use. * @param secure Is TLS required + * @param timeOut The connection timeout * @return The ApiConnection * @throws me.legrange.mikrotik.ApiConnectionException Thrown if there is a * problem connecting */ - public static ApiConnection connect(String host, int port, boolean secure) throws ApiConnectionException { + public static ApiConnection connect(String host, int port, boolean secure, int timeOut) throws ApiConnectionException { ApiConnectionImpl con = new ApiConnectionImpl(); - con.open(host, port, secure); + con.open(host, port, secure, timeOut); return con; } - /** - * Check the state of connection. - * - * @return if connection is established to router it returns true. - */ @Override public boolean isConnected() { return connected; } - /** - * Disconnect from the remote API - * - * @throws me.legrange.mikrotik.ApiConnectionException Thrown if there is a - * problem disconnecting - */ @Override public void disconnect() throws ApiConnectionException { if (!connected) { @@ -69,20 +61,14 @@ public final class ApiConnectionImpl extends ApiConnection { processor.interrupt(); reader.interrupt(); try { + in.close(); + out.close(); sock.close(); } catch (IOException ex) { throw new ApiConnectionException(String.format("Error closing socket: %s", ex.getMessage()), ex); } } - /** - * Log in to the remote router. - * - * @param username - username of the user on the router - * @param password - password for the user - * @throws me.legrange.mikrotik.MikrotikApiException - * @throws java.lang.InterruptedException - */ @Override public void login(String username, String password) throws MikrotikApiException, InterruptedException { if (username.trim().isEmpty()) { @@ -96,45 +82,35 @@ public final class ApiConnectionImpl extends ApiConnection { execute("/login name=" + username + " response=00" + chal); } - /** - * execute a command and return a list of results. - * - * @param cmd Command to execute - * @return The list of results - * @throws me.legrange.mikrotik.MikrotikApiException - */ @Override public List> execute(String cmd) throws MikrotikApiException { - return execute(Parser.parse(cmd)); + return execute(Parser.parse(cmd), timeout); } - /** - * execute a command and attach a result listener to receive it's results. - * - * @param cmd Command to execute - * @param lis ResultListener that will receive the results - * @return A command object that can be used to cancel the command. - * @throws MikrotikApiException - */ @Override public String execute(String cmd, ResultListener lis) throws MikrotikApiException { return execute(Parser.parse(cmd), lis); } - /** - * cancel a command - * @param tag - * @throws me.legrange.mikrotik.MikrotikApiException Thrown if an error is experienced while canceling the - */ @Override public void cancel(String tag) throws MikrotikApiException { execute(String.format("/cancel tag=%s", tag)); } - private List> execute(Command cmd) throws MikrotikApiException { + @Override + public void setTimeout(int timeout) throws MikrotikApiException { + if (timeout > 0) { + this.timeout = timeout; + } + else { + throw new MikrotikApiException(String.format("Invalid timeout value '%d'; must be postive", timeout)); + } + } + + private List> execute(Command cmd, int timeout) throws MikrotikApiException { SyncListener l = new SyncListener(); execute(cmd, l); - return l.getResults(); + return l.getResults(timeout); } private String execute(Command cmd, ResultListener lis) throws MikrotikApiException { @@ -155,23 +131,16 @@ public final class ApiConnectionImpl extends ApiConnection { this.listeners = new ConcurrentHashMap<>(); } - /** - * Start the API. Connects to the Mikrotik without using encryption - */ - private void open(String host, int port) throws ApiConnectionException { - open(host, port, false); - } - /** * Start the API. Connects to the Mikrotik */ - private void open(String host, int port, boolean secure) throws ApiConnectionException { + private void open(String host, int port, boolean secure, int conTimeout) throws ApiConnectionException { try { InetAddress ia = InetAddress.getByName(host.trim()); if (secure) { - sock = openSSLSocket(ia, port); + sock = openSSLSocket(ia, port, conTimeout); } else { - sock = new Socket(ia, port); + sock = openClearSocket(ia, port, conTimeout); } in = new DataInputStream(sock.getInputStream()); out = new DataOutputStream(sock.getOutputStream()); @@ -191,11 +160,19 @@ public final class ApiConnectionImpl extends ApiConnection { } } + private Socket openClearSocket(InetAddress ia, int port, int timeOut) throws IOException { + Socket clear = new Socket(); + SocketAddress addr = new InetSocketAddress(ia, port); + clear.connect(new InetSocketAddress(ia, port), timeOut); + return clear; + } + /** * open and configure a SSL socket. */ - private Socket openSSLSocket(InetAddress ia, int port) throws IOException { - SSLSocket ssl = (SSLSocket) SSLSocketFactory.getDefault().createSocket(ia, port); + private Socket openSSLSocket(InetAddress ia, int port, int timeOut) throws IOException { + SSLSocket ssl = (SSLSocket) SSLSocketFactory.getDefault().createSocket(); + ssl.connect(new InetSocketAddress(ia, port), timeOut); List cs = new LinkedList<>(); // not happy with this code. Without it, SSL throws a "Remote host closed connection during handshake" error // caused by a "SSL peer shut down incorrectly" error @@ -212,7 +189,7 @@ public final class ApiConnectionImpl extends ApiConnection { _tag++; return Integer.toHexString(_tag); } - private static final int DEFAULT_PORT = 8728; + private Socket sock = null; private DataOutputStream out = null; private DataInputStream in = null; @@ -221,6 +198,7 @@ public final class ApiConnectionImpl extends ApiConnection { private Processor processor; private final Map listeners; private Integer _tag = 0; + private int timeout = ApiConnection.DEFAULT_COMMAND_TIMEOUT; /** * thread to read data from the socket and process it into Strings @@ -318,15 +296,15 @@ public final class ApiConnectionImpl extends ApiConnection { return !lines.isEmpty() || !reader.isEmpty(); } - private String peekLine() throws ApiConnectionException, ApiDataException { - if (lines.isEmpty()) { + private String peekLine() throws ApiConnectionException, ApiDataException { + if (lines.isEmpty()) { String block = reader.take(); String parts[] = block.split("\n"); lines.addAll(Arrays.asList(parts)); } return lines.get(0); } - + private Response unpack() throws MikrotikApiException { if (line == null) { nextLine(); @@ -340,8 +318,7 @@ public final class ApiConnectionImpl extends ApiConnection { return unpackError(); case "!halt": return unpackError(); - case "" : - System.out.printf("sock.isClosed() = %s, sock.isInputShutdown() = %s\n", sock.isClosed(), sock.isInputShutdown()); + case "": default: throw new ApiDataException(String.format("Unexpected line '%s'", line)); } @@ -379,8 +356,8 @@ public final class ApiConnectionImpl extends ApiConnection { } return res; } - - private String unpackResult(String first )throws ApiConnectionException, ApiDataException { + + private String unpackResult(String first) throws ApiConnectionException, ApiDataException { StringBuilder buf = new StringBuilder(first); line = null; @@ -390,8 +367,7 @@ public final class ApiConnectionImpl extends ApiConnection { nextLine(); buf.append("\n"); buf.append(line); - } - else { + } else { break; } } @@ -479,6 +455,7 @@ public final class ApiConnectionImpl extends ApiConnection { @Override public synchronized void completed() { + complete = true; notify(); } @@ -488,6 +465,7 @@ public final class ApiConnectionImpl extends ApiConnection { res.put("ret", done.getHash()); results.add(res); } + complete = true; notify(); } @@ -496,11 +474,17 @@ public final class ApiConnectionImpl extends ApiConnection { results.add(result); } - private List> getResults() throws MikrotikApiException { + private List> getResults(int timeout) throws MikrotikApiException { try { - synchronized (this) { // don't wait if we already have a result. - if ((err == null) && results.isEmpty()) { - wait(); + synchronized (this) { // don't wait if we already have a result. + int waitTime = timeout; + while (!complete && (waitTime > 0)) { + long start = System.currentTimeMillis(); + wait(waitTime); + waitTime = waitTime - (int)(System.currentTimeMillis() - start); + if ((waitTime <= 0) && !complete) { + err = new ApiConnectionException(String.format("Command timed out after %d ms", timeout)); + } } } } catch (InterruptedException ex) { @@ -511,7 +495,9 @@ public final class ApiConnectionImpl extends ApiConnection { } return results; } + private final List> results = new LinkedList<>(); private MikrotikApiException err; + private boolean complete = false; } }