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.
salt.modules.win_pkg.
compare_versions
(ver1=u'', oper=u'==', ver2=u'')¶Compare software package versions
Parameters: |
---|
Returns (bool): True if the comparison is valid, otherwise False
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
CLI Example:
salt-run pkg.genrepo
salt -G 'os:windows' pkg.genrepo verbose=true failhard=false
salt -G 'os:windows' pkg.genrepo saltenv=base
Keyword Arguments (kwargs)
Parameters: |
|
---|
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: | 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: |
|
---|
Keyword Arguments (kwargs)
Parameters: |
|
---|---|
Returns: | Return a dict containing the new package names and versions: |
Return type: | dict If the package is installed by {'<package>': {'old': '<old-version>',
'new': '<new-version>'}}
If the package is already installed: {'<package>': {'current': '<current-version>'}}
|
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.
CLI Example:
salt '*' pkg.latest_version <package name>
salt '*' pkg.latest_version <package1> <package2> <package3> ...
Keyword Arguments (kwargs)
:param str saltenv: Salt environment. Default base
:param bool refresh: Refresh package metadata. Default True
salt.modules.win_pkg.
list_available
(*names, **kwargs)¶Return a list of available versions of the specified package.
Parameters: | name (str) -- One or more package names |
---|---|
Returns: | For multiple package names listed returns dict of package names and versions For single package name returns a version string |
Return type: | dict or string |
Keyword Arguments (kwargs)
:param str saltenv: The salt environment to use. Default base
.
:param bool refresh: Refresh package metadata. Default True
.
:param bool return_dict_always: Default False
dict when a single package name is queried.
CLI Example: .. code-block:: bash
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 in a dict:
*Keyword Arguments (kwargs)*
Parameters: |
---|
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 |
---|
Keyword Arguments (kwargs)
:param str saltenv: Salt environment. Default base
CLI Example:
salt '*' pkg.list_upgrades
salt.modules.win_pkg.
purge
(name=None, pkgs=None, version=None, **kwargs)¶Package purges are not supported, this function is identical to
remove()
.
pkgs
option below, then this version will be
applied to all targeted packages.Multiple Package Options:
name
parameter will be ignored if this option is passed.Keyword Arguments (kwargs)
:param str saltenv: Salt environment. Default base
:param bool refresh: Refresh package metadata. Default False
New in version 0.16.0.
Returns a dict containing the changes.
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)¶Fectches metadata files and calls pkg.genrepo
to compile updated repository metadata.
CLI Example:
salt '*' pkg.refresh_db
salt '*' pkg.refresh_db saltenv=base
salt.modules.win_pkg.
remove
(name=None, pkgs=None, version=None, **kwargs)¶Remove the passed package(s) from the system using winrepo
Parameters: |
|
---|
Multiple Package Options:
Parameters: | pkgs (list or None) -- A list of packages to delete. Must be passed as a python list. The
name parameter will be ignored if this option is passed. |
---|
New in version 0.16.0.
Keyword Arguments (kwargs)
:param str saltenv: Salt environment. Default base
:param bool refresh: Refresh package metadata. Default False
Returns: | Returns a dict containing the changes. |
---|---|
Return type: | dict If the package is removed by
If the package is already uninstalled:
|
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
Keyword Arguments (kwargs)
:param str saltenv: The salt environment to use. Default base
.
:param bool refresh: Refresh package metadata. Default True
.
Note
This feature is not yet implemented for Windows.
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 -- The name of a single package |
---|---|
Returns: | Return True if newer version available |
Return type: | bool |
Keyword Arguments (kwargs)
:param str saltenv: Salt environment
:param bool refresh: Refresh package metadata. Default True
CLI Example:
salt '*' pkg.upgrade_available <package name>
salt.modules.win_pkg.
version
(*names, **kwargs)¶Returns a version if the package is installed, else returns an empty string
Parameters: | name (str) -- One or more package names |
---|---|
Returns: | For multiple package names listed returns dict of package names and current version For single package name returns a current version string |
Return type: | dict or string |
Keyword Arguments (kwargs)
:param str saltenv: The salt environment to use. Default base
.
:param bool refresh: Refresh package metadata. Default False
.
CLI Example: .. code-block:: bash
salt '*' pkg.version <package name> salt '*' pkg.version <package name01> <package name02>
Docs for previous releases are available on readthedocs.org.
Latest Salt release: 2016.11.1