From ad064654bb5e2335ecccc5cd22b5c07d60c64406 Mon Sep 17 00:00:00 2001 From: iSazonov Date: Thu, 25 Jan 2018 13:48:22 +0300 Subject: [PATCH 1/5] PowerShell Core configuration --- 1-Draft/RFCnnnn-PowerShell-Configuration.md | 175 ++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 1-Draft/RFCnnnn-PowerShell-Configuration.md diff --git a/1-Draft/RFCnnnn-PowerShell-Configuration.md b/1-Draft/RFCnnnn-PowerShell-Configuration.md new file mode 100644 index 00000000..a3922a82 --- /dev/null +++ b/1-Draft/RFCnnnn-PowerShell-Configuration.md @@ -0,0 +1,175 @@ +--- +RFC: RFCnnnn +Author: Ilya Sazonov +Status: Draft +SupercededBy: N/A +Version: 0.1 +Area: Engine +Comments Due: 2/25/2018 +--- + +# `PowerShell Core` configuration + +## Motivation + +Consumers, developers, and enterpsise system administrators should be able to flexibly and conveniently configure PowerShell Core and applications based on it. + +The public PowerShell Core configuration API allows to use unified configuration means and to manage PowerShell-based applications in a consistent manner. + +## Specification + +`PowerShell Core` is configured using the following schemes: + +- On Windows - Group Policy Objects (GPO), Group Policy Preferences (GPP) and settings files. +- On Unix - settings files. + +The settings files have `Json` format. + +**Caution!** The settings files differ from `PowerShell Core` _profile_ files that are PowerShell scripts. + +Configuration schemes allow to customize `PowerShell Core` in the most flexible way: + +- Enterprise system administrators can use GPO, GPP and computer-wide settings files to apply approved configuration settings and mandatory security settings in a centralized manner. The same settings can be applied at user, application or startup levels. +- Developers and consumers can use user, application and startup level settings files. + +### Settings locations + +`PowerShell Core` settings are grouped into `Policy settings` and `Regular settings`. Regular settings are normal configuration settings. Regular settings can be treated as default values. Policy settings is high priority and overlap regular settings. Policy settings are used by administrators to centrally manage applications. + +Location | Policy settings | Regular settings +- | - | - +File section | "PowerShell": { "PolicySettings": {...} } | "PowerShell": { "RegularSettings": {...} } +File section | "OtherPowerShellApplication": { "PolicySettings": {...} } | "OtherPowerShellApplication": { "RegularSettings": {...} } +Registry key | Software\Policies\PowerShellCore | Software\PowerShellCore +Registry key | Software\Policies\PowerShellCore\OtherPowerShellApplication | Software\PowerShellCore\OtherPowerShellApplication + +### Priority of applying settings + +Because a configuration setting can be in several schemes, the setting wins according to the priority of its scheme. + +#### Priorities for Policy settings in descending order + +Scheme | Windows | Unix +-| - | - +GPO -> Computer Policy | HKLM\Software\Policies\PowerShellCore | /etc/powershell.config.json +GPO -> User Policy | HKCU\Software\Policies\PowerShellCore | See `Comment A` below +File -> Computer-Wide | %ProgramFiles%/PowerShell/powershell.config.json | /opt/Microsoft/powershell/powershell.config.json +File -> User-Wide | %APPDATA%/powershell.config.json | ~/powershell.config.json +File -> Application-Wide | $apphome/powershell.config.json | $apphome/powershell.config.json +File -> Application-Startup | pwsh -settingsfile `somepath/powershell.config.json` | pwsh -settingsfile `somepath/powershell.config.json` + +#### Priorities for Regular settings in descending order + +Scheme | Windows | Unix +-| - | - +File -> Application-Startup | pwsh -settingsfile `somepath/powershell.config.json` | pwsh -settingsfile `somepath/powershell.config.json` +File -> Application-Wide | $apphome\powershell.config.json | $apphome/powershell.config.json +File -> User-Wide | %APPDATA%\powershell.config.json | ~/powershell.config.json +File -> Computer-Wide | %ProgramFiles%\PowerShell\powershell.config.json | /opt/Microsoft/powershell/powershell.config.json +GPO -> User Config | HKCU\Software\PowerShellCore | See `Comment A` below +GPO -> Computer Config | HKLM\Software\PowerShellCore | /etc/powershell.config.json + +### Configuration settings + +A set of configuration settings in GPO scheme and file scheme for policy settings and regular settings is the same. This allows to discover and configure settings in the simplest and fastest way. + +#### Registry keys and settings + +| Key | SubKey | Option | Type +| -| - | - | - +Software\Policies\PowerShellCore | - | - +Software\PowerShellCore | - | - +| | | ExecutionPolicy | String +| | | PipelineMaxStackSizeMB | DWORD +| | ConsoleSessionConfiguration | EnableConsoleSessionConfiguration | DWORD +| | ConsoleSessionConfiguration | ConsoleSessionConfigurationName | String +| | ModuleLogging | EnableModuleLogging | DWORD +| | ModuleLogging | ModuleNames | String +| | ProtectedEventLogging | EncryptionCertificate | DWORD +| | ScriptBlockLogging | EnableScriptBlockInvocationLogging | DWORD +| | ScriptBlockLogging | EnableScriptBlockLogging | DWORD +| | Transcription | EnableTranscripting | DWORD +| | Transcription | EnableInvocationHeader | DWORD +| | Transcription | OutputDirectory | String +| | UpdatableHelp | DefaultSourcePath | String +|Software\Policies\Microsoft\Windows\EventLog | ProtectedEventLogging | EnableProtectedEventLogging | DWORD + +#### Json file settings format + +```json +{ + "PowerShell": { + "RegularSettings": { + "ConsoleSessionConfiguration": { + "EnableConsoleSessionConfiguration": true, + "ConsoleSessionConfigurationName": "name" + }, + "ProtectedEventLogging": { + "EnableProtectedEventLogging": false, + "EncryptionCertificate": [ + "Joe" + ] + }, + "ScriptBlockLogging": { + "EnableScriptBlockInvocationLogging": true, + "EnableScriptBlockLogging": false + }, + "ScriptExecution": { + "ExecutionPolicy": "RemoteSigned", + "PipelineMaxStackSizeMB": 10 + }, + "Transcription": { + "EnableTranscripting": true, + "EnableInvocationHeader": true, + "OutputDirectory": "c:\\tmp" + }, + "UpdatableHelp": { + "DefaultSourcePath": "f:\\temp" + } + }, + + "PoliciesSettigs": { + ... + } + }, + + "OtherPowerShellApplication": { + "RegularSettings": { + ... + }, + "PolicySettings": { + ... + } +} +``` + +## Alternate Proposals and Considerations + +We could redesign `-settingsfile` startup parameter. If we'd support configuration sections for applications we'd can introduce `-settings` parameter to specify a particular configuration as `-settings OtherPowerShellApplication`. Ex.: `pwsh -settings Debug`. + +### Comment A + +Mainly for Unix we'd add `Users` section to computer wide Json file (`/etc/powershell.config.json`) to allow administrators set policies and regular settings on user level base + +```json +{ + "PowerShell": { + "RegularSettings": { + ... + }, + "PolicySettings": { + ... + }, + "Users": { + "Smith": { + "PowerShell": { + "RegularSettings": { + ... + }, + "PolicySettings": { + ... + } + } + } +} +``` From b1b1df5db45a3e0cba677975d921604bde22f579 Mon Sep 17 00:00:00 2001 From: iSazonov Date: Thu, 29 Mar 2018 12:18:23 +0300 Subject: [PATCH 2/5] Fix typo. --- 1-Draft/RFCnnnn-PowerShell-Configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-Draft/RFCnnnn-PowerShell-Configuration.md b/1-Draft/RFCnnnn-PowerShell-Configuration.md index a3922a82..7f1ac92d 100644 --- a/1-Draft/RFCnnnn-PowerShell-Configuration.md +++ b/1-Draft/RFCnnnn-PowerShell-Configuration.md @@ -128,7 +128,7 @@ Software\PowerShellCore | - | - } }, - "PoliciesSettigs": { + "PoliciesSettings": { ... } }, From a209f4d39c44d8476aa62c63ef3c8313007b36d7 Mon Sep 17 00:00:00 2001 From: iSazonov Date: Wed, 21 Nov 2018 11:44:15 +0500 Subject: [PATCH 3/5] Address feedbacks --- 1-Draft/RFCnnnn-PowerShell-Configuration.md | 26 ++++++++++++++------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/1-Draft/RFCnnnn-PowerShell-Configuration.md b/1-Draft/RFCnnnn-PowerShell-Configuration.md index 7f1ac92d..48fe1ac4 100644 --- a/1-Draft/RFCnnnn-PowerShell-Configuration.md +++ b/1-Draft/RFCnnnn-PowerShell-Configuration.md @@ -12,9 +12,9 @@ Comments Due: 2/25/2018 ## Motivation -Consumers, developers, and enterpsise system administrators should be able to flexibly and conveniently configure PowerShell Core and applications based on it. +Consumers, developers, and enterprise system administrators should be able to flexibly and conveniently configure PowerShell Core and applications based on it. -The public PowerShell Core configuration API allows to use unified configuration means and to manage PowerShell-based applications in a consistent manner. +A public PowerShell Core configuration API would allow a unified way to manage PowerShell-based applications in a consistent manner. ## Specification @@ -23,9 +23,9 @@ The public PowerShell Core configuration API allows to use unified configuration - On Windows - Group Policy Objects (GPO), Group Policy Preferences (GPP) and settings files. - On Unix - settings files. -The settings files have `Json` format. +The settings files have `JSON` format. -**Caution!** The settings files differ from `PowerShell Core` _profile_ files that are PowerShell scripts. +**Warning** The settings files differ from `PowerShell Core` _profile_ files, which are PowerShell scripts run at startup. Configuration schemes allow to customize `PowerShell Core` in the most flexible way: @@ -54,9 +54,19 @@ Scheme | Windows | Unix GPO -> Computer Policy | HKLM\Software\Policies\PowerShellCore | /etc/powershell.config.json GPO -> User Policy | HKCU\Software\Policies\PowerShellCore | See `Comment A` below File -> Computer-Wide | %ProgramFiles%/PowerShell/powershell.config.json | /opt/Microsoft/powershell/powershell.config.json -File -> User-Wide | %APPDATA%/powershell.config.json | ~/powershell.config.json -File -> Application-Wide | $apphome/powershell.config.json | $apphome/powershell.config.json File -> Application-Startup | pwsh -settingsfile `somepath/powershell.config.json` | pwsh -settingsfile `somepath/powershell.config.json` +File -> User-Wide | %APPDATA%/powershell.config.json | %XDG_CONFIG_HOME%/powershell.config.json +File -> Application-Wide | $apphome/powershell.config.json | $apphome/powershell.config.json + +Defaults: + +`%APPDATA%` - `C:\Users\useraccount\AppData\Roaming` + +`%XDG_CONFIG_HOME%` - `HOME/.config` + +#### Parameter `-settingsfile` + +With `-settingsfile` parameter users can assign custom settings from the config file and overwrite user-wide and application-wide settings. Only users with elevated rights can overwrite computer-wide and user policy settings. #### Priorities for Regular settings in descending order @@ -94,7 +104,7 @@ Software\PowerShellCore | - | - | | UpdatableHelp | DefaultSourcePath | String |Software\Policies\Microsoft\Windows\EventLog | ProtectedEventLogging | EnableProtectedEventLogging | DWORD -#### Json file settings format +#### JSON file settings format ```json { @@ -149,7 +159,7 @@ We could redesign `-settingsfile` startup parameter. If we'd support configurati ### Comment A -Mainly for Unix we'd add `Users` section to computer wide Json file (`/etc/powershell.config.json`) to allow administrators set policies and regular settings on user level base +Mainly for Unix we'd add `Users` section to computer wide JSON file (`/etc/powershell.config.json`) to allow administrators set policies and regular settings on user level base ```json { From 5092fe4c6e4754e7a6980561e337444fb8b55508 Mon Sep 17 00:00:00 2001 From: iSazonov Date: Thu, 21 Mar 2019 15:19:57 +0500 Subject: [PATCH 4/5] Fix table --- 1-Draft/RFCnnnn-PowerShell-Configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-Draft/RFCnnnn-PowerShell-Configuration.md b/1-Draft/RFCnnnn-PowerShell-Configuration.md index 48fe1ac4..c903cb5c 100644 --- a/1-Draft/RFCnnnn-PowerShell-Configuration.md +++ b/1-Draft/RFCnnnn-PowerShell-Configuration.md @@ -37,7 +37,7 @@ Configuration schemes allow to customize `PowerShell Core` in the most flexible `PowerShell Core` settings are grouped into `Policy settings` and `Regular settings`. Regular settings are normal configuration settings. Regular settings can be treated as default values. Policy settings is high priority and overlap regular settings. Policy settings are used by administrators to centrally manage applications. Location | Policy settings | Regular settings -- | - | - +-| - | - File section | "PowerShell": { "PolicySettings": {...} } | "PowerShell": { "RegularSettings": {...} } File section | "OtherPowerShellApplication": { "PolicySettings": {...} } | "OtherPowerShellApplication": { "RegularSettings": {...} } Registry key | Software\Policies\PowerShellCore | Software\PowerShellCore From 688550456d12917f3f65e8420e68da2507bc9992 Mon Sep 17 00:00:00 2001 From: iSazonov Date: Thu, 21 Mar 2019 16:17:22 +0500 Subject: [PATCH 5/5] Add Configuration defaults --- 1-Draft/RFCnnnn-PowerShell-Configuration.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/1-Draft/RFCnnnn-PowerShell-Configuration.md b/1-Draft/RFCnnnn-PowerShell-Configuration.md index c903cb5c..c7183838 100644 --- a/1-Draft/RFCnnnn-PowerShell-Configuration.md +++ b/1-Draft/RFCnnnn-PowerShell-Configuration.md @@ -32,6 +32,18 @@ Configuration schemes allow to customize `PowerShell Core` in the most flexible - Enterprise system administrators can use GPO, GPP and computer-wide settings files to apply approved configuration settings and mandatory security settings in a centralized manner. The same settings can be applied at user, application or startup levels. - Developers and consumers can use user, application and startup level settings files. +### Configuration defaults + +PowerShell Core has hardcoded defaults for all configuration options. + +The default values must be `secure-by-default`. + +For release versions hardcoded defaults must be the same as ones in re-installed configuration files. For preview versions they may vary (ex., enable experimental features and so on). + +If during startup PowerShell Core cannot read configuration files it uses _hardcoded_ defaults. + +If during operation PowerShell Core cannot read configuration files it continue to use _current_ (runtime) configuration values. + ### Settings locations `PowerShell Core` settings are grouped into `Policy settings` and `Regular settings`. Regular settings are normal configuration settings. Regular settings can be treated as default values. Policy settings is high priority and overlap regular settings. Policy settings are used by administrators to centrally manage applications.