This is the service that the agents (chocolatey-agent) communicates with. You could install one or more of these depending on the size of your environment (not multiple on one machine though). The FQDN and certificate used determine what the URL will be for the agents to check into Chocolatey Central Management.

WARNING

Unless otherwise noted, please follow these steps in exact order. These steps build on each other and need to be completed in order.

WARNING

In order to run the Chocolatey Central Management Service a user with Administrator access is required. By default, a new user named ChocolateyLocalAdmin will be created and configured to run the Chocolatey Central Management Service. In addition, Logon as Service and Logon as Batch privileges will be asserted for this user. If attempting to run the Chocolatey Central Management Service as a different user, these permissions will be required.

Step 1: Complete Prerequisites

WARNING

The database must be setup and available, along with logins and access.

• High-level Requirements
• PowerShell 5.1

Step 2: Install Chocolatey Central Management Service Package

By default the service will install as the local administrative user ChocolateyLocalAdmin (and manage the password as well). However you can specify your own user with package parameters (such as using a domain account). You will need to specify credentials to the database as we’ll see in scenarios below.

WARNING

Timezones are super important here and time synchronization is really important when generating SSL Certificates. You want to make sure this information is correct. Otherwise there is a potential edge case you could generate an SSL Certificate that is not yet valid. As the service package could generate an SSL certificate if you don’t pass an existing thumbprint, it’s best to ensure that time synchronization is not an issue with the machine you are installing this on.

FQDN Usage

When installing the Chocolatey Central Management Service, the default is to use the Fully Qualified Domain Name (FQDN) of the machine that it is being installed on. As a result, there is an expectation that the certificate (either the self-signed certificate that is created during installation, or the existing certificate which is configured with the CertificateThumbprint parameter) that is used to secure the transport layer of this service also uses the same FQDN.

# Find FDQN for current machine
$hostName = [System.Net.Dns]::GetHostName()
$domainName = [System.Net.NetworkInformation.IPGlobalProperties]::GetIPGlobalProperties().DomainName

if(-Not $hostName.endswith($domainName)) {
  $hostName += "." + $domainName
}

choco config set --name="'centralManagementServiceUrl'" --value="'https://$($hostname):24020/ChocolateyManagementService'"

If this is not the case, it will be necessary to provide the information to the package about the actual name for the machine that is being used. When using a self-signed certificate, this can be specified using the CertificateDnsName, and when using an existing certificate, no additional parameters are required. In both cases, it will be necessary to also set the centralManagementServiceUrl configuration parameter. This can be done using the following command:

choco config set --name="'centralManagementServiceUrl'" --value="'https://<accessible_url>:24020/ChocolateyManagementService'"

Package Parameters

Note items with “:” mean a value should be provided. Items without are simply switches.

• /Username: - Username to run the service under. Defaults to ChocolateyLocalAdmin. This should be a local Administrator - this is typically ensured during installation. Logon as Service and Logon as Batch privileges are also ensured.
• /Password: - Password for the user. Default is the Chocolatey Managed Password.
• /EnterPassword - Receive the password at runtime as a secure string. Requires input at runtime whe installing/upgrading the package.
• /NoRestartService - Do not shut down and restart the service. You will need to restart later to take advantage of new service information.
• /DoNotReinstallService - Do not re-install the service.
• /PortNumber: - The port the Chocolatey Management Service will listen on. This will automatically create a rule to open the firewall on the port specified. Defaults to 24020.
• /CertificateDnsName: - The DNS name of the self-signed certificate that is generated if no existing certificate thumbprint is provided using the /CertificateThumbprint parameter (below). Defaults to <LOCAL COMPUTER FQDN NAME>.
• /CertificateThumbprint: - Provide the thumbprint of an existing certificate (already installed in LocalMachine\TrustedPeople certificate store) to use for secure communication with clients. Defaults to a new self-signed SSL certificate on first installation / reuses existing on upgrades.
• /ConnectionString: - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. By default, this value is constructed from the default or explicit values for /SqlServiceInstance and /Database, and uses Integrated Security (with all default values, this value will look like the following: Server=<LOCAL COMPUTER FQDN NAME>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;). The account should have db_datareader/db_datawriter access to the database.
• /SqlServerInstance: - Instance name of the SQL Server database to connect to. Alternative to passing full connection string with /ConnectionString. Uses /Database (below) to build a connection string. Defaults to <LOCAL COMPUTER FQDN NAME>.
• /Database: - Name of the SQL Server database to use. Alternative to passing full connection string with /ConnectionString. Uses /SqlServerInstance (above) to build a connection string. Defaults to ChocolateyManagement.

NOTE

Items suffixed with “:” mean a value should be provided. Items without are simply switches.

Service Settings

• Service Name: chocolatey-central-management
• Service Displayname: Chocolatey Central Management Service
• Description: Chocolatey Central Management Service is a service for Chocolatey
• Service Startup: Automatic
• Service Username: ChocolateyLocalAdmin or ‘/Username:’

Chocolatey Central Management Service Configuration

For most installations, the default values for the Chocolatey Central Management Service configuration should be all that is required. However, if you need to modify this configuration, then full details of what can be controlled is detailed on the Chocolatey Central Management Service configuration page.

Chocolatey Configuration

There are a number of different Chocolatey Configuration values that can be set for the Chocolatey Central Management Service. The main setting that has to be set is detailed below, and you can find a complete list on the Chocolatey Central Management Service configuration page.

• centralManagementServiceUrl = ’ ’ (empty) - The URL that should be used to communicate with Chocolatey Central Management. It should look something like https://servicemachineFQDN:24020/ChocolateyManagementService. See FQDN usage. Defaults to ” (empty). NOTE: Chocolatey Agent and Chocolatey Central Management Service share this value on a machine that contains both. If blank, the Chocolatey Central Management Service will construct a URL based on defaults of the machine, but is required to be set for Agents.

WARNING

The Chocolatey Agent installed on the same machine that has the Chocolatey Central Management Service installed will share the centralManagementServiceUrl setting, so that agent can only report into that Chocolatey Central Management Service.

Chocolatey Managed Password

When Chocolatey manages the password for a local Administrator, it creates a very complex password:

• It is 32 characters long.
• It uses uppercase, lowercase, numbers, and symbols to meet very stringent complexity requirements.
• The password is different for every machine.
• Due to the way that it is generated, it is completely unguessable.
• No one at Chocolatey Software could even tell you what the password is for a particular machine without local access.

Chocolatey Central Management Service Windows Account Considerations

• Windows Account (required, defaults to ChocolateyLocalAdmin)
  • The Chocolatey Central Management Service requires an administrative account, whether that is a domain account or a local account - it just needs to be a local admin (a member of the Administrators group).
  • The Chocolatey Central Management Service doesn’t specifically require the ChocolateyLocalAdmin account. Any Windows account can be used. The ChocolateyLocalAdmin is used as the default if one is not specified.
  • Upon use of an account during installation, it will make that account a member of the Administrators account.
  • The account used will also be granted LogonAsService and LogonAsBatch privileges.
• Managed Password (optional, default)
  • When the ChocolateyLocalAdmin account is used, it generates a managed password that is different on every machine. The password is 32 characters long, meets complexity requirements, and is basically very strong.
  • To determine the managed password, it would take access to the box and someone from Chocolatey Software who has access to the algorithm used to generate the password (more information in the FAQs below).
• Rotating/Updating Passwords
  • If a different account with a rotating password is used, the service will need to be updated with the new credentials and restarted soon after changing that password.
  • The managed password is not currently updated/rotated, but it is something we are looking to implement once we have figured out the best approach to do so.

Database Authentication Scenarios

WARNING

As of Chocolatey Central Management v0.13.0, the SQL connection mode has changed to secure-by-default. By default, all connection strings will assume Encrypt=true; and attempt a connection to the SQL Server over SSL. If you wish to disable this, you must pass a complete connection string to the /ConnectionString package parameter that contains an explicit Encrypt=false; parameter.

