Chat now with support
Chat with Support

syslog-ng Premium Edition 6.0.17 - Administration Guide

Preface Chapter 1. Introduction to syslog-ng Chapter 2. The concepts of syslog-ng Chapter 3. Installing syslog-ng Chapter 4. The syslog-ng PE quick-start guide Chapter 5. The syslog-ng PE configuration file Chapter 6. Collecting log messages — sources and source drivers Chapter 7. Sending and storing log messages — destinations and destination drivers Chapter 8. Routing messages: log paths, reliability, and filters Chapter 9. Global options of syslog-ng PE Chapter 10. TLS-encrypted message transfer Chapter 11. FIPS-compliant syslog-ng Chapter 12.  Reliable Log Transfer Protocol™ Chapter 13. Reliability and minimizing the loss of log messages Chapter 14. Manipulating messages Chapter 15. Parsing and segmenting structured messages Chapter 16. Processing message content with a pattern database Chapter 17. Statistics and metrics of syslog-ng Chapter 18. Multithreading and scaling in syslog-ng PE Chapter 19. Troubleshooting syslog-ng Chapter 20. Best practices and examples

Chapter 6. Collecting log messages — sources and source drivers

How sources work

A source is where syslog-ng receives log messages. Sources consist of one or more drivers, each defining where and how messages are received.

To define a source, add a source statement to the syslog-ng configuration file using the following syntax:

source <identifier> { source-driver(params); source-driver(params); ... };

Example 6.1. A simple source statement

The following source statement receives messages on the TCP port 1999 of the interface having the 10.1.2.3 IP address.

source s_demo_tcp { network(ip(10.1.2.3) port(1999)); };

Example 6.2. A source statement using two source drivers

The following source statement receives messages on the 1999 TCP port and the 1999 UDP port of the interface having the 10.1.2.3 IP address.

source s_demo_two_drivers {
           network(ip(10.1.2.3) port(1999));
           network(ip(10.1.2.3) port(1999) transport("udp")); };

Example 6.3. Setting default priority and facility

If the message received by the source does not have a proper syslog header, you can use the default-facility() and default-priority() options to set the facility and priority of the messages. Note that these values are applied only to messages that do not set these parameters in their header.

source headerless_messages { network(default-facility(syslog) default-priority(emerg)); };

Define a source only once. The same source can be used in several log paths. Duplicating sources causes syslog-ng to open the source (TCP/IP port, file, and so on) more than once, which might cause problems. For example, include the /dev/log file source only in one source statement, and use this statement in more than one log path if needed.

Caution:

Sources and destinations are initialized only when they are used in a log statement. For example, syslog-ng PE starts listening on a port or starts polling a file only if the source is used in a log statement. For details on creating log statements, see Chapter 8, Routing messages: log paths, reliability, and filters.

To collect log messages on a specific platform, it is important to know how the native syslogd communicates on that platform. The following table summarizes the operation methods of syslogd on some of the tested platforms:

Table 6.1. Communication methods used between the applications and syslogd

