Windows Package Manager¶

Requirements¶

If using the a software definition files hosted on a Git repo, the following libraries are required:

• GitPython 0.3 or later

  or

• pygit2 0.20.3 with libgit 0.20.0 or later

Master Configuration¶

The following are settings are available for configuring the winrepo on the master:

• winrepo_dir

• winrepo_dir_ng

• winrepo_remotes

• winrepo_remotes_ng

• winrepo_branch

• winrepo_provider

• winrepo_ssl_verify

See here for detailed information on all master config options for winrepo.

winrepo_remotes: []

Master Configuration (pygit2)¶

The following configuration options only apply when the winrepo_provider option is set to pygit2.

• winrepo_insecure_auth

• winrepo_passphrase

• winrepo_password

• winrepo_privkey

• winrepo_pubkey

• winrepo_user

Minion Configuration¶

Refreshing the package definitions can take some time, these options were introduced to allow more control of when it occurs. These settings apply to all minions whether in masterless mode or not.

• winrepo_cache_expire_max

• winrepo_cache_expire_min

• winrepo_cachefile

• winrepo_source_dir

Masterless Minion Configuration¶

The following are settings are available for configuring the winrepo on a masterless minion:

• winrepo_dir

• winrepo_dir_ng

• winrepo_remotes

• winrepo_remotes_ng

See here for detailed information on all minion config options for winrepo.

winrepo_remotes: []

Populate the Local Repository¶

The SLS files used to install Windows packages are not distributed by default with Salt. Use the winrepo.update_git_repos runner initialize the repository in the location specified by winrepo_dir_ng in the master config. This will pull the software definition files down from the git repository.

salt-run winrepo.update_git_repos

If running a minion in masterless mode, the same command can be run using salt-call. The repository will be initialized in the location specified by winrepo_dir_ng in the minion config.

salt-call --local winrepo.update_git_repos

These commands will also sync down the legacy repo to maintain backwards compatibility with legacy minions. See Legacy Minions

The legacy repo can be disabled by setting it to an empty list in the master or minion config.

winrepo_remotes: []

Generate the Metadata File (Legacy)¶

This step is only required if you are supporting legacy minions. In current usage the metadata file is generated on the minion in the next step, Update the Minion Database. For legacy minions the metadata file is generated on the master using the winrepo.genrepo runner.

salt-run winrepo.genrepo

Update the Minion Database¶

Run pkg.refresh_db on each of your Windows minions to synchronize the package repository to the minion and build the package database.

# From the master
salt -G 'os:windows' pkg.refresh_db

# From the minion in masterless mode
salt-call --local pkg.refresh_db

The above command returns the following summary denoting the number of packages that succeeded or failed to compile:

local:
    ----------
    failed:
        0
    success:
        301
    total:
        301

List Installed Packages¶

You can get a list of packages installed on the system using pkg.list_pkgs.

# From the master
salt -G 'os:windows' pkg.list_pkgs

# From the minion in masterless mode
salt-call --local pkg.list_pkgs

This will return all software installed on the system whether it is managed by Salt or not as shown below:

local:
    ----------
    Frhed 1.6.0:
        1.6.0
    GNU Privacy Guard:
        2.2.16
    Gpg4win (3.1.9):
        3.1.9
    git:
        2.17.1.2
    nsis:
        3.03
    python3_x64:
        3.7.4150.0
    salt-minion-py3:
        2019.2.3

You can tell by how the software name is displayed which software is managed by Salt and which software is not. When Salt finds a match in the winrepo database it displays the short name as defined in the software definition file. It is usually a single-word, lower-case name. All other software names will be displayed with the full name as they are shown in Add/Remove Programs. So, in the return above, you can see that Git (git), Nullsoft Installer (nsis), Python 3.7 (python3_x64) and Salt (salt-minion-py3) all have a corresponding software definition file. The others do not.

List Available Versions¶

You can query the available version of a package using pkg.list_available and passing the name of the software:

# From the master
salt winminion pkg.list_available firefox_x64

