Skip to content

Commit 363b57b

Browse files
st3phhaysst3phhays
authored
Merge pull request #1118 from steviecoaster/gh1117
Provide additional documentation for advance parameter usage with Register-C4bEndpoint.ps1
2 parents e04c73b + 1df82fa commit 363b57b

File tree

2 files changed

+144
-1
lines changed

2 files changed

+144
-1
lines changed

‎src/content/docs/en-us/c4b-environments/quick-start-environment/advanced-client-configuration.mdx

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
order: 21
3+
xref: qsg-advanced-endpoint-config
4+
title: Advanced Endpoint Configuration
5+
description: Deploy Chocolatey for Business from a Quick Start Environment with advanced configuration options.
6+
---
7+
import Callout from '@choco/components/Callout.astro';
8+
import Iframe from '@choco/components/Iframe.astro';
9+
import Xref from '@components/Xref.astro';
10+
11+
The minimum configuration for a Chocolatey for Business client installs, licenses, and configurations Chocolatey to work with the deployed repository solution and Chocolatey Central Management.
12+
While this opinionated approach is fine for most situations, flexibility is required for some organizations. This page provides examples of different scnenarios in which you wish to deploy Chocolatey in your organization.
13+
14+
<Callout type="info">
15+
All examples require you to provide the credentials to connect to the repository installed during execution of the Quickstart Guide.
16+
17+
These credentials are found in the REAME file placed on the Desktop of the server during installation, or wherever you documented them if you changed them after installtion.
18+
</Callout>
19+
## Include Packaging Tools with installation
20+
21+
Some members of your team may be responsible for maintaining Chocolatey packages in your organization. These tools can be included in the installation by providing the `-IncludePackageTools` parameter.
22+
23+
```powershell
24+
Set-Location /path/to/register-c4bendpoint.ps1
25+
. .\Register-C4bEndpoint.ps1 -RepositoryCredential (Get-Credential) -IncludePackageTools
26+
```
27+
28+
## Enable/Disable additional features with installation
29+
30+
Some endpoints may require a different set of features. The default installation will apply our _recommended_ configuration.
31+
However, you can override these defaults or enable/disable additional features by providing the `-AdditionalFeatures` parameter.
32+
33+
In this example we will disable the use of the background service so non-admin users cannot use Chocolatey (not recommended), and enable Gloabl Confirmation so you no longer need to pass -y when performing a package operation.
34+
35+
```powershell
36+
Set-Location /path/to/register-c4bendpoint.ps1
37+
. .\Register-C4bEndpoint.ps1 -RepositoryCredential (Get-Credential) -AdditionalFeatures @{ useBackgroundService = 'Disabled'; allowGlobalCOnfirmation = 'Enabled' }
38+
```
39+
40+
## Apply custom configuration during installation
41+
42+
You can apply custom configuration which overrides the defaults or provides additional configuration by providing the `-AdditionalConfiguration` parameter.
43+
The following example sets the `centralManagementReportPackagesTimerIntervalInSeconds` configuration item to 21600 seconds (6 hours).
44+
45+
```powershell
46+
Set-Location /path/to/register-c4bendpoint.ps1
47+
. .\Register-C4bEndpoint.ps1 -RepositoryCredential (Get-Credential) -AdditionalConfiguration @{ 'centralManagementReportPackagesTimerIntervalInSeconds' = '21600'}
48+
```
49+
50+
## Include additional Chocolatey sources
51+
52+
You can include additional Chocolatey sources during the installation process by providing the `-AdditionalSources` parameter.
53+
54+
#### Include a group repository source
55+
In this example we will add a new source called Engineering, which is a group source configured on the repository server
56+
that contains a repository for Engineering-specific packages, with a base repository of general use packages.
57+
58+
```powershell
59+
Set-Location /path/to/register-c4bendpoint.ps1
60+
. .\Register-C4bEndpoint.ps1 -RepositoryCredential (Get-Credential) -AdditionalSources @{Name = 'Engineering'; Source = 'https://repo.fabrikam.com/repository/EngineeringGroup/index.json'}
61+
```
62+
63+
#### Include a local source
64+
65+
<Callout type="warning">
66+
The local folder must exist prior to using this source.
67+
</Callout>
68+
69+
This example include Packaging Tools and sets up a local folder source for package development testing.
70+
71+
```powershell
72+
Set-Location /path/to/register-c4bendpoint.ps1
73+
. .\Register-C4bEndpoint.ps1 -RepositoryCredential (Get-Credential) -IncludePackageTools -AdditionalSources @{Name = 'LocalTest'; Source = 'C:\packages\testing'}
74+
```
75+
76+
#### Available options
77+
78+
The following is a sample hashtable of all the available options you can pass while adding additional sources.
79+
80+
```powershell
81+
@{
82+
Name = 'MySource'
83+
Source = 'https://nexus.fabrikam.com/repository/MyChocolateySource'
84+
#Optional items
85+
Credentials = $MySourceCredential
86+
AllowSelfService = $true # Defaults to $false
87+
AdminOnly = $true # Defaults to $false
88+
BypassProxy = $true # Defaults to $false
89+
Priority = 10
90+
Certificate = 'C:\cert.pfx'
91+
CertificatePassword = 's0mepa$$'
92+
}
93+
```
94+
95+
## Install additional packages
96+
97+
You can install additional Chocolatey packages during the installation process by providing the `-AdditionalPackages` parameter.
98+
99+
<Callout type="warning">
100+
To use this parameter, you must ensure that the package is available on configured sources.
101+
</Callout>
102+
103+
#### Install the latest version of the notepadplusplus.install package
104+
The following example installs the notepadplusplus.install package.
105+
106+
```powershell
107+
Set-Location /path/to/register-c4bendpoint.ps1
108+
. .\Register-C4bEndpoint.ps1 -RepositoryCredential (Get-Credential) -AdditionalPackages @{Id ='notepadplusplus.install'}
109+
```
110+
111+
#### Install a specific version of the notepadplusplus.install package
112+
The following example installs version 8.7.5 of the notepadplusplus.install package.
113+
114+
```powershell
115+
Set-Location /path/to/register-c4bendpoint.ps1
116+
. .\Register-C4bEndpoint.ps1 -RepositoryCredential (Get-Credential) -AdditionalPackages @{Id ='notepadplusplus.install'; Version = '8.7.5'}
117+
```
118+
119+
#### Install a specific version of the notepadplusplus.install package, and pin it so it does not upgrade automaticallyThe following example installs version 8.7.5 of the notepadplusplus.install package and pins it so that it is not upgraded when using `choco upgrade`
120+
To upgrade this package, you will need to first unpin it, and then perform the upgrade.
121+
122+
```powershell
123+
Set-Location /path/to/register-c4bendpoint.ps1
124+
. .\Register-C4bEndpoint.ps1 -RepositoryCredential (Get-Credential) -AdditionalPackages @{Id ='notepadplusplus.install'; Version = '8.7.5'; Pin = $true}
125+
```