Platform Method
Linux A SOCK_DGRAM unix socket named /dev/log. Newer distributions that use systemd collect log messages into a journal file.
BSD flavors A SOCK_DGRAM unix socket named /var/run/log.
Solaris (2.5 or below) An SVR4 style STREAMS device named /dev/log.
Solaris (2.6 or above) In addition to the STREAMS device used in earlier versions, 2.6 uses a new multithreaded IPC method called door. By default the door used by syslogd is /etc/.syslog_door.
Windows Special Eventlog containers that can be accessed using the proprietary API of Microsoft.
HP-UX 11 or later HP-UX uses a named pipe called /dev/log that is padded to 2048 bytes, for example source s_hp-ux {pipe ("/dev/log" pad-size(2048)}.
AIX 5.2 and 5.3 A SOCK_STREAM or SOCK_DGRAM unix socket called /dev/log.

Each possible communication mechanism has a corresponding source driver in syslog-ng. For example, to open a unix socket with SOCK_DGRAM style communication use the driver unix-dgram. The same socket using the SOCK_STREAM style — as used under Linux — is called unix-stream.

Example 6.4. Source statement on a Linux based operating system

The following source statement collects the following log messages:

  • internal(): Messages generated by syslog-ng.

  • network(transport("udp")): Messages arriving to the 514/UDP port of any interface of the host.

  • unix-dgram("/dev/log");: Messages arriving to the /dev/log socket.

source s_demo {
    internal();
    network(transport("udp"));
    unix-dgram("/dev/log"); };

The following table lists the source drivers available in syslog-ng.

Table 6.2. Source drivers available in syslog-ng

Name Description
eventlog() Collects Windows eventlog messages.
file() Opens the specified file and reads messages.
internal() Messages generated internally in syslog-ng.
network() Receives messages from remote hosts using the BSD-syslog protocol over IPv4 and IPv6. Supports the TCP, UDP,RLTP™, and TLS network protocols.
pipe() Opens the specified named pipe and reads messages.
program() Opens the specified application and reads messages from its standard output.
sql() Collects logs from tables of relational database
sun-stream(), sun-streams() Opens the specified STREAMS device on Solaris systems and reads incoming messages.
syslog() Listens for incoming messages using the new IETF-standard syslog protocol.
system() Automatically detects which platform syslog-ng PE is running on, and collects the native log messages of that platform.
systemd-journal() Collects messages directly from the journal of platforms that use systemd.
systemd-syslog() Collects messages from the journal using a socket on platforms that use systemd.
unix-dgram() Opens the specified unix socket in SOCK_DGRAM mode and listens for incoming messages.
unix-stream() Opens the specified unix socket in SOCK_STREAM mode and listens for incoming messages.

Collecting messages from Windows eventlog sources

The syslog-ng PE application can collect messages from the standard Windows eventlog containers, as well as from custom containers. The syslog-ng PE application forwards the messages from three standard eventlog containers (Application, Security, System). To enable or disable these sources, or to add custom eventlog containers, complete the following steps:

Caution:

If an eventlog container becomes corrupt, syslog-ng PE will stop processing the event source. A log message (Eventlog file is corrupt) is sent directly to the log server to notify about the error.

Caution:

Hazard of data loss! It is not recommended to setup archiving for the event container. It is possible to lose logs if there are non-processed events in the event container when the archiving is started. Windows closes and renames the event container and starts a new one regardless of any reading applications.

To prevent this, enable overwrite events when needed mode in the Windows Event Viewer with the following conditions:

  • The messages are not generated faster than the syslog-ng PE's processing speed.

  • There is enough window between the first and the last events for planned syslog-ng PE stops. Ensure that new events will not overwrite the event last read by syslog-ng PE during syslog-ng PE stop.

Example 6.5. Using the eventlog() driver

source s_AGENT_EVENT{
    eventlog(channel(Application)
        prefix(".SDATA.win@18372.4")
        read-old-records(no)
    );
    eventlog(channel(A*lic?tion)
        prefix(".SDATA.win@18372.4")
    );
    eventlog(channel(*)
    prefix(".SDATA.win@18372.4")
    );
};

eventlog() source options

The following options can be specified for the eventlog() driver:

default-facility()
Type: facility string
Default: kern

Description: This parameter assigns a facility value to the messages received from the eventlog source, if the message does not specify one.

default-level()
Type: priority string
Default:

Description: The alias of the default-priority() parameter.

channel()
Type: string
Default:

Description: Set the windows containers, separated with a space. The container name may include wildcard characters (for example *).

event-api()
Type: EVT_API or EVTX_API
Default: Under Windows Vista: EVT_API, Windows Vista and above: EVTX_API

Description: To read the messages from eventlog containers, the syslog-ng PE application uses the nativeWindows API tools. The Windows Vista and newer platforms use an XML-based eventlog format. The API (calledEVTX) that reads the XML-messages from the eventlog container and passes them to syslog-ng PE is inherently slow, severely limiting the performance of syslog-ng PE. The API tools that syslog-ng PE uses on the Microsoft Windows XP and 2003 Server platforms is available on the newer platforms as well, and can increase the speed of reading from eventlog containers, up to 500%. However, using this old API (called EVT) has limitations when used with XML-based eventlog containers.

prefix()
Type: string
Default:

Description: To send eventlog message metadata as SDATA when sending the message in IETF-syslog format, enter the prefix in the following format: .SDATA.<name>@<private enterprise number>. For example, .SDATA.mySDATA-field@18372.4. (18372.4 is the private enterprise number of BalaBit IT Security, the developer of syslog-ng PE.)

NOTE:

On the destination server, you can refer to message fields like: ${.SDATA.<prefix()>.EVENT_SOURCE}

read-old-records()
Type: yes|no
Default: no

Description: If set to yes, syslog-ng PE will start reading the records from the beginning of the container, if the container has not been read yet. If set to no, syslog-ng PE will read only the new records. If the source has a state in the persist file, this option will have no effect.

Limitations of using the EVT API on Windows Vista or newer

When using the EVT API to read messages from XML-based eventlog containers, note the following limitations.

  • The EVT API supports only containers are listed under the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\ key in the registry. The three default containers (Security, Application, System) are listed here by default.

  • Derived containers (for example, microsoft-windows-bits-client/analytic) are not supported.

  • The following macros do not work, that is, their values will be empty: ${EVENT_CATEGORY}, ${EVENT_MESSAGE_XML}, ${EVENT_MSG_XML}, and ${EVENT_TASK}.

  • The way how the EVT API provided by Microsoft reads the values of the XML-based is not perfect. Therefore, filters that use these macros might not work properly. The following list shows the known limitations and errors:

    • ${EVENT_LEVEL}: The value of this macro can be incorrect. It will always be a number as expected, but not necessarily the correct value.

    • ${EVENT_SOURCE}: It is possible that the value of this macro will be formatted differently. For example, Microsoft-Windows-Security-Auditing instead of Microsoft Windows security auditing.

    • ${EVENT_TYPE}: The value of this macro is known to be incorrect in the following scenarios:

      • For security audit logs, if ${EVENT_LEVEL} is 4, the value of the ${EVENT_TYPE} macro will be Audit Success instead of Information. This is known to happen when the "Audit log cleared" event is generated.

      • For non-security audit logs, if ${EVENT_LEVEL} is 0, the value of the ${EVENT_TYPE} macro will be Undefined instead of Information.

    • ${EVENT_USERNAME}: The EVT API will always add value of the Username field to this macro. If the Username field of the event is empty, the EVTX API used the TargetUserName or the SubjectUserName instead, but this is not possible with the EVT API. For example, the Username field of events from the security container will be often N/A.

    • ${PRI}: The value of this macro is based on the ${EVENT_LEVEL}, therefore, it can be incorrect.

Collecting internal messages

All messages generated internally by syslog-ng use this special source. To collect warnings, errors and notices from syslog-ng itself, include this source in one of your source statements.

internal()

The syslog-ng application will issue a warning upon startup if none of the defined log paths reference this driver.

Example 6.6. Using the internal() driver

source s_local { internal(); };

The syslog-ng PE application sends the following message types from the internal() source: 

  • fatal: Priority value: critical (2), Facility value: syslog (5)

  • error: Priority value: error (3), Facility value: syslog (5)

  • warning: Priority value: warning (4), Facility value: syslog (5)

  • notice: Priority value: notice (5), Facility value: syslog (5)

  • info: Priority value: info (6), Facility value: syslog (5)

internal() source options

The internal() driver has the following options:

host-override()
Type: string
Default:

Description: Replaces the ${HOST} part of the message with the parameter string.

log-iw-size()
Type: number (messages)
Default: 1000

Description: The size of the initial window, this value is used during flow control. If the max-connections() option is set, the log-iw-size() will be divided by the number of connections, otherwise log-iw-size() is divided by 10 (the default value of the max-connections() option). The resulting number is the initial window size of each connection. For optimal performance when receiving messages from syslog-ng PE clients, make sure that the window size is larger than the flush-lines() option set in the destination of your clients.

Example 6.7. Initial window size of a connection

If log-iw-size(1000) and max-connections(10), then each connection will have an initial window size of 100.


normalize-hostnames()
Accepted values: yes | no
Default: no

Description: If enabled (normalize-hostnames(yes)), syslog-ng PE converts the hostnames to lowercase.

program-override()
Type: string
Default:

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

tags()
Type: string
Default:

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

use-fqdn()
Type: yes or no
Default: no

Description: Add Fully Qualified Domain Name instead of short hostname. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

use-syslogng-pid()
Type: yes or no
Default: no

Description: If the value of this option is yes, then the PID value of the message will be overridden with the PID of the running syslog-ng process.

Collecting messages from text files

Collects log messages from plain-text files, for example from the logfiles of an Apache webserver.

The syslog-ng application notices if a file is renamed or replaced with a new file, so it can correctly follow the file even if logrotation is used. When syslog-ng is restarted, it records the position of the last sent log message in the /opt/syslog-ng/var/syslog-ng.persist file, and continues to send messages from this position after the restart.

The file driver has a single required parameter specifying the file to open. For the list of available optional parameters, see the section called “file() source options”.

Caution:

Hazard of data loss! If your log files are on an NFS-mounted network file system, see the section called “NFS file system for log files”.

Declaration: 

file("filename");

Example 6.8. Using the file() driver

source s_file { file("/var/log/messages"); };

NOTE:

On Microsoft Windows platforms, enclose paths and filenames between single quotes, for example, 'C:\temp\logs\mylogs.log'


Example 6.9. Tailing files

The following source checks the access.log file every second for new messages.

source s_tail { file("/var/log/apache/access.log"
            follow-freq(1) flags(no-parse)); };

NOTE:

If the message does not have a proper syslog header, syslog-ng treats messages received from files as sent by the kern facility. Use the default-facility() and default-priority() options in the source definition to assign a different facility if needed.

Wildcards and file sources. 

In syslog-ng PE, the filename (but not the pathname) may include wildcard characters (for example *). Note that when using wildcards in filenames, always set how often syslog-ng PE should check the file for new messages using the follow-freq() parameter.

Caution:

If you use wildcards in multiple file sources, make sure that the files and folders that match the wildcards do not overlap. That is, every file and folder should belong to only one file source. Monitoring a file from multiple wildcard sources can lead to data loss.

To use wildcards in the file source if your log files are on an NFS file system, set the force-directory-polling() option to yes to detect newly created files. Note that wildcard file sources are available only in syslog-ng PE version 6.0.3 and newer versions of the 6.x branch, and are not yet available in syslog-ng PE version 7.

When using wildcards, syslog-ng PE monitors every matching file, and can receive new log messages from any of the files. However, monitoring (polling) many files (that is, more than ten) has a significant overhead and may affect performance. On Linux this overhead is not so significant, because syslog-ng PE uses the inotify feature of the kernel.

Also, by default, the operating system notifies syslog-ng PE when an application modifies a logfile. However, in some cases this does not happen, because the file-monitoring API of the operating system does not notice that the file has changed, for example, when monitoring logfiles of the Windows DHCP service. In such cases, enable the force-directory-polling() option. Note that enabling this option decreases the performance of syslog-ng PE if you monitor lots of logfiles.

Example 6.10. Using wildcards in the filename

The following example monitors every file with the .log extension in the /var/application directory for log messages. Note that only syslog-ng PE supports wildcards in the file and pathnames.

source s_file { file("/var/application/*.log" follow-freq(1));};

Notes on reading kernel messages

Note the following points when reading kernel messages on various platforms.

  • The kernel usually sends log messages to a special file (/dev/kmsg on BSDs, /proc/kmsg on Linux). The file() driver reads log messages from such files. The syslog-ng application can periodically check the file for new log messages if the follow-freq() option is set.

  • On Linux, the klogd daemon can be used in addition to syslog-ng to read kernel messages and forward them to syslog-ng. klogd used to preprocess kernel messages to resolve symbols and so on, but as this is deprecated by ksymoops there is really no point in running both klogd and syslog-ng in parallel. Also note that running two processes reading /proc/kmsg at the same time might result in dead-locks.

  • When using syslog-ng to read messages from the /proc/kmsg file, syslog-ng automatically disables the follow-freq() parameter to avoid blocking the file.

  • To read the kernel messages on HP-UX platforms, use the following options in the source statement:

    file("/dev/klog" program-override("kernel") flags(kernel) follow-freq(0));

File sources and the RFC5424 message format

When reading messages from a file and forwarding them in IETF-syslog (RFC5424) format, syslog-ng PE automatically adds all file-related information to the file@18372.4 SDATA block. When the source is file and the transport protocol is syslog or syslog-protocol flags were used in the destination side, the message will contain the following source file-related information:

  • size: size of the file

  • position: file position the message was read from

  • name: name of the file

Example 6.11. File-related information in message

309 <38>1 2010-10-19T15:50:45.018203+02:00 server1 localprg 1234 - [timeQuality isSynced="0" tzKnown="0"][file@18372.4 size="184567" pos="1024" name="/var/tmp/msg.txt"] seq: 0000000001, runid: 1287496244, stamp: 2010-10-19T15:50:45 messagetext


file() source options

The file() driver has the following options:

default-facility()
Type: facility string
Default: kern

Description: This parameter assigns a facility value to the messages received from the file source, if the message does not specify one.

default-priority()
Type: priority string
Default:

Description: This parameter assigns an emergency level to the messages received from the file source, if the message does not specify one. For example, default-priority(warning)

encoding()
Type: string
Default:

Description: Specifies the characterset (encoding, for example UTF-8) of messages using the legacy BSD-syslog protocol. To list the available character sets on a host, execute the iconv -l command. For details on how encoding affects the size of the message, see the section called “Message size and encoding”.

flags()
Type: assume-utf8, empty-lines, expect-hostname, kernel, no-multi-line, no-parse, dont-store-legacy-msghdr, syslog-protocol, validate-utf8
Default: empty set

Description: Specifies the log parsing options of the source.

  • assume-utf8: The assume-utf8 flag assumes that the incoming messages are UTF-8 encoded, but does not verify the encoding. If you explicitly want to validate the UTF-8 encoding of the incoming message, use the validate-utf8 flag.

  • dont-store-legacy-msghdr: By default, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, for example, adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). If you do not want to store the original header of the message, enable the dont-store-legacy-msghdr flag.

  • empty-lines: Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng PE removes empty lines automatically.

  • expect-hostname: If the expect-hostname flag is enabled, syslog-ng PE will assume that the log message contains a hostname and parse the message accordingly. This is the default behavior for TCP sources. Note that pipe sources use the no-hostname flag by default.

  • kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.

  • no-hostname: Enable the no-hostname flag if the log message does not include the hostname of the sender host. That way syslog-ng PE assumes that the first part of the message header is ${PROGRAM} instead of ${HOST}. For example:

    source s_dell { network(port(2000) flags(no-hostname)); };
  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line. Note that this happens only if the underlying transport method actually supports multi-line messages. Currently the rltp, syslog(), network(), unix-dgram() drivers support multi-line messages.

  • no-parse: By default, syslog-ng PE parses incoming messages as syslog messages. The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng PE application will generate a new syslog header (timestamp, host, and so on) automatically and put the entire incoming message into the MSG part of the syslog message. This flag is useful for parsing messages not complying to the syslog format.

    If you are using the flags(no-parse) option, then syslog message parsing is completely disabled, and the entire incoming message is treated as the ${MESSAGE} part of a syslog message. In this case, syslog-ng PE generates a new syslog header (timestamp, host, and so on) automatically. Note that since flags(no-parse) disables message parsing, it interferes with other flags, for example, disables flags(no-multi-line).

  • syslog-protocol: The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC5424), but without the frame header. Note that this flag is not needed for the syslog driver, which handles only messages that have a frame header.

  • validate-utf8: The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see the section called “IETF-syslog messages”). If theBOM[4]character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.

