Chat now with support
Chat with Support

syslog-ng Premium Edition 7.0.33 - Administration Guide

Preface Introduction to syslog-ng The concepts of syslog-ng Installing syslog-ng PE The syslog-ng PE quick-start guide The syslog-ng PE configuration file Collecting log messages — sources and source drivers
How sources work default-network-drivers: Receive and parse common syslog messages internal: Collecting internal messages file: Collecting messages from text files google-pubsub: collecting messages from the Google Pub/Sub messaging service wildcard-file: Collecting messages from multiple text files linux-audit: Collecting messages from Linux audit logs mssql, oracle, sql: collecting messages from an SQL database network: Collecting messages using the RFC3164 protocol (network() driver) office365: Fetching logs from Office 365 osquery: Collect and parse osquery result logs pipe: Collecting messages from named pipes program: Receiving messages from external applications python: writing server-style Python sources python-fetcher: writing fetcher-style Python sources snmptrap: Read Net-SNMP traps 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 udp-balancer: Receiving UDP messages at very high rate unix-stream, unix-dgram: Collecting messages from UNIX domain sockets windowsevent: Collecting Windows event logs
Sending and storing log messages — destinations and destination drivers
elasticsearch2>: Sending messages directly to Elasticsearch version 2.0 or higher (DEPRECATED) elasticsearch-http: Sending messages to Elasticsearch HTTP Event Collector file: Storing messages in plain-text files google_pubsub(): Sending logs to the Google Cloud Pub/Sub messaging service google_pubsub-managedaccount(): Sending logs to the Google Cloud Pub/Sub messaging service authenticated by Google Cloud managed service account hdfs: Storing messages on the Hadoop Distributed File System (HDFS) http: Posting messages over HTTP kafka(): Publishing messages to Apache Kafka (Java implementation) (DEPRECATED) kafka-c(): Publishing messages to Apache Kafka using the librdkafka client (C implementation) logstore: Storing messages in encrypted files mongodb: Storing messages in a MongoDB database network: Sending messages to a remote log server using the RFC3164 protocol (network() driver) pipe: Sending messages to named pipes program: Sending messages to external applications python: writing custom Python destinations sentinel(): Sending logs to the Microsoft Azure Sentinel cloud snmp: Sending SNMP traps smtp: Generating SMTP messages (email) from logs splunk-hec: Sending messages to Splunk HTTP Event Collector sql(): Storing messages in an SQL database stackdriver: Sending logs to the Google Stackdriver cloud syslog: Sending messages to a remote logserver using the IETF-syslog protocol syslog-ng(): Forward logs 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) unix-stream, unix-dgram: Sending messages to UNIX domain sockets usertty: Sending messages to a user terminal — usertty() destination Client-side failover
Routing messages: log paths, flags, and filters Global options of syslog-ng PE TLS-encrypted message transfer Advanced Log Transport Protocol Reliability and minimizing the loss of log messages Manipulating messages parser: Parse and segment structured messages Processing message content with a pattern database Correlating log messages Enriching log messages with external data Monitoring statistics and metrics of syslog-ng Multithreading and scaling in syslog-ng PE Troubleshooting syslog-ng Best practices and examples The syslog-ng manual pages Glossary

How to process messages from an orphan disk-buffer file using a separate syslog-ng PE instance

This section describes how to read messages from an orphan disk-buffer file by using a separate syslog-ng Premium Edition (syslog-ng PE) process running parallel to the already running syslog-ng PE instance.

Orphan disk-buffer files

In certain situations (for example, after modifying the disk-buffer configuration or losing the persist information), syslog-ng PE creates a new disk-buffer file instead of using the already existing one. In these situations, the already existing disk-buffer file becomes a so-called orphan disk-buffer file.

NOTE: The syslog-ng PE application does not store messages in orphan disk-buffer files or forward the messages stored in the disk-buffer file.

Processing the messages from an orphan disk-buffer file by using a separate syslog-ng PE instance

When syslog-ng PE creates orphan disk-buffer files, you can start a separate syslog-ng PE instance parallel to the syslog-ng PE instance already running, and use the following resolution process to process the messages in the orphan disk-buffer file.

Caution:

Before starting a separate syslog-ng PE instance to process the messages from the orphan disk-buffer file, consider the following:

  • During the resolution process, a separate syslog-ng PE instance will be started with its temporary files beside the syslog-ng PE instance already running.
  • An incorrect startup command and incorrect configurations may cause issues for the syslog-ng PE instance already running.
  • The disk-buffer file stores processed log messages in the format in which they would have been sent out to the destination.
  • The disk-buffer file doesn't store information about the destination.

To process the messages from an orphan disk-buffer file using a separate syslog-ng PE instance,

  1. Identify the orphan disk-buffer files and make a record of them. For more information, see How to get information about disk-buffer files.

    It is important to know the type of the disk-buffer file. Disk-buffer file types can be normal (.qf) or reliable (.rqf).

    In the examples during this process, the /opt/syslog-ng/var/syslog-ng-00005.rqf orphan reliable disk-buffer file is used.

  2. Determine the destination of the logs. The content of the disk-buffer may help you determine the logs' destination. For more information, see How to get information about disk-buffer files.

    In the examples during this process, the destination 10.21.10.20 is used with the standard network() port 514.

  3. Create a directory for the temporary instance. In the examples during this process, the /tmp/qdisk directory is used.

    mkdir /tmp/qdisk

    Caution:

    Make sure that there is sufficient disk space in the directory. The minimum recommended disk space in the directory is equal to the size of the orphan disk-buffer file.

    If you want to use a different temporary directory (that is, other than /tmp/qdisk), create a symbolic link between /tmp/qdisk and the temporary directory you want to use with ln -s /path/to/tempdir /tmp/qdisk. This will allow you to use the commands in this resolution process.

    If you will not use a different temporary directory, use the /tmp/qdisk temporary directory in the example commands and file names.

  4. Create the configuration file /tmp/qdisk/qdisk.conf for the temporary instance with the following content.

    Example: creating the /tmp/qdisk/qdisk.conf configuration file for the temporary instance
    @version:7.0
    @include "scl.conf"
    
    options {
      keep-hostname(yes);
      keep-timestamp(yes);
    };
    
    destination d_destination {
    #    ADD YOUR DESTINATION HERE
    
    };
    
    log {
      destination(d_destination);
    };
  5. Add your destination statement with disk-buffer() to the configuration file. You can copy the destination statement from your running syslog-ng PE configuration.

    Caution:

    Add the dir() option and set the disk-buffer file's destination directory to the temporary directory (that is, /tmp/qdisk) in your destination statement.

    Example: adding the destination statement with disk-buffer() to the configuration file
    network("10.21.10.20"
        disk-buffer(
            disk-buf-size(1048576)
            reliable(yes)
            dir(/tmp/qdisk/)
    );
  6. Start the temporary syslog-ng PE instance in the foreground.

    syslog-ng -Fe -f /tmp/qdisk/qdisk.conf -R /tmp/qdisk/qdisk.persist -c /tmp/qdisk/qdisk.ctl

    The syslog-ng PE application will log to the console, so you will see any potential error that may occur during startup.

    The following example output displays that an empty disk-buffer file has been created and the connection to the remote destination has been established.

    Example: output displaying newly created empty disk-buffer file and connection established to remote destination
    Follow-mode file source not found, deferring open; filename='/no_such_file_or.dir'
    Reliable disk-buffer state saved; filename='/tmp/qdisk/syslog-ng-00000.rqf', qdisk_length='0'
    No server license found, running in client mode;
    syslog-ng starting up; version='7.0.20', cfg-fingerprint='eaa03b9efb88b87d7c1b0ce7efd042ed8ac0c013', cfg-nonce-ndx='0', cfg-signature='c0327a7f7e6418ce0399a75089377dfb662bb072'
    FIPS information; FIPS-mode='disabled'
    Syslog connection established; fd='7', server='AF_INET(10.21.10.20:514)', local='AF_INET(0.0.0.0:0)'
  7. To stop syslog-ng PE, press CTRL+C.

  8. Overwrite the empty disk-buffer file with the orphan disk-buffer file.

    mv /opt/syslog-ng/var/syslog-ng-00005.rqf /tmp/qdisk/syslog-ng-00000.rqf
  9. Start syslog-ng PE using the command used in Start the temporary syslog-ng PE instance in the foreground step.

    syslog-ng -Fe -f /tmp/qdisk/qdisk.conf -R /tmp/qdisk/qdisk.persist -c /tmp/qdisk/qdisk.ctl
  10. Open another terminal and check the progress by using one of the following methods.

    • Checking the number of stored logs in the disk-buffer (that is, the last number from the output).

      /opt/syslog-ng/sbin/syslog-ng-ctl stats -c /tmp/qdisk/qdisk.ctl | grep 'dst.*queued'
    • Checking the status of the disk-buffer file.

      /opt/syslog-ng/bin/dqtool info /tmp/qdisk/syslog-ng-00000.rqf

      An empty disk-buffer file will look similar to this:

      Example: empty disk-buffer file status message

      When checking the status of the disk-buffer files, the terminal will display a similar status message for an empty disk-buffer file:

      Reliable disk-buffer state loaded; filename='/tmp/qdisk/syslog-ng-00000.rqf', queue_length='0', size='0'
  11. Press CTRL+C to stop syslog-ng PE.

  12. Check the state of the orphan disk-buffer file. For more information, see How to get information about disk-buffer files.

  13. If you have more than one orphan disk-buffer file, repeat the steps following the syslog-ng PE stop (that is, the steps beginning from overwriting the empty disk-buffer file with the orphan disk-buffer file) for each orphan disk-buffer file.

  14. Remove the temporary directory.

    Example: command for removing the temporary directory

    The following command removes the /mp/qdisk temporary directory:

    rm -rf /tmp/qdisk

How to empty disk-buffer files

This section describes how to empty disk-buffer files used in syslog-ng Premium Edition (syslog-ng PE).

Caution:

Hazard of data loss!

You must stop log reception to be able to empty a disk-buffer. If you fail to stop log reception before emptying a disk-buffer, your newly received log messages may get stored in the disk-buffer, overwriting your previous log messages. To avoid log loss, One Identity recommends that you redirect your logs to a different syslog server when emptying your disk-buffer files.

NOTE: Consider the following while reading this section:

This section uses a simple example configuration with one source and one destination with disk-buffer.

If you are not aware of disk-buffers or you're not sure which of your destinations use disk-buffer, One Identity recommends that you do not proceed with the procedure of emptying your disk-buffer files. Instead, One Identity recommends that you contact our Support Team and open a service request. When opening the service request, describe your issue and attach a collected debug bundle from your system.

For more information about collecting a debug bundle for Microsoft Windows, see How to create a syslog-ng debug bundle archive on Windows operating system.

For more information about collecting a debug bundle for Linux or Unix OS, see How to create a syslog-ng debug bundle on Linux Or Unix operating system.

Recommendation

One Identity recommends that you empty your disk-buffer files before you begin the following:

  • Upgrading syslog-ng Premium Edition (syslog-ng PE) from version 6 to 7.

  • Changing the configuration of a remote destination with disk-buffer.

  • Applying a solution that includes the removal of the syslog-ng PE persistent file.

Example configuration for emptying disk-buffer files

The syslog-ng PE application uses the following example configuration to describe how to empty disk-buffer files:

source s_net { 
    network(); 
};
destination d_logserver { 
    network("10.21.10.20" port(514) disk-buffer( disk-buf-size(2000000) ) );
};
log { 
    source(s_net);
    destination(d_logserver);
};

To empty disk-buffer files,

  1. Name the disk-buffer file to empty and the destination statement using it.

    If you are not sure about which disk-buffer file to empty, or the destination statement using the disk-buffer file in question, you can use one of the following methods:

    • Check the list and the status of the disk-buffer files.

      Examples
      • Non-empty disk-buffer file

        Disk-buffer state loaded; filename='/opt/syslog-ng/var/syslog-ng-00000.qf', qout_length='0', qbacklog_length='0', qoverflow_length='0', qdisk_length='3006'
      • IP:PORT information of the destination with the disk-buffer in use

        afsocket_dd_qfile(stream,10.21.10.20:514) = { "queue_file": "/opt/syslog-ng/var/syslog-ng-00000.qf" }

      For more information about getting information about disk-buffer files, see Information about disk-buffer files.

    • Find the destination statement in the syslog-ng PE configuration using the IP:PORT information.

      destination d_logserver { network("10.21.10.20" port(514) disk-buffer( disk-buf-size(2000000) ) ); };
  2. Locate the log statements that use the destination statement you named previously.

  3. Disable the sources in the log statements.

    Add '#' at the beginning of all source() entries in the log paths.

    log { 
    #source(s_net);
     destination(d_logserver);
    }
  4. Reload syslog-ng PE by entering the /opt/syslog-ng/sbin/syslog-ng-ctl reload command.

  5. Check the disk-buffer file status.

    For more information, see Getting the status information of disk-buffer files.

  6. To enable the sources again, remove '#' from the log paths and reload syslog-ng PE.

Enabling memory buffering

To enable memory buffering, use the log-fifo-size() parameter in the destination. All destination drivers can use memory buffering. Use memory buffering if you want to send logs to destinations where the disk-buffer option is not available, if you want the fastest solution, and if syslog-ng PE crash or network downtime is never expected. In these cases, losing logs is possible. This solution does not use the disk-buffer option. Instead, logs are stored only in the memory.

Example: Example for using memory buffering
destination d_BSD {
    network(
            "127.0.0.1"
            port(3333)
            log-fifo-size(10000)
        );
};

About disk queue files

Normal and reliable queue files

The key difference between disk queue files that employ the reliable(yes) option and not is the strategy they employ. Reliable disk queues guarantee that all the messages passing through them are written to disk first, and removed from the queue only after the destination has confirmed that the message has been successfully received. This prevents message loss, for example, due to syslog-ng PE crashes if the client and the destination server communicate using the Advanced Log Transport Protocol (ALTP). Note that the Reliable Log Transfer Protocol is available only in syslog-ng Premium Edition version 6 LTS. Of course, using the reliable(yes) option introduces a significant performance penalty as well.

Both reliable and normal disk-buffers employ an in-memory output queue (set in quot-size()) and an in-memory overflow queue (set in mem-buf-size() for reliable disk-buffers, or mem-buf-length() for normal disk-buffers). The difference between reliable and normal disk-buffers is that when the reliable disk-buffer uses one of its in-memory queues, it also stores the message on the disk, whereas the normal disk-buffer stores the message only in memory. The normal disk-buffer only uses the disk if the in-memory output buffer is filled up completely. This approach has better performance (due to fewer disk I/O operations), but also carries the risk of losing a maximum of quot-size() plus mem-buf-length() number of messages in case of an unexpected power failure or application crash.

Size of the queue files

Disk queue files tend to grow. Each may take up to disk-buf-size() bytes on the disk. Due to the nature of reliable queue files, all the messages traversing the queue are written to disk, constantly increasing the size of the queue file.

The disk-buffer file's size should be considered as the configured disk-buf-size() at any point of time, even if it does not have messages in it. Truncating the disk-buffer file can slow down disk I/O operations, so syslog-ng PE does not always truncate the file when it would be possible (see the truncate-size-ratio() option). If a large disk-buffer file is not desirable, you should set the disk-buf-size() option to a smaller value.

Caution:

One Identity recommends that you do not build upon the current truncating logic of the disk-buffer files, because syslog-ng PE might pre-allocate the disk-buffer files and never truncate them in the future.

NOTE: The disk-buffer file's size does not strictly correlate to the number of stored messages. If you want to get information about the disk-buffer, use dqtool (for more information, see Getting the status information of disk-buffer files).

NOTE: If a queue file becomes corrupt, syslog-ng PE starts a new one. This might lead to the queue files consuming more space in total than their maximal configured size and the number of configured queue files multiplied together.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating