Chat now with support
Chat with Support

syslog-ng Premium Edition 6.0.21 - Administrator Guide for syslog-ng Agent for Windows

Debugging syslog-ng Agent

To enable debug options, create the debug.ini file in the syslog-ng Agent install directory.

Example 10.1. Content of the debug.ini file

The debug.ini can consist of the following entries:

[AgentDbgLog]
enabled=on/off
path=<debug_file_folder_path>[GpoDbgLog]
enabled=on/off
path=<debug_file_folder_path>[WriteMiniDump]
enabled=on/off

 NOTE:

The debug.ini file cannot be distributed. It can only be used on a local machine.

Procedure 10.1. Creating core and memory dumps

Purpose: 

The BalaBit support team might request you to send them core dumps of the syslog-ng Agent to investigate a particular problem. When enabled, the syslog-ng Agent for Windows application creates core dumps automatically when it experiences an unexpected shutdown.

Steps: 

  1. To enable core dumps, enter the following lines in the debug.ini file:

    [WriteMiniDump]
enabled=on

    Core dumps are written into the installation folder of the syslog-ng Agent under the syslog-ng-agent.PID.dmp filename. The size of a core file is typically about 40-50 MB.

    		 NOTE:

    By default, this option is enabled. Due to disk space limits you can disable it to prevent hard disk becomes full.

  2. To apply the changes, restart the syslog-ng Agent after modifying the [WriteMiniDump] part of the debug.ini file.

Procedure 10.2. Enabling debug logging in syslog-ng Agent

Purpose: 

In case you experience problems with The syslog-ng Agent the BalaBit support team might request you to create debug logs for the application to help troubleshoot the problem. Complete the following steps.

 NOTE:

The debug log is not suited to detect the reasons behind why a syslog-ng service could not start. The only way to check a non-starting agent service is to run it manually in debug mode (use the command syslog-ng-agent.exe /D). Make sure that if the [AgentDbgLog] part of the debug.ini file exists, it is set to enabled=off.

Steps: 

  1. To enable logging debug logs, enter the following lines in the debug.ini file:

    [AgentDbgLog]
enabled=on

    Debug messages are written into the installation folder of the syslog-ng Agent under the syslog_ng_agent_dbg.log filename by default, if no other path is specified. To change the destination folder of the debug log file, enter a path in the path=<debug_file_folder_path> row.

    		 Caution:

    When using an optional path, make sure that syslog-ng Agent has the right to write it. Also, make sure that the path exists. Otherwise, syslog-ng Agent will not write into the file.

  2. To apply the changes, restart the syslog-ng Agent after modifying the [AgentDbgLog] part of the debug.ini file.

    After the restart, a log message is automatically generated about the start of debug logging mode, with a timestamp and the path of the log file.

    Example 10.2. Debug logging enabled log message 

    Apr 16 13:14:02 zts-win015 syslog-ng[252]: syslog-ng Agent debug mode is enabled; output file='.\syslog_ng_agent_dbg.log'

  3. Reproduce the error. It will be included in the debug log.

  4. After solving the problem, disable debug logging, otherwise the log file will grow and might consume the available hard disk space. The log file contains the log messages received and processed by the syslog-ng Agent as well.

Procedure 10.3. Troubleshooting domain setting problems

Purpose: 

If the domain settings are not downloaded to a domain host, the syslog-ng Agent (starting from version 3.0.6) can create a log file to debug why the domain settings are not updated on the client. Complete the following steps:

Steps: 

  1. To enable logging domain update errors, enter the following lines in the debug.ini file:

    [GpoDbgLog]
enabled=on

    Debug messages are written into the installation folder of the syslog-ng Agent under the syslog_ng_agent_gpo_dbg.log filename by default, if no other path is specified. To change the destination folder of the debug log file, enter a path in the path=<debug_file_folder_path> row.

    		 Caution:

    When using an optional path, make sure that syslog-ng Agent has the right to write it. Also, make sure that the path exists. Otherwise, syslog-ng Agent will not write into the file.

  2. Select Start > Run > gpupdate to reproduce the error.

  3. After solving the problem, disable logging domain update errors, otherwise the log file will grow every time when the domain settings of the client are updated.

Reading eventlog messages is slow on Windows Vista or newer

To read the messages from eventlog containers, the syslog-ng Agent for Windows application uses the native Windows API tools. The Windows platforms use an XML-based eventlog format. The API (called EVTX) that reads the XML-messages from the eventlog container and passes them to syslog-ng Agent is inherently slow, severely limiting the performance of syslog-ng Agent.

