salt.modules.win_wua¶

Module for managing Windows Updates using the Windows Update Agent.

List updates on the system using the following functions:

win_wua.available
win_wua.list

This is an easy way to find additional information about updates available to to the system, such as the GUID, KB number, or description.

Once you have the GUID or a KB number for the update you can get information about the update, download, install, or uninstall it using these functions:

win_wua.get
win_wua.download
win_wua.install
win_wua.uninstall

The get function expects a name in the form of a GUID, KB, or Title and should return information about a single update. The other functions accept either a single item or a list of items for downloading/installing/uninstalling a specific list of items.

The win_wua.list and win_wua.get functions are utility functions. In addition to returning information about updates they can also download and install updates by setting download=True or install=True. So, with py:func:win_wua.list <salt.modules.win_wua.list_> for example, you could run the function with the filters you want to see what is available. Then just add install=True to install everything on that list.

If you want to download, install, or uninstall specific updates, use win_wua.download, win_wua.install, or win_wua.uninstall. To update your system with the latest updates use win_wua.list and set install=True

You can also adjust the Windows Update settings using the win_wua.set_wu_settings function. This function is only supported on the following operating systems:

Windows Vista / Server 2008
Windows 7 / Server 2008R2
Windows 8 / Server 2012
Windows 8.1 / Server 2012R2

As of Windows 10 and Windows Server 2016, the ability to modify the Windows Update settings has been restricted. The settings can be modified in the Local Group Policy using the lgpo module.

New in version 2015.8.0.

depends: salt.utils.win_update

salt.modules.win_wua.available(software=True, drivers=True, summary=False, skip_installed=True, skip_hidden=True, skip_mandatory=False, skip_reboot=False, categories=None, severities=None)¶

New in version 2017.7.0.

List updates that match the passed criteria. This allows for more filter options than list(). Good for finding a specific GUID or KB.

Parameters

software (bool) -- Include software updates in the results (default is True)
drivers (bool) -- Include driver updates in the results (default is True)
summary (bool) --
- True: Return a summary of updates available for each category.
- False (default): Return a detailed list of available updates.
skip_installed (bool) -- Skip updates that are already installed. Default is False.
skip_hidden (bool) -- Skip updates that have been hidden. Default is True.
skip_mandatory (bool) -- Skip mandatory updates. Default is False.
skip_reboot (bool) -- Skip updates that require a reboot. Default is False.
categories (list) --
Specify the categories to list. Must be passed as a list. All categories returned by default.

Categories include the following:
- Critical Updates
- Definition Updates
- Drivers (make sure you set drivers=True)
- Feature Packs
- Security Updates
- Update Rollups
- Updates
- Update Rollups
- Windows 7
- Windows 8.1
- Windows 8.1 drivers
- Windows 8.1 and later drivers
- Windows Defender
severities (list) --
Specify the severities to include. Must be passed as a list. All severities returned by default.

Severities include the following:
- Critical
- Important

Returns

Returns a dict containing either a summary or a list of updates:

List of Updates:
{'<GUID>': {'Title': <title>,
            'KB': <KB>,
            'GUID': <the globally unique identifier for the update>
            'Description': <description>,
            'Downloaded': <has the update been downloaded>,
            'Installed': <has the update been installed>,
            'Mandatory': <is the update mandatory>,
            'UserInput': <is user input required>,
            'EULAAccepted': <has the EULA been accepted>,
            'Severity': <update severity>,
            'NeedsReboot': <is the update installed and awaiting reboot>,
            'RebootBehavior': <will the update require a reboot>,
            'Categories': [ '<category 1>',
                            '<category 2>',
                            ...]
            }
}

Summary of Updates:
{'Total': <total number of updates returned>,
 'Available': <updates that are not downloaded or installed>,
 'Downloaded': <updates that are downloaded but not installed>,
 'Installed': <updates installed (usually 0 unless installed=True)>,
 'Categories': { <category 1>: <total for that category>,
                 <category 2>: <total for category 2>,
                 ... }
}

Return type

dict

CLI Examples:

# Normal Usage (list all software updates)
salt '*' win_wua.available

# List all updates with categories of Critical Updates and Drivers
salt '*' win_wua.available categories=["Critical Updates","Drivers"]

# List all Critical Security Updates
salt '*' win_wua.available categories=["Security Updates"] severities=["Critical"]

# List all updates with a severity of Critical
salt '*' win_wua.available severities=["Critical"]

# A summary of all available updates
salt '*' win_wua.available summary=True

# A summary of all Feature Packs and Windows 8.1 Updates
salt '*' win_wua.available categories=["Feature Packs","Windows 8.1"] summary=True

salt.modules.win_wua.download(names)¶

New in version 2017.7.0.

Downloads updates that match the list of passed identifiers. It's easier to use this function by using list_updates and setting install=True.

Parameters: names (str, list) -- A single update or a list of updates to download. This can be any combination of GUIDs, KB numbers, or names. GUIDs or KBs are preferred.

Note

An error will be raised if there are more results than there are items in the names parameter

Returns: A dictionary containing the details about the downloaded updates
Return type: dict

CLI Examples:

# Normal Usage
salt '*' win_wua.download names=['12345678-abcd-1234-abcd-1234567890ab', 'KB2131233']

salt.modules.win_wua.get(name, download=False, install=False)¶

New in version 2017.7.0.

Returns details for the named update

Parameters

name (str) -- The name of the update you're searching for. This can be the GUID, a KB number, or any part of the name of the update. GUIDs and KBs are preferred. Run list to get the GUID for the update you're looking for.
download (bool) -- Download the update returned by this function. Run this function first to see if the update exists, then set download=True to download the update.
install (bool) -- Install the update returned by this function. Run this function first to see if the update exists, then set install=True to install the update.

Returns

Returns a dict containing a list of updates that match the name if download and install are both set to False. Should usually be a single update, but can return multiple if a partial name is given.

If download or install is set to true it will return the results of the operation.

List of Updates:
{'<GUID>': {'Title': <title>,
            'KB': <KB>,
            'GUID': <the globally unique identifier for the update>
            'Description': <description>,
            'Downloaded': <has the update been downloaded>,
            'Installed': <has the update been installed>,
            'Mandatory': <is the update mandatory>,
            'UserInput': <is user input required>,
            'EULAAccepted': <has the EULA been accepted>,
            'Severity': <update severity>,
            'NeedsReboot': <is the update installed and awaiting reboot>,
            'RebootBehavior': <will the update require a reboot>,
            'Categories': [ '<category 1>',
                            '<category 2>',
                            ...]
            }
}

Return type

dict

CLI Examples:

# Recommended Usage using GUID without braces
# Use this to find the status of a specific update
salt '*' win_wua.get 12345678-abcd-1234-abcd-1234567890ab

# Use the following if you don't know the GUID:

# Using a KB number
# Not all updates have an associated KB
salt '*' win_wua.get KB3030298

# Using part or all of the name of the update
# Could possibly return multiple results
# Not all updates have an associated KB
salt '*' win_wua.get 'Microsoft Camera Codec Pack'

salt.modules.win_wua.get_needs_reboot()¶

Determines if the system needs to be rebooted.

Returns: True if the system requires a reboot, otherwise False
Return type: bool

CLI Examples:

salt '*' win_wua.get_needs_reboot

salt.modules.win_wua.get_wu_settings()¶

Get current Windows Update settings.

Returns

A dictionary of Windows Update settings:

Featured Updates:

Boolean value that indicates whether to display notifications for featured updates.

Group Policy Required (Read-only):

Boolean value that indicates whether Group Policy requires the Automatic Updates service.

Microsoft Update:

Boolean value that indicates whether to turn on Microsoft Update for other Microsoft Products

Needs Reboot:

Boolean value that indicates whether the machine is in a reboot pending state.

Non Admins Elevated:

Boolean value that indicates whether non-administrators can perform some update-related actions without administrator approval.

Notification Level:

Number 1 to 4 indicating the update level:

Never check for updates
Check for updates but let me choose whether to download and install them
Download updates but let me choose whether to install them
Install updates automatically

Read Only (Read-only):

Boolean value that indicates whether the Automatic Update settings are read-only.

Recommended Updates:

Boolean value that indicates whether to include optional or recommended updates when a search for updates and installation of updates is performed.

Scheduled Day:

Days of the week on which Automatic Updates installs or uninstalls updates.

Scheduled Time:

Time at which Automatic Updates installs or uninstalls updates.

Return type

dict

CLI Examples:

salt '*' win_wua.get_wu_settings

salt.modules.win_wua.install(names)¶

New in version 2017.7.0.

Installs updates that match the list of identifiers. It may be easier to use the list_updates function and set install=True.

Parameters: names (str, list) -- A single update or a list of updates to install. This can be any combination of GUIDs, KB numbers, or names. GUIDs or KBs are preferred.

Note

An error will be raised if there are more results than there are items in the names parameter

Returns: A dictionary containing the details about the installed updates
Return type: dict

CLI Examples:

# Normal Usage
salt '*' win_wua.install KB12323211

salt.modules.win_wua.list(software=True, drivers=False, summary=False, skip_installed=True, categories=None, severities=None, download=False, install=False)¶

New in version 2017.7.0.

Returns a detailed list of available updates or a summary. If download or install is True the same list will be downloaded and/or installed.

Parameters