To accommodate this new default, the package installation will automatically add the TrustServerCertificate=True parameter to the connection string it constructs or receives if the initial connection to the SQL server fails without it.

If you would like to ensure a completely secure SQL connection, you must install a trusted SSL Certificate on the SQL Server instance before installing, upgrading, or reinstalling Chocolatey Central Management packages. If you have already installed v0.13.0 or later versions of Chocolatey Central Management, you will need to explicitly pass the SQL connection package parameters when upgrading or reinstalling in order to ensure the connection is established in a fully secure mode.

• Scenario 1 - Windows Authentication to Local SQL Server
• Scenario 2 - Active Directory Authentication to Remote SQL Server
• Scenario 3 - SQL Server Authentication to Local SQL Server
• Scenario 4 - SQL Server Authentication to Remote SQL Server

• Scenario 1
• Scenario 2
• Scenario 3
• Scenario 4

choco install chocolatey-management-service -y --package-parameters="'/ConnectionString:Server=<Localhost\SQLEXPRESS>;Database=ChocolateyManagement;Trusted_Connection=True; /Username:<LocalWindowsAccount>'" --package-parameters-sensitive="'/Password:<Local account password>'"

choco install chocolatey-management-service -y --package-parameters="'/ConnectionString:Server=<Localhost\SQLEXPRESS>;Database=ChocolateyManagement;Trusted_Connection=True;'"

choco install chocolatey-management-service -y --package-parameters="'/ConnectionString:Server=<RemoteSqlHost>;Database=ChocolateyManagement;Trusted_Connection=True; /Username:<DomainAccount>'" --package-parameters-sensitive="'/Password:<domain account password>'"

choco install chocolatey-management-service -y --package-parameters-sensitive="'/ConnectionString:Server=Localhost;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;'"

choco install chocolatey-management-service -y --package-parameters-sensitive="'/ConnectionString:Server=Localhost\SQLEXPRESS;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;'"

choco install chocolatey-management-service -y --package-parameters-sensitive="'/ConnectionString:Server=<RemoteSqlHost>;Database=ChocolateyManagement;User ID=ChocoUser;Password=Ch0c0R0cks;'"

Step 3: Verify Installation

The chocolatey-management-service is responsible for making a number of changes to your system. A successful installation of this package can be verified by:

• Open the services snap-in (services.msc) and check for the presence of the Chocolatey Management Service which should be in the “Started” state.
• The installation folder for chocolatey-management-service is at $env:ChocolateyInstall\lib\chocolatey-management-service\tools\service.
• Open the Service log file located at $env:ChocolateyInstall\logs\ccm-service.log and verify that there are no recently reported errors. If you are on a version of Chocolatey Central Management prior to 0.2.0, the log will be located at $env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log.

FAQ

Why is the Chocolatey Central Management Service not marked as ‘Stopped’ when there is an error during its execution?

By default, all exceptions that occur within the Chocolatey Central Management Service are logged to the applications log file (ccm-service.log). However, these exceptions do not result in actually physically stopping the service. If an exception is thrown within the application, and you checked the Chocolatey Central Management Service in the Windows Services snap-in, you would still see that the service is running. Due to the nature of how exceptions occur within the Chocolatey Central Management Service, this is normally perfectly fine since operations are attempted again at a later date. There are occasions, for example when something in the appsettings.json file has been misconfigured, that an exception can be thrown and the service doesn’t start up correctly, but it is still marked as Running. This situation can occur with any version of Chocolatey Central Management up to and including v0.6.2, but it is something that we are looking to address in a future release.

What is the minimum required configuration for the appsettings.json file?

As of Chocolatey Central Management v0.13.0, the default configuration values in the appsettings.json for the Chocolatey Central Management service are:

{
  "ConnectionStrings": {
    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
  },
  "CertificateThumbprint": "<THUMBPRINT_OF_CERTIFICATE_FOUND_DURING_INSTALLATION>"
}

NOTE

