network plugin¶

See this section in the full configuration reference

The Network plugin sends data to a remote instance of collectd, receives data from a remote instance, or both at the same time. Data which has been received from the network is usually not transmitted again, but this can be activated, see the Forward option below.

The default IPv6 multicast group is ff18::efc0:4a42. The default IPv4 multicast group is 239.192.74.66. The default UDP port is 25826.

Both, Server and Listen can be used as single option or as block. When used as block, given options are valid for this socket only. The following example will export the metrics twice: Once to an "internal" server (without encryption and signing) and one to an external server (with cryptographic signature):

<Plugin "network">
  # Export to an internal server
  # (demonstrates usage without additional options)
  Server "collectd.internal.tld"

  # Export to an external server
  # (demonstrates usage with signature options)
  <Server "collectd.external.tld">
    SecurityLevel "sign"
    Username "myhostname"
    Password "ohl0eQue"
  </Server>
</Plugin>

<Server Host [Port]>

The Server statement/block sets the server to send datagrams to. The statement may occur multiple times to send each datagram to multiple destinations.

The argument Host may be a hostname, an IPv4 address or an IPv6 address. The optional second argument specifies a port number or a service name. If not given, the default, 25826, is used.

The following options are recognized within Server blocks:

SecurityLevel Encrypt|Sign|None

Set the security you require for network communication. When the security level has been set to Encrypt, data sent over the network will be encrypted using AES-256. The integrity of encrypted packets is ensured using SHA-1. When set to Sign, transmitted data is signed using the HMAC-SHA-256 message authentication code. When set to None, data is sent without any security.

This feature is only available if the network plugin was linked with libgcrypt.

Username Username

Sets the username to transmit. This is used by the server to lookup the password. See AuthFile below. All security levels except None require this setting.

This feature is only available if the network plugin was linked with libgcrypt.

Password Password

Sets a password (shared secret) for this socket. All security levels except None require this setting.

This feature is only available if the network plugin was linked with libgcrypt.

Interface Interface name

Set the outgoing interface for IP packets. This applies at least to IPv6 packets and if possible to IPv4. If this option is not applicable, undefined or a non-existent interface name is specified, the default behavior is to let the kernel choose the appropriate interface. Be warned that the manual selection of an interface for unicast traffic is only necessary in rare cases.

BindAddress IP Address

Set the outgoing IP address for IP packets. This option can be used instead of the Interface option to explicitly define the IP address which will be used to send Packets to the remote server.

ResolveInterval Seconds

Sets the interval at which to re-resolve the DNS for the Host. This is useful to force a regular DNS lookup to support a high availability setup. If not specified, re-resolves are never attempted.

<Listen Host [Port]>

The Listen statement sets the interfaces to bind to. When multiple statements are found the daemon will bind to multiple interfaces.

The argument Host may be a hostname, an IPv4 address or an IPv6 address. If the argument is a multicast address the daemon will join that multicast group. The optional second argument specifies a port number or a service name. If not given, the default, 25826, is used.

The following options are recognized within <ListenE<gt> blocks:

SecurityLevel Encrypt|Sign|None

Set the security you require for network communication. When the security level has been set to Encrypt, only encrypted data will be accepted. The integrity of encrypted packets is ensured using SHA-1. When set to Sign, only signed and encrypted data is accepted. When set to None, all data will be accepted. If an AuthFile option was given (see below), encrypted data is decrypted if possible.

This feature is only available if the network plugin was linked with libgcrypt.

AuthFile Filename

Sets a file in which usernames are mapped to passwords. These passwords are used to verify signatures and to decrypt encrypted network packets. If SecurityLevel is set to None, this is optional. If given, signed data is verified and encrypted packets are decrypted. Otherwise, signed data is accepted without checking the signature and encrypted data cannot be decrypted. For the other security levels this option is mandatory.

The file format is very simple: Each line consists of a username followed by a colon and any number of spaces followed by the password. To demonstrate, an example file could look like this:

user0: foo
user1: bar

Each time a packet is received, the modification time of the file is checked using stat(2). If the file has been changed, the contents is re-read. While the file is being read, it is locked using fcntl(2).

Interface Interface name

Set the incoming interface for IP packets explicitly. This applies at least to IPv6 packets and if possible to IPv4. If this option is not applicable, undefined or a non-existent interface name is specified, the default behavior is, to let the kernel choose the appropriate interface. Thus incoming traffic gets only accepted, if it arrives on the given interface.

TimeToLive 1-255

Set the time-to-live of sent packets. This applies to all, unicast and multicast, and IPv4 and IPv6 packets. The default is to not change this value. That means that multicast packets will be sent with a TTL of 1 (one) on most operating systems.

MaxPacketSize 1024-65535

Set the maximum size for datagrams received over the network. Packets larger than this will be truncated. Defaults to 1452E<nbsp>bytes, which is the maximum payload size that can be transmitted in one Ethernet frame using IPv6E<nbsp>/ UDP.

On the server side, this limit should be set to the largest value used on any client. Likewise, the value on the client must not be larger than the value on the server, or data will be lost.

Compatibility: Versions prior to versionE<nbsp4.8> used a fixed sized buffer of 1024E<nbsp>bytes. Versions 4.8, 4.9 and 4.10 used a default value of 1024E<nbsp>bytes to avoid problems when sending data to an older server.

Forward true|false

If set to true, write packets that were received via the network plugin to the sending sockets. This should only be activated when the Listen- and Server-statements differ. Otherwise packets may be send multiple times to the same multicast group. While this results in more network traffic than necessary it's not a huge problem since the plugin has a duplicate detection, so the values will not loop.

ReportStats true|false

The network plugin cannot only receive and send statistics, it can also create statistics about itself. Collectd data included the number of received and sent octets and packets, the length of the receive queue and the number of values handled. When set to true, the Network plugin will make these statistics available. Defaults to false.