network

Documentation

Overview

Package network implements collectd's binary network protocol.

Index

• Constants
• Variables
• func ListenAndWrite(ctx context.Context, address string, d api.Writer) error
• func Parse(b []byte, opts ParseOpts) ([]*api.ValueList, error)
• type AuthFile
  • func NewAuthFile(name string) *AuthFile
  • func (a *AuthFile) Password(user string) (string, error)
• type Buffer
  • func NewBuffer(size int) *Buffer
  • func (b *Buffer) Available() int
  • func (b *Buffer) Bytes() ([]byte, error)
  • func (b *Buffer) Encrypt(username, password string)
  • func (b *Buffer) Read(out []byte) (int, error)
  • func (b *Buffer) Sign(username, password string)
  • func (b *Buffer) Write(_ context.Context, vl *api.ValueList) error
  • func (b *Buffer) WriteTo(w io.Writer) (int64, error)
• type Client
  • func Dial(address string, opts ClientOptions) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Flush() error
  • func (c *Client) Write(ctx context.Context, vl *api.ValueList) error
• type ClientOptions
• type ParseOpts
• type PasswordLookup
• type SecurityLevel
• type Server
  • func (srv *Server) ListenAndWrite(ctx context.Context) error

Examples

• Client
• ListenAndWrite
• Server.ListenAndWrite

Constants

const (
	DefaultIPv4Address = "239.192.74.66"
	DefaultIPv6Address = "ff18::efc0:4a42"
	DefaultService     = "25826"
)

Well-known addresses and port.

const DefaultBufferSize = 1452

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

Variables

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

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

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

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

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

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

Functions

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.

Example

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("example.com", DefaultService), opts)
if err != nil {
	log.Fatal(err)
}
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.

Types

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

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.

Example

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

vl := &api.ValueList{
	Identifier: api.Identifier{
		Host:   "example.com",
		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 {
	log.Fatal(err)
}

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
	Sign
	Encrypt
)

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

type Server

type Server struct {
	Addr           string         // UDP address to listen on.
	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 address, parses the received packets and writes them to the provided api.Writer.

Example

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
log.Fatal(srv.ListenAndWrite(context.Background()))