Trigger alerts with NXLog Agent

One of the benefits of automated log processing is detecting high-priority events. Alerting the relevant personnel of such events enables them to act quickly, minimizing the impact they may have. You can trigger alerts with NXLog Agent in several ways, including sending emails with a script or third-party application.

Send email alerts with a script

Using NXLog Agent’s Go, Java, Perl, Python, and Ruby modules, you can send email alerts with an external script.

Below, we provide a Python script you can use with NXLog Agent’s xm_python extension module.

send_email.py

import smtplib
import ssl
import json
import nxlog

def main(event):
    with open("config.json") as config_file:
        config = json.load(config_file)

    try:
        module = event.module
        host = event.get_field('Hostname')
        message = event.get_field('Message')
        server = smtplib.SMTP(config["smtp_server"],config["port"])
        server.starttls(context=ssl.create_default_context())
        server.login(config["sender_email"], config["password"])
        content = "Subject: NXLog Email Alert\nTo: %s\nFrom: %s\n\nHost: %s\nMessage: %s" % (config["receiver_email"], config["sender_email"], host, message)
        server.sendmail(config["sender_email"], config["receiver_email"], content)
    except Exception as e:
        print(e)

The script reads email configuration parameters from a JSON configuration file like the one below. Update the values according to your SMTP server settings and place the file in the same folder as the script.

config.json

{
  "smtp_server": "<your_smtp_server>",
  "port": "<port>",
  "sender_email": "<your_email>",
  "password": "<your_password>",
  "receiver_email": ["first_email","second_email","third_email"]
}

This script is provided "AS IS" without warranty of any kind, either expressed or implied. Use at your own risk.

Example 1. Sending email alerts with a script

Below is an example of a login event from the Linux auth.log file.

Linux authentication failure event

Nov 15 20:47:04 SERVER-1 sudo: pam_unix(sudo:auth): authentication failure; logname= uid=1000 euid=0 tty=/dev/pts/1 ruser=jsmith rhost=  user=jsmith

This configuration reads logs from the Linux authentication log file and parses them into structured data using the parse_syslog() procedure of the xm_syslog module. This procedure adds the $Message field to the event record.

It then uses a regular expression to filter for authentication failures and sends an email alert when it encounters a matching record.

nxlog.conf

<Extension syslog>
    Module        xm_syslog
</Extension>

<Extension python>
    Module        xm_python
    PythonCode    '/path/to/send_email.py' (1)
</Extension>

<Input linux_auth>
    Module        im_file
    File          '/var/log/auth.log'
    <Exec> 
        parse_syslog();
        if $Message =~ /.*authentication failure.*/  { (2)
            python_call('main'); (3)
        }
    </Exec>
</Input>

1	The PythonCode directive specifies the path to the Python script.
2	This regex searches for messages containing `authentication failure`.
3	The python_call() procedure executes the `main()` function of the Python script when a match is found.

For sending email alerts with other programming languages, see Send email alerts from NXLog Agent using Python, Perl, or Ruby in our blog.

Send email alerts with a third-party application

NXLog Agent’s xm_exec module can invoke external programs. It provides two procedures, exec() and exec_async(), which you can use to run an application or script. These procedures spawn a new process every time they’re called. Therefore, you must ensure that the application or script you invoke terminates on its own once processing is complete.

Several utilities are available for sending emails, or you might have a custom application of your own. In this example, we will use GNU Mailutils to trigger email alerts from NXLog Agent.

To install Mailutils on Debian-based distributions such as Ubuntu, first, update your package list:

$ sudo apt-get update

Then, execute the following command to install the mailutils package:

$ sudo apt install -y mailutils

Or, if you’re on RedHat, use the following command to install mailx:

$ sudo yum install mailx

Mailutils on Debian-based distributions installs Postfix. Follow the wizard to configure it.

Hit the right arrow key and then enter on your keyboard.
Select Internet Site and choose <ok>.
Enter your email domain name and choose <ok> to finalize the installation.

You can configure further mail settings, including a relay, in /etc/postfix/main.cf. See Postfix Basic Configuration and Postfix Configuration Parameters for details.

Verify your Mailutils configuration by sending a test email:

$ echo "This is a test email" | mail -s "Test subject" user@example.com

Once your application is up and running, you can configure NXLog Agent to use it to send alerts.

Example 2. Sending email alerts with Mailutils

Below is an example of a login event from the Linux auth.log file.

Linux authentication failure event

Nov 15 20:47:04 SERVER-1 sudo: pam_unix(sudo:auth): authentication failure; logname= uid=1000 euid=0 tty=/dev/pts/1 ruser=jsmith rhost=  user=jsmith

It then uses a regular expression to filter for authentication failures. When it encounters a matching record, it uses the exec_async() procedure of the xm_exec module to invoke an application to send an email alert.

nxlog.conf

<Extension syslog>
    Module    xm_syslog
</Extension>

<Extension _exec>
    Module    xm_exec
</Extension>

<Input linux_auth>
    Module    im_file
    File      '/var/log/auth.log'
    <Exec>
        parse_syslog();
        if $Message =~ /.*authentication failure.*(user=.*)/  { (1)
            exec_async("/bin/sh", "-c", 'echo "Raw message: ' + $raw_event + (2)
                       '" | mail -s "Authentication failure for ' + $1 + (3)
                       '" admin@example.com'); 
        }
    </Exec>
</Input>

1	This regex searches for messages containing `authentication failure` and captures the target account name.
2	Invokes the system shell with the `-c` option.
3	Executes the `mail` command to send an email to `admin@example.com`. Change this command according to your application.

See Invoking mail in the GNU Mailutils documentation for more command line options.

Output sample

The authentication failure event above will result in the following email.

Subject: Authentication failure for user=jsmith
To: <admin@example.com>
X-Mailer: mail (GNU Mailutils 3.7)
Message-Id: <20231115204705.CB06A2C0161@example.com>
Date: Wed, 15 Nov 2023 20:47:05 +0100 (CET)
From: nxlog <nxlog@example.com>

Raw message: Nov 15 20:47:04 SERVER-1 sudo: pam_unix(sudo:auth): authentication failure; logname= uid=1000 euid=0 tty=/dev/pts/1 ruser=jsmith rhost=  user=jsmith

Write to the NXLog Agent log file

You can instruct NXLog Agent to write an event to its log file. The following procedures are available for logging events with different severity:

When you use these procedures, NXLog Agent will write to the log file specified by the global LogFile directive. You must also ensure that you configure the correct LogLevel according to the severity you’re using.

Example 3. Logging a warning in the NXLog Agent log file

Below is an example of a login event from the Linux auth.log file.

Linux authentication failure event

Nov 15 20:47:04 SERVER-1 sudo: pam_unix(sudo:auth): authentication failure; logname= uid=1000 euid=0 tty=/dev/pts/1 ruser=jsmith rhost=  user=jsmith

It then uses a regular expression to filter for authentication failures and logs a warning when it encounters a matching record.

nxlog.conf

<Extension syslog>
    Module    xm_syslog
</Extension>

<Input linux_auth>
    Module    im_file
    File      '/var/log/auth.log'
    <Exec> 
        parse_syslog();
        if $Message =~ /.*authentication failure.*(user=.*)/  { (1)
            log_warning('Authentication failure for ' + $1); (2)
        }
    </Exec>
</Input>

1	This regex searches for messages containing `authentication failure` and captures the target account name.
2	Logs a warning in the log file and includes the account name captured by the regex.

Output sample

The authentication failure event above will result in the following warning in the NXLog Agent log file.

2023-11-15 20:47:05 WARNING [im_file|linux_auth] Authentication failure for user=jsmith

Disclaimer

While we endeavor to keep the information on this page up to date and correct, NXLog makes no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, suitability, or availability of the content represented here. We update our screenshots and instructions on a best-effort basis.

GNU Mailutils 3.7
Ubuntu 20.04
NXLog Agent version 6.0

Last revision: 16 December 2023