This file will usually be condensed into a single line, with the values encrypted.

If these values are removed or incorrect, the Chocolatey Central Management service may fail to start. To correct this, ensure all configuration is present and correct and then restart the Chocolatey Central Management service.

Get-Service -Name chocolatey-central-management | Restart-Service

How can we increase the level of logging for Chocolatey Central Management?

This can be done by changing the level value, which should be currently INFO, to use DEBUG, as per the following:

<root>
  <level value="DEBUG" />
  <appender-ref ref="ColoredConsoleAppender" />
  <appender-ref ref="RollingLogFileAppender" />
</root>

In the following files:

• $env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\log4net.config. If you are on a version less than 0.2.0, then it will be in $env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\chocolatey-central-management.exe.config.
• $env:ChocolateyInstall\lib\chocolatey-agent\tools\service\chocolatey-agent.exe.config

When the value is changed, the services may also need restarted.

How can we view what SSL registrations have been made by the installation of chocolatey-management-service?

By default, the installation of the chocolatey-management-service package will register a single netsh binding between a self-signed certificate (created at the point of installation) and port 24020. This can be verified using the following command:

netsh http show sslcert

:choco-info: NOTE

Starting with Chocolatey Central Management 0.6.0, netsh bindings are no longer created during the installation of the Chocolatey Central Management Service package. On installing the 0.6.0 Chocolatey Central Management Service package, any existing netsh bindings that were created specifically for Chocolatey Central Management usage will be removed.

How can we remove a netsh binding that has been created?

If you need to remove a netsh binding, you can do that using the following command:

netsh http delete sslcert ipport=0.0.0.0:<port_number>

NOTE

Here, <port_number> should be replaced with the Port Number that has been registered.

Starting with Chocolatey Central Management 0.6.0, netsh bindings are no longer created during the installation of the Chocolatey Central Management Service package. On installing the 0.6.0 Chocolatey Central Management Service package, any existing netsh bindings that were created specifically for Chocolatey Central Management usage will be removed.

Can we manually create an SSL binding?

If required, it is possible to manually create a netsh binding. This is done using the following command:

netsh http add sslcert ipport=0.0.0.0:<port_number> certhash=<certificate_thumbprint> appid={<random_guid>}

NOTE

Here, <port_number> should be replaced with the Port Number to be used for the registration. <certificate_thumbprint> should be replaced with the thumbprint for the certificate that is to be used for the registration. <random_guid> should be replaced with a random guid in the following format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Starting with Chocolatey Central Management 0.6.0, netsh bindings are no longer created during the installation of the Chocolatey Central Management Service package. On installing the 0.6.0 Chocolatey Central Management Service package, any existing netsh bindings that were created specifically for Chocolatey Central Management usage will be removed.

Can we install the Chocolatey Central Management Service behind a load balancer?

Unfortunately, this is not a supported scenario. If you are trying to load balance requests to the Chocolatey Central Management service, you should install multiple instances on multiple machines and point clients explicitly to an instance so they can work together. If you are trying to load balance other things on a machine and the Chocolatey Central Management service just happens to be there (like with QDE), move the Chocolatey Central Management service to a different machine or allow direct connections to the box for Chocolatey Central Management.

NOTE

If you are an expert in managing X509 certificates with load balancing, you can certainly set this up, but if you can’t get it to work, move to a supported scenario. The Support team will tell you the same.

We want to set up the Chocolatey Central Management service to use a domain account that will have local admin privileges on each box. Can we do this?

Yes, absolutely. You will pass those credentials through at install/upgrade time, and you will also want to turn on the feature useRememberedArgumentsForUpgrades (see configuration) so that future upgrades will have that information available. The remembered arguments are stored encrypted on the box (and that encryption is reversible so you may opt to pass that information each time).

• /Username: - provide username - instead of using the default ‘ChocolateyLocalAdmin’ user. This user should be a local Administrator.
• /Password: - optional password for the user.
• /EnterPassword - receive the password at runtime as a secure string

