Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions src/content/docs/en-us/features/self-service-anywhere.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,44 @@ To help minimize issues and improve security, the following options, along with
If a user attempts to configure any of these options through `choco config`, Chocolatey CLI returns an error. These options are required for reliable Background Service operation and must remain unrestricted.
</Callout>

### Common Configuration Options

<Callout type="info">
While the different options above have been specified using their `--` prefix, only the name of each option should be specified when setting them through `choco config`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is context here I am missing? Apologies. Without that context, I don't understand this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The context is that the easiest/best way that were found to restrict configurable options where to use them without having a prefix. So for instance instead of --source it would end up just be source for the option that is stored.

There is already logic to prevent the options being specified using the -- before the name of the option.

</Callout>

Normally there is no need to change the default options that are restricted through the Background Service, and the defaults will be sufficient for most.

If the default options had been overridden at one point, and there is a need to reset these to the default restricted options, this can be done in two different ways.
We recommend using the below explicit option.
Comment on lines +175 to +178
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Normally there is no need to change the default options that are restricted through the Background Service, and the defaults will be sufficient for most.
If the default options had been overridden at one point, and there is a need to reset these to the default restricted options, this can be done in two different ways.
We recommend using the below explicit option.
The default value for `backgroundServiceDisallowedOptions` will be sufficient for most organizational needs.
If the configuration has been set, you can reset it to the default value in two different ways. **Note the option we recommend.**


**Unset the configuration key**
```powershell
choco config unset --name="'backgroundServiceDisallowedOptions'"
```

**Explicitly set the default restricted options (Recommended)**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this the recommended way?

If we change the default values in future, we will have to change the docs to match. Would "unsetting" the configuration value not always reset it back to the current default values (when I say current, I mean whatever the default values for the version being used to run the config command is)?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I marked this as the recommended way (I don't think it has ever been discussed) due to if someone calls choco config unset then if they in the future do choco config get, the value returned will be empty.

The default values will still be used, it just isn't surfaced to the user if it has been unset.

```powershell
choco config set --name="'backgroundServiceDisallowedOptions'" --value="'allowemptychecksum,allowemptychecksums,allow-empty-checksums,allowemptychecksumsecure,allowemptychecksumssecure,allow-empty-checksums-secure,applyargstodependencies,apply-args-to-dependencies,apply-install-arguments-to-dependencies,argsglobal,args-global,cache,cachelocation,cache-location,checksum,checksum64,checksumx64,dir,directory,downloadchecksum,download-checksum,downloadchecksumx64,download-checksum-x64,fromprograms,from-programs,fromprogramsandfeatures,from-programs-and-features,ia,ignorechecksum,ignore-checksum,ignorechecksums,ignore-checksums,ignore-pinned,installargs,install-args,installargsglobal,install-args-global,installarguments,install-arguments,install-arguments-sensitive,installdir,install-dir,installdirectory,install-directory,override,overrideargs,overridearguments,override-arguments,proxy,proxy-bypass-list,proxy-bypass-on-local,s,skipvirus,skip-virus,skipviruscheck,skip-virus-check,source,svc,trace,ua,uninstallargs,uninstallarguments,uninstall-arguments,uninstall-arguments-sensitive,use-system-powershell,viruspositivesmin,virus-positives-minimum'"
```

**Append new restricted options**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there precedent to using bold headings like this rather than H headings (ie. H3 / 4)?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mainly used bold headings in this PR to be consistent in this file.

The previous PR that I submitted I had also used bold items when there were headers. Mainly because I didn't really consider these headers, but just wanted to emphasize it a bit.

To be able to add additional restricted options, for instance prohibit the use of the `--force` option, it is needed to include all of the existing restricted options including the options you wish to add to the list.

It is recommended to get the existing list of restricted options before attempting to set an updated list.
This can be achieved by using something similar to the below PowerShell example script.
Comment on lines +191 to +194
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To be able to add additional restricted options, for instance prohibit the use of the `--force` option, it is needed to include all of the existing restricted options including the options you wish to add to the list.
It is recommended to get the existing list of restricted options before attempting to set an updated list.
This can be achieved by using something similar to the below PowerShell example script.
To be able to add additional restricted options, for instance to prohibit the use of the `--force` option, it is needed to include _all_ the existing restricted options and then add the options you wish to. This can be achieved by using the below PowerShell example code.


```powershell
$existingOptions = & choco config get --name="'backgroundServiceDisallowedOptions'" --limit-output
$updatedOptions = "$existingOptions,f,force" # Add the -f and --force to the existing restricted options variable.
choco config set --name="'backgroundServiceDisallowedOptions'" --value="'$updatedOptions'"
```

<Callout type="info">
If the configuration value has previously been `unset`, appending the new options in the suggested approach above is not possible as `choco config get` will return the empty value.
Instead, you will need to be explicit as shown in the _Explicitly set the default restricted options_ example.
</Callout>
Comment on lines +196 to +205
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
```powershell
$existingOptions = & choco config get --name="'backgroundServiceDisallowedOptions'" --limit-output
$updatedOptions = "$existingOptions,f,force" # Add the -f and --force to the existing restricted options variable.
choco config set --name="'backgroundServiceDisallowedOptions'" --value="'$updatedOptions'"
```
<Callout type="info">
If the configuration value has previously been `unset`, appending the new options in the suggested approach above is not possible as `choco config get` will return the empty value.
Instead, you will need to be explicit as shown in the _Explicitly set the default restricted options_ example.
</Callout>
<Callout type="info">
If the configuration value is empty, appending the new options using the code below will not work `choco config get` will return the empty value.
Instead, you will need to be explicit as shown in the _Explicitly set the default restricted options_ example, above.
</Callout>
```powershell
$existingOptions = & choco config get --name="'backgroundServiceDisallowedOptions'" --limit-output
$updatedOptions = "$existingOptions,f,force" # Add the -f and --force to the existing restricted options variable.
choco config set --name="'backgroundServiceDisallowedOptions'" --value="'$updatedOptions'"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should look at making this code work for either use case (i.e. if get returns nothing or returns something)?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To have it work when get doesn't return anything, that would just be same same as the previous example that set all of the default options (and then append the new options).


### See It In Action

* Chocolatey's Self-Service Installer - Part 1:
Expand Down