Module for managing Windows Updates using the Windows Update Agent.
List updates on the system using the following functions:
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:
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:
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: |
|
---|---|
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: |
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.
download_update
(name)¶Deprecated since version 2017.7.0: Use download()
instead
Downloads a single update.
Parameters: | name (str) -- The name of the update to download. This can be a GUID, a KB number, or any part of the name. To ensure a single item is matched the GUID is preferred. |
---|
Note
If more than one result is returned an error will be raised.
Returns: | A dictionary containing the results of the download |
---|---|
Return type: | dict |
CLI Examples:
salt '*' win_wua.download_update 12345678-abcd-1234-abcd-1234567890ab
salt '*' win_wua.download_update KB12312321
salt.modules.win_wua.
download_updates
(names)¶Deprecated since version 2017.7.0: Use download()
instead
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 (list) -- A list of updates to download. This can be any combination of GUIDs, KB numbers, or names. GUIDs or KBs are preferred. |
---|---|
Returns: | A dictionary containing the details about the downloaded updates |
Return type: | dict |
CLI Examples:
# Normal Usage
salt '*' win_wua.download_updates guid=['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: |
|
---|---|
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: |
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:
|
---|---|
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.
install_update
(name)¶Deprecated since version 2017.7.0: Use install()
instead
Installs a single update
Parameters: |
|
---|
Note
If no results or more than one result is returned an error will be raised.
Returns: | A dictionary containing the results of the install |
---|---|
Return type: | dict |
CLI Examples:
salt '*' win_wua.install_update 12345678-abcd-1234-abcd-1234567890ab
salt '*' win_wua.install_update KB12312231
salt.modules.win_wua.
install_updates
(names)¶Deprecated since version 2017.7.0: Use install()
instead
Installs updates that match the list of identifiers. It may be easier to use the list_updates function and set install=True.
Parameters: |
|
---|---|
Returns: | A dictionary containing the details about the installed updates |
Return type: |
CLI Examples:
# Normal Usage
salt '*' win_wua.install_updates guid=['12345678-abcd-1234-abcd-1234567890ab', '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: |
|
---|---|
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: |
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.
list_update
(name, download=False, install=False)¶Deprecated since version 2017.7.0: Use get()
instead
Returns details for all updates that match the search criteria
Parameters: |
|
---|---|
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: |
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, skip_installed=True, categories=None, severities=None, download=False, install=False)¶Deprecated since version 2017.7.0: Use list()
instead
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: |
|
---|---|
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: |
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: |
|
---|---|
Returns: | Returns a dictionary containing the results. |
Return type: |
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']