follow-freq()
Type: number (seconds)
Default: 1

Description: Indicates that the source should be checked periodically. This is useful for files which always indicate readability, even though no new lines were appended. If this value is higher than zero, syslog-ng will not attempt to use poll() on the file, but checks whether the file changed every time the follow-freq() interval (in seconds) has elapsed. Floating-point numbers (for example 1.5) can be used as well.

force-directory-polling()
Type: yes or no
Default: no

Description: Specifies whether syslog-ng should force the polling of the logfiles that match the wildcarded filenames specified in the file() driver.

NOTE:

Enabling this option decreases performance if you monitor lots of logfiles.

To use wildcards in the file source if your log files are on an NFS file system, set the force-directory-polling() option to yes to detect newly created files. Note that wildcard file sources are available only in syslog-ng PE version 6.0.3 and newer versions of the 6.x branch, and are not yet available in syslog-ng PE version 7.

keep-timestamp()
Type: yes or no
Default: yes

Description: Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Caution:

To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng PE).

log-fetch-limit()
Type: number (messages)
Default: 10

Description: The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log-fetch-limit() is too high.

log-iw-size()
Type: number
Default: 1000

Description: The size of the initial window, this value is used during flow control. Make sure that log-iw-size() is larger than the value of log-fetch-limit().

