Internet Setup
Internet Setup
:choco-info: NOTE
This document was written primarily for QDE v1.0.
The information it contains may still be helpful for you in later versions for troubleshooting and/or planning. In more recent versions of QDE, all of this required setup can be handled by the setup scripts packaged with the image.
See the following QDE v2.0+ documents for more information on how to handle this setup or certificate renewals in newer versions:
With an unprecedented amount of employees working from home, there is a much greater demand to serve their software lifecycle needs remotely. Thus, many organizations would like the option to make the Chocolatey Quick Deployment Environment (QDE) Internet-accessible. This document walks you through some options you will need to consider, if you choose this route.
:choco-warning: WARNING
This document assumes you have an understanding of the underlying principles behind SSL Certificates and Public Key Infrastructure. Therefore, it does not exhaustively cover these topics, but rather presents steps and examples of what you will need to accomplish. You should be able to manage certificates in your organizational environment before proceeding any further.
Firewall Considerations
When we talk about making QDE Internet-accessible, we are referring to exposing certain application ports on QDE via your VM/Organizational firewall:
- Chocolatey Central Management Service (24020): This port is used for communication between Chocolatey Agent on your endpoint and the Chocolatey Central Management (CCM) server.
- Sonatype Nexus repository (8443): This is the port on which endpoints will connect to your Nexus repository (over HTTPS), in order to download packages for install/upgrade.
There are, of course, additional applications and ports on the QDE server. In general, it is not required or may not be advisable to have these accessible externally:
- Chocolatey Central Management Dashboard (443) (HTTPS)
- Jenkins (8080) (HTTP)
You can access these via a Remote Desktop session on the QDE server itself, or opening these ports up to your internal network. Again, we strongly advise against opening these ports up to the public Internet for security reasons.
Further details on firewall changes can be found on the QDE Firewall Setup page.
SSL Certificate Setup
If you are planning to expose QDE to the Internet, it is essential to not use the default self-signed certificates generated for you. Rather, new ones should be generated. Some additional common reasons for this change are:
- If you change the hostname of this server.
- If you add QDE to a domain.
- If you have purchased your own SSL/TLS certificates or need to renew your own certificates that are already installed.
Essentially, in any scenario where the fully-qualified domain name (FQDN) of the QDE server has been modified, you will need to ensure that the "Subject/Common Name" attribute on the SSL certificates matches this FQDN. If you are making any of the above changes, please generate new SSL certificates after any changes to the FQDN have been completed.
The New-SSLCertificate.ps1
script in the "C:\choco-setup\files" folder on the QDE VM will:
- Generate new SSL certificates for your Nexus and CCM Service applications
- Move these certificates to the appropriate certificate stores
- Configure the Nexus and CCM services to use these certificates in communication with endpoints
: exclamation: IMPORTANT
If you are running QDE v1.0, there is a good chance that the current version of the
New-SSLCertificate.ps1
script in the "C:\choco-setup\files" folder on your QDE VM is out-of-date, as we have made numerous updates to it over the past few months. Please use the following command to update your version of this file (to be run in a PowerShell Administrator window):Invoke-WebRequest -Uri 'https://ch0.co/newssl' -OutFile "$env:SystemDrive\choco-setup\files\New-SSLCertificate.ps1"
This script can be utilized in multiple certificate scenarios outlined below. Any time this script is run, please be mindful of the warnings below.
:choco-warning: WARNING
- The
New-SSLCertificate.ps1
script will appear to prompt for input, and also display some misleading output. This is due to the nature of the Java tooling by which the script interacts with Nexus. Please ignore any spurious prompts and output.- If you provide your own SSL certificate, your private key needs to be exportable so that the script can export that key into Nexus' Java keystore. If the private key is not exportable, the script will fail to complete, and you will likely need to manually adjust the Nexus configuration to get it running again.
- Timezones and time synchronization are critically important when generating SSL Certificates. You'll want to ensure all hosts are utilizing the same NTP time source. Otherwise, it's possible to generate an SSL Certificate that a client may see as not yet valid.
SSL Certificate Scenarios
There are three possible approaches to acquiring SSL certificates for QDE:
- Scenario 1: Domain Server Certificates: This would be the domain server SSL certificate, generated on domain join and trusted by all endpoints on your domain.
- Scenario 2: Purchased/Acquired Certificates from CA: This would be an SSL certificate that you purchased or acquired from an external Certificate Authority (CA; e.g. LetsEncrypt).
- Scenario 3: Self-Signed SSL Certificates: This would be a self-generated SSL certificate, similar to the one that comes with QDE (least-desirable).
Each approach is discussed individually in the sections below.
Scenario 1: Domain Server Certificates
If you manage a Windows AD Domain, this is going to be the most common scenario. The majority of customers will want to join the QDE server to their domain, and possibly even change the hostname to match their organizational naming conventions. As this process will change your FQDN, this will need to be completed ahead of any other changes.
:choco-warning: WARNING
We are assuming you are able to manage certificates in your Active Directory (AD) domain environment. You should have a server with the Active Directory Certificate Services (AD CS) role in place, that can issue and mange digital certificates. A detailed explanation of Certificate Authorities is beyond the scope of this document.
The following prerequisites are required to be in place for later steps to be successful:
- Ensure that you join the QDE server to the domain first.
- Ensure that the FQDN of the QDE server is resolvable to its IP across your domain.
Once you have your new valid and resolvable FQDN for QDE, you will now want to ensure the domain server certificate associated with that FQDN is utilized for the Nexus and CCM services on QDE.
Open the "Certificates - Local Computer" MMC snap-in by pressing the Windows key, and when the Start menu pops up, type certificates. You should now see an option under the "Settings" section that says "Manage computer certificates". Alternatively, open the Run dialog (Windows key + R), type
certlm.msc
, and click "OK".Under the "Personal" store, you should see a server certificate matching the FQDN of your QDE server. Double-click on the certificate to open it, and under the details tab, copy out the
Thumbprint
value of the certificate. You will need this for later steps.Now, you can run the
New-SSLCertificate.ps1
script and pass the thumbprint you copied above using the-Thumbprint
parameter. Please run the below command from a PowerShell Administrator window:Set-ExecutionPolicy Bypass -Scope Process -Force; . C:\choco-setup\files\New-SSLCertificate.ps1 -Thumbprint '<YOUR_CERT_THUMBPRINT_HERE>'
(Optional) If some endpoints are not on the domain, or on a different domain, you will need to ensure that the Nexus and CCM certificates of QDE are copied to the
Local Computer\Trusted People\Certificates
store on those endpoints as well. If the endpoints connecting to Nexus and CCM are also on the same domain, this step may not be necessary as they will inherently trust the domain server certificate of the QDE server.
Scenario 2: Purchased/Acquired Certificates from CA
Organizations can also opt to purchase or acquire a certificate from an external Certificate Authority (CA; e.g. LetsEncrypt).
As mentioned before, you will need to ensure that the "Subject/Common Name" attribute on the SSL certificates matches the FQDN you are using.
For example, if you purchase an SSL certificate for your server with the "Subject/Common Name" attribute chocoserver.example.com
, you will of course need to ensure that you have a DNS record resolving chocoserver.example.com
to the external IP of your QDE server.
The steps involved in this scenario are similar to the Domain certificates above, with some slight adjustments:
Ensure that a DNS record exists, resolving the desired "Subject/Common Name" attribute from your purchased/acquired SSL certificate to its external IP address.
Import your certificate into the
Local Computer\Personal\Certificates
andLocal Computer\Trusted People\Certificates
stores on the QDE server. Open the "Certificates - Local Computer" MMC snap-in by pressing the Windows key, and when the Start menu pops up, type certificates. You should now see an option under the "Settings" section that says "Manage computer certificates". Alternatively, open the Run dialog (Windows key + R) and typecertlm.msc
and click "OK". Double-check to ensure that the SSL certificate you have purchased is placed in the correct stores, otherwise this process will not succeed.Under the "Personal" store, you should see a server certificate matching the FQDN of the certificate your QDE server. Double-click on the certificate to open it, and under the details tab, copy out the
Thumbprint
value of the certificate.Run the
New-SSLCertificate.ps1
script and pass the thumbprint you copied above using the-Thumbprint
parameter. Please run the below command from a PowerShell Administrator window:Set-ExecutionPolicy Bypass -Scope Process -Force; . C:\choco-setup\files\New-SSLCertificate.ps1 -Thumbprint '<YOUR_CERT_THUMBPRINT_HERE>'
(Optional) Assuming you've acquired your SSL certificate from an already-trusted Certificate Authority, your endpoints should trust this certificate natively. If you run into any issues with this, you may need to ensure that the QDE certificate is copied to the
Local Computer\Trusted People\Certificates
store on those endpoints as well.
Scenario 3: Self-Signed SSL Certificates
If you are planning to use self-signed SSL certificates to secure your communication with Nexus and CCM on QDE, then you will be required to run the New-SSLCertificate.ps1
script using the command above at least once.
As you will be exposing these two services via the Internet, you must make sure your certificates are unique and not the default certificates provided by the QDE image.
Ensure you have a valid DNS record for the
CHOCOSERVER
hostname of the QDE VM, that resolves to the external IP of QDE. If not, create a host record for the hostnameCHOCOSERVER
in your Windows HOSTS file on your endpoints. This is located at:“C:\Windows\System32\drivers\etc\hosts”
.Run the
New-SSLCertificate.ps1
script, from a PowerShell Administrator window:Set-ExecutionPolicy Bypass -Scope Process -Force; . C:\choco-setup\files\New-SSLCertificate.ps1
This scenario is the least desirable for an Internet-accessible setup, as you will likely have to perform steps manually on every endpoint. It is also less secure, and thus not recommended for a server that is Internet-accessible.
:choco-warning: SECURITY NOTE
As valid and widely-trusted SSL certificates are now available from CA's such as LetsEncrypt for free, there is no need to continue using self-signed certificates for Internet-accessible resources. For resources that are being utilized over the Internet, it's much safer to use a certificate that is signed by a trusted third party for SSL connections.
Nexus Setup
The New-SSLCertificate.ps1
mentioned above will create a Java KeyStore (JKS) version of an SSL certificate, that can be used to secure communication between your endpoints and your Nexus repositories.
As mentioned in the section above, this certificate will need to be trusted by your endpoints.
Additionally, when logging in and resetting your administrative credential in the Nexus web UI, there is a checkbox to allow "Anonymous" access. This is convenient for endpoints that will be accessing Nexus strictly from your internal network, but will need to be changed if you are planning to expose Nexus to your endpoints over the Internet. You can follow two paths to accomplish this:
Option 1: Scripted Nexus Configuration
:choco-info: NOTE
QDE v1 customers, please download the
Set-QDEnvironmentInternetSecurity.ps1
script and save it to theC:\choco-setup\files\
directory on your QDE instance. You can accomplish this with the following script:Invoke-WebRequest -Uri 'https://ch0.co/qdenetsec' -OutFile "$env:SystemDrive\choco-setup\files\Set-QDEnvironmentInternetSecurity.ps1"
Now, you will use Set-QDEnvironmentInternetSecurity.ps1
to update the scripts in your choco-install
Nexus raw repository to reflect the additional security measures you've implemented above.
Remember, it is required to pass your FQDN for your QDE server with the -FullyQualifiedDomainName
parameter.
:choco-warning: WARNING
This script will throw an error if you have logged into Nexus and changed your password from the default found in the README when you first got started with the appliance. If this is the case, add the
-NexusAdminPassword
parameter to the below command and supply the new password.
From an administrative PowerShell console, execute the following:
Set-ExecutionPolicy Bypass -Scope Process -Force ; . C:\choco-setup\files\Set-QDEnvironmentInternetSecurity.ps1 -FullyQualifiedDomainName '<YOUR_FQDN_HERE>' -PasswordLength 32 -SpecialCharCount 12
:choco-info: NOTE
- This script will emit random passwords for your nexus user, your client salt, and your service salt. Make sure you save these passwords for use when setting up your clients later.
- Now that you've added a credential to your Nexus repositories, access to the
ChocolateyInstall.ps1
andClientSetup.ps1
scripts in yourchoco-install
raw repository will require this credential as well.
Option 2: Manual Configuration of Nexus
Login to the Nexus Web UI and authenticate as your
admin
user. Select the gear icon at the top middle of the screen, to access the "Server administration and configuration" view.Show Animation
Under the
Security
sidebar menu, selectRoles
. Then click theCreate role
button, and chooseNexus role
in the dropdown menu.Show Animation
Set the
Role ID
andRole name
values to something reflecting the purpose of the role; for example,chocorole
.Show Animation
Now you need to ensure that users of this Role can browse and read the relevant source feeds. Under the
Privileges
section, double-click the following options to add them to theGiven
section:nx-repository-view-nuget-*-browse
nx-repository-view-nuget-*-read
nx-repository-view-raw-*-browse
nx-repository-view-raw-*-browse
Show Animation
Click the
Create role
button to create the role.Show Animation
We will now add a User to this Role. Under the
Security
sidebar menu, selectUsers
, then click theCreate local user
button. Fill in the ID, First name, Last name, and Email fields as desired (e.g.chocouser
). Create a secure Password for this user. Set the Status toActive
.Show Animation
In the Roles section, double-click the
chocorole
Role to to add it to theGranted
section. Click theCreate local user
button to create your user.Show Animation
Under the
Security
sidebar menu, selectAnonymous Access
. Un-check the box next to the optionAllow anonymous users to access the server
, and clickSave
.Show Animation
On your endpoints, you can now set up your internal source repository using this newly created
chocouser
credential. The below command is an example; please adjust according to your FQDN, repository name, and user credential created:choco source add --name "'ChocolateyInternal'" --source "'https://chocoserver:8443/repository/ChocolateyInternal/'" --user='chocouser' --password='YOUR_PASSWORD' --allow-self-service
CCM Setup
:choco-info: NOTE
If you ran option 1 above (Scripted Nexus Configuration), you can skip this step, as the configuration has already been applied to the server.
QDE V1 does not currently include the most up-to-date version of the CCM packages (version 0.3.0, as of this writing). If you have already purchased your Chocolatey for Business (C4B) license, or have a current trial license, you can upgrade by following the Central Management Upgrade documentation.
An additional mechanism of security that is highly recommended is the addition of salt additives to the encrypted communication between your endpoints and the CCM Service.
As we know, communication from the endpoints to CCM occurs over port 24020, and is secured by SSL certificates.
Adding a salt additive on both ends further hashes this encrypted data, and provides another layer of verification.
These salt additives should be at least 8 characters, and you will need to provide both additives on the CCM server and endpoint ends when setting up your communication.
These are both configuration items that can be set using the choco config
command, as shown in the example here:
choco config set --name centralManagementClientCommunicationSaltAdditivePassword --value 'YourSuperSecureSalt1'
choco config set --name centralManagementServiceCommunicationSaltAdditivePassword --value 'YourSuperSecureSalt2'
Further details on configuring CCM, and all available settings, can be found in the Central Management Client Setup documentation.
In the next section, you will need to incorporate both these salt additives into the script that helps you set up your endpoint clients.
Adjusting Scripts for Client Setup
On-boarding endpoints into CCM will require the running of a ClientSetup.ps1
script on those endpoints.
: exclamation: IMPORTANT
If you are running QDE v1.0, there is a good chance that the current version of the
ClientSetup.ps1
script in the "C:\choco-setup\files" folder on your QDE VM is out-of-date, as we have made numerous updates to it over the past few months. Please use the following command to update your version of this file (to be run in a PowerShell Administrator window):Invoke-WebRequest -Uri 'https://ch0.co/clientsetup' -OutFile "$env:SystemDrive\choco-setup\files\ClientSetup.ps1"
This new ClientSetup.ps1 script will also need to be uploaded to your Nexus instance before attempting to install and configure Chocolatey on a client.
Please be sure to insert the following values before running the script below:
$RepositoryUrl
: This is the "ChocolateyInternal" Nexus repository URL on the QDE server, where the Nexus repositories are. You must supply this parameter in QDE V1.$Credential
: This is thechocouser
credential used to connect to Nexus that we specified earlier in Nexus Setup. You can generate this ahead of time via a command like$Credential = Get-Credential
$ClientSalt
: This is the client-side salt additive we discussed in the CCM Setup section above.$ServerSalt
: This is the server-side salt additive we discussed in the CCM Setup section above.
Because this script is stored on your Nexus instance, and clients will need to authenticate to Nexus in order to download and execute the script, the following code can be run using any tool which can run PowerShell, so long as it is run in an elevated context.
An example of running this script with the requisite parameters on an endpoint is as follows (to be run from a PowerShell Administrator window):
# CHANGE THESE VALUES!
$clientCommunicationSalt = '2iLYko*f9y9kiv!Aw7kpZhBz7RnWQVHg' # example 32 character password. MUST BE UNIQUE
$serverCommunicationSalt = '[email protected]*.UyHx!-qrw4kWvwrT!' # example 32 character password. MUST BE UNIQUE
$fqdn = 'chocoserver' # If you have adjusted your FQDN, you HAVE to CHANGE this to reflect that
$password = 'x3mrj3NbGtkZBzJatLe9AcUtT8G_Y4Ra' # example 32 character password
# Touch NOTHING below this line
$user = 'chocouser'
$securePassword = $password | ConvertTo-SecureString -AsPlainText -Force
$repositoryUrl = "https://$($fqdn):8443/repository/ChocolateyInternal/"
$credential = [pscredential]::new($user, $securePassword)
$downloader = [System.Net.WebClient]::new()
$downloader.Credentials = $credential
$script = $downloader.DownloadString("https://$($fqdn):8443/repository/choco-install/ClientSetup.ps1")
$params = @{
Credential = $credential
ClientSalt = $clientCommunicationSalt
ServerSalt = $serverCommunicationSalt
InternetEnabled = $true
RepositoryUrl = $repositoryUrl
}
& ([scriptblock]::Create($script)) @params
This script will accomplish the following:
- Install Chocolatey from the installation script hosted in your internal raw Nexus repository
- Add the
ChocolateyInternal
source, and enable it for self-service - Disable the default
Chocolatey
Community Repository on your endpoints - Install your Chocolatey license using the
chocolatey-license
package you created - Install the Chocolatey Licensed Extension (without context menus for Package Builder)
- Install the
ChocolateyGUI
package on the endpoint, for self-service support - Install the
chocolatey-agent
package, which supports self-service and CCM communication - Enable and disable features related to configuring self-service access on the endpoint
- Setup the communication channel between the endpoint and CCM, using the correct URL and salts
- Opt the endpoint into CCM Deployments
Jenkins
The Jenkins open source automation server application is installed on QDE, and available locally on the VM at port 8080 (http://localhost:8080). As this is a local website, and accessible over HTTP, it is our recommendation to just utilize the tool locally on the VM itself, instead of making it accessible elsewhere.
If you must open up access to Jenkins internally, we advise you to review the following documentation in order to better secure that access:
:choco-warning: WARNING
As Jenkins is more of a "set-and-forget" service, we strongly advise you do not open up access to the Jenkins web console, but rather just use the web console on the QDE VM itself as needed. If you must, we recommend you only access it over your internal network, or via a VPN.