salt.modules.win_wua

Module for managing Windows Updates using the Windows Update Agent.

New in version 2015.8.0.

depends:
  • win32com
  • pythoncom
salt.modules.win_wua.download_update(guid=None)

Downloads a single update

Parameters:guid -- str A GUID for the update to be downloaded
Returns:A dictionary containing the status, a message, and a list of updates that were downloaded.

CLI Examples:

salt '*' win_wua.download_update 12345678-abcd-1234-abcd-1234567890ab
salt.modules.win_wua.download_updates(guid=None)

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

Parameters:guid -- A list of GUIDs to be downloaded
Returns:A dictionary containing the status, a message, and a list of updates that were downloaded.

CLI Examples:

# Normal Usage
salt '*' win_wua.download_updates                 guid=['12345678-abcd-1234-abcd-1234567890ab',                      '87654321-dcba-4321-dcba-ba0987654321']
salt.modules.win_wua.get_needs_reboot()

Determines if the system needs to be rebooted.

Returns:bool True if the system requires a reboot, False if not

CLI Examples:

salt '*' win_wua.get_needs_reboot
salt.modules.win_wua.get_wu_settings()

Get current Windows Update settings.

Returns:
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:
  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
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.

CLI Examples:

salt '*' win_wua.get_wu_settings
salt.modules.win_wua.install_update(guid=None)

Installs a single update

Parameters:guid -- str A GUID for the update to be installed
Returns:dict A dictionary containing the details about the installed update

CLI Examples:

salt '*' win_wua.install_update 12345678-abcd-1234-abcd-1234567890ab
salt.modules.win_wua.install_updates(guid=None)

Installs updates that match the passed criteria. It may be easier to use the list_updates function and set install=True.

Parameters:guid -- list A list of GUIDs to be installed
Returns:dict A dictionary containing the details about the installed updates

CLI Examples:

# Normal Usage
salt '*' win_wua.install_updates
 guid=['12345678-abcd-1234-abcd-1234567890ab',
 '87654321-dcba-4321-dcba-ba0987654321']
salt.modules.win_wua.list_update(name=None, download=False, install=False)

Returns details for all updates that match the search criteria

Parameters:
  • name (str) -- The name of the update you're searching for. This can be the GUID (preferred), a KB number, or the full name of the update. Run list_updates 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. This will override download=True
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 win_wua.download_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>',
                            ...]
            }
}

Return type:

dict

CLI Examples:

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

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

# Using a KB number (could possibly return multiple results)
# Not all updates have an associated KB
salt '*' win_wua.list_update 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.list_update 'Microsoft Camera Codec Pack'
salt.modules.win_wua.list_updates(software=True, drivers=False, summary=False, installed=False, categories=None, severities=None, download=False, install=False)

Returns a detailed list of available updates or a summary

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.
  • installed (bool) -- Include installed updates in the results (default if False)
  • download (bool) -- (Overrides reporting functionality) Download the list of updates returned by this function. Run this function first to see what will be installed, 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 to see what will be installed, then set install=True to install the updates. This will override download=True
  • 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 uinique 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_updates

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

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

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

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

# A summary of all Feature Packs and Windows 8.1 Updates
salt '*' win_wua.list_updates 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.

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
Returns:

Returns a dictionary containing the results.

CLI Examples:

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