Skip to main content

Python API to RouterBoard devices produced by MikroTik.

Project description

RouterOS-api

Build Status Latest Version Supported Python versions Wheel Status License

Python API to RouterBoard devices produced by MikroTik written by Social WiFi.

Social WiFi logo

Usage

Connection

import routeros_api

connection = routeros_api.RouterOsApiPool('IP', username='admin', password='', plaintext_login=True)
api = connection.get_api()

Use plaintext_login=True option when connecting to RouterOS version 6.43 and newer.

Connection parameters

routeros_api.RouterOsApiPool(
    host,
    username='admin',
    password='',
    port=8728,
    plaintext_login=True,
    use_ssl=False,
    ssl_verify=True,
    ssl_verify_hostname=True,
    ssl_context=None,
)

Parameters:

  • host - String - Hostname or IP of device

Optional Parameters:

  • username - String - Login username - Default 'admin'
  • password - String - Login password - Default empty string
  • port - Integer - TCP Port for API - Default 8728 or 8729 when using SSL
  • plaintext_login - Boolean - Try plaintext login (for RouterOS 6.43 onwards) - Default False
  • use_ssl - Boolean - Use SSL or not? - Default False
  • ssl_verify - Boolean - Verify the SSL certificate? - Default True
  • ssl_verify_hostname - Boolean - Verify the SSL certificate hostname matches? - Default True
  • ssl_context - Object - Pass in a custom SSL context object. Overrides other options. - Default None

Using SSL

If we want to use SSL, we can simply specify use_ssl as True:

connection = routeros_api.RouterOsApiPool('<IP>', username='admin', password='', use_ssl=True)

This will automatically verify SSL certificate and hostname. The most flexible way to modify SSL parameters is to provide an SSL Context object using the ssl_context parameter, but for typical use-cases with self-signed certificates, the shorthand options of ssl_verify and ssl_verify_hostname are provided.