You would pass something like choco install chocolatey-management-service -y --params="'/Username:domain\account /EnterPassword'" to securely pass the password at runtime. You could also run choco install chocolatey-management-service -y --params="'/Username:<domain\account>'" --package-parameters-sensitive="'/Password:<password>'" (or do it as part of choco upgrade).

Is the password stored anywhere?

No, that would reduce the security of the password. It exists in memory long enough to set the value on the user and the service and then it is cleared.

There is no storage of the password anywhere other than how Windows stores passwords.

We are going to use our own account with a rotating password. When we rotate the password for the account that we use for the Chocolatey Central Management Service, what do we need to do?

Like with any service that uses rotating passwords, you will need to redeploy the service or go into the Services Management console and update the password. As it is much faster to deploy out that update, you can do something like choco upgrade chocolatey-management-service -y --params="'/Username:domain\account'" --package-parameters-sensitive="'/Password:newpassword'" --force (the --force ensures the code is redeployed).

Tell me more about the Chocolatey managed password.

So you’ve seen from above that

• It is 32 characters long.
• It uses uppercase, lowercase, numbers, and symbols to meet very stringent complexity requirements.
• The password is different for every machine.
• Due to the way that it is generated, it is completely unguessable.
• No one at Chocolatey Software could even tell you what the password is for a particular machine without local access.

Chocolatey uses something unique about each system, along with an encrypted value in the licensed code base to generate the base password. It then makes some other changes to ensure that the password meets complexity requirements. We won’t give you the full algorithm of how the password is generated as knowing the algorithm would be a security issue. Like having a partial picture of a key; you could start working on how to break in. Unlike a picture of a key, even knowing the full algorithm doesn’t get you everything you need as you would require local access to each machine to determine the password for each machine.

Is the managed password stored or logged anywhere?

No, that would reduce the security of the password. It exists in memory long enough to set the value on the user and the service and then it is cleared.

There is no storage of the password anywhere other than how Windows stores passwords.

Is the managed password the same on every machine?

No, a different password is created for every machine at deployment.

How would someone potentially get access to the managed password?

The Chocolatey licensed code base is encrypted, so only people that work at Chocolatey Software would be able to determine the password for a particular box (just that one) IF they have local access to that box. Even with all of the information and the algorithm, it’s still going to take our folks a while to determine the password. That gets them access to one machine. Of course, Chocolatey folks are not going to do this for obvious reasons.

Let’s realize this to its full potential - If someone were able to hack the Chocolatey licensed codebase, they would be able to determine the full password algorithm. Then they’d also need to hack into your infrastructure and get local access to every box that they wanted to get the Chocolatey-managed password so they could get admin access to just that box. Taking this out a bit further, it’s reasonable to assume that if someone has hacked into your infrastructure, it’s highly unlikely they are going to be using a non-Administrator account to get local access to a box so they can get the password for an Administrator account for just that one box. It’s more likely they would would already have a local admin account for the boxes they are attacking, and are likely to seek other attack vectors that are much less sophisticated.

Do you rotate the managed password on a schedule?

We are looking to do this in a future release. We may make the schedule configurable.

Can I take advantage of Chocolatey managed passwords with my own Windows services?

Yes, absolutely. If you use Chocolatey For Business’s PowerShell Windows Services code, you will be able to install services and have Chocolatey manage the password for those as well.

What is the Chocolatey Central Management Component Compatibility Matrix?

Chocolatey Central Management has specific compatibility requirements with quite a few moving parts. It is important to understand that there are some Chocolatey Agent versions that may not be able to communicate with some versions of Chocolatey Central Management and vice versa. Please see the Chocolatey Central Management Component Compatibility Matrix for details.

I entered incorrect database details on install. Do I need to reinstall to fix that?

It depends. You can simply go to the appsettings.json file and adjust the connection string to be plaintext. It will remain in plaintext though (at least until upgrade), so if you have actual password details you need to keep secure, you should do a force installation using the --force parameter.

