nmsg

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 27, 2023 License: MPL-2.0 Imports: 10 Imported by: 0

README

Golang bindings for NMSG

cgo-nmsg provides Golang bindings to the C libnmsg library.

The NMSG network message encapsulation library format is an efficient encoding of typed, structured data into payloads which are packed into containers which can be transmitted over the network or stored to disk. For more information, see https://github.com/farsightsec/nmsg/.

A pure but limited Golang NMSG library is available with go-nmsg.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	BufferSizeMax   = int(C.nmsg_wbufsiz_max)
	BufferSizeMin   = int(C.nmsg_wbufsiz_min)
	BufferSizeEther = int(C.nmsg_wbufsiz_ether)
	BufferSizeJumbo = int(C.nmsg_wbufsiz_jumbo)
)

Buffer Size constants from libnmsg

Functions

func ErrorFull 

func ErrorFull(err error) bool

ErrorFull returns true if the container is full. If the Container Add() method returns such an error, the message will need to be added to the next container.

func ErrorOverfull 

func ErrorOverfull(err error) bool

ErrorOverfull returns true if the container contains a single payload and its size is greater than the target size.

func ErrorRetry 

func ErrorRetry(err error) bool

ErrorRetry returns true if the error indicates that the nmsg operation should be retried.

func SetDebug 

func SetDebug(debug int)

SetDebug sets the debug print level for the nmsg library. Debugging messages are sent to stderr. Higher debug values increase verbosity.

Types

type Container 

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

A Container is a collection of NMSG payloads with a target size.

func NewContainer 

func NewContainer(conf *ContainerConfig) *Container

NewContainer creates a container with the given target size.

func (*Container) Add 

func (c *Container) Add(m *Message) error

Add adds the supplied Message to the Container.

func (*Container) Bytes 

func (c *Container) Bytes() []byte

Bytes returns the serialized container and resets the container.

type ContainerConfig 

type ContainerConfig struct {
	Compress bool
	Sequence bool
	Size     int
}

ContainerConfig contains

type Enum 

type Enum struct {
	Value       uint32
	Description string
}

Enum contains both the numeric Value and the string Description of an enumerated NMSG field value.

type IO 

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

IO is a handle to a libnmsg io loop connecting one or more Inputs with one ore more Outputs.

func NewIO 

func NewIO() *IO

NewIO creates and returns a new IO

func (*IO) AddInput 

func (io *IO) AddInput(i Input) error

AddInput adds a separately created Input to the IO as an input.

func (*IO) AddInputChannel 

func (io *IO) AddInputChannel(channel string) error

AddInputChannel opens an NMSG channel and adds it as an Input to the IO.

func (*IO) AddInputSockSpec 

func (io *IO) AddInputSockSpec(sockspec string) error

AddInputSockSpec opens one or more sockets based on the sockspec (add/port ,or addr/lowport..highport) and adds it to the IO as an input.

func (*IO) AddOutput 

func (io *IO) AddOutput(o Output) error

AddOutput adds a separately created Output to the IO as an output.

func (*IO) Break 

func (io *IO) Break()

Break stops the IO main loop.

func (*IO) Run 

func (io *IO) Run() error

Run starts the IO loop, returning when it is finished or broken with Break()

func (*IO) SetDebug 

func (io *IO) SetDebug(debug int)

SetDebug sets the debug print level of the underlying io. Larger numbers are more verbose.

func (*IO) SetMirrored 

func (io *IO) SetMirrored(mirrored bool)

SetMirrored controls whether the IO mirrors output to all outputs (mirrored = true) or stripes its output across all outputs.

type Input 

type Input interface {
	// Read returns a Message or nil, and an error if any.
	Read() (*Message, error)

	// SetFilterMsgtype instructs the input to discard all Messages
	// not of the given vendor id and msgtype, specified by number.
	SetFilterMsgtype(vendor, msgtype uint32)

	// SetFilterMsgtypeByname instructs the input to discard all Messages
	// not of the given vendor id and msgtype, specified by name.
	SetFilterMsgtypeByname(vendor, msgtype string)

	// SetFilterSource instructs the input to discard all Messages not
	// from the supplied source.
	SetFilterSource(source uint32)

	// SetFilterOperator instructs the input to discard all Messages not
	// from the supplied operator.
	SetFilterOperator(operator uint32)

	// SetFilterGroup instructs the input to discard all Messages not
	// in the supplied group.
	SetFilterGroup(group uint32)
}

An Input is a source of NMSG payloads (Messages).

func NewCallbackInput 

func NewCallbackInput(i InputFunc) Input

NewCallbackInput creates an NmsgInput which calls the supplied InputFunc.

func NewInput 

func NewInput(r io.Reader) Input

NewInput creates a new Input from an io.Reader. Currently, the reader must be a *net.UDPConn or a *os.File

type InputFunc 

type InputFunc func() (*Message, error)

An InputFunc is a function with the same signature as Input.Read(), usable directly as an Input.

