Version information
This version is compatible with:
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
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 - An under-the-hood peek at what the module is doing and how
- 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 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.
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+
NOTE: The module does not yet offer an installation option for Chocolatey, so you will need to install that as well.
Beginning with Chocolatey provider
Install this module via any of these approaches:
- puppet forge
- git-submodule (tutorial)
- librarian-puppet
- r10k
Usage
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 {
# default package provider
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',
}
- this is versionable so
ensure => '1.0'
works - this is upgradeable
- supports
latest
(checks upstream),absent
(uninstall) - supports
install_options
for pre-release, other cli - soon: supports 'holdable'
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
- Chocolatey provider (
lib/puppet/provider/package/chocolatey.rb
) - params.pp (
manifests/params.pp
) - install.pp (
manifests/install.pp
) - config.pp (
manifests/config.pp
)
Chocolatey Provider
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.
Limitations
Works with Windows only.
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.
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
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.