# From the minion in masterless mode
salt-call --local pkg.list_available firefox_x64

The above command will return the following:

winminion:
    - 69.0
    - 69.0.1
    - 69.0.2
    - 69.0.3
    - 70.0
    - 70.0.1
    - 71.0
    - 72.0
    - 72.0.1
    - 72.0.2
    - 73.0
    - 73.0.1
    - 74.0

As you can see, there are many versions of Firefox available for installation. You can refer to a software package by its name or its full_name surrounded by quotes.

Install a Package¶

You can install a package using pkg.install:

# From the master
salt winminion pkg.install 'firefox_x64'

# From the minion in masterless mode
salt-call --local pkg.install "firefox_x64"

The above will install the latest version of Firefox.

# From the master
salt winminion pkg.install 'firefox_x64' version=74.0

# From the minion in masterless mode
salt-call --local pkg.install "firefox_x64" version=74.0

The above will install version 74.0 of Firefox.

If a different version of the package is already installed it will be replaced with the version in the winrepo (only if the package itself supports live updating).

You can also specify the full name:

# From the master
salt winminion pkg.install 'Mozilla Firefox 17.0.1 (x86 en-US)'

# From the minion in masterless mode
salt-call --local pkg.install "Mozilla Firefox 17.0.1 (x86 en-US)"

Remove a Package¶

You can uninstall a package using pkg.remove:

# From the master
salt winminion pkg.remove firefox_x64

# From the minion in masterless mode
salt-call --local pkg.remove firefox_x64

Directory Structure and Naming¶

The files are stored in the location designated by the winrepo_dir_ng setting. All files in this directory that have a .sls file extension are considered software definition files. The files are evaluated to create the metadata file on the minion.

You can maintain standalone software definition files that point to software on other servers or on the internet. In this case the file name would be the short name of the software with the .sls extension, ie firefox.sls.

You can also store the binaries for your software together with their software definition files in their own directory. In this scenario, the directory name would be the short name for the software and the software definition file would be inside that directory and named init.sls.

Look at the following example directory structure on a Linux master assuming default config settings:

srv/
|---salt/
|   |---win/
|   |   |---repo-ng/
|   |   |   |---custom_defs/
|   |   |   |   |---ms_office_2013_x64/
|   |   |   |   |   |---access.en-us/
|   |   |   |   |   |---excel.en-us/
|   |   |   |   |   |---outlook.en-us/
|   |   |   |   |   |---powerpoint.en-us/
|   |   |   |   |   |---word.en-us/
|   |   |   |   |   |---init.sls
|   |   |   |   |   |---setup.dll
|   |   |   |   |   |---setup.exe
|   |   |   |   |---openssl.sls
|   |   |   |   |---zoom.sls
|   |   |   |---salt-winrepo-ng/
|   |   |   |   |---auditbeat/
|   |   |   |   |   |---init.sls
|   |   |   |   |   |---install.cmd
|   |   |   |   |   |---install.ps1
|   |   |   |   |   |---remove.cmd
|   |   |   |   |---gpg4win/
|   |   |   |   |   |---init.sls
|   |   |   |   |   |---silent.ini
|   |   |   |   |---7zip.sls
|   |   |   |   |---adobereader.sls
|   |   |   |   |---audacity.sls
|   |   |   |   |---ccleaner.sls
|   |   |   |   |---chrome.sls
|   |   |   |   |---firefox.sls

In the above directory structure, the user has created the custom_defs directory in which to store their custom software definition files. In that directory you see a folder for MS Office 2013 that contains all the installer files along with a software definition file named init.sls. The user has also created two more standalone software definition files; openssl.sls and zoom.sls.

The salt-winrepo-ng directory is created by the winrepo.update_git_repos command. This folder contains the clone of the git repo designated by the winrepo_remotes_ng config setting.

Writing Software Definition Files¶

A basic software definition file is really easy to write if you already know some basic things about your software:

• The full name as shown in Add/Remove Programs

• The exact version number as shown in Add/Remove Programs

• How to install your software silently from the command line

The software definition file itself is just a data structure written in YAML. The top level item is a short name that Salt will use to reference the software. There can be only one short name in the file and it must be unique across all software definition files in the repo. This is the name that will be used to install/remove the software. It is also the name that will appear when Salt finds a match in the repo when running pkg.list_pkgs.

The next indentation level is the version number. There can be many of these, but they must be unique within the file. This is also displayed in pkg.list_pkgs.

The last indentation level contains the information Salt needs to actually install the software. Available parameters are:

• full_name : The full name as displayed in Add/Remove Programs

• installer : The location of the installer binary

• install_flags : The flags required to install silently

• uninstaller : The location of the uninstaller binary

• uninstall_flags : The flags required to uninstall silently

• msiexec : Use msiexec to install this package

• allusers : If this is an MSI, install to all users

• cache_dir : Cache the entire directory in the installer URL if it starts with salt://

• cache_file : Cache a single file in the installer URL if it starts with salt://

• use_scheduler : Launch the installer using the task scheduler

• source_hash : The hash sum for the installer

Usage of these parameters is demonstrated in the following examples and discussed in more detail below. To understand these examples you'll need a basic understanding of Jinja. The following links have some basic tips and best practices for working with Jinja in Salt:

Understanding Jinja

Jinja

Example: Basic¶

Take a look at this basic, pure YAML example for a software definition file for Firefox:

firefox_x64:
  '74.0':
    full_name: Mozilla Firefox 74.0 (x64 en-US)
    installer: 'https://download-installer.cdn.mozilla.net/pub/firefox/releases/74.0/win64/en-US/Firefox%20Setup%2074.0.exe'
    install_flags: '/S'
    uninstaller: '%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe'
    uninstall_flags: '/S'
  '73.0.1':
    full_name: Mozilla Firefox 73.0.1 (x64 en-US)
    installer: 'https://download-installer.cdn.mozilla.net/pub/firefox/releases/73.0.1/win64/en-US/Firefox%20Setup%2073.0.1.exe'
    install_flags: '/S'
    uninstaller: '%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe'
    uninstall_flags: '/S'

You can see the first item is the short name for the software, in this case firefox_x64. It is the first line in the definition. The next line is indented two spaces and contains the software version. The lines following the version are indented two more spaces and contain all the information needed to install the Firefox package.

As you can see in the example above, a software definition file can define multiple versions for the same piece of software. These are denoted by putting the next version number at the same indentation level as the first with its software definition information indented below it.

Example: Jinja¶

When there are tens or hundreds of versions available for a piece of software definition file can become quite large. This is a scenario where Jinja can be helpful. Consider the following software definition file for Firefox using Jinja:

{%- set lang = salt['config.get']('firefox:pkg:lang', 'en-US') %}

firefox_x64:
  {% for version in ['74.0',
                     '73.0.1', '73.0',
                     '72.0.2', '72.0.1', '72.0',
                     '71.0', '70.0.1', '70.0',
                     '69.0.3', '69.0.2', '69.0.1'] %}
  '{{ version }}':
    full_name: 'Mozilla Firefox {{ version }} (x64 {{ lang }})'
    installer: 'https://download-installer.cdn.mozilla.net/pub/firefox/releases/{{ version }}/win64/{{ lang }}/Firefox%20Setup%20{{ version }}.exe'
    install_flags: '/S'
    uninstaller: '%ProgramFiles%\Mozilla Firefox\uninstall\helper.exe'
    uninstall_flags: '/S'
  {% endfor %}

In this example we are able to generate a software definition file that defines how to install 12 versions of Firefox. We use Jinja to create a list of available versions. That list is in a for loop where each version is placed in the version variable. The version is inserted everywhere there is a {{ version }} marker inside the for loop.

You'll notice that there is a single variable (lang) defined at the top of the software definition. Because these files are going through the Salt renderer many Salt modules are exposed via the salt keyword. In this case it is calling the config.get function to get a language setting that can be placed in the minion config. If it is not there, it defaults to en-US.