The API tools that syslog-ng Agent 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.

Limitations of using the EVT API

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.

Procedure 10.4. Enabling the EVT API

Purpose: 

To use the older, but faster EVT API to handle the eventlog containers (instead of the native EVTX API), complete the following steps.

Warnings: 

  • Hazard of data loss! If you change the API, the position of the last read message can be lost, causing the syslog-ng Agent application to duplicate or lose messages.

  • The EVT API is not fully compatible with the EVTX API. Make sure to read the section called “Limitations of using the EVT API” before changing your configuration.

  • Changing the API affects every eventlog container on the host. It is not possible to use the EVT API only for selected containers.

Steps: 

  1. Start the configuration interface of the syslog-ng Agent for Windows application.

  2. Select syslog-ng Agent Settings > Eventlog Sources > Eventlog Properties.

  3. Select Enable.

  4. Select Event API > Event Logging (EVT).

    		 NOTE:

    By default, the syslog-ng Agent for Windows application uses the native API on every platform: EVT on Windows XP and Server 2003, and EVTX on Windows.

  5. Select Apply, then OK. To activate the changes, restart the syslog-ng Agent service.

    Expected result: 

    The syslog-ng Agent for Windows application uses the EVT API to read messages from the eventlog containers, improving the performance.

Debug bundle on Windows

To create a debug bundle that you can attach to your support ticket, use the syslog-windebun application. For details, see syslog-windebun.ps1.

Chapter 11. Configuring the auditing policy on Windows

This section describes how to configure the logging and auditing policy on various versions of Microsoft Windows. The syslog-ng Agent can transfer log messages only about those events that are actually logged, so the audit policy has to be configured to log the important events.

Microsoft Windows operating systems can record a range of event types, from a system-wide event such as a user logging on, to an attempt by a particular user to read a specific file. Both successful and unsuccessful attempts to perform an action can be recorded. The audit policy specifies the types of events to be audited. When such an event occurs, an entry is added to the log file of the computer.

Following is a brief overview on how to configure the audit policy on various versions of Microsoft Windows. For details, consult the documentation of your operating system, or visit Microsoft TechNet. For details on configuring the auditing and logging of various applications, like the IIS Server or the ISA Server, consult your product documentation.

Procedure 11.1. Turning on security logging on Windows XP

Purpose: 

The following procedure describes how to enable security logging on Windows XP Professional hosts.

Steps: 

  1. Login as an administrator.

  2. Click Start, click Run, and type mmc /a.

  3. On the File menu, click Add/Remove Snap-in, and click Add.

  4. Under Snap-in, click Group Policy, and click Add.

  5. In Select Group Policy Object, select Local Computer, then click Finish, click Close, and click OK.

  6. In Console Root, select Local Computer Policy, then click Audit Policy.

  7. Right-click the attribute or event you want to audit on the details pane.

  8. Set the desired options in the Properties.

  9. Repeat Steps 7-8 for every other event you want to audit.

    		 NOTE:

    For details on how to remotely enable security logging for workstations, member servers, and domain controllers, see Procedure 11.2, “Turning on security logging for domain controllers”.

Procedure 11.2. Turning on security logging for domain controllers

Purpose: 

The following procedure describes how to enable security logging on a Windows XP Professional domain controller.

Steps: 

  1. Login as an administrator.

  2. Click Start, point to Programs, point to Administrative Tools, and click Active Directory Users and Computers.

  3. In the console tree, click Domain Controllers.

  4. Click Action, then click Properties.

  5. On the Group Policy tab, select the policy you want to change, and click Edit.

  6. In the Group Policy window, in the console tree, click Audit Policy.

  7. Right-click the attribute or event you want to audit on the details pane.

  8. Set the desired options in the Properties.

  9. Repeat Steps 7-8 for every other event you want to audit.

Procedure 11.3. Turning on auditing on Windows 2003 Server

Purpose: 

The following procedure describes how to configure auditing on a Windows 2003 Server host.

Steps: 

  1. Login as an administrator.

  2. Click Start, point to Programs, point to Administrative Tools, and click Domain Security Policy.

  3. In the console tree, click Local Policies, then Audit Policy.

  4. Double-click on an event and select the Define these policy settings option.

  5. Select the type of event to log: Success or Failure.

  6. Repeat Steps 4-5 for every other event you want to audit.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating