{"id":25814858,"url":"https://github.com/gideonlegrange/mikrotik-java","last_synced_at":"2025-09-22T23:57:06.958Z","repository":{"id":9460774,"uuid":"11342661","full_name":"GideonLeGrange/mikrotik-java","owner":"GideonLeGrange","description":"A Java client implementation for the Mikrotik RouterOS API. ","archived":false,"fork":false,"pushed_at":"2024-09-26T12:41:48.000Z","size":264,"stargazers_count":187,"open_issues_count":3,"forks_count":106,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-07-27T15:18:06.586Z","etag":null,"topics":["java","mikrotik-api","mikrotik-routeros-api","routeros-api"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GideonLeGrange.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-07-11T13:30:37.000Z","updated_at":"2025-07-18T05:59:23.000Z","dependencies_parsed_at":"2025-03-22T18:01:12.741Z","dependency_job_id":"2c3cf0db-2047-4eb2-8a14-8a6ec743a7cc","html_url":"https://github.com/GideonLeGrange/mikrotik-java","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/GideonLeGrange/mikrotik-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GideonLeGrange%2Fmikrotik-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GideonLeGrange%2Fmikrotik-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GideonLeGrange%2Fmikrotik-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GideonLeGrange%2Fmikrotik-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GideonLeGrange","download_url":"https://codeload.github.com/GideonLeGrange/mikrotik-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GideonLeGrange%2Fmikrotik-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276492817,"owners_count":25652049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-22T02:00:08.972Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","mikrotik-api","mikrotik-routeros-api","routeros-api"],"created_at":"2025-02-28T03:46:53.370Z","updated_at":"2025-09-22T23:57:06.937Z","avatar_url":"https://github.com/GideonLeGrange.png","language":"Java","readme":"# mikrotik-java \n\nA Java client library implementation for the Mikrotik RouterOS API. \n\nThis 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.\n\n## Versions\n\n![Java CI with Maven](https://github.com/GideonLeGrange/mikrotik-java/workflows/Java%20CI%20with%20Maven/badge.svg)\n\n**The current stable version is 3.0.8**\n\nVersion 3.0.8 fixes a null pointer error \n\n### Changes in version 3.0:\n\nVersion 3.0 addresses the problems the API had around TLS encryption. The way secure connections are implemented is changed so that the user has complete control over the creation of TLS sockets. To this end:\n* A new method, `connect(SocketFactory fact, String host, int port, int timeout)`, was added to allow for better user control over sockets and especially encryption.\n* The `connectTLS()` API methods were removed. \n* Most of the overloaded `connect()` methods were removed. \n* Added a pre-built `jar` file to the downloads.\n\nFurther changes include:\n* The previously deprecated `disconnect()` method is removed. \n\n#### Versions 1.x and 2.x\n\nVersions 1 and 2 are considered *obsolete* and will no longer be supported or patched. \n\n## Getting the API\n\nMaven users can use the artifact from Maven Central with this dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eme.legrange\u003c/groupId\u003e\n  \u003cartifactId\u003emikrotik\u003c/artifactId\u003e\n  \u003cversion\u003e3.0.8\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nYou can also 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)\n\n## Asking for help or contributing\n\nI welcome contributions, be it bug fixes or other improvements. \n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for information on how to contribute to this project.\n\n# Using the API\n\nHow to use the API is best illustrated by examples. \n\nThese 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. The command line syntax gives you an indication of what commands you can pass, but the RouterOS API used by this library does not support everyting. \n\nSome things to consider when debugging your API calls are:\n* The RouterOS API does not support auto-completion. You need to write out command and parameter names. For example, you can't say `/ip/hotspot/user/add name=john add=10.0.0.1`, you need to write out `address`.\n* You need to quote values with spaces in. You can't say `name=Joe Blogs`, you need to use `name=\"Joe Blogs\"`\n* Exceptions with a root cause of `ApiCommandException` are errors received from the remote RouterOS device and contain the error message received. \n\n## Opening a connection\nHere is a simple example: Connect to a router and reboot it. \n\n```java\nApiConnection con = ApiConnection.connect(\"10.0.1.1\"); // connect to router\ncon.login(\"admin\",\"password\"); // log in to router\ncon.execute(\"/system/reboot\"); // execute a command\ncon.close(); // disconnect from router\n```\nThe above example shows a easy way of creating an unencrypted connection using the default API port and timeout, which is useful for development and testing.\n\n### TLS encryption\n\nFor production environments, encrypting API traffic is recommended. To do this you need to open a TLS connection to the router by passing an instance of the `SocketFactory` you wish to use to construct the TLS socket to the API:\n\n```java\nApiConnection con = ApiConnection.connect(SSLSocketFactory.getDefault(), \"10.0.1.1\", ApiConnection.DEFAULT_TLS_PORT, ApiConnection.DEFAULT_CONNECTION_TIMEOUT);\n```\n\nAbove 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 the 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. \n\nRouterOS also supports anonymous TLS. An example showing how to create a socket factory for anonymous TLS is `AnonymousSocketFactory` in the examples directory.\n\n### Connection timeouts\n\nBy default, the API will generate an exception if it cannot connect to the specified router. This can take place immediately (typically if the OS 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:\n\n```java\n   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\n```\t\n\n### Constants\nSome constants are provided in `ApiConnection` to make it easier for users to construct connections with default ports and timeouts:\n\nConstant | Use for | Value \n---------|---------|------\nDEFAULT_PORT | Default TCP `port` value for unencrypyted connections | 8728\nDEFAULT_TLS_PORT | Default TCP `port` value for encrypyted connections | 8729\nDEFAULT_CONNECTION_TIMEOUT | Default connection `timeout` value (ms) | 60000\n\n### Try with resources \n\nThe API can also be used in a \"try with resources\" statement which will ensure that the connection is closed:\n\n```java\n        try (ApiConnection con = ApiConnection.connect(SocketFactory.getDefault(), Config.HOST, ApiConnection.DEFAULT_PORT, 2000)) {\n            con.login(Config.USERNAME, Config.PASSWORD);\n            con.execute(\"/user/add name=eric\");\n        }\n```\n\nIn 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`.\n\n## Reading data \n\nA simple example that returns a result - Print all interfaces:\n\n\n```java\nList\u003cMap\u003cString, String\u003e\u003e rs = con.execute(\"/interface/print\");\nfor (Map\u003cString,String\u003e r : rs) {\n  System.out.println(r);\n}\n```\n\nResults are returned as a list of maps of String key/value pairs. The reason for this is that a command can return multiple results, which have multpile variables. For example, to print the names of all the interfaces returned in the command above, do:\n\n```java\nfor (Map\u003cString, String\u003e map : rs) { \n  System.out.println(map.get(\"name\"));\n}\n```\n\n### Filtering results\n\nThe same query, but with the results filtered: Print all interfaces of type 'vlan'.\n\n```java\nList\u003cMap\u003cString, String\u003e\u003e rs = con.execute(\"/interface/print where type=vlan\");\n```\n\n### Selecting returned fields\n\nThe same query, but we only want certain result fields names: Print all interfaces of type 'vlan' and return just their name:\n\n```java\nList\u003cMap\u003cString, String\u003e\u003e rs = con.execute(\"/interface/print where type=vlan return name\");\n```\n\n## Writing data \n\nCreating, modifying and deleting configuration objects is of course possible.\n\n### Creating an object \n\nThis example shows how to create a new GRE interface: \n\n```java\ncon.execute(\"/interface/gre/add remote-address=192.168.1.1 name=gre1 keepalive=10\");\n```\n\n### Modify an existing object\n\nChange the IP address in the object created by the above example:\n\n```java\ncon.execute(\"/interface/gre/set .id=gre1 remote-address=10.0.1.1\"); \n```\n\n### Remove an existing object\n\nAnd now remove the object:\n\n```java\ncon.execute(\"/interface/gre/remove .id=gre1\"); \n```\n\n### Un-setting a variable on an object \n\nUn-setting a variable is a bit different, and you need to use a parameter called `value-name`. This isn't well documented. Let's say you have a firewall rule that was set up like this:\n\n```java\ncon.execute(\"/ip/firewall/filter/add action=accept chain=forward time=00:00:01-01,mon\")\n```\nAssuming the rule can be accessed as `.id=*1`, you un-set it by using `value-name` as seen below:\n\n```java \ncon.execute(\"/ip/firewall/filter/unset .id=*1 value-name=time\");\n```\n\n## Asynchronous commands\n\nWe can run some commands asynchronously in order to continue receiving updates:\n\nThis example shows how to run '/interface wireless monitor' and have the result sent to a listener object, which prints it:\n\n```java\nString tag = con.execute(\"/interface/wireless/monitor .id=wlan1 return signal-to-noise\", \n      new ResultListener() {\n\n            public void receive(Map\u003cString, String\u003e result) {\n                System.out.println(result);\n            }\n\n           public void error(MikrotikApiException e) {\n               System.out.println(\"An error occurred: \" + e.getMessage());\n           }\n\n           public void completed() {\n                System.out.println(\"Asynchronous command has finished\"); \n           }\n            \n        }\n  );\n```\n\nThe `ResultListener` interface has three methods the user needs to implement:\n* `receive()` is called to receive results produced by the router from the API. \n* `error()` is called when an exception is raised based on a 'trap' received from the router or another (typically connection) problem.\n* `completed()` is called when the router has indicated that the command has completed or has been cancelled. \n\nThe 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:\n\n```java\ncon.cancel(tag);\n```\n\n## Command timeouts\n\nCommand 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:\n\n```java\nApiConnection con = ApiConnection.connect(\"10.0.1.1\"); // connect to router\ncon.setTimeout(5000); // set command timeout to 5 seconds\ncon.login(\"admin\",\"password\"); // log in to router\ncon.execute(\"/system/reboot\"); // execute a command\n``` \n \t\nIt is important to note that command timeouts can be set before ```login()``` is called, and can therefore influence the behaviour of login. \n\nThe default command timeout, if none is set by the user, is 60 seconds. \n\n# References\n\nThe RouterOS API is documented here: http://wiki.mikrotik.com/wiki/Manual:API\n\n# Licence\n\nThis library is released under the Apache 2.0 licence. See the [LICENCE.md](LICENCE.md) file\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgideonlegrange%2Fmikrotik-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgideonlegrange%2Fmikrotik-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgideonlegrange%2Fmikrotik-java/lists"}