snmp

Documentation

Index

• Variables
• type DataType
• type Handler
• type PDU
• type Server
• type ServerFactory
  • func NewServerFactory() ServerFactory
• type ServerHooks
• type ServerOption
  • func Address(value string) ServerOption
  • func Hooks(trace *ServerHooks) ServerOption
  • func Port(value int) ServerOption
  • func ServerNetwork(value string) ServerOption
• type Session
• type SessionConfig
• type SessionFactory
  • func NewFactory() SessionFactory
• type SessionOption
  • func Community(value string) SessionOption
  • func LoggingHooks(trace *SessionTrace) SessionOption
  • func Network(value string) SessionOption
  • func Retries(value int) SessionOption
  • func Timeout(timeout time.Duration) SessionOption
  • func WithVersion(value Version) SessionOption
• type SessionTrace
• type TypedValue
  • func (tv *TypedValue) Int() int
  • func (tv *TypedValue) OID() asn1.ObjectIdentifier
  • func (tv *TypedValue) String() string
• type Varbind
• type Version
• type Walker

Variables

var DefaultLoggingHooks = &SessionTrace{
	Error: func(location string, config *SessionConfig, err error) {
		log.Printf("SNMP-Error context:%s target:%s err:%v\n", location, config.address, err)
	},
}

DefaultLoggingHooks provides a default logging hook to report errors.

var DefaultServerHooks = &ServerHooks{
	Error: func(config *serverConfig, err error) {
		log.Printf("Error target:%s err:%v\n", config.address, err)
	},
	WriteComplete: func(config *serverConfig, addr net.Addr, output []byte, err error) {
		if err != nil {
			log.Printf("WriteComplete target:%s err:%v\n", addr, err)
		}
	},
	ReadComplete: func(config *serverConfig, addr net.Addr, input []byte, err error) {
		if err != nil {
			log.Printf("ReadComplete source:%s err:%v\n", addr, err)
		}
	},
}

DefaultServerHooks provides a default logging hook to report server errors.

var DiagnosticLoggingHooks = &SessionTrace{
	ConnectStart: func(config *SessionConfig) {
		log.Printf("SNMP-ConnectStart target:%s\n", config.address)
	},
	ConnectDone: MetricLoggingHooks.ConnectDone,
	Error:       DefaultLoggingHooks.Error,
	WriteDone: func(config *SessionConfig, output []byte, err error, d time.Duration) {
		log.Printf("SNMP-WriteDone target:%s err:%v took:%dms data:%s\n", config.address, err, d.Milliseconds(), hex.EncodeToString(output))
	},
	ReadDone: func(config *SessionConfig, input []byte, err error, d time.Duration) {
		log.Printf("SNMP-ReadDone target:%s err:%v took:%dms data:%s\n", config.address, err, d.Milliseconds(), hex.EncodeToString(input))
	},
}

DiagnosticLoggingHooks provides a set of hooks that log all events with all data.

var DiagnosticServerHooks = &ServerHooks{
	StartListening: func(addr net.Addr) {
		log.Printf("StartListening address:%s\n", addr)
	},
	StopListening: func(addr net.Addr, err error) {
		log.Printf("StopListening address:%s err:%v\n", addr, err)
	},
	Error: func(config *serverConfig, err error) {
		log.Printf("Error err:%v\n", err)
	},
	WriteComplete: func(config *serverConfig, addr net.Addr, output []byte, err error) {
		log.Printf("WriteComplete target:%s err:%v data:%s\n", addr, err, hex.EncodeToString(output))
	},
	ReadComplete: func(config *serverConfig, addr net.Addr, input []byte, err error) {
		log.Printf("ReadComplete source:%s err:%v data:%s\n", addr, err, hex.EncodeToString(input))
	},
}

DiagnosticServerHooks provides a set of default diagnostic server hooks

var MetricLoggingHooks = &SessionTrace{
	ConnectDone: func(config *SessionConfig, err error, d time.Duration) {
		log.Printf("SNMP-ConnectDone target:%s err:%v took:%dms\n", config.address, err, d.Milliseconds())
	},
	Error: DefaultLoggingHooks.Error,
	WriteDone: func(config *SessionConfig, output []byte, err error, d time.Duration) {
		log.Printf("SNMP-WriteDone target:%s err:%v took:%dms\n", config.address, err, d.Milliseconds())
	},
	ReadDone: func(config *SessionConfig, input []byte, err error, d time.Duration) {
		log.Printf("SNMP-ReadDone target:%s err:%v took:%dms\n", config.address, err, d.Milliseconds())
	},
}

MetricLoggingHooks provides a set of hooks that log metrics.

var NoOpLoggingHooks = &SessionTrace{
	ConnectStart: func(config *SessionConfig) {},
	ConnectDone:  func(config *SessionConfig, err error, d time.Duration) {},
	Error:        func(location string, config *SessionConfig, err error) {},
	WriteDone:    func(config *SessionConfig, output []byte, err error, d time.Duration) {},
	ReadDone:     func(config *SessionConfig, input []byte, err error, d time.Duration) {},
}

NoOpLoggingHooks provides set of hooks that do nothing.

var NoOpServerHooks = &ServerHooks{
	StartListening: func(addr net.Addr) {},
	StopListening:  func(addr net.Addr, err error) {},
	Error:          func(config *serverConfig, err error) {},
	WriteComplete:  func(config *serverConfig, addr net.Addr, output []byte, err error) {},
	ReadComplete:   func(config *serverConfig, addr net.Addr, input []byte, err error) {},
}

NoOpServerHooks provides set of server hooks that do nothing.

Types

type DataType

type DataType int

DataType is used to define the different types of variable found in variable bindings.

const (
	Integer DataType = iota
	OctetString
	OID

	IPAdddress
	Time
	Counter32
	Counter64
	Gauge32
	Opaque

	EndOfMib
	NoSuchObject
	NoSuchInstance
)

type Handler

type Handler interface {
	// NewMessage is called when a trap/inform message has been received.
	// pdu defines the content of the message.
	// isInform defines the message type.
	// sourceAddr is the address which originated the message
	// Note that a NewMessage invocation will block the receipt of other messages.
	// In the case of an inform message, it will also block the transmission of the acknowledgement message.
	// It is the responsibility of the Handler implementation to return in a timely fashion.
	NewMessage(pdu *PDU, isInform bool, sourceAddr net.Addr)
}

Handler is the interface that needs to be supported by the callback provided when a server is instantiated.

type PDU

type PDU struct {
	RequestID int32
	// Non-zero used to indicate that an exception occurred to prevent the processing of the request
	Error int
	// If Error is non-zero, identifies which variable binding in the list caused the exception
	ErrorIndex  int
	VarbindList []Varbind
}

PDU defines an SNMP PDU, as returned by the Get/GetNext methods. Note that it differs from rawPDU in that the variable bindings define value using golang types, rather than the ASN.1 transport format.

type Server

type Server io.Closer

Server provides an interface for receiving Trap and Inform messages. This is only defined because it will facilitate unit testing of calling code that might want to mock the server factory.

type ServerFactory

type ServerFactory interface {
	// NewServer instantiates an SNMP Trap/Inform server.
	NewServer(ctx context.Context, handler Handler, opts ...ServerOption) (Server, error)
}

SewrverFactory defines an interface for instantiating SNMP Trap/Inform servers.

func NewServerFactory

func NewServerFactory() ServerFactory

Delivers a new server factory.

type ServerHooks

type ServerHooks struct {
	// StartListening is called when the server is about to start listening for messages.
	StartListening func(addr net.Addr)

	// StopListening is called when the server has stopped listening.
	StopListening func(addr net.Addr, err error)

	// Error is called after an error condition has been detected.
	Error func(config *serverConfig, err error)

	// WriteComplete is called after a packet has been written
	WriteComplete func(config *serverConfig, addr net.Addr, output []byte, err error)

	// ReadComplete is called after a read has completed
	ReadComplete func(config *serverConfig, addr net.Addr, input []byte, err error)
}

ServerHooks defines a structure for handling server hook events

type ServerOption

type ServerOption func(*serverConfig)

ServerOption implements options for configuring server behaviour.

func Address

func Address(value string) ServerOption

Address defines the address on which to listen. Default value is ""

func Hooks

func Hooks(trace *ServerHooks) ServerOption

Hooks defines a set of hooks to be invoked by the server. Default value is DefaultServerHooks.

func Port

func Port(value int) ServerOption

Port defines the port on which to listen. Default value is 162.

func ServerNetwork

func ServerNetwork(value string) ServerOption

ServerNetwork defines the transport network. Default value is udp

type Session

type Session interface {
	// Issues an SNMP GET request for the specified oids.
	// Get request processing is described at https://tools.ietf.org/html/rfc1905#section-4.2.1.
	Get(ctx context.Context, oids []string) (*PDU, error)

	// Issues an SNMP GET NEXT request for the specified oids.
	// Get Bext request processing is described athttps://tools.ietf.org/html/rfc1905#section-4.2.2.
	GetNext(ctx context.Context, oids []string) (*PDU, error)

	// Issues an SNMP GET BULK request for the specified oids.
	// Get Bulk request processing is described at https://tools.ietf.org/html/rfc1905#section-4.2.3
	GetBulk(ctx context.Context, oids []string, nonRepeaters int, maxRepetitions int) (*PDU, error)

	// Issues SNMP GET NEXT requests starting from the specified root oid, invoking the function walker for each
	// variable that is a descendant of the root oid.
	Walk(ctx context.Context, rootOid string, walker Walker) error

	// Issues SNMP GET BULK requests starting from the specified root oid, invoking the function walker for each
	// variable that is a descendant of the root oid.
	BulkWalk(ctx context.Context, rootOid string, maxRepetitions int, walker Walker) error

	// Embed standard Close()
	io.Closer
}

Session provides an interface for SNMP device management.

type SessionConfig

type SessionConfig struct {
	// contains filtered or unexported fields
}

SessionConfig defines properties controlling session behaviour.

type SessionFactory

type SessionFactory interface {
	// NewSession instantiates an SNMP session for managing the target device.
	NewSession(ctx context.Context, target string, opts ...SessionOption) (Session, error)
}

Defines a factory method for instantiating SNMP Sessions.

func NewFactory

func NewFactory() SessionFactory

Delivers a new session factory.

type SessionOption

type SessionOption func(*SessionConfig)

SessionOption implements options for configuring session behaviour.

func Community

func Community(value string) SessionOption

Commmunity defines the community string to be used. Default value is public.

func LoggingHooks

func LoggingHooks(trace *SessionTrace) SessionOption

LoggingHooks defines a set of logging hooks to be used by the session. Default value is DefaultLoggingHooks.

func Network

func Network(value string) SessionOption

Network defines the transport network. Default value is udp

func Retries

func Retries(value int) SessionOption

Retries defines the number of times an unsuccessful request will be retried. Default value is 0

func Timeout

func Timeout(timeout time.Duration) SessionOption

Timeout defines the timeout for receiving a response to a request Default value is 1s.

func WithVersion

func WithVersion(value Version) SessionOption

WithVersion defines the SNMP version to use. Default value is SNMPV2C

type SessionTrace

type SessionTrace struct {
	// ConnectStart is called before establishing a network connection to an agent.
	ConnectStart func(config *SessionConfig)

	// ConnectDone is called when the network connection attempt completes, with err indicating
	// whether it was successful.
	ConnectDone func(config *SessionConfig, err error, d time.Duration)

	// Error is called after an error condition has been detected.
	Error func(location string, config *SessionConfig, err error)

	// WriteDone is called after a packet has been written
	WriteDone func(config *SessionConfig, output []byte, err error, d time.Duration)

	// ReadDone is called after a read has completed
	ReadDone func(config *SessionConfig, input []byte, err error, d time.Duration)
}

SessionTrace defines a structure for handling trace events

type TypedValue

type TypedValue struct {
	Type  DataType
	Value interface{}
}

Encapsulates the data type and value of a variable received in a variable binding from an agent.

func (*TypedValue) Int

func (tv *TypedValue) Int() int

Delivers value of a typed value as an int. Value type must be integer-based.

func (*TypedValue) OID

func (tv *TypedValue) OID() asn1.ObjectIdentifier

Delivers value of a typed value as an ObjectIdentifier. Value type must be OID!

func (*TypedValue) String

func (tv *TypedValue) String() string

Delivers value of a typed value as a string.

type Varbind

type Varbind struct {
	OID        asn1.ObjectIdentifier
	TypedValue *TypedValue
}

type Version

type Version int

SNMP Versions.

const (
	SNMPV1  Version = 0
	SNMPV2C Version = 1
	SNMPV3  Version = 3
)

type Walker

type Walker func(vb *Varbind) error

Walker defines a function that will be called for each variable processed by the Walk/BulkWalk methods. If the function returns an error, the walk will be terminated.