syslog-ng Open Source Edition 3.22 - Administration Guide

Preface Introduction to syslog-ng The concepts of syslog-ng Installing syslog-ng The syslog-ng OSE quick-start guide The syslog-ng OSE configuration file source: Read, receive, and collect log messages
How sources work default-network-drivers: Receive and parse common syslog messages internal: Collecting internal messages file: Collecting messages from text files wildcard-file: Collecting messages from multiple text files linux-audit: Collecting messages from Linux audit logs network: Collecting messages using the RFC3164 protocol (network() driver) nodejs: Receiving JSON messages from nodejs applications mbox: Converting local e-mail messages to log messages osquery: Collect and parse osquery result logs pipe: Collecting messages from named pipes pacct: Collecting process accounting logs on Linux program: Receiving messages from external applications python: writing server-style Python sources python-fetcher: writing fetcher-style Python sources snmptrap: Read Net-SNMP traps sun-streams: Collecting messages on Sun Solaris syslog: Collecting messages using the IETF syslog protocol (syslog() driver) system: Collecting the system-specific log messages of a platform systemd-journal: Collecting messages from the systemd-journal system log storage systemd-syslog: Collecting systemd messages using a socket tcp, tcp6, udp, udp6: Collecting messages from remote hosts using the BSD syslog protocol— OBSOLETE unix-stream, unix-dgram: Collecting messages from UNIX domain sockets stdin: Collecting messages from the standard input stream
destination: Forward, send, and store log messages
amqp: Publishing messages using AMQP collectd: sending metrics to collectd elasticsearch2: Sending messages directly to Elasticsearch version 2.0 or higher (DEPRECATED) elasticsearch-http: Sending messages to Elasticsearch HTTP Bulk API file: Storing messages in plain-text files graphite: Sending metrics to Graphite Sending logs to Graylog hdfs: Storing messages on the Hadoop Distributed File System (HDFS) Posting messages over HTTP http: Posting messages over HTTP without Java kafka: Publishing messages to Apache Kafka (Java implementation) kafka: Publishing messages to Apache Kafka (C implementation, using the librdkafka client) loggly: Using Loggly logmatic: Using Logmatic.io mongodb: Storing messages in a MongoDB database network: Sending messages to a remote log server using the RFC3164 protocol (network() driver) osquery: Sending log messages to osquery's syslog table pipe: Sending messages to named pipes program: Sending messages to external applications pseudofile() python: writing custom Python destinations redis: Storing name-value pairs in Redis riemann: Monitoring your data with Riemann slack: Sending alerts and notifications to a Slack channel smtp: Generating SMTP messages (e-mail) from logs snmp: Sending SNMP traps Splunk: Sending log messages to Splunk sql: Storing messages in an SQL database stomp: Publishing messages using STOMP syslog: Sending messages to a remote logserver using the IETF-syslog protocol syslog-ng: Forwarding messages and tags to another syslog-ng node tcp, tcp6, udp, udp6: Sending messages to a remote log server using the legacy BSD-syslog protocol (tcp(), udp() drivers) Telegram: Sending messages to Telegram unix-stream, unix-dgram: Sending messages to UNIX domain sockets usertty: Sending messages to a user terminal: usertty() destination Write your own custom destination in Java or Python Client-side failover
log: Filter and route log messages using log paths, flags, and filters Global options of syslog-ng OSE TLS-encrypted message transfer template and rewrite: Format, modify, and manipulate log messages parser: Parse and segment structured messages db-parser: Process message content with a pattern database (patterndb) Correlating log messages Enriching log messages with external data Statistics of syslog-ng Multithreading and scaling in syslog-ng OSE Troubleshooting syslog-ng Best practices and examples The syslog-ng manual pages Creative Commons Attribution Non-commercial No Derivatives (by-nc-nd) License

Template functions of syslog-ng OSE

The following template functions are available in syslog-ng OSE.

base64-encode

Syntax:

$(base64-encode argument)

Description: You can use the base64-encode template function to base64-encode strings and macros. The template function can receive multiple parameters (maximum 64). In this case, syslog-ng OSE joins the parameters into a single string and encodes this string. For example, $(base64-encode string1 string2) is equivalent to $(base64-encode string1string2).

Available in syslog-ng OSE version 3.18 and later.

basename

Syntax:

$(basename argument)

Description: Returns the filename from an argument (for example, a macro: $(basename ${FILE_NAME})) that contains a filename with a path. For example, $(basename "/var/log/messages.log") returns messages.log. To extract the path, use the dirname template function.

Available in syslog-ng OSE version 3.10 and later.

ceil

Syntax:

$(ceil argument)

Description: Rounds a floating-point number upwards to the nearest integer. For example, $(ceil 1.5) is 2, $(ceil -1.5) is -1. See also the floor and round template functions.

context-lookup

Syntax:

$(context-lookup [option] condition value-to-select)

Description: The context-lookup template function can search a message context when correlating messages (for example, when you use a pattern database or the grouping-by parser). The context-lookup template function requires a condition (a filter or a string), and returns a specific macro or template of the matching messages (for example, the ${MESSAGE}) as a list. It works similarly to the $(grep) template function, but it escapes its output properly, so that the returned value is a list that can be processed with other template functions that work on lists, for example, $(list-slice).

Example: Using the context-lookup template function

The following example selects the message of the context that has a username name-value pair with the root value, and returns the value of the tags name-value pair.

$(context-lookup ("${username}" == "root") ${tags})

To limit the number of matches that the template function returns, use the --max-count option, for example, $(context-lookup --max-count 5 ("${username}" == "root") ${tags}). If you do not want to limit the number of matches, use --max-count 0.

