Version: v0.5.0 Latest Latest

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

Go to latest
Published: Jun 5, 2020 License: ISC Imports: 22 Imported by: 44



Package network implements collectd's binary network protocol.




View Source
const (
	DefaultIPv4Address = ""
	DefaultIPv6Address = "ff18::efc0:4a42"
	DefaultService     = "25826"
	DefaultPort        = 25826

Well-known addresses and port.

View Source
const DefaultBufferSize = 1452

DefaultBufferSize is the default size of "Buffer". This is based on the maximum bytes that fit into an Ethernet frame without fragmentation:

<Ethernet frame> - (<IPv6 header> + <UDP header>) = 1500 - (40 + 8) = 1452


View Source
var ErrInvalid = errors.New("invalid data")

ErrInvalid is returned when parsing the network data was aborted due to illegal data format.

View Source
var ErrNotEnoughSpace = errors.New("not enough space")

ErrNotEnoughSpace is returned when adding a ValueList would exeed the buffer size.

View Source
var ErrUnknownType = errors.New("unknown type")

ErrUnknownType is returned when attempting to write values of an unknown type


func ListenAndWrite

func ListenAndWrite(ctx context.Context, address string, d api.Writer) error

ListenAndWrite listens on the provided UDP address, parses the received packets and writes them to the provided api.Writer. This is a convenience function for a minimally configured server. If you need more control, see the "Server" type below.


This example demonstrates how to forward received IPv6 multicast traffic to a unicast address, using PSK encryption.

opts := ClientOptions{
	SecurityLevel: Encrypt,
	Username:      "collectd",
	Password:      "dieXah7e",
client, err := Dial(net.JoinHostPort("", DefaultService), opts)
if err != nil {
defer client.Close()

// blocks
log.Fatal(ListenAndWrite(context.Background(), ":"+DefaultService, client))

func Parse

func Parse(b []byte, opts ParseOpts) ([]*api.ValueList, error)

Parse parses the binary network format and returns a slice of ValueLists. If a parse error is encountered, all ValueLists parsed to this point are returned as well as the error. Unknown "parts" are silently ignored.


type AuthFile

type AuthFile struct {
	// contains filtered or unexported fields

AuthFile implements the PasswordLookup interface in the same way the collectd network plugin implements it, i.e. by stat'ing and reading a file.

The file has a very simple syntax with one username / password mapping per line, separated by a colon. For example:

alice: w0nderl4nd
bob:   bu1|der

func NewAuthFile

func NewAuthFile(name string) *AuthFile

NewAuthFile initializes and returns a new AuthFile.

func (*AuthFile) Password

func (a *AuthFile) Password(user string) (string, error)

Password looks up a user in the file and returns the associated password.

type Buffer

type Buffer struct {
	// contains filtered or unexported fields

Buffer contains the binary representation of multiple ValueLists and state optimally write the next ValueList.

func NewBuffer

func NewBuffer(size int) *Buffer

NewBuffer initializes a new Buffer. If "size" is 0, DefaultBufferSize will be used.

func (*Buffer) Available

func (b *Buffer) Available() int

Available returns the number of bytes still available in the buffer.

func (*Buffer) Bytes added in v0.2.0

func (b *Buffer) Bytes() ([]byte, error)

Bytes returns the content of the buffer as a byte slice. If signing or encrypting are enabled, the content will be signed / encrypted prior to being returned. This method resets the buffer.

func (*Buffer) Encrypt

func (b *Buffer) Encrypt(username, password string)

Encrypt enables encryption of data.

func (*Buffer) Read

func (b *Buffer) Read(out []byte) (int, error)

Read reads the buffer into "out". If signing or encryption is enabled, data will be signed / encrypted before writing it to "out". Returns ErrNotEnoughSpace if the provided buffer is too small to hold the entire packet data.

func (*Buffer) Sign

func (b *Buffer) Sign(username, password string)

Sign enables cryptographic signing of data.

func (*Buffer) Write

func (b *Buffer) Write(_ context.Context, vl *api.ValueList) error

Write adds a ValueList to the buffer. Returns ErrNotEnoughSpace if not enough space in the buffer is available to add this value list. In that case, call Read() to empty the buffer and try again.

func (*Buffer) WriteTo

func (b *Buffer) WriteTo(w io.Writer) (int64, error)

WriteTo writes the buffer contents to "w". It implements the io.WriteTo interface.

type Client

type Client struct {
	// contains filtered or unexported fields

Client is a connection to a collectd server. It implements the api.Writer interface.

ctx := context.Background()
conn, err := Dial(net.JoinHostPort("", DefaultService), ClientOptions{})
if err != nil {
defer conn.Close()

vl := &api.ValueList{
	Identifier: api.Identifier{
		Host:   "",
		Plugin: "golang",
		Type:   "gauge",
	Time:     time.Now(),
	Interval: 10 * time.Second,
	Values:   []api.Value{api.Gauge(42.0)},

if err := conn.Write(ctx, vl); err != nil {

func Dial

func Dial(address string, opts ClientOptions) (*Client, error)

Dial connects to the collectd server at address. "address" must be a network address accepted by net.Dial().

func (*Client) Close

func (c *Client) Close() error

Close writes remaining data to the network and closes the socket. You must not use "c" after this call.

func (*Client) Flush

func (c *Client) Flush() error

Flush writes the contents of the underlying buffer to the network immediately.

func (*Client) Write

func (c *Client) Write(ctx context.Context, vl *api.ValueList) error

Write adds a ValueList to the internal buffer. Data is only written to the network when the buffer is full.

type ClientOptions

type ClientOptions struct {
	// SecurityLevel determines whether data is signed, encrypted or sent
	// in plain text.
	SecurityLevel SecurityLevel
	// Username and password for the "Sign" and "Encrypt" security levels.
	Username, Password string
	// Size of the send buffer. When zero, DefaultBufferSize is used.
	BufferSize int

ClientOptions holds configuration options for Client.

type ParseOpts

type ParseOpts struct {
	// PasswordLookup is used lookup passwords to verify signed data and
	// decrypt encrypted data.
	PasswordLookup PasswordLookup
	// SecurityLevel determines the minimum security level expected by the
	// caller. If set to "Sign", only signed and encrypted data is returned
	// by Parse(), if set to "Encrypt", only encrypted data is returned.
	SecurityLevel SecurityLevel
	// TypesDB for looking up DS names and verify data source types.
	TypesDB *api.TypesDB

ParseOpts holds confiruation options for "Parse()".

type PasswordLookup

type PasswordLookup interface {
	Password(user string) (string, error)

PasswordLookup is used when parsing signed and encrypted network traffic to look up the password associated with a given username.

type SecurityLevel

type SecurityLevel int

SecurityLevel determines whether data is signed, encrypted or used without any protection.

const (
	None SecurityLevel = iota

Predefined security levels. "None" is used for plain text.

type Server

type Server struct {
	// UDP connection the server listens on. If Conn is nil, a new server
	// connection is opened. The connection is closed by ListenAndWrite
	// before returning.
	Conn *net.UDPConn
	// Address to listen on if Conn is nil. If Addr is empty, too, then the
	// "any" interface and the DefaultService will be used.
	Addr           string
	Writer         api.Writer     // Object used to send incoming ValueLists to.
	BufferSize     uint16         // Maximum packet size to accept.
	PasswordLookup PasswordLookup // User to password lookup.
	SecurityLevel  SecurityLevel  // Minimal required security level.
	TypesDB        *api.TypesDB   // TypesDB for looking up DS names and verify data source types.
	// Interface is the name of the interface to use when subscribing to a
	// multicast group. Has no effect when using unicast.
	Interface string

Server holds parameters for running a collectd server.

func (*Server) ListenAndWrite

func (srv *Server) ListenAndWrite(ctx context.Context) error

ListenAndWrite listens on the provided UDP connection (or creates one using Addr if Conn is nil), parses the received packets and writes them to the provided api.Writer.


This example demonstrates how to listen to encrypted network traffic and dump it to STDOUT using format.Putval.

srv := &Server{
	Addr:           net.JoinHostPort("::", DefaultService),
	Writer:         format.NewPutval(os.Stdout),
	PasswordLookup: NewAuthFile("/etc/collectd/users"),

// blocks

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL