Chat now with support
Chat with Support

syslog-ng Premium Edition 7.0.14 - Windows Event Collector Administration Guide

Configure Windows Event Collector

Once you have configured your event source computer(s), the next step is to configure your event collector, in this case, the Windows Event Collector for syslog-ng PE.

 NOTE:

The configuration file of WEC is YAML based. Note that YAML uses spaces, not tabs, for indentation.

To configure WEC, use the following options.

For an example wec.yaml file, see WEC configuration example.

server
Type: string
Default: N/A

Description: The hostname, IP address, or FQDN of the server where WEC is running. It must match the Common Name of the SSL certificate.

port
Type: integer
Default: 5986

Description: The port where the server running WEC is listening.

keyfile
Type: string
Default: N/A

Description: The path to the file that contains the unencrypted private key of the server running WEC. The file is in PEM format.

certfile
Type: string
Default: N/A

Description: The path to the file that contains the X.509 certificate of the server running WEC. The file is in PEM format.

cadir
Type: string
Default: N/A

Description: The path to the directory that contains the trusted CA certificates in PEM format.

log
Type: map
Default: N/A

Description: The options to specify how to handle the internal logs of WEC:

WEC sends internal log messages to stderr. You can also optionally specify a file to send logs to (in parallel with stderr). If you are using a systemd platform and start WEC using systemctl, then stderr is redirected to systemd-journal, and this is where you will find the internal logs of WEC.

level
Type: debug|info
Default: info

Description: The application log level of WEC.

Possible values are:

  • debug: Information with the most details, useful when debugging WEC and diagnosing issues.

  • info: Basic information about the initialization of WEC. Following initialization, no information is displayed on screen, unless an issue occurs.
file
Type: string
Default: N/A

Description: The path to the file where WEC should write internal log messages. The log file is automatically created by syslog-ng PE.

You can send this file to syslog-ng using a file() source.
eventdestination
Type: map
Default: N/A

Description: The options to specify how to store the event logs that are forwarded to WEC:

file
Type: string
Default: N/A

Description: The path to the file where WEC should write the events received from the Windows host(s). Use this option for debug purposes only, when you wish to check what WEC is sending to syslog-ng PE.

It is possible to log both to a file and a Unix datagram socket in parallel.
unixdatagram
Type: string
Default: N/A

Description: The path to the Unix datagram socket receiving the Windows events. WEC writes the received events to the Unix datagram socket specified here. The listening socket is automatically created by syslog-ng PE.

It is possible to log both to a file and a Unix datagram socket in parallel.
queuesize
Type: integer
Default: 10000

Description: The number of events that the destination memory queue can store. Note that the main purpose of queuesize is to speed up the writing of data into memory and smooth out peaks.

It is recommened to use the default value for this option.

For more information about flow control, see Flow control.
subscriptions
Type: map
Default: N/A

Description: The options related to the subscriptions you have set up on WEC:

NOTE:

You can set up multiple subscriptions to events coming from the same Windows host. If an event matches more than one subscription, the event log comes in to WEC as many times as there is a match.

name
Type: string
Default: N/A

Description: The unique name of the subscription in WEC.
computers
Type: list of strings
Default: N/A

Description: A list of strings that specifies the DNS names of the non-domain computers that are allowed to initiate subscriptions. Specifies the Windows hosts from which you want WEC to receive event logs.

The names can be specified using the * and ? wildcards, for example "*.mydomain.com" or "*".
contentformat
Type: Events|RenderedText
Default: N/A

Description: A value that specifies the format of the returned events.

Possible values are:

  • RenderedText: Events are returned with the localized strings (such as event description strings) attached to the events

  • Events: Events are returned without any of the localized strings

One Identity recommends setting this option to RenderedText.
heartbeats
Type: integer
Default: N/A

Description: A value that specifies the heartbeat interval for the subscription in seconds.
connectionretry
Type: integer
Default: N/A

Description: WEC attempts to reconnect to the Windows host(s) at the specified interval of time in seconds.
batchsizelimit
Type: integer
Default: 0 (meaning that there is no limit)

Description: Specifies the maximum number of items for batched delivery in the event subscription.

Set this value to 1 if you wish to perform tests or debugging.

 NOTE:

This option is not enforced on the Windows host side. Windows is handling this value only as a recommendation. The only exception is the value 1.
batchtimeoutlimit
Type: integer
Default: N/A

Description: Specifies the maximum latency allowed in delivering a batch of events (in seconds).

 NOTE:

This option is not enforced on the Windows host side. Windows is handling this value only as a recommendation.
queries
Type: string
Default: N/A

Description: Specifies the query string for the subscription.

You can:

  • type this value manually, or

  • copy this value from the XML tab of the Create Custom View pop-up window in Windows

For examples of queries, check the following Windows blog posts:
readexistingevents
Type: true|false
Default: false

Description: When the value is true, all existing events are read from the subscription event source if the subscription in question has not been read yet. When the value is false, only future (arriving) events are delivered. If the subscription has a state in the persist file, this option will have no effect.

Configure syslog-ng PE

Prerequisites:

syslog-ng Premium Edition version 7.0.6 or newer.

To enable syslog-ng PE to read and accept Windows events, you need to configure a source called windowsevent().

To configure syslog-ng PE

  1. Ensure that the default 5986 TCP port is accessible from WEC, as it is the Windows Event Collector that will initiate the event forwarding subscription toward the syslog-ng PE server.

  2. Configure the windowsevent() source.

    source s_wec {
    windowsevent();
};

    The windowsevent() source takes the following options:

    • unix-domain-socket(): The path to the Unix domain socket to read messages from.

      The default value is /opt/syslog-ng/var/run/wec.sock.

    • prefix(): The prefix that you wish to append to the key-value pairs.

      The default value is ".windowsevent.".

      If you want to send Windows event logs to SDATA, then set prefix(".SDATA."). This can be useful, for example, when you forward Windows event logs to a syslog-ng Store Box.

    For more information on the windowsevent() source, see "windowsevent: Collecting Windows event logs" in the Administration Guide.

  3. Define a complete log path in syslog-ng.conf to enable the windowsevent() source, s_wec. Otherwise, the WEC process will not run (connection refused).

    For example:

    source s_wec {
    windowsevent();
};

log {
    source(s_wec);
    destination {
        file("/var/log/example.log"
            template("$(format-json --scope dot-nv-pairs)\n")
        );
    };
};

Start/stop Windows Event Collector

To start and stop the Windows Event Collector tool manually, use the following commands:

systemd service for systemd-based systems:

  • Start WEC: systemctl start syslog-ng-wec

  • Stop WEC: systemctl stop syslog-ng-wec

SysV init for SysV-based systems:

  • Start WEC: /etc/init.d/syslog-ng-wec start

  • Stop WEC: /etc/init.d/syslog-ng-wec stop

To start WEC in the foreground, execute:

wec -c /path/to/wec.yaml

Message format in Windows Event Collector for syslog-ng PE

The Windows Event Collector for syslog-ng PE is supported for Windows 7 or newer platforms. Starting with Windows 7, event logging is XML-based, meaning that event log messages reach WEC in XML format. When these are forwarded to the syslog-ng PE server, syslog-ng PE parses them into key-value pairs using the XML parser.

Once event log data is available in syslog-ng PE, you have the flexibility to modify and format data any way you want, using macros and rewrite rules.

Note that while event log data as processed by the WEC tool may differ from the data collected and made available by the syslog-ng Agent for Windows, the Windows Event Collector tool provides you with greater freedom and flexibility when it comes to manipulating your raw data.

Related Documents