Install The Licensed Edition

Congratulations on your recent purchase of a licensed edition of Chocolatey! If you are trialing, please pay particular attention to that section:

• Some Administrative Actions
• How Do I Know When the License is Installed?
• See It In Action
• How Do I Install The Licensed Edition?
  • How Do I Install a Local nupkg File?
  • How Do I Install The Trial Edition?
    • Notes on the Trial Version
• Upgrading
  • How Do I Upgrade The Trial Edition?
• Installing / Upgrading In Secure Environments / Without Internet Access
• Set Up Licensed Edition With Puppet
• Install the Chocolatey Agent Service
  • Ensure the Chocolatey Agent Service with Puppet
• Common Errors and Resolutions
  • Chocolatey doesn't recognize the license file
  • Exception of type 'Rhino.Licensing.LicenseNotFoundException' was thrown.
  • ERROR: The term 'Install-ChocolateyWindowsService' is not recognized as the name of a cmdlet, function, script file, or operable program.
  • Unable to load licensed version extensions and commands.

Some Administrative Actions

• The email the license is sent to will automatically be subscribed to the customer advisory list. If there are other folks who need to be on that list for important notifications, please have them sign up at Chocolatey Customers.
• Please sign up for software announcements at Chocolatey Announce. Direct others to sign up for the list as well.
• For support, remember to use the support email address (below).
• Learn how to install below. Installation is also found at https://chocolatey.org/docs/installation-licensed.

How Do I Know When the License is Installed?

Installing a licensed edition requires two parts

• The properly placed license file
• Installing/upgrading the licensed package - Chocolatey Licensed Extension (chocolatey.extension)

When you have performed all parts correctly, running choco will produce a message like one of the following:

• Chocolatey v0.10.7 Professional
• Chocolatey v0.10.7 Business

If you do not see the edition next to the name and version, you need to check over your installation procedure again to ensure you've completed it properly. See below.

See It In Action

Here's the whole process for installing your license and installing the licensed code.

How Do I Install The Licensed Edition?

1. Install a recent version of Chocolatey (0.10.7+) - choco upgrade chocolatey (due to a tight integration, chocolatey.extension may need a newer version than what is listed here).
2. You received a license file in email.
3. Take that license file and copy it to your Chocolatey install folder license subdirectory (you may need to create it first). For most folks that path would be "C:\ProgramData\chocolatey\license". Alternatively, you can put the license in your user profile directory, e.g. "C:\Users\YourUserName\chocolatey.license.xml"

1. Run this command: choco upgrade chocolatey.extension (or you can call install instead of upgrade). You will see an error you can safely ignore.

1. That's it! You are good to go.

How Do I Install a Local nupkg File?

See the next section

How Do I Install The Trial Edition?

If you've received a trial license, you will also receive a link to download a recent version of the chocolatey.extension package. You will not be able to install or upgrade the licensed edition through regular means. Chocolatey may add the licensed source, but your license will not be recognized on the server.

• Follow all of the instructions above except the choco upgrade chocolatey.extension command, that will not work with the trial license as the license will not be recognized by the licensed source.
• Instead download the chocolatey.extension (licensed package) from the provided download link location and remember where you saved it.
• Now run this command: choco upgrade chocolatey.extension --pre --source c:\folder\where\downloaded\nupkg\resides (or you can use install instead of upgrade). Note: Source location is not --source c:\downloads\chocolatey.extension.1.8.1.nupkg, it is --source c:\downloads.

Notes on the Trial Version

In the trial, package authoring features have nag warnings that require someone to manually hit the Enter key a random number of times. Do not attempt to automate Package Internalizer / Package Builder or choco sync when using a trial of C4B. Execute those things directly and see how well they work for you.

There are no trial type messages for runtime features unless they need to use Package Builder (like choco sync does), which should allow you to test those features with other integration tools.

Upgrading

To upgrade the licensed edition just run the following code:

• choco upgrade chocolatey.extension

Your license automatically adds the licensed source.

How Do I Upgrade The Trial Edition?

You will not be able to upgrade through regular means - please reach back out to the Chocolatey Software folks to get an updated edition (and possibly an extended trial license).

Installing / Upgrading In Secure Environments / Without Internet Access

Once you have the license down and the licensed edition extension intstalled the first time, you will have access to choco download. This will allow you to download the licensed edition and put it on your internally hosted repository.

From a machine that will have access to do this you simply run:

• choco download chocolatey.extension --source https://licensedpackages.chocolatey.org/api/v2/ --ignore-dependencies
• Whatever followup command you need to push that downloaded package to your internal package repository.

You can even script this or add it to a CI job that would automatically make the newer edition available.

NOTE: The licensed source that is automatically added can be disabled, but it cannot be removed. So just run choco source disable -n chocolatey.licensed to disable it or set that up in your configuration management solution scripts. Some of them, like Puppet, have a resource dedicated strictly to this:

chocolateysource {'chocolatey.licensed':
  ensure   => disabled,
  require  => File['C:/ProgramData/chocolatey/license/chocolatey.license.xml'],
}

Set Up Licensed Edition With Puppet

Most organizations using Chocolatey and Puppet are going to do so with zero internet access.

• Set up a local licensed edition of Chocolatey and run the following commands:
• choco download chocolatey --source https://chocolatey.org/api/v2/
• choco download chocolatey.server --source https://chocolatey.org/api/v2/
• choco download chocolatey.extension --source https://licensedpackages.chocolatey.org/api/v2/ --ignore-dependencies
• choco download chocolatey-agent --source https://licensedpackages.chocolatey.org/api/v2/ --ignore-dependencies
• Use choco push to push those items to your internal package repository (e.g. choco push chocolatey.0.10.7.nupkg -s http://internal_repo/ -k abc123)
• Determine how to get the bare url to download the Chocolatey.Nupkg directly. You will need that for the internal url for installing Chocolatey offline. For the community repository, it is https://chocolatey.org/api/v2/package/chocolatey

Here is what a completely offline use of Chocolatey looks like (complete with a Chocolatey.Server instance):

# Requires puppetlabs/chocolatey module
# See https://forge.puppet.com/puppetlabs/chocolatey

## - Ensure Chocolatey Install -
## Download chocolatey.nupkg to your internal repository (see above
##  about getting the package for offline use)
## Note: `chocolatey_download_url is completely different than normal
##  source locations. This is directly to the bare download url for the
##  chocolatey.nupkg, similar to what you see when you browse to
##  https://chocolatey.org/api/v2/package/chocolatey
class {'chocolatey':
  chocolatey_download_url => 'https://<internalurl/to>/chocolatey.nupkg',
  use_7zip                => false,
}


## If you need FIPS compliance
## make this the first thing you configure before you do any additional
## configuration or package installations
#chocolateyfeature {'useFipsCompliantChecksums':
#  ensure => enabled,
#}

## Keep chocolatey up to date based on your internal source
## You control the upgrades based on when you push an updated version
##  to your internal repository.
## Note the source here is to the OData feed, similar to what you see
##  when you browse to https://chocolatey.org/api/v2
package {'chocolatey':
  ensure   => latest,
  provider => chocolatey,
  source   => 'https://<internal_repo>/chocolatey',
}

## - Configure Chocolatey -
### Config Settings

## Move cache location so Chocolatey is very deterministic about
## cleaning up temporary data
chocolateyconfig {'cacheLocation':
  value => 'c:\ProgramData\choco-cache',
}

## Increase timeout to 4 hours
chocolateyconfig {'commandExecutionTimeoutSeconds':
  value => '14400',
}

### Sources
## Remove the default community package repository source
chocolateysource {'chocolatey':
  ensure   => absent,
  location => 'https://chocolatey.org/api/v2/',
}

## Disable the licensed source, it can't be removed
## Disabled sources still need all other attributes until
## https://tickets.puppetlabs.com/browse/MODULES-4449 is resolved.
## Password is necessary with user, but not ensurable, so it should not
## matter what it is set to here. If you ever do get into trouble here,
## the password is your license GUID.
chocolateysource {'chocolatey.licensed':
  ensure   => disabled,
  priority => '10',
  user     => 'customer',
  password => '1234',
  require  => File['C:/ProgramData/chocolatey/license/chocolatey.license.xml'],
}

## Add default sources for your internal repositories
chocolateysource {'internal_chocolatey':
  ensure   => present,
  location => 'http://internal_location/OData/endpoint',
  priority => 1,
  username => 'optional',
  password => 'optional,not ensured',
}

### Features
chocolateyfeature {'checksumFiles':
  ensure => enabled,
}

## When using Puppet for installs
chocolateyfeature {'showDownloadProgress':
  ensure => disabled,
}

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

## - LICENSED OPTIONS -
### See https://chocolatey.org/docs/installation-licensed

file { ['C:/ProgramData/chocolatey','C:/ProgramData/chocolatey/license']:
  ensure => directory,
}

### Ensure the license file is in the module
### `puppet:///modules/module_name` == files directory of the module
### `<module_name>\files\chocolatey.license.xml` is where the example
###  be found, where <module_name> is the name of the module (e.g. `choco_internal`)
file {'C:/ProgramData/chocolatey/license/chocolatey.license.xml':
  ensure              => file,
  source              => 'puppet:///modules/<module_name>/chocolatey.license.xml',
  source_permissions  => ignore,
}

## Ensure the chocolatey.extension package
package {'chocolatey.extension':
  ensure          => latest,
  source          => 'internal_chocolatey',
  install_options => ['-pre'],
  require         => File['C:/ProgramData/chocolatey/license/chocolatey.license.xml'],
}

### Licensed Config Settings
chocolateyconfig {'virusScannerType':
  value   => 'Generic',
  require => Package['chocolatey.extension'],
}

## McAfee options
## https://kc.mcafee.com/corporate/index?page=content&id=KB75478
#chocolateyconfig {'genericVirusScannerPath':
#  value   => 'C:\full\path\to\scan.exe',
#  require => Package['chocolatey.extension'],
#}

## https://community.mcafee.com/thread/70968?start=0&tstart=0
## You could try cleaning as well /CLEAN /NORENAME (instead of /DEL)
#chocolateyconfig {'genericVirusScannerArgs':
#  value   => '[[File]] /ANALYZE /NC /NOEXPIRE /DEL /NOEXPIRE /SILENT /REPORT=c:\ProgramData\choco-cache\lastscan.log',
#  require => Package['chocolatey.extension'],
#}

## 0 for no issues, 19 for success on cleaning any infected files
#chocolateyconfig {'genericVirusScannerValidExitCodes':
#  value   => '0, 19',
#  require => Package['chocolatey.extension'],
#}

### Licensed Feature Settings
chocolateyfeature {'virusCheck':
  ensure  => enabled,
  require => Package['chocolatey.extension'],
}

## Package Internalizer enhancement
## See https://chocolatey.org/docs/features-automatically-recompile-packages
chocolateyfeature {'internalizeAppendUseOriginalLocation':
  ensure  => enabled,
  require => Package['chocolatey.extension'],
}

## Package Reducer - keep space down
chocolateyfeature {'reduceInstalledPackageSpaceUsage':
  ensure  => enabled,
  require => Package['chocolatey.extension'],
}

## Unlock preview features - check before you do this, may not be
##  production ready
#chocolateyfeature {'allowPreviewFeatures':
#  ensure  => enabled,
#  require => Package['chocolatey.extension'],
#}


## - Chocolatey Simple Server Package Repository -
## Requires chocolatey/chocolatey_server module  - see
##  https://forge.puppet.com/chocolatey/chocolatey_server
## this contains the bits to install the custom server
## - Ensures IIS and Ensure ASP.NET
## - Installs and configures the Chocolatey.Server website and app pool
## - Sets permissions appropriately

## `server_package_source` is to the OData feed, similar to what you see
##  when you browse to https://chocolatey.org/api/v2
class {'chocolatey_server':
  server_package_source => 'https://internalurl/odata/server',
}

chocolateysource {'local_chocolatey_server':
  ensure   => present,
  location => 'http://localhost/chocolatey',
  priority => 2,
}

Install the Chocolatey Agent Service

For C4B (Chocolatey for Business) customers, there is an optional agent service you can install. The agent service allows for things like background mode, setting up maintenance windows (future), and hooking up to Chocolatey Central Management (future).

To be able to install it, you must first have the licensed edition properly installed. Once you have verified your install, you can run the following:

• choco install chocolatey-agent <options>

For more on the agent service, please see [[Agent Service|FeaturesAgentService]].

Ensure the Chocolatey Agent Service with Puppet

This is used in conjunction with the script in Set Up Licensed Edition With Puppet. Here are some additional commands and scripts you will need for that setup:

• choco download chocolatey-agent --source https://licensedpackages.chocolatey.org/api/v2/ --ignore-dependencies
• Use choco push to push packages to your internal package repository (e.g. choco push chocolatey-agent.0.8.0.nupkg -s http://internal_repo/ -k abc123)

## - Chocolatey Agent (Additional optional Chocolatey for Business install) -
## See https://chocolatey.org/docs/features-agent-service

## ensure we set the user up properly
chocolateyfeature {'useLocalSystemForServiceInstalls':
  ensure  => disabled,
  require => Package['chocolatey.extension'],
}

## this is the default setting
chocolateyconfig {'serviceInstallsDefaultUserName':
  value   => 'ChocolateyLocalAdmin',
  require => Package['chocolatey.extension'],
}

## if you are passing through a password, set that here
## otherwise Chocolatey will manage a password that is secured
## and different per machine
#chocolateyconfig {'serviceInstallsDefaultUserPassword':
#  value   => '<inject_from_hiera>',
#  require => Package['chocolatey.extension'],
#}

package {'chocolatey-agent':
  ensure          => latest,
  install_options => ['-pre'],
  require         => Chocolateyfeature['useLocalSystemForServiceInstalls'],
}

For setting up Self-Service / Background Mode, add the following elements:

• choco download chocolateygui --pre --source="'https://www.myget.org/F/chocolateygui/;https://chocolatey.org/api/v2'" --ignore-dependencies
• choco download dotnet4.5.2 --internalize --source https://chocolatey.org/api/v2
• Use choco push to push those items to your internal package repository (e.g. choco push chocolatey.0.10.7.nupkg -s http://internal_repo/ -k abc123)

## You don't want a non-admin to get a warning when using self-service
chocolateyfeature {'showNonElevatedWarnings':
  ensure => disabled,
  require => Package['chocolatey-agent'],
}

## Ensure Admins (and Puppet) do not use the background service
chocolateyfeature {'useBackgroundServiceWithNonAdministratorsOnly':
  ensure  => enabled,
  require => Package['chocolatey-agent'],
}

## You still need to figure out how to set up a source as allowed for
## Self-service until the Puppet module gets that attribute added to
## chocolateysource
## We don't recommend disabling this unless you've removed all sources
##  except for your internal and they are fine for self-service
#chocolateyfeature {'useBackgroundServiceWithSelfServiceSourcesOnly':
#  ensure  => disabled,
#  require => Package['chocolatey-agent'],
#}

## Set Chocolatey into background mode
chocolateyfeature {'useBackgroundService':
  ensure  => enabled,
  require => Chocolateyfeature['useBackgroundServiceWithNonAdministratorsOnly'],
}

package {'dotnet4.5.2':
  ensure => latest,
  notify => Reboot['pending_dot_net_install'],
}

reboot { 'pending_dot_net_install':
  when => pending,
}

package {'chocolateygui':
  ensure          => latest,
  install_options => ['-pre'],
  require         => Package['dotnet4.5.2'],
}

Common Errors and Resolutions

When you are attempting to install the licensed edition, you may run into some errors depending on your configuration. Here are some common ones we've seen.

Chocolatey doesn't recognize the license file

When you run choco, it doesn't show a commercial edition next to the name. Like 'Chocolatey v0.10.7 Professional'. This means that Chocolatey is not detecting a license file. This could be an incorrectly placed or incorrectly named file. For troubleshooting, please perform the following:

1. Open PowerShell and run the following command (verbatim): Get-Content $env:ChocolateyInstall\license\chocolatey.license.xml

You should see the output of the license file. If you do not see this, the license file is not placed correctly or misnamed. Please go back and set the license correctly to see if that fixes the issue.

If you do see the expected output but Chocolatey is still not recognizing the file, please do the following:

1. Run cacls.exe C:\ProgramData\chocolatey\license
2. Run cacls.exe C:\ProgramData\chocolatey\license\chocolatey.license.xml
3. Run where.exe choco
4. Please zip up C:\ProgramData\chocolatey\logs\chocolatey.log
5. Open a support ticket and send us the log and the output of the commands in this step.

Exception of type 'Rhino.Licensing.LicenseNotFoundException' was thrown.

If you run into this error, it means you are on an older version of Chocolatey and you need to upgrade.

1. Remove the license file.
2. Upgrade the chocolatey package - choco upgrade chocolatey <options>
3. Set the license file back and proceed with the install or upgrade process as above.

ERROR: The term 'Install-ChocolateyWindowsService' is not recognized as the name of a cmdlet, function, script file, or operable program.

You can get this if you are attempting to install the chocolatey-agent package, but you don't have a verified installation of a licensed edition of Chocolatey. You must resolve that prior to attempting to install the chocolatey-agent package. See How Do I Know When the License is Installed?.

Unable to load licensed version extensions and commands.

You may see a message like this: Unable to load licensed version extensions and commands. Please make sure the version of Chocolatey you are on is up to date and meets the minimum requirements of the licensed version. If that version is in beta, that means the latest avaialble version. followed by the actual error that may look something like this: Could not load type 'chocolatey.infrastructure.app.services.Isomething' from assembly 'choco, Version=0.10.7.0, Culture=neutral, PublicKeyToken=79d02ea9cad655eb'. 0.10.7.

If you see this, it is typically due to an incompatibility between Chocolatey and the licensed extension (Chocolatey.Extension). As these two are tightly integrated to each other, sometimes there are incompatibilities introduced. Chocolatey Software will inform customers of these issues and ways to get around that, typically ahead of releases on the customer advisory list (the link for this is sent with the email that contained the license).

First steps:

• Try choco upgrade chocolatey.extension -y

If that is successful, you are good to go.

If not, the following steps should remedy the situation:

NOTE: Running choco in an unlicensed sense will reset/remove all licensed configuration.

• Make a backup of the chocolatey.config (typically at "C:\ProgramData\chocolatey\config\chocolatey.config").
• Remove the license file - rename the license folder to licensed (typically at "C:\ProgramData\chocolatey\license").
• In the extensions folder, delete the chocolatey folder (typically at "C:\ProgramData\chocolatey\extensions\chocolatey").
• Run choco uninstall chocolatey.extension.
• Add the license file again - rename the licensed folder back to license.
• Run choco upgrade chocolatey.extension.
• Compare the current chocolatey.config to your backed up chocolatey.config` and set anything that was reset in this process.