e.g. if using a self-signed certificate, you can (but probably shouldn't) use:

connection = routeros_api.RouterOsApiPool(
    '<IP>',
    username='admin',
    password='',
    use_ssl=True,
    ssl_verify=False,
    ssl_verify_hostname=False,
)

Login for RouterOS v6.43 onwards

RouterOS Versions v6.43 onwards now use a different login method. The disadvantage is that it passes the password in plain text. For security we only attempt the plaintext login if requested using the plaintext_login parameter. It is highly recommended only to use this option with SSL enabled.

routeros_api.RouterOsApiPool(host, username='admin', password='', plaintext_login=True)

Handling non UTF-8 characters

The API does not assume any particular encoding, so non utf-8 characters will not be shown correctly. A default encoding can be specified if needed. For some cases the latin-1 encoding will be the best one to use, for others - windows-1250 will work better. Ref. https://forum.mikrotik.com/viewtopic.php?t=106053#p528460

It is possible to use specific encoding by defining custom default structure like this:

import collections
import routeros_api
from routeros_api.api_structure import StringField

connection = routeros_api.RouterOsApiPool('ip', username='admin', password='password', plaintext_login=True)
api = connection.get_api()
# This part here is important:
default_structure = collections.defaultdict(lambda: StringField(encoding='windows-1250'))
api.get_resource('/system/identity', structure=default_structure).get()

Execute Commands

Call this with a resource and parameters as name/value pairs.

api.get_resource('/').call('<resource>', { <dict of params> })

You can also use the "binary" version, but in this case, all dict values should be encoded to bytes and the result will be returned as bytes.

api.get_binary_resource('/').call('<resource>', { <dict of params> })

Examples

>>> api.get_resource('/tool').call('fetch', {'url': 'http://example.com', 'dst-path': 'output.html'})
[{'status': 'connecting', '.section': '0'}, {'status': 'finished', 'downloaded': '1', 'total': '1', 'duration': '1s', '.section': '1'}]

>>> api.get_resource('/').call('ping', {'address': '8.8.8.8', 'count': '4'})
[
 {'seq': '0', 'host': '8.8.8.8', 'size': '56', 'ttl': '58', 'time': '14ms612us', 'sent': '1', 'received': '1', 'packet-loss': '0', 'min-rtt': '14ms612us', 'avg-rtt': '14ms612us', 'max-rtt': '14ms612us'}, 
 {'seq': '1', 'host': '8.8.8.8', 'size': '56', 'ttl': '58', 'time': '22ms237us', 'sent': '2', 'received': '2', 'packet-loss': '0', 'min-rtt': '14ms612us', 'avg-rtt': '18ms424us', 'max-rtt': '22ms237us'}, 
 {'seq': '2', 'host': '8.8.8.8', 'size': '56', 'ttl': '58', 'time': '13ms823us', 'sent': '3', 'received': '3', 'packet-loss': '0', 'min-rtt': '13ms823us', 'avg-rtt': '16ms890us', 'max-rtt': '22ms237us'}, 
 {'seq': '3', 'host': '8.8.8.8', 'size': '56', 'ttl': '58', 'time': '8ms614us', 'sent': '4', 'received': '4', 'packet-loss': '0', 'min-rtt': '8ms614us', 'avg-rtt': '14ms821us', 'max-rtt': '22ms237us'}
]

Fetch List/Resource

list = api.get_resource('/command')

Example

list_queues = api.get_resource('/queue/simple')

Show all elements

list_queues.get()

Add rules

list.add(attribute='vale', attribute_n='value')

NOTE: Attributes with -, like max-limit use underscore _: max_limit

Example:

list_queues.add(name='001', max_limit='512k/4M', target='192.168.10.1/32')

Update Values

list.set(id, attributes)

Example:

list_queues.set(id='*2', name='john')

Get element:

list.get(attribute=value)

Example:

list_queues.get(name='john')

Remove element:

list.remove(id)

Example:

list_queues.remove(id='*2')

Close conection:

connection.disconnect()

Return results and count of results

Let's take DHCP leases as an example.

CLI: /ip/dhcp-server/lease/print

api.get_resource('/ip/dhcp-server/lease').get()

Now, let's use count-only.

CLI: /ip/dhcp-server/lease/print count-only (returns 13)

>>> api.get_resource('/ip/dhcp-server/lease').call('print', {'count-only': None}).done_message

{'ret': '13'}

Now, let's use count-only and where.

CLI: /ip/dhcp-server/lease/print count-only where server=developers (returns 4)

>>> api.get_resource('/ip/dhcp-server/lease').call('print', {'count-only': None}, {'server': 'developers'}).done_message

{'ret': '4'}

Now, let's use count-only and where with boolean value.

CLI: /ip/route/pri count-only where static (returns 1)

>>> api.get_resource('/ip/route').call('print', {'count-only': None}, {'static': 'yes'}).done_message

{'ret': '1'}

Run script and get output

The example script only prints "hello". Here's a simplified example of how to run it and get the output:

>>> api.get_resource('/system/script').get()[0]['source']
'/put "hello"'
>>> response = api.get_resource('/system/script').call('run', {'number': '0'})
>>> response.done
True
>>> response.done_message['ret']
'hello'

Run monitor and get output

CLI command: /interface/ethernet/poe/monitor numbers=0 once

>>> response = api.get_resource('/interface/ether/poe').call('monitor', {'numbers': '0', 'once': None})
>>> response
[{'name': 'ether10', 'poe-out': 'auto-on', 'poe-out-status': 'waiting-for-load'}]

Set value using numbers

CLI command: /interface/ethernet/poe set poe-out=off 0

api.get_resource('/interface/ethernet/poe').call('set', {'poe-out': 'off', 'numbers': '0'}

Set value using id

>> api.get_resource('/interface/ethernet/poe').call('print')
[{'id': '*B', 'name': 'ether10', 'poe-out': 'off', 'poe-priority': '10', 'poe-lldp-enabled': 'false', 'power-cycle-ping-enabled': 'false', 'power-cycle-interval': 'none'}]

>> api.get_resource('/interface/ethernet/poe').call('set', {'poe-out': 'off', '.id': "*B"})

Add and remove item

list_address = api.get_resource('/ip/firewall/address-list')
list_address.add(address='192.168.0.1', comment='P1', list='10M')
response = list_address.get(comment='P1')
list_address.remove(id=response[0]['id'])

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

routeros_api-0.21.0.tar.gz (14.3 kB view details)

Uploaded Source

Built Distribution

routeros_api-0.21.0-py2.py3-none-any.whl (22.7 kB view details)

Uploaded Python 2Python 3

File details

Details for the file routeros_api-0.21.0.tar.gz.

File metadata

  • Download URL: routeros_api-0.21.0.tar.gz
  • Upload date:
  • Size: 14.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.2

File hashes

Hashes for routeros_api-0.21.0.tar.gz
Algorithm Hash digest
SHA256 0d37452a4ff85cd476dca392068d7d76ba430c9b055c39d8dabc5930a997d82d
MD5 1974fb42fb692b8707ba1892db5559ac
BLAKE2b-256 3b3d414cfbdc91ca6cf127cde120178ec0961caec4b1810e654f2d4520a475b7

See more details on using hashes here.

File details

Details for the file routeros_api-0.21.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for routeros_api-0.21.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 4189c11bdeae0d8d654b1f1212f3654a54f0df8e4ec0bcb4d5bc31303a7f76d0
MD5 c32482d5770aa6f8dc04de4a27aefc36
BLAKE2b-256 d50005f60d90a041ff61fce514cf8db3d5b8401e45a1baad1b1b1cde814f5c27

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page