Running NXLog Agent

This page describes how to run and control NXLog Agent on Linux/UNIX and Windows, covering command-line options, default file locations, signals and service controls, and the nxlog-processor offline processing tool.

nxlog

nxlog is the main NXLog Agent service. On Linux and UNIX systems it runs as a daemon; on Windows it runs as a Windows service.

On Windows, the executable is C:\Program Files\nxlog\nxlog.exe by default.

Synopsis

nxlog [-c conffile] [-f]
nxlog [-c conffile] -v
nxlog [-r | -s]

Options

Option Description

Option	Description
`-c conffile`, `--conf conffile`	Specify an alternative configuration file conffile. To change the configuration file used by the Windows service, modify the `nxlog` service parameters.
`-f`, `--foreground`	Run in the foreground instead of as a service.
`-q`, `--quiet`	Suppress output to STDOUT/STDERR.
`-h`, `--help`	Print help.
`-r`, `--reload`	Reload the configuration of a running instance. On Windows, stop and start the service instead: `sc stop nxlog` and `sc start nxlog`.
`-s`, `--stop`	Send a stop signal to a running instance. On Windows, use `sc stop nxlog` instead.
`-v`, `--verify`	Verify the configuration file syntax.

-c conffile, --conf conffile

Specify an alternative configuration file conffile. To change the configuration file used by the Windows service, modify the nxlog service parameters.

-f, --foreground

Run in the foreground instead of as a service.

-q, --quiet

Suppress output to STDOUT/STDERR.

-h, --help

Print help.

-r, --reload

Reload the configuration of a running instance. On Windows, stop and start the service instead: sc stop nxlog and sc start nxlog.

-s, --stop

Send a stop signal to a running instance. On Windows, use sc stop nxlog instead.

-v, --verify

Verify the configuration file syntax.

nxlog-processor

The nxlog-processor tool is similar to the NXLog Agent service and uses the same configuration file. However, it runs in the foreground and exits after it finishes processing the input data. Common input sources include files and databases. This tool is useful for data processing tasks such as:

Migrating data from files to a database
Converting between different data formats
Testing patterns
Correlating events offline
Checking HMAC message integrity

On Windows, the executable is C:\Program Files\nxlog\nxlog-processor.exe by default.

Synopsis

nxlog-processor [-c conffile] [-v]

Options

Option Description

Option	Description
`-c conffile`, `--conf conffile`	Specify an alternative configuration file conffile.
`-h`, `--help`	Print help.
`-v`, `--verify`	Verify the configuration file syntax.

-c conffile, --conf conffile

Specify an alternative configuration file conffile.

-h, --help

Print help.

-v, --verify

Verify the configuration file syntax.

File paths

The default installation paths differ between Linux/UNIX and Windows. If you installed NXLog Agent to a non-default location, adjust the paths accordingly.

Linux/UNIX
Windows

Path Description

Path	Description
`/opt/nxlog/bin/nxlog`	The main NXLog Agent executable.
`/opt/nxlog/bin/nxlog-processor`	The nxlog-processor executable.
`/opt/nxlog/bin/nxlog-stmnt-verifier`	A tool to check NXLog language statements. It reads statements from the standard input stream and validates them. If a statement is invalid, the tool prints an error to the standard error stream and exits with a non-zero value.
`/opt/nxlog/etc/nxlog.conf`	The default configuration file.
`/opt/nxlog/lib/nxlog/modules`	The NXLog Agent modules are located in this directory by default. See the ModuleDir directive.
`/opt/nxlog/var/log/nxlog/nxlog.log`	The default NXLog Agent log file. See the LogFile directive.
`/opt/nxlog/spool/nxlog`	If PersistLogqueue is set to `TRUE`, module queues are stored in this directory. See also the LogqueueDir and SyncLogqueue directives.
`/opt/nxlog/spool/nxlog/configcache.dat`	The cache file that stores the last read position. See the NoCache, CacheDir, CacheFlushInterval, and CacheSync directives.
`/opt/nxlog/var/run/nxlog/nxlog.pid`	The process ID (PID) of the currently running NXLog Agent process is written to this file. See the PidFile directive.

/opt/nxlog/bin/nxlog

The main NXLog Agent executable.

/opt/nxlog/bin/nxlog-processor

The nxlog-processor executable.

/opt/nxlog/bin/nxlog-stmnt-verifier

A tool to check NXLog language statements. It reads statements from the standard input stream and validates them. If a statement is invalid, the tool prints an error to the standard error stream and exits with a non-zero value.

