Chat now with support
Chat with Support

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

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.

syslog-windebun.ps1

Name

syslog-windebun.ps1 — syslog-ng WINdows DEBUg buNdle generator PowerShell script

Synopsis

powershell C:\PATH\TO\syslog-debun.ps1

Description

The syslog-windebun application is a powershell script that collects information about its environment into a file, to help troubleshoot syslog-ng Premium Edition and syslog-ng Agent for Windows installations.

The syslog-windebun application application is distributed with the syslog-ng PE system logging application, and is usually part of the syslog-ng Premium Edition package or the syslog-ng Agent for Windows package. The latest version of the is available at the syslog-ng Downloads page. You can also contact the One Identity Support Team and request the latest version of the script.

Using syslog-windebun

The application requires PowerShell 2.0 or later. Administrator privileges are not required.

To use syslog-windebun, run the application in an interactive powershell terminal. On 64-bit Windows, use the 64-bit PowerShell terminal.

Example:

powershell -NoProfile -ExecutionPolicy RemoteSigned C:\PATH\TO\syslog-debun.ps1

The script collects the information about the syslog-ng PE environment into a file, and displays the location of this file. When creating a support ticket, attach this file to the ticket to help our support team troubleshoot your problem. The following is an example output.

PS C:\Users\balabit> C:\Users\balabit\Downloads\syslog-windebun.ps1
syslog-ng Agent is installed
Start gathering Agent related information
Finished gathering syslog-ng Agent information
syslog-ng PE is installed
Start gathering syslog-ng PE related information
Finished gathering syslog-ng PE related information
Starting to gather system related information
Finished gathering system related information.

The resulted zip file is found where you started running the program.

Please send the following file to Balabit Support:
C:\Users\balabit\syslog-windebun-CjZ.zip

Data collection policy

The syslog-windebun application collects the following information into a file.

  • Routing information

  • System information

  • Network statistics

  • Network port information

  • IP configuration

  • The XML configuration file of syslog-ng Agent for Windows

  • Registry information of syslog-ng Agent for Windows

  • The content of the etc folder of syslog-ng Premium Edition

  • PowerShell and .NET version

  • syslog-ng Premium Edition and syslog-ng Agent for Windows version

  • Installation logs of syslog-ng Premium Edition and syslog-ng Agent for Windows version

Files

/opt/syslog-ng/bin/dqtool

Author

This manual page was written by the One Identity Documentation Team <documentation@balabit.com>.

Copyright

Copyright© 2000-2018One Identity. Published under the Creative Commons Attribution-Noncommercial-No Derivative Works (by-nc-nd) 3.0 license. For details, see https://creativecommons.org//. The latest version is always available at the syslog-ng Documentation page.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating