# 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`:

- `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='', oper='==', ver2='')

  Compare software package versions. Made public for use with Jinja

  Parameters:

    - ver1 (`str`, optional) --

      A software version to compare.

      Default is "".

    - oper (`str`, optional) --

      The operand to use to compare.

      Default is "==".

    - ver2 (`str`, optional) -- A software version to compare. Default is ""

  Returns:

    `True` if the comparison is valid, otherwise `False`.

  Return type:

    bool

  CLI Example:

      salt '*' pkg.compare_versions 1.2 >= 1.3

salt.modules.win_pkg.genrepo(**kwargs)

  Generate package metadata db based on files within the winrepo_source_dir

  Kwargs:

  > saltenv (str): Salt environment.

  > > Default is `base`.

  > verbose (bool):

  >   Return verbose data structure which includes 'success_list', a list of all sls files and the package names contained within.

  >   Default is `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.

  >   Default is `True`.

  Note

  - Hidden directories (directories beginning with '.', such as '.git') will be ignored.

  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_package_info(name, saltenv='base')

  Get information about the package as found in the winrepo database

  Parameters:

    - name (str) -- The name of the package

    - saltenv (`str`, optional) --

      The salt environment to use.

      Default is `base`.

  Returns:

    A dictionary of package info, empty if package not available

  Return type:

    dict

  CLI Example:

      salt '*' pkg.get_package_info chrome

