search

puppetlabs / puppetlabs-chocolatey

Chocolatey Package Provider for Puppet
Apache License 2.0
19 stars 68 forks source link
hacktoberfest module supported

readme

chocolatey

Chocolatey for Business Now Available!

We're excited for you to learn more about what's available in the Business editions!

Table of Contents

  1. Overview
  2. Module Description - What the chocolatey module does and why it is useful
  3. Setup - The basics of getting started with chocolatey
  4. Usage - Configuration options and additional functionality
  5. Reference
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module
  8. License
  9. Attributions

Overview

This is a Puppet package provider for Chocolatey, which is like apt-get, but for Windows. Check the module's metadata.json for compatible Puppet and Puppet Enterprise versions.

Module Description

This is the official module for working with the Chocolatey package manager. There are two versions available:

This module supports all editions of Chocolatey, including FOSS, Professional and Chocolatey for Business.

This module is able to:

Why Chocolatey

Chocolatey closely mimics how package managers on other operating systems work. If you can imagine the built-in provider for Windows versus Chocolatey, take a look at the use case of installing git:

# Using built-in provider
package { "Git version 1.8.4-preview20130916":
  ensure    => installed,
  source    => 'C:\temp\Git-1.8.4-preview20130916.exe',
  install_options => ['/VERYSILENT']
}
# Using Chocolatey (set as default for Windows)
package { 'git':
  ensure   => latest,
}

With the built-in provider:

With Chocolatey's provider:

For reference, read about the provider features available from the built-in provider, compared to other package managers:

Provider holdable install options installable package settings purgeable reinstallable uninstall options uninstallable upgradeable versionable virtual packages
Windows x x x x x
Chocolatey x x x x x x x
apt x x x x x x x
yum x x x x x x x

Setup

What Chocolatey affects

Chocolatey affects your system and what software is installed on it, ranging from tools and portable software, to natively installed applications.

Setup Requirements

Chocolatey requires the following components:

Beginning with Chocolatey provider

Install this module via any of these approaches:

Usage

Manage Chocolatey installation

Ensure Chocolatey is installed and configured:

include chocolatey

Override default Chocolatey install location

class {'chocolatey':
  choco_install_location => 'D:\secured\choco',
}

NOTE: This will affect suitability on first install. There are also special considerations for C:\Chocolatey as an install location, see choco_install_location for details.

Use an internal chocolatey.nupkg for Chocolatey installation

class {'chocolatey':
  chocolatey_download_url         => 'https://internalurl/to/chocolatey.nupkg',
  use_7zip                        => false,
  choco_install_timeout_seconds   => 2700,
}

Use a file chocolatey.0.9.9.9.nupkg for installation

class {'chocolatey':
  chocolatey_download_url         => 'file:///c:/location/of/chocolatey.0.9.9.9.nupkg',
  use_7zip                        => false,
  choco_install_timeout_seconds   => 2700,
}

Specify the version of chocolatey by class parameters

class {'chocolatey':
  chocolatey_download_url         => 'file:///c:/location/of/chocolatey.0.9.9.9.nupkg',
  use_7zip                        => false,
  choco_install_timeout_seconds   => 2700,
  chocolatey_version              => '0.9.9.9',
}

Log chocolatey bootstrap installer script output

class {'chocolatey':
  log_output              => true,
}

Install chocolatey using a proxy server

class {'chocolatey':
  install_proxy => 'http://proxy.megacorp.com:3128',
}

Configuration

If you have Chocolatey 0.9.9.x or above, you can take advantage of configuring different aspects of Chocolatey.

Sources Configuration

You can specify sources that Chocolatey uses by default, along with priority.

Requires Chocolatey v0.9.9.0+.

Disable the default community repository source
chocolateysource {'chocolatey':
  ensure => disabled,
}
Set a priority on a source
chocolateysource {'chocolatey':
  ensure   => present,
  location => 'https://chocolatey.org/api/v2',
  priority => 1,
}
Add credentials to a source
chocolateysource {'sourcename':
  ensure   => present,
  location => 'https://internal/source',
  user     => 'username',
  password => 'password',
}

NOTE: Chocolatey encrypts the password in a way that is not verifiable. If you need to rotate passwords, you cannot use this resource to do so unless you also change the location, user, or priority (because those are ensurable properties).

