:vista_and_newer: This option is only available on operating systems + supporting the Windows Event Log API (Microsoft Windows Vista and newer). [[configuration-winlogbeat-options]] == Set up Winlogbeat The `winlogbeat` section of the +{beatname_lc}.yml+ config file specifies all options that are specific to Winlogbeat. Most importantly, it contains the list of event logs to monitor. Here is a sample configuration: [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: Application ignore_older: 72h - name: Security - name: System -------------------------------------------------------------------------------- [float] === Configuration options You can specify the following options in the `winlogbeat` section of the +{beatname_lc}.yml+ config file: [float] ==== `registry_file` The name of the file where Winlogbeat stores information that it uses to resume monitoring after a restart. By default the file is stored as `.winlogbeat.yml` in the directory where the Beat was started. When you run the process as a Windows service, it's recommended that you set the value to `C:/ProgramData/winlogbeat/.winlogbeat.yml`. [source,yaml] -------------------------------------------------------------------------------- winlogbeat.registry_file: C:/ProgramData/winlogbeat/.winlogbeat.yml -------------------------------------------------------------------------------- NOTE: The forward slashes (/) in the path are automatically changed to backslashes (\) for Windows compatibility. You can use either forward or backslashes. Forward slashes are easier to work with in YAML because there is no need to escape them. [float] ==== `event_logs` A list of entries (called 'dictionaries' in YAML) that specify which event logs to monitor. Each entry in the list defines an event log to monitor as well as any information to be associated with the event log (filter, tags, and so on). The `name` field is the only required field for each event log. [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: Application -------------------------------------------------------------------------------- [float] ==== `event_logs.batch_read_size` experimental[] The maximum number of event log records to read from the Windows API in a single batch. The default batch size is 100. Most Windows versions return an error if the value is larger than 1024. *{vista_and_newer}* Winlogbeat starts a goroutine (a lightweight thread) to read from each individual event log. The goroutine reads a batch of event log records using the Windows API, applies any processors to the events, publishes them to the configured outputs, and waits for an acknowledgement from the outputs before reading additional event log records. [float] [[configuration-winlogbeat-options-event_logs-name]] ==== `event_logs.name` The name of the event log to monitor. Each dictionary under `event_logs` must have a `name` field. You can get a list of available event logs by running `Get-EventLog *` in PowerShell. Here is a sample of the output from the command: [source,sh] -------------------------------------------------------------------------------- PS C:\Users\vagrant> Get-EventLog * Max(K) Retain OverflowAction Entries Log ------ ------ -------------- ------- --- 20,480 0 OverwriteAsNeeded 75 Application 20,480 0 OverwriteAsNeeded 0 HardwareEvents 512 7 OverwriteOlder 0 Internet Explorer 20,480 0 OverwriteAsNeeded 0 Key Management Service 20,480 0 OverwriteAsNeeded 1,609 Security 20,480 0 OverwriteAsNeeded 1,184 System 15,360 0 OverwriteAsNeeded 464 Windows PowerShell -------------------------------------------------------------------------------- Channel names can also be specified if running on Windows Vista or newer. A channel is a named stream of events that transports events from an event source to an event log. Most channels are tied to specific event publishers. Here is an example showing how to list all channels using PowerShell. [source,sh] -------------------------------------------------------------------------------- PS C:\> Get-WinEvent -ListLog * | Format-List -Property LogName LogName : Application LogName : HardwareEvents LogName : Internet Explorer LogName : Key Management Service LogName : Security LogName : System LogName : Windows PowerShell LogName : ForwardedEvents LogName : Microsoft-Management-UI/Admin LogName : Microsoft-Rdms-UI/Admin LogName : Microsoft-Rdms-UI/Operational LogName : Microsoft-Windows-Windows Firewall With Advanced Security/Firewall ... -------------------------------------------------------------------------------- You must specify the full name of the channel in the configuration file. [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: Microsoft-Windows-Windows Firewall With Advanced Security/Firewall -------------------------------------------------------------------------------- [float] ==== `event_logs.ignore_older` If this option is specified, Winlogbeat filters events that are older than the specified amount of time. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". This option is useful when you are beginning to monitor an event log that contains older records that you would like to ignore. This field is optional. [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: Application ignore_older: 168h -------------------------------------------------------------------------------- [float] ==== `event_logs.forwarded` A boolean flag to indicate that the log contains only events collected from remote hosts using the Windows Event Collector. The value defaults to true for the ForwardedEvents log and false for any other log. *{vista_and_newer}* This settings allows Winlogbeat to optimize reads for forwarded events that are already rendered. When the value is true Winlogbeat does not attempt to render the event using message files from the host computer. The Windows Event Collector subscription should be configured to use the "RenderedText" format (this is the default) to ensure that the events are distributed with messages and descriptions. [float] ==== `event_logs.event_id` A whitelist and blacklist of event IDs. The value is a comma-separated list. The accepted values are single event IDs to include (e.g. 4624), a range of event IDs to include (e.g. 4700-4800), and single event IDs to exclude (e.g. -4735). *{vista_and_newer}* [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: Security event_id: 4624, 4625, 4700-4800, -4735 -------------------------------------------------------------------------------- [WARNING] ======================================= If you specify more that 22 event IDs to include or 22 event IDs to exclude, Windows will prevent Winlogbeat from reading the event log because it limits the number of conditions that can be used in an event log query. If this occurs a similar warning as shown below will be logged by Winlogbeat, and it will continue processing data from other event logs. For more information, see https://support.microsoft.com/en-us/kb/970453. `WARN EventLog[Application] Open() error. No events will be read from this source. The specified query is invalid.` If you have more than 22 event IDs, you can workaround this Windows limitation by using a drop_event[drop-event] processor to do the filtering after Winlogbeat has received the events from Windows. The filter shown below is equivalent to `event_id: 903, 1024, 4624` but can be expanded beyond 22 event IDs. [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: Security event_id: ... processors: - drop_event.when.not.or: - equals.event_id: 903 - equals.event_id: 1024 - equals.event_id: 4624 -------------------------------------------------------------------------------- ======================================= [float] ==== `event_logs.level` A list of event levels to include. The value is a comma-separated list of levels. *{vista_and_newer}* [cols="2*", options="header"] |=== |Level |Value |critical, crit |1 |error, err |2 |warning, warn |3 |information, info |0 or 4 |verbose |5 |=== [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: Security level: critical, error, warning -------------------------------------------------------------------------------- [float] ==== `event_logs.provider` A list of providers (source names) to include. The value is a YAML list. *{vista_and_newer}* [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: Application provider: - Application Error - Application Hang - Windows Error Reporting - EMET -------------------------------------------------------------------------------- You can obtain a list of providers associated with a log by using PowerShell. Here is an example showing the providers associated with the Security log. [source,sh] -------------------------------------------------------------------------------- PS C:\> (Get-WinEvent -ListLog Security).ProviderNames DS LSA SC Manager Security Security Account Manager ServiceModel 4.0.0.0 Spooler TCP/IP VSSAudit Microsoft-Windows-Security-Auditing Microsoft-Windows-Eventlog -------------------------------------------------------------------------------- [float] ==== `event_logs.include_xml` Boolean option that controls if the raw XML representation of an event is included in the data sent by Winlogbeat. The default is false. *{vista_and_newer}* The XML representation of the event is useful for troubleshooting purposes. The data in the fields reported by Winlogbeat can be compared to the data in the XML to diagnose problems. Example: [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: Microsoft-Windows-Windows Defender/Operational include_xml: true -------------------------------------------------------------------------------- [float] ==== `event_logs.tags` A list of tags that the Beat includes in the `tags` field of each published event. Tags make it easy to select specific events in Kibana or apply conditional filtering in Logstash. These tags will be appended to the list of tags specified in the general configuration. Example: [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: CustomLog tags: ["web"] -------------------------------------------------------------------------------- [float] [[winlogbeat-configuration-fields]] ==== `event_logs.fields` Optional fields that you can specify to add additional information to the output. For example, you might add fields that you can use for filtering event data. Fields can be scalar values, arrays, dictionaries, or any nested combination of these. By default, the fields that you specify here will be grouped under a `fields` sub-dictionary in the output document. To store the custom fields as top-level fields, set the `fields_under_root` option to true. If a duplicate field is declared in the general configuration, then its value will be overwritten by the value declared here. [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: CustomLog fields: customer_id: 51415432 -------------------------------------------------------------------------------- [float] ==== `event_logs.fields_under_root` If this option is set to true, the custom <> are stored as top-level fields in the output document instead of being grouped under a `fields` sub-dictionary. If the custom field names conflict with other field names added by Winlogbeat, then the custom fields overwrite the other fields. [float] ==== `event_logs.processors` A list of processors to apply to the data generated by the event log. See <> for information about specifying processors in your config.