Troubleshooting

• 1: Possible causes of losing log messages
• 2: Creating core files
• 3: Collecting debugging information with strace, truss, or tusc
• 4: Running a failure script
• 5: Stopping the syslog-ng process
• 6: Reporting bugs and finding help
• 7: Recover data from orphaned diskbuffer files
• 8: No local logs after specifying an unusual storage directory
• 9: No logs after specifying an unusual port number
• 10: Error messages
• 11: SELinux prevents using the execmem access on a process

1 - Possible causes of losing log messages

During the course of a message from the sending application to the final destination of the message, there are a number of locations where a message may be lost, even though AxoSyslog does its best to avoid message loss. Usually losing messages can be avoided with careful planning and proper configuration of AxoSyslog and the hosts running syslog-ng. The following list shows the possible locations where messages may be lost, and provides methods to minimize the risk of losing messages:

• Between the application and the AxoSyslog client: Make sure to use an appropriate source to receive the logs from the application (for example, from /dev/log). For example, use unix-stream instead of unix-dgram whenever possible.

• When AxoSyslog is sending messages: If AxoSyslog cannot send messages to the destination and the output buffer gets full, AxoSyslog will drop messages.

  Use flags (flow-control) to avoid this (for details, see Configuring flow-control). For more information about the error caused by the missing flow-control, see Destination queue full in Error messages.

  The number of dropped messages is displayed per destination in the log message statistics of AxoSyslog (for details, see Statistics of AxoSyslog).

• On the network: When transferring messages using the UDP protocol, messages may be lost without any notice or feedback — such is the nature of the UDP protocol. Always use the TCP protocol to transfer messages over the network whenever possible.

  For details on minimizing message loss when using UDP, see the tutorial.

• In the socket receive buffer: When transferring messages using the UDP protocol, the UDP datagram (that is, the message) that reaches the receiving host placed in a memory area called the socket receive buffer. If the host receives more messages than it can process, this area overflows, and the kernel drops messages without letting AxoSyslog know about it. Using TCP instead of UDP prevents this issue. If you must use the UDP protocol, increase the size of the receive buffer using the so-rcvbuf() option.

• When AxoSyslog is receiving messages:

  • The receiving AxoSyslog (for example, the AxoSyslog server or relay) may drop messages if the fifo of the destination file gets full. The number of dropped messages is displayed per destination in the log message statistics of AxoSyslog (for details, see Statistics of AxoSyslog).

• When the destination cannot handle large load: When AxoSyslog is sending messages at a high rate into an SQL database, a file, or another destination, it is possible that the destination cannot handle the load, and processes the messages slowly. As a result, the buffers of AxoSyslog fill up, AxoSyslog cannot process the incoming messages, and starts to loose messages. For details, see the previous entry. Use the throttle parameter to avoid this problem.

• As a result of an unclean shutdown of the AxoSyslog server: If the host running the AxoSyslog server experiences an unclean shutdown, it takes time until the clients realize that the connection to the AxoSyslog server is down. Messages that are put into the output TCP buffer of the clients during this period are not sent to the server.

• When AxoSyslog is writing messages into files: If AxoSyslog receives a signal (SIG) while writing log messages to file, the log message that is processed by the write call can be lost if the flush_lines parameter is higher than 1.

2 - Creating core files

Purpose:

When syslog-ng crashes for some reason, it can create a core file that contains important troubleshooting information. To enable core files, complete the following procedure:

Steps:

1. Core files are produced only if the maximum core file size ulimit is set to a high value in the init script of syslog-ng. Add the following line to the init script of syslog-ng:

       ulimit -c unlimited
   

2. Verify that syslog-ng has permissions to write the directory it is started from, for example, /opt/syslog-ng/sbin/.

3. If syslog-ng crashes, it will create a core file in the directory syslog-ng was started from.

4. To test that syslog-ng can create a core file, you can create a crash manually. For this, determine the PID of syslog-ng (for example, using the ps -All|grep syslog-ng command), then issue the following command: kill -ABRT <syslog-ng pid>

   This should create a core file in the current working directory.

3 - Collecting debugging information with strace, truss, or tusc

To properly troubleshoot certain situations, it can be useful to trace which system calls AxoSyslog performs. How this is performed depends on the platform running AxoSyslog. In general, note the following points:

• When AxoSyslog is started, a supervisor process might stay in the foreground, while the actual syslog-ng daemon goes to the background. Always trace the background process.

• Apart from the system calls, the time between two system calls can be important as well. Make sure that your tracing tool records the time information as well. For details on how to do that, refer to the manual page of your specific tool (for example, strace on Linux, or truss on Solaris and BSD).

• Run your tracing tool in verbose mode, and if possible, set it to print long output strings, so the messages are not truncated.

• When using strace, also record the output of lsof to see which files are accessed.

The following are examples for tracing system calls of syslog-ng on some platforms. The output is saved into the /tmp/syslog-ng-trace.txt file, sufficed with the PID of the related syslog-ng process. The path of the syslog-ng binary may be different for your installation, as distribution-specific packages may use different paths.

• Linux: strace -o /tmp/trace.txt -s256 -ff -ttT /opt/syslog-ng/sbin/syslog-ng -f /opt/syslog-ng/etc/syslog-ng.conf -Fdv