‎src/content/docs/en-us/c4b-environments/quick-start-environment/chocolatey-for-business-quick-start-guide.mdx

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -283,7 +283,7 @@ export const callout4 = {
283283
```powershell
284284
Set-ExecutionPolicy Bypass -Scope Process -Force
285285
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::tls12
286-
.\Register-C4bEndpoint.ps1
286+
.\Register-C4bEndpoint.ps1 -RepositoryCredential (Get-Credential) # Will prompt for username and password. Values found in README on Server Desktop.
287287
```
288288

289289
> <details>
@@ -300,6 +300,24 @@ export const callout4 = {
300300
> </ul>
301301
> </details>
302302
303+
#### Available parameters
304+
305+
* `ClientCommunicationSalt` - Chocolatey Central Management Client Communication Salt Additive - The salt additive to use in the salt recipe for encrypting and verifying communication from an agent TO an instance of Central Management Service (will need to be set the same on all clients contacting that service AND the instance of the management service itself). When not set a default encryption phrase set by the system will be used. When set the unencrypted value must match exactly with what is set in the configuration for Central Management Service and every client contacting that instance of Central Management Service. Value is not shared over the wire. Because this is a much more involved process, it is recommended only setting this if you are transmitting messages over the internet. Defaults to ''. Needs to be at least 8 characters long if set or it will throw errors and use the default. Available in business editions only. IMPORTANT: If this value is set, agents less than v0.10.0 will be unable to contact Central Management to report in.
306+
* `ServiceCommunicationSalt` -Chocolatey Central Management Service Communication Salt Additive - The salt additive to use in the salt recipe for encrypting and verifying communication FROM an instance of Central Management Service to an agent (will need to be set the same on all clients contacting that service AND the instance of the management service itself). When not set a default encryption phrase set by the system will be used. When set the unencrypted value must match exactly with what is set in the configuration for Central Management Service and every client contacting that instance of Central Management Service. Value is not shared over the wire. Because this is a much more involved process, it is recommended only setting this if you are transmitting messages over the internet. Defaults to ''. Needs to be at least 8 characters long if set or it will throw errors and use the default. Available in business editions only.
307+
* `RepositoryCredential` - The credential to use to access the repository server from the endpoint. Details available from README file on server desktop.
308+
* `ProxyUrl` - The URL of a proxy server to use for connecting to the repository.
309+
* `ProxyCredential` - The credentials, if required, to connect to the proxy server.
310+
* `IncludePackageTools` - Install the Chocolatey Licensed Extension with right-click context menus available
311+
* `AdditionalConfiguration` - Allows for the application of user-defined configuration that is applied after the base configuration.
312+
* `AdditionalFeatures` - Allows for the toggling of additional features that is applied after the base configuration.
313+
* `AdditionalPackages` - Allows for the installation of additional packages after the system base packages have been installed.
314+
* `AdditionalSources` - Allows for the addition of alternative sources after the base configuration has been applied.
315+
* `TrustCertificate` - If passed, downloads the certificate from the client server before initializing Chocolatey Agent
316+
317+
#### Advanced Endpoint Configuration
318+
319+
It is possible to customize the installtion of Chocolatey on an endpoint via the available parameters above. For examples, please see <Xref title='Advanced Endpoint Configuration' value='qsg-advanced-endpoint-config'/>
320+
303321
### Conclusion
304322

305323
Congratulations! If you followed all the steps detailed above, you should now have a fully functioning Chocolatey for Business implementation deployed in your environment.

0 commit comments

Comments
 (0)