Example: Latest¶

There are some software vendors that do not provide access to all versions of their software. Instead they provide a single URL to what is always the latest version. In some cases the software keeps itself up to date. One example of this is the Google Chrome web browser.

Chrome

To handle situations such as these, set the version to latest. Here's an example:

chrome:
  latest:
    full_name: 'Google Chrome'
    installer: 'https://dl.google.com/edgedl/chrome/install/GoogleChromeStandaloneEnterprise.msi'
    install_flags: '/qn /norestart'
    uninstaller: 'https://dl.google.com/edgedl/chrome/install/GoogleChromeStandaloneEnterprise.msi'
    uninstall_flags: '/qn /norestart'
    msiexec: True

The above example shows us two things. First it demonstrates the usage of latest as the version. In this case Salt will install the version of Chrome at the URL and report that version.

The second thing to note is that this is installing software using an MSI. You can see that msiexec is set to True.

Example: MSI Patch¶

When the msiexec parameter is set to True it uses the /i option for installs and the /x option for uninstalls. This is problematic when trying to install an MSI patch which requires the /p option. You can't combine the /i and /p options. So how do you apply a patch to installed software in winrepo using an .msp file?

One wiley contributor came up with the following solution to this problem by using the %cd% environment variable. Consider the following software definition file:

MyApp:
  '1.0':
    full_name: MyApp
    installer: 'salt://win/repo-ng/MyApp/MyApp.1.0.msi'
    install_flags: '/qn /norestart'
    uninstaller: '{B5B5868F-23BA-297A-917D-0DF345TF5764}'
    uninstall_flags: '/qn /norestart'
    msiexec: True
  '1.1':
    full_name: MyApp
    installer: 'salt://win/repo-ng/MyApp/MyApp.1.0.msi'
    install_flags: '/qn /norestart /update "%cd%\\MyApp.1.1.msp" '
    uninstaller: '{B5B5868F-23BA-297A-917D-0DF345TF5764}'
    uninstall_flags: '/qn /norestart'
    msiexec: True
    cache_file: salt://win/repo/MyApp/MyApp.1.1.msp

There are a few things to note about this software definition file. First, is the solution we are trying to solve, that of applying a patch. Version 1.0 just installs the application using the 1.0 MSI defined in the installer parameter. There is nothing special in the install_flags and nothing is cached.

Version 1.1 uses the same installer, but uses the cache_file option to specify a single file to cache. In order for this to work the MSP file needs to be in the same directory as the MSI file on the file_roots.

The final step to getting this to work is to add the additional /update flag to the install_flags parameter. Add the path to the MSP file using the %cd% environment variable. %cd% resolves to the current working directory which is the location in the minion cache where the installer file is cached.

See issue #32780 for more details.

This same approach could be used for applying MST files for MSIs and answer files for other types of .exe based installers.

Parameters¶

These are the parameters that can be used to generate a software definition file. These parameters are all placed under the version in the software definition file:

Example usage can be found on the github repo

salt 'test-2008' pkg.list_pkgs
test-2008
    ----------
    7-Zip 9.20 (x64 edition):
        9.20.00.0
    Mozilla Firefox 74.0 (x64 en-US)
        74.0
    Mozilla Maintenance Service:
        74.0
    salt-minion-py3:
        3001

test-2008:
    ----------
    7zip:
        9.20.00.0
    Mozilla Maintenance Service:
        74.0
    firefox_x64:
        74.0
    salt-minion-py3:
        3001

7zip:
  '9.20.00.0':
    full_name: 7-Zip 9.20 (x64 edition)
    installer: salt://win/repo-ng/7zip/7z920-x64.msi
    install_flags: '/qn /norestart'
    uninstaller: '{23170F69-40C1-2702-0920-000001000000}'
    uninstall_flags: '/qn /norestart'
    msiexec: True

