: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]]
== Configure {beatname_uc}

++++
<titleabbrev>{beatname_uc}</titleabbrev>
++++

The `winlogbeat` section of the +{beatname_lc}.yml+ config file specifies all options that are specific to {beatname_uc}.
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 {beatname_uc} 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]
==== `shutdown_timeout`

The amount of time to wait for all events to be published when shutting down.
By default there is no shutdown timeout so {beatname_uc} will stop without waiting.
When you restart it will resume from the last successfully published event in
each event log.

In some use cases you do want to wait for the publishing queue to drain before
exiting and that's when you would use this option.

Valid time units are `ns`, `us`, `ms`, `s`, `m`, `h`.

[source,yaml]
--------------------------------------------------------------------------------
winlogbeat.shutdown_timeout: 30s
--------------------------------------------------------------------------------

[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}*

{beatname_uc} 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
--------------------------------------------------------------------------------

To read events from an archived `.evtx` file you can specify the `name` as the
absolute path (it cannot be relative) to the file. There's a complete example
of how to read from an .evtx file in the <<reading-from-evtx,FAQ>>.

[source,yaml]
--------------------------------------------------------------------------------
winlogbeat.event_logs:
  - name: 'C:\backup\sysmon-2019.08.evtx'
--------------------------------------------------------------------------------

[float]
==== `event_logs.ignore_older`

If this option is specified, {beatname_uc} 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 {beatname_uc} to optimize reads for forwarded events that are
already rendered. When the value is true {beatname_uc} 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 list of included and excluded (blocked) 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 {beatname_uc} 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 {beatname_uc}, 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
{beatname_uc} 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
    processors:
      - drop_event.when.not.or:
        - equals.winlog.event_id: 903
        - equals.winlog.event_id: 1024
        - equals.winlog.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 {beatname_uc}. 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 {beatname_uc} 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 <<winlogbeat-configuration-fields,fields>>
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 {beatname_uc}, 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 <<filtering-and-enhancing-data>> for information about specifying
processors in your config.

[float]
==== `event_logs.index`

If present, this formatted string overrides the index for events from this
event log (for elasticsearch outputs), or sets the `raw_index` field of the event's
metadata (for other outputs). This string can only refer to the agent name and
version and the event timestamp; for access to dynamic fields, use
`output.elasticsearch.index` or a processor.

Example value: `"%{[agent.name]}-myindex-%{+yyyy.MM.dd}"` might
expand to `"winlogbeat-myindex-2019.12.13"`.

[float]
==== `event_logs.keep_null`

If this option is set to true, fields with `null` values will be published in
the output document. By default, `keep_null` is set to `false`.

[float]
==== `event_logs.no_more_events`

The action that the event log reader should take when it receives a signal from
Windows that there are no more events to read. It can either `wait` for more
events to be written (the default behavior) or it can `stop`. The overall
{beatname_uc} process will stop when all of the individual event log readers have
stopped. *{vista_and_newer}*

Setting `no_more_events` to `stop` is useful when reading from archived event
log files where you want to read the whole file then exit. There's a complete
example of how to read from an `.evtx` file in the <<reading-from-evtx,FAQ>>.

[float]
==== `event_logs.api`

experimental[]

This selects the event log reader implementation that is used to read events
from the Windows APIs. You should only set this option when testing experimental
features. When the value is set to `wineventlog-experimental` Winlogbeat will
replace the default event log reader with the experimental implementation.
We are evaluating this implementation to see if it can provide increased
performance and reduce CPU usage. *{vista_and_newer}*

[source,yaml]
--------------------------------------------------------------------------------
winlogbeat.event_logs:
  - name: ForwardedEvents
    api: wineventlog-experimental
--------------------------------------------------------------------------------

There are a few notable differences in the events:

* Events that contained data under `winlog.user_data` will now have it under
  `winlog.event_data`.
* Setting `include_xml: true` has no effect.

