UDP (im_udp)

This module accepts UDP datagrams on the configured address and port. UDP is the transport protocol of the legacy BSD Syslog as described in RFC 3164, so this module can be particularly useful to receive such messages from older devices that do not support other protocols.

To examine the supported platforms, see the list of installation packages.

UDP is an unreliable transport protocol and does not guarantee delivery. Messages may not be received or may be truncated. It is recommended to use the TCP or SSL transport modules instead, if possible.

To reduce the likelihood of message loss, consider:

increasing the socket buffer size with SockBufSize,
raising the route priority by setting the Priority directive (to a low number such as 1), and
adding additional buffering by increasing the LogqueueSize or adding a pm_buffer instance.

This module does not provide access control. Firewall rules can be used to deny connections from certain hosts.

For parsing syslog messages, see the parse_syslog_bsd() procedure of the xm_syslog module.

Configuration

The im_udp module accepts the following directives in addition to the common module directives.

Optional directives

InputType

This directive is identical to the InputType common module directive.

The default is Dgram, meaning the module waits until the buffer is full before processing the record.

ListenAddr

Set this directive to the IP address or DNS hostname on which the module accepts connections. The default is localhost, which restricts access to the local machine and prevents connections from remote hosts.

Append the port number to the address using a colon separator (host:port). The default port is 514. For IPv6 addresses, enclose the address in square brackets ([addr]:port). Use 0.0.0.0:514 for IPv4 or [::]:514 for IPv6 to accept connections on all interfaces. NXLog Agent requires additional privileges to bind to ports below 1024 on Linux. See Granting additional Linux capabilities for more information.

You can specify this directive multiple times to accept connections on multiple addresses or ports within a single module instance. Set IPv4 and IPv6 addresses as separate entries. If you use a DNS name, keep the number of addresses or CNAMEs below 16 to avoid errors caused by DNS response size limits.

AllowIP

Set this directive to restrict incoming connections to specific IP addresses or networks. You can specify this directive multiple times to allow multiple IPs or networks. AllowIP has no effect unless ListenAddr is configured.

If AllowIP is not set, the module falls back to BlockIP to deny specific connections. If neither AllowIP nor BlockIP is set, the module does not restrict incoming connections.

The following IP address formats may be used:

0.0.0.0 (IPv4 address)
0.0.0.0/32 (IPv4 network with subnet bits)
0.0.0.0/0.0.0.0 (IPv4 network with subnet address)
aa::1 (IPv6 address)
aa::12/64 (IPv6 network with subnet bits)

BlockIP

Set this directive to deny incoming connections from specific IP addresses or networks. You can specify this directive multiple times to deny multiple IPs or networks. BlockIP has no effect unless ListenAddr is configured.

If BlockIP is not set, the module falls back to AllowIP to restrict incoming connections. If neither BlockIP nor AllowIP is set, the module does not restrict incoming connections.

The following IP address formats may be used:

0.0.0.0 (IPv4 address)
0.0.0.0/32 (IPv4 network with subnet bits)
0.0.0.0/0.0.0.0 (IPv4 network with subnet address)
aa::1 (IPv6 address)
aa::12/64 (IPv6 network with subnet bits)

MaxConnections

Set this directive to limit the number of concurrent active connections for a listening TCP socket. The default is 4294967295 (unlimited). When the limit is reached, the module rejects new connections and logs an error:

Number of allowed active connections(10) reached: 10. Refusing connection from 127.0.0.1

ConnectionIdleTimeout

Set this directive to close TCP connections that have been idle for longer than the specified number of seconds. The minimum value is 15 seconds. If this directive is not set, the module keeps idle TCP connections open indefinitely.

ExclusiveAddrUse

Set this directive to TRUE to prevent other processes or module instances from binding to the same port.

The default is FALSE; multiple module instances can bind to the same port.

This directive is only supported on Windows.

ReuseAddr

Set this directive to TRUE to allow the module instance to bind to a port that is already in use.

The default is TRUE; multiple module instances can listen on the same port and process data simultaneously.

ReusePort

Set this directive to TRUE to allow multiple module instances to listen on the same port. Each instance runs in a separate thread, allowing NXLog Agent to process incoming logs simultaneously.

The default is FALSE; multiple module instances cannot bind to the same port.

This directive is not supported on Windows.

SockBufSize

This optional directive sets the socket buffer size (SO_RCVBUF) to the value specified. If not set, the operating system defaults are used. If UDP packet loss is occurring at the kernel level, setting this to a high value (such as 150000000) may help. On Windows systems, the default socket buffer size is extremely low, and using this option is highly recommended.

UseRecvmmsg

This boolean directive specifies that the recvmmsg() system call should be used, if available, to receive multiple messages per call to improve performance. The default is TRUE.

MaxMessages

This optional directive allocates space in the module buffer in order to fit the declared amount of UDP datagrams in the buffer at the same time. The value should be in the range 1 ⇐ amount ⇐ 100. If not set, the default value 10 is used.

Fields

The following fields are created by im_udp.

$raw_event (type: string): The received string.
$MessageSourceAddress (type: ipaddr): The IP address of the remote host.

Examples

Example 1. Using the im_udp module

This configuration accepts log messages via UDP and writes them to a file.

nxlog.conf

<Input udp>
    Module        im_udp
    ListenAddr    192.168.1.1:514
</Input>

<Output file>
    Module        om_file
    File          "tmp/output"
</Output>

<Route udp_to_file>
    Path          udp => file
</Route>

Example 2. Reusing a single port by multiple module instances

The configuration below provides two im_udp module instances to reuse port 514 via the ReusePort directive. Received messages are written to the /tmp/output file.

nxlog.conf

<Input udp_one>
    Module        im_udp
    ListenAddr    192.168.1.1:514
    ReusePort     TRUE
</Input>

<Input udp_two>
    Module        im_udp
    ListenAddr    192.168.1.1:514
    ReusePort     TRUE
</Input>

<Output file>
    Module        om_file
    File          "tmp/output"
</Output>

<Route udp_to_file>
    Path          udp_one, udp_two => file
</Route>