File Lists (xm_filelist)

The xm_filelist module can be used to implement file-based allow and block lists. This extension module accepts one or more files containing a list of values separated by a newline. It provides two functions, contains() and matches() that can be invoked to check whether a string argument is present in the files. This can be a username, IP address, or similar. The specified files are cached in memory and any modifications are automatically loaded without the need to restart NXLog Agent.

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

Configuration

The xm_filelist module accepts the following directives in addition to the common module directives. The File directive is required.

Required directives

The following directives are required for the module to start.

File

The mandatory File directive specifies the path to the file that will be read into memory. This directive may be specified more than once if multiple files need to be loaded.

Optional directives

CheckInterval

This optional directive specifies the frequency with which the files are checked for modifications, in seconds. The default value is 5 seconds. File checks are disabled if CheckInterval is set to 0.

Functions

The following functions are exported by xm_filelist.

type: boolean contains(type: string str): Check if line in the file(s) contains the string str. You must call this function using the -> operator. See Calling a function of a specific module instance for more information.
type: boolean contains(type: string str, type: boolean caseinsensitive): Check if line in the file(s) contains the string str. May be case insensitive according to caseinsensitive. You must call this function using the -> operator. See Calling a function of a specific module instance for more information.
type: boolean matches(type: string str): Check if a line in the file(s) matches the string str. You must call this function using the -> operator. See Calling a function of a specific module instance for more information.
type: boolean matches(type: string str, type: boolean caseinsensitive): Check if a line in the file(s) matches the string str. May be case insensitive according to caseinsensitive. You must call this function using the -> operator. See Calling a function of a specific module instance for more information.

Examples

Example 1. Dropping events from specific hosts

The following configuration loads a list of whitelisted hostnames using the xm_filelist module. The input instance processes Syslog messages and uses the matches function to check if the $Hostname field is found in the loaded list. If it is, the record is discarded using the drop procedure.

<Extension hosts_list>
    Module    xm_filelist
    File      /path/to/hosts/whitelist
</Extension>

<Input in>
    Module    im_file
    File      '/path/to/log/file'
    Exec      parse_syslog();
    Exec      if hosts_list->matches($Hostname, TRUE) drop();
</Input>