winstall

Table of Contents

1. Description
2. Usage
3. Facts
4. Limitations
5. Development

Description

This Puppet module enables installing Windows packages from different sources, allowing installation directly from a URL in addition to local or UNC paths. The module accepts a hash of 'products' that defines the applications to be installed and iterates through them using the 'winstall::product' defined type.

When a URL is used as the source, a copy of the source is downloaded to a temp file, installed, and the downloaded installer is deleted.

Usage

Including the module in an environment does nothing by default. You must invoke the class with a products hash, define winstall::products in hiera, or use the defined type winstall::product directly in a manifest to manage Windows software products.

Controlling versions and upgrades depends on whether or not the package contains a proper version attribute. See the Puppet documentation for more details on using package resources on Windows.

Generally, to install an exact version, the ensure parameter of the product defined type should be set to the target version. To just make sure the product is installed, but perhaps allow clients to upgrade versions beyond the initially assigned package, set the value of ensure to 'installed'.

This hiera example data would install 7-Zip on the targeted node:

winstall::products:
  '7-Zip 19.00 (x64)':
    ensure: 'installed'
    source: 'https://www.7-zip.org/a/7z1900-x64.msi'
    install_options:
      - '/S'

This example is a hiera based role I assign to Windows 10 clients used for development. The role installs several products from packages, ensures OneDrive is removed, installs PowerCLI PowerShell modules, and sets GIT_SSH as a global environment variable so Visual Studio Code can use SSH keys loaded into the PuTTY agent.

---
# Windows 10 dev tools - Requires the following modules in the environment
#----(Puppetfile format)-------------
# mod 'puppetlabs/pwshlib', :latest
# mod 'puppetlabs-powershell', :latest
# mod 'puppetlabs-registry', :latest
# mod 'puppet/archive', :latest
# mod 'southalc/types', :latest
# mod 'southalc/winstall', :latest
#------------------------------------

classes:
  - types
  - winstall

types::types:
  - registry_key
  - registry_value

winstall::products:
  'Microsoft OneDrive':
    ensure: absent
    source: '%WINDIR%\WinSxS\wow64_microsoft-windows-onedrive-setup_*\OneDriveSetup.exe'
  '7-Zip 19.00 (x64)':
    ensure: installed
    source: 'https://my.local.server/pub/software/7z1900-x64.exe'
    install_options:
      - '/S'
  'VMware Remote Console':
    ensure: installed
    source: 'https://my.local.server/pub/software/VMware-VMRC-12.0.1-18113358.exe'
    install_options:
      - '/s'
      - '/v'
      - '/qn'
      - 'EULAS_AGREED=1'
      - 'AUTOSOFTWAREUPDATE=1'
      - 'DATACOLLECTION=0'
  'PuTTY release 0.76 (64-bit)':
    ensure: installed
    source: 'https://the.earth.li/~sgtatham/putty/latest/w64/putty-64bit-0.76-installer.msi'
    install_options:
      - '/qn'
  'Git':
    ensure: '2.33.1'
    source: 'https://github.com/git-for-windows/git/releases/download/v2.33.1.windows.1/Git-2.33.1-64-bit.exe'
    install_options:
      - '/VERYSILENT'
      - '/NORESTART'
  'Microsoft Visual Studio Code':
    ensure: installed
    source: 'https://my.local.server/pub/software/VSCodeSetup-x64-1.47.2.exe'
    install_options:
      - '/VERYSILENT'
      - '/NORESTART'
      - '/MERGETASKS=!runcode'


