Chat now with support
Chat with Support

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

Macros available in the syslog-ng Agent

The following sections list the available macros:

Caution:

These macros are available only in the syslog-ng Agent for Windows. To recognize Windows-specific elements of the log message (for example eventlog-related macros) on the syslog-ng server, you have to use parsers on the syslog-ng server. The parser must be configured to match the message format set in the syslog-ng Agent.

NOTE:

Note that if you use the Syslog protocol template (meaning that messages are sent using the IETF-syslog protocol), only the message part of the log message can be customized, the structure of the headers and other information is fixed by the protocol.

Protocol-related macros of the syslog-ng Agent

APP_NAME

Description: An alias for the APPLICATION_NAME macro.

APPLICATION_NAME

Description:

  • At event container: Name of the application the message came from

  • At file as the name of creator (default value): syslog-ng-agent

HOST

Description: Name of the host sending the message. Hostnames are automatically converted to lowercase.

MESSAGE

Description: The content of the message, including the text of the message and any file- or event-specific macros that are set for the source.

MSG

Description: An alias for the MESSAGE macro.

MSGHDR

Description: The name and the PID of the program that sent the log message in PROGRAM[PID]: format. Includes a trailing whitespace. Note that the macro returns an empty value if both the PROGRAM and PID fields of the message are empty.

PRI

Description: Priority header of the message, storing the facility and the level of the message.

PROCESS_ID

Description: PID of the application the message came from.

Time-related macros of the syslog-ng Agent

BSDDATE, R_BSDDATE, S_BSDDATE

Description: Date of the message in BSD timestamp format (month/day/hour/minute/second, each expressed in two digits). This is the original syslog time stamp without year information, for example Jun 13 15:58:00. If possible, it is recommended to use ISODATE for timestamping.

DATE, R_DATE, S_DATE

Description: Date of the message using the BSD-syslog style timestamp format (month/day/hour/minute/second, each expressed in two digits). This is the original syslog time stamp without year information, for example: Jun 13 15:58:00.

DAY, R_DAY, S_DAY

Description: The day the message was sent.

FULLDATE, R_FULLDATE, S_FULLDATE

Description: A nonstandard format for the date of the message using the same format as ${DATE}, but including the year as well, for example: 2006 Jun 13 15:58:00.

HOUR, R_HOUR, S_HOUR

Description: The hour of day the message was sent.

ISODATE, R_ISODATE, S_ISODATE

Description: Date of the message in the ISO 8601 compatible standard timestamp format (yyyy-mm-ddThh:mm:ss+-ZONE), for example: 2006-06-13T15:58:00.123+01:00. If possible, it is recommended to use ISODATE for timestamping. Note that the syslog-ng Agent cannot produce fractions of a second (for example milliseconds) in the timestamp.

MIN, R_MIN, S_MIN

Description: The minute the message was sent.

MONTH, R_MONTH, S_MONTH

Description: The month the message was sent as a decimal value, prefixed with a zero if smaller than 10.

MONTHNAME, R_MONTHNAME, S_MONTHNAME

Description: The English name of the month the message was sent, abbreviated to three characters (for example Jan, Feb, and so on).

SEC, R_SEC, S_SEC

Description: The second the message was sent.

TZ, R_TZ, S_TZ

Description: An alias of the ${TZOFFSET} macro.

TZOFFSET, R_TZOFFSET, S_TZOFFSET

Description: The time-zone as hour offset from GMT, for example: -07:00. In syslog-ng 1.6.x this used to be -0700 but as ${ISODATE} requires the colon it was added to ${TZOFFSET} as well.

UNIXTIME, R_UNIXTIME, S_UNIXTIME

Description: Standard UNIX timestamp, represented as the number of seconds since 1970-01-01T00:00:00.

YEAR, R_YEAR, S_YEAR

Description: The year the message was sent.

WEEK, R_WEEK, S_WEEK

Description: The week number of the year, prefixed with a zero for the first nine week of the year. (The first Monday in the year marks the first week.)

WEEKDAY, R_WEEKDAY, S_WEEKDAY

Description: The 3-letter name of the day of week the message was sent, for example Thu.

Eventlog-related macros of the syslog-ng Agent

EVENT_CATEGORY

Description: The category of the event.

EVENT_DATA

Description: Empty macro, does not contain any data.

EVENT_CONTAINER_COUNTER

Description: The number of received messages per container since the syslog-ng Agent for Windows was started.

EVENT_FACILITY

Description: The facility that sent the message.

EVENT_GLOBAL_COUNTER

Description: A unique ID for messages generated at reception time on the receiving host. It facilitates defining relationships between messages that are potentially distributed to different files on the same host, or different hosts.

