gosnmp

README

gosnmp

GoSNMP is a simple SNMP client library, written fully in Go. Currently it supports only GetRequest (with the rest GetNextRequest, SetRequest in the pipe line). Support for traps is also in the plans.

Install

The easiest way to install is via go get:

go get github.com/alouca/gosnmp

License

Some parts of the code are borrowed by the Golang project (specifically some functions for unmarshaling BER responses), which are under the same terms and conditions as the Go language, which are marked appropriately in the source code. The rest of the code is under the BSD license.

See the LICENSE file for more details.

Usage

The library usage is pretty simple:

// Connect to 192.168.0.1 with timeout of 5 seconds

import (
	go-snmp
	"log"
)

s, err := gosnmp.NewGoSNMP("61.147.69.87", "public", gosnmp.Version2c, 5)
if err != nil {
	log.Fatal(err)
}
resp, err := s.Get(".1.3.6.1.2.1.1.1.0")
if err == nil {
	for _, v := range resp.Variables {
		switch v.Type {
		case gosnmp.OctetString:
			log.Printf("Response: %s : %s : %s \n", v.Name, v.Value.(string), v.Type.String())
		}
	}
}

The response value is always given as an interface{} depending on the PDU response from the SNMP server. For an example checkout examples/example.go.

Responses are a struct of the following format:

type Variable struct {
  Name  asn1.ObjectIdentifier
  Type  Asn1BER
  Value interface{}
}

Where Name is the OID encoded as an object identifier, Type is the encoding type of the response and Value is an interface{} type, with the response appropriately decoded.

SNMP BER Types can be one of the following:

type Asn1BER byte

const (
  Integer          Asn1BER = 0x02
	BitString                = 0x03
	OctetString              = 0x04
	Null                     = 0x05
	ObjectIdentifier         = 0x06
	Counter32                = 0x41
	Gauge32                  = 0x42
	TimeTicks                = 0x43
	Opaque                   = 0x44
	NsapAddress              = 0x45
	Counter64                = 0x46
	Uinteger32               = 0x47
)

GoSNMP supports most of the above values, subsequent releases will support all of them.

Documentation

Index

• Constants
• func Uvarint(buf []byte) (x uint64)
• type Asn1BER
  • func (dataType Asn1BER) String() string
• type BitStringValue
  • func (b BitStringValue) At(i int) int
  • func (b BitStringValue) RightAlign() []byte
• type Client
  • func NewClient(host, community string, version SnmpVersion, timeout int64) (*Client, error)
  • func (c *Client) BulkWalk(maxRepetitions uint8, oid string) ([]SnmpPDU, error)
  • func (c *Client) Close() error
  • func (c *Client) Debug(data []byte) (*SnmpPacket, error)
  • func (c *Client) Get(oids ...string) (*SnmpPacket, error)
  • func (c *Client) GetBulk(nonRepeaters, maxRepetitions uint8, oids ...string) (*SnmpPacket, error)
  • func (c *Client) GetNext(oid string) (*SnmpPacket, error)
  • func (c *Client) SetTimeout(seconds int64)
  • func (c *Client) StreamWalk(oid string, pdus chan SnmpPDU) error
  • func (c *Client) Walk(oid string) ([]SnmpPDU, error)
• type RawBER
• type SnmpPDU
• type SnmpPacket
  • func Unmarshal(packet []byte) (*SnmpPacket, error)
• type SnmpVersion
  • func (s SnmpVersion) String() string
• type Variable

Examples

• Client.Get

Constants

const (
	Integer          Asn1BER = 0x02
	BitString                = 0x03
	OctetString              = 0x04
	Null                     = 0x05
	ObjectIdentifier         = 0x06
	Sequence                 = 0x30
	IpAddress                = 0x40
	Counter32                = 0x41
	Gauge32                  = 0x42
	TimeTicks                = 0x43
	Opaque                   = 0x44
	NsapAddress              = 0x45
	Counter64                = 0x46
	Uinteger32               = 0x47
	NoSuchObject             = 0x80
	NoSuchInstance           = 0x81
	GetRequest               = 0xa0
	GetNextRequest           = 0xa1
	GetResponse              = 0xa2
	SetRequest               = 0xa3
	Trap                     = 0xa4
	GetBulkRequest           = 0xa5
	EndOfMibView             = 0x82
)

SNMP Data Types

Functions

func Uvarint

func Uvarint(buf []byte) (x uint64)

Types

type Asn1BER

type Asn1BER byte

func (Asn1BER) String

func (dataType Asn1BER) String() string

type BitStringValue

type BitStringValue struct {
	Bytes     []byte // bits packed into bytes.
	BitLength int    // length in bits.
}

