-
Notifications
You must be signed in to change notification settings - Fork 227
(docs) Clarify how to manage backgroundServiceDisallowedOptions #1253
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -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`. | ||||||||||||||||||||||||||||||||||||||||
| </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
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||
| **Unset the configuration key** | ||||||||||||||||||||||||||||||||||||||||
| ```powershell | ||||||||||||||||||||||||||||||||||||||||
| choco config unset --name="'backgroundServiceDisallowedOptions'" | ||||||||||||||||||||||||||||||||||||||||
| ``` | ||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||
| **Explicitly set the default restricted options (Recommended)** | ||||||||||||||||||||||||||||||||||||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 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** | ||||||||||||||||||||||||||||||||||||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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)?
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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> | ||||||||||||||||||||||||||||||||||||||||
|
Comment on lines
+196
to
+205
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. To have it work when |
||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||
| ### See It In Action | ||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||
| * Chocolatey's Self-Service Installer - Part 1: | ||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
--sourceit would end up just besourcefor the option that is stored.There is already logic to prevent the options being specified using the
--before the name of the option.