EVENT_HOST

Description: The name of the host that sent the log message.

EVENT_ID

Description: The identification number of the event.

EVENT_LEVEL

Description: Importance level of the message represented as a number: 6 - Success, 5 - Informational, 4- Warning, or 3 - Error).

EVENT_MESSAGE

Description: The content of the message.

EVENT_MESSAGE_XML

Description: Contains the entire message in XML format. Available only on Windows Vista, Server 2008, and newer platforms.

EVENT_MSG

Description: The content of the message. This is an alias of the EVENT_MESSAGE.

EVENT_MSG_XML

Description: Contains the entire message in XML format. This is an alias of the EVENT_MESSAGE_XML. Available only on Windows Vista, Server 2008, and newer platforms.

EVENT_NAME

Description: Name of the Windows event log container (for example Application or Security).

EVENT_PROVIDER

Description: Name of the service that generated the log message.

EVENT_REC_NUM

Description: The record number of the event in the event log.

EVENT_SID

Description: The security identification number of the event.

EVENT_SID_TYPE

Description: The security identification number resolved into name. One of the following: User, Group, Domain, AliasWellKnownGroup, DeletedAccount, Invalid, Unknown, Computer.

EVENT_SOURCE

Description: The application that created the message.

EVENT_TASK

Description: The task category of the event. Available only on Windows Vista, Server 2008, and newer platforms.

EVENT_TYPE

Description: The importance level of the message in text format.

EVENT_USERNAME

Description: The user running the application that created the message.

File-related macros of the syslog-ng Agent

FILE_CURRENT_POSITION

Description: The position of the message from the beginning of the file in bytes.

FILE_FACILITY

Description: The facility that sent the message.

FILE_LEVEL

Description: Importance level of the message represented as a number: 6 - Success, 5 - Informational, 4- Warning, or 3 - Error).

FILE_MESSAGE

Description: The content of the message.

FILE_MSG

Description: The content of the message. This is an alias of the FILE_MESSAGE macro.

FILE_NAME

Description: Name of the log file (including its path) from where the syslog-ng PE received the message.

FILE_SIZE

Description: The current size of the file in bytes.

Chapter 9. Controlling the syslog-ng Agent services

During installation, syslog-ng Agent registers the syslog-ng Agent service that is started automatically when the host boots. To disable the automatic startup of the syslog-ng Agent use the Start Menu > Control Panel > Administrative Tools > Services interface. The service is running with the privileges of the NT AUTHORITY\SYSTEM user.

To manually start or stop the service use the Start Menu > Control Panel > Administrative Tools > Services interface, or navigate to Start Menu > Programs > syslog-ng Agent for Windows. Note that in the latter case if User Access Control (UAC) is enabled, you need the Run as Administrator privilege to start or stop the syslog-ng Agent.

When the syslog-ng Agent service is started or stopped, it sends a syslog message to the central log server and an eventlog message to the Application eventlog container of the host.

Caution:

If you change the timezone setting of the host while the syslog-ng Agent is running, you have to restart the syslog-ng Agent. Otherwise, it will not receive the updated timezone information and the date of the events will be incorrect.

NOTE:

It is possible to run the service with an administrator account that has "log on as service" rights (to set user rights, navigate to Local Security Policy > Local Policies > User rights Assignment). These settings are unsupported, use them only at your own risk. Also note that during the next upgrade procedure, these settings will be overwritten by factory default settings.

Command-line options

The syslog-ng Agent for Windows application has the following command-line options:

NOTE:

Command-line options are case-insensitive. The options consist of a single letter introduced by either "-" or "/".

NOTE:

On Windows Vista or above, command line options will only work with administrator permission.

/c

Start the syslog-ng Agent using the specified XML configuration file.

/d

Start the syslog-ng Agent in debug mode.

/h

Display a help message about the command-line options.

/i

Install the syslog-ng Agent service into the services list.

/r

Remove the syslog-ng Agent service from the services list.

/v

Display version information.

/x

Validate XML configuration file without importing it.

To use these options, select Start > Run > cmd, navigate to the directory where the syslog-ng Agent is installed (for example cd C:\Windows\Program Files\BalaBit\syslog-ng Agent\), and execute the syslog-ng-agent.exe file with the required option.

Example 9.1. Using command line options

To start syslog-ng Agent in debug mode:

syslog-ng-agent.exe /d

To start syslog-ng Agent with XML configuration file:

syslog-ng-agent.exe /c C:\ConfigFiles\syslog-ng-agent-conf.xml 

To register syslog-ng Agent as a service using XML configuration file:

