collectd.org: collectd.org/network Index | Examples | Files

package network

import "collectd.org/network"

Package network implements collectd's binary network protocol.

Index

Examples

Package Files

buffer.go client.go crypto.go main.go parse.go server.go

Constants

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

Well-known addresses and port.

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

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

func ListenAndWrite Uses

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.

Code:

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 Uses

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 Uses

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 Uses

func NewAuthFile(name string) *AuthFile

NewAuthFile initializes and returns a new AuthFile.

func (*AuthFile) Password Uses

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

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

type Buffer Uses

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 Uses

func NewBuffer(size int) *Buffer

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

func (*Buffer) Available Uses

func (b *Buffer) Available() int

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

func (*Buffer) Bytes Uses

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 Uses

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

Encrypt enables encryption of data.

func (*Buffer) Read Uses

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 Uses

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

Sign enables cryptographic signing of data.

func (*Buffer) Write Uses

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 Uses

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

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

type Client Uses

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

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

Code:

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 Uses

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 Uses

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 Uses

func (c *Client) Flush() error

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

func (*Client) Write Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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.

Code:

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

// blocks
log.Fatal(srv.ListenAndWrite(context.Background()))

Package network imports 22 packages (graph) and is imported by 66 packages. Updated 2020-05-06. Refresh now. Tools for package owners.