• HP-UX: tusc -f -o /tmp/syslog-ng-trace.txt -T /opt/syslog-ng/sbin/syslog-ng

• IBM AIX and Solaris: truss -f -o /tmp/syslog-ng-trace.txt -r all -w all -u libc:: /opt/syslog-ng/sbin/syslog-ng -d -d -d

4 - Running a failure script

Purpose:

You can create a failure script that is executed when AxoSyslog terminates abnormally, that is, when it exits with a non-zero exit code. For example, you can use this script to send an automatic email notification.

Prerequisites:

The failure script must be the following file: /opt/syslog-ng/sbin/syslog-ng-failure, and must be executable.

To create a sample failure script, complete the following steps.

Steps:

1. Create a file named /opt/syslog-ng/sbin/syslog-ng-failure with the following content:

       #!/usr/bin/env bash
       cat >>/tmp/test.txt <<EOF
       $(date)
       Name............$1
       Chroot dir......$2
       Pid file dir....$3
       Pid file........$4
       Cwd.............$5
       Caps............$6
       Reason..........$7
       Argbuf..........$8
       Restarting......$9
   
       EOF
   

2. Make the file executable: chmod +x /opt/syslog-ng/sbin/syslog-ng-failure

3. Run the following command in the /opt/syslog-ng/sbin directory: ./syslog-ng --process-mode=safe-background; sleep 0.5; ps aux | grep './syslog-ng' | grep -v grep | awk '{print $2}' | xargs kill -KILL; sleep 0.5; cat /tmp/test.txt

   The command starts AxoSyslog in safe-background mode (which is needed to use the failure script) and then kills it. You should see that the relevant information is written into the /tmp/test.txt file, for example:

       Thu May 18 12:08:58 UTC 2017
       Name............syslog-ng
       Chroot dir......NULL
       Pid file dir....NULL
       Pid file........NULL
       Cwd.............NULL
       Caps............NULL
       Reason..........signalled
       Argbuf..........9
       Restarting......not-restarting
   

4. You should also see messages similar to the following in system syslog. The exact message depends on the signal (or the reason why AxoSyslog stopped):

       May 18 13:56:09 myhost supervise/syslog-ng[10820]: Daemon exited gracefully, not restarting; exitcode='0'
       May 18 13:57:01 myhost supervise/syslog-ng[10996]: Daemon exited due to a deadlock/signal/failure, restarting; exitcode='131'
       May 18 13:57:37 myhost supervise/syslog-ng[11480]: Daemon was killed, not restarting; exitcode='9'
   

   The failure script should run on every non-zero exit event.

5 - Stopping the syslog-ng process

To avoid problems, always use the init scripts to stop syslog-ng (/etc/init.d/syslog-ng stop), instead of using the kill command. This is especially true on Solaris and HP-UX systems, here use /etc/init.d/syslog stop.

6 - Reporting bugs and finding help

If you need help, want to open a support ticket, or report a bug, we recommend using the syslog-ng-debun tool to collect information about your environment and AxoSyslog version. For details, see the The syslog-debun manual page. For support contacts, see Getting support.

7 - Recover data from orphaned diskbuffer files

When you change the configuration of a AxoSyslog host that uses disk-based buffering (also called disk queue), AxoSyslog may start new disk buffer files for the destinations that you have changed. In this case, AxoSyslog abandons the old disk queue files. If there were unsent log messages in the disk queue files, these messages remain in the disk queue files, and will not be sent to the destinations.

8 - No local logs after specifying an unusual storage directory

Security-Enhanced Linux (SELinux) is a set of kernel and user-space tools enforcing strict access control policies. SELinux rules in Linux distributions cover all aspects of the configuration coming in the syslog-ng package available in the distribution. But as soon as an unusual port number or directory name is specified in the configuration, syslog-ng fails to work even with a completely legitimate configuration.

When you choose to save logs of a central AxoSyslog server to a directory other than the /var/log directory, logs will not start appearing on the newly configured directory. For details on how to fix this issue, see section “Using a different storage directory” in the blog post titled Using syslog-ng with SELinux in enforcing mode.

9 - No logs after specifying an unusual port number

Security-Enhanced Linux (SELinux) is a set of kernel and user-space tools enforcing strict access control policies. SELinux rules in Linux distributions cover all aspects of the configuration coming in the syslog-ng package available in the distribution. But as soon as an unusual port number or directory name is specified in the configuration, syslog-ng fails to work even with a completely legitimate configuration.

By default, SELinux only allows connections to the default syslog ports. When you have to use any other port for some reason, sending logs to that port will not work. For details on how to fix this issue, see section “Using a different port” in the blog post titled Using syslog-ng with SELinux in enforcing mode.

10 - Error messages

This section describes the most common error messages.

Destination queue full

Alert unknown CA

PEM routines:PEM_read_bio:no start line

11 - SELinux prevents using the execmem access on a process

If you are using a recent enough PCRE library, AxoSyslog will automatically use the JIT of the regexp engine, which will result in a similar error:

   setroubleshoot [21631 ] : SELinux is preventing <syslog-ng path> from using the execmem access on a process. (...)
    
    python [21631 ] : SELinux is preventing <syslog-ng path> from using the execmem access on a process.

To resolve this issue, switch off the PCRE JIT compile function by using the disable-jit flags() option in the given filter or rewrite rule of your configuration.