syslog-ng-agent.exe /i C:\ConfigFiles\syslog-ng-agent-conf.xml

Chapter 10. Troubleshooting syslog-ng Agent for Windows

In case you experience problems with the syslog-ng Agent for Windows application, the following points can be of help.

NOTE:

The followings address only problems specific to the syslog-ng Agent, and assume that communication between the server and the client is otherwise possible (that is, the server is properly configured to receive messages and is available on the network, and name resolution is properly configured on the client).

Configuration changes do not take effect: 

Configuration changes take effect only after restarting the syslog-ng service or rebooting the system. Also restart the system after changing the timezone settings of the host, or importing a certificate that you want to use to authenticate the communication between the agent and the server. If the configuration of the agent has changed since the last restart, the syslog-ng Agent sends a message of the change, including the hmac-sha-1 hash of the new configuration.

Also note that if your clients are managed from a Domain Controller, configuration changes are not instantly downloaded to the client hosts, only at the time of the next group policy update. To update the configuration of a client host earlier, open a command prompt on the client host, and issue the gpupdate /force command.

After downloading the configuration from the Domain Controller, the syslog-ng Agent service is automatically restarted if the configuration has changed.

NOTE:

Certain domain settings that can affect the syslog-ng Agent are downloaded only when the machine is rebooted. For example, moving the computer from one group policy to another requires a reboot to have effect.

The syslog-ng Agent does not send messages to the server: 

Check the Application eventlog for messages of the syslog-ng Agent. In case of connection errors and certificate problems, the syslog-ng Agent sends error messages into the eventlog. Ensure that the destination address of the server is correctly set. If you use SSL encryption, verify that the certificate of the Certificate Authority of the server and that the certificate of the client are properly imported. If there are no error messages, check the logs on your log server: the syslog-ng Agent sends a MARK message every ten minutes even if there are no other messages to send (unless you have disabled MARK messages).

The syslog-ng Agent sends only MARK messages to the server: 

Verify that you have configured the eventlog and file sources, and that they have not been disabled globally. If these settings are correct but the server still does not send any messages, temporarily disable all filters to see that they are not configured to ignore every message. When using filter, it is also recommended to check the global case-sensitivity settings.

The hostname used in the messages changes: If a host is sometimes logged in into a domain and sometimes it is not, its hostname might reflect this. To avoid this situation, select syslog-ng Agent Settings and double-click on Global Settings. Enable Global Settings, navigate to Hostname and select Use FQDN. This causes syslog-ng Agent to resolve its own hostname from DNS and use the resolved FQDN in the syslog messages. For details, see Procedure 5.8, “Configuring the hostname format”.

Command-line parameters are ignored on Windows Vista and 2008 Server: 

Command-line parameters work only for administrators if User Account Control (UAC) is enabled. To execute syslog-ng Agent with command-line parameters, select Start > Programs > Accessories, right-click on Command prompt > Run as administrator.

If you contact the BalaBit Support Team about a problem with the syslog-ng Agent for Windows, execute the syslog-ng-agent -V command from the command line and include every version and platform information it displays in your support request.

CPU load is high: See the section called “Sending messages and CPU load”.

Losing messages from eventlog containers: 

An eventlog container is a special file. The Agent reads this file, formats the messages and sends them to remote log server. Note that the eventlog container can be configured only to a certain size. If the container reaches that size, Windows writes the next message to the beginning of the file. As a result, if the agent is not running (or the destination server is unavailable) so long that the eventlog container is filled up, messages can be lost.

Logs are not forwarded instantly: 

For the logs of certain applications (for example, Internet Information Services (IIS) for Windows Server), the syslog-ng Agent for Windows application does not forward the log messages in real time, only in batches after a certain amount of time. The cause of the problem is that the Windows operating system does not immediately flush its buffers to the file when an application sends a log message. The syslog-ng Agent for Windows application immediately starts sending the log messages when they become available in the log file.

Sending messages and CPU load

The syslog-ng Agent application can send messages to the server when the Windows Scheduler provides resources to the syslog-ng Agent. When there are many unsent log messages in the log sources, and there is no other significant activity on the host, syslog-ng will start to send the messages to the server, possibly increasing the CPU load to 100%. After all messages have been sent, or if another application requires the resources, the CPU load decreases back to normal.

TIP:

To avoid the initial large load on the CPU, limit the rate of message sending temporarily. You can remove the limit after the old messages have been sent. For details, see Procedure 4.2, “Limiting the rate of messages”.

When relaying the messages from multiple sources, the syslog-ng Agent sends one message at a time from each source. That way a single source with a large log traffic does not block other log sources.

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.

Related Documents