1. The file is located at $env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\appsettings.json.
2. You would open that up in an editor and modify the "Default" connection string.
3. It would look something like the following (adjust the connection string as necessary):

{
  "ConnectionStrings": {
        "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
  }
}

1. You may find it all on a single line in the file, and that is okay.
2. Restart the service by running the following from an admin powershell session: Get-Service chocolatey-management-service | Stop-Service; Get-Service chocolatey-management-service | Start-Service

WARNING

Do not put sec: or secure- at the start (prefix) of any values that you are adding/modifying directly. That tells Chocolatey components they are encrypted and it will attempt to decrypt them for use. If that is done incorrectly, it will cause things to crash.

Can we use an account for the service that is not a local Administrator?

No. This is not a supported scenario. The installation will attempt to ensure that the user becomes an Administrator if they are not, in addition to Logon as Service and Logon as Batch privileges.

Where is the management service installed?

The installation folder for chocolatey-management-service is at $env:ChocolateyInstall\lib\chocolatey-management-service\tools\service.

Common Errors and Resolutions

Cannot convert the “System.Object[]” value of type “System.Object[]” to type “System.Int32”.

You may see this error message when attempting to install version 0.6.0 of the chocolatey-management-service package.

Please see Licensed Issue #242 for details on a workaround that can be used. This bug will be addressed in the 0.6.1 release of Chocolatey Central Management.

Agents are unable to communicate with Chocolatey Central Management Service and the Chocolatey Central Management service log shows “Unable to start Kestrel”.

This is a known issue with Chocolatey Central Management v0.6.0 and v0.6.1 due to changes in how the Chocolatey Central Management service is hosted. netsh bindings are no longer required for the Chocolatey Central Management service, and you may also notice the bindings for the Chocolatey Central Management service removed during upgrade. The identifying symptom of this issue is the following in the Chocolatey Central Management service log file:

[FATAL] Microsoft.AspNetCore.Server.Kestrel (0): Unable to start Kestrel

In these versions, the best workaround is to ensure that your LocalMachine\TrustedPeople certificate store contains only one certificate with a DNS name that matches the Chocolatey Central Management service URL setting in your chocolatey.config file, and that this certificate has the ServerAuthentication usage applied to it.

Starting in v0.6.2, it is possible to configure the Chocolatey Central Management service to select a specific certificate to use. The Chocolatey Central Management service log file error will also now contain slightly more information, looking something like this:

[FATAL] ChocolateyServiceManagementTask: Microsoft.AspNetCore.Server.Kestrel [0]
Unable to start Kestrel.
System.InvalidOperationException: Certificate 3edebdfee63b57b0a0a12a079ed8da791da03ba7 cannot be used as an SSL server certificate. It has an Extended Key Usage extension but the usages do not include Server Authentication (OID 1.3.6.1.5.5.7.3.1).

You may also receive a differently-worded error if the certificate used by the Chocolatey Central Management service in the LocalMachine\TrustedPeople store is removed.

Starting in Chocolatey Central Management v0.6.2, the Chocolatey Central Management Service package will attempt to select an appropriate certificate during installation, and store the thumbprint in the appsettings.json file. You can also specify the thumbprint for the certificate to use as the /CertificateThumbprint package parameter during installation or upgrade.

If you need to change the certificate you’re using after installation, you can modify the entry in the appsettings.json file for the Chocolatey Central Management service. Below is a sample of what the appsettings.json file looks like by default as of Chocolatey Central Management v0.13.0.

{
  "ConnectionStrings": {
    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
  },
  "CertificateThumbprint": "<THUMBPRINT_OF_CERTIFICATE_FOUND_DURING_INSTALLATION>"
}

Altering the CertificateThumbprint value will cause the Chocolatey Central Management service to select the corresponding certificate from the LocalMachine\TrustedPeople store instead. You will need to restart the Chocolatey Central Management service after changing this value for it to take effect.

Get-Service -Name chocolatey-central-management | Restart-Service

Chocolatey Agent Service is unable to communicate with Chocolatey Central Management Service.