When using wildcards in the filenames, syslog-ng PE attempts to read log-fetch-limit() number of messages from each file. For optimal performance, make sure that log-iw-size() is greater than log-fetch-limit()*(the-number-of-matching-files).

Example 6.12. Initial window size of file sources

If log-fetch-limit() is 10, and your wildcard file source has 200 files, then log-iw-size() should be at least 2000.


log-msg-size()
Type: number (bytes)
Default: Use the global log-msg-size() option, which defaults to 65535.

Description: Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified. For details on how encoding affects the size of the message, see the section called “Message size and encoding”.

log-prefix() (DEPRECATED)
Type: string
Default:

Description: A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program-override() instead.

multi-line-garbage()
Type: regular expression
Default: empty string

Description: Use the multi-line-garbage() option when processing multi-line messages that contain unneeded parts between the messages. Specify a string or regular expression that matches the beginning of the unneeded message parts. If the multi-line-garbage() option is set, syslog-ng PE ignores the lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix(). See also the multi-line-prefix() option.

When receiving multi-line messages from a source when the multi-line-garbage() option is set, but no matching line is received between two lines that match multi-line-prefix(), syslog-ng PE will continue to process the incoming lines as a single message until a line matching multi-line-garbage() is received.

Caution:

If the multi-line-garbage() option is set, syslog-ng PE discards lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix().

NOTE:

Starting with syslog-ng PE version 3.2.1, a message is considered complete if no new lines arrive to the message for 10 seconds, even if no line matching the multi-line-garbage() option is received.

multi-line-prefix()
Type: regular expression
Default: empty string

Description: Use the multi-line-prefix() option to process multi-line messages, that is, log messages that contain newline characters (for example, Tomcat logs). Specify a string or regular expression that matches the beginning of the log messages. Use as simple regular expressions as possible, because complex regular expressions can severely reduce the rate of processing multi-line messages. If the multi-line-prefix() option is set, syslog-ng PE ignores newline characters from the source until a line matches the regular expression again, and treats the lines between the matching lines as a single message. See also the multi-line-garbage() option.

NOTE:

Starting with syslog-ng PE version 3.2.1, a message is considered complete if no new lines arrive to the message for 10 seconds, even if no line matching the multi-line-garbage() option is received.

TIP:
  • To make multi-line messages more readable when written to a file, use a template in the destination and instead of the ${MESSAGE} macro, use the following: $(indent-multi-line ${MESSAGE}). This expression inserts a tab after every newline character (except when a tab is already present), indenting every line of the message after the first. For example:

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

    For details on using templates, see the section called “Templates and macros”.

  • To actually convert the lines of multi-line messages to single line (by replacing the newline characters with whitespaces), use the flags(no-multi-line) option in the source.