When used directly as an Input, only the Read() method is implemented. All others are no-ops. If the functionality of the other methods is desired, the InputFunc can be passed to NewCallbackInput.

func (InputFunc) Read 

func (i InputFunc) Read() (*Message, error)

Read calls the underlying function to return the next message.

func (InputFunc) SetFilterGroup 

func (i InputFunc) SetFilterGroup(group uint32)

SetFilterGroup satisfies the Input interface with a no-op

func (InputFunc) SetFilterMsgtype 

func (i InputFunc) SetFilterMsgtype(vendor, msgtype uint32)

SetFilterMsgtype satisfies the Input interface with a no-op

func (InputFunc) SetFilterMsgtypeByname 

func (i InputFunc) SetFilterMsgtypeByname(vendor, msgtype string)

SetFilterMsgtypeByname satisfies the Input interface with a no-op

func (InputFunc) SetFilterOperator 

func (i InputFunc) SetFilterOperator(operator uint32)

SetFilterOperator satisfies the Input interface with a no-op

func (InputFunc) SetFilterSource 

func (i InputFunc) SetFilterSource(source uint32)

SetFilterSource satisfies the Input interface with a no-op

type Message 

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

A Message is a unit of NMSG data.

func NewMessage 

func NewMessage(mod *MessageMod) *Message

NewMessage initializes a message of a type given by the supplied MessageMod

func NewMessageFromPayload 

func NewMessageFromPayload(payload []byte, vendor uint32, msgtype uint32) *Message

NewMessageFromPayload encapsulates a byte buffer in a payload with the supplied vendor and message type.

func UnpackContainer 

func UnpackContainer(b []byte) ([]*Message, error)

UnpackContainer returns the messages the container contains.

func (*Message) GetBytesField 

func (msg *Message) GetBytesField(name string, idx int) ([]byte, error)

GetBytesField retrieves a field of type bytes from a Message.

func (*Message) GetDoubleField 

func (msg *Message) GetDoubleField(name string, idx int) (float64, error)

GetDoubleField retrieves the value of a double field in a Message

func (*Message) GetEnumField 

func (msg *Message) GetEnumField(name string, idx int) (string, error)

GetEnumField returns the string description of a Message field with an enumerated type.

func (*Message) GetIPField 

func (msg *Message) GetIPField(name string, idx int) (net.IP, error)

GetIPField retrieves the value of an IP field in a Message

func (*Message) GetIntField 

func (msg *Message) GetIntField(name string, idx int) (int64, error)

GetIntField retrieves the value of a named field of integer type from a Message.

func (*Message) GetMsgtype 

func (msg *Message) GetMsgtype() (vendor, msgtype uint32)

GetMsgtype returns the vendor and payload type of the message.

func (*Message) GetStringField 

func (msg *Message) GetStringField(name string, idx int) (string, error)

GetStringField retrieves the value of a string field in a Message

func (*Message) GetUintField 

func (msg *Message) GetUintField(name string, idx int) (uint64, error)

GetUintField retrieves the named field of a unsigned int type from a Message. If the field has an enumerated type, the numeric value is retrieved.

func (*Message) Group 

func (msg *Message) Group() uint32

Group returns the group id of the message, or zero if the group id is not set.

func (*Message) MarshalJSON 

func (msg *Message) MarshalJSON() ([]byte, error)

MarshalJSON formats a JSON representation of the Message

func (*Message) MarshalText 

func (msg *Message) MarshalText() ([]byte, error)

MarshalText converts a Message to presentation format.

func (*Message) Operator 

func (msg *Message) Operator() uint32

Operator returns the operator id of the message, or zero if the operator id is not set.

func (*Message) SetBytesField 

func (msg *Message) SetBytesField(name string, idx int, val []byte) error

SetBytesField sets the value of a bytes field in a Message

func (*Message) SetDoubleField 

func (msg *Message) SetDoubleField(name string, idx int, val float64) error

SetDoubleField sets the value of a double field in a Message

func (*Message) SetEnumField 

func (msg *Message) SetEnumField(name string, idx int, vname string) error

SetEnumField sets the value of the named Message field to the value corresponding to the supplied description.

func (*Message) SetGroup 

func (msg *Message) SetGroup(group uint32)

SetGroup sets the group id of the message.

func (*Message) SetIPField 

func (msg *Message) SetIPField(name string, idx int, val net.IP) error

SetIPField sets the value of an IP field in a Message

func (*Message) SetIntField 

func (msg *Message) SetIntField(name string, idx, bitsize int, val int64) error

SetIntField sets the value of an int16, int32, or int64 field in the message. The bitsize field specifies which size, and must by 16, 32, or 64

func (*Message) SetOperator 

func (msg *Message) SetOperator(operator uint32)

SetOperator sets the operator id of the message.

func (*Message) SetSource 

func (msg *Message) SetSource(source uint32)

SetSource sets the source id of the message.

