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
- type 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
- type ClientOptions
- type ParseOpts
- type PasswordLookup
- type SecurityLevel
- type Server
Examples ¶
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
Functions ¶
func ListenAndWrite ¶
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))
Output:
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 ¶
NewAuthFile initializes and returns a new AuthFile.
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 ¶
NewBuffer initializes a new Buffer. If "size" is 0, DefaultBufferSize will be used.
func (*Buffer) Bytes ¶ added in v0.2.0
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) Read ¶
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.
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)
}
Output:
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 ¶
Close writes remaining data to the network and closes the socket. You must not use "c" after this call.
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 ¶
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 {
// 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 ¶
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.
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()))
Output:
Source Files