Skip to content

Commit 1df82fa

Browse files
steviecoastersteviecoaster
committed
(#1117) Add advanced parameter usage documentation
With this commit a new page has been created which provides examples for using the new parameters available to users when running the Register-C4bEndpoint.ps1 script on a new endpoint.
1 parent e84d71e commit 1df82fa

File tree

2 files changed

+129
-0
lines changed

2 files changed

+129
-0
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: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -314,6 +314,10 @@ export const callout4 = {
314314
* `AdditionalSources` - Allows for the addition of alternative sources after the base configuration has been applied.
315315
* `TrustCertificate` - If passed, downloads the certificate from the client server before initializing Chocolatey Agent
316316

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+
317321
### Conclusion
318322

319323
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)