func (*Message) SetStringField 

func (msg *Message) SetStringField(name string, idx int, val string) error

SetStringField sets the value of a string field in a Message

func (*Message) SetUintField 

func (msg *Message) SetUintField(name string, idx, bitsize int, val uint64) error

SetUintField sets the value of a field of type uint16, uint32, or uint64. The bitsize parameter specifies which type, and must be 16, 32, or 64

func (*Message) Source 

func (msg *Message) Source() uint32

Source returns the source id of the message, or zero if the source id is not set.

func (*Message) UnmarshalJSON 

func (msg *Message) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON representation of the Message

type MessageMod 

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

MessageMod something something

func MessageModLookup 

func MessageModLookup(v, m uint32) *MessageMod

MessageModLookup something something

func MessageModLookupByName 

func MessageModLookupByName(vname, mname string) *MessageMod

MessageModLookupByName something something

type Output 

type Output interface {
	// Write sends the supplied message to the Output.
	Write(*Message) error

	// SetBuffered controls whether the output buffers Messages into containers
	// before sending them. NmsgOutputs are buffered by default, but low volume
	// sources may choose to turn this off to reduce latency.
	SetBuffered(bool)

	// SetCompression controls whether the output compresses
	// the container data prior to sending.
	SetCompression(bool)

	// Flush writes any buffered data to the Output.
	Flush() error

	// SetFilterMsgtype instructs the output to discard all Messages
	// not of the supplied vendor and type, specified by number.
	SetFilterMsgtype(vendor, msgtype uint32)

	// SetFilterMsgtypeByname instructs the output to discard all Messages
	// not of the supplied vendor and type, specified by name.
	SetFilterMsgtypeByname(vendor, msgtype string)

	// SetRate sets an output rate limit. The rate is specified
	// in containers per second, and is checked every freq pauses.
	// The freq parameter should be about 10-15% of the rate.
	SetRate(rate *Rate)

	// SetSource instructs the output to set the source parameter
	// of all outbound messages to the supplied value.
	SetSource(source uint32)

	// SetOperator instructs the output to set the operator parameter
	// of all outbound messages to the supplied value.
	SetOperator(group uint32)

	// SetGroup instructs the output to set the group parameter
	// of all outbound messages to the supplied value.
	SetGroup(group uint32)
}

An Output is a destination for NMSG data (Messages)

func NewCallbackOutput 

func NewCallbackOutput(o OutputFunc) Output

NewCallbackOutput creates an NmsgOutput which calls o.Send() on every message.

func NewOutput 

func NewOutput(w io.Writer, bufsiz int) Output

NewOutput creates an output writing to w, with target container size of bufsiz. The Writer currently must be a *os.File or *net.UDPConn.

type OutputFunc 

type OutputFunc func(*Message) error

An OutputFunc is a function with the same signature as Output.Write, usable directly as an Output.

When used directly as an Output, only the Write() method is defined. All others are no-ops.

func (OutputFunc) Flush 

func (o OutputFunc) Flush() error

Flush satisfies the Output interface with a no-op

func (OutputFunc) SetBuffered 

func (o OutputFunc) SetBuffered(bool)

SetBuffered satisfies the Output interface with a no-op

func (OutputFunc) SetCompression 

func (o OutputFunc) SetCompression(bool)

SetCompression satisfies the Output interface with a no-op

func (OutputFunc) SetFilterMsgtype 

func (o OutputFunc) SetFilterMsgtype(vendor, msgtype uint32)

SetFilterMsgtype satisfies the Output interface with a no-op

func (OutputFunc) SetFilterMsgtypeByname 

func (o OutputFunc) SetFilterMsgtypeByname(vendor, msgtype string)

SetFilterMsgtypeByname satisfies the Output interface with a no-op

func (OutputFunc) SetGroup 

func (o OutputFunc) SetGroup(group uint32)

SetGroup satisfies the Output interface with a no-op

func (OutputFunc) SetOperator 

func (o OutputFunc) SetOperator(group uint32)

SetOperator satisfies the Output interface with a no-op

func (OutputFunc) SetRate 

func (o OutputFunc) SetRate(r *Rate)

SetRate satisfies the Output interface with a no-op

func (OutputFunc) SetSource 

func (o OutputFunc) SetSource(source uint32)

SetSource satisfies the Output interface with a no-op

func (OutputFunc) Write 

func (o OutputFunc) Write(m *Message) error

Write calls the underlying function with the supplied message

type Rate 

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

A Rate provides Rate limiting across one or more outputs.

func NewRate 

func NewRate(rate, freq uint) *Rate

NewRate initializes and returns a rate context. The rate parameter specifies the target rate of packets (containers and fragments) sent on all outputs using the Rate. The freq parameter specifies how often (in packets) to check the rate limit.

func (*Rate) Sleep 

func (r *Rate) Sleep()

Sleep pauses for an appropriate amount of time to maintain the given output rate.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.