NOTE: The sensitive password can be deferred using the Deferred function on Puppet Master and enable to execute on agent.

chocolateysource {'sourcename':
  ensure   => present,
  location => 'https://internal/source',
  user     => 'username',
  password => Deferred('sprintf', ['password']),
}

Features Configuration

You can configure features that Chocolatey has available. Run choco feature list to see the available configuration features.

Requires Chocolatey v0.9.9.0+.

Enable Auto Uninstaller

Uninstall from Programs and Features without requiring an explicit uninstall script.

chocolateyfeature {'autouninstaller':
  ensure => enabled,
}
Disable Use Package Exit Codes

Requires 0.9.10+ for this feature.

Use Package Exit Codes - Allows package scripts to provide exit codes. With this enabled, Chocolatey uses package exit codes for exit when non-zero (this value can come from a dependency package). Chocolatey defines valid exit codes as 0, 1605, 1614, 1641, 3010. With this feature disabled, Chocolatey exits with a 0 or a 1 (matching previous behavior).

Note that this behavior may cause Puppet to think that the run has failed. We advise that you leave this at the default setting or disable it. Do not enable it.

chocolateyfeature {'usepackageexitcodes':
  ensure => disabled,
}
Enable Virus Check

Requires 0.9.10+ and Chocolatey Pro / Business for this feature.

Virus Check - Performs virus checking on downloaded files. (Licensed versions only.)

chocolateyfeature {'viruscheck':
  ensure => enabled,
}
Enable FIPS Compliant Checksums

Requires 0.9.10+ for this feature.

Use FIPS Compliant Checksums - Ensures checksumming done by Chocolatey uses FIPS compliant algorithms. Not recommended unless required by FIPS Mode. Enabling on an existing installation could have unintended consequences related to upgrades or uninstalls.

chocolateyfeature {'usefipscompliantchecksums':
  ensure => enabled,
}

Config configuration

You can configure config values that Chocolatey has available. Run choco config list to see the config settings available (just the config settings section).

Requires Chocolatey v0.9.10.0+.

Set cache location

The cache location defaults to the TEMP directory. You can set an explicit directory to cache downloads to instead of the default.

chocolateyconfig {'cachelocation':
  value  => "c:\\downloads",
}
Unset cache location

Removes cache location setting, returning the setting to its default.

chocolateyconfig {'cachelocation':
  ensure => absent,
}
Use an explicit proxy

When using Chocolatey behind a proxy, set proxy and optionally proxyUser and proxyPassword.

NOTE: The proxyPassword value is not verifiable.

chocolateyconfig {'proxy':
  value  => 'https://someproxy.com',
}

chocolateyconfig {'proxyUser':
  value  => 'bob',
}

# not verifiable
chocolateyconfig {'proxyPassword':
  value  => 'securepassword',
}

NOTE: The sensitive value can be deferred using the Deferred function on Puppet Master and enable to execute on agent.

chocolateyconfig {'proxyPassword':
  value  => Deferred('sprintf', ['securepassword']),
}

Set Chocolatey as Default Windows Provider

If you want to set this provider as the site-wide default, add to your site.pp:

if $::kernel == 'windows' {
  Package { provider => chocolatey, }
}

# OR

case $operatingsystem {
  'windows': {
    Package { provider => chocolatey, }
  }
}

Packages

With all options

package { 'notepadplusplus':
  ensure            => installed|latest|'1.0.0'|'>=1.0 <2.0'|absent,
  provider          => 'chocolatey',
  install_options   => ['-pre','-params','"','param1','param2','"'],
  uninstall_options => ['-r'],
  source            => 'https://myfeed.example.com/api/v2',
  package_settings  => { 'verbose' => true, 'log_output' => true, },
}

Simple install

package { 'notepadplusplus':
  ensure   => installed,
  provider => 'chocolatey',
}

To always ensure using the newest version available

package { 'notepadplusplus':
  ensure   => latest,
  provider => 'chocolatey',
}

To ensure a specific version

package { 'notepadplusplus':
  ensure   => '6.7.5',
  provider => 'chocolatey',
}

To ensure a version range

package { 'notepadplusplus':
  ensure   => '>=6.7.5 <7.0',
  provider => 'chocolatey',
}

To specify custom source