You can to specify multiple name-value pairs as parameters, separated with commas. If multiple messages match the condition of context-lookup, these will be returned also separated by commas. This can be used for example to collect the e-mail recipients from postfix messages.

Available in syslog-ng OSE version 3.10 and later.

context-values

Syntax:

$(context-values $name-value1 $name-value2 ...)

Description: The context-values template function returns a list of every occurrence of the specified name-value pairs from the entire context. For example, if the context contains multiple messages, the $(context-values ${HOST}) template function will return a comma-separated list of the ${HOST} values that appear in the context.

Available in syslog-ng OSE version 3.10 and later.

dirname

Syntax:

$(dirname argument)

Description: Returns the path (without the filename) from an argument (for example, a macro: $(basename ${FILE_NAME}) that contains a filename with a path. For example, $(dirname "/var/log/messages.log") returns /var/log path. To extract the filename, use the basename template function.

Available in syslog-ng OSE version 3.10 and later.

echo

Syntax:

$(echo argument)

Description: Returns the value of its argument. Using $(echo ${HOST}) is equivalent to ${HOST}.

env

Syntax:

$(env <environment-variable>)

Description: Returns the value of the specified environment variable. Available in syslog-ng OSE 3.5 and later.

explode

Syntax:

$(explode <separator> <string1> <string2> ...)

Description: Turns a string separated by a specific character into a list. You can also use the implode template function, which turns a list into a string combining the pieces together with a separator. Available in syslog-ng OSE 3.21 and later.

Example: Using the explode template function

The following configuration example turns strings into a list. If there are several strings, syslog-ng OSE looks for a separator within each individual string. For example, string 2 is separated as string, 2 in the example below:

Configuration Result
$(explode ';' string1;string 2;string3;string4) "string1,string,2,string3,string4"

Enclose the strings in double-quotes or apostrophes and string 2 is separated as shown below:

Configuration Result
$(explode ' ' 'string1 string 2 string3 string4 string5') "string1,string 2,string3,string4,string5"

The following examples replace the separator ';' character with a ',' character:

Configuration Result
$(implode ',' $(explode ';' 'string1;string2;string3')) "string1,string2,string3"

$(explode ';' 'string1;string2;string3;string4;string5')

"string1,string2,string3,string4,string5"

floor

Syntax:

$(floor argument)

Description: Rounds a floating-point number downwards to the nearest integer. For example, $(floor 1.5) is 1, $(floor -1.5) is -2. See also the ceil and round template functions.

format-cef-extension

syslog-ng OSE version 3.8 includes a new template function (format-cef-extension) to format name-value pairs as ArcSight Common Event Format extensions. Note that the template function only formats the selected name-value pairs, it does not provide any mapping. There is no special support for creating the prefix part of a Common Event Format (CEF) message. Note that the order of the elements is random. For details on the CEF extension escaping rules format, see the ArcSight Common Event Format.

You can use the value-pairs that syslog-ng OSE stores about the log message as CEF fields. Using value-pairs, you can:

  • select which value-pairs to use as CEF fields,

  • add custom value-pairs as CEF fields,

  • rename value-pairs, and so on.

For details, see Structuring macros, metadata, and other value-pairs. Note that the syntax of format-* template functions is different from the syntax of value-pairs(): these template functions use a syntax similar to command lines.

Using the format-cef-extension template function, has the following prerequisites:

  • Load the the cef module in your configuration:

    @module cef
  • Set the on-error global option to drop-property, otherwise if the name of a name-value pair includes an invalid character, syslog-ng OSE drops the entire message. (Key name in CEF extensions can contain only the A-Z, a-z and 0-9 characters.)

    options {
       on-error("drop-property");
    };
  • The log messages must be encoded in UTF-8. Use the encoding() option or the validate-utf8 flag in the message source.

Example: Using the format-cef-extension template function

The following example selects every available information about the log message, except for the date-related macros (R_* and S_*), selects the .SDATA.meta.sequenceId macro, and defines a new value-pair called MSGHDR that contains the program name and PID of the application that sent the log message (since you will use the template-function in a template, you must escape the double-quotes).

$(format-cef-extension --scope syslog,all_macros,selected_macros \
  --exclude R_* --exclude S_* --key .SDATA.meta.sequenceId \
  --pair MSGHDR=\"$PROGRAM[$PID]: \")

The following example selects every value-pair that has a name beginning with .cef., but removes the .cef. prefix from the key names.

template("$(format-cef-extension --subkeys .cef.)\n")

The following example shows how to use this template function to store log messages in CEF format:

destination d_cef_extension {
    file("/var/log/messages.cef" template("${ISODATE} ${HOST} $(format-cef-extension --scope selected_macros --scope nv_pairs)\n"));
};
format-cim

Syntax:

$(format-cim)

Description: Formats the message into Splunk Common Information Model (CIM) format. Applications that can receive messages in CIM format include Kibana, logstash, and Splunk. Applications that can be configured to log into CIM format include nflog and the Suricata IDS engine.

destination d_cim {
    network(
        "192.168.1.1"
        template("$(format-cim)\n")
    );
};

You can find the exact source of this template function in the syslog-ng OSE GitHub repository.

NOTE:

To use the format-cim() template function, syslog-ng OSE must be compiled with JSON support. For details, see Compiling options of syslog-ng OSE. To see if your syslog-ng OSE binary was compiled with JSON support, execute the syslog-ng --version command.

format-ewmm

Syntax:

$(format-ewmm)

Description: The format-ewmm template function converts the message into the Enterprise-wide message model (EWMM) format. Available in version 3.16 and later.

The following is a sample log message in EWMM format.

<13>1 2018-05-13T13:27:50.993+00:00 my-host @syslog-ng - - -
{"MESSAGE":"<34>Oct 11 22:14:15 mymachine su: 'su root' failed for username on
/dev/pts/8","HOST_FROM":"my-host","HOST":"my-host","FILE_NAME":"/tmp/in","._TAGS":".source.s_file"}
format-gelf

Syntax:

$(format-gelf)

Description: Available in syslog-ng OSE 3.13 and later.

You can use the Graylog Extended Log Format (GELF) template together with the graylog2() destination to send syslog messages to Graylog. GELF is the native data format of Graylog.

Example: Using the format-gelf template function

The following configuration example shows how you can use the format-gelf template:

destination graylog2 {
    network(
        "127.0.0.1"
        port(12201)
        transport(tcp)
        template("$(format-gelf)")
    );
};
format-json

Syntax:

$(format-json parameters)

Description: The format-json template function receives value-pairs as parameters and converts them into JavaScript Object Notation (JSON) format. Including the template function in a message template allows you to store selected information about a log message (that is, its content, macros, or other metadata) in JSON format. Note that the input log message does not have to be in JSON format to use format-json, you can reformat any incoming message as JSON.

You can use the value-pairs that syslog-ng OSE stores about the log message as JSON fields. Using value-pairs, you can:

  • select which value-pairs to use as JSON fields,

  • add custom value-pairs as JSON fields,

  • rename value-pairs, and so on.

For details, see Structuring macros, metadata, and other value-pairs. Note that the syntax of format-json is different from the syntax of value-pairs(): format-json uses a syntax similar to command lines.

NOTE:

By default, syslog-ng OSE handles every message field as a string. For details on how to send selected fields as other types of data (for example, handle the PID as a number), see Specifying data types in value-pairs.

Example: Using the format-json template function

The following example selects every available information about the log message, except for the date-related macros (R_* and S_*), selects the .SDATA.meta.sequenceId macro, and defines a new value-pair called MSGHDR that contains the program name and PID of the application that sent the log message (since you will use the template-function in a template, you must escape the double-quotes).

$(format-json --scope syslog,all_macros,selected_macros \
  --exclude R_* --exclude S_* --key .SDATA.meta.sequenceId \
  --pair MSGHDR=\"$PROGRAM[$PID]: \")

The following example shows how to use this template function to store log messages in JSON format:

destination d_json {
    file(
        "/var/log/messages.json"
        template("$(format-json --scope selected_macros --scope nv_pairs)\n")
    );
};

NOTE:

In the case of syslog-ng macros starting with a dot (for example, ".SDATA.meta.sequenceID"), format-json replaces the dot with an underscore character (for example, {"_SDATA":{"meta":{"sequenceId":"55555"}}}).

format-welf

This template function converts value-pairs into the WebTrends Enhanced Log file Format (WELF). The WELF format is a comma-separated list of name=value elements. Note that the order of the elements is random. If the value contains whitespace, it is enclosed in double-quotes, for example, name="value". For details on the WELF format, see https://www3.trustwave.com/support/kb/article.aspx?id=10899.

To select which value-pairs to convert, use the command-line syntax of the value-pairs() option. For details on selecting value-pairs, see value-pairs().

Example: Using the format-welf() template function

The following example selects every available information about the log message, except for the date-related macros (R_* and S_*), selects the .SDATA.meta.sequenceId macro, and defines a new value-pair called MSGHDR that contains the program name and PID of the application that sent the log message (since you will use the template-function in a template, you must escape the double-quotes).

$(format-welf --scope syslog,all_macros,selected_macros \
  --exclude R_* --exclude S_* --key .SDATA.meta.sequenceId \
  --pair MSGHDR=\"$PROGRAM[$PID]: \")

The following example shows how to use this template function to store log messages in WELF format:

destination d_welf {
    file(
        "/var/log/messages.welf"
        template("$(format-welf --scope selected_macros --scope nv_pairs)\n")
    );
};
geoip (DEPRECATED)

This template function is deprecated. Use geoip2 instead.

Syntax:

$(geoip <IPv4-address>)

Description: This template function returns the 2-letter country code of any IPv4 address or host. IPv6 addresses are not supported. Currently only the 2-letter codes are supported, and only from the default database. For example, $(geoip $HOST)

NOTE:

This template function is available only if syslog-ng OSE has been compiled with the --enable-geoip compiling option.

To retrieve additional GeoIP information, see Looking up GeoIP data from IP addresses (DEPRECATED).

geoip2

Syntax:

$(geoip2 --database <path-to-geoip2-database-file>
    [ --field "registered_country.names.ru" ] ${HOST})

Description: This template function extracts specific fields from the mmdb database using the --field parameter. If you omit this parameter, it returns the 2-letter country code of any IPv4/IPv6 address or host.

NOTE:

This template function is available only if syslog-ng OSE has been compiled with geoip2 support. To enable it, use the --enable-geoip compiling option.

To retrieve additional GeoIP information, see Looking up GeoIP2 data from IP addresses.

getent

Syntax:

$(getent)

Description: Available in syslog-ng OSE 3.13 and later.

You can use the getent template function to look up entries from the Name Service Switch libraries, such as, passwd, services, or protocols.

The following databases are supported:

  • passwd

    Use this database to query data related to a user. Specify the user by either username or user ID. You can query the following data: username, user ID, group ID, GECOS field, home directory, or user shell.

    $(getent passwd testuser name)
    $(getent passwd testuser uid)
    $(getent passwd testuser gid)
    $(getent passwd testuser gecos)
    $(getent passwd testuser dir)
    $(getent passwd testuser shell)

    or

    $(getent passwd 1000 name)
    $(getent passwd 1000 uid)
    $(getent passwd 1000 gid)
    $(getent passwd 1000 gecos)
    $(getent passwd 1000 dir)
    $(getent passwd 1000 shell)

    The queried data is optional. When you do not query any data, the default behavior applies, which is as follows: user ID is returned for username, or username is returned for user ID.

    • Username $(getent passwd testuser) returns user ID 1000.

    • User ID $(getent passwd 1000) returns username testuser.

  • group

    Use this database to query group-related data. The group can be specified using either group ID or group name. You can query the following data: group name, group ID, and members.

    $(getent group adm name)
    $(getent group adm gid)
    $(getent group adm members)

    The queried data is optional. The default behavior is as follows: group ID is returned for group name, or group name is returned for user ID.

    • Group name $(getent group adm) returns group ID 4.

    • Group ID $(getent group 4) returns group name adm.

  • protocols

    Use this database to translate protocol name to protocol ID, or protocol ID to protocol string.

    $(getent protocols tcp)
    $(getent protocols 6)
  • services

    Use this database to translate service name to service ID, or service ID to service name.

    $(getent services http)
    $(getent services 80)
graphite-output

Syntax:

$(graphite-output parameters)

Description: Available in syslog-ng OSE 3.6 and later (Originally appeared in the syslog-ng OSE incubator for syslog-ng 3.5). This template function converts value-pairs from the incoming message to the Graphite plain text protocol format. It is ideal to use with the messages generated by the monitor-source plugin (currently available in the syslog-ng incubator project).

For details on selecting value-pairs in syslog-ng OSE and for possibilities to specify which information to convert to Graphite plain text protocol format, see Structuring macros, metadata, and other value-pairs. Note that the syntax of graphite-output is different from the syntax of value-pairs(): graphite-output uses a the command-line syntax used in the format-json template function.

Example: Using the graphite-output template function

The following configuration example shows, how to send value-pairs with names starting with "vmstat." to Graphite running on localhost, port 2003:

destination d_graphite {
    network( host("localhost") port(2003) template("$(graphite-output --key vmstat.*)"));
};
grep

Syntax:

$(grep condition value-to-select)

Description: The grep template function can search a message context when correlating messages (for example, when you use a pattern database or the grouping-by parser). The context-lookup template function requires a condition (a filter or a string), and returns a specific macro or template of the matching message (for example, the ${MESSAGE} field of the message).

Example: Using the grep template function

The following example selects the message of the context that has a username name-value pair with the root value, and returns the value of the auth_method name-value pair.

$(grep ("${username}" == "root") ${auth_method})

You can to specify multiple name-value pairs as parameters, separated with commas. If multiple messages match the condition of grep, these will be returned also separated by commas. This can be used for example to collect the e-mail recipients from postfix messages.

hash

Syntax:

$(<method> [opts] $arg1 $arg2 $arg3...)

Options:

--length N, -l N
Truncate the hash to the first N characters.

Description: Calculates a hash of the string or macro received as argument using the specified hashing method. If you specify multiple arguments, effectively you receive the hash of the first argument salted with the subsequent arguments.

<method> can be one of md5, md4, sha1, sha256, sha512 and "hash", which is equivalent to md5. Macros are expected as arguments, and they are concatenated without the use of additional characters.

This template function can be used for anonymizing sensitive parts of the log message (for example username) that were parsed out using PatternDB before storing or forwarding the message. This way, the ability of correlating messages along this value is retained.

Also, using this template, quasi-unique IDs can be generated for data, using the --length option. This way, IDs will be shorter than a regular hash, but there is a very small possibility of them not being as unique as a non-truncated hash.

NOTE:

These template functions are available only if syslog-ng OSE has been compiled with the --enable-ssl compile option and the tfhash module has been loaded.

By default, syslog-ng OSE loads every available module. For details, see Loading modules.

Example: Using the $(hash) template function

The following example calculates the SHA1 hash of the hostname of the message:

$(sha1 $HOST)

The following example calculates the SHA256 hash of the hostname, using the salted string to salt the result:

$(sha1 $HOST salted)

To use shorter hashes, set the --length:

$(sha1 --length 6 $HOST)

To replace the hostname with its hash, use a rewrite rule:

rewrite r_rewrite_hostname{set("$(sha1 $HOST)", value("HOST"));};
Example: Anonymizing IP addresses

The following example replaces every IPv4 address in the MESSAGE part with its SHA-1 hash:

rewrite pseudonymize_ip_addresses_in_message {subst ("((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])[.]){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]))", "$(sha1 $0)", value("MESSAGE"));};
if

Syntax:

$(if (<condition>) <true template> <false template>)

Description: Returns the value of the <true template> parameter if the <condition> is true. If the <condition> is false, the value of <false template> is returned.

Example: Using pattern databases and the if template function

The following example returns violation if the username name-value pair of a message is root, and system otherwise.

$(if ("${username}" == "root") "violation" "system")

This can be used to set the class of a message in pattern database rules based on the condition.

<value name="username">$(if ("${username}" == "root") "violation" "system")</value>

Since template functions can be embedded into each other, it is possible to use another template function as the template of the first one. For example, the following expression returns root if the username is root, admin if the username is joe, and normal user otherwise.

<value name="username">
    $(if ("${username}" == "root")
        "root"
        $(if ("${username}" == "joe") "admin" "normal user"))</value>
implode

Syntax:

$(implode <separator> <string1>, <string2>, ...)

Description: Turns a list into a string combining the pieces together with a separator. You can also use the explode template function, which turns a string separated by a specific character into a list. Available in syslog-ng OSE 3.21 and later.

Example: Using the implode template function

The following configuration example shows how you can use the implode template to turn a list into a string:

Configuration Result
$(implode ' ' 'string1,string2,string3,string4,string5') "string1 string2 string3 string4 string5"

You can also use a $(list-*) template function to further manipulate the list. The following example returns the first three elements of the list:

Configuration Result
$(implode ' ' $(list-slice :3 string1,string2,string3,string4,string5)) "string1 string2 string3"
indent-multi-line

Syntax:

$(indent-multi-line parameter)

Description: This template function makes it possible to write multi-line log messages into a file. The first line is written like a regular message, subsequent lines are indented with a tab, in compliance with RFC822.

Example: Using the indent-multi-line template function

The following example writes multi-line messages into a text file.

destination d_file {
    file (
        "/var/log/messages"
        template("${ISODATE} ${HOST} $(indent-multi-line ${MESSAGE})\n")
    );
};
ipv4-to-int

Syntax:

$(ipv4-to-int parameter)

Description: Converts the specified IPv4 address to its numeric representation. The numerical value of an IPv4 address is calculated by treating the IP address as a 4-byte hexadecimal value. For example, the 192.168.1.1 address equals to: 192=C0, 168=A8, 1=01, 1=01, or C0A80101, which is 3232235777 in decimal representation.

NOTE:

This template function is available only if the convertfuncs module has been loaded.

By default, syslog-ng OSE loads every available module. For details, see Loading modules.

List manipulation

The list-* template functions allow you to manipulate comma-separated lists. Such lists represent a simple array type in syslog-ng OSE. Note the following about formatting lists:

  • Values are separated by commas, for example, "item1","item2","item3". The single-element list is an element without a comma.

  • You can use shell-like quotation to embed commas, for example, "item1","ite\,m2","item3".

  • Empty values are skipped (except if they are quoted)

These template functions return a well-formed list, properly encoding and quoting all elements. If a template function returns a single element, all quotation is decoded and the value contains the literal value.

Starting with syslog-ng OSE version 3.10, the following list-related template functions are available. Certain functions allow you to reference an element using its number: note that the list index starts with zero, so the index of the first element is 0, the second element is 1, and so on.

list-append

Syntax:

$(list-append ${list} ${name-value-pair1} ${name-value-pair2} ... )

Description: Returns a list and appends the values of the specified name-value pairs to the end of the list. You can also append elements to an empty list, for example, $(list-append '' 'element-to-add')

list-concat

Syntax:

$(list-concat ${name-value-pair1} ${name-value-pair2} ... )
The commas between the parameters are optional.

Description: This template function creates (concatenates) a list of the values it receives as parameter. The values can be single values (for example, ${HOST}) or lists.

For example, the value of the $(list-concat ${HOST}, ${PROGRAM}, ${PID}) is a comma-separated list.

You can concatenate existing lists into a single list using:

$(list-concat ${list1} ${list2})
list-count

Syntax:

$(list-count ${list} )

Description: Returns the number of elements in the list.

list-head

Syntax:

$(list-head ${list} )

Description: Returns the first element of the list, unquoted.

list-nth

Syntax:

$(list-nth <index-number> ${list} )

Description: Returns the nth element of the list, unquoted. Note that the list index starts with zero, so (list-nth 1 ${list} ) returns the second element, and so on.

list-tail

Syntax:

$(list-tail ${list} )

Description: Returns the list without the first element. For example, if the ${mylist} list contains the one, two, three elements, then $(list-tail ${mylist} ) returns two, three.

list-slice

Syntax:

$(list-slice <from>:<to> ${list} )

Description: Returns the specified subset of the list. Note that the list index starts with zero, for example, $(list-slice 1:2 ${list} ) returns the second and third element of the list, and so on.

You can omit the from or to index if you want to start the subset from the beginning or end of the list, for example: 3: returns the list starting with the 4th element, while :3 returns the first four elements.

Negative numbers select an element from the end of the list, for example, -3: returns the last three element of the list.

length

Syntax:

$(length "<macro>")

Description: Returns the length of the macro in characters, for example, the length of the message. For example, the following filter selects messages that are shorter than 16 characters:

f_short {
    match ('-', value ("$(if ($(length "${MESSAGE}") <= 16) "-" "+")"));
};
lowercase

Syntax:

$(lowercase "<macro>")

Description: Returns the lowercase version of the specified string or macro. For example, the following example uses the lowercase version of the hostname in a directory name:

destination d_file {
    file ("/var/log/${MONTH}/${DAY}/$(lowercase "${HOST}")/messages");
};

Available in syslog-ng OSE 3.5 and later.

Numerical operations

Syntax:

$(<operation> "<value1>" "<value2>")

Description: These template functions allow you to manipulate numbers, that is, to perform addition (+), substraction (-), multiplication (*), division (/), and modulus (%). All of them require two numeric arguments. The result is NaN (Not-a-Number) if the parameters are not numbers, cannot be parsed, or if a division by zero would occur. For example, to add the value of two macros, use the following template function:

$(+ "${<MACRO1>}" "${<MACRO2>}");

Starting with syslog-ng OSE version 3.22 and later, the numerical operators support floating-point values. They behave like the operators in the C programming language:

  • If both operands are integers, they return an integer.

  • If any of the operands is a floating-point number, they return a floating-point result.

For example:

$(/ 3 2) # Both operands are integers, so the result is 1
# One of the operands is a floating point number, so the result is also floating-point
$(/ 3.0 2) # = 1.500000
$(/ 3 2.0) # = 1.500000
$(/ 3.0 2.0) # = 1.500000

To round floating-point numbers, you can use the ceil, floor, and round template functions.

When you are correlating messages and a name-value pair contains numerical values in the messages, you can calculate the lowest (min), highest (max), total (sum), and mean (average) values. These calculations process every message of the correlation context. For details on message correlation, see Correlating log messages. For example, if the messages of the context have a .myfields.load name-value pair, you can find the highest load value using the following template function.

$(max ${.myfields.load})
or

Syntax:

$(or <macro1> <macro2>)

Description: This template function returns the first non-empty argument.

padding

Syntax:

 $(padding <macro> <width> <prepended-character-or-string>)

Description: This template function returns the value of its first parameter (a string or macro), prepended with a string. This string is <width> long, and repeats the character or string set in the third parameter. If you use a single character, it is added <width> times. If you use a string, it is repeated until its length reaches <width>. The default padding character is ' ' (space). For example:

Example: Using the padding template function

If the value of the ${MESSAGE} macro is mymessage, then the output of the padding() template function is the following:

$(padding ${MESSAGE} 10 X)

Output: XXXXXXXXXXmymessage

$(padding ${MESSAGE} 10 foo)

Output: foofoofoofmymessage

python

Syntax:

 $(python <name-of-the-python-method-to-use> <arguments-of-the-method>)

Description: This template function enables you to write a custom template function in Python. You can define a Python block in your syslog-ng OSE configuration file, define one or more Python functions in it, and use the methods as template functions. If you use a Python block, syslog-ng OSE embeds a Python interpreter to process the messages.

    The following points apply to using Python blocks in syslog-ng OSE in general.

  • Python parsers and template functions are available in syslog-ng OSE version 3.10 and later.

    Python destinations and sources are available in syslog-ng OSE version 3.18 and later.

  • Supported Python versions: 2.7 and 3.4+ (if you are using pre-built binaries, check the dependencies of the package to find out which Python version it was compiled with)

  • The Python block must be a top-level block in the syslog-ng OSE configuration file.

  • If you store the Python code in a separate Python file and only include it in the syslog-ng OSE configuration file, make sure that the PYTHON_PATH environment variable includes the path to the Python file, and export the PYTHON_PATH environment variable. For example, if you start syslog-ng OSE manually from a terminal and you store your Python files in the /opt/syslog-ng/etc directory, use the following command: export PYTHONPATH=/opt/syslog-ng/etc

    In production, when syslog-ng OSE starts on boot, you must configure your startup script to include the Python path. The exact method depends on your operating system. For recent Red Hat Enterprise Linux, Fedora, and CentOS distributions that use systemd, the systemctl command sources the /etc/sysconfig/syslog-ng file before starting syslog-ng OSE. (On openSUSE and SLES, /etc/sysconfig/syslog file.) Append the following line to the end of this file: PYTHONPATH="<path-to-your-python-file>", for example, PYTHONPATH="/opt/syslog-ng/etc"

  • The Python object is initiated every time when syslog-ng OSE is started or reloaded.

    Caution:

    If you reload syslog-ng OSE, existing Python objects are destroyed, therefore the context and state information of Python blocks is lost. Log rotation and updating the configuration of syslog-ng OSE typically involves a reload.

  • The Python block can contain multiple Python functions.

  • Using Python code in syslog-ng OSE can significantly decrease the performance of syslog-ng OSE, especially if the Python code is slow. In general, the features of syslog-ng OSE are implemented in C, and are faster than implementations of the same or similar features in Python.

  • Validate and lint the Python code before using it. The syslog-ng OSE application does not do any of this.

  • Python error messages are available in the internal() source of syslog-ng OSE.

  • You can access the name-value pairs of syslog-ng OSE directly through a message object or a dict.

  • To help debugging and troubleshooting your Python code, you can send log messages to the internal() source of syslog-ng OSE. For details, see Logging from your Python code.

The following points apply to Python parsers.

  • The first argument in the definition of the Python function is the actual log message. This is implicitly passed to the function, you do not have to use it in the template function.

  • The value of the template function is return value of the Python function.

  • To reference a name-value pair or a macro in the Python function, use the dot-notation. For example, if the first argument in the definition of the function is called log-message, the value of the HOST macro is log-message.HOST, and so on.

  • You can define new name-value pairs in the Python function. For example, if the first argument in the definition of the function is called log-message, you can create a new name-value pair like this: log_message["new-macro-name"]="value". This is useful when you parse a part of the message from Python, or lookup a value based on data extracted from the log message.

Declaration:
python {
def <name_of_the_python_function>(<log_message>, <optional_other_arguments>):
    # <your-python-code>
    return <value_of_the_template_function>
};

template <template-name> {
    template($(python <name_of_the_python_function>));
};
Example: Writing template functions in Python

The following example creates a Python template function called return_message that returns the MESSAGE part of the log message.

@version: 3.22

python {
def return_message(log_message):
    return log_message.MESSAGE
};

destination d_local {
    file("/tmp/logs.txt" template("[$(python return_message)]\n"));
};

The following example creates a Python template function called resolve_host that receives an IP address as an argument, and attempts to resolve it into a hostname.

@version: 3.22

python {
import socket

def resolve_host(log_message, hostname):
    try:
        return socket.gethostbyaddr(hostname)[0]
    except (socket.herror, socket.error):
        return 'unknown'
};

destination d_local {
    file(
        "/tmp/logs.txt"
        template("${ISODATE} $(python resolve_host ${SOURCE_IP}) ${MESSAGE}\n")
    );
};
replace-delimiter

Syntax:

$(replace-delimiter "<old-delimiters>" "<new-delimiter>" "<macro>")

Description: Replaces the delimiter character with a new one. For example, the following example replaces the tabulators (\t) in the message with semicolons (;):

$(replace-delimiter "\t" ";" "${MESSAGE}")

Available in syslog-ng OSE 3.5 and later.

round

Syntax:

$(round argument)

Description: Rounds a floating-point number to the nearest integer. For example, $(round 1.5) is 2. See also the ceil and floor template functions.

This template function has an optional second argument that sets the precision of rounding. The default is 0 (output a natural number), but values up to 20 are accepted. For example, $(round 2.123456 4) is 2.1235.

sanitize

Syntax:

$(sanitize <options> "<macro1>" "<macro2> ...")

Description: This file replaces the special characters in macro values, for example, it can replace the slash (/) characters in a filename with the underscore (_) character. If you specify multiple arguments, they will be concatenated using the / character, so they can be used as separate directory levels when used in filenames.

The function has the following options:

  • --ctrl-chars or -c
  • Filter control characters (characters that have an ASCII code of 32 or lower). This option is used by default.

  • --invalid-chars <characterlist> or -i <characterlist>
  • The list of characters to be replaced with underscores (_). The default list contains the / character. The following example replaces the \ and @ characters, so for example, fo\o@bar becomes foobar:

    $(sanitize -i \@ $PROGRAM)
  • --no-ctrl-chars or -C
  • Do not filter the control characters (characters that have an ASCII code of 32 or lower).

  • --replacement <replacement-character> or -r <replacement-character>
  • The character used to replace invalid characters. By default, this is the underscore (_). The following example replaces invalid characters with colons instead of underscores, so for example, foo/bar becomes foo;bar:

    $(sanitize -r ; $PROGRAM)
Example: Using the sanitize template function

The following example uses the sanitize function on two macros, and the results are used as directory names in a file destination.

file("/var/log/$(sanitize $HOST $PROGRAM)/messages");

This is equivalent to file("/var/log/$HOST/$PROGRAM/messages");, but any slashes in the values of the $HOST and $PROGRAM macros are replaced with underscores.

stardate

Syntax:

$(stardate [option] "<date-in-unixtime>")

Description: Converts a date in UNIXTIME (for example, ${UNIXTIME}) into stardate, displaying the year and the progress of the year in a number of digits (YYYY.NNN). You can set the number of digits using the --digits option, for example:

$(stardate --digits 2 "${R_UNIXTIME}")
strip

Syntax:

$(strip "<macro>")

Description: Deletes whitespaces from the beginning and the end of a macro. You can specify multiple macros separated with whitespace in a single template function, for example:

$(strip "${MESSAGE}" "${PROGRAM}")
substr

Syntax:

$(substr "<argument>" "<offset>" "<length>")

Description: This function extracts a substring of a string.

  • argument
  • The string to extract the substring from, for example, "${MESSAGE}"

  • offset
  • Specifies where the substring begins (in characters). 0 means to start from the beginning of the string, 5 means to skip the first 5 characters of the string, and so on. Use negative numbers to specify where to start from the end of the string, for example, -1 means the last character, -5 means to start five characters before the end of the string.

  • length
  • Optional parameter: The number of characters to extract. If not specified, the substring will be extracted from the offset to the end of the string. Use negative numbers to stop the substring before the end of the string, for example, -5 means the substring ends five characters before the end of the string.

Example: Using the substr template function

Skip the first 15 characters of the message, and select the rest:

$(substr "${MESSAGE}" "15");

Select characters 16-30 of the message (15 characters with offset 15):

$(substr "${MESSAGE}" "15" "15");

Select the last 15 characters of the message:

$(substr "${MESSAGE}" "-15");

A template that converts the message to RFC3164 (BSD-syslog) format and truncates the messages to 1023 characters:

template t_truncate_messages {
    template("$(substr \"<$PRI>$DATE $HOST $MSGHDR$MESSAGE\" \"0\" \"1023\")\n");
    template-escape(no);
};
template

Syntax:

$(template <template-name>)
$(template $<dynamic-template-name>)
$(template $<dynamic-template-name> '<optional-fallback-template>')

Description: This template function looks up the <template-name> in the configuration and uses that to format its result. The referenced template can be static or dynamic. For static templates, syslog-ng OSE resolves the template when it starts, or when the configuration is reloaded. For dynamic templates, the results are resolved runtime (for dynamic templates, the template name contains at least one '$' character). For example, the name of the template to be invoked can be extracted from the message, or from a name-value pair set using the add-contextual-data() feature.

For dynamic templates, you can set an optional second template. This second template will be the results of the template function if resolving the dynamic template fails for some reason. For example:

$(template ${my-dynamic-template} '$DATE $HOST $MSGHDR$MSG\n')

Available in syslog-ng OSE 3.22 and later.

uppercase

Syntax:

$(uppercase "<macro>")

Description: Returns the uppercase version of the specified string or macro. For example, the following example uses the uppercase version of the hostname in a directory name:

destination d_file {
    file ("/var/log/${MONTH}/${DAY}/$(uppercase "${HOST}")/messages");
};

Available in syslog-ng OSE 3.5 and later.

url-decode

Syntax:

$(url-decode <string-pr-macro-1> <string-pr-macro-2> ... )

Description: You can use the url-decode template function to decode url-encoded strings and macros. For example, $(url-decode %3C%3E) yields <>. The url-decode can receive multiple parameters (maximum 64). In this case, each parameter is decoded separately, and simply concatenated.

Available in syslog-ng OSE version 3.18 and later.

url-encode

Syntax:

$(url-encode ${MESSAGE} )\n")

Description: You can use the url-encode template function together with the telegram() destination to send syslog messages to Telegram. The url-encode template function escapes strings. All input characters that are not a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version.

Available in syslog-ng OSE version 3.18 and later. (In version 3.16-3.17, this template function was called urlencode.)

uuid

Syntax:

$(uuid)

Description: Generates a Universally Unique IDentifier (UUID) that complies with RFC4122. That way, an UUID can be added to the message soon after it is received, so messages stored in multiple destinations can be identified. For example, when storing messages in a database and also in files, the UUID can be used to find a particular message both in the database and the files.

To generate a UUID, you can use a rewrite rule to create a new value-pair for the message.

Example: Using Universally Unique Identifiers

The following example adds a value-pair called MESSAGE_UUID to the message using a rewrite rule and a template.

rewrite r_add_uuid {
    set("$(uuid)" value("MESSAGE_UUID"));
};

destination d_file {
    file (
        "/var/log/messages"
        template("$MESSAGE_UUID $ISODATE $HOST $MSG\n")
        template-escape(no)
    );
};

log {
    source(s_network);
    rewrite(r_add_uuid);
    destination(d_file);
};

NOTE:

This template function is available only if the tfuuid module has been loaded.

By default, syslog-ng OSE loads every available module. For details, see Loading modules.


Was this topic helpful?

[Select Rating]



Modifying the on-the-wire message format

Macros, templates, and template functions allow you to fully customize the format of the message. This flexibility makes it possible to use syslog-ng OSE in some unexpected way if needed, for example, to emulate simple, plain-text protocols. The following example shows you how to send LPUSH commands to a Redis server.

NOTE:

The purpose of this example is to demonstrate the flexibility of syslog-ng OSE. A dedicated Redis destination is available in syslog-ng OSE version 3.5. For details, see redis: Storing name-value pairs in Redis.

The following template is a valid LPUSH command in accordance with the Redis protocol, and puts the $MESSAGE into a separate list for every $PROGRAM:

template t_redis_lpush {
    template("*3\r\n$$5\r\nLPUSH\r\n$$$(length ${PROGRAM})\r\n${PROGRAM}\r\n$$$(length ${MESSAGE})\r\n${MESSAGE}\r\n");
};

If you use this template in a network() destination, syslog-ng OSE formats the message according to the template, and sends it to the Redis server.

destination d_redis_tcp {
    network("127.0.0.1" port(6379) template(t_redis_lpush));
};

Was this topic helpful?

[Select Rating]



Modifying messages using rewrite rules

The syslog-ng application can rewrite parts of the messages using rewrite rules. Rewrite rules are global objects similar to parsers and filters and can be used in log paths. The syslog-ng application has two methods to rewrite parts of the log messages: substituting (setting) a part of the message to a fix value, and a general search-and-replace mode.

Substitution completely replaces a specific part of the message that is referenced using a built-in or user-defined macro.

General rewriting searches for a string in the entire message (or only a part of the message specified by a macro) and replaces it with another string. Optionally, this replacement string can be a template that contains macros.

Rewriting messages is often used in conjunction with message parsing parser: Parse and segment structured messages.

Rewrite rules are similar to filters: they must be defined in the syslog-ng configuration file and used in the log statement. You can also define the rewrite rule inline in the log path.

NOTE:

The order of filters, rewriting rules, and parsers in the log statement is important, as they are processed sequentially.


Was this topic helpful?

[Select Rating]



Replacing message parts

To replace a part of the log message, you have to:

  • define a string or regular expression to find the text to replace

  • define a string to replace the original text (macros can be used as well)

  • select the field of the message that the rewrite rule should process

Substitution rules can operate on any soft macros, for example MESSAGE, PROGRAM, or any user-defined macros created using parsers. Hard macros cannot be modified. For details on the hard and soft macros, see Hard vs. soft macros). You can also rewrite the structured-data fields of messages complying to the RFC5424 (IETF-syslog) message format. Substitution rules use the following syntax:

Declaration:
rewrite <name_of_the_rule> {
    subst(
        "<string or regular expression to find>",
        "<replacement string>", value(<field name>), flags()
    );
};

The type() and flags() options are optional. The type() specifies the type of regular expression to use, while the flags() are the flags of the regular expressions. For details on regular expressions, see Regular expressions.

A single substitution rule can include multiple substitutions that are applied sequentially to the message. Note that rewriting rules must be included in the log statement to have any effect.

TIP:

For case-insensitive searches, add the flags(ignore-case) option. To replace every occurrence of the string, add flags(global) option. Note that the store-matches flag is automatically enabled in rewrite rules.

Example: Using substitution rules

The following example replaces the IP in the text of the message with the string IP-Address.

rewrite r_rewrite_subst{
    subst("IP", "IP-Address", value("MESSAGE"));
};

To replace every occurrence, use:

rewrite r_rewrite_subst{
    subst("IP", "IP-Address", value("MESSAGE"), flags("global"));
};

Multiple substitution rules are applied sequentially. The following rules replace the first occurrence of the string IP with the string IP-Addresses.

rewrite r_rewrite_subst{
    subst("IP", "IP-Address", value("MESSAGE"));
    subst("Address", "Addresses", value("MESSAGE"));
};
Example: Anonymizing IP addresses

The following example replaces every IPv4 address in the MESSAGE part with its SHA-1 hash:

rewrite pseudonymize_ip_addresses_in_message {subst ("((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])[.]){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]))", "$(sha1 $0)", value("MESSAGE"));};

Was this topic helpful?

[Select Rating]



Related Documents