Example 6.13. Processing Tomcat logs

The log messages of the Apache Tomcat server are a typical example for multi-line log messages. The messages start with the date and time of the query in the YYYY.MM.DD HH:MM:SS format, as you can see in the following example.

2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
SEVERE: Catalina.start:
LifecycleException:  service.getName(): "Catalina";  Protocol handler start failed: java.net.BindException: Address already in use<null>:8080
       at org.apache.catalina.connector.Connector.start(Connector.java:1138)
       at org.apache.catalina.core.StandardService.start(StandardService.java:531)
       at org.apache.catalina.core.StandardServer.start(StandardServer.java:710)
       at org.apache.catalina.startup.Catalina.start(Catalina.java:583)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:288)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.commons.daemon.support.DaemonLoader.start(DaemonLoader.java:177)
2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
INFO: Server startup in 1206 ms
2010.06.09. 12:45:08 org.apache.coyote.http11.Http11Protocol pause
INFO: Pausing Coyote HTTP/1.1 on http-8080
2010.06.09. 12:45:09 org.apache.catalina.core.StandardService stop
INFO: Stopping service Catalina

To process these messages, specify a regular expression matching the timestamp of the messages in the multi-line-prefix() option. Such an expression is the following:

source s_file{ file("/var/log/tomcat6/catalina.2010-06-09.log" follow-freq(0) multi-line-prefix("[0-9]{4}\.[0-9]{2}\.[0-9]{2}\.") flags(no-parse));
};

