Use this directive to configure a constant or macro to be used later. Refer to a define by surrounding the name with percent signs (%). Enclose a group of statements with curly braces ({}).

define BASEDIR /var/log
define IMPORTANT if $raw_event =~ /important/ \
                    $Message = 'IMPORTANT ' + $raw_event;
define WARN_DROP { log_warning("dropping message"); drop(); }

<Input messages>
    Module  im_file
    File    '%BASEDIR%/messages'
</Input>

<Input proftpd>
    Module  im_file
    File    '%BASEDIR%/proftpd.log'
    <Exec>
        %IMPORTANT%
        if $raw_event =~ /dropme/ %WARN_DROP%
    </Exec>
</Input>

This directive works like define, except that the value is retrieved from the environment.

envvar BASEDIR

<Input in>
    Module  im_file
    File    '%BASEDIR%/messages'
</Input>

This directive allows a specified file or files to be included in the current NXLog configuration. Wildcarded filenames are supported.

include modules/module1.conf

include /etc/nxlog.d/*.conf

include C:\Program Files\nxlog\conf\nxlog.d\*.conf

Use this directive to load dynamic configuration from the standard output of a command or script. include_stdout behaves like a command-line interface and accepts a path to a command or script file. It does not support arguments or executing external scripts, such as PowerShell, directly. However, you can encapsulate scripts in a command file.

include_stdout /opt/nxlog/etc/fetch_conf.sh

After receiving the first termination signal NXLog might not terminate right away due to its shutdown sequence. This boolean directive specifies whether NXLog should immediately terminate on second termination signal (SIGINT, SIGQUIT or SIGTERM). Default value is FALSE.

Modules accumulate multiple records together into a batch, and each batch is forwarded to the next module in the route. This directive specifies the maximum number of records to accumulate per batch. If not specified, it defaults to maximum 50 records per batch. The global batch size can be overridden per module, with the BatchSize module-level directive.

Input and processor modules accumulate multiple records together into a batch, and each batch is forwarded to the next module in the route. This directive specifies the timeout, in seconds, before a batch of records will be forwarded to the next module in the route, even if it has accumulated fewer than the maximum number of records given by the BatchSize directive. If this directive is not specified, it defaults to 0.1 (100 milliseconds). The flush interval can be overriden per module, with the BatchFlushInterval module level directive.

This directive specifies a directory where the cache file (configcache.dat) should be written. This directive has a compiled-in value which is used by default.

This directive specifies how often the in-memory position cache should be flushed to the cache file. A value of 0 indicates that the cache should only be flushed to file when the agent shuts down; if the server or agent crashes, the current position cache will be lost. A positive integer indicates the interval in seconds between flushes of the cache. The string always specifies that the cache should be flushed to file immediately when a module sets a value. If this directive is not specified the default value of 5 seconds is used. See also the CacheSync directive below.

NXLog persists saved positions in cache that is written the disk. To prevent the cache growing indefinitely an invalidation period is used. This directive defines the invalidation period. If the last modification time of an entry exceeds the value set with this directive, the entry is discarded when the cache is read from disk. This directive accepts a positive Integer value. If the directive is not specified, the default value of 864000 (10 days) is used.

When the in-memory position cache is flushed to the cache file, the cache may not be immediately written to the disk due to file system buffering. When this directive is set to TRUE, the cache file is synced to disk immediately when it is written. The default is FALSE. CacheSync has no effect if CacheFlushInterval is set to FALSE or 0. Setting CacheSync to TRUE when CacheFlushInterval is set to always may reduce performance, yet it guarantees data integrity in the event of a crash.

This directive allows you to define Linux capabilities that NXLog must not drop after it has started.

This directive can be used to change the default date format as it appears in the LogFile, in the $raw_event generated by the modules, and when a datetime type value is converted to a string. The following values are accepted (corresponding to the formats accepted by the NXLog strftime() function):

This boolean directive specifies whether the backslash (\) character in glob patterns or wildcarded entries should be enabled as an escape sequence. If set to TRUE, this directive implies that the backslash character (\) needs to be escaped by another backslash character (\\). File and directory patterns on Windows do not require escaping and are processed as non-escaped even if this directive is set to TRUE. The default is FALSE. This directive is used in the im_file, im_fim, and im_regmon modules.

This optional boolean directive specifies the flow control default for input and processor module instances. Output module instances do not inherit from this directive. By default, the global FlowControl value is TRUE. See the description of the module level FlowControl directive for more information.

This bolean directive, when set to TRUE, which is also the default, enables FIFO mode for modules that have flow control disabled. In this mode, when the log queue of a module is full, older records will be dropped in order to make room for newer ones. When set to FALSE, the old behavior is in effect: while the log queue is full, no records will be dropped, but new incoming records will be discarded instead.

If set to TRUE, this boolean directive specifies that UTC should be used when generating dates in the format YYYY-MM-DD hh:mm:ss. If set to FALSE, local time will be used when generating dates in this format. The default is FALSE. See also ParseDateInUTC.

Similar to User, NXLog will set the group ID to run under. The group can be specified by name or numeric ID. This directive has no effect when running on the Windows platform or with nxlog-processor(8).

If set to FALSE, NXLog will stop when it encounters a problem with the configuration file (such as an invalid module directive) or if there is any other problem which would prevent all modules functioning correctly. If set to TRUE, NXLog will start after logging the problem. The default value is TRUE.

NXLog will write its internal log to this file. If this directive is not specified, self logging is disabled. Note that the im_internal module can also be used to direct internal log messages to files or different output destinations, but this does not support log level below INFO. This LogFile directive is especially useful for debugging.

This directive has five possible values: CRITICAL, ERROR, WARNING, INFO, and DEBUG. It will set both the logging level used for LogFile and the standard output if NXLog is started in the foreground. The default LogLevel is INFO. This directive can also be used at the module level.

This directive specifies the directory where the files of the persistent queues are stored for processor and output module instances. Even if PersistLogqueue is set to FALSE, NXLog will persist in-memory queues to the LogqueueDir on shutdown. If not specified, the default is the value of CacheDir. This directive can also be used at the module level to specify a log queue directory for a specific module instance.

This directive controls the size of the log queue for all processor and output module instances. The default is 100 record batches. See the module-level LogqueueSize for more information.

This directive controls which configuration file will be backed-up when a new version is written by the xm_admin PutFile command. The default is managed.conf.

By default the NXLog binaries have a compiled-in value for the directory to search for loadable modules. This can be overridden with this directive. The module directory contains sub-directories for each module type (extension, input, output, and processor), and the module binaries are located in those.

Some modules save data to a cache file which is persisted across a shutdown/restart. Modules such as im_file will save the file position in order to continue reading from the same position after a restart. This caching mechanism can be explicitly turned off with this directive. This is mostly useful with nxlog-processor(8) in offline mode. If this boolean directive is not specified, it defaults to FALSE (caching is enabled). Note that many input modules, such as im_file, provide a SavePos directive that can be used to disable the position cache for a specific module instance. SavePos has no effect if the cache is disabled globally with NoCache TRUE.

This directive is for debugging. When set to TRUE, NXLog will not free module resources on exit, allowing tools like Valgrind to show proper stack trace locations in module function calls. The default value is FALSE.

A panic condition is a critical state which usually indicates a bug. Assertions are used in NXLog code for checking conditions where the code will not work unless the asserted condition is satisfied, and for security. Failing assertions result in a panic and suggest a bug in the code. A typical case is checking for NULL pointers before pointer dereference. This directive can take three different values: HARD, SOFT, or OFF. HARD will cause an abort in case the assertion fails. This is how most C based programs work. SOFT will cause an exception to be thrown at the place of the panic/assertion. In case of NULL pointer checks this is identical to a NullPointerException in Java. It is possible that NXLog can recover from exceptions and can continue to process log messages, or at least the other modules can. In case of assertion failure the location and the condition is printed at CRITICAL log level in HARD mode and ERROR log level in SOFT mode. If Panic is set to OFF, the failing condition is printed in the logs but the execution will continue on the normal code path. Most of the time this will result in a segmentation fault or other undefined behavior, though in some cases turning off a buggy assertion or panic will solve the problems caused by it in HARD/SOFT mode. The default value for Panic is SOFT.

If set to TRUE, this boolean directive specifies that dates in the format YYYY-MM-DD hh:mm:ss should be parsed as UTC. If set to FALSE, dates in this format are assumed to be in local time. The default is FALSE. See also GenerateDateInUTC.

This boolean directive specifies that log queues of processor and output module instances should be disk-based. See the module level PersistLogqueue directive for more information.

Under Unix operating systems, NXLog writes a PID file as other system daemons do. The default PID file can be overridden with this directive in case multiple daemon instances need to be running. This directive has no effect when running on the Windows platform or with nxlog-processor(8).

This directive is specific to nxlog-processor(8). It controls the exit condition of nxlog-processor(8). Its value is a timeout in seconds. If nxlog-processor(8) gets no data to process during this period then it will stop waiting for more data and will exit. The default value is 0.05 s. For any non-negative value which is less than 0.05 this will be 0.05. In case nxlog-processor(8) is configured to read data from the network it is recommended to set this to a higher value.

NXLog will set its root directory to the value specified with this directive. If SpoolDir is also set, this will be relative to the value of RootDir (chroot() is called first). This directive has no effect when running on the Windows platform or with the nxlog-processor(8).

NXLog will change its working directory to the value specified with this directive. This is useful with files created through relative filenames (for example, with om_file) and in case of core dumps. This directive has no effect with the nxlog-processor(8).

To protect against memory exhaustion (and possibly a denial-of-service) caused by over-sized strings, there is a limit on the length of each string (in bytes). The default value is 5242880 bytes (strings will be truncated at 5 MiB).

Under some circumstances it is possible for NXLog to generate an extreme amount of internal logs consisting of the same message due to an incorrect configuration or a software bug. In this case, the LogFile can quickly consume the available disk space. With this directive, NXLog will write at most 2 lines per second if the same message is generated successively, by logging "last message repeated n times" messages. If this boolean directive is not specified, it defaults to TRUE (suppression of repeating messages is enabled).

When this directive is set to TRUE and PersistLogqueue is enabled, the disk-based queues of processor and output module instances will be immediately synced after each new entry is added to the queue. This greatly reduces performance but makes the queue more reliable and crash-safe. This directive can also be used at the module level.

This directive specifies the number of worker threads to use. The number of worker threads is calculated and set to an optimal value if this directive is not defined. Do not set this unless you know what you are doing.

NXLog will drop to the user specified with this directive. This is useful if NXLog needs privileged access to some system resources (such as kernel messages or to bind a port below 1024). On Linux systems NXLog will use capabilities to access these resources. In this case NXLog must be started as root. The user can be specified by name or numeric ID. This directive has no effect when running on the Windows platform or with nxlog-processor(8).

This mandatory directive specifies which binary should be loaded. The module binary has a .so extension on Unix and a .dll on Windows platforms and resides under the ModuleDir directory. Each module binary name is prefixed with im_, pm_, om_, or xm_ (for input, processor, output, and extension, respectively). It is possible for multiple instances to use the same loadable binary. In this case the binary is only loaded once but instantiated multiple times. Different module instances may have different configurations.

This directive specifies how many records will be collected by the module and forwarded together as a batch to the next module in the route. For configuring the batch size for all modules globally, read the global BatchSize directive description.

This directive can only be used with input and processor modules. It specifies the timeout before a record-batch is forwarded to the next module in the route. See the description of the global BatchFlushInterval directive for more information.

This directive specifies the read/write buffer size for input and output modules in bytes. The default buffer size is 65000 bytes. Only stream-oriented modules use this directive, i.e., those connecting over the network (UDP, TCP, and HTTP) or reading and writing to files. Each module instance can have multiple buffers. For example, an im_file instance collecting logs from multiple files will have a buffer for each open file. Similarly, an im_tcp instance will have a buffer for each open connection. The value set in this directive applies to each buffer and is not cumulative; therefore, it does not limit how much memory a module instance can use.

This directive specifies the directory where the files of the persistent queue are stored. LogqueueDir is only valid for processor and output module instances. See the description of the global LogqueueDir for more information.

Every processor and output instance has an input log queue for events waiting to be processed by that module. The size of the queue is measured in batches of event records, and can be set with this directive—the default is 100 batches. When the log queue of a module instance is full and FlowControl is enabled for the preceding module, the preceding module will be suspended. If flow control is not enabled for the preceding module, events will be discarded. This directive is only valid for processor and output module instances. This directive can be used at the global level to affect all modules.

When a module passes an event to the next module along the route, it puts it into the next module’s queue. This queue can be either a memory-based or disk-based (persistent) queue. When this directive is set to TRUE, the module will use a persistent (disk-based) queue. With the default value of FALSE, the module’s incoming log queue will be memory-based; however, in-memory log queues will still be persisted to disk on shutdown. This directive is only valid for processor and output module instances. This directive can also be used at the global level.

When this directive is set to TRUE and PersistLogqueue is enabled, the disk-based queue will be immediately synced after each new entry is added to the queue. This greatly reduces performance but makes the queue more reliable and crash-safe. This directive is only valid for processor and output module instances. This directive can be used at the global level to affect all modules.