routeros

README

RouterOS Client for the Go language

Go library for accessing Mikrotik devices using the RouterOS API.

Look in the examples directory to learn how to use this library: run, listen, tab.

API documentation is available at pkg.go.dev.
Page on the Mikrotik Wiki.

Usage of gopkg.in was removed in favor of Go modules. Please, update you import paths to github.com/go-routeros/routeros/v3.

Current version: v3 and newest,

Old released versions: v2, v1

To install it, run: go get github.com/go-routeros/routeros/v3

Documentation

Overview

Package routeros is a pure Go client library for accessing Mikrotik devices using the RouterOS API.

Index

• Variables
• type Client
  • func Dial(address, username, password string) (*Client, error)
  • func DialContext(ctx context.Context, address, username, password string) (*Client, error)
  • func DialTLS(address, username, password string, tlsConfig *tls.Config) (*Client, error)
  • func DialTLSContext(ctx context.Context, address, username, password string, tlsConfig *tls.Config) (*Client, error)
  • func DialTLSTimeout(address, username, password string, tlsConfig *tls.Config, ...) (*Client, error)
  • func DialTimeout(address, username, password string, timeout time.Duration) (*Client, error)
  • func NewClient(rwc io.ReadWriteCloser) (*Client, error)
  • func (c *Client) Async() <-chan error
  • func (c *Client) AsyncContext(ctx context.Context) <-chan error
  • func (c *Client) Close() error
  • func (c *Client) IsAsync() bool
  • func (c *Client) Listen(sentence ...string) (*ListenReply, error)
  • func (c *Client) ListenArgs(sentence []string) (*ListenReply, error)
  • func (c *Client) ListenArgsContext(ctx context.Context, sentence []string) (*ListenReply, error)
  • func (c *Client) ListenArgsQueue(sentence []string, queueSize int) (*ListenReply, error)
  • func (c *Client) ListenArgsQueueContext(ctx context.Context, sentence []string, queueSize int) (*ListenReply, error)
  • func (c *Client) ListenContext(ctx context.Context, sentence ...string) (*ListenReply, error)
  • func (c *Client) Login(username, password string) error
  • func (c *Client) LoginContext(ctx context.Context, username, password string) error
  • func (c *Client) Run(sentences ...string) (*Reply, error)
  • func (c *Client) RunArgs(sentences []string) (*Reply, error)
  • func (c *Client) RunArgsContext(ctx context.Context, sentences []string) (*Reply, error)
  • func (c *Client) RunContext(ctx context.Context, sentences ...string) (*Reply, error)
  • func (c *Client) SetLogHandler(handler LogHandler)
• type DeviceError
  • func (err *DeviceError) Error() string
• type ListenReply
  • func (l *ListenReply) Cancel() (*Reply, error)
  • func (l *ListenReply) CancelContext(ctx context.Context) (*Reply, error)
  • func (l *ListenReply) Chan() <-chan *proto.Sentence
  • func (a *ListenReply) Err() error
• type LogHandler
• type Reply
  • func (r *Reply) String() string
• type UnknownReplyError
  • func (err *UnknownReplyError) Error() string

Variables

var (
	ErrNoChallengeReceived      = errors.New("no ret (challenge) received")
	ErrInvalidChallengeReceived = errors.New("invalid ret (challenge) hex string received")
)

Types

type Client

type Client struct {
	Queue int
	// contains filtered or unexported fields
}

Client is a RouterOS API client.

func Dial

func Dial(address, username, password string) (*Client, error)

Dial connects and logs in to a RouterOS device.

func DialContext

func DialContext(ctx context.Context, address, username, password string) (*Client, error)

DialContext connects and logs in to a RouterOS device using context.

func DialTLS

func DialTLS(address, username, password string, tlsConfig *tls.Config) (*Client, error)

DialTLS connects and logs in to a RouterOS device using TLS.

func DialTLSContext

func DialTLSContext(ctx context.Context, address, username, password string, tlsConfig *tls.Config) (*Client, error)

DialTLSContext connects and logs in to a RouterOS device using TLS and context.

func DialTLSTimeout

func DialTLSTimeout(address, username, password string, tlsConfig *tls.Config, timeout time.Duration) (*Client, error)

DialTLSTimeout connects and logs in to a RouterOS device using TLS with timeout.

func DialTimeout

func DialTimeout(address, username, password string, timeout time.Duration) (*Client, error)

DialTimeout connects and logs in to a RouterOS device with timeout.

func NewClient

func NewClient(rwc io.ReadWriteCloser) (*Client, error)

