Version information
This version is compatible with:
- Puppet Enterprise >= 2.7.0 < 2016.4.0
- Puppet >= 2.7.0 < 5.0.0
This module has been deprecated by its author since Feb 19th 2020.
The author has suggested puppetlabs-chocolatey as its replacement.
Start using this module
Documentation
Chocolatey Package Provider for Puppet
Chocolatey for Business Now Available!
We're excited for you to learn more about what's available in the Business editions!
Build Status
Travis | AppVeyor |
---|---|
Table of Contents
- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with chocolatey
- Usage - Configuration options and additional functionality
- Reference
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
- Attributions
Overview
This is a Puppet package provider for chocolatey, which is like apt-get, but for Windows. This should be compatible with a wide range of Puppet versions.
Module Description
This is the official module for working with the Chocolatey package manager.
This module supports all editions of Chocolatey, including FOSS, Professional and Chocolatey for Business.
This module will ultimately be able to
- install Chocolatey
- work with custom location installations
- configure Chocolatey
- use Chocolatey as a package provider
Why Chocolatey
Chocolatey is a nicer abstraction because it nearly mimics how package managers on other operating systems work. If you can imagine the built in provider for Windows versus Chocolatey, let's 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,
}
The built-in provider has the following needs:
- Package name must match exactly the name from installed programs. See package name must be DisplayName
- Package name has issues with unicode characters
- Source must point to the location of the executable installer. See source is required.
- No
ensure => latest
- see handling versions and upgrades
Chocolatey's provider on the other hand:
- Package name only has to match the name of the package, which can be whatever you choose.
- The package is a nice abstraction
- Package knows how to install the software silently
- Package knows where to get the executable installer
- Source is free to specify different Chocolatey feeds
- Chocolatey makes
package
more platform agnostic since it looks exactly like other platforms.
For reference, let's take a look at the provider features available as compared to the built-in provider and some other package managers:
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
- Powershell v2+
- intalled on most systems by default
- .NET Framework v4+
Beginning with Chocolatey provider
Install this module via any of these approaches:
- puppet forge
- git-submodule (tutorial)
- librarian-puppet
- r10k
Usage
Ensure Chocolatey is install and configured:
include chocolatey
Override default Chocolatey install location
class {'chocolatey':
choco_install_location => 'D:\secured\choco',
}
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,
}
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, }
}
}
With All Options
package { 'notepadplusplus':
ensure => installed|latest|'1.0.0'|absent,
provider => 'chocolatey',
install_options => ['-pre','-params','"','param1','param2','"'],
uninstall_options => ['-r'],
source => 'https://myfeed.example.com/api/v2',
}
- supports
installable
anduninstallable
- supports
versionable
soensure => '1.0'
works - supports
upgradeable
- supports
latest
(checks upstream),absent
(uninstall) - supports
install_options
for pre-release, other cli - supports
uninstall_options
for pre-release, other cli - supports
holdable
, requires choco 0.9.9+
Simple install
package { 'notepadplusplus':
ensure => installed,
provider => 'chocolatey',
}
Ensure always the newest version available
package { 'notepadplusplus':
ensure => latest,
provider => 'chocolatey',
}
Ensure specific version
package { 'notepadplusplus':
ensure => '6.7.5',
provider => 'chocolatey',
}
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. The example
below covers -installArgs "/VERYSILENT /NORESTART"
.
package {'launchy':
ensure => installed,
provider => 'chocolatey',
install_options => ['-override', '-installArgs', '"', '/VERYSILENT', '/NORESTART', '"'],
}
Install options with quotes / 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 will 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, we must split on every space. Yes, on every space we must split the string or the result will come out incorrectly. So 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.
Reference
Classes
Public classes
Private classes
chocolatey::install.pp
: Ensures Chocolatey is installed.chocolatey::config.pp
: Ensures Chocolatey is configured.
Facts
chocolateyversion
- The version of the installed choco client (could also be provided by class parameterchocolatey_version
).choco_install_path
- The location of the installed choco client (could also be provided by class parameterchoco_install_location
).
Types/Providers
Package Provider: Chocolatey
Chocolatey implements a package type with a resource provider, which is built into Puppet.
This provider supports the install_options
and uninstall_options
attributes,
which allow command-line options to be passed to the choco command. These options
should be specified as documented below.
- Required binaries:
choco.exe
, usually found inC:\Program Data\chocolatey\bin\choco.exe
.- The binary is searched for using the Environment Variable
ChocolateyInstall
, then by two known locations (C:\Chocolatey\bin\choco.exe
andC:\ProgramData\chocolatey\bin\choco.exe
). - On Windows 2003 you should install Chocolatey to
C:\Chocolatey
or somewhere besides the default. NOTE: the root ofC:\
is not a secure location by default, so you may want to update the security on the folder.
- The binary is searched for using the Environment Variable
- Supported features:
install_options
,installable
,uninstall_options
,uninstallable
,upgradeable
,versionable
.
Properties/Parameters
ensure
(Property: This attribute represents concrete state on the target system.)
What state the package should be in. You can choose which package to retrieve by
specifying a version number or latest
as the ensure value. This defaults to
installed
.
Valid options: present
(also called installed
), absent
, latest
or a version
number.
install_options
An array of additional options to pass when installing a package. These options are
package-specific, and should be documented by the software vendor. One commonly
implemented option is INSTALLDIR
:
package {'launchy':
ensure => installed,
provider => 'chocolatey',
install_options => ['-installArgs', '"', '/VERYSILENT', '/NORESTART', '"'],
}
The above method of single quotes in an array is the only method you should use
in passing install_options
with the Chocolatey provider. There are other ways
to do it, but they are passed through to Chocolatey in ways that may not be
sufficient.
This is the only place in Puppet where backslash separators should be used. Note that backslashes in double-quoted strings must be double-escaped and backslashes in single-quoted strings may be double-escaped.
name
(Namevar: If ommitted, this attribute's value will default to the resource's title.)
The package name. This is the name that the packaging system uses internally.
provider
The specific backend to use for the package
resource. Chocolatey is not the
default provider for Windows so it must be specified (or by using a resource
default, shown in Usage). Valid options for this provider are 'chocolatey'
.
source
Where to find the package file. Chocolatey maintains default sources in its configuration file that it will use by default. Use this to override the default source(s).
Chocolatey accepts different values for source, including accept paths to local files/folders stored on the target system, URLs (to OData feeds), and network drive paths. Puppet will not automatically retrieve source files for you, and usually just passes the value of source to the package installation command.
You can use a file
resource if you need to manually copy package files to the
target system.
uninstall_options
An array of additional options to pass when uninstalling a package. These options are package-specific, and should be documented by the software vendor.
package {'launchy':
ensure => absent,
provider => 'chocolatey',
uninstall_options => ['-uninstallargs', '"', '/VERYSILENT', '/NORESTART', '"'],
}
The above method of single quotes in an array is the only method you should use
in passing uninstall_options
with the Chocolatey provider. There are other ways
to do it, but they are passed through to Chocolatey in ways that may not be
sufficient.
This is the only place in Puppet where backslash separators should be used. Note that backslashes in double-quoted strings must be double-escaped and backslashes in single-quoted strings may be double-escaped.
Class: chocolatey
Used for managing installation and configuration of Chocolatey itself.
Parameters
choco_install_location
Where Chocolatey install should be located. This needs to be an absolute path starting with a drive letter e.g. c:\
. Defaults to the currently detected install location based on the ChocolateyInstall
environment variable, falls back to 'C:\ProgramData\chocolatey'
.
use_7zip
Whether to use built-in shell or allow installer to download 7zip to extract chocolatey.nupkg
during installation. Defaults to true
.
choco_install_timeout_seconds
How long in seconds should be allowed for the install of Chocolatey (including .NET Framework 4 if necessary). Defaults to 1500
(25 minutes).
chocolatey_download_url
A url that will return chocolatey.nupkg
. This must be a url, but not necessarily an OData feed. Any old url location will work. Defaults to 'https://chocolatey.org/api/v2/package/chocolatey/'
.
enable_autouninstaller
Should auto uninstaller be turned on? Auto uninstaller is what allows Chocolatey to automatically manage the uninstall of software from Programs and Features without necessarily requiring a chocolateyUninstall.ps1
file in the package. Defaults to true
.
log_output
Log output from the installer. Defaults to false
.
Limitations
- Works with Windows only.
- If you override an existing install location of Chocolatey using
choco_install_location =>
in the Chocolatey class, it does not bring any of the existing packages with it. You will need to handle that through some other means.
Known Issues
- This module doesn't support side by side scenarios. This is ticketed as #74.
- This module may have issues upgrading Chocolatey itself using the package resource. See #65 and #60
- Other known issues/enhancements can be found on the issues list.
- If .NET 4.0 is not installed, it may have trouble installing Chocolatey. Choco version 0.9.9.9+ help alleviate this issue.
- If there is an error in the installer (
InstallChocolatey.ps1.erb
), it may not show as an error. This may be an issue with the PowerShell provider and is still under investigation.
Development
See CONTRIBUTING.md
Attributions
A special thanks goes out to Rich Siegel who wrote the original provider and continues to contribute to the development of this provider.
2016-07-11 Release 1.2.6
- Fix - AutoUninstaller runs every time in 0.9.9.x #134
2016-06-20 Release 1.2.5
- Support feature list changes in v0.9.10+ #133
- Fix - Chocolatey fails to install in PowerShell v2 with PowerShell Module 1.x #128
2016-06-04 Release 1.2.4
- Compatibility with puppetlabs-powershell 2.x #125.
2016-05-06 Release 1.2.3
- Do not call choco with --debug --verbose by default #100.
- Announce Chocolatey for Business in ReadMe.
2016-05-06 Release 1.2.3
- Do not call choco with --debug --verbose by default #100.
- Announce Chocolatey for Business in ReadMe.
2016-04-06 Release 1.2.2
- Fix: puppet apply works again #105.
$::chocolateyversion
fact is optional - see #110- Fix: Implement PowerShell Redirection Fix for Windows 2008 / PowerShell v2 - see #119
2015-12-08 Release 1.2.1
- Small release for support of newer PE versions.
##2015-11-03 Release 1.2.0
2015-10-02 Release 1.1.2
- Ensure 0.9.9.9 compatibility (#94)
- Fix - Mixed stale environment variables of existing choco install causing issues (#86)
- Upgrade From POSH Version of Chocolatey Fails from Puppet (#60)
2015-09-25 Release 1.1.1
- Add log_output for chocolatey bootstrap installer script
- Ensure bootstrap enforces chocolatey.nupkg in libs folder
- Allow file location for installing nupkg file.
2015-09-09 Release 1.1.0
- Install Chocolatey itself / ensure Chocolatey is installed (PUP-1691)
- Adds custom facts for chocolateyversion and choco_install_path
2015-07-23 Release 1.0.2
- Fixes #71 - Allow
ensure => $version
to work with already installed packages
2015-07-01 Release 1.0.1
- Fixes #66 - Check for choco existence more comprehensively
2015-06-08 Release 1.0.0
- No change, bumping to 1.0.0
2015-05-22 Release 0.5.3
- Fix manifest issue
- Fix choco path issue
- Update ReadMe - fix/clarify how options with quotes need to be passed.
2015-04-23 Release 0.5.2
- Update ReadMe
- Add support for Windows 10.
- Fixes #56 - Avoiding puppet returning 2 instead of 0 when there are no changes to be done.
2015-03-31 Release 0.5.1
- Fixes #54 - Blocking: Linux masters throw error if module is present
2015-03-30 Release 0.5.0
- Provider enhancements
- Better docs
- Works with both compiled and powershell Chocolatey clients
- Fixes #50 - work with newer compiled Chocolatey client (0.9.9+)
- Fixes #43 - check for installed packages is case sensitive
- Fixes #18 - The OS handle's position is not what FileStream expected.
- Fixes #52 - Document best way to pass options with spaces (#15 also related)
- Fixes #26 - Document Chocolatey needs to be installed by other means
Dependencies
- puppetlabs/stdlib (>= 4.6.0 < 5.0.0)
- puppetlabs/powershell (>= 1.0.1 < 3.0.0)
- badgerious/windows_env (>= 2.2.1 < 3.0.0)
Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.