Note that the flags(no-parse) is needed to avoid syslog-ng PE trying to interpret the date in the message.

pad-size()
Type: number (bytes)
Default: 0

Description: Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). The syslog-ng PE application will pad reads from the associated device to the number of bytes set in pad-size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes. If pad-size() was given and the incoming message does not fit into pad-size(), syslog-ng will not read anymore from this pipe and displays the following error message:

Padding was set, and couldn't read enough bytes
program-override()
Type: string
Default:

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

read-old-records()
Type: yes|no
Default: yes

Description: If set to yes, syslog-ng PE will start reading the records from the beginning of the file, if the file has not been read yet. If set to no, syslog-ng PE will read only the new records. If the source has a state in the persist file, this option will have no effect.

recursive

Type: yes or no
Default: no

Description: When enabled, syslog-ng PE monitors every subdirectory of the directory set in the path of the file parameter, and reads log messages from files with the set filename. The recursive option can be used together with wildcards in the filename.

Example 6.14. Monitoring multiple directories

The following example reads files having the .log extension from the /var/application/ directory and its subdirectories. Note that only syslog-ng PE supports recursive directory handling and wildcards in the file and pathnames.

source s_file_subdirectories { file("/var/application/*.log"
                    recursive(yes)
                    follow-freq(1)
                    log-fetch-limit(100)
                    );};

replace-null-characters()
Type: yes|no
Default: no

Description: If set to yes, syslog-ng PE replaces the '\0' characters in the file input data with spaces ' '. Available in version 6.0.8 and later.

tags()
Type: string
Default:

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

time-zone()
Type: name of the timezone, or the timezone offset
Default:

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

use-syslogng-pid()
Type: yes or no
Default: no

Description: If the value of this option is yes, then the PID value of the message will be overridden with the PID of the running syslog-ng process.



[4] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

Related Documents