syslog-ng Premium Edition 7.0.24 - Administration Guide

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.

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.

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).

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);
};

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.

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 Transfer 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. Reliable disk queues employ an in-memory cache buffer, the content of which is also written to the disk, and which is intended to speed up the process of reading back data from the queue.

Normal disk queues work in a different way: they employ an in-memory output buffer (set in qout-size()) and an in-memory overflow queue (set in mem-buf-length()). The disk-buffer file itself is only used if the in-memory output buffer (set in qout-size()) is filled up completely. This approach has better performance (because of less disk IO operations), but also carries the risk of losing a maximum of qout-size() plus mem-buf-length() number of messages in case of an unexpected power failure or application crash.

Size and truncation of 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. Truncation only occurs if the read and write heads of the queue reach the same position. Given that new messages arrive all the time, at least a small number of messages will almost always be stored in the queue file at all times. As a result, the queue file is not truncated automatically, but grows until it reaches the maximal configured size, after which the write head will wrap around, later followed by the read head.

In case of normal disk queue files, growth in size is not so apparent, as the disk-based queue file is only used if the in-memory overflow buffer fills up. Once the destination sends messages faster than the incoming message rate, the queue will start to empty, and when the read and write heads of the queue reach the same position, the queue files are finally truncated.

Note that 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.