go-routeros

The repository provides several example implementations to demonstrate different ways to interact with Mikrotik devices via the RouterOS API:

• Run: Basic execution patterns (examples/run/main.go).
• Listen: Implementing a listener pattern (examples/listen/main.go).
• Tab: Tabular or interactive usage (examples/tab/main.go).

To install the RouterOS Client for Go, use the following command to fetch the v3 module:

go get github.com/go-routeros/routeros/v3

Note: The project has moved away from gopkg.in. Ensure your import paths use the Go module format: github.com/go-routeros/routeros/v3.

When a listening session ends, the ListenReply.Done field is populated based on the sentence received from RouterOS. The following special sentences determine the state of the listener:

For detailed technical specifications of the exported functions, types, and methods, refer to the official Go documentation:

https://pkg.go.dev/github.com/go-routeros/routeros/v3

Call Close() to gracefully shut down the connection to the RouterOS device. This closes the underlying io.ReadWriteCloser and the internal protocol reader/writer. It is safe to call multiple times.

defer client.Close()

Use the Dial family of functions to establish a TCP connection and authenticate with a RouterOS device in a single step. These functions handle the connection, the /login command, and any necessary MD5 challenge-response cycles automatically.

Available connection methods:

• Dial(address, username, password): Standard TCP connection using context.Background().
• DialTimeout(address, username, password, timeout): TCP connection with a specified timeout.
• DialContext(ctx, address, username, password): TCP connection using a provided context.Context for cancellation or deadlines.

import "github.com/go-routeros/routeros/v3"

// Connect with a timeout
client, err := routeros.DialTimeout("192.168.88.1:8728", "admin", "password", 5 * time.Second)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

If you already have an established io.ReadWriteCloser (such as a custom net connection), you can wrap it in a routeros.Client using NewClient.

Note: When using NewClient, you must manually call Login or LoginContext to authenticate before executing commands.

// Assuming 'conn' is an io.ReadWriteCloser
client, err := routeros.NewClient(conn)
if err != nil {
    log.Fatal(err)
}

// You MUST login manually after using NewClient
err = client.Login("admin", "password")
if err != nil {
    log.Fatal(err)
}

The Login and LoginContext methods execute the /login command on the RouterOS device. This method is compatible with both modern RouterOS versions (post-6.43) which use a single-stage cleartext login, and older versions that require a two-stage MD5 challenge-response.

• Login(username, password): Uses context.Background().
• LoginContext(ctx, username, password): Uses the provided context for lifecycle management.

err := client.LoginContext(ctx, "admin", "password")
if err != nil {
    log.Fatal(err)
}

The Reply struct represents the complete response received from a RouterOS API call. It aggregates multiple proto.Sentence objects into two categories:

1. Re: A slice of *proto.Sentence containing the actual data/sentences returned by the command.
2. Done: A single *proto.Sentence indicating the end of the response stream.

You can use the String() method on a Reply instance to get a newline-delimited string representation of all sentences contained within the reply.

// Example of what a Reply structure looks like conceptually
reply := &routeros.Reply{
    Re:   []*proto.Sentence{/* ... data sentences ... */},
    Done: &proto.Sentence{/* ... done sentence ... */},
}

// Get a string representation of the entire response
fmt.Println(reply.String())

Call Async() on a *Client instance to start asynchronous mode. This allows the client to process multiple requests concurrently by listening for tagged sentences from the RouterOS device. Async() returns immediately and provides a receive-only error channel (<-chan error) that will receive an error if the asynchronous loop terminates unexpectedly. If the client is already in asynchronous mode, the channel will receive errAlreadyAsync.

// Assuming 'client' is an initialized *routeros.Client
errChan := client.Async()

// Monitor the error channel in a separate goroutine or after your operations
go func() {
    if err := <-errChan;
        err != nil {
        log.Printf("Async mode error: %v", err)
    }
}()

Use AsyncContext(ctx context.Context) to start asynchronous mode with a specific lifecycle controlled by the provided context.Context. If the context is canceled or reaches its deadline, the asynchronous loop will be terminated and the underlying connection will be canceled. Like Async(), it returns a <-chan error to signal if the background loop fails.

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

errChan := client.AsyncContext(ctx)

// The loop will stop if ctx is canceled