There is a known issue with the beta release of Chocolatey Central Management where an inconsistent Port Number is used between these two services. One used 24020 and the other used 24040. The correct default Port Number is 24020, and this is used in the 0.1.0 release of Chocolatey Central Management. If required, the Port Number can be explicitly set during the installation of the Chocolatey Central Management packages using the following option when installing chocolatey-management-service:

--params="'/PortNumber=24020'"

Unable to report computer information to Chocolatey Central Management.

You may see messaging like the following in the chocolatey-agent.log:

[INFO ] - Creating secure channel to https://ccmserver:24020/ChocolateyManagementService ahead of CCM check-in...
[ERROR] - Unable to report computer information to CCM.:
 The message with Action 'http://tempuri.org/IChocolateyManagementService/report_computer_information' cannot be
 processed at the receiver, due to a ContractFilter mismatch at the EndpointDispatcher. This may be because of either a
 contract mismatch (mismatched Actions between sender and receiver) or a binding/security mismatch between the sender
 and the receiver.  Check that sender and receiver have the same contract and the same binding (including security
 requirements, e.g. Message, Transport, None).

This is due to having a Chocolatey Agent that is v0.10.0+ versus an older Chocolatey Central Management Service (< v0.2.0). Newer agents are incompatible because they use newer and more secure methods of communication. Please upgrade Chocolatey Central Management to v0.2.0+ at your earliest convenience. Or if you are on Chocolatey Central Management v0.3.0+, your agents need to be on v0.11.0+. Please refer to the Chocolatey Central Management Component Compatibility Matrix.

Unable to check for deployments from Chocolatey Central Management.

This will provide similar messaging as the above. The fix is the same, upgrade Chocolatey Central Management to v0.2.0+. Or if you are on Chocolatey Central Management v0.3.0+, your agents need to be on v0.11.0+. Please refer to the Chocolatey Central Management Component Compatibility Matrix. You may need to be on at least v0.3.0 and agents on v0.11.0+. If you are experiencing improper passphrase issues noted below, it means you need to likely upgrade to v0.3.0+ / v0.11.0 across your infrastructure.

We are seeing the error “attempted to call report_computer_information with an improper passphrase” in the Chocolatey Central Management service log.

If you are in the Chocolatey Central Management service logs, you may see the above error. This is a bug that was found with the communication of Chocolatey Central Management v0.2.0 and Chocolatey Agent v0.10.0. That was resolved in Chocolatey Central Management v0.3.0 and Chocolatey Agent v0.11.0. Please see the Chocolatey Central Management Component Compatibility Matrix and Licensed Issue #152 for more details.

The client reports successful check-in, but nothing is showing up in Chocolatey Central Management.

You need to check the Chocolatey Central Management service logs. The agent will always report success when it communicates with the service successfully. The service may reject what it receives, but due to security settings, it won’t tell the client about that.

The logs are located at $env:ChocolateyInstall\logs\ccm-service.log. If you are on a version of Chocolatey Central Management prior to 0.2.0, the log will be located at $env:ChocolateyInstall\lib\chocolatey-management-service\tools\service\logs\chocolatey.service.host.log.

A parameter cannot be found that matches parameter name KeyUsage.

This is a known issue with the beta release of Chocolatey Central Management regarding the creation of a self-signed certificate. You may see the error:

A parameter cannot be found that matches parameter name KeyUsage

This happens when installing Chocolatey Central Management on a machine that has PowerShell 4 or earlier. This is corrected in the 0.1.0 release of Chocolatey Central Management.

To work around this issue, you can use the following script to manually create a self-signed certificate, which will then be used to continue the installation:

$hostName = [System.Net.Dns]::GetHostName()
$domainName = [System.Net.NetworkInformation.IPGlobalProperties]::GetIPGlobalProperties().DomainName

if(-Not $hostName.endswith($domainName)) {
  $hostName += "." + $domainName
}

$certificateDnsName = $hostName

$newCert = New-SelfSignedCertificate -CertStoreLocation cert:\LocalMachine\My -DnsName $certificateDnsName

