External Programs (xm_exec)

This module provides two procedures to enable the execution of external scripts or programs. These procedures are provided through this extension module to minimize the size of the NXLog Agent core. Additionally, if this module is not loaded arbitrary scripts cannot be executed from NXLog Agent.

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

The im_exec and om_exec modules also provide support for running external programs, though the purpose of these is to pipe data to and read data from programs. The procedures provided by the xm_exec module do not pipe log message data but are intended for multiple invocations. Data can still be passed to the executed script/program as command-line arguments.

Configuration

The xm_exec module accepts only the common module directives.

Functions

The following functions are exported by xm_exec.

string exec(string command, varargs args): Execute command, passing it the supplied arguments, and wait for it to terminate. The command is executed in the caller module’s context. Returns a string from stdout. Note that the module calling this function will block for at most 10 seconds or until the process terminates. Use the exec_async() procedure to avoid this problem. All output written to standard error by the spawned process is discarded.

Procedures

The following procedures are exported by xm_exec.

exec(string command, varargs args);: Execute command, passing it the supplied arguments, and wait for it to terminate. The command is executed in the caller module’s context. Note that the module calling this procedure will block until the process terminates. Use the exec_async() procedure to avoid this problem. All output written to standard output and standard error by the spawned process is discarded.

exec_async(string command, varargs args);: This procedure executes the command passing it the supplied arguments and does not wait for it to terminate.

Examples

Example 1. NXLog Agent acting as a cron daemon

This xm_exec module instance will run the command every second without waiting for it to terminate.

nxlog.conf

<Extension exec>
    Module  xm_exec
    <Schedule>
        Every   1 sec
        Exec    exec_async("/bin/true");
    </Schedule>
</Extension>

Example 2. Sending email alerts

If the $raw_event field matches the regular expression, an email will be sent.

nxlog.conf

<Extension exec>
    Module        xm_exec
</Extension>

<Input tcp>
    Module        im_tcp
    ListenAddr    0.0.0.0:1514
    <Exec>
      if $raw_event =~ /alertcondition/
      {
        exec_async("/bin/sh", "-c", 'echo "' + $Hostname +
        '\n\nRawEvent:\n' + $raw_event +
        '"|/usr/bin/mail -a "Content-Type: text/plain; charset=UTF-8" -s "ALERT" ' +
        'user@domain.com');
      }
    </Exec>
</Input>

<Output file>
    Module        om_file
    File          "/var/log/messages"
</Output>

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

For another example, see File rotation based on size.