salt.modules.win_pkg.get_repo_data(saltenv='base')

  Returns the existing package metadata db. Will create it, if it does not exist, however will not refresh it.

  Parameters:

    saltenv (`str`, optional) --

    Salt environment.

    Default is `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:

    - name (str) -- The name of a single package, or a comma-separated list of packages to install. (no spaces after the commas)

    - refresh (`bool`, optional) --

      Boolean value representing whether or not to refresh the winrepo db.

      Default is `False`.

    - pkgs (`list`, optional) --

      A list of packages to install from a software repository. All packages listed under `pkgs` will be installed via a single command.

      You can specify a version by passing the item as a dict:

      CLI Example:

          # will install the latest version of foo and bar
          salt '*' pkg.install pkgs='["foo", "bar"]'

          # will install the latest version of foo and version 1.2.3 of bar
          salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3"}]'

      Default is `None`.

  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.

  >   Note

  >   Remember that versions that contain a single . will be interpreted as numbers and must be double-quoted. For example, version `3006.10` will be rendered as `3006.1`. To pass `3006.10` you'll need to use double-quotes. `version="'3006.10'"`

  >   CLI Example:

  >   >     # Version is ignored
  >   >     salt '*' pkg.install pkgs="['foo', 'bar']" version=1.2.3

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

  >   Added in version 2016.11.0.

  > force (bool):

  >   If `True`, the installation will run whether the package is already installed or not. If `False`, the installation will not run if the correct version of the package is already installed. Default is `False`.

  >   Added in version 3006.15.

  Returns:

    Return a dict containing the new package names and versions. If the package is already installed, an empty dict is returned.

    If the package is installed by `pkg.install`:

        {'<package>': {'old': '<old-version>',
                       'new': '<new-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.

  Note

  Since this is looking for the latest version available, a refresh_db will be triggered by default. This can take some time. To avoid this set `refresh` to `False`.

  Parameters:

    names (str, list) -- A single name or a list of names to lookup

  Kwargs:

  > saltenv (str): Salt environment. Default `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, list) -- A single name or a list of names to check

  Kwargs:

  > saltenv (str): The salt environment to use. Default is `base`.

  > refresh (bool): Refresh package metadata.

  >   Default is `False`.

  > return_dict_always (bool):

  >   Return a dict when a single package name is queried. Default is `False`.

  > reverse_sort (bool):

  >   Sort the versions for latest to oldest

  >   Added in version 3007.2.

  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, include_components=True, include_updates=True, **kwargs)

  List the packages currently installed.

  Note

  To view installed software as displayed in the Add/Remove Programs, set `include_components` and `include_updates` to False.

  Parameters:

    - versions_as_list (`bool`, optional) --

      Returns the versions as a list.

      Default is `False`.

    - include_components (`bool`, optional) --

      Include sub components of installed software.

      Default is `True`.

    - include_updates (`bool`, optional) --

      Include software updates and Windows updates.

      Default is `True`

  Kwargs:

  > saltenv (str):

  >   The salt environment to use.

  >   Default is `base`.

  > refresh (bool):

  >   Refresh package metadata.

  >   Default is `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_repo_pkgs(*args, saltenv='base', **kwargs)

  Added in version 3007.2.

  This function was added to match a similar function in Linux. It will return all available packages. Optionally, package names (and name globs) can be passed and the results will be filtered to packages matching those names.

  This function can be helpful in discovering the version or repo to specify in a `pkg.installed` state.

  The return data will be a dictionary mapping package names to a list of version numbers, ordered from newest to oldest. For example:

      {
          'bash': ['4.3-14ubuntu1.1',
                   '4.3-14ubuntu1'],
          'nginx': ['1.10.0-0ubuntu0.16.04.4',
                    '1.9.15-0ubuntu1']
      }

  CLI Examples:

      salt '*' pkg.list_repo_pkgs
      salt '*' pkg.list_repo_pkgs foo bar baz

salt.modules.win_pkg.list_upgrades(refresh=True, **kwargs)

  List all available package upgrades on this system

  Parameters:

    refresh (`bool`, optional) -- Refresh package metadata. Default is `True`.

  Kwargs:

  > saltenv (str): Salt environment. Default is `base`

  Returns:

    A dictionary of packages with available upgrades

  Return type:

    dict

  CLI Example:

      salt '*' pkg.list_upgrades

salt.modules.win_pkg.normalize_name(name)

  Nothing to do on Windows. We need this function so that Salt doesn't go through every module looking for `pkg.normalize_name`.

  Added in version 3006.0.

  Parameters:

    name (str) -- The name of the package

  Returns:

    The name of the package

  Return type:

    str

  CLI Example:

      salt '*' pkg.normalize_name git

salt.modules.win_pkg.purge(name=None, pkgs=None, **kwargs)

  Package purges are not supported on Windows, this function is identical to `remove()`.

  Note

  At some point in the future, `pkg.purge` may direct the installer to remove all configs and settings for software packages that support that option.

  Added in version 0.16.0.

  Parameters:

    - name (`str`, optional) --

      The name of the package to be deleted.

      Default is `None`.

    - pkgs (`list`, optional) --

      A list of packages to delete. Must be passed as a python list. The `name` parameter will be ignored if this option is passed.

      Default is `None`.

  Kwargs:

  > version (str):

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

  > saltenv (str): Salt environment.

  > > Default is `base`.

  > refresh (bool): Refresh package metadata.

  >   Default is `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:\ProgramData\Salt Project\Salt\var\cache\salt\minion\files\base\win\repo-ng\winrepo.p`

  This module performs the following steps to generate the software metadata database:

  - Fetch the package definition files (.sls) from winrepo_source_dir (default salt://win/repo-ng) and cache them in <cachedir>files<saltenv><winrepo_source_dir> (default: `C:\ProgramData\Salt Project\Salt\var\cache\salt\minion\files\base\win\repo-ng`)

  - Call `pkg.genrepo` to parse the package definition files and generate the repository metadata database file (winrepo.p)

  - Return the report received from `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

  - Hidden directories (directories beginning with '.', such as '.git') will be ignored.

  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:

  - winrepo_cache_expire_min

  - winrepo_cache_expire_max

  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

  Kwargs:

  > saltenv (str): Salt environment.

  >   Default is `base`.

  > verbose (bool):

  >   Return a verbose data structure which includes 'success_list', a list of all sls files and the package names contained within.

  >   Default is `False`.

  > failhard (bool):

  >   If `True`, an error will be raised if any repo SLS files fail to process. If `False`, no error will be raised, and a dictionary containing the full results will be returned.

  >   Default is `True`.

  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

  Added in version 0.16.0.

  Parameters:

    - name (`str`, optional) --

      The name(s) of the package(s) to be uninstalled. Can be a single package or a comma-delimited list of packages, no spaces.

      Default is `None`.

    - pkgs (`list`, optional) --

      A list of packages to delete. Must be passed as a python list. The `name` parameter will be ignored if this option is passed.

      Default is `None`.

  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 is `base`.

  > refresh (bool): Refresh package metadata.

  > > Default is `False`.

  Returns:

    Returns a dict containing the changes.

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

  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

  Kwargs:

  > saltenv (str): The salt environment to use.

  > > Default is `base`.

  > refresh (bool): Refresh package metadata.

  > > Default is `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 an upgrade is available for a given package

  Parameters:

    name (str) -- The name of a single package

  Kwargs:

  > refresh (bool): Refresh package metadata. Default `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, list) -- A single name or a list of package names to check

  Kwargs:

  > saltenv (str): The salt environment to use. Default `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>