Resolver (xm_resolver)

This module provides functions for resolving (converting between) IP addresses and names, and between group/user IDs and names. The module uses an internal cache in order to minimize the number of DNS lookup queries.

To examine the supported platforms, see the list of installer packages in the Available Modules chapter.

Resolving hostnames and group/user names may require connecting to other resources on the network such as LDAP, AD, or a DNS server. This causes additional network traffic and may slow down log processing. To improve performance, it is recommended to make use of a local name service caching solution, such as nscd, systemd-resolved, or SSSD.

Configuration

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

CacheExpiry: Specifies the time in seconds after which entries in the cache are considered invalid and are refreshed by issuing a DNS lookup. A value of 0 disables the caching of successful queries. The default expiry is 3600 seconds.

CacheLimit: This directive can be used to specify an upper limit on the number of entries in the cache to prevent it from becoming arbitrary large and potentially exhausting memory. When the number of entries in the cache reaches this value, no more items will be inserted into the cache. The default is 100,000 entries.

NegativeCacheExpiry: Specifies the time in seconds after which failed entries in the cache are considered invalid and are refreshed by issuing a DNS lookup. A value of 0 disables the caching of failed queries. The default expiry is 30 seconds.

Functions

The following functions are exported by xm_resolver.

string ad_guid_to_name(string guid): This function is available on Windows only. Return the object name corresponding to the Active Directory object’s GUID. This function takes a guid string in the format %{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} (where x is a hexadecimal digit). If guid cannot be looked up, undef is returned.

string gid_to_name(integer gid): Return the group name assigned to the group ID. If gid cannot be looked up, undef is returned.

string gid_to_name(string gid): Return the group name assigned to the string gid on Unix. If gid cannot be looked up, undef is returned.

integer group_get_gid(string groupname): Return the group ID assigned to the group name.

string ipaddr_to_name(unknown ipaddr): Resolve and return the DNS name assigned to the IP address. The ipaddr argument can be either a string or an ipaddr type.

ipaddr name_to_ipaddr(string name): Resolve and return the first IPv4 address assigned to name.

string uid_to_name(integer uid): Return the username corresponding to the user ID. If uid cannot be looked up, undef is returned.

string uid_to_name(string uid): Return the username corresponding to the user ID or SID. This function takes a string which is normally a SID on Windows or an integer UID on Unix. On Windows this function will convert the SID to a string in the format of DOMAIN\USER. If uid cannot be looked up, undef is returned.

integer user_get_gid(string username): Return the user’s group ID (the group ID assigned to username).

integer user_get_uid(string username): Return the user ID assigned to username.

Examples

Example 1. Using functions provided by xm_resolver

It is common for devices to send syslog messages containing the IP address of the device instead of a real hostname. In this example, syslog messages are parsed and the hostname field of each syslog header is converted to a hostname if it looks like an IP address.

nxlog.conf

<Extension syslog>
    Module      xm_syslog
</Extension>

<Extension _resolver>
    Module      xm_resolver
</Extension>

<Input tcp>
    Module      im_tcp
    ListenAddr  0.0.0.0:1514
    <Exec>
        parse_syslog();
        if $Hostname =~ /^\d+\.\d+\.\d+\.\d+/
        {
            $HostIP = $Hostname;
            $Hostname = ipaddr_to_name($HostIP);
            if not defined $Hostname $Hostname = $HostIP;
	    
            if ($Hostname == ipaddr_to_name("127.0.0.1"))
            {
                $Hostname = "localhost";
            }
        }
    </Exec>
</Input>

<Output file>
    Module      om_file
    File        'tmp/output'
    Exec        to_syslog_bsd();
</Output>

<Route tcp_to_file>
    Path        tcp => file
</Route>

Input sample

<38>2014-11-11 11:40:27 127.0.0.1 sshd[3436]: Failed none for invalid user asdf from 127.0.0.1 port 51824 ssh2
<38>2014-11-12 12:42:37 127.0.0.1 sshd[3436]: Failed password for invalid user fdsa from 127.0.0.1 port 51824 ssh2

Output sample

<38>Nov 11 11:40:27 localhost sshd[3436]: Failed none for invalid user asdf from 127.0.0.1 port 51824 ssh2
<38>Nov 12 12:42:37 localhost sshd[3436]: Failed password for invalid user fdsa from 127.0.0.1 port 51824 ssh2