5. Collecting logs from Windows hosts
5.6. Customizing the message format
The format of the messages received from the eventlog and the file sources can be customized using templates.
You can define separate message format for the eventlog and the file sources. When creating a template to customiy the message format, you can use macros, all alphanumeric characters, and the following special characters:<>,():;-+/_.
To create a template, complete the following procedure:
Customizing the message format
Procedure 5.14. Customizing messages using templates
1. Start the configuration interface of the syslog-ng Agent for Windows application.
2. Select sysng Agent Settings > Destinations > Network, and double-click on IPv4. Select your log-server, and click Edit.
3. Type the message format you want to use into the Template field. Do not forget to add the$character before macros. See Section 5.6.2, “Macros available in the syslog-ng Agent” (p. 58) for a complete list of the available macros.
For example, to send the messages in the DATE HOSTNAME MESSAGE format, type Date:$DATE Hostname:$HOST Logmessage:$MESSAGE.
Note that the $MESSAGE macro contains not only the text of the log message, but also additional inform-ation received from the message source, such as the name of the eventlog container, or the file, as set in the eventlog-specific and file-specific templates. See Customizing eventlog messages (p. 57) and Custom-izing eventlog messages (p. 57) for details on modifying the eventlog-specific and file-specific templates.
Note
Templates are assigned to a single destination server, so it is possible to use different templates for different servers. However, a server and its failover servers always receive the same message.
Warning
If you have more than one destination servers configured (separate servers, not in failover mode), and you want to use the same template for every server, you must manually copy the template into the configuration of each server. Template modifications are not applied automatically to every server.
4. Click OK.
5. To activate the changes, restart the syslog-ng Agent service.
To customize the format of eventlog messages, complete the following procedure. This template is applied by the $MESSAGE macro to format messages received from the eventlog.
Procedure 5.15. Customizing eventlog messages
1. Start the configuration interface of the syslog-ng Agent for Windows application.
2. Select syslog-ng Agent Settings, right-click on Eventlog Sources and select Properties.
3. Type the message format into the Message Template field. You can use date- and eventlog-related macros (see Section 5.6.2, “Macros available in the syslog-ng Agent” (p. 58) for a list of macros).The message customized here is included in the server-specific templates using theMESSAGEmacro.
By default, the following is sent about file messages: ${EVENT_USERNAME}: ${EVENT_NAME}
${EVENT_SOURCE}: [${EVENT_TYPE}] ${EVENT_MSG} (EventID ${EVENT_ID}).
4. Select Apply, then OK. To activate the changes, restart the syslog-ng Agent service.
To customize the format of file messages, complete the following procedure. This template is applied by the
$MESSAGE macro to format messages received from the log files.
Customizing the message format
Procedure 5.16. Customizing file messages
1. Start the configuration interface of the syslog-ng Agent for Windows application.
2. Select syslog-ng Agent Settings, right-click on File Sources and select Properties.
3. Type the message format into the Message Template field. You can use date- and file-related macros (see Section 5.6.2, “Macros available in the syslog-ng Agent” (p. 58) for a list of macros). The message customized here is included in the server-specific templates using theMESSAGEmacro.
By default, the following is sent about file messages: $FILE_NAME:
$FILE_CURRENT_POSITION/$FILE_SIZE: $FILE_MESSAGE $DATE $R_DATE.
4. Select Apply, then OK. To activate the changes, restart the syslog-ng Agent service.
5.6.1. Customizing the timestamp used by the syslog-ng Agent
The syslog-ng agent can send the syslog messages using either the ISO or the BSD timestamp format. It is recommended to use the ISO format, because it contains much more information than the BSD format.
The macros related to the date of the message (e.g.:ISODATE,HOUR, etc.) have two further versions each:
one with theS_and one with theR_prefix (e.g.:S_DATEandR_DATE). TheS_DATEmacro represents the date found in the log message, i.e. when the message was sent by the original application.R_DATEis the date when syslog has received the message.
Note that in the syslog-ng agent, the macros without prefix (e.g.,DATE) always refer to the receiving date of the message (e.g.,R_DATE) when it arrived into the event log container, and are included only for compatibility reasons.
Warning
If a remote host is logging into the event log of the local host that is running syslog-ng Agent for Win-dows, both hosts should be in the same timezone, because the event log message does not include the timezone information of the sender host. Otherwise, the date of the messages received from the remote host will be incorrect.
5.6.2. Macros available in the syslog-ng Agent
The following tables list the available macros:
■ Macros related to protocol headers
■ Macros related to the date and time of the message
■ Macros related to eventlog sources
■ Macros related to file sources
By default, syslog-ng Agent uses the following format:<${PRI}>$DATE $HOST $MESSAGE, where$MESSAGE is${EVENT_USERNAME}: ${EVENT_NAME} ${EVENT_SOURCE}: [${EVENT_TYPE}] ${EVENT_MSG}
(EventID ${EVENT_ID}) for eventlog messages, and $FILE_NAME:
$FILE_CURRENT_POSITION/$FILE_SIZE: $FILE_MESSAGE $DATE $R_DATEfor file messages.
Customizing the timestamp used by the syslog-ng Agent
Description Macro
Name of the host sending the message.
HOST
The content of the message, including the text of the message and any file- or event-specific macros that are set for the source.
MESSAGE
The content of the message.
MSG
Priority header of the message, storing the facility and the level of the message.
PRI
Table 5.1. Protocol-related macros of the syslog-ng agent
Macros available in the syslog-ng Agent
Description Macro
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, e.g.,Jun 13 15:58:00. If possible, it is recommended to use ISODATEfor timestamping.
BSDDATE, R_BSDDATE, S_BSDDATE
An alias of the ISODATE macro.
DATE
The day the message was sent.
DAY, R_DAY, S_DAY
A nonstandard format for the date of the message using the same format asDATE, but including the year as well, e.g.:2006 Jun 13 15:58:00.
FULLDATE, R_FULLDATE,
S_FULLDATE
The hour of day the message was sent.
HOUR, R_HOUR, S_HOUR
Date of the message in the ISO 8601 compatible standard timestamp
format (yyyy-mm-ddThh:mm:ss+-ZONE), e.g.:
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 (e.g., milliseconds) in the timestamp.
ISODATE, R_ISODATE, S_ISODATE
The minute the message was sent.
MIN, R_MIN, S_MIN
The month the message was sent.
MONTH, R_MONTH, S_MONTH
The English name of the month the message was sent, abbreviated to three characters (e.g., Jan, Feb, etc.).
MONTHNAME, R_MONTHNAME,
S_MONTHNAME
Date when the message was recorded into the eventlog container.
R_DATE
Date when the message was created.
S_DATE
The second the message was sent.
SEC, R_SEC, S_SEC
The name of the time zone of the host.
TZ, R_TZ, S_TZ
The time-zone as hour offset from GMT; e.g.:-07:00. In syslog-ng 1.6.x this used to be-0700but asISODATErequires the colon it was added toTZOFFSETas well.
TZOFFSET, R_TZOFFSET,
S_TZOFFSET
Standard unix timestamp, represented as the number of seconds since 1970-01-01T00:00:00.
UNIXTIME, R_UNIXTIME, S_UNIX-TIME
The year the message was sent.
YEAR, R_YEAR, S_YEAR
The week number of the year. (The first Monday in the year marks the first week.)
WEEK, R_WEEK, S_WEEK
The 3-letter name of the day of week the message was sent, e.g.Thu.
WEEKDAY, R_WEEKDAY, S_WEEK-DAY
Table 5.2. Time-related macros of the syslog-ng agent
Macros available in the syslog-ng Agent
Description Macro
The category of the event.
EVENT_CATEGORY
The facility that sent the message.
EVENT_FACILITY
The identification number of the event.
EVENT_ID
Importance level of the message represented as a number: 6 - Success, 5 - Informa-tional, 4- Warning, or 3 - Error).
EVENT_LEVEL
The content of the message.
EVENT_MESSAGE EVENT_MSG
Name of the Windows event log container (e.g., Application or Security).
EVENT_NAME
The record number of the event in the event log.
EVENT_REC_NUM
The security identification number of the event.
EVENT_SID
The security identification number resolved into name. One of the following: User, Group,Domain,Alias WellKnownGroup,DeletedAccount,Invalid,Unknown, Computer.
EVENT_SID_TYPE
The application that created the message.
EVENT_SOURCE
The importance level of the message in text format.
EVENT_TYPE
The user running the application that created the message.
EVENT_USERNAME
Table 5.3. Eventlog-related macros of the syslog-ng agent Description
Macro
The position of the message from the beginning of the file in bytes.
FILE_CURRENT_POSITION
The facility that sent the message.
FILE_FACILITY
Importance level of the message represented as a number: 6 Success, 5 -Informational, 4- Warning, or 3 - Error).
FILE_LEVEL
The content of the message.
FILE_MESSAGE FILE_MSG
Name of the log file (including its path) from where the syslog-ng Agent received the message.
FILE_NAME
The current size of the file in bytes.
FILE_SIZE
Table 5.4. File-related macros of the syslog-ng agent