Adding metadata from an external file

• 1: Using filters as selector
• 2: Shell-style globbing in the selector
• 3: Options add-contextual-data()

   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,[email protected]

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

   @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

1 - 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, AxoSyslog evaluates the filters in the order they appear in the database file. If a filter matches the message, AxoSyslog 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 AxoSyslog 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, AxoSyslog 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,[email protected]

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 AxoSyslog configuration file, but must contain only a version string and filters (and optionally comments). You can use the `syslog-ng –syntax-only command to ensure that the file is valid. For example, the content of such a file can be:

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

Declaration:

   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 AxoSyslog for the changes to take effect. If reloading AxoSyslog or the files fails for some reason, AxoSyslog will keep using the last working version of the file.

2 - Shell-style globbing in the selector

Starting with in AxoSyslog 3.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 AxoSyslog 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 AxoSyslog appication does not evaluate other entries after the first match.

• In debug mode, AxoSyslog 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'
  

3 - Options add-contextual-data()

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

Required options:

The following options are required: selector(), database().

database()

Description: Specifies the path to the CSV file, for example, /opt/syslog-ng/my-csv-database.csv. The extension of the file must be .csv, and can include Windows-style (CRLF) or UNIX-style (LF) linebreaks. You can use absolute path, or relative to the syslog-ng binary.

default-selector()

Description: Specifies the ID of the entry (line) that is corresponds to log messages that do not have a selector that matches an entry in the database. For example, if you add name-value pairs from the database based on the hostname from the log message (selector("${HOST}")), then you can include a line for unknown hosts in the database, and set default-selector() to the ID of the line for unknown hosts. In the CSV file:

   unknown-hostname,host-role,unknown

In the AxoSyslog configuration file:

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

ignore-case()

Description: Specifies if selectors are handled as case insensitive. If you set the ignore-case() option to yes, selectors are handled as case insensitive.

prefix()

Description: Insert a prefix before the name part of the added name-value pairs (including the pairs added by the default-selector()) to help further processing.

selector()

Description: Specifies the string or macro that AxoSyslog evaluates for each message, and if its value matches the ID of an entry in the database, AxoSyslog adds the name-value pair of every matching database entry to the log message. You can use the following in the selector() option.

• Strings

• A single macro (for example, selector("${HOST}"))

• To use filters as selectors, see Using filters as selector.

• To use shell-style globbing (wildcards) in selectors, see Shell-style globbing in the selector.

• Using templates as selectors is not supported.