NewClient returns a new Client over rwc. Login must be called.

func (*Client) Async

func (c *Client) Async() <-chan error

Async starts asynchronous mode and returns immediately.

func (*Client) AsyncContext

func (c *Client) AsyncContext(ctx context.Context) <-chan error

AsyncContext starts asynchronous mode with context and returns immediately.

func (*Client) Close

func (c *Client) Close() error

Close closes the connection to the RouterOS device.

func (*Client) IsAsync

func (c *Client) IsAsync() bool

IsAsync return true if client run in async mode.

func (*Client) Listen

func (c *Client) Listen(sentence ...string) (*ListenReply, error)

Listen simply calls ListenArgsQueue() with queueSize set to c.Queue.

func (*Client) ListenArgs

func (c *Client) ListenArgs(sentence []string) (*ListenReply, error)

ListenArgs simply calls ListenArgsQueue() with queueSize set to c.Queue.

func (*Client) ListenArgsContext

func (c *Client) ListenArgsContext(ctx context.Context, sentence []string) (*ListenReply, error)

ListenArgsContext simply calls ListenArgsQueue() with queueSize set to c.Queue.

func (*Client) ListenArgsQueue

func (c *Client) ListenArgsQueue(sentence []string, queueSize int) (*ListenReply, error)

ListenArgsQueue sends a sentence to the RouterOS device and returns immediately.

func (*Client) ListenArgsQueueContext

func (c *Client) ListenArgsQueueContext(ctx context.Context, sentence []string, queueSize int) (*ListenReply, error)

ListenArgsQueueContext sends a sentence to the RouterOS device and returns immediately.

func (*Client) ListenContext

func (c *Client) ListenContext(ctx context.Context, sentence ...string) (*ListenReply, error)

ListenContext simply calls ListenArgsQueue() with queueSize set to c.Queue.

func (*Client) Login

func (c *Client) Login(username, password string) error

Login runs the /login command. Dial and DialTLS call this automatically.

func (*Client) LoginContext

func (c *Client) LoginContext(ctx context.Context, username, password string) error

LoginContext runs the /login command. DialContext and DialTLSContext call this automatically.

func (*Client) Run

func (c *Client) Run(sentences ...string) (*Reply, error)

Run simply calls RunArgs().

func (*Client) RunArgs

func (c *Client) RunArgs(sentences []string) (*Reply, error)

RunArgs sends a sentence to the RouterOS device and waits for the reply.

func (*Client) RunArgsContext

func (c *Client) RunArgsContext(ctx context.Context, sentences []string) (*Reply, error)

RunArgsContext sends a sentence to the RouterOS device and waits for the reply.

func (*Client) RunContext

func (c *Client) RunContext(ctx context.Context, sentences ...string) (*Reply, error)

RunContext simply calls RunArgsContext().

func (*Client) SetLogHandler

func (c *Client) SetLogHandler(handler LogHandler)

type DeviceError

type DeviceError struct {
	Sentence *proto.Sentence
}

DeviceError records the sentence containing the error received from the device. The sentence may have Word !trap or !fatal.

func (*DeviceError) Error

func (err *DeviceError) Error() string

type ListenReply

type ListenReply struct {
	Done *proto.Sentence
	// contains filtered or unexported fields
}

ListenReply is the struct returned by the Listen*() functions. When the channel returned by Chan() is closed, Done is set to the RouterOS sentence that caused it to be closed.

func (*ListenReply) Cancel

func (l *ListenReply) Cancel() (*Reply, error)

Cancel sends a cancel command to the RouterOS device.

func (*ListenReply) CancelContext

func (l *ListenReply) CancelContext(ctx context.Context) (*Reply, error)

CancelContext sends a cancel command to the RouterOS device with context.

func (*ListenReply) Chan

func (l *ListenReply) Chan() <-chan *proto.Sentence

Chan returns a channel for receiving !re RouterOS sentences. To close the channel, call Cancel() on l.

func (*ListenReply) Err

func (a *ListenReply) Err() error

Err returns the first error that happened processing sentences with tag.

type LogHandler

type LogHandler slog.Handler

type Reply

type Reply struct {
	Re   []*proto.Sentence
	Done *proto.Sentence
}

Reply has all the sentences from a reply.

func (*Reply) String

func (r *Reply) String() string

type UnknownReplyError

type UnknownReplyError struct {
	Sentence *proto.Sentence
}

UnknownReplyError records the sentence whose Word is unknown.

func (*UnknownReplyError) Error

func (err *UnknownReplyError) Error() string