community.windows.win_eventlog (2.2.0) — module

Install collection

Install with ansible-galaxy collection install community.windows:==2.2.0

Add to requirements.yml

  collections:
    - name: community.windows
      version: 2.2.0

Description

Allows the addition, clearing and removal of local Windows event logs, and the creation and removal of sources from a given event log. Also allows the specification of settings per log and source.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Add a new event log with two custom sources
  community.windows.win_eventlog:
    name: MyNewLog
    sources:
      - NewLogSource1
      - NewLogSource2
    state: present

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Change the category and message resource files used for NewLogSource1
  community.windows.win_eventlog:
    name: MyNewLog
    sources:
      - NewLogSource1
    category_file: C:\NewApp\CustomCategories.dll
    message_file: C:\NewApp\CustomMessages.dll
    state: present

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Change the maximum size and overflow action for MyNewLog
  community.windows.win_eventlog:
    name: MyNewLog
    maximum_size: 16MB
    overflow_action: DoNotOverwrite
    state: present

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Clear event entries for MyNewLog
  community.windows.win_eventlog:
    name: MyNewLog
    state: clear

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Remove NewLogSource2 from MyNewLog
  community.windows.win_eventlog:
    name: MyNewLog
    sources:
      - NewLogSource2
    state: absent

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Remove MyNewLog and all remaining sources
  community.windows.win_eventlog:
    name: MyNewLog
    state: absent

Inputs

    
name:
    description:
    - Name of the event log to manage.
    required: true
    type: str

state:
    choices:
    - absent
    - clear
    - present
    default: present
    description:
    - Desired state of the log and/or sources.
    - When C(sources) is populated, state is checked for sources.
    - When C(sources) is not populated, state is checked for the specified log itself.
    - If C(state) is C(clear), event log entries are cleared for the target log.
    type: str

sources:
    description:
    - A list of one or more sources to ensure are present/absent in the log.
    - When C(category_file), C(message_file) and/or C(parameter_file) are specified, these
      values are applied across all sources.
    elements: str
    type: list

maximum_size:
    description:
    - The maximum size of the event log.
    - Value must be between 64KB and 4GB, and divisible by 64KB.
    - Size can be specified in KB, MB or GB (e.g. 128KB, 16MB, 2.5GB).
    type: str

message_file:
    description:
    - For one or more sources specified, the path to a custom event message resource file.
    type: path

category_file:
    description:
    - For one or more sources specified, the path to a custom category resource file.
    type: path

parameter_file:
    description:
    - For one or more sources specified, the path to a custom parameter resource file.
    type: path

retention_days:
    description:
    - The minimum number of days event entries must remain in the log.
    - This option is only used when C(overflow_action) is C(OverwriteOlder).
    type: int

overflow_action:
    choices:
    - DoNotOverwrite
    - OverwriteAsNeeded
    - OverwriteOlder
    description:
    - The action for the log to take once it reaches its maximum size.
    - For C(DoNotOverwrite), all existing entries are kept and new entries are not retained.
    - For C(OverwriteAsNeeded), each new entry overwrites the oldest entry.
    - For C(OverwriteOlder), new log entries overwrite those older than the C(retention_days)
      value.
    type: str

Outputs

entries:
  description: The count of entries present in the event log.
  returned: success
  sample: 50
  type: int
exists:
  description: Whether the event log exists or not.
  returned: success
  sample: true
  type: bool
maximum_size_kb:
  description: Maximum size of the log in KB.
  returned: success
  sample: 512
  type: int
name:
  description: The name of the event log.
  returned: always
  sample: MyNewLog
  type: str
overflow_action:
  description: The action the log takes once it reaches its maximum size.
  returned: success
  sample: OverwriteOlder
  type: str
retention_days:
  description: The minimum number of days entries are retained in the log.
  returned: success
  sample: 7
  type: int
sources:
  description: A list of the current sources for the log.
  returned: success
  sample:
  - MyNewLog
  - NewLogSource1
  - NewLogSource2
  type: list
sources_changed:
  description: A list of sources changed (e.g. re/created, removed) for the log; this
    is empty if no sources are changed.
  returned: always
  sample:
  - NewLogSource2
  type: list

See also

• community.windows.win_eventlog_entry