A module to manage software on Windows
Important
If you feel that Salt should be using this module to manage packages on a minion, and it is using a different module (or gives an error similar to 'pkg.install' is not available), see here.
The following functions require the existence of a windows repository metadata DB, typically created by running
pkg.refresh_db
:
pkg.get_repo_data
pkg.install
pkg.latest_version
pkg.list_available
pkg.list_pkgs
pkg.list_upgrades
pkg.remove
If a metadata DB does not already exist and one of these functions is run, then one will be created from the repo SLS files that are present.
As the creation of this metadata can take some time, the
winrepo_cache_expire_min
minion config option can be used to
suppress refreshes when the metadata is less than a given number of seconds
old.
Note
Version numbers can be version number string
, latest
and Not
Found
, where Not Found
means this module was not able to determine
the version of the software installed, it can also be used as the version
number in sls definitions file in these cases. Versions numbers are sorted
in order of 0, Not Found
, order version numbers
, ..., latest
.
salt.modules.win_pkg.
compare_versions
(ver1=u'', oper=u'==', ver2=u'')¶Compare software package versions
Parameters: | |
---|---|
Returns: | True if the comparison is valid, otherwise False |
Return type: |
CLI Example:
salt '*' pkg.compare_versions 1.2 >= 1.3
salt.modules.win_pkg.
genrepo
(**kwargs)¶Generate package metedata db based on files within the winrepo_source_dir
Kwargs:
saltenv (str): Salt environment. Default:
base
- verbose (bool):
- Return verbose data structure which includes 'success_list', a list of all sls files and the package names contained within. Default
False
.- failhard (bool):
- If
True
, an error will be raised if any repo SLS files failed to process. IfFalse
, no error will be raised, and a dictionary containing the full results will be returned.
Note
Returns: | A dictionary of the results of the command |
---|---|
Return type: | dict |
CLI Example:
salt-run pkg.genrepo
salt -G 'os:windows' pkg.genrepo verbose=true failhard=false
salt -G 'os:windows' pkg.genrepo saltenv=base
salt.modules.win_pkg.
get_repo_data
(saltenv=u'base')¶Returns the existing package meteadata db. Will create it, if it does not exist, however will not refresh it.
Parameters: | saltenv (str) -- Salt environment. Default base |
---|---|
Returns: | A dict containing contents of metadata db. |
Return type: | dict |
CLI Example:
salt '*' pkg.get_repo_data
salt.modules.win_pkg.
install
(name=None, refresh=False, pkgs=None, **kwargs)¶Install the passed package(s) on the system using winrepo
Parameters: |
|
---|
Kwargs:
- version (str):
The specific version to install. If omitted, the latest version will be installed. Recommend for use when installing a single package.
If passed with a list of packages in the
pkgs
parameter, the version will be ignored.CLI Example:
# Version is ignored salt '*' pkg.install pkgs="['foo', 'bar']" version=1.2.3If passed with a comma separated list in the
name
parameter, the version will apply to all packages in the list.CLI Example:
# Version 1.2.3 will apply to packages foo and bar salt '*' pkg.install foo,bar version=1.2.3- extra_install_flags (str):
- Additional install flags that will be appended to the
install_flags
defined in the software definition file. Only applies when single package is passed.- saltenv (str):
- Salt environment. Default 'base'
- report_reboot_exit_codes (bool):
If the installer exits with a recognized exit code indicating that a reboot is required, the module function
win_system.set_reboot_required_witnessedwill be called, preserving the knowledge of this event for the remainder of the current boot session. For the time being, 3010 is the only recognized exit code. The value of this param defaults to True.
New in version 2016.11.0.
Returns: | Return a dict containing the new package names and versions If the package is installed by {'<package>': {'old': '<old-version>',
'new': '<new-version>'}}
If the package is already installed: {'<package>': {'current': '<current-version>'}}
|
---|---|
Return type: | dict |
The following example will refresh the winrepo and install a single package, 7zip.
CLI Example:
salt '*' pkg.install 7zip refresh=True
CLI Example:
salt '*' pkg.install 7zip
salt '*' pkg.install 7zip,filezilla
salt '*' pkg.install pkgs='["7zip","filezilla"]'
WinRepo Definition File Examples:
The following example demonstrates the use of cache_file
. This would be
used if you have multiple installers in the same directory that use the
same install.ini
file and you don't want to download the additional
installers.
ntp:
4.2.8:
installer: 'salt://win/repo/ntp/ntp-4.2.8-win32-setup.exe'
full_name: Meinberg NTP Windows Client
locale: en_US
reboot: False
cache_file: 'salt://win/repo/ntp/install.ini'
install_flags: '/USEFILE=C:\salt\var\cache\salt\minion\files\base\win\repo\ntp\install.ini'
uninstaller: 'NTP/uninst.exe'
The following example demonstrates the use of cache_dir
. It assumes a
file named install.ini
resides in the same directory as the installer.
ntp:
4.2.8:
installer: 'salt://win/repo/ntp/ntp-4.2.8-win32-setup.exe'
full_name: Meinberg NTP Windows Client
locale: en_US
reboot: False
cache_dir: True
install_flags: '/USEFILE=C:\salt\var\cache\salt\minion\files\base\win\repo\ntp\install.ini'
uninstaller: 'NTP/uninst.exe'
salt.modules.win_pkg.
latest_version
(*names, **kwargs)¶Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.
If the latest version of a given package is already installed, an empty string will be returned for that package.
Parameters: | names (str) -- A single or multiple names to lookup |
---|
base
refresh (bool): Refresh package metadata. Default True
Returns: | A dictionary of packages with the latest version available |
---|---|
Return type: | dict |
CLI Example:
salt '*' pkg.latest_version <package name>
salt '*' pkg.latest_version <package1> <package2> <package3> ...
salt.modules.win_pkg.
list_available
(*names, **kwargs)¶Return a list of available versions of the specified package.
Parameters: | names (str) -- One or more package names |
---|
Kwargs:
saltenv (str): The salt environment to use. Default
base
.refresh (bool): Refresh package metadata. Default
False
.
- return_dict_always (bool):
- Default
False
dict when a single package name is queried.
Returns: | The package name with its available versions |
---|---|
Return type: | dict |
{'<package name>': ['<version>', '<version>', ]}
CLI Example:
salt '*' pkg.list_available <package name> return_dict_always=True
salt '*' pkg.list_available <package name01> <package name02>
salt.modules.win_pkg.
list_pkgs
(versions_as_list=False, **kwargs)¶List the packages currently installed
version_as_list (bool): Returns the versions as a list
saltenv (str): The salt environment to use. Default base
.
refresh (bool): Refresh package metadata. Default False
.
Returns: | A dictionary of installed software with versions installed |
---|---|
Return type: | dict |
{'<package_name>': '<version>'}
CLI Example:
salt '*' pkg.list_pkgs
salt '*' pkg.list_pkgs versions_as_list=True
salt.modules.win_pkg.
list_upgrades
(refresh=True, **kwargs)¶List all available package upgrades on this system
Parameters: | refresh (bool) -- Refresh package metadata. Default True |
---|
base
Returns: | A dictionary of packages with available upgrades |
---|---|
Return type: | dict |
CLI Example:
salt '*' pkg.list_upgrades
salt.modules.win_pkg.
purge
(name=None, pkgs=None, **kwargs)¶Package purges are not supported, this function is identical to
remove()
.
New in version 0.16.0.
Parameters: |
|
---|
base
refresh (bool): Refresh package metadata. Default False
Returns: | A dict containing the changes. |
---|---|
Return type: | dict |
CLI Example:
salt '*' pkg.purge <package name>
salt '*' pkg.purge <package1>,<package2>,<package3>
salt '*' pkg.purge pkgs='["foo", "bar"]'
salt.modules.win_pkg.
refresh_db
(**kwargs)¶Generates the local software metadata database (winrepo.p) on the minion. The database is stored in a serialized format located by default at the following location:
C:saltvarcachesaltminionfilesbasewinrepo-ngwinrepo.p
This module performs the following steps to generate the software metadata database:
pkg.genrepo
to parse the
package definition files and generate the repository metadata database
file (winrepo.p)pkg.genrepo
The default winrepo directory on the master is /srv/salt/win/repo-ng. All files that end with .sls in this and all subdirectories will be used to generate the repository metadata database (winrepo.p).
Note
Note
There is no need to call pkg.refresh_db every time you work with the pkg module. Automatic refresh will occur based on the following minion configuration settings:
However, if the package definition files have changed, as would be the case if you are developing a new package definition, this function should be called to ensure the minion has the latest information about packages available to it.
Warning
Directories and files fetched from <winrepo_source_dir> (/srv/salt/win/repo-ng) will be processed in alphabetical order. If two or more software definition files contain the same name, the last one processed replaces all data from the files processed before it.
For more information see Windows Software Repository
Arguments:
saltenv (str): Salt environment. Default: base
True
, an error will be raised if any repo SLS files fails to
process. If False
, no error will be raised, and a dictionary
containing the full results will be returned.Returns: | A dictionary containing the results of the database refresh. |
---|---|
Return type: | dict |
Note
A result with a total: 0 generally means that the files are in the wrong location on the master. Try running the following command on the minion: salt-call -l debug pkg.refresh saltenv=base
Warning
When calling this command from a state using module.run be sure to pass failhard: False. Otherwise the state will report failure if it encounters a bad software definition file.
CLI Example:
salt '*' pkg.refresh_db
salt '*' pkg.refresh_db saltenv=base
salt.modules.win_pkg.
remove
(name=None, pkgs=None, **kwargs)¶Remove the passed package(s) from the system using winrepo
New in version 0.16.0.
Parameters: |
---|
Kwargs:
- version (str):
- The version of the package to be uninstalled. If this option is used to to uninstall multiple packages, then this version will be applied to all targeted packages. Recommended using only when uninstalling a single package. If this parameter is omitted, the latest version will be uninstalled.
saltenv (str): Salt environment. Default
base
refresh (bool): Refresh package metadata. DefaultFalse
Returns: | Returns a dict containing the changes. If the package is removed by
If the package is already uninstalled:
|
---|---|
Return type: | dict |
CLI Example:
salt '*' pkg.remove <package name>
salt '*' pkg.remove <package1>,<package2>,<package3>
salt '*' pkg.remove pkgs='["foo", "bar"]'
salt.modules.win_pkg.
upgrade
(**kwargs)¶Upgrade all software. Currently not implemented
base
.
refresh (bool): Refresh package metadata. Default True
.Note
This feature is not yet implemented for Windows.
Returns: | Empty dict, until implemented |
---|---|
Return type: | dict |
CLI Example:
salt '*' pkg.upgrade
salt.modules.win_pkg.
upgrade_available
(name, **kwargs)¶Check whether or not an upgrade is available for a given package
Parameters: | name (str) -- The name of a single package |
---|
True
saltenv (str): The salt environment. Default base
Returns: | True if new version available, otherwise False |
---|---|
Return type: | bool |
CLI Example:
salt '*' pkg.upgrade_available <package name>
salt.modules.win_pkg.
version
(*names, **kwargs)¶Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.
Parameters: | name (str) -- One or more package names |
---|
base
.
refresh (bool): Refresh package metadata. Default False
.Returns: | version string when a single package is specified. dict: The package name(s) with the installed versions. |
---|---|
Return type: | str |
{['<version>', '<version>', ]} OR
{'<package name>': ['<version>', '<version>', ]}
CLI Example:
salt '*' pkg.version <package name>
salt '*' pkg.version <package name01> <package name02>