package { 'notepadplusplus':
  ensure   => '6.7.5',
  provider => 'chocolatey',
  source   => 'C:\local\folder\packages',
}
package { 'notepadplusplus':
  ensure   => '6.7.5',
  provider => 'chocolatey',
  source   => '\\unc\source\packages',
}
package { 'notepadplusplus':
  ensure   => '6.7.5',
  provider => 'chocolatey',
  source   => 'https://custom.nuget.odata.feed/api/v2/',
}
package { 'notepadplusplus':
  ensure   => '6.7.5',
  provider => 'chocolatey',
  source   => 'C:\local\folder\packages;https://chocolatey.org/api/v2/',
}

Install options with spaces

Spaces in arguments must always be covered with a separation. Shown below is an example of how you configure -installArgs "/VERYSILENT /NORESTART".

package {'launchy':
  ensure          => installed,
  provider        => 'chocolatey',
  install_options => ['-override', '-installArgs', '"', '/VERYSILENT', '/NORESTART', '"'],
}

Install options with quotes or spaces

The underlying installer may need quotes passed to it. This is possible, but not as intuitive. The example below covers passing /INSTALLDIR="C:\Program Files\somewhere".

For this to be passed through with Chocolatey, you need a set of double quotes surrounding the argument and two sets of double quotes surrounding the item that must be quoted (see how to pass/options/switches). This makes the string look like -installArgs "/INSTALLDIR=""C:\Program Files\somewhere""" for proper use with Chocolatey.

Then, for Puppet to handle that appropriately, you must split on every space. Yes, on every space you must split the string or the result comes out incorrectly. This means it will look like the following:

install_options => ['-installArgs',
  '"/INSTALLDIR=""C:\Program', 'Files\somewhere"""']

Make sure you have all of the right quotes - start it off with a single double quote, then two double quotes, then close it all by closing the two double quotes and then the single double quote or a possible three double quotes at the end.

package {'mysql':
  ensure          => latest,
  provider        => 'chocolatey',
  install_options => ['-override', '-installArgs',
    '"/INSTALLDIR=""C:\Program', 'Files\somewhere"""'],
}

You can split it up a bit for readability if it suits you:

package {'mysql':
  ensure          => latest,
  provider        => 'chocolatey',
  install_options => ['-override', '-installArgs', '"'
    '/INSTALLDIR=""C:\Program', 'Files\somewhere""',
    '"'],
}

Note: The above is for Chocolatey v0.9.9+. You may need to look for an alternative method to pass args if you have 0.9.8.x and below.

A warning about secrets in install_options

There is no guarantee that secrets in install_options will not show up in debug runs of either puppet agent or puppet apply calls.

This is another reason to not set your production runs to debug mode.

However, this information is not written to puppetdb or any other Puppet logs.

It is written to the Chocolatey log on each machine unless you have C4B and use the --package-parameters-sensitive or --install-arguments-sensitive Chocolatey parameters, which will redact specified values from the Chocolatey log.

For more information on these Chocolatey parameters, see the Chocolatey reference documentation on the install command and the upgrade command.

If you need to include a secret in your install_options, do not run in debug mode in production and use C4B and the --package-parameters-sensitive or --install-arguments-sensitive Chocolatey parameter.

Passing Flags With Package Settings

You can pass flags to the chocolatey provider using package_settings. You might want to do this in a default:

    Package {
      package_settings => { 'verbose' => true, 'log_output' => true, },
    }

Reference

For information on classes and types, see REFERENCE.md. For information on facts, see below.

Facts

Limitations

Known Issues

License

This codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of AGPL, BSD-2, BSD-3, GPL2.0, LGPL, MIT and MPL Licensing.

Development

Acceptance tests for this module leverage puppet_litmus. To run the acceptance tests follow the instructions here. You can also find a tutorial and walkthrough of using Litmus and the PDK on YouTube.

If you run into an issue with this module, or if you would like to request a feature, please file a ticket. Every Monday the Puppet IA Content Team has office hours in the Puppet Community Slack, alternating between an EMEA friendly time (1300 UTC) and an Americas friendly time (0900 Pacific, 1700 UTC).

If you have problems getting this module up and running, please contact Support.

If you submit a change to this module, be sure to regenerate the reference documentation as follows:

puppet strings generate --format markdown --out REFERENCE.md

Attributions

A special thanks goes out to Rich Siegel and Rob Reynolds who wrote the original provider and continue to contribute to the development of this provider.