salt.modules.win_pkg

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:

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:
  • ver1 (str) -- A software version to compare
  • oper (str) -- The operand to use to compare
  • ver2 (str) -- A software version to compare

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:
  • 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 proess. If False, no error will be raised, and a dictionary containing the full results will be returned.
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:
  • name (str, list, or None) -- The name of a single package, or a comma-separated list of packages to install. (no spaces after the commas)
  • refresh (bool) -- Boolean value representing whether or not to refresh the winrepo db
  • pkgs (list or None) -- A list of packages to install from a software repository. All packages listed under pkgs will be installed via a single command.

Keyword Arguments (kwargs)

Parameters:
  • version (str) -- The specific version to install. If omitted, the latest version will be installed. If passed with multiple install, the version will apply to all packages. Recommended for single installation only.
  • cache_file (str) -- A single file to copy down for use with the installer. Copied to the same location as the installer. Use this over cache_dir if there are many files in the directory and you only need a specific file and don't want to cache additional files that may reside in the installer directory. Only applies to files on salt://
  • cache_dir (bool) -- True will copy the contents of the installer directory. This is useful for installations that are not a single file. Only applies to directories on salt://
  • 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_witnessed

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

Return type:

dict

If the package is installed by pkg.install:

{'<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:
  • saltenv (str) -- The salt environment to use. Default base.
  • refresh (bool) --

    Refresh package metadata. Default ``False`.

    {'<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

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().

name
The name of the package to be deleted.
version
The version of the package to be deleted. If this option is used in combination with the pkgs option below, then this version will be applied to all targeted packages.

Multiple Package Options:

pkgs
A list of packages to delete. Must be passed as a python list. The 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)

Fetches metadata files and calls pkg.genrepo to compile updated repository metadata.

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

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, version=None, **kwargs)

Remove the passed package(s) from the system using winrepo

Parameters:
  • name (str, list, or None) -- The name of the package to be uninstalled.
  • 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.

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 pkg.remove:

{'<package>': {'old': '<old-version>',
'new': '<new-version>'}}

If the package is already uninstalled:

{'<package>': {'current': 'not installed'}}

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>