# move the certificate to 'TrustedPeople'
$certPath = Get-ChildItem -Path 'Cert:\\LocalMachine\\My' | Where-Object subject -like "*$certificateDnsName"
$null = Move-Item -Path $certPath.PsPath -Destination 'Cert:\\LocalMachine\\TrustedPeople'

The term ‘Install-ChocolateyAppSettingsJsonFile’ is not recognized as the name of a cmdlet, function, script file, or operable program.

In the beta version of the Chocolatey Licensed Extension, there was a cmdlet named Install-ChocolateyAppSettingsJsonFile and this was used in the 0.1.0-beta-20181009 release of the Chocolatey Central Management components. In the final released version of the Chocolatey Licensed Extension, this was renamed to Install-AppSettingsJsonFile.

As a result, the Chocolatey Central Management beta no longer works with the released version of Chocolatey Licensed Extension. This will be corrected once the next release of the Chocolatey Central Management components is completed.

Cannot process command because of one or more missing mandatory parameters: FilePath.

During the creation of Chocolatey Central Management, some additional PowerShell cmdlets were created, and these are installed as part of the Chocolatey Licensed Extension package. These cmdlets went through a number of iterations, and as a result, different combinations of Chocolatey Central Management packages were incompatible with the Chocolatey Licensed Extension package, resulting in the error:

Cannot process command because of one or more missing mandatory parameters: FilePath

The guidance in this case to update to the latest versions of all packages where the situation should be addressed.

The remote server returned an unexpected response: (413) Request Entity Too Large.

When reporting a larger number of packages (approximately 200), this error may be reported. This is due to the size of the information, in bytes, being too large to send between the Chocolatey Agent Service and the Chocolatey Central Management Service. This has been identified as a bug, which is due to be corrected in version 0.1.1 of Chocolatey Central Management.

ERROR: Cannot index into a null array.

This error can be reported when installing the Chocolatey Central Management Service. This can happen depending on the netsh bindings that are currently present on the machine that the Chocolatey Central Management service is being installed on. If, for example, you have enabled SNI on a website on the machine that you are installing onto, then this error may occur. This has been identified as a bug, which is due to be corrected in version 0.1.1 of Chocolatey Central Management.

This could also be when you are providing an existing certificate - this was identified as a bug and was fixed in Chocolatey Central Management v0.2.0.

There is a known issue with Chocolatey Central Management v.0.3.0 affecting at least French machines. Please reach out to Support if you are experiencing this (run choco support for options).

The new license is not being picked up.

You need to restart services and Chocolatey Central Management web to pick up the license. Here’s a handy script:

Get-Service chocolatey-* | Stop-Service
Get-Process -Name "ChocolateySoftware.ChocolateyManagement.Web.Mvc" -ErrorAction SilentlyContinue | Stop-Process
Get-Service chocolatey-* | Start-Service

Failed to generate a user instance of SQL Server due to failure in retrieving the user’s local application data path.

You may see the following: “System.Data.SqlClient.SqlException (0x80131904): Failed to generate a user instance of SQL Server due to failure in retrieving the user’s local application data path. Please make sure the user has a local user profile on the computer. The connection will be closed.”

This means you are attempting to attach a Local DB file as part of your connection. This is an invalid scenario. This could also mean that there is something wrong with your connection strings format in the appsettings.json file.

System.ServiceModel.AddressAccessDeniedException HTTP could not register URL.

You may see the following: System.ServiceModel.AddressAccessDeniedException: HTTP could not register URL https://+:24020/ChocolateyManagementService/. Your process does not have access rights to this namespace (see http://go.microsoft.com/fwlink/?LinkId=70353 for details). ---> System.Net.HttpListenerException: Access is denied

You are attempting to set up a user that is not in the local Administrators group with the Chocolatey Central Management Service. This is not a supported scenario.

Please refer to the Chocolatey Central Management Service Windows Account Considerations and select an option that works best for your organization.

Central Management Setup | Chocolatey Central Management