win_updates - Download and install Windows updates¶

New in version 2.0.

Synopsis
Parameters
Notes
Examples
Return Values
Status
Maintenance
- Support
- Author

Synopsis ¶

Searches, downloads, and installs Windows updates synchronously by automating the Windows Update client.

Parameters ¶

Parameter	Choices/Defaults	Comments
blacklist list (added in 2.5)		A list of update titles or KB numbers that can be used to specify which updates are to be excluded from installation. If an available update does match one of the entries, then it is skipped and not installed. Each entry can either be the KB article or Update title as a regex according to the PowerShell regex rules.
category_names list	Choices: Application Connectors CriticalUpdates ← DefinitionUpdates DeveloperKits FeaturePacks Guidance SecurityUpdates ← ServicePacks Tools UpdateRollups ← Updates Default: [u'CriticalUpdates', u'SecurityUpdates', u'UpdateRollups']	A scalar or list of categories to install updates from
log_path path		If set, `win_updates` will append update progress to the specified file. The directory must already exist.
reboot bool (added in 2.5)	Choices: no ← yes	Ansible will automatically reboot the remote host if it is required and continue to install updates after the reboot. This can be used instead of using a win_reboot task after this one and ensures all updates for that category is installed in one go. Async does not work when `reboot=True`.
reboot_timeout (added in 2.5)	Default: 1200	The time in seconds to wait until the host is back online from a reboot. This is only used if `reboot=True` and a reboot is required.
state	Choices: installed ← searched	Controls whether found updates are returned as a list or actually installed. This module also supports Ansible check mode, which has the same effect as setting state=searched
use_scheduled_task bool (added in 2.6)	Choices: no ← yes	Will not auto elevate the remote process with become and use a scheduled task instead. Set this to `yes` when using this module with async on Server 2008, 2008 R2, or Windows 7, or on Server 2008 that is not authenticated with basic or credssp. Can also be set to `yes` on newer hosts where become does not work due to further privilege restrictions from the OS defaults.
whitelist list (added in 2.5)		A list of update titles or KB numbers that can be used to specify which updates are to be searched or installed. If an available update does not match one of the entries, then it is skipped and not installed. Each entry can either be the KB article or Update title as a regex according to the PowerShell regex rules. The whitelist is only validated on updates that were found based on category_names. It will not force the module to install an update if it was not in the category specified.

Notes ¶

Note

win_updates must be run by a user with membership in the local Administrators group.
win_updates will use the default update service configured for the machine (Windows Update, Microsoft Update, WSUS, etc).
By default win_updates does not manage reboots, but will signal when a reboot is required with the reboot_required return value, as of Ansible 2.5 reboot can be used to reboot the host if required in the one task.
win_updates can take a significant amount of time to complete (hours, in some cases). Performance depends on many factors, including OS version, number of updates, system load, and update server load.
More information about PowerShell and how it handles RegEx strings can be found at https://technet.microsoft.com/en-us/library/2007.11.powershell.aspx.

Examples ¶

- name: Install all security, critical, and rollup updates without a scheduled task
  win_updates:
    category_names:
      - SecurityUpdates
      - CriticalUpdates
      - UpdateRollups

- name: Install only security updates as a scheduled task for Server 2008
  win_updates:
    category_names: SecurityUpdates
    use_scheduled_task: yes

- name: Search-only, return list of found updates (if any), log to C:\ansible_wu.txt
  win_updates:
    category_names: SecurityUpdates
    state: searched
    log_path: C:\ansible_wu.txt

- name: Install all security updates with automatic reboots
  win_updates:
    category_names:
    - SecurityUpdates
    reboot: yes

- name: Install only particular updates based on the KB numbers
  win_updates:
    category_name:
    - SecurityUpdates
    whitelist:
    - KB4056892
    - KB4073117

- name: Exlude updates based on the update title
  win_updates:
    category_name:
    - SecurityUpdates
    - CriticalUpdates
    blacklist:
    - Windows Malicious Software Removal Tool for Windows
    - \d{4}-\d{2} Cumulative Update for Windows Server 2016

Return Values ¶

Common return values are documented here, the following are the fields unique to this module:

Key		Returned	Description
failed_update_count int		always	The number of updates that failed to install
filtered_updates complex		success	List of updates that were found but were filtered based on blacklist or whitelist. The return value is in the same form as updates. Sample: see the updates return value
found_update_count int		success	The number of updates found needing to be applied Sample: 3
installed_update_count int		success	The number of updates successfully installed Sample: 2
reboot_required boolean		success	True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot) Sample: True
updates complex		success	List of updates that were found/installed
	kb list of strings	always	A list of KB article IDs that apply to the update Sample: ['3004365']
	title string	always	Display name Sample: Security Update for Windows Server 2012 R2 (KB3004365)
	failure_hresult_code boolean	on install failure	The HRESULT code from a failed update Sample: 2147942402
	id string (guid)	always	Internal Windows Update GUID Sample: fb95c1c8-de23-4089-ae29-fd3351d55421
	installed boolean	always	Was the update successfully installed Sample: True

Status ¶

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance ¶

This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Core Team, see here.

Support ¶

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author ¶

Matt Davis (@nitzmahone)

Hint

If you notice any issues in this documentation you can edit this document to improve it.