types::exec:
  install_powerCLI:
    provider: 'powershell'
    command: |
      [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
      Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
      Set-PSRepository -Name 'PSGallery' -InstallationPolicy Trusted
      Install-Module -Name VMware.PowerCLI -Confirm:$false
      Set-PSRepository -Name 'PSGallery' -InstallationPolicy Untrusted
    unless: Get-InstalledModule VMware.PowerCLI -ErrorAction Stop
    require:
      - 'Registry_value[HKLM\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell\ExecutionPolicy]'
  install_powershell_PackageManagement:
    provider: 'powershell'
    command: |
      [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
      Install-Module -Name PackageManagement -Force -MinimumVersion 1.4.6 -Scope AllUsers -AllowClobber
    unless: (Get-InstalledModule -Name PackageManagement -ErrorAction Stop).Version -ge 1.4.6


# Ensure keys exist before trying to manage values
types::registry_key:
  'HKLM\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell':
    ensure: present
  'HKLM\SOFTWARE\Policies\Microsoft\Windows\OneDrive':
    ensure: present

types::registry_value:
  # Enable Visual Studio code to use SSH keys loaded into pageant
  'HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\GIT_SSH':
    ensure: present
    type: string
    data: 'C:\Program Files\PuTTY\plink.exe'
  # Globally manage PowerShell execution policy
  'HKLM\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell\ExecutionPolicy':
    ensure: present
    type: string
    data: RemoteSigned
    require:
      - 'Registry_key[HKLM\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell]'
  # Disables OneDrive
  'HKLM\SOFTWARE\Policies\Microsoft\Windows\OneDrive\DisableFileSyncNGSC':
    ensure: present
    type: string
    data: '1'
    require:
      - 'Registry_key[HKLM\SOFTWARE\Policies\Microsoft\Windows\OneDrive]'

Facts

When installing packages from a URL, we need to have an inventory of installed software in order to determine if an assigned package should be downloaded and installed. The module includes the custom fact products that abuses the native Puppet provider to return a hash of installed software products with the current version. This fact is similar to what is returned by running puppet resource package.

Limitations

This module is for Windows only, and should work with all Windows versions. The archive module is requied when using URLs as the source for a product.

Development

To contribute, fork the source and submit a pull request.

Reference

Table of Contents

Classes

• winstall: A class for installing Windows packages from various sources

Defined types

• winstall::product: A defined type for installing Windows software products

Classes

winstall

Enables installation of Windows software products from local, UNC (MSI packages only), or URL paths. When a URL is used, a local copy is downloaded, installed, and the installer file deleted.

Examples

include winstall

Parameters

The following parameters are available in the winstall class.

products

Data type: Hash

Hash A hash of products to be installed. See the products defined type documentation.

Default value: {}

Defined types

winstall::product

Enable Windows software installation from local, network, or URL sources. When using this defined type, ensure the resource title matches the DisplayName of the product being installed to prevent Windows from re-installing with every Puppet run.

Ref: https://puppet.com/docs/puppet/latest/resources_package_windows.html

Examples

Install 7-zip, where the version is included in the title

winstall::product { '7-Zip 19.00 (x64)':
  ensure          => 'installed',
  source          => 'https://www.7-zip.org/a/7z1900-x64.msi',
  install_options => ['/qn'],
}

Parameters

The following parameters are available in the winstall::product defined type.

ensure

Data type: String

String Valid options are installed, absent, or <version> that represents the specific version of the product that must be installed.

Default value: 'installed'

source

Data type: String

String Source path to the installation package. This can be a local or network drive, a UNC path for MSI packages, or a URL to the package file. When the source to be installed is a URL it will be downloaded to a a temporary file, installed, and the temporary file removed.

tmp_file

Data type: String

String Optional temporary file for staging installer files when the source is a URL without a "friendly" file name. By default, the source URL is split on the forward slash and the last segment is used as the temp file.

Default value: ''

tmp_dir

Data type: String

String Optional temporary directory for staging installer files when the source is a URL. If defined, the directory must already exist.

Default value: ''

install_options

Data type: Array

Array Optional array of command arguments to be used by the installer. These are often unique per application.

Default value: []

uninstall_options

Data type: Array

Array Optional array of command arguments to be used by the uninstaller. These are often unique per application.

Default value: []

Changelog

Release 0.1.2

• Replace if conditions with selector expressions in 'winstall::product'
• Bugfix: Use $tmp_dir when a value is supplied in 'winstall::product'

Release 0.1.1

• Remove 7zip from module hiera.
• Set hiera lookup merge strategy to deep for "winstall::products"
• Do not loop over the products hash unless the OS kernel is "windows"

Release 0.1.0

• Initial release