/opt/nxlog/etc/nxlog.conf

The default configuration file.

/opt/nxlog/lib/nxlog/modules

The NXLog Agent modules are located in this directory by default. See the ModuleDir directive.

/opt/nxlog/var/log/nxlog/nxlog.log

The default NXLog Agent log file. See the LogFile directive.

/opt/nxlog/spool/nxlog

If PersistLogqueue is set to TRUE, module queues are stored in this directory. See also the LogqueueDir and SyncLogqueue directives.

/opt/nxlog/spool/nxlog/configcache.dat

The cache file that stores the last read position. See the NoCache, CacheDir, CacheFlushInterval, and CacheSync directives.

/opt/nxlog/var/run/nxlog/nxlog.pid

The process ID (PID) of the currently running NXLog Agent process is written to this file. See the PidFile directive.

Path Description

Path	Description
`C:\Program Files\nxlog\nxlog.exe`	The main NXLog Agent executable.
`C:\Program Files\nxlog\nxlog-processor.exe`	The nxlog-processor executable.
`C:\Program Files\nxlog\nxlog-stmnt-verifier.exe`	A tool to check NXLog language statements. It reads statements from the standard input stream and validates them. If a statement is invalid, the tool prints an error to the standard error stream and exits with a non-zero value.
`C:\Program Files\nxlog\conf\nxlog.conf`	The default configuration file.
`C:\Program Files\nxlog\data\nxlog.log`	The default NXLog Agent log file. See the LogFile directive.
`C:\Program Files\nxlog\data`	The default directory for NXLog Agent data files, including the cache and queue files. See the CacheDir and LogqueueDir directives.

C:\Program Files\nxlog\nxlog.exe

The main NXLog Agent executable.

C:\Program Files\nxlog\nxlog-processor.exe

The nxlog-processor executable.

C:\Program Files\nxlog\nxlog-stmnt-verifier.exe

C:\Program Files\nxlog\conf\nxlog.conf

The default configuration file.

C:\Program Files\nxlog\data\nxlog.log

The default NXLog Agent log file. See the LogFile directive.

C:\Program Files\nxlog\data

The default directory for NXLog Agent data files, including the cache and queue files. See the CacheDir and LogqueueDir directives.

Controlling the agent

Once NXLog Agent is running, you can start or stop it, reload the configuration on the fly, or check its status. The commands to do this depend on your operating system.

Linux/UNIX
Windows

You can control the NXLog Agent process by sending it the following signals using the kill command.

Signal Effect

Signal	Effect
`SIGHUP`	Reload the NXLog Agent configuration and restart the module instances.
`SIGUSR1`	Write an `INFO` message to the LogFile containing the current NXLog Agent status. The message is also available via the Internal input module.
`SIGUSR2`	Switch NXLog Agent to debug log level. This is equivalent to setting the LogLevel directive to `DEBUG` but does not require an NXLog Agent restart.
`SIGINT` / `SIGQUIT` / `SIGTERM`	Stop NXLog Agent.

SIGHUP

Reload the NXLog Agent configuration and restart the module instances.

SIGUSR1

Write an INFO message to the LogFile containing the current NXLog Agent status. The message is also available via the Internal input module.

SIGUSR2

Switch NXLog Agent to debug log level. This is equivalent to setting the LogLevel directive to DEBUG but does not require an NXLog Agent restart.

SIGINT / SIGQUIT / SIGTERM

Stop NXLog Agent.

For example, the following command sends the SIGUSR1 signal:

$ kill -SIGUSR1 $(cat /opt/nxlog/var/run/nxlog/nxlog.pid)

On Windows, NXLog Agent runs as a service managed through the Windows Service Control Manager. Use the sc command to control it from the command prompt, or use the Services MMC snap-in (services.msc).

Command Effect

Command	Effect
`sc start nxlog`	Start the NXLog Agent service.
`sc stop nxlog`	Stop the NXLog Agent service.
`sc control nxlog 200`	Write an `INFO` message containing the current NXLog Agent status to the log file.
`sc control nxlog 201`	Switch NXLog Agent to debug log level.

sc start nxlog

Start the NXLog Agent service.

sc stop nxlog

Stop the NXLog Agent service.

sc control nxlog 200

Write an INFO message containing the current NXLog Agent status to the log file.

sc control nxlog 201

Switch NXLog Agent to debug log level.

For example, the following command sends the status request:

> sc control nxlog 200

Environment variables

To access environment variables from the NXLog Agent configuration on both Linux and Windows, use the envvar directive.