software (bool) -- Include software updates in the results (default is True)
drivers (bool) -- Include driver updates in the results (default is False)
summary (bool) --
- True: Return a summary of updates available for each category.
- False (default): Return a detailed list of available updates.
skip_installed (bool) -- Skip installed updates in the results (default is False)
download (bool) -- (Overrides reporting functionality) Download the list of updates returned by this function. Run this function first with download=False to see what will be downloaded, then set download=True to download the updates.
install (bool) -- (Overrides reporting functionality) Install the list of updates returned by this function. Run this function first with install=False to see what will be installed, then set install=True to install the updates.
categories (list) --
Specify the categories to list. Must be passed as a list. All categories returned by default.

Categories include the following:
- Critical Updates
- Definition Updates
- Drivers (make sure you set drivers=True)
- Feature Packs
- Security Updates
- Update Rollups
- Updates
- Update Rollups
- Windows 7
- Windows 8.1
- Windows 8.1 drivers
- Windows 8.1 and later drivers
- Windows Defender
severities (list) --
Specify the severities to include. Must be passed as a list. All severities returned by default.

Severities include the following:
- Critical
- Important

Returns

Returns a dict containing either a summary or a list of updates:

List of Updates:
{'<GUID>': {'Title': <title>,
            'KB': <KB>,
            'GUID': <the globally unique identifier for the update>
            'Description': <description>,
            'Downloaded': <has the update been downloaded>,
            'Installed': <has the update been installed>,
            'Mandatory': <is the update mandatory>,
            'UserInput': <is user input required>,
            'EULAAccepted': <has the EULA been accepted>,
            'Severity': <update severity>,
            'NeedsReboot': <is the update installed and awaiting reboot>,
            'RebootBehavior': <will the update require a reboot>,
            'Categories': [ '<category 1>',
                            '<category 2>',
                            ...]
            }
}

Summary of Updates:
{'Total': <total number of updates returned>,
 'Available': <updates that are not downloaded or installed>,
 'Downloaded': <updates that are downloaded but not installed>,
 'Installed': <updates installed (usually 0 unless installed=True)>,
 'Categories': { <category 1>: <total for that category>,
                 <category 2>: <total for category 2>,
                 ... }
}

Return type

dict

CLI Examples:

# Normal Usage (list all software updates)
salt '*' win_wua.list

# List all updates with categories of Critical Updates and Drivers
salt '*' win_wua.list categories=['Critical Updates','Drivers']

# List all Critical Security Updates
salt '*' win_wua.list categories=['Security Updates'] severities=['Critical']

# List all updates with a severity of Critical
salt '*' win_wua.list severities=['Critical']

# A summary of all available updates
salt '*' win_wua.list summary=True

# A summary of all Feature Packs and Windows 8.1 Updates
salt '*' win_wua.list categories=['Feature Packs','Windows 8.1'] summary=True

salt.modules.win_wua.set_wu_settings(level=None, recommended=None, featured=None, elevated=None, msupdate=None, day=None, time=None)¶

Change Windows Update settings. If no parameters are passed, the current value will be returned.

Supported:

Windows Vista / Server 2008
Windows 7 / Server 2008R2
Windows 8 / Server 2012
Windows 8.1 / Server 2012R2

Parameters

level (int) --
Number from 1 to 4 indicating the update level:
1. Never check for updates
2. Check for updates but let me choose whether to download and install them
3. Download updates but let me choose whether to install them
4. Install updates automatically
recommended (bool) -- Boolean value that indicates whether to include optional or recommended updates when a search for updates and installation of updates is performed.
featured (bool) -- Boolean value that indicates whether to display notifications for featured updates.
elevated (bool) -- Boolean value that indicates whether non-administrators can perform some update-related actions without administrator approval.
msupdate (bool) -- Boolean value that indicates whether to turn on Microsoft Update for other Microsoft products
day (str) --
Days of the week on which Automatic Updates installs or uninstalls updates. Accepted values:
- Everyday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
time (str) -- Time at which Automatic Updates installs or uninstalls updates. Must be in the ##:## 24hr format, eg. 3:00 PM would be 15:00. Must be in 1 hour increments.

Returns

Returns a dictionary containing the results.

Return type

dict

CLI Examples:

salt '*' win_wua.set_wu_settings level=4 recommended=True featured=False

salt.modules.win_wua.uninstall(names)¶

New in version 2017.7.0.

Uninstall updates.

Parameters: names (str, list) -- A single update or a list of updates to uninstall. This can be any combination of GUIDs, KB numbers, or names. GUIDs or KBs are preferred.
Returns: A dictionary containing the details about the uninstalled updates
Return type: dict

CLI Examples:

# Normal Usage
salt '*' win_wua.uninstall KB3121212

# As a list
salt '*' win_wua.uninstall guid=['12345678-abcd-1234-abcd-1234567890ab', 'KB1231231']

Generated on August 05, 2021 at 04:04:00 UTC.

You are viewing docs for the previous stable release, 3000.9. Switch to docs for the latest stable release, 3003.1, or to a recent doc build from the master branch.

saltstack.com