syslog-ng Open Source Edition 3.30 - Administration Guide

Adding metadata from an external file

In syslog-ng OSE version 3.8 and later, you can use an external database file to add additional metadata to your log messages. For example, you can create a database (or export it from an existing tool) that contains a list of hostnames or IP addresses, and the department of your organization that the host belongs to, the role of the host (mailserver, webserver, and so on), or similar contextual information.

The database file is a simple text file in comma-separated value (CSV) format, where each line contains the following information:

• A selector or ID that appears in the log messages, for example, the hostname. To use shell-style globbing (wildcards) in selectors, see Shell-style globbing in the selector. You can also reference the name of a filter that matches the messages, see Using filters as selector

• The name of the name-value pair that syslog-ng OSE adds to matching log messages.

• The value of the name-value pairs. Starting with syslog-ng OSE version 3.22, the value of the name-value pair can be a template or a template function, for example, "selector3,name,$(echo $HOST_FROM)";

For example, the following csv-file contains three lines identified with the IP address, and adds the host-role field to the log message.

192.168.1.1,host-role,webserver
192.168.2.1,host-role,firewall
192.168.3.1,host-role,mailserver

192.168.1.1,host-role,webserver
192.168.1.1,contact-person,"John Doe"
192.168.1.1,contact-email,johndoe@example.com

parser p_add_context_data {
    add-contextual-data(
        selector("${HOST}"),
        database("context-info-db.csv"),
    );
};

You can also add data to messages that do not have a matching selector entry in the database using the default-selector() option.

If you modify the database file, you have to reload syslog-ng OSE for the changes to take effect. If reloading syslog-ng OSE or the database file fails for some reason, syslog-ng OSE will keep using the last working database file.

@include "scl.conf"

source s_network {
    network(port(5555));
};

destination d_local {
    file("/tmp/test-msgs.log"
    template("$MSG Additional metadata:[${.metadata.host-role}]")};

parser p_add_context_data {
    add-contextual-data(selector("$SOURCEIP"), database("context-info-db.csv"), default-selector("unknown"), prefix(".metadata."));
};

log {
    source(s_network);
    parser(p_add_context_data);
    destination(d_local);
};

192.168.1.1,host-role,webserver
192.168.2.1,host-role,firewall
192.168.3.1,host-role,mailserver
unknown,host-role,unknown

Using filters as selector

To better control to which log messages you add contextual data, you can use filters as selectors. In this case, the first column of the CSV database file must contain the name of a filter. For each message, syslog-ng OSE evaluates the filters in the order they appear in the database file. If a filter matches the message, syslog-ng OSE adds the name-value pair related to the filter.

For example, the database file can contain the entries. (For details on the accepted CSV-format, see database().)

f_auth,domain,all
f_localhost,source,localhost
f_kern,domain,kernel

Note that syslog-ng OSE does not evaluate other filters after the first match. For example, if you use the previous database file, and a message matches both the f_auth and f_localhost filters, syslog-ng OSE adds only the name-value pair of f_auth to the message.

To add multiple name-value pairs to a message, include a separate line in the database for each name-value pair, for example:

f_localhost,host-role,firewall
f_localhost,contact-person,"John Doe"
f_localhost,contact-email,johndoe@example.com

You can also add data to messages that do not have a matching selector entry in the database using the default-selector() option.

You must store the filters you reference in a database in a separate file. This file is similar to a syslog-ng OSE configuration file, but must contain only a version string and filters (and optionally comments). You can use the syslog-ng --syntax-only <filename> command to ensure that the file is valid. For example, the content of such a file can be:

@version: 3.30
filter f_localhost { host("mymachine.example.com") };
filter f_auth { facility(4) };
filter f_kern { facility(0) };

parser p_add_context_data_filter {
    add-contextual-data(
        selector(filters("filters.conf")),
        database("context-info-db.csv"),
        prefix(".metadata.")
    );
};

If you modify the database file, or the file that contains the filters, you have to reload syslog-ng OSE for the changes to take effect. If reloading syslog-ng OSE or the files fails for some reason, syslog-ng OSE will keep using the last working version of the file.

Shell-style globbing in the selector

Starting with in syslog-ng OSE3.24 and later, you can use shell-style globbing ('*' and '?' wildcards) in the selector.

To use globs in a selector

1. Use the glob() option within the selector() option in your syslog-ng OSE configuration file, for example:

   parser p_add_context_data {
       add-contextual-data(
           selector(glob("${HOST}"))
           database("context-info-db.csv")
       );
   };

2. Use globs and wildcards in the selector column of your CSV-file, for example:

   example-glob-entry1*,sourcetype,:hec:user
   example-glob-entry2*,sourcetype,:hec:user
   postfix*,sourcetype,:hec:mta

Note the following points when using globbing in the selector:

• The order of the patterns depends on the CSV-file. The order of entries in the database determines the matching order.

• The globs are matched against the expanded template string sequentially.

• Put more specific patterns to the top of the CSV-file. The syslog-ng OSE appication does not evaluate other entries after the first match.

• In debug mode, syslog-ng OSE sends log messages to its internal() destination to help troubleshooting. For example:

  [2019-09-21T06:01:10.748237] add-contextual-data(): Evaluating glob against message; glob-template='$PROGRAM', string='postfix/smtpd', pattern='example-glob-entry1*', matched='0'
  [2019-09-21T06:01:10.748562] add-contextual-data(): Evaluating glob against message; glob-template='$PROGRAM', string='postfix/smtpd', pattern='example-glob-entry2*', matched='0'
  [2019-09-21T06:01:10.748697] add-contextual-data(): Evaluating glob against message; glob-template='$PROGRAM', string='postfix/smtpd', pattern='postfix*', matched='1'
  [2019-09-21T06:01:10.750084] add-contextual-data(): message lookup finished; message='almafa', resolved_selector='postfix*', selector='postfix*', msg='0x8e15320'

Options add-contextual-data()

The add-contextual-data() has the following options.

unknown-hostname,host-role,unknown

add-contextual-data(
    selector("$HOST")
    database("context-info-db.csv")
    default-selector("unknown-hostname")
);