7zip:
  '9.20.00.0':
    full_name: 7-Zip 9.20 (x64 edition)
    installer: salt://win/repo-ng/7zip/7z920-x64.msi
    install_flags: '/qn /norestart'
    uninstaller: salt://win/repo-ng/7zip/7z920-x64.msi
    uninstall_flags: '/qn /norestart'
    msiexec: True

7zip:
  '9.20.00.0':
    full_name: 7-Zip 9.20 (x64 edition)
    installer: salt://win/repo/7zip/7z920-x64.msi
    install_flags: '/qn /norestart'
    uninstaller: salt://win/repo/7zip/7z920-x64.msi
    uninstall_flags: '/qn /norestart'
    msiexec: 'C:\Windows\System32\msiexec.exe'

sqlexpress:
  '12.0.2000.8':
    full_name: Microsoft SQL Server 2014 Setup (English)
    installer: 'salt://win/repo/sqlexpress/setup.exe'
    install_flags: '/ACTION=install /IACCEPTSQLSERVERLICENSETERMS /Q'
    cache_dir: True

messageanalyzer:
  '4.0.7551.0':
    full_name: 'Microsoft Message Analyzer'
    installer: 'salt://win/repo/messageanalyzer/MessageAnalyzer64.msi'
    install_flags: '/quiet /norestart'
    uninstaller: '{1CC02C23-8FCD-487E-860C-311EC0A0C933}'
    uninstall_flags: '/quiet /norestart'
    msiexec: True
    source_hash: 'sha1=62875ff451f13b10a8ff988f2943e76a4735d3d4'

My software installs correctly but pkg.installed says it failed¶

If you have a package that seems to install properly, but Salt reports a failure then it is likely you have a version or full_name mismatch.

Check the exact full_name and version as shown in Add/Remove Programs (appwiz.cpl). Use pkg.list_pkgs to check that the full_name and version exactly match what is installed. Make sure the software definition file has the exact value for full_name and that the version matches exactly.

Also, make sure the version is wrapped in single quotes in the software definition file.

Changes to sls files not being picked up¶

You may have recently updated some of the software definition files on the repo. Ensure you have refreshed the database on the minion.

salt winminion pkg.refresh_db

How Success and Failure are Reported by pkg.installed¶

The install state/module function of the Windows package manager works roughly as follows:

1. Execute pkg.list_pkgs to get a list of software currently on the machine

2. Compare the requested version with the installed version

3. If versions are the same, report no changes needed

4. Install the software as described in the software definition file

5. Execute pkg.list_pkgs to get a new list of software currently on the machine

6. Compare the requested version with the new installed version

7. If versions are the same, report success

8. If versions are different, report failure

Winrepo Upgrade Issues¶

To minimize potential issues, it is a good idea to remove any winrepo git repositories that were checked out by the legacy (pre-2015.8.0) winrepo code when upgrading the master to 2015.8.0 or later. Run winrepo.update_git_repos to clone them anew after the master is started.

Legacy Configuration¶

Winrepo settings were changed with the introduction of the Next Generation (ng) of winrepo.

Legacy Quick Start¶

You can get up and running with winrepo pretty quickly just using the defaults. Assuming no changes to the default configuration (ie, file_roots) run the following commands on the master:

salt-run winrepo.update_git_repos
salt-run winrepo.genrepo
salt * pkg.refresh_db
salt * pkg.install firefox

These commands clone the default winrepo from github, generate the metadata file, push the metadata file down to the legacy minion, and install the latest version of Firefox.

Legacy Initialization¶

Initializing the winrepo for a legacy minion is similar to that for a newer minion. There is an added step in that the metadata file needs to be generated on the master prior to refreshing the database on the minion.

salt-run winrepo.update_git_repos

salt-run winrepo.genrepo

# From the master
salt -G 'os:windows' pkg.refresh_db

Changes in Version 2015.8.0+¶

Git repository management for the Windows Software Repository changed in version 2015.8.0, and several master/minion config parameters were renamed for consistency.

For a complete list of the new winrepo config options, see here for master config options, and here for configuration options for masterless Windows minions.