BitStringValue is the structure to use when you want an ASN.1 BIT STRING type. A bit string is padded up to the nearest byte in memory and the number of valid bits is recorded. Padding bits will be zero.

func (BitStringValue) At

func (b BitStringValue) At(i int) int

At returns the bit at the given index. If the index is out of range it returns false.

func (BitStringValue) RightAlign

func (b BitStringValue) RightAlign() []byte

RightAlign returns a slice where the padding bits are at the beginning. The slice may share memory with the BitString.

type Client

type Client struct {
	Host      string
	Community string
	Version   SnmpVersion
	Timeout   time.Duration
	// contains filtered or unexported fields
}

Client represents the SNMP client

func NewClient

func NewClient(host, community string, version SnmpVersion, timeout int64) (*Client, error)

NewClient creates a new SNMP client. Host is the IP address, Community the SNMP Community String and Version the SNMP version. Currently only v2c is supported. Timeout parameter is measured in seconds.

func (*Client) BulkWalk

func (c *Client) BulkWalk(maxRepetitions uint8, oid string) ([]SnmpPDU, error)

BulkWalk sends an walks the target using SNMP BULK-GET requests. This returns a Variable with the response and the error condition

func (*Client) Close

func (c *Client) Close() error

Close closes the UDP client connection.

func (*Client) Debug

func (c *Client) Debug(data []byte) (*SnmpPacket, error)

Debug function. Unmarshals raw bytes and returns the result without the network part

func (*Client) Get

func (c *Client) Get(oids ...string) (*SnmpPacket, error)

Get sends an SNMP GET request to the target. Returns a Variable with the response or an error

Example

package main

import (
	"fmt"
	"log"

	snmp "github.com/mwalto7/gosnmp"
)

func main() {
	// Create a new SNMP client connection and defer closing the connection.
	client, err := snmp.NewClient("host", "public", snmp.Version2c, 5)
	if err != nil {
		log.Fatalf("failed to dial: %v", err)
	}
	defer client.Close()

	// Get the client's sysDescr.0 OID.
	resp, err := client.Get("1.3.6.1.2.1.1.1.0")
	if err != nil {
		log.Fatalf("failed to get oid: %v", err)
	}

	// Loop through the response variables.
	for _, v := range resp.Variables {
		// Handle the SNMP types you expect.
		switch v.Type {
		case snmp.OctetString:
			fmt.Printf("%s: %s = %s\n", v.Name, v.Type.String(), v.Value.([]byte))
		}
	}
}

func (*Client) GetBulk

func (c *Client) GetBulk(nonRepeaters, maxRepetitions uint8, oids ...string) (*SnmpPacket, error)

GetBulk sends an SNMP BULK-GET request to the target. Returns a Variable with the response or an error

func (*Client) GetNext

func (c *Client) GetNext(oid string) (*SnmpPacket, error)

GetNext sends an SNMP Get Next Request to the target. Returns the next variable response from the OID given or an error

func (*Client) SetTimeout

func (c *Client) SetTimeout(seconds int64)

SetTimeout sets the timeout for network read/write functions. Defaults to 5 seconds.

func (*Client) StreamWalk

func (c *Client) StreamWalk(oid string, pdus chan SnmpPDU) error

StreamWalk will start walking a specified OID, and push through a channel the results as it receives them, without waiting for the whole process to finish to return the results. Once it has completed the walk, the channel is closed.

func (*Client) Walk

func (c *Client) Walk(oid string) ([]SnmpPDU, error)

Walk will SNMP walk the target, blocking until the process is complete

type RawBER

type RawBER struct {
	Type         Asn1BER
	HeaderLength uint64
	DataLength   uint64
	Data         []byte
	BERVariable  *Variable
}

type SnmpPDU

type SnmpPDU struct {
	Name  string
	Type  Asn1BER
	Value interface{}
}

type SnmpPacket

type SnmpPacket struct {
	Version        SnmpVersion
	Community      string
	RequestType    Asn1BER
	RequestID      uint32
	Error          uint8
	ErrorIndex     uint8
	NonRepeaters   uint8
	MaxRepetitions uint8
	Variables      []SnmpPDU
}

func Unmarshal

func Unmarshal(packet []byte) (*SnmpPacket, error)

type SnmpVersion

type SnmpVersion uint8

const (
	Version1  SnmpVersion = 0x0
	Version2c SnmpVersion = 0x1
)

func (SnmpVersion) String

func (s SnmpVersion) String() string

type Variable

type Variable struct {
	Name  []int
	Type  Asn1BER
	Size  uint64
	Value interface{}
}