routeros

README

routeros-api-go

Go library to manage Mikrotik routers using the Mikrotik RouterOS API

Usage

import (
    "github.com/jda/routeros-api-go"
    "fmt"
)
c, err := routeros.New("10.0.0.1:8728")
if err != nil {
    fmt.Errorf("Error parsing address: %s\n", err)
}

err = c.Connect("username", "password")
if err != nil {
    fmt.Errorf("Error connecting to device: %s\n", err)
}

res, err := c.Call("/system/resource/getall", nil)
if err != nil {
    fmt.Errorf("Error getting system resources: %s\n", err)
}

uptime := res.SubPairs[0]["uptime"]
fmt.Printf("Uptime: %s\n", uptime)

Running Tests

You need a device or VM running Mikrotik RouterOS to run tests. Mikrotik provides VM images of RouterOS under the Cloud Hosted Router(CHR) brand. The free edition of CHR is limited to 1Mbps per interface which is more than sufficient for API testing.

I run the VMDK under VMware Fusion with host-only networking. The CHR images are running DHCP client by default so there's no network setup required, just log in to the image and "/ip address print" to discover which address to use. Change the password for the admin user from blank to admin (or whatever you chose): "/user set 0 password=admin"

Test setup

export ROS_TEST_TARGET=VM_IP:API_PORT export ROS_TEST_USER=admin export ROS_TEST_PASSWORD=admin

To Do

• Write better docstrings
• Make README
• Add support for command/response tags
• Add checking for error codes

Documentation

Overview

Package routeros provides a programmatic interface to the Mikrotik RouterOS API

Index

• func GetPairVal(pairs []Pair, key string) (string, error)
• type Client
  • func New(address string) (*Client, error)
  • func (c *Client) Call(command string, params []Pair) (Reply, error)
  • func (c *Client) Close()
  • func (c *Client) Connect(user string, password string) error
  • func (c *Client) ConnectNew(user string, password string) error
  • func (c *Client) Dial() error
  • func (c *Client) Query(command string, q Query) (Reply, error)
  • func (c *Client) Receive() (reply Reply, err error)
  • func (c *Client) WriteWord(word string) error
• type Pair
  • func NewPair(key string, value string) *Pair
• type Query
• type Reply
  • func (r *Reply) GetPairVal(key string) (string, error)
  • func (r *Reply) GetSubPairByName(key string) (map[string]string, error)

Functions

func GetPairVal

func GetPairVal(pairs []Pair, key string) (string, error)

Types

type Client

type Client struct {
	Timeout   time.Duration
	TLSConfig *tls.Config
	// contains filtered or unexported fields
}

Client is a RouterOS API client.

func New

func New(address string) (*Client, error)

Create a new instance of the RouterOS API client

func (*Client) Call

func (c *Client) Call(command string, params []Pair) (Reply, error)

func (*Client) Close

func (c *Client) Close()

func (*Client) Connect

func (c *Client) Connect(user string, password string) error

func (*Client) ConnectNew

func (c *Client) ConnectNew(user string, password string) error

func (*Client) Dial

func (c *Client) Dial() error

func (*Client) Query

func (c *Client) Query(command string, q Query) (Reply, error)

func (*Client) Receive

func (c *Client) Receive() (reply Reply, err error)

func (*Client) WriteWord

func (c *Client) WriteWord(word string) error

type Pair

type Pair struct {
	Key   string
	Value string
	// Op is used for Query words to signify logical operations
	// valid operators are -, =, <, >
	// see http://wiki.mikrotik.com/wiki/Manual:API#Queries for details.
	Op string
}

Pair is a Key-Value pair for RouterOS Attribute, Query, and Reply words use slices of pairs instead of map because we care about order

func NewPair

func NewPair(key string, value string) *Pair

type Query

type Query struct {
	Pairs    []Pair
	Op       string
	Proplist []string
}

type Reply

type Reply struct {
	Pairs    []Pair
	SubPairs []map[string]string
}

A reply can contain multiple pairs. A pair is a string key->value. A reply can also contain subpairs, that is, a array of pair arrays.

func (*Reply) GetPairVal

func (r *Reply) GetPairVal(key string) (string, error)

func (*Reply) GetSubPairByName

func (r *Reply) GetSubPairByName(key string) (map[string]string, error)