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:

s := gosnmp.NewGoSNMP("192.168.0.1", "public", gosnmp.Version2c)
resp, err := s.Get(".1.3.6.1.2.1.1.1.0")

if err == nil {
  switch resp.Type {
    case OctetString:
      fmt.Printf("Response: %s\n", string(resp.Value))
  }
}

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 (
    EndOfContents    Asn1BER = 0x00
    Boolean                  = 0x01
    Integer                  = 0x02
    BitString                = 0x03
    OctetString              = 0x04
    Null                     = 0x05
    ObjectIdentifier         = 0x06
    ObjectDesription         = 0x07
    IpAddress                = 0x40
    Counter32                = 0x41
    Gauge32                  = 0x42
    TimeTicks                = 0x43
    Opaque                   = 0x44
    NsapAddress              = 0x45
    Counter64                = 0x46
    Uinteger32               = 0x47
    NoSuchObject             = 0x80
    NoSuchInstance           = 0x81
)

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

Testing

Many, many thanks to Andreas Louca for writing alouca/gosnmp. The major difference between his version and soniah/gosnmp is that the latter has tests written. (However the code could do with refactoring). The tests were used to find and correct errors in the following SNMP BER Types:

• Counter32
• Gauge32
• Counter64
• OctetString
• ObjectIdentifier
• IpAddress

Also, this version contains functions for treating the returned snmp values as *big.Int (convenient, as SNMP can return int32, uint32, and uint64 values):

func ToBigInt(value interface{}) *big.Int

Running the Tests

The tests use the Verax Snmp Simulator [1]; setup Verax before running "go test":

• download, install and run Verax with the default configuration

• in the gosnmp directory, setup these symlinks (or equivalents for your system):

  ln -s /usr/local/vxsnmpsimulator/device device ln -s /usr/local/vxsnmpsimulator/conf/devices.conf.xml devices.conf.xml

• remove randomising elements from Verax device files:

  cd device/cisco sed -i -e 's!//$.!!' -e 's!^M!!' cisco_router.txt sed -i -e 's///^int.unq()^///2/' cisco_router.txt cd ../os sed -i -e 's!//$.!!' -e 's!^M!!' os-linux-std.txt sed -i -e 's///^int.unq()^///2/' os-linux-std.txt

[1] http://www.veraxsystems.com/en/products/snmpsimulator

Documentation

Index

• Constants
• func ParseUint16(content []byte) int
• func ToBigInt(value interface{}) *big.Int
• type Asn1BER
• type BitStringValue
  • func (b BitStringValue) At(i int) int
  • func (b BitStringValue) RightAlign() []byte
• type GoSNMP
  • func NewGoSNMP(target string, port uint16, community string, version SnmpVersion, ...) (*GoSNMP, error)
  • func (x *GoSNMP) Debug(data []byte) (*SnmpPacket, error)
  • func (x *GoSNMP) Get(oid string) (result *SnmpPacket, err error)
  • func (x *GoSNMP) SetDebug(d bool)
  • func (x *GoSNMP) SetTimeout(seconds int64)
  • func (x *GoSNMP) SetVerbose(v bool)
  • func (x *GoSNMP) StreamWalk(oid string, c chan *Variable) error
  • func (x *GoSNMP) Walk(oid string) ([]*Variable, error)
• type Message
• type MessageType
• type PDU
• type PDUResponse
• type SnmpPDU
• type SnmpPacket
  • func Unmarshal(packet []byte) (*SnmpPacket, error)
• type SnmpVersion
  • func (s SnmpVersion) String() string
• type VarBind
• type Variable

Constants

const (
	EndOfContents    Asn1BER = 0x00
	Boolean                  = 0x01
	Integer                  = 0x02
	BitString                = 0x03
	OctetString              = 0x04
	Null                     = 0x05
	ObjectIdentifier         = 0x06
	ObjectDesription         = 0x07
	IpAddress                = 0x40
	Counter32                = 0x41
	Gauge32                  = 0x42
	TimeTicks                = 0x43
	Opaque                   = 0x44
	NsapAddress              = 0x45
	Counter64                = 0x46
	Uinteger32               = 0x47
	NoSuchObject             = 0x80
	NoSuchInstance           = 0x81
)

const (
	Sequence       MessageType = 0x30
	GetRequest     MessageType = 0xa0
	GetNextRequest             = 0xa1
	GetResponse                = 0xa2
	SetRequest                 = 0xa3
	Trap                       = 0xa4
	GetBulkRequest             = 0xa5
)

Functions

func ParseUint16

func ParseUint16(content []byte) int

Parses UINT16

func ToBigInt

func ToBigInt(value interface{}) *big.Int

ToBigInt converts SnmpPDU.Value to big.Int, or returns a zero big.Int for non int-like types (eg strings).

This is a convenience function to make working with SnmpPDU's easier - it reduces the need for type assertions. A big.Int is convenient, as SNMP can return int32, uint32, and uint64.

Types

type Asn1BER

type Asn1BER byte

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 GoSNMP

type GoSNMP struct {
	Target    string
	Port      uint16
	Community string
	Version   SnmpVersion
	Timeout   time.Duration
	Conn      net.Conn
	Log       *l.Logger
}

func NewGoSNMP

func NewGoSNMP(target string, port uint16, community string, version SnmpVersion, timeout int64) (*GoSNMP, error)

func (*GoSNMP) Debug

func (x *GoSNMP) Debug(data []byte) (*SnmpPacket, error)

Debug function

func (*GoSNMP) Get

func (x *GoSNMP) Get(oid string) (result *SnmpPacket, err error)

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

func (*GoSNMP) SetDebug

func (x *GoSNMP) SetDebug(d bool)

Enables debugging

func (*GoSNMP) SetTimeout

func (x *GoSNMP) SetTimeout(seconds int64)

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

func (*GoSNMP) SetVerbose

func (x *GoSNMP) SetVerbose(v bool)

Enables verbose logging

func (*GoSNMP) StreamWalk

func (x *GoSNMP) StreamWalk(oid string, c chan *Variable) 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

func (*GoSNMP) Walk

func (x *GoSNMP) Walk(oid string) ([]*Variable, error)

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

type Message

type Message struct {
	Version   int
	Community []uint8
	Data      asn1.RawValue
}

type MessageType

type MessageType byte

type PDU

type PDU struct {
	RequestId   int32
	ErrorStatus int
	ErrorIndex  int
	VarBindList []VarBind
}

type PDUResponse

type PDUResponse struct {
	RequestId   int32
	ErrorStatus int
	ErrorIndex  int
	VarBindList []*Variable
}

type SnmpPDU

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

type SnmpPacket

type SnmpPacket struct {
	Version     SnmpVersion
	Community   string
	RequestType MessageType
	RequestID   uint8
	Error       uint8
	ErrorIndex  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 VarBind

type VarBind struct {
	Name  asn1.ObjectIdentifier
	Value asn1.RawValue
}

type Variable

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