From 26f17ce9bf7c0140de02bfda5937d71f0f1820b2 Mon Sep 17 00:00:00 2001 From: davidsmatlak Date: Mon, 25 Mar 2019 07:41:41 -0700 Subject: [PATCH 1/3] Copyedits, style, rewrote examples --- .../About/about_Execution_Policies.md | 169 ++++---- .../Get-ExecutionPolicy.md | 186 +++++---- .../Set-ExecutionPolicy.md | 335 +++++++++++----- .../About/about_Execution_Policies.md | 169 ++++---- .../Get-ExecutionPolicy.md | 200 ++++++---- .../Set-ExecutionPolicy.md | 350 +++++++++++----- .../About/about_Execution_Policies.md | 171 ++++---- .../Get-ExecutionPolicy.md | 200 ++++++---- .../Set-ExecutionPolicy.md | 374 ++++++++++++------ .../About/about_Execution_Policies.md | 169 ++++---- .../Get-ExecutionPolicy.md | 200 ++++++---- .../Set-ExecutionPolicy.md | 364 +++++++++++------ .../About/about_Execution_Policies.md | 181 +++++---- .../Get-ExecutionPolicy.md | 195 +++++---- .../Set-ExecutionPolicy.md | 353 +++++++++++------ 15 files changed, 2310 insertions(+), 1306 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index a66392048365..e69965327b51 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -1,5 +1,5 @@ --- -ms.date: 01/15/2019 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -22,9 +22,9 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell -profile. The execution policy for a particular session is stored only in -memory and is lost when the session is closed. +registry. You do not need to set execution policies in your PowerShell profile. +The execution policy for a particular session is stored only in memory and is +lost when the session is closed. The execution policy is not a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at @@ -36,13 +36,6 @@ unintentionally. The PowerShell execution policies are as follows: -### Restricted - -- The default execution policy for Windows client computers. -- Permits individual commands, but will not run scripts. -- Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). - ### AllSigned - Scripts can run. @@ -52,6 +45,19 @@ The PowerShell execution policies are as follows: classified as trusted or untrusted. - Risks running signed, but malicious, scripts. +### Bypass + +- Nothing is blocked and there are no warnings or prompts. +- This execution policy is designed for configurations in which a PowerShell + script is built in to a larger application or for configurations in which + PowerShell is the foundation for a program that has its own security model. + +### Default + +- Sets the default execution policy. +- **Restricted** for Windows clients +- **RemoteSigned** for Windows servers. + ### RemoteSigned - The default execution policy for Windows server computers. @@ -66,18 +72,12 @@ The PowerShell execution policies are as follows: - Risks running unsigned scripts from sources other than the Internet and signed, but malicious, scripts. -### Unrestricted - -- Unsigned scripts can run. There is a risk of running malicious scripts. -- Warns the user before running scripts and configuration files that are - downloaded from the Internet. - -### Bypass +### Restricted -- Nothing is blocked and there are no warnings or prompts. -- This execution policy is designed for configurations in which a PowerShell - script is built in to a larger application or for configurations in which - PowerShell is the foundation for a program that has its own security model. +- The default execution policy for Windows client computers. +- Permits individual commands, but will not run scripts. +- Prevents running of all script files, including formatting and configuration + files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). ### Undefined @@ -85,6 +85,12 @@ The PowerShell execution policies are as follows: - If the execution policy in all scopes is Undefined, the effective execution policy is Restricted, which is the default execution policy. +### Unrestricted + +- Unsigned scripts can run. There is a risk of running malicious scripts. +- Warns the user before running scripts and configuration files that are + downloaded from the Internet. + > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths > from Internet paths, scripts that are identified by a UNC path might not be @@ -94,19 +100,30 @@ The PowerShell execution policies are as follows: You can set an execution policy that is effective only in a particular scope. -The valid values for **Scope** are Process, CurrentUser, and LocalMachine. -LocalMachine is the default when setting an execution policy. +The valid values for **Scope** are **MachinePolicy**, **UserPolicy**, +**Process**, **CurrentUser**, and **LocalMachine**. **LocalMachine** is the +default when setting an execution policy. -The **Scope** values are listed in precedence order. +The **Scope** values are listed in precedence order. The policy that takes +precedence is effective in the current session, even if a more restrictive +policy was set at a lower level of precedence. -### Process +For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). + +### MachinePolicy + +Set by a Group Policy for all users of the computer. -The execution policy affects only the current session. The current PowerShell -process. +### UserPolicy -The execution policy is stored in the `$env:PSExecutionPolicyPreference` -environment variable, not in the registry, and it is deleted when the session -is closed. You cannot change the policy by editing the variable value. +Set by a Group Policy for the current user of the computer. + +### Process + +The **Process** scope only affects the current PowerShell session. The +execution policy is saved in the environment variable +`$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. ### CurrentUser @@ -115,20 +132,15 @@ The execution policy affects only the current user. It is stored in the ### LocalMachine -The execution policy affects all users on the current computer. It is stored -in the **HKEY_LOCAL_MACHINE** registry subkey. - -The policy that takes precedence is effective in the current session, even if -a more restrictive policy was set at a lower level of precedence. - -For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). +The execution policy affects all users on the current computer. It is stored in +the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy -To get the PowerShell execution policy that is in effect in the current -session, use the `Get-ExecutionPolicy` cmdlet. +To get the effective execution policy for the current PowerShell session, use +the `Get-ExecutionPolicy` cmdlet. -The following command gets the current execution policy: +The following command gets the effective execution policy: ```powershell Get-ExecutionPolicy @@ -153,15 +165,15 @@ MachinePolicy Undefined LocalMachine AllSigned ``` -In this case, the effective execution policy is RemoteSigned because the +In this case, the effective execution policy is **RemoteSigned** because the execution policy for the current user takes precedence over the execution policy set for the local computer. To get the execution policy set for a particular scope, use the **Scope** parameter of `Get-ExecutionPolicy`. -For example, the following command gets the execution policy for the current -user scope: +For example, the following command gets the execution policy for the +**CurrentUser** scope: ```powershell Get-ExecutionPolicy -Scope CurrentUser @@ -173,18 +185,18 @@ To change the PowerShell execution policy on your Windows computer, use the `Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not need to restart PowerShell. -If you set the execution policy for the local computer (the default) or the -current user, the change is saved in the registry and remains effective until -you change it again. +If you set the execution policy for the scopes **LocalMachine** or the +**CurrentUser**, the change is saved in the registry and remains effective +until you change it again. -If you set the execution policy for the current process, it is not saved in +If you set the execution policy for the **Process** scope, it's not saved in the registry. The execution policy is retained until the current process and any child processes are closed. > [!NOTE] -> In Windows Vista and later versions of Windows, to run commands that change -> the execution policy for the local computer (the default), start PowerShell -> with the **Run as administrator** option. +> In Windows Vista and later versions of Windows, to run commands that +> change the execution policy for the local computer, **LocalMachine** scope, +> start PowerShell with the **Run as administrator** option. To change your execution policy: @@ -207,7 +219,7 @@ Set-ExecutionPolicy -ExecutionPolicy -Scope For example: ```powershell -Set-ExecutionPolicy RemoteSigned -Scope CurrentUser +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` A command to change an execution policy can succeed but still not change the @@ -218,24 +230,24 @@ can succeed but be overridden by the execution policy for the current user. ## Remove Your Execution Policy -To remove the execution policy for a particular scope, set the execution -policy to Undefined. +To remove the execution policy for a particular scope, set the execution policy +to **Undefined**. For example, to remove the execution policy for all the users of the local computer: ```powershell -Set-ExecutionPolicy Undefined +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope LocalMachine ``` To remove the execution policy for a **Scope**: ```powershell -Set-ExecutionPolicy Undefined -Scope LocalMachine +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser ``` If no execution policy is set in any scope, the effective execution policy is -Restricted, which is the default for Windows clients. +**Restricted**, which is the default for Windows clients. ## Set a Different Execution Policy for One Session @@ -254,8 +266,8 @@ For example: powershell.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it -is stored in the `$env:PSExecutionPolicyPreference` environment variable. The +The execution policy that you set is not stored in the registry. Instead, it is +stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. @@ -266,8 +278,8 @@ execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy -You can use the **Turn on Script Execution** Group Policy setting to manage -the execution policy of computers in your enterprise. The Group Policy setting +You can use the **Turn on Script Execution** Group Policy setting to manage the +execution policy of computers in your enterprise. The Group Policy setting overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: @@ -310,42 +322,43 @@ For more information, see [about_Group_Policy_Settings](about_Group_Policy_Setti When determining the effective execution policy for a session, PowerShell evaluates the execution policies in the following precedence order: -- Group Policy: Computer Configuration -- Group Policy: User Configuration +- Group Policy: MachinePolicy +- Group Policy: UserPolicy - Execution Policy: Process (or `powershell.exe -ExecutionPolicy`) - Execution Policy: CurrentUser - Execution Policy: LocalMachine ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is RemoteSigned, PowerShell will not run -unsigned scripts that are downloaded from the Internet which includes e-mail -and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell will not +run unsigned scripts that are downloaded from the Internet which includes +e-mail and instant messaging programs. -You can sign the script or elect to run an unsigned script without changing -the execution policy. +You can sign the script or elect to run an unsigned script without changing the +execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the -`Get-Item` cmdlet to detect files that are blocked because they were -downloaded from the Internet, and you can use the `Unblock-File` cmdlet to -unblock the scripts so that you can run them in PowerShell. +`Get-Item` cmdlet to detect files that are blocked because they were downloaded +from the Internet, and you can use the `Unblock-File` cmdlet to unblock the +scripts so that you can run them in PowerShell. -For more information, see [about_Signing](about_Signing.md), -[Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). +For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), +and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). ## See Also [about_Environment_Variables](about_Environment_Variables.md) +[about_Group_Policy_Settings](about_Group_Policy_Settings.md) + [about_Signing](about_Signing.md) [Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) +[Pwsh Console Help](about_pwsh.md) -[PowerShell.exe Command-Line Help](/powershell/scripting/components/console/powershell.exe-command-line-help) \ No newline at end of file +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) + +[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md b/reference/3.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md index 50e8edf333b6..d3e0f6c63473 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,114 +7,165 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113315 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Get-ExecutionPolicy --- + # Get-ExecutionPolicy ## SYNOPSIS - Gets the execution policies for the current session. ## SYNTAX +### All + ``` Get-ExecutionPolicy [[-Scope] ] [-List] [] ``` ## DESCRIPTION -The **Get-ExecutionPolicy** cmdlet gets the execution policies for the current session. +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. -The execution policy is determined by execution policies that you set by using Set-ExecutionPolicy and the Group Policy settings for the Windows PowerShell execution policy. -The default value is "Restricted." +The effective execution policy is determined by execution policies that are set by +`Set-ExecutionPolicy` and Group Policy settings. -Without parameters, **Get-ExecutionPolicy** gets the execution policy that is effective in the session. -You can use the **List** parameter to get all execution policies that affect the session or the Scope parameter to get the execution policy for a particular scope. - -For more information, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +For more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). ## EXAMPLES -### Example 1 +### Example 1: Get all execution policies + +This command displays the execution policies for each scope in the order of precedence. +```powershell +Get-ExecutionPolicy -List ``` -PS> Get-ExecutionPolicy -Restricted + +```Output +Scope ExecutionPolicy +----- --------------- +MachinePolicy Undefined +UserPolicy Undefined +Process Undefined +CurrentUser AllSigned +LocalMachine Undefined ``` -This command gets the current execution policy for the computer. +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. + +### Example 2: Set an execution policy -### Example 2 +This example shows how to set an execution policy for the local computer. +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List ``` -PS> Set-ExecutionPolicy RemoteSigned -PS> Get-ExecutionPolicy -RemoteSigned + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned ``` -These commands set a new user preference for the execution policy and then display the effective execution policy. -The commands are separated by a semicolon (;). -In this example, because there is no Group Policy setting, the user preference is the effective policy for the computer. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. + +### Example 3: Get the effective execution policy -### Example 3 +This example shows how to display the effective execution policy for a PowerShell session. ``` PS> Get-ExecutionPolicy -List -Scope ExecutionPolicy ------ --------------- -MachinePolicy Undefined -UserPolicy Undefined -Process Undefined -CurrentUser AllSigned -LocalMachine RemoteSigned + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned PS> Get-ExecutionPolicy + AllSigned ``` -These commands get all execution policies in the current session and the effective execution policy. +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. The `Get-ExecutionPolicy` cmdlet is run without a parameter to display the effective +execution policy, **AllSigned**. -The first command gets all execution policies that affect the current session. -The policies are listed in precedence order. +### Example 4: Unblock a script to run it without changing the execution policy -The second command gets only the effective execution policy, which is the one set in the CurrentUser scope. +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. -### Example 4 +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. ``` -The first command uses the **Get-ExecutionPolicy** cmdlet to get the effective execution policy in the current session. +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + PS> Get-ExecutionPolicy + RemoteSigned -The second command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is **RemoteSigned**. The **RemoteSigned** policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. PS> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + CategoryInfo : NotSpecified: (:) [], PSSecurityException - + FullyQualifiedErrorId : UnauthorizedAccess ++ CategoryInfo : NotSpecified: (:) [], PSSecurityException ++ FullyQualifiedErrorId : UnauthorizedAccess +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 -The third command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS> Unblock-File -Path Start-ActivityTracker.ps1 - -This command shows the effect of the **Unblock-File** command. The command does not change the execution policy. However, it unblocks the script so it will run in Windows PowerShell. PS> Get-ExecutionPolicy + RemoteSigned -PS> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the **RemoteSigned** execution policy, which prevents you from running unsigned scripts that were downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. + +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. + +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. + +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. + +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. + +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. ## PARAMETERS ### -List -Gets all execution policy values for the session listed in precedence order. -By default, **Get-ExecutionPolicy** gets only the effective execution policy. +Gets all execution policy values for the session listed in precedence order. By default, +`Get-ExecutionPolicy` gets only the effective execution policy. ```yaml Type: SwitchParameter @@ -130,24 +181,24 @@ Accept wildcard characters: False ### -Scope -Gets the execution policy in the specified scope. -By default, **Get-ExecutionPolicy** gets the effective execution policy for the current session. +Specifies the scope that is affected by an execution policy. -Valid values are: +The effective execution policy is determined by the order of precedence as follows: -- MachinePolicy: The execution policy set by a Group Policy for all users of the computer. -- UserPolicy: The execution policy set by a Group Policy for the current user of the computer. -- Process: The execution policy that is set for the current Windows PowerShell process. -- CurrentUser: The execution policy that is set for the current user. -- LocalMachine: The execution policy that is set for all users of the computer. +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False -Position: 1 +Position: 0 Default value: Effective execution policy Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False @@ -155,13 +206,15 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### None -You cannot pipe input to this cmdlet. +`Get-ExecutionPolicy` doesn't accept input from the pipeline. ## OUTPUTS @@ -169,23 +222,18 @@ You cannot pipe input to this cmdlet. ## NOTES -- The execution policy is part of the security strategy of Windows PowerShell. It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. - The effective execution policy is determined by the policies that you set by using the Set-ExecutionPolicy cmdlet and the "Turn on Script Execution" group policies for computers and users. -The precedence order is Computer Group Policy \> User Group Policy \> Process (session) execution policy \> User execution policy \> Computer execution policy. +## RELATED LINKS - For more information about Windows PowerShell execution policy, including definitions of the Windows PowerShell policies, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +[about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md) -## RELATED LINKS +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) [Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) [Set-ExecutionPolicy](Set-ExecutionPolicy.md) - -[Unblock-File](../Microsoft.PowerShell.Utility/Unblock-File.md) - -[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) - -[about_Signing](../Microsoft.PowerShell.Core/About/about_Signing.md) \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md b/reference/3.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md index 8453d0c22aaf..7265ef1c84ca 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,163 +7,275 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113394 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Set-ExecutionPolicy --- + # Set-ExecutionPolicy ## SYNOPSIS - -Changes the user preference for the Windows PowerShell execution policy. +Sets the PowerShell execution policies for Windows computers. ## SYNTAX +### All + ``` -Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] [-WhatIf] - [-Confirm] [] +Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] +[-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Set-ExecutionPolicy** cmdlet changes the user preference for the Windows PowerShell execution policy. +The `Set-ExecutionPolicy` cmdlet changes PowerShell execution policies for Windows computers. For +more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). -The execution policy is part of the security strategy of Windows PowerShell. -It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. -For more information, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. -NOTE: To change the execution policy for the default (LocalMachine) scope, start Windows PowerShell with the "Run as administrator" option. +The `Set-ExecutionPolicy` cmdlet's default scope is **LocalMachine**, which affects everyone who +uses the computer. To change the execution policy for **LocalMachine**, start PowerShell with **Run +as Administrator**. + +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. ## EXAMPLES -### Example 1 +### Example 1: Set an execution policy + +This example shows how to set the execution policy for the local computer. ```powershell -Set-ExecutionPolicy RemoteSigned +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List +``` + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser RemoteSigned + LocalMachine RemoteSigned ``` -This command sets the user preference for the shell execution policy to RemoteSigned. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. -### Example 2 +### Example 2: Set an execution policy that conflicts with a Group Policy + +This command attempts to set the **LocalMachine** scope's execution policy to **Restricted**. +**LocalMachine** is more restrictive, but isn't the effective policy because it conflicts with a +Group Policy. The **Restricted** policy is written to the registry hive **HKEY_LOCAL_MACHINE**. ``` -PS> Set-ExecutionPolicy Restricted -Set-ExecutionPolicy : Windows PowerShell updated your local preference successfully, but the setting is overridden by the group policy applied to your system. Due to the override, your shell will retain its current effective execution policy of "AllSigned". Contact your group policy administrator for more information. -At line:1 char:20 -+ Set-ExecutionPolicy <<<< restricted -``` +PS> Set-ExecutionPolicy -ExecutionPolicy Restricted -Scope LocalMachine -This command attempts to set the execution policy for the shell to "Restricted." The "Restricted" setting is written to the registry, but because it conflicts with a Group Policy, it is not effective, even though it is more restrictive than the policy. +Set-ExecutionPolicy : PowerShell updated your local preference successfully, but the setting is +overridden by the Group Policy applied to your system. Due to the override, your shell will retain +its current effective execution policy of "AllSigned". Contact your Group Policy administrator for +more information. At line:1 char:20 + Set-ExecutionPolicy <<<< restricted -### Example 3 +PS> Get-ChildItem -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds -```powershell -Invoke-Command -ComputerName Server01 -ScriptBlock {Get-ExecutionPolicy} | Set-ExecutionPolicy -Force -``` + Hive: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds -This command gets the execution policy from a remote computer and applies that execution policy to the local computer. +Name Property +---- -------- +Microsoft.PowerShell Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe + ExecutionPolicy : Restricted +ScriptedDiagnostics ExecutionPolicy : Unrestricted +``` -The command uses the Invoke-Command cmdlet to send the command to the remote computer. -Because you can pipe an ExecutionPolicy (Microsoft.PowerShell.ExecutionPolicy) object to **Set-ExecutionPolicy**, the **Set-ExecutionPolicy** command does not need an **ExecutionPolicy** parameter. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**Restricted** policy. The **Scope** parameter specifies the default scope value, **LocalMachine**. +The `Get-ChildItem` cmdlet uses the **Path** parameter with the **HKLM** provider to specify +registry location. -The command uses the **Force** parameter to suppress the user prompt. +### Example 3: Apply the execution policy from a remote computer to a local computer -### Example 4 +This command gets the execution policy object from a remote computer and sets the policy on the +local computer. `Get-ExecutionPolicy` sends a **Microsoft.PowerShell.ExecutionPolicy** object down +the pipeline. `Set-ExecutionPolicy` accepts pipeline input and doesn't require the +**ExecutionPolicy** parameter. ``` -The first command uses the **Set-ExecutionPolicy** cmdlet to set an execution policy of **AllSigned** for the current user. It uses the **Force** parameter to suppress the user prompts. -PS> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy AllSigned -Force +PS> Invoke-Command -ComputerName Server01 -ScriptBlock { Get-ExecutionPolicy } | Set-ExecutionPolicy +``` -The second command uses the **List** parameter of the Get-ExecutionPolicy cmdlet to get the execution policies set in each scope. The results show that the execution policy that is set for the current user differs from the execution policy set for all users of the computer. -PS> Get-ExecutionPolicy -List +The `Invoke-Command` cmdlet is executed at the local computer and sends the **ScriptBlock** to the +remote computer. The **ComputerName** parameter specifies the remote computer, **Server01**. The +**ScriptBlock** parameter runs `Get-ExecutionPolicy` on the remote computer. The +`Get-ExecutionPolicy` object is sent down the pipeline to the `Set-ExecutionPolicy`. +`Set-ExecutionPolicy` applies the execution policy to the local computer's default scope, +**LocalMachine**. -Scope ExecutionPolicy ------ --------------- -MachinePolicy Undefined -UserPolicy Undefined -Process Undefined -CurrentUser AllSigned -LocalMachine RemoteSigned +### Example 4: Set the scope for an execution policy +This example shows how to set an execution policy for a specified scope, **CurrentUser**. The +**CurrentUser** scope only affects the user who sets this scope. -PS> Get-ExecutionPolicy -AllSigned +```powershell +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope CurrentUser +Get-ExecutionPolicy -List ``` -This example shows how to set an execution policy for a particular scope. +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned +``` + +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. + +The effective execution policy for the user becomes **AllSigned**. -### Example 5 +### Example 5: Remove the execution policy for the current user + +This example shows how use the **Undefined** execution policy to remove an execution policy for a +specified scope. ```powershell -Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser +Get-ExecutionPolicy -List +``` + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser Undefined + LocalMachine RemoteSigned ``` -This command uses an execution policy value of **Undefined** to effectively remove the execution policy that is set for the current user scope. -As a result, the execution policy that is set in Group Policy or in the LocalMachine (all users) scope is effective. +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **Undefined** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. -If you set the execution policy in all scopes to **Undefined** and the Group Policy is not set, the default execution policy, **Restricted**, is effective for all users of the computer. +### Example 6: Set the execution policy for the current PowerShell session -### Example 6 +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference` and is deleted when the session is +closed. ```powershell -Set-ExecutionPolicy -Scope Process -ExecutionPolicy AllSigned +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope Process ``` -This command sets an execution policy of **AllSigned** for only the current Windows PowerShell session. -This execution policy is saved in the **PSExecutionPolicyPreference** environment variable ($env:PSExecutionPolicyPreference), so it does not affect the value in the registry. -The variable and its value are deleted when the current session is closed. +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process AllSigned + CurrentUser RemoteSigned + LocalMachine RemoteSigned +``` + +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** +policy. The **Scope** parameter specifies the value **Process**. To view the execution policy +settings, use the `Get-ExecutionPolicy` cmdlet with the **List** parameter. + +### Example 7: Unblock a script to run it without changing the execution policy -### Example 7 +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. + +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. ``` -The first command uses the **Set-ExecutionPolicy** cmdlet to change the execution policy to RemoteSigned. -PS> Set-ExecutionPolicy RemoteSigned +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine -The second command uses the Get-ExecutionPolicy cmdlet to get the effective execution policy in the session. The output shows that it is **RemoteSigned**. PS> Get-ExecutionPolicy + RemoteSigned -The third command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is **RemoteSigned**. The **RemoteSigned** policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. PS> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + CategoryInfo : NotSpecified: (:) [], PSSecurityException - + FullyQualifiedErrorId : UnauthorizedAccess - ++ CategoryInfo : NotSpecified: (:) [], PSSecurityException ++ FullyQualifiedErrorId : UnauthorizedAccess -The fourth command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS> Unblock-File -Path Start-ActivityTracker.ps1 +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 -The fifth and sixth commands show the effect of the **Unblock-File** command. The **Unblock-File** command does not change the execution policy. However, it unblocks the script so it will run in Windows PowerShell. PS> Get-ExecutionPolicy + RemoteSigned -PS> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the **RemoteSigned** execution policy, which prevents you from running unsigned scripts that were downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. + +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. + +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. + +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. + +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. + +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. ## PARAMETERS ### -ExecutionPolicy -Specifies the new execution policy. -Valid values are: - -- Restricted: Does not load configuration files or run scripts. "Restricted" is the default execution policy. -- AllSigned: Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- RemoteSigned: Requires that all scripts and configuration files downloaded from the Internet be signed by a trusted publisher. -- Unrestricted: Loads all configuration files and runs all scripts. If you run an unsigned script that was downloaded from the Internet, you are prompted for permission before it runs. -- Bypass: Nothing is blocked and there are no warnings or prompts. -- Undefined: Removes the currently assigned execution policy from the current scope. This parameter will not remove an execution policy that is set in a Group Policy scope. +Specifies the execution policy. If there are no Group Policies and each scope's execution policy is +set to **Undefined**, then **Restricted** becomes the effective policy for all users. + +The acceptable execution policy values are as follows: + +- **AllSigned**. Requires that all scripts and configuration files are signed by a trusted + publisher, including scripts written on the local computer. +- **Bypass**. Nothing is blocked and there are no warnings or prompts. +- **Default**. Sets the default execution policy. **Restricted** for Windows clients or + **RemoteSigned** for Windows servers. +- **RemoteSigned**. Requires that all scripts and configuration files downloaded from the Internet + are signed by a trusted publisher. The default execution policy for Windows server computers. +- **Restricted**. Doesn't load configuration files or run scripts. The default execution policy + Windows client computers. +- **Undefined**. No execution policy is set for the scope. Removes an assigned execution policy from + a scope that is not set by a Group Policy. If the execution policy in all scopes is **Undefined**, + the effective execution policy is **Restricted**. +- **Unrestricted**. Loads all configuration files and runs all scripts. If you run an unsigned + script that was downloaded from the Internet, you are prompted for permission before it runs. ```yaml Type: ExecutionPolicy Parameter Sets: (All) Aliases: +Accepted values: AllSigned, Bypass, Default, RemoteSigned, Restricted, Undefined, Unrestricted Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False @@ -171,8 +283,8 @@ Accept wildcard characters: False ### -Force -Suppresses all prompts. -By default, **Set-ExecutionPolicy** displays a warning whenever you change the execution policy. +Suppresses all the confirmation prompts. Use caution with this parameter to avoid unexpected +results. ```yaml Type: SwitchParameter @@ -188,27 +300,34 @@ Accept wildcard characters: False ### -Scope -Specifies the scope of the execution policy. -The default is LocalMachine. +Specifies the scope that is affected by an execution policy. The default scope is **LocalMachine**. + +The effective execution policy is determined by the order of precedence as follows: -Valid values are: +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. -- Process: The execution policy affects only the current Windows PowerShell process. -- CurrentUser: The execution policy affects only the current user. -- LocalMachine: The execution policy affects all users of the computer. +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. -To remove an execution policy from a particular scope, set the execution policy for that scope to Undefined. +Execution policies for the **CurrentUser** scope are written to the registry hive +**HKEY_LOCAL_USER**. -When the value of the **Scope** parameter is **Process**, the execution policy is saved in the **PSExecutionPolicyPreference** environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and the variable is deleted when the process is closed. -You cannot change the execution policy of the process by editing the variable. +Execution policies for the **LocalMachine** scope are written to the registry hive +**HKEY_LOCAL_MACHINE**. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False -Position: 2 +Position: 1 Default value: LocalMachine Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False @@ -232,8 +351,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -249,37 +367,52 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### Microsoft.PowerShell.ExecutionPolicy, System.String -You can pipe an execution policy object or a string that contains the name of an execution policy to **Set-ExecutionPolicy**. +You can pipe an execution policy object or a string that contains the name of an execution policy to +`Set-ExecutionPolicy`. ## OUTPUTS ### None -This cmdlet does not return any output. +`Set-ExecutionPolicy` doesn't return any output. ## NOTES -- When you use **Set-ExecutionPolicy** in any scope other than **Process**, the new user preference is saved in the registry and remains unchanged until you change it. When the value of the **Scope** parameter is **Process**, the user preference is stored in the **PSExecutionPolicyPreference** environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and it is deleted when the session in which it is effective is closed. +`Set-ExecutionPolicy` doesn't change the **MachinePolicy** and **UserPolicy** scopes because they +are set by Group Policies. - If the "**Turn on Script Execution**" Group Policy is enabled for the computer or user, the user preference is saved, but it is not effective, and Windows PowerShell displays a message explaining the conflict. -You cannot use **Set-ExecutionPolicy** to override a Group Policy, even if the user preference is more restrictive than the policy. +`Set-ExecutionPolicy` doesn't override a Group Policy, even if the user preference is more +restrictive than the policy. +If the Group Policy **Turn on Script Execution** is enabled for the computer or user, the user +preference is saved, but it is not effective. PowerShell displays a message that explains the +conflict. ## RELATED LINKS +[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) + +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) + [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) +[Get-ChildItem](../Microsoft.PowerShell.Management/Get-ChildItem.md) + [Get-ExecutionPolicy](Get-ExecutionPolicy.md) -[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) +[Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md) -[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) +[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) -[about_Signing](../Microsoft.PowerShell.Core/About/about_Signing.md) \ No newline at end of file +[Unblock-File](../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 4608bec55f78..b1e1f8da9545 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -1,5 +1,5 @@ --- -ms.date: 01/15/2019 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -22,9 +22,9 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell -profile. The execution policy for a particular session is stored only in -memory and is lost when the session is closed. +registry. You do not need to set execution policies in your PowerShell profile. +The execution policy for a particular session is stored only in memory and is +lost when the session is closed. The execution policy is not a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at @@ -36,13 +36,6 @@ unintentionally. The PowerShell execution policies are as follows: -### Restricted - -- The default execution policy for Windows client computers. -- Permits individual commands, but will not run scripts. -- Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). - ### AllSigned - Scripts can run. @@ -52,6 +45,19 @@ The PowerShell execution policies are as follows: classified as trusted or untrusted. - Risks running signed, but malicious, scripts. +### Bypass + +- Nothing is blocked and there are no warnings or prompts. +- This execution policy is designed for configurations in which a PowerShell + script is built in to a larger application or for configurations in which + PowerShell is the foundation for a program that has its own security model. + +### Default + +- Sets the default execution policy. +- **Restricted** for Windows clients +- **RemoteSigned** for Windows servers. + ### RemoteSigned - The default execution policy for Windows server computers. @@ -66,18 +72,12 @@ The PowerShell execution policies are as follows: - Risks running unsigned scripts from sources other than the Internet and signed, but malicious, scripts. -### Unrestricted - -- Unsigned scripts can run. There is a risk of running malicious scripts. -- Warns the user before running scripts and configuration files that are - downloaded from the Internet. - -### Bypass +### Restricted -- Nothing is blocked and there are no warnings or prompts. -- This execution policy is designed for configurations in which a PowerShell - script is built in to a larger application or for configurations in which - PowerShell is the foundation for a program that has its own security model. +- The default execution policy for Windows client computers. +- Permits individual commands, but will not run scripts. +- Prevents running of all script files, including formatting and configuration + files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). ### Undefined @@ -85,6 +85,12 @@ The PowerShell execution policies are as follows: - If the execution policy in all scopes is Undefined, the effective execution policy is Restricted, which is the default execution policy. +### Unrestricted + +- Unsigned scripts can run. There is a risk of running malicious scripts. +- Warns the user before running scripts and configuration files that are + downloaded from the Internet. + > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths > from Internet paths, scripts that are identified by a UNC path might not be @@ -94,19 +100,30 @@ The PowerShell execution policies are as follows: You can set an execution policy that is effective only in a particular scope. -The valid values for **Scope** are Process, CurrentUser, and LocalMachine. -LocalMachine is the default when setting an execution policy. +The valid values for **Scope** are **MachinePolicy**, **UserPolicy**, +**Process**, **CurrentUser**, and **LocalMachine**. **LocalMachine** is the +default when setting an execution policy. -The **Scope** values are listed in precedence order. +The **Scope** values are listed in precedence order. The policy that takes +precedence is effective in the current session, even if a more restrictive +policy was set at a lower level of precedence. -### Process +For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). + +### MachinePolicy + +Set by a Group Policy for all users of the computer. -The execution policy affects only the current session. The current PowerShell -process. +### UserPolicy -The execution policy is stored in the `$env:PSExecutionPolicyPreference` -environment variable, not in the registry, and it is deleted when the session -is closed. You cannot change the policy by editing the variable value. +Set by a Group Policy for the current user of the computer. + +### Process + +The **Process** scope only affects the current PowerShell session. The +execution policy is saved in the environment variable +`$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. ### CurrentUser @@ -115,20 +132,15 @@ The execution policy affects only the current user. It is stored in the ### LocalMachine -The execution policy affects all users on the current computer. It is stored -in the **HKEY_LOCAL_MACHINE** registry subkey. - -The policy that takes precedence is effective in the current session, even if -a more restrictive policy was set at a lower level of precedence. - -For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). +The execution policy affects all users on the current computer. It is stored in +the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy -To get the PowerShell execution policy that is in effect in the current -session, use the `Get-ExecutionPolicy` cmdlet. +To get the effective execution policy for the current PowerShell session, use +the `Get-ExecutionPolicy` cmdlet. -The following command gets the current execution policy: +The following command gets the effective execution policy: ```powershell Get-ExecutionPolicy @@ -153,15 +165,15 @@ MachinePolicy Undefined LocalMachine AllSigned ``` -In this case, the effective execution policy is RemoteSigned because the +In this case, the effective execution policy is **RemoteSigned** because the execution policy for the current user takes precedence over the execution policy set for the local computer. To get the execution policy set for a particular scope, use the **Scope** parameter of `Get-ExecutionPolicy`. -For example, the following command gets the execution policy for the current -user scope: +For example, the following command gets the execution policy for the +**CurrentUser** scope: ```powershell Get-ExecutionPolicy -Scope CurrentUser @@ -173,18 +185,18 @@ To change the PowerShell execution policy on your Windows computer, use the `Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not need to restart PowerShell. -If you set the execution policy for the local computer (the default) or the -current user, the change is saved in the registry and remains effective until -you change it again. +If you set the execution policy for the scopes **LocalMachine** or the +**CurrentUser**, the change is saved in the registry and remains effective +until you change it again. -If you set the execution policy for the current process, it is not saved in +If you set the execution policy for the **Process** scope, it's not saved in the registry. The execution policy is retained until the current process and any child processes are closed. > [!NOTE] -> In Windows Vista and later versions of Windows, to run commands that change -> the execution policy for the local computer (the default), start PowerShell -> with the **Run as administrator** option. +> In Windows Vista and later versions of Windows, to run commands that +> change the execution policy for the local computer, **LocalMachine** scope, +> start PowerShell with the **Run as administrator** option. To change your execution policy: @@ -207,7 +219,7 @@ Set-ExecutionPolicy -ExecutionPolicy -Scope For example: ```powershell -Set-ExecutionPolicy RemoteSigned -Scope CurrentUser +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` A command to change an execution policy can succeed but still not change the @@ -218,24 +230,24 @@ can succeed but be overridden by the execution policy for the current user. ## Remove Your Execution Policy -To remove the execution policy for a particular scope, set the execution -policy to Undefined. +To remove the execution policy for a particular scope, set the execution policy +to **Undefined**. For example, to remove the execution policy for all the users of the local computer: ```powershell -Set-ExecutionPolicy Undefined +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope LocalMachine ``` To remove the execution policy for a **Scope**: ```powershell -Set-ExecutionPolicy Undefined -Scope LocalMachine +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser ``` If no execution policy is set in any scope, the effective execution policy is -Restricted, which is the default for Windows clients. +**Restricted**, which is the default for Windows clients. ## Set a Different Execution Policy for One Session @@ -254,8 +266,8 @@ For example: powershell.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it -is stored in the `$env:PSExecutionPolicyPreference` environment variable. The +The execution policy that you set is not stored in the registry. Instead, it is +stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. @@ -266,8 +278,8 @@ execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy -You can use the **Turn on Script Execution** Group Policy setting to manage -the execution policy of computers in your enterprise. The Group Policy setting +You can use the **Turn on Script Execution** Group Policy setting to manage the +execution policy of computers in your enterprise. The Group Policy setting overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: @@ -310,42 +322,43 @@ For more information, see [about_Group_Policy_Settings](about_Group_Policy_Setti When determining the effective execution policy for a session, PowerShell evaluates the execution policies in the following precedence order: -- Group Policy: Computer Configuration -- Group Policy: User Configuration +- Group Policy: MachinePolicy +- Group Policy: UserPolicy - Execution Policy: Process (or `powershell.exe -ExecutionPolicy`) - Execution Policy: CurrentUser - Execution Policy: LocalMachine ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is RemoteSigned, PowerShell will not run -unsigned scripts that are downloaded from the Internet which includes e-mail -and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell will not +run unsigned scripts that are downloaded from the Internet which includes +e-mail and instant messaging programs. -You can sign the script or elect to run an unsigned script without changing -the execution policy. +You can sign the script or elect to run an unsigned script without changing the +execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the -`Get-Item` cmdlet to detect files that are blocked because they were -downloaded from the Internet, and you can use the `Unblock-File` cmdlet to -unblock the scripts so that you can run them in PowerShell. +`Get-Item` cmdlet to detect files that are blocked because they were downloaded +from the Internet, and you can use the `Unblock-File` cmdlet to unblock the +scripts so that you can run them in PowerShell. -For more information, see [about_Signing](about_Signing.md), -[Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). +For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), +and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). ## See Also [about_Environment_Variables](about_Environment_Variables.md) +[about_Group_Policy_Settings](about_Group_Policy_Settings.md) + [about_Signing](about_Signing.md) [Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) +[Pwsh Console Help](about_pwsh.md) -[PowerShell.exe Command-Line Help](/powershell/scripting/components/console/powershell.exe-command-line-help) \ No newline at end of file +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) + +[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) diff --git a/reference/4.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md b/reference/4.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md index 88642fe89452..8a124db50d63 100644 --- a/reference/4.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md +++ b/reference/4.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -15,100 +15,157 @@ Gets the execution policies for the current session. ## SYNTAX +### All + ``` Get-ExecutionPolicy [[-Scope] ] [-List] [] ``` ## DESCRIPTION -The **Get-ExecutionPolicy** cmdlet gets the execution policies for the current session. -The execution policy is determined by execution policies that you set by using Set-ExecutionPolicy and the Group Policy settings for the Windows PowerShell execution policy. -The default value is "Restricted." +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. -Without parameters, **Get-ExecutionPolicy** gets the execution policy that is effective in the session. -You can use the **List** parameter to get all execution policies that affect the session or the Scope parameter to get the execution policy for a particular scope. +The effective execution policy is determined by execution policies that are set by +`Set-ExecutionPolicy` and Group Policy settings. -For more information, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +For more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). ## EXAMPLES -### Example 1 -```powershell -PS C:\> Get-ExecutionPolicy -Restricted -``` +### Example 1: Get all execution policies -This command gets the current execution policy for the computer. +This command displays the execution policies for each scope in the order of precedence. -### Example 2 ```powershell -PS C:\> Set-ExecutionPolicy RemoteSigned -PS C:\> Get-ExecutionPolicy -RemoteSigned +Get-ExecutionPolicy -List ``` -These commands set a new user preference for the execution policy and then display the effective execution policy. -The commands are separated by a semicolon (;). -In this example, because there is no Group Policy setting, the user preference is the effective policy for the computer. - -### Example 3 -```powershell -PS C:\> Get-ExecutionPolicy -List - +```Output Scope ExecutionPolicy ----- --------------- MachinePolicy Undefined UserPolicy Undefined Process Undefined CurrentUser AllSigned -LocalMachine RemoteSigned +LocalMachine Undefined +``` + +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. + +### Example 2: Set an execution policy + +This example shows how to set an execution policy for the local computer. + +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List +``` + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned +``` + +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. + +### Example 3: Get the effective execution policy + +This example shows how to display the effective execution policy for a PowerShell session. + +``` +PS> Get-ExecutionPolicy -List + + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned + +PS> Get-ExecutionPolicy -PS C:\> Get-ExecutionPolicy AllSigned ``` -These commands get all execution policies in the current session and the effective execution policy. +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. The `Get-ExecutionPolicy` cmdlet is run without a parameter to display the effective +execution policy, **AllSigned**. -The first command gets all execution policies that affect the current session. -The policies are listed in precedence order. +### Example 4: Unblock a script to run it without changing the execution policy -The second command gets only the effective execution policy, which is the one set in the CurrentUser scope. +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. + +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. + +``` +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + +PS> Get-ExecutionPolicy -### Example 4 -```powershell -The first command uses the **Get-ExecutionPolicy** cmdlet to get the effective execution policy in the current session. -PS C:\> Get-ExecutionPolicy RemoteSigned -The second command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is **RemoteSigned**. The **RemoteSigned** policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 +PS> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + CategoryInfo : NotSpecified: (:) [], PSSecurityException - + FullyQualifiedErrorId : UnauthorizedAccess ++ CategoryInfo : NotSpecified: (:) [], PSSecurityException ++ FullyQualifiedErrorId : UnauthorizedAccess +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 -The third command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path Start-ActivityTracker.ps1 +PS> Get-ExecutionPolicy -This command shows the effect of the **Unblock-File** command. The command does not change the execution policy. However, it unblocks the script so it will run in Windows PowerShell. -PS C:\> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the **RemoteSigned** execution policy, which prevents you from running unsigned scripts that were downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. + +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. + +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. + +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. + +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. + +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. ## PARAMETERS ### -List -Gets all execution policy values for the session listed in precedence order. -By default, **Get-ExecutionPolicy** gets only the effective execution policy. + +Gets all execution policy values for the session listed in precedence order. By default, +`Get-ExecutionPolicy` gets only the effective execution policy. ```yaml Type: SwitchParameter @@ -123,59 +180,60 @@ Accept wildcard characters: False ``` ### -Scope -Gets the execution policy in the specified scope. -By default, **Get-ExecutionPolicy** gets the effective execution policy for the current session. -Valid values are: +Specifies the scope that is affected by an execution policy. + +The effective execution policy is determined by the order of precedence as follows: -- MachinePolicy: The execution policy set by a Group Policy for all users of the computer. -- UserPolicy: The execution policy set by a Group Policy for the current user of the computer. -- Process: The execution policy that is set for the current Windows PowerShell process. -- CurrentUser: The execution policy that is set for the current user. -- LocalMachine: The execution policy that is set for all users of the computer. +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False -Position: 1 +Position: 0 Default value: Effective execution policy Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### None -You cannot pipe input to this cmdlet. + +`Get-ExecutionPolicy` doesn't accept input from the pipeline. ## OUTPUTS ### Microsoft.PowerShell.ExecutionPolicy ## NOTES -* The execution policy is part of the security strategy of Windows PowerShell. It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. - - The effective execution policy is determined by the policies that you set by using the Set-ExecutionPolicy cmdlet and the "Turn on Script Execution" group policies for computers and users. -The precedence order is Computer Group Policy \> User Group Policy \> Process (session) execution policy \> User execution policy \> Computer execution policy. - For more information about Windows PowerShell execution policy, including definitions of the Windows PowerShell policies, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. ## RELATED LINKS +[about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md) + +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) + [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) [Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) [Set-ExecutionPolicy](Set-ExecutionPolicy.md) - -[Unblock-File](../Microsoft.PowerShell.Utility/Unblock-File.md) - -[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) - -[about_Signing](../Microsoft.PowerShell.Core/About/about_Signing.md) \ No newline at end of file diff --git a/reference/4.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md b/reference/4.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md index c58d95a92a0a..e2d42f7f2305 100644 --- a/reference/4.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md +++ b/reference/4.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,158 +11,280 @@ title: Set-ExecutionPolicy # Set-ExecutionPolicy ## SYNOPSIS -Changes the user preference for the Windows PowerShell execution policy. +Sets the PowerShell execution policies for Windows computers. ## SYNTAX +### All + ``` -Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] [-WhatIf] - [-Confirm] [] +Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] +[-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Set-ExecutionPolicy** cmdlet changes the user preference for the Windows PowerShell execution policy. -The execution policy is part of the security strategy of Windows PowerShell. -It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. -For more information, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +The `Set-ExecutionPolicy` cmdlet changes PowerShell execution policies for Windows computers. For +more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). + +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. -NOTE: To change the execution policy for the default (LocalMachine) scope, start Windows PowerShell with the "Run as administrator" option. +The `Set-ExecutionPolicy` cmdlet's default scope is **LocalMachine**, which affects everyone who +uses the computer. To change the execution policy for **LocalMachine**, start PowerShell with **Run +as Administrator**. + +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. ## EXAMPLES -### Example 1 +### Example 1: Set an execution policy + +This example shows how to set the execution policy for the local computer. + +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List ``` -PS C:\> Set-ExecutionPolicy RemoteSigned + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser RemoteSigned + LocalMachine RemoteSigned ``` -This command sets the user preference for the shell execution policy to RemoteSigned. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. + +### Example 2: Set an execution policy that conflicts with a Group Policy + +This command attempts to set the **LocalMachine** scope's execution policy to **Restricted**. +**LocalMachine** is more restrictive, but isn't the effective policy because it conflicts with a +Group Policy. The **Restricted** policy is written to the registry hive **HKEY_LOCAL_MACHINE**. -### Example 2 ``` -PS C:\> Set-ExecutionPolicy Restricted -Set-ExecutionPolicy : Windows PowerShell updated your local preference successfully, but the setting is overridden by the group policy applied to your system. Due to the override, your shell will retain its current effective execution policy of "AllSigned". Contact your group policy administrator for more information. -At line:1 char:20 -+ Set-ExecutionPolicy <<<< restricted +PS> Set-ExecutionPolicy -ExecutionPolicy Restricted -Scope LocalMachine + +Set-ExecutionPolicy : PowerShell updated your local preference successfully, but the setting is +overridden by the Group Policy applied to your system. Due to the override, your shell will retain +its current effective execution policy of "AllSigned". Contact your Group Policy administrator for +more information. At line:1 char:20 + Set-ExecutionPolicy <<<< restricted + +PS> Get-ChildItem -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds + + Hive: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds + +Name Property +---- -------- +Microsoft.PowerShell Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe + ExecutionPolicy : Restricted +ScriptedDiagnostics ExecutionPolicy : Unrestricted ``` -This command attempts to set the execution policy for the shell to "Restricted." The "Restricted" setting is written to the registry, but because it conflicts with a Group Policy, it is not effective, even though it is more restrictive than the policy. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**Restricted** policy. The **Scope** parameter specifies the default scope value, **LocalMachine**. +The `Get-ChildItem` cmdlet uses the **Path** parameter with the **HKLM** provider to specify +registry location. + +### Example 3: Apply the execution policy from a remote computer to a local computer + +This command gets the execution policy object from a remote computer and sets the policy on the +local computer. `Get-ExecutionPolicy` sends a **Microsoft.PowerShell.ExecutionPolicy** object down +the pipeline. `Set-ExecutionPolicy` accepts pipeline input and doesn't require the +**ExecutionPolicy** parameter. -### Example 3 ``` -PS C:\> Invoke-Command -ComputerName Server01 -ScriptBlock {Get-ExecutionPolicy} | Set-ExecutionPolicy -Force +PS> Invoke-Command -ComputerName Server01 -ScriptBlock { Get-ExecutionPolicy } | Set-ExecutionPolicy ``` -This command gets the execution policy from a remote computer and applies that execution policy to the local computer. +The `Invoke-Command` cmdlet is executed at the local computer and sends the **ScriptBlock** to the +remote computer. The **ComputerName** parameter specifies the remote computer, **Server01**. The +**ScriptBlock** parameter runs `Get-ExecutionPolicy` on the remote computer. The +`Get-ExecutionPolicy` object is sent down the pipeline to the `Set-ExecutionPolicy`. +`Set-ExecutionPolicy` applies the execution policy to the local computer's default scope, +**LocalMachine**. -The command uses the Invoke-Command cmdlet to send the command to the remote computer. -Because you can pipe an ExecutionPolicy (Microsoft.PowerShell.ExecutionPolicy) object to **Set-ExecutionPolicy**, the **Set-ExecutionPolicy** command does not need an **ExecutionPolicy** parameter. +### Example 4: Set the scope for an execution policy -The command uses the **Force** parameter to suppress the user prompt. +This example shows how to set an execution policy for a specified scope, **CurrentUser**. The +**CurrentUser** scope only affects the user who sets this scope. -### Example 4 +```powershell +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope CurrentUser +Get-ExecutionPolicy -List ``` -The first command uses the **Set-ExecutionPolicy** cmdlet to set an execution policy of **AllSigned** for the current user. It uses the **Force** parameter to suppress the user prompts. -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy AllSigned -Force -The second command uses the **List** parameter of the Get-ExecutionPolicy cmdlet to get the execution policies set in each scope. The results show that the execution policy that is set for the current user differs from the execution policy set for all users of the computer. -PS C:\> Get-ExecutionPolicy -List +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned +``` -Scope ExecutionPolicy ------ --------------- -MachinePolicy Undefined -UserPolicy Undefined -Process Undefined -CurrentUser AllSigned -LocalMachine RemoteSigned +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. +The effective execution policy for the user becomes **AllSigned**. -PS C:\> Get-ExecutionPolicy -AllSigned -``` +### Example 5: Remove the execution policy for the current user -This example shows how to set an execution policy for a particular scope. +This example shows how use the **Undefined** execution policy to remove an execution policy for a +specified scope. -### Example 5 +```powershell +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser +Get-ExecutionPolicy -List ``` -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser Undefined + LocalMachine RemoteSigned ``` -This command uses an execution policy value of **Undefined** to effectively remove the execution policy that is set for the current user scope. -As a result, the execution policy that is set in Group Policy or in the LocalMachine (all users) scope is effective. +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **Undefined** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. + +### Example 6: Set the execution policy for the current PowerShell session -If you set the execution policy in all scopes to **Undefined** and the Group Policy is not set, the default execution policy, **Restricted**, is effective for all users of the computer. +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference` and is deleted when the session is +closed. -### Example 6 +```powershell +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope Process ``` -PS C:\> Set-ExecutionPolicy -Scope Process -ExecutionPolicy AllSigned + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process AllSigned + CurrentUser RemoteSigned + LocalMachine RemoteSigned ``` -This command sets an execution policy of **AllSigned** for only the current Windows PowerShell session. -This execution policy is saved in the **PSExecutionPolicyPreference** environment variable ($env:PSExecutionPolicyPreference), so it does not affect the value in the registry. -The variable and its value are deleted when the current session is closed. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** +policy. The **Scope** parameter specifies the value **Process**. To view the execution policy +settings, use the `Get-ExecutionPolicy` cmdlet with the **List** parameter. + +### Example 7: Unblock a script to run it without changing the execution policy + +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. + +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. -### Example 7 ``` -The first command uses the **Set-ExecutionPolicy** cmdlet to change the execution policy to RemoteSigned. -PS C:\> Set-ExecutionPolicy RemoteSigned +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + +PS> Get-ExecutionPolicy -The second command uses the Get-ExecutionPolicy cmdlet to get the effective execution policy in the session. The output shows that it is **RemoteSigned**. -PS C:\> Get-ExecutionPolicy RemoteSigned -The third command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is **RemoteSigned**. The **RemoteSigned** policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 +PS> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + CategoryInfo : NotSpecified: (:) [], PSSecurityException - + FullyQualifiedErrorId : UnauthorizedAccess ++ CategoryInfo : NotSpecified: (:) [], PSSecurityException ++ FullyQualifiedErrorId : UnauthorizedAccess +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 -The fourth command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path Start-ActivityTracker.ps1 +PS> Get-ExecutionPolicy -The fifth and sixth commands show the effect of the **Unblock-File** command. The **Unblock-File** command does not change the execution policy. However, it unblocks the script so it will run in Windows PowerShell. -PS C:\> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the **RemoteSigned** execution policy, which prevents you from running unsigned scripts that were downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. + +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. + +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. + +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. + +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. + +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. ## PARAMETERS ### -ExecutionPolicy -Specifies the new execution policy. -Valid values are: -- Restricted: Does not load configuration files or run scripts. "Restricted" is the default execution policy. -- AllSigned: Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- RemoteSigned: Requires that all scripts and configuration files downloaded from the Internet be signed by a trusted publisher. -- Unrestricted: Loads all configuration files and runs all scripts. If you run an unsigned script that was downloaded from the Internet, you are prompted for permission before it runs. -- Bypass: Nothing is blocked and there are no warnings or prompts. -- Undefined: Removes the currently assigned execution policy from the current scope. This parameter will not remove an execution policy that is set in a Group Policy scope. +Specifies the execution policy. If there are no Group Policies and each scope's execution policy is +set to **Undefined**, then **Restricted** becomes the effective policy for all users. + +The acceptable execution policy values are as follows: + +- **AllSigned**. Requires that all scripts and configuration files are signed by a trusted + publisher, including scripts written on the local computer. +- **Bypass**. Nothing is blocked and there are no warnings or prompts. +- **Default**. Sets the default execution policy. **Restricted** for Windows clients or + **RemoteSigned** for Windows servers. +- **RemoteSigned**. Requires that all scripts and configuration files downloaded from the Internet + are signed by a trusted publisher. The default execution policy for Windows server computers. +- **Restricted**. Doesn't load configuration files or run scripts. The default execution policy + Windows client computers. +- **Undefined**. No execution policy is set for the scope. Removes an assigned execution policy from + a scope that is not set by a Group Policy. If the execution policy in all scopes is **Undefined**, + the effective execution policy is **Restricted**. +- **Unrestricted**. Loads all configuration files and runs all scripts. If you run an unsigned + script that was downloaded from the Internet, you are prompted for permission before it runs. ```yaml Type: ExecutionPolicy Parameter Sets: (All) Aliases: +Accepted values: AllSigned, Bypass, Default, RemoteSigned, Restricted, Undefined, Unrestricted Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` ### -Force -Suppresses all prompts. -By default, **Set-ExecutionPolicy** displays a warning whenever you change the execution policy. + +Suppresses all the confirmation prompts. Use caution with this parameter to avoid unexpected +results. ```yaml Type: SwitchParameter @@ -177,33 +299,42 @@ Accept wildcard characters: False ``` ### -Scope -Specifies the scope of the execution policy. -The default is LocalMachine. -Valid values are: +Specifies the scope that is affected by an execution policy. The default scope is **LocalMachine**. -- Process: The execution policy affects only the current Windows PowerShell process. -- CurrentUser: The execution policy affects only the current user. -- LocalMachine: The execution policy affects all users of the computer. +The effective execution policy is determined by the order of precedence as follows: -To remove an execution policy from a particular scope, set the execution policy for that scope to Undefined. +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. -When the value of the **Scope** parameter is **Process**, the execution policy is saved in the **PSExecutionPolicyPreference** environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and the variable is deleted when the process is closed. -You cannot change the execution policy of the process by editing the variable. +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. + +Execution policies for the **CurrentUser** scope are written to the registry hive +**HKEY_LOCAL_USER**. + +Execution policies for the **LocalMachine** scope are written to the registry hive +**HKEY_LOCAL_MACHINE**. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False -Position: 2 +Position: 1 Default value: LocalMachine Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -219,8 +350,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -235,34 +366,53 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### Microsoft.PowerShell.ExecutionPolicy, System.String -You can pipe an execution policy object or a string that contains the name of an execution policy to **Set-ExecutionPolicy**. + +You can pipe an execution policy object or a string that contains the name of an execution policy to +`Set-ExecutionPolicy`. ## OUTPUTS ### None -This cmdlet does not return any output. + +`Set-ExecutionPolicy` doesn't return any output. ## NOTES -* When you use **Set-ExecutionPolicy** in any scope other than **Process**, the new user preference is saved in the registry and remains unchanged until you change it. When the value of the **Scope** parameter is **Process**, the user preference is stored in the **PSExecutionPolicyPreference** environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and it is deleted when the session in which it is effective is closed. - If the "**Turn on Script Execution**" Group Policy is enabled for the computer or user, the user preference is saved, but it is not effective, and Windows PowerShell displays a message explaining the conflict. -You cannot use **Set-ExecutionPolicy** to override a Group Policy, even if the user preference is more restrictive than the policy. +`Set-ExecutionPolicy` doesn't change the **MachinePolicy** and **UserPolicy** scopes because they +are set by Group Policies. + +`Set-ExecutionPolicy` doesn't override a Group Policy, even if the user preference is more +restrictive than the policy. + +If the Group Policy **Turn on Script Execution** is enabled for the computer or user, the user +preference is saved, but it is not effective. PowerShell displays a message that explains the +conflict. -* ## RELATED LINKS +[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) + +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) + [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) +[Get-ChildItem](../Microsoft.PowerShell.Management/Get-ChildItem.md) + [Get-ExecutionPolicy](Get-ExecutionPolicy.md) -[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) +[Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md) -[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) +[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) -[about_Signing](../Microsoft.PowerShell.Core/About/about_Signing.md) \ No newline at end of file +[Unblock-File](../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 02b6ae33492a..b1e1f8da9545 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -1,13 +1,15 @@ --- -ms.date: 01/15/2019 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Execution_Policies --- + # About Execution Policies ## Short Description + Describes the PowerShell execution policies and explains how to manage them. ## Long Description @@ -20,9 +22,9 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell -profile. The execution policy for a particular session is stored only in -memory and is lost when the session is closed. +registry. You do not need to set execution policies in your PowerShell profile. +The execution policy for a particular session is stored only in memory and is +lost when the session is closed. The execution policy is not a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at @@ -34,13 +36,6 @@ unintentionally. The PowerShell execution policies are as follows: -### Restricted - -- The default execution policy for Windows client computers. -- Permits individual commands, but will not run scripts. -- Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). - ### AllSigned - Scripts can run. @@ -50,6 +45,19 @@ The PowerShell execution policies are as follows: classified as trusted or untrusted. - Risks running signed, but malicious, scripts. +### Bypass + +- Nothing is blocked and there are no warnings or prompts. +- This execution policy is designed for configurations in which a PowerShell + script is built in to a larger application or for configurations in which + PowerShell is the foundation for a program that has its own security model. + +### Default + +- Sets the default execution policy. +- **Restricted** for Windows clients +- **RemoteSigned** for Windows servers. + ### RemoteSigned - The default execution policy for Windows server computers. @@ -64,18 +72,12 @@ The PowerShell execution policies are as follows: - Risks running unsigned scripts from sources other than the Internet and signed, but malicious, scripts. -### Unrestricted - -- Unsigned scripts can run. There is a risk of running malicious scripts. -- Warns the user before running scripts and configuration files that are - downloaded from the Internet. - -### Bypass +### Restricted -- Nothing is blocked and there are no warnings or prompts. -- This execution policy is designed for configurations in which a PowerShell - script is built in to a larger application or for configurations in which - PowerShell is the foundation for a program that has its own security model. +- The default execution policy for Windows client computers. +- Permits individual commands, but will not run scripts. +- Prevents running of all script files, including formatting and configuration + files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). ### Undefined @@ -83,6 +85,12 @@ The PowerShell execution policies are as follows: - If the execution policy in all scopes is Undefined, the effective execution policy is Restricted, which is the default execution policy. +### Unrestricted + +- Unsigned scripts can run. There is a risk of running malicious scripts. +- Warns the user before running scripts and configuration files that are + downloaded from the Internet. + > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths > from Internet paths, scripts that are identified by a UNC path might not be @@ -92,19 +100,30 @@ The PowerShell execution policies are as follows: You can set an execution policy that is effective only in a particular scope. -The valid values for **Scope** are Process, CurrentUser, and LocalMachine. -LocalMachine is the default when setting an execution policy. +The valid values for **Scope** are **MachinePolicy**, **UserPolicy**, +**Process**, **CurrentUser**, and **LocalMachine**. **LocalMachine** is the +default when setting an execution policy. -The **Scope** values are listed in precedence order. +The **Scope** values are listed in precedence order. The policy that takes +precedence is effective in the current session, even if a more restrictive +policy was set at a lower level of precedence. -### Process +For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). + +### MachinePolicy -The execution policy affects only the current session. The current PowerShell -process. +Set by a Group Policy for all users of the computer. -The execution policy is stored in the `$env:PSExecutionPolicyPreference` -environment variable, not in the registry, and it is deleted when the session -is closed. You cannot change the policy by editing the variable value. +### UserPolicy + +Set by a Group Policy for the current user of the computer. + +### Process + +The **Process** scope only affects the current PowerShell session. The +execution policy is saved in the environment variable +`$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. ### CurrentUser @@ -113,20 +132,15 @@ The execution policy affects only the current user. It is stored in the ### LocalMachine -The execution policy affects all users on the current computer. It is stored -in the **HKEY_LOCAL_MACHINE** registry subkey. - -The policy that takes precedence is effective in the current session, even if -a more restrictive policy was set at a lower level of precedence. - -For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). +The execution policy affects all users on the current computer. It is stored in +the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy -To get the PowerShell execution policy that is in effect in the current -session, use the `Get-ExecutionPolicy` cmdlet. +To get the effective execution policy for the current PowerShell session, use +the `Get-ExecutionPolicy` cmdlet. -The following command gets the current execution policy: +The following command gets the effective execution policy: ```powershell Get-ExecutionPolicy @@ -151,15 +165,15 @@ MachinePolicy Undefined LocalMachine AllSigned ``` -In this case, the effective execution policy is RemoteSigned because the +In this case, the effective execution policy is **RemoteSigned** because the execution policy for the current user takes precedence over the execution policy set for the local computer. To get the execution policy set for a particular scope, use the **Scope** parameter of `Get-ExecutionPolicy`. -For example, the following command gets the execution policy for the current -user scope: +For example, the following command gets the execution policy for the +**CurrentUser** scope: ```powershell Get-ExecutionPolicy -Scope CurrentUser @@ -171,18 +185,18 @@ To change the PowerShell execution policy on your Windows computer, use the `Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not need to restart PowerShell. -If you set the execution policy for the local computer (the default) or the -current user, the change is saved in the registry and remains effective until -you change it again. +If you set the execution policy for the scopes **LocalMachine** or the +**CurrentUser**, the change is saved in the registry and remains effective +until you change it again. -If you set the execution policy for the current process, it is not saved in +If you set the execution policy for the **Process** scope, it's not saved in the registry. The execution policy is retained until the current process and any child processes are closed. > [!NOTE] -> In Windows Vista and later versions of Windows, to run commands that change -> the execution policy for the local computer (the default), start PowerShell -> with the **Run as administrator** option. +> In Windows Vista and later versions of Windows, to run commands that +> change the execution policy for the local computer, **LocalMachine** scope, +> start PowerShell with the **Run as administrator** option. To change your execution policy: @@ -205,7 +219,7 @@ Set-ExecutionPolicy -ExecutionPolicy -Scope For example: ```powershell -Set-ExecutionPolicy RemoteSigned -Scope CurrentUser +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` A command to change an execution policy can succeed but still not change the @@ -216,24 +230,24 @@ can succeed but be overridden by the execution policy for the current user. ## Remove Your Execution Policy -To remove the execution policy for a particular scope, set the execution -policy to Undefined. +To remove the execution policy for a particular scope, set the execution policy +to **Undefined**. For example, to remove the execution policy for all the users of the local computer: ```powershell -Set-ExecutionPolicy Undefined +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope LocalMachine ``` To remove the execution policy for a **Scope**: ```powershell -Set-ExecutionPolicy Undefined -Scope LocalMachine +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser ``` If no execution policy is set in any scope, the effective execution policy is -Restricted, which is the default for Windows clients. +**Restricted**, which is the default for Windows clients. ## Set a Different Execution Policy for One Session @@ -252,8 +266,8 @@ For example: powershell.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it -is stored in the `$env:PSExecutionPolicyPreference` environment variable. The +The execution policy that you set is not stored in the registry. Instead, it is +stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. @@ -264,8 +278,8 @@ execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy -You can use the **Turn on Script Execution** Group Policy setting to manage -the execution policy of computers in your enterprise. The Group Policy setting +You can use the **Turn on Script Execution** Group Policy setting to manage the +execution policy of computers in your enterprise. The Group Policy setting overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: @@ -308,42 +322,43 @@ For more information, see [about_Group_Policy_Settings](about_Group_Policy_Setti When determining the effective execution policy for a session, PowerShell evaluates the execution policies in the following precedence order: -- Group Policy: Computer Configuration -- Group Policy: User Configuration +- Group Policy: MachinePolicy +- Group Policy: UserPolicy - Execution Policy: Process (or `powershell.exe -ExecutionPolicy`) - Execution Policy: CurrentUser - Execution Policy: LocalMachine ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is RemoteSigned, PowerShell will not run -unsigned scripts that are downloaded from the Internet which includes e-mail -and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell will not +run unsigned scripts that are downloaded from the Internet which includes +e-mail and instant messaging programs. -You can sign the script or elect to run an unsigned script without changing -the execution policy. +You can sign the script or elect to run an unsigned script without changing the +execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the -`Get-Item` cmdlet to detect files that are blocked because they were -downloaded from the Internet, and you can use the `Unblock-File` cmdlet to -unblock the scripts so that you can run them in PowerShell. +`Get-Item` cmdlet to detect files that are blocked because they were downloaded +from the Internet, and you can use the `Unblock-File` cmdlet to unblock the +scripts so that you can run them in PowerShell. -For more information, see [about_Signing](about_Signing.md), -[Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). +For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), +and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). ## See Also [about_Environment_Variables](about_Environment_Variables.md) +[about_Group_Policy_Settings](about_Group_Policy_Settings.md) + [about_Signing](about_Signing.md) [Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) +[Pwsh Console Help](about_pwsh.md) -[PowerShell.exe Command-Line Help](/powershell/scripting/components/console/powershell.exe-command-line-help) \ No newline at end of file +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) + +[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) diff --git a/reference/5.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md b/reference/5.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md index 9768e359ebef..6a70ffb3395c 100644 --- a/reference/5.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md +++ b/reference/5.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,6 +7,7 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821714 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Get-ExecutionPolicy --- + # Get-ExecutionPolicy ## SYNOPSIS @@ -14,106 +15,157 @@ Gets the execution policies for the current session. ## SYNTAX +### All + ``` Get-ExecutionPolicy [[-Scope] ] [-List] [] ``` ## DESCRIPTION -The **Get-ExecutionPolicy** cmdlet gets the execution policies for the current session. - -The execution policy is determined by execution policies that you set by using Set-ExecutionPolicy and the Group Policy settings for the Windows PowerShell execution policy. -The default value is Restricted. +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. -Without parameters, **Get-ExecutionPolicy** gets the execution policy that is effective in the session. -You can use the *List* parameter to get all execution policies that affect the session or the *Scope* parameter to get the execution policy for a particular scope. +The effective execution policy is determined by execution policies that are set by +`Set-ExecutionPolicy` and Group Policy settings. -For more information, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +For more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). ## EXAMPLES -### Example 1: Get the current execution policy +### Example 1: Get all execution policies + +This command displays the execution policies for each scope in the order of precedence. ```powershell -PS C:\> Get-ExecutionPolicy -Restricted +Get-ExecutionPolicy -List +``` + +```Output +Scope ExecutionPolicy +----- --------------- +MachinePolicy Undefined +UserPolicy Undefined +Process Undefined +CurrentUser AllSigned +LocalMachine Undefined ``` -This command gets the current execution policy for the computer. +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. + +### Example 2: Set an execution policy -### Example 2: Set the execution policy +This example shows how to set an execution policy for the local computer. ```powershell -PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -PS C:\> Get-ExecutionPolicy -RemoteSigned +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List ``` -These commands set a new user preference for the execution policy and then display the effective execution policy. -In this example, because there is no Group Policy setting, the user preference is the effective policy for the computer. +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned +``` -### Example 3: Get all execution policies for the current session +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. -```powershell -PS C:\> Get-ExecutionPolicy -List +### Example 3: Get the effective execution policy -Scope ExecutionPolicy ------ --------------- -MachinePolicy Undefined -UserPolicy Undefined -Process Undefined -CurrentUser AllSigned -LocalMachine RemoteSigned +This example shows how to display the effective execution policy for a PowerShell session. +``` +PS> Get-ExecutionPolicy -List + + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned + +PS> Get-ExecutionPolicy -PS C:\> Get-ExecutionPolicy AllSigned ``` -These commands get all execution policies in the current session and the effective execution policy. +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. The `Get-ExecutionPolicy` cmdlet is run without a parameter to display the effective +execution policy, **AllSigned**. -The first command gets all execution policies that affect the current session. -The policies are listed in precedence order. +### Example 4: Unblock a script to run it without changing the execution policy -The second command gets only the effective execution policy, which is the one set in the CurrentUser scope. +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. -### Example 4: Prevent a unsigned script from running +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. + +``` +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + +PS> Get-ExecutionPolicy -```powershell -PS C:\> Get-ExecutionPolicy RemoteSigned -The second command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is RemoteSigned. The RemoteSigned policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute -on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. +PS> .\Start-ActivityTracker.ps1 + +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [], PSSecurityException + FullyQualifiedErrorId : UnauthorizedAccess -The third command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path "Start-ActivityTracker.ps1" +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 + +PS> Get-ExecutionPolicy -This command shows the effect of the Unblock-File command. The command does not change the execution policy. However, it unblocks the script so that it runs in Windows PowerShell. -PS C:\> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the RemoteSigned execution policy, which prevents you from running unsigned scripts that are downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. -The first command uses the **Get-ExecutionPolicy** cmdlet to get the effective execution policy in the current session. +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. + +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. + +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. + +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. + +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. ## PARAMETERS ### -List -Gets all execution policy values for the session listed in precedence order. -By default, **Get-ExecutionPolicy** gets only the effective execution policy. +Gets all execution policy values for the session listed in precedence order. By default, +`Get-ExecutionPolicy` gets only the effective execution policy. ```yaml Type: SwitchParameter @@ -129,26 +181,21 @@ Accept wildcard characters: False ### -Scope -Gets the execution policy in the specified scope. -By default, **Get-ExecutionPolicy** gets the effective execution policy for the current session. -The acceptable values for this parameter are: - -- MachinePolicy. -The execution policy set by a Group Policy for all users of the computer. -- UserPolicy. -The execution policy set by a Group Policy for the current user of the computer. -- Process. -The execution policy that is set for the current Windows PowerShell process. -- CurrentUser. -The execution policy that is set for the current user. -- LocalMachine. -The execution policy that is set for all users of the computer. +Specifies the scope that is affected by an execution policy. + +The effective execution policy is determined by the order of precedence as follows: + +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: -Accepted values: Process, CurrentUser, LocalMachine, UserPolicy, MachinePolicy +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False Position: 0 @@ -159,13 +206,15 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### None -You cannot pipe input to this cmdlet. +`Get-ExecutionPolicy` doesn't accept input from the pipeline. ## OUTPUTS @@ -173,23 +222,18 @@ You cannot pipe input to this cmdlet. ## NOTES -* The execution policy is part of the security strategy of Windows PowerShell. It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. - The effective execution policy is determined by the policies that you set by using the Set-ExecutionPolicy cmdlet and the "Turn on Script Execution" group policies for computers and users. -The precedence order is Computer Group Policy \> User Group Policy \> Process (session) execution policy \> User execution policy \> Computer execution policy. +## RELATED LINKS - For more information about Windows PowerShell execution policy, including definitions of the Windows PowerShell policies, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +[about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md) -## RELATED LINKS +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) [Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) [Set-ExecutionPolicy](Set-ExecutionPolicy.md) - -[Unblock-File](../Microsoft.PowerShell.Utility/Unblock-File.md) - -[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) - -[about_Signing](../Microsoft.PowerShell.Core/About/about_Signing.md) \ No newline at end of file diff --git a/reference/5.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md b/reference/5.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md index a1d6e330afb0..03ade2b407b3 100644 --- a/reference/5.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md +++ b/reference/5.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,189 +7,272 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821719 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Set-ExecutionPolicy --- + # Set-ExecutionPolicy ## SYNOPSIS -Changes the user preference for the Windows PowerShell execution policy. +Sets the PowerShell execution policies for Windows computers. ## SYNTAX +### All + ``` -Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] [-WhatIf] - [-Confirm] [] +Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] +[-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Set-ExecutionPolicy** cmdlet changes the user preference for the Windows PowerShell execution policy. +The `Set-ExecutionPolicy` cmdlet changes PowerShell execution policies for Windows computers. For +more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). + +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. -The execution policy is part of the security strategy of Windows PowerShell. -It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. -For more information, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +The `Set-ExecutionPolicy` cmdlet's default scope is **LocalMachine**, which affects everyone who +uses the computer. To change the execution policy for **LocalMachine**, start PowerShell with **Run +as Administrator**. -To change the execution policy for the default (LocalMachine) scope, start Windows PowerShell with the "Run as administrator" option. +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. ## EXAMPLES -### Example 1: Set the shell execution policy +### Example 1: Set an execution policy +This example shows how to set the execution policy for the local computer. + +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List ``` -PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser RemoteSigned + LocalMachine RemoteSigned ``` -This command sets the user preference for the shell execution policy to RemoteSigned. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. -### Example 2: Set a shell execution policy that conflicts with the group policy +### Example 2: Set an execution policy that conflicts with a Group Policy + +This command attempts to set the **LocalMachine** scope's execution policy to **Restricted**. +**LocalMachine** is more restrictive, but isn't the effective policy because it conflicts with a +Group Policy. The **Restricted** policy is written to the registry hive **HKEY_LOCAL_MACHINE**. ``` -PS C:\> Set-ExecutionPolicy -ExecutionPolicy Restricted -Set-ExecutionPolicy : Windows PowerShell updated your local preference successfully, but the setting is -overridden by the group policy applied to your system. Due to the override, your shell will retain its current -effective execution policy of "AllSigned". Contact your group policy administrator for more information. -At line:1 char:20 -+ Set-ExecutionPolicy <<<< restricted -``` +PS> Set-ExecutionPolicy -ExecutionPolicy Restricted -Scope LocalMachine -This command attempts to set the execution policy for the shell to Restricted. -The Restricted setting is written to the registry, but because it conflicts with a group policy, it is not effective, even though it is more restrictive than the group policy. +Set-ExecutionPolicy : PowerShell updated your local preference successfully, but the setting is +overridden by the Group Policy applied to your system. Due to the override, your shell will retain +its current effective execution policy of "AllSigned". Contact your Group Policy administrator for +more information. At line:1 char:20 + Set-ExecutionPolicy <<<< restricted -### Example 3: Apply the execution policy from a remote computer to the local computer +PS> Get-ChildItem -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds -``` -PS C:\> Invoke-Command -ComputerName "Server01" -ScriptBlock {Get-ExecutionPolicy} | Set-ExecutionPolicy -Force -``` + Hive: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds -This command gets the execution policy from a remote computer and applies that execution policy to the local computer. +Name Property +---- -------- +Microsoft.PowerShell Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe + ExecutionPolicy : Restricted +ScriptedDiagnostics ExecutionPolicy : Unrestricted +``` -The command uses the Invoke-Command cmdlet to send the command to the remote computer. -Because you can pipe an ExecutionPolicy (Microsoft.PowerShell.ExecutionPolicy) object to **Set-ExecutionPolicy**, the **Set-ExecutionPolicy** command does not require an *ExecutionPolicy* parameter. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**Restricted** policy. The **Scope** parameter specifies the default scope value, **LocalMachine**. +The `Get-ChildItem` cmdlet uses the **Path** parameter with the **HKLM** provider to specify +registry location. -The command uses the *Force* parameter to suppress the user prompt. +### Example 3: Apply the execution policy from a remote computer to a local computer -### Example 4: Set the scope for an execution policy +This command gets the execution policy object from a remote computer and sets the policy on the +local computer. `Get-ExecutionPolicy` sends a **Microsoft.PowerShell.ExecutionPolicy** object down +the pipeline. `Set-ExecutionPolicy` accepts pipeline input and doesn't require the +**ExecutionPolicy** parameter. ``` -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy AllSigned -Force +PS> Invoke-Command -ComputerName Server01 -ScriptBlock { Get-ExecutionPolicy } | Set-ExecutionPolicy +``` + +The `Invoke-Command` cmdlet is executed at the local computer and sends the **ScriptBlock** to the +remote computer. The **ComputerName** parameter specifies the remote computer, **Server01**. The +**ScriptBlock** parameter runs `Get-ExecutionPolicy` on the remote computer. The +`Get-ExecutionPolicy` object is sent down the pipeline to the `Set-ExecutionPolicy`. +`Set-ExecutionPolicy` applies the execution policy to the local computer's default scope, +**LocalMachine**. -The second command uses the *List* parameter of the Get-ExecutionPolicy cmdlet to get the execution policies set in each scope. The results show that the execution policy that is set for the current user differs from the execution policy set for all users of the computer. -PS C:\> Get-ExecutionPolicy -List -Scope ExecutionPolicy ------ --------------- -MachinePolicy Undefined -UserPolicy Undefined -Process Undefined -CurrentUser AllSigned -LocalMachine RemoteSigned +### Example 4: Set the scope for an execution policy + +This example shows how to set an execution policy for a specified scope, **CurrentUser**. The +**CurrentUser** scope only affects the user who sets this scope. +```powershell +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope CurrentUser +Get-ExecutionPolicy -List +``` -PS C:\> Get-ExecutionPolicy -AllSigned +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned ``` -This example shows how to set an execution policy for a particular scope. +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. -The first command uses the **Set-ExecutionPolicy** cmdlet to set an execution policy of **AllSigned** for the current user. -It uses the *Force* parameter to suppress the user prompt. +The effective execution policy for the user becomes **AllSigned**. ### Example 5: Remove the execution policy for the current user +This example shows how use the **Undefined** execution policy to remove an execution policy for a +specified scope. + +```powershell +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser +Get-ExecutionPolicy -List ``` -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser Undefined + LocalMachine RemoteSigned ``` -This command uses an execution policy value of Undefined to effectively remove the execution policy that is set for the current user scope. -As a result, the execution policy that is set in Group Policy or in the LocalMachine (all users) scope is effective. +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **Undefined** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. -If you set the execution policy in all scopes to Undefined and the Group Policy is not set, the default execution policy, Restricted, is effective for all users of the computer. +### Example 6: Set the execution policy for the current PowerShell session -### Example 6: Set the execution policy for the current session +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference` and is deleted when the session is +closed. +```powershell +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope Process ``` -PS C:\> Set-ExecutionPolicy -Scope Process -ExecutionPolicy AllSigned + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process AllSigned + CurrentUser RemoteSigned + LocalMachine RemoteSigned ``` -This command sets an execution policy of AllSigned for only the current Windows PowerShell session. -This execution policy is saved in the PSExecutionPolicyPreference environment variable ($env:PSExecutionPolicyPreference), so it does not affect the value in the registry. -The variable and its value are deleted when the current session is closed. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** +policy. The **Scope** parameter specifies the value **Process**. To view the execution policy +settings, use the `Get-ExecutionPolicy` cmdlet with the **List** parameter. ### Example 7: Unblock a script to run it without changing the execution policy +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. + +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. + ``` -The first command uses the **Set-ExecutionPolicy** cmdlet to change the execution policy to RemoteSigned. -PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + +PS> Get-ExecutionPolicy -The second command uses the Get-ExecutionPolicy cmdlet to get the effective execution policy in the session. The output shows that it is RemoteSigned. -PS C:\> Get-ExecutionPolicy RemoteSigned -The third command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is RemoteSigned. The RemoteSigned policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 -is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies -at http://go.microsoft.com/fwlink/?LinkID=135170. +PS> .\Start-ActivityTracker.ps1 + +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [], PSSecurityException + FullyQualifiedErrorId : UnauthorizedAccess -The fourth command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path "Start-ActivityTracker.ps1" +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 + +PS> Get-ExecutionPolicy -The fifth and sixth commands show the effect of the **Unblock-File** command. The **Unblock-File** command does not change the execution policy. However, it unblocks the script so it will run in Windows PowerShell. -PS C:\> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the RemoteSigned execution policy, which prevents you from running unsigned scripts that were downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. -## PARAMETERS +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. -### -Confirm +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. -Prompts you for confirmation before running the cmdlet. +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. + +## PARAMETERS ### -ExecutionPolicy -Specifies the new execution policy. -The acceptable values for this parameter are: - -- Restricted. -Does not load configuration files or run scripts. -Restricted is the default execution policy. -- AllSigned. -Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- RemoteSigned. -Requires that all scripts and configuration files downloaded from the Internet be signed by a trusted publisher. -- Unrestricted. -Loads all configuration files and runs all scripts. -If you run an unsigned script that was downloaded from the Internet, you are prompted for permission before it runs. -- Bypass. -Nothing is blocked and there are no warnings or prompts. -- Undefined. -Removes the currently assigned execution policy from the current scope. -This parameter will not remove an execution policy that is set in a Group Policy scope. +Specifies the execution policy. If there are no Group Policies and each scope's execution policy is +set to **Undefined**, then **Restricted** becomes the effective policy for all users. + +The acceptable execution policy values are as follows: + +- **AllSigned**. Requires that all scripts and configuration files are signed by a trusted + publisher, including scripts written on the local computer. +- **Bypass**. Nothing is blocked and there are no warnings or prompts. +- **Default**. Sets the default execution policy. **Restricted** for Windows clients or + **RemoteSigned** for Windows servers. +- **RemoteSigned**. Requires that all scripts and configuration files downloaded from the Internet + are signed by a trusted publisher. The default execution policy for Windows server computers. +- **Restricted**. Doesn't load configuration files or run scripts. The default execution policy + Windows client computers. +- **Undefined**. No execution policy is set for the scope. Removes an assigned execution policy from + a scope that is not set by a Group Policy. If the execution policy in all scopes is **Undefined**, + the effective execution policy is **Restricted**. +- **Unrestricted**. Loads all configuration files and runs all scripts. If you run an unsigned + script that was downloaded from the Internet, you are prompted for permission before it runs. ```yaml Type: ExecutionPolicy Parameter Sets: (All) Aliases: -Accepted values: Unrestricted, RemoteSigned, AllSigned, Restricted, Default, Bypass, Undefined +Accepted values: AllSigned, Bypass, Default, RemoteSigned, Restricted, Undefined, Unrestricted Required: True Position: 0 @@ -200,8 +283,8 @@ Accept wildcard characters: False ### -Force -Suppresses all prompts. -By default, **Set-ExecutionPolicy** displays a warning whenever you change the execution policy. +Suppresses all the confirmation prompts. Use caution with this parameter to avoid unexpected +results. ```yaml Type: SwitchParameter @@ -217,24 +300,31 @@ Accept wildcard characters: False ### -Scope -Specifies the scope of the execution policy. -The default is LocalMachine. -The acceptable values for this parameter are: +Specifies the scope that is affected by an execution policy. The default scope is **LocalMachine**. + +The effective execution policy is determined by the order of precedence as follows: + +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. -- Process: The execution policy affects only the current Windows PowerShell process. -- CurrentUser: The execution policy affects only the current user. -- LocalMachine: The execution policy affects all users of the computer. +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. -To remove an execution policy from a particular scope, set the execution policy for that scope to Undefined. +Execution policies for the **CurrentUser** scope are written to the registry hive +**HKEY_LOCAL_USER**. -When the value of the *Scope* parameter is Process, the execution policy is saved in the PSExecutionPolicyPreference environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and the variable is deleted when the process is closed. -You cannot change the execution policy of the process by editing the variable. +Execution policies for the **LocalMachine** scope are written to the registry hive +**HKEY_LOCAL_MACHINE**. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: -Accepted values: Process, CurrentUser, LocalMachine, UserPolicy, MachinePolicy +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False Position: 1 @@ -243,10 +333,25 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -262,37 +367,52 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### Microsoft.PowerShell.ExecutionPolicy, System.String -You can pipe an execution policy object or a string that contains the name of an execution policy to **Set-ExecutionPolicy**. +You can pipe an execution policy object or a string that contains the name of an execution policy to +`Set-ExecutionPolicy`. ## OUTPUTS ### None -This cmdlet does not return any output. +`Set-ExecutionPolicy` doesn't return any output. ## NOTES -* When you use **Set-ExecutionPolicy** in any scope other than Process, the new user preference is saved in the registry and remains unchanged until you change it. When the value of the *Scope* parameter is Process, the user preference is stored in the PSExecutionPolicyPreference environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and it is deleted when the session in which it is effective is closed. +`Set-ExecutionPolicy` doesn't change the **MachinePolicy** and **UserPolicy** scopes because they +are set by Group Policies. + +`Set-ExecutionPolicy` doesn't override a Group Policy, even if the user preference is more +restrictive than the policy. - If the "Turn on Script Execution" group policy is enabled for the computer or user, the user preference is saved, but it is not effective, and Windows PowerShell displays a message explaining the conflict. -You cannot use **Set-ExecutionPolicy** to override a Group Policy, even if the user preference is more restrictive than the policy. +If the Group Policy **Turn on Script Execution** is enabled for the computer or user, the user +preference is saved, but it is not effective. PowerShell displays a message that explains the +conflict. -* ## RELATED LINKS +[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) + +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) + [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) +[Get-ChildItem](../Microsoft.PowerShell.Management/Get-ChildItem.md) + [Get-ExecutionPolicy](Get-ExecutionPolicy.md) -[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) +[Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md) -[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) +[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) -[about_Signing](../Microsoft.PowerShell.Core/About/about_Signing.md) \ No newline at end of file +[Unblock-File](../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 4608bec55f78..b1e1f8da9545 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -1,5 +1,5 @@ --- -ms.date: 01/15/2019 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -22,9 +22,9 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell -profile. The execution policy for a particular session is stored only in -memory and is lost when the session is closed. +registry. You do not need to set execution policies in your PowerShell profile. +The execution policy for a particular session is stored only in memory and is +lost when the session is closed. The execution policy is not a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at @@ -36,13 +36,6 @@ unintentionally. The PowerShell execution policies are as follows: -### Restricted - -- The default execution policy for Windows client computers. -- Permits individual commands, but will not run scripts. -- Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). - ### AllSigned - Scripts can run. @@ -52,6 +45,19 @@ The PowerShell execution policies are as follows: classified as trusted or untrusted. - Risks running signed, but malicious, scripts. +### Bypass + +- Nothing is blocked and there are no warnings or prompts. +- This execution policy is designed for configurations in which a PowerShell + script is built in to a larger application or for configurations in which + PowerShell is the foundation for a program that has its own security model. + +### Default + +- Sets the default execution policy. +- **Restricted** for Windows clients +- **RemoteSigned** for Windows servers. + ### RemoteSigned - The default execution policy for Windows server computers. @@ -66,18 +72,12 @@ The PowerShell execution policies are as follows: - Risks running unsigned scripts from sources other than the Internet and signed, but malicious, scripts. -### Unrestricted - -- Unsigned scripts can run. There is a risk of running malicious scripts. -- Warns the user before running scripts and configuration files that are - downloaded from the Internet. - -### Bypass +### Restricted -- Nothing is blocked and there are no warnings or prompts. -- This execution policy is designed for configurations in which a PowerShell - script is built in to a larger application or for configurations in which - PowerShell is the foundation for a program that has its own security model. +- The default execution policy for Windows client computers. +- Permits individual commands, but will not run scripts. +- Prevents running of all script files, including formatting and configuration + files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). ### Undefined @@ -85,6 +85,12 @@ The PowerShell execution policies are as follows: - If the execution policy in all scopes is Undefined, the effective execution policy is Restricted, which is the default execution policy. +### Unrestricted + +- Unsigned scripts can run. There is a risk of running malicious scripts. +- Warns the user before running scripts and configuration files that are + downloaded from the Internet. + > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths > from Internet paths, scripts that are identified by a UNC path might not be @@ -94,19 +100,30 @@ The PowerShell execution policies are as follows: You can set an execution policy that is effective only in a particular scope. -The valid values for **Scope** are Process, CurrentUser, and LocalMachine. -LocalMachine is the default when setting an execution policy. +The valid values for **Scope** are **MachinePolicy**, **UserPolicy**, +**Process**, **CurrentUser**, and **LocalMachine**. **LocalMachine** is the +default when setting an execution policy. -The **Scope** values are listed in precedence order. +The **Scope** values are listed in precedence order. The policy that takes +precedence is effective in the current session, even if a more restrictive +policy was set at a lower level of precedence. -### Process +For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). + +### MachinePolicy + +Set by a Group Policy for all users of the computer. -The execution policy affects only the current session. The current PowerShell -process. +### UserPolicy -The execution policy is stored in the `$env:PSExecutionPolicyPreference` -environment variable, not in the registry, and it is deleted when the session -is closed. You cannot change the policy by editing the variable value. +Set by a Group Policy for the current user of the computer. + +### Process + +The **Process** scope only affects the current PowerShell session. The +execution policy is saved in the environment variable +`$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. ### CurrentUser @@ -115,20 +132,15 @@ The execution policy affects only the current user. It is stored in the ### LocalMachine -The execution policy affects all users on the current computer. It is stored -in the **HKEY_LOCAL_MACHINE** registry subkey. - -The policy that takes precedence is effective in the current session, even if -a more restrictive policy was set at a lower level of precedence. - -For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). +The execution policy affects all users on the current computer. It is stored in +the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy -To get the PowerShell execution policy that is in effect in the current -session, use the `Get-ExecutionPolicy` cmdlet. +To get the effective execution policy for the current PowerShell session, use +the `Get-ExecutionPolicy` cmdlet. -The following command gets the current execution policy: +The following command gets the effective execution policy: ```powershell Get-ExecutionPolicy @@ -153,15 +165,15 @@ MachinePolicy Undefined LocalMachine AllSigned ``` -In this case, the effective execution policy is RemoteSigned because the +In this case, the effective execution policy is **RemoteSigned** because the execution policy for the current user takes precedence over the execution policy set for the local computer. To get the execution policy set for a particular scope, use the **Scope** parameter of `Get-ExecutionPolicy`. -For example, the following command gets the execution policy for the current -user scope: +For example, the following command gets the execution policy for the +**CurrentUser** scope: ```powershell Get-ExecutionPolicy -Scope CurrentUser @@ -173,18 +185,18 @@ To change the PowerShell execution policy on your Windows computer, use the `Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not need to restart PowerShell. -If you set the execution policy for the local computer (the default) or the -current user, the change is saved in the registry and remains effective until -you change it again. +If you set the execution policy for the scopes **LocalMachine** or the +**CurrentUser**, the change is saved in the registry and remains effective +until you change it again. -If you set the execution policy for the current process, it is not saved in +If you set the execution policy for the **Process** scope, it's not saved in the registry. The execution policy is retained until the current process and any child processes are closed. > [!NOTE] -> In Windows Vista and later versions of Windows, to run commands that change -> the execution policy for the local computer (the default), start PowerShell -> with the **Run as administrator** option. +> In Windows Vista and later versions of Windows, to run commands that +> change the execution policy for the local computer, **LocalMachine** scope, +> start PowerShell with the **Run as administrator** option. To change your execution policy: @@ -207,7 +219,7 @@ Set-ExecutionPolicy -ExecutionPolicy -Scope For example: ```powershell -Set-ExecutionPolicy RemoteSigned -Scope CurrentUser +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` A command to change an execution policy can succeed but still not change the @@ -218,24 +230,24 @@ can succeed but be overridden by the execution policy for the current user. ## Remove Your Execution Policy -To remove the execution policy for a particular scope, set the execution -policy to Undefined. +To remove the execution policy for a particular scope, set the execution policy +to **Undefined**. For example, to remove the execution policy for all the users of the local computer: ```powershell -Set-ExecutionPolicy Undefined +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope LocalMachine ``` To remove the execution policy for a **Scope**: ```powershell -Set-ExecutionPolicy Undefined -Scope LocalMachine +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser ``` If no execution policy is set in any scope, the effective execution policy is -Restricted, which is the default for Windows clients. +**Restricted**, which is the default for Windows clients. ## Set a Different Execution Policy for One Session @@ -254,8 +266,8 @@ For example: powershell.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it -is stored in the `$env:PSExecutionPolicyPreference` environment variable. The +The execution policy that you set is not stored in the registry. Instead, it is +stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. @@ -266,8 +278,8 @@ execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy -You can use the **Turn on Script Execution** Group Policy setting to manage -the execution policy of computers in your enterprise. The Group Policy setting +You can use the **Turn on Script Execution** Group Policy setting to manage the +execution policy of computers in your enterprise. The Group Policy setting overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: @@ -310,42 +322,43 @@ For more information, see [about_Group_Policy_Settings](about_Group_Policy_Setti When determining the effective execution policy for a session, PowerShell evaluates the execution policies in the following precedence order: -- Group Policy: Computer Configuration -- Group Policy: User Configuration +- Group Policy: MachinePolicy +- Group Policy: UserPolicy - Execution Policy: Process (or `powershell.exe -ExecutionPolicy`) - Execution Policy: CurrentUser - Execution Policy: LocalMachine ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is RemoteSigned, PowerShell will not run -unsigned scripts that are downloaded from the Internet which includes e-mail -and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell will not +run unsigned scripts that are downloaded from the Internet which includes +e-mail and instant messaging programs. -You can sign the script or elect to run an unsigned script without changing -the execution policy. +You can sign the script or elect to run an unsigned script without changing the +execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the -`Get-Item` cmdlet to detect files that are blocked because they were -downloaded from the Internet, and you can use the `Unblock-File` cmdlet to -unblock the scripts so that you can run them in PowerShell. +`Get-Item` cmdlet to detect files that are blocked because they were downloaded +from the Internet, and you can use the `Unblock-File` cmdlet to unblock the +scripts so that you can run them in PowerShell. -For more information, see [about_Signing](about_Signing.md), -[Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). +For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), +and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). ## See Also [about_Environment_Variables](about_Environment_Variables.md) +[about_Group_Policy_Settings](about_Group_Policy_Settings.md) + [about_Signing](about_Signing.md) [Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) +[Pwsh Console Help](about_pwsh.md) -[PowerShell.exe Command-Line Help](/powershell/scripting/components/console/powershell.exe-command-line-help) \ No newline at end of file +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) + +[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) diff --git a/reference/5.1/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md b/reference/5.1/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md index 418f5d06382e..075d72dd77d0 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md @@ -3,7 +3,7 @@ external help file: Microsoft.PowerShell.Security.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Security -ms.date: 06/09/2017 +ms.date: 3/22/2019 online version: http://go.microsoft.com/fwlink/?LinkId=821714 schema: 2.0.0 title: Get-ExecutionPolicy @@ -16,99 +16,157 @@ Gets the execution policies for the current session. ## SYNTAX +### All + ``` Get-ExecutionPolicy [[-Scope] ] [-List] [] ``` ## DESCRIPTION -The **Get-ExecutionPolicy** cmdlet gets the execution policies for the current session. -The execution policy is determined by execution policies that you set by using Set-ExecutionPolicy and the Group Policy settings for the Windows PowerShell execution policy. -The default value is Restricted. +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. -Without parameters, **Get-ExecutionPolicy** gets the execution policy that is effective in the session. -You can use the *List* parameter to get all execution policies that affect the session or the *Scope* parameter to get the execution policy for a particular scope. +The effective execution policy is determined by execution policies that are set by +`Set-ExecutionPolicy` and Group Policy settings. -For more information, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +For more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). ## EXAMPLES -### Example 1: Get the current execution policy -```powershell -PS C:\> Get-ExecutionPolicy -Restricted -``` +### Example 1: Get all execution policies -This command gets the current execution policy for the computer. +This command displays the execution policies for each scope in the order of precedence. -### Example 2: Set the execution policy ```powershell -PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -PS C:\> Get-ExecutionPolicy -RemoteSigned +Get-ExecutionPolicy -List ``` -These commands set a new user preference for the execution policy and then display the effective execution policy. -In this example, because there is no Group Policy setting, the user preference is the effective policy for the computer. - -### Example 3: Get all execution policies for the current session -```powershell -PS C:\> Get-ExecutionPolicy -List - +```Output Scope ExecutionPolicy ----- --------------- MachinePolicy Undefined UserPolicy Undefined Process Undefined CurrentUser AllSigned -LocalMachine RemoteSigned +LocalMachine Undefined +``` + +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. + +### Example 2: Set an execution policy + +This example shows how to set an execution policy for the local computer. + +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List +``` + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned +``` + +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. + +### Example 3: Get the effective execution policy + +This example shows how to display the effective execution policy for a PowerShell session. + +``` +PS> Get-ExecutionPolicy -List + + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned + +PS> Get-ExecutionPolicy -PS C:\> Get-ExecutionPolicy AllSigned ``` -These commands get all execution policies in the current session and the effective execution policy. +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. The `Get-ExecutionPolicy` cmdlet is run without a parameter to display the effective +execution policy, **AllSigned**. -The first command gets all execution policies that affect the current session. -The policies are listed in precedence order. +### Example 4: Unblock a script to run it without changing the execution policy -The second command gets only the effective execution policy, which is the one set in the CurrentUser scope. +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. + +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. + +``` +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + +PS> Get-ExecutionPolicy -### Example 4: Prevent a unsigned script from running -```powershell -PS C:\> Get-ExecutionPolicy RemoteSigned -The second command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is RemoteSigned. The RemoteSigned policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute -on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. +PS> .\Start-ActivityTracker.ps1 + +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [], PSSecurityException + FullyQualifiedErrorId : UnauthorizedAccess -The third command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path "Start-ActivityTracker.ps1" +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 + +PS> Get-ExecutionPolicy -This command shows the effect of the Unblock-File command. The command does not change the execution policy. However, it unblocks the script so that it runs in Windows PowerShell. -PS C:\> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the RemoteSigned execution policy, which prevents you from running unsigned scripts that are downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. + +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. + +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. + +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. -The first command uses the **Get-ExecutionPolicy** cmdlet to get the effective execution policy in the current session. +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. + +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. ## PARAMETERS ### -List -Gets all execution policy values for the session listed in precedence order. -By default, **Get-ExecutionPolicy** gets only the effective execution policy. + +Gets all execution policy values for the session listed in precedence order. By default, +`Get-ExecutionPolicy` gets only the effective execution policy. ```yaml Type: SwitchParameter @@ -123,56 +181,58 @@ Accept wildcard characters: False ``` ### -Scope -Gets the execution policy in the specified scope. -By default, **Get-ExecutionPolicy** gets the effective execution policy for the current session. -The acceptable values for this parameter are: - -- MachinePolicy. -The execution policy set by a Group Policy for all users of the computer. -- UserPolicy. -The execution policy set by a Group Policy for the current user of the computer. -- Process. -The execution policy that is set for the current Windows PowerShell process. -- CurrentUser. -The execution policy that is set for the current user. -- LocalMachine. -The execution policy that is set for all users of the computer. + +Specifies the scope that is affected by an execution policy. + +The effective execution policy is determined by the order of precedence as follows: + +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: -Accepted values: Process, CurrentUser, LocalMachine, UserPolicy, MachinePolicy +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False Position: 0 -Default value: None +Default value: Effective execution policy Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### None -You cannot pipe input to this cmdlet. + +`Get-ExecutionPolicy` doesn't accept input from the pipeline. ## OUTPUTS ### Microsoft.PowerShell.ExecutionPolicy ## NOTES -* The execution policy is part of the security strategy of Windows PowerShell. It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. - - The effective execution policy is determined by the policies that you set by using the Set-ExecutionPolicy cmdlet and the "Turn on Script Execution" group policies for computers and users. -The precedence order is Computer Group Policy \> User Group Policy \> Process (session) execution policy \> User execution policy \> Computer execution policy. - For more information about Windows PowerShell execution policy, including definitions of the Windows PowerShell policies, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. ## RELATED LINKS +[about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md) + +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) + [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) [Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) diff --git a/reference/5.1/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md b/reference/5.1/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md index e7a6be79f371..3b7aab9ce85a 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md @@ -3,7 +3,7 @@ external help file: Microsoft.PowerShell.Security.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Security -ms.date: 06/09/2017 +ms.date: 3/22/2019 online version: http://go.microsoft.com/fwlink/?LinkId=821719 schema: 2.0.0 title: Set-ExecutionPolicy @@ -12,161 +12,268 @@ title: Set-ExecutionPolicy # Set-ExecutionPolicy ## SYNOPSIS -Changes the user preference for the Windows PowerShell execution policy. +Sets the PowerShell execution policies for Windows computers. ## SYNTAX +### All + ``` -Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] [-WhatIf] - [-Confirm] [] +Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] +[-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Set-ExecutionPolicy** cmdlet changes the user preference for the Windows PowerShell execution policy. -The execution policy is part of the security strategy of Windows PowerShell. -It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. -For more information, see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). +The `Set-ExecutionPolicy` cmdlet changes PowerShell execution policies for Windows computers. For +more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). + +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. -To change the execution policy for the default (LocalMachine) scope, start Windows PowerShell with the "Run as administrator" option. +The `Set-ExecutionPolicy` cmdlet's default scope is **LocalMachine**, which affects everyone who +uses the computer. To change the execution policy for **LocalMachine**, start PowerShell with **Run +as Administrator**. + +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. ## EXAMPLES -### Example 1: Set the shell execution policy -``` -PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -``` +### Example 1: Set an execution policy -This command sets the user preference for the shell execution policy to RemoteSigned. +This example shows how to set the execution policy for the local computer. -### Example 2: Set a shell execution policy that conflicts with the group policy +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List ``` -PS C:\> Set-ExecutionPolicy -ExecutionPolicy Restricted -Set-ExecutionPolicy : Windows PowerShell updated your local preference successfully, but the setting is -overridden by the group policy applied to your system. Due to the override, your shell will retain its current -effective execution policy of "AllSigned". Contact your group policy administrator for more information. -At line:1 char:20 -+ Set-ExecutionPolicy <<<< restricted + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser RemoteSigned + LocalMachine RemoteSigned ``` -This command attempts to set the execution policy for the shell to Restricted. -The Restricted setting is written to the registry, but because it conflicts with a group policy, it is not effective, even though it is more restrictive than the group policy. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. + +### Example 2: Set an execution policy that conflicts with a Group Policy + +This command attempts to set the **LocalMachine** scope's execution policy to **Restricted**. +**LocalMachine** is more restrictive, but isn't the effective policy because it conflicts with a +Group Policy. The **Restricted** policy is written to the registry hive **HKEY_LOCAL_MACHINE**. -### Example 3: Apply the execution policy from a remote computer to the local computer ``` -PS C:\> Invoke-Command -ComputerName "Server01" -ScriptBlock {Get-ExecutionPolicy} | Set-ExecutionPolicy -Force +PS> Set-ExecutionPolicy -ExecutionPolicy Restricted -Scope LocalMachine + +Set-ExecutionPolicy : PowerShell updated your local preference successfully, but the setting is +overridden by the Group Policy applied to your system. Due to the override, your shell will retain +its current effective execution policy of "AllSigned". Contact your Group Policy administrator for +more information. At line:1 char:20 + Set-ExecutionPolicy <<<< restricted + +PS> Get-ChildItem -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds + + Hive: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds + +Name Property +---- -------- +Microsoft.PowerShell Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe + ExecutionPolicy : Restricted +ScriptedDiagnostics ExecutionPolicy : Unrestricted ``` -This command gets the execution policy from a remote computer and applies that execution policy to the local computer. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**Restricted** policy. The **Scope** parameter specifies the default scope value, **LocalMachine**. +The `Get-ChildItem` cmdlet uses the **Path** parameter with the **HKLM** provider to specify +registry location. -The command uses the Invoke-Command cmdlet to send the command to the remote computer. -Because you can pipe an ExecutionPolicy (Microsoft.PowerShell.ExecutionPolicy) object to **Set-ExecutionPolicy**, the **Set-ExecutionPolicy** command does not require an *ExecutionPolicy* parameter. +### Example 3: Apply the execution policy from a remote computer to a local computer -The command uses the *Force* parameter to suppress the user prompt. +This command gets the execution policy object from a remote computer and sets the policy on the +local computer. `Get-ExecutionPolicy` sends a **Microsoft.PowerShell.ExecutionPolicy** object down +the pipeline. `Set-ExecutionPolicy` accepts pipeline input and doesn't require the +**ExecutionPolicy** parameter. -### Example 4: Set the scope for an execution policy ``` -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy AllSigned -Force +PS> Invoke-Command -ComputerName Server01 -ScriptBlock { Get-ExecutionPolicy } | Set-ExecutionPolicy +``` -The second command uses the *List* parameter of the Get-ExecutionPolicy cmdlet to get the execution policies set in each scope. The results show that the execution policy that is set for the current user differs from the execution policy set for all users of the computer. -PS C:\> Get-ExecutionPolicy -List -Scope ExecutionPolicy ------ --------------- -MachinePolicy Undefined -UserPolicy Undefined -Process Undefined -CurrentUser AllSigned -LocalMachine RemoteSigned +The `Invoke-Command` cmdlet is executed at the local computer and sends the **ScriptBlock** to the +remote computer. The **ComputerName** parameter specifies the remote computer, **Server01**. The +**ScriptBlock** parameter runs `Get-ExecutionPolicy` on the remote computer. The +`Get-ExecutionPolicy` object is sent down the pipeline to the `Set-ExecutionPolicy`. +`Set-ExecutionPolicy` applies the execution policy to the local computer's default scope, +**LocalMachine**. +### Example 4: Set the scope for an execution policy + +This example shows how to set an execution policy for a specified scope, **CurrentUser**. The +**CurrentUser** scope only affects the user who sets this scope. + +```powershell +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope CurrentUser +Get-ExecutionPolicy -List +``` -PS C:\> Get-ExecutionPolicy -AllSigned +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned ``` -This example shows how to set an execution policy for a particular scope. +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. -The first command uses the **Set-ExecutionPolicy** cmdlet to set an execution policy of **AllSigned** for the current user. -It uses the *Force* parameter to suppress the user prompt. +The effective execution policy for the user becomes **AllSigned**. ### Example 5: Remove the execution policy for the current user + +This example shows how use the **Undefined** execution policy to remove an execution policy for a +specified scope. + +```powershell +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser +Get-ExecutionPolicy -List ``` -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser Undefined + LocalMachine RemoteSigned ``` -This command uses an execution policy value of Undefined to effectively remove the execution policy that is set for the current user scope. -As a result, the execution policy that is set in Group Policy or in the LocalMachine (all users) scope is effective. +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **Undefined** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. -If you set the execution policy in all scopes to Undefined and the Group Policy is not set, the default execution policy, Restricted, is effective for all users of the computer. +### Example 6: Set the execution policy for the current PowerShell session -### Example 6: Set the execution policy for the current session +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference` and is deleted when the session is +closed. + +```powershell +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope Process ``` -PS C:\> Set-ExecutionPolicy -Scope Process -ExecutionPolicy AllSigned + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process AllSigned + CurrentUser RemoteSigned + LocalMachine RemoteSigned ``` -This command sets an execution policy of AllSigned for only the current Windows PowerShell session. -This execution policy is saved in the PSExecutionPolicyPreference environment variable ($env:PSExecutionPolicyPreference), so it does not affect the value in the registry. -The variable and its value are deleted when the current session is closed. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** +policy. The **Scope** parameter specifies the value **Process**. To view the execution policy +settings, use the `Get-ExecutionPolicy` cmdlet with the **List** parameter. ### Example 7: Unblock a script to run it without changing the execution policy + +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. + +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. + ``` -The first command uses the **Set-ExecutionPolicy** cmdlet to change the execution policy to RemoteSigned. -PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + +PS> Get-ExecutionPolicy -The second command uses the Get-ExecutionPolicy cmdlet to get the effective execution policy in the session. The output shows that it is RemoteSigned. -PS C:\> Get-ExecutionPolicy RemoteSigned -The third command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is RemoteSigned. The RemoteSigned policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 -is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies -at http://go.microsoft.com/fwlink/?LinkID=135170. +PS> .\Start-ActivityTracker.ps1 + +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [], PSSecurityException + FullyQualifiedErrorId : UnauthorizedAccess -The fourth command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path "Start-ActivityTracker.ps1" +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 + +PS> Get-ExecutionPolicy -The fifth and sixth commands show the effect of the **Unblock-File** command. The **Unblock-File** command does not change the execution policy. However, it unblocks the script so it will run in Windows PowerShell. -PS C:\> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the RemoteSigned execution policy, which prevents you from running unsigned scripts that were downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. + +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. + +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. + +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. + +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. + +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. ## PARAMETERS ### -ExecutionPolicy -Specifies the new execution policy. -The acceptable values for this parameter are: - -- Restricted. -Does not load configuration files or run scripts. -Restricted is the default execution policy. -- AllSigned. -Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- RemoteSigned. -Requires that all scripts and configuration files downloaded from the Internet be signed by a trusted publisher. -- Unrestricted. -Loads all configuration files and runs all scripts. -If you run an unsigned script that was downloaded from the Internet, you are prompted for permission before it runs. -- Bypass. -Nothing is blocked and there are no warnings or prompts. -- Undefined. -Removes the currently assigned execution policy from the current scope. -This parameter will not remove an execution policy that is set in a Group Policy scope. + +Specifies the execution policy. If there are no Group Policies and each scope's execution policy is +set to **Undefined**, then **Restricted** becomes the effective policy for all users. + +The acceptable execution policy values are as follows: + +- **AllSigned**. Requires that all scripts and configuration files are signed by a trusted + publisher, including scripts written on the local computer. +- **Bypass**. Nothing is blocked and there are no warnings or prompts. +- **Default**. Sets the default execution policy. **Restricted** for Windows clients or + **RemoteSigned** for Windows servers. +- **RemoteSigned**. Requires that all scripts and configuration files downloaded from the Internet + are signed by a trusted publisher. The default execution policy for Windows server computers. +- **Restricted**. Doesn't load configuration files or run scripts. The default execution policy + Windows client computers. +- **Undefined**. No execution policy is set for the scope. Removes an assigned execution policy from + a scope that is not set by a Group Policy. If the execution policy in all scopes is **Undefined**, + the effective execution policy is **Restricted**. +- **Unrestricted**. Loads all configuration files and runs all scripts. If you run an unsigned + script that was downloaded from the Internet, you are prompted for permission before it runs. ```yaml Type: ExecutionPolicy Parameter Sets: (All) Aliases: -Accepted values: Unrestricted, RemoteSigned, AllSigned, Restricted, Default, Bypass, Undefined +Accepted values: AllSigned, Bypass, Default, RemoteSigned, Restricted, Undefined, Unrestricted Required: True Position: 0 @@ -176,8 +283,9 @@ Accept wildcard characters: False ``` ### -Force -Suppresses all prompts. -By default, **Set-ExecutionPolicy** displays a warning whenever you change the execution policy. + +Suppresses all the confirmation prompts. Use caution with this parameter to avoid unexpected +results. ```yaml Type: SwitchParameter @@ -192,33 +300,42 @@ Accept wildcard characters: False ``` ### -Scope -Specifies the scope of the execution policy. -The default is LocalMachine. -The acceptable values for this parameter are: -- Process: The execution policy affects only the current Windows PowerShell process. -- CurrentUser: The execution policy affects only the current user. -- LocalMachine: The execution policy affects all users of the computer. +Specifies the scope that is affected by an execution policy. The default scope is **LocalMachine**. + +The effective execution policy is determined by the order of precedence as follows: -To remove an execution policy from a particular scope, set the execution policy for that scope to Undefined. +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. -When the value of the *Scope* parameter is Process, the execution policy is saved in the PSExecutionPolicyPreference environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and the variable is deleted when the process is closed. -You cannot change the execution policy of the process by editing the variable. +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. + +Execution policies for the **CurrentUser** scope are written to the registry hive +**HKEY_LOCAL_USER**. + +Execution policies for the **LocalMachine** scope are written to the registry hive +**HKEY_LOCAL_MACHINE**. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: -Accepted values: Process, CurrentUser, LocalMachine, UserPolicy, MachinePolicy +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False Position: 1 -Default value: None +Default value: LocalMachine Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -234,8 +351,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -250,30 +367,53 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### Microsoft.PowerShell.ExecutionPolicy, System.String -You can pipe an execution policy object or a string that contains the name of an execution policy to **Set-ExecutionPolicy**. + +You can pipe an execution policy object or a string that contains the name of an execution policy to +`Set-ExecutionPolicy`. ## OUTPUTS ### None -This cmdlet does not return any output. + +`Set-ExecutionPolicy` doesn't return any output. ## NOTES -* When you use **Set-ExecutionPolicy** in any scope other than Process, the new user preference is saved in the registry and remains unchanged until you change it. When the value of the *Scope* parameter is Process, the user preference is stored in the PSExecutionPolicyPreference environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and it is deleted when the session in which it is effective is closed. - If the "Turn on Script Execution" group policy is enabled for the computer or user, the user preference is saved, but it is not effective, and Windows PowerShell displays a message explaining the conflict. -You cannot use **Set-ExecutionPolicy** to override a Group Policy, even if the user preference is more restrictive than the policy. +`Set-ExecutionPolicy` doesn't change the **MachinePolicy** and **UserPolicy** scopes because they +are set by Group Policies. + +`Set-ExecutionPolicy` doesn't override a Group Policy, even if the user preference is more +restrictive than the policy. + +If the Group Policy **Turn on Script Execution** is enabled for the computer or user, the user +preference is saved, but it is not effective. PowerShell displays a message that explains the +conflict. -* ## RELATED LINKS +[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) + +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) + [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) +[Get-ChildItem](../Microsoft.PowerShell.Management/Get-ChildItem.md) + [Get-ExecutionPolicy](Get-ExecutionPolicy.md) -[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) \ No newline at end of file +[Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md) + +[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) + +[Unblock-File](../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/6/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 23a596cddc3c..bbc51f3275e3 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -1,13 +1,15 @@ --- -ms.date: 01/15/2019 +ms.date: 3/22/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Execution_Policies --- + # About Execution Policies ## Short Description + Describes the PowerShell execution policies and explains how to manage them. ## Long Description @@ -20,9 +22,9 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell -profile. The execution policy for a particular session is stored only in -memory and is lost when the session is closed. +registry. You do not need to set execution policies in your PowerShell profile. +The execution policy for a particular session is stored only in memory and is +lost when the session is closed. The execution policy is not a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at @@ -30,21 +32,14 @@ the command line when they cannot run a script. Instead, the execution policy helps users to set basic rules and prevents them from violating them unintentionally. -For non-Windows computers, the default execution policy is **Unrestricted** -and cannot be changed. The `Set-ExecutionPolicy` cmdlet is available but -displays a PowerShell console message that it is not supported. +For non-Windows computers, the default execution policy is **Unrestricted** and +cannot be changed. The `Set-ExecutionPolicy` cmdlet is available, but +PowerShell displays a console message that it's not supported. ## PowerShell Execution Policies The PowerShell execution policies are as follows: -### Restricted - -- The default execution policy for Windows client computers. -- Permits individual commands, but will not run scripts. -- Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). - ### AllSigned - Scripts can run. @@ -54,6 +49,19 @@ The PowerShell execution policies are as follows: classified as trusted or untrusted. - Risks running signed, but malicious, scripts. +### Bypass + +- Nothing is blocked and there are no warnings or prompts. +- This execution policy is designed for configurations in which a PowerShell + script is built in to a larger application or for configurations in which + PowerShell is the foundation for a program that has its own security model. + +### Default + +- Sets the default execution policy. +- **Restricted** for Windows clients +- **RemoteSigned** for Windows servers. + ### RemoteSigned - The default execution policy for Windows server computers. @@ -68,20 +76,12 @@ The PowerShell execution policies are as follows: - Risks running unsigned scripts from sources other than the Internet and signed, but malicious, scripts. -### Unrestricted - -- The default execution policy for non-Windows computers and cannot be - changed. -- Unsigned scripts can run. There is a risk of running malicious scripts. -- Warns the user before running scripts and configuration files that are - downloaded from the Internet. - -### Bypass +### Restricted -- Nothing is blocked and there are no warnings or prompts. -- This execution policy is designed for configurations in which a PowerShell - script is built in to a larger application or for configurations in which - PowerShell is the foundation for a program that has its own security model. +- The default execution policy for Windows client computers. +- Permits individual commands, but will not run scripts. +- Prevents running of all script files, including formatting and configuration + files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). ### Undefined @@ -89,6 +89,14 @@ The PowerShell execution policies are as follows: - If the execution policy in all scopes is Undefined, the effective execution policy is Restricted, which is the default execution policy. +### Unrestricted + +- The default execution policy for non-Windows computers and cannot be + changed. +- Unsigned scripts can run. There is a risk of running malicious scripts. +- Warns the user before running scripts and configuration files that are + downloaded from the Internet. + > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths > from Internet paths, scripts that are identified by a UNC path might not be @@ -98,19 +106,30 @@ The PowerShell execution policies are as follows: You can set an execution policy that is effective only in a particular scope. -The valid values for **Scope** are Process, CurrentUser, and LocalMachine. -LocalMachine is the default when setting an execution policy. +The valid values for **Scope** are **MachinePolicy**, **UserPolicy**, +**Process**, **CurrentUser**, and **LocalMachine**. **LocalMachine** is the +default when setting an execution policy. -The **Scope** values are listed in precedence order. +The **Scope** values are listed in precedence order. The policy that takes +precedence is effective in the current session, even if a more restrictive +policy was set at a lower level of precedence. -### Process +For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). + +### MachinePolicy -The execution policy affects only the current session. The current PowerShell -process. +Set by a Group Policy for all users of the computer. -The execution policy is stored in the `$env:PSExecutionPolicyPreference` -environment variable, not in the registry, and it is deleted when the session -is closed. You cannot change the policy by editing the variable value. +### UserPolicy + +Set by a Group Policy for the current user of the computer. + +### Process + +The **Process** scope only affects the current PowerShell session. The +execution policy is saved in the environment variable +`$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. ### CurrentUser @@ -119,20 +138,15 @@ The execution policy affects only the current user. It is stored in the ### LocalMachine -The execution policy affects all users on the current computer. It is stored -in the **HKEY_LOCAL_MACHINE** registry subkey. - -The policy that takes precedence is effective in the current session, even if -a more restrictive policy was set at a lower level of precedence. - -For more information, see [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md). +The execution policy affects all users on the current computer. It is stored in +the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy -To get the PowerShell execution policy that is in effect in the current -session, use the `Get-ExecutionPolicy` cmdlet. +To get the effective execution policy for the current PowerShell session, use +the `Get-ExecutionPolicy` cmdlet. -The following command gets the current execution policy: +The following command gets the effective execution policy: ```powershell Get-ExecutionPolicy @@ -157,15 +171,15 @@ MachinePolicy Undefined LocalMachine AllSigned ``` -In this case, the effective execution policy is RemoteSigned because the +In this case, the effective execution policy is **RemoteSigned** because the execution policy for the current user takes precedence over the execution policy set for the local computer. To get the execution policy set for a particular scope, use the **Scope** parameter of `Get-ExecutionPolicy`. -For example, the following command gets the execution policy for the current -user scope: +For example, the following command gets the execution policy for the +**CurrentUser** scope: ```powershell Get-ExecutionPolicy -Scope CurrentUser @@ -177,18 +191,18 @@ To change the PowerShell execution policy on your Windows computer, use the `Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not need to restart PowerShell. -If you set the execution policy for the local computer (the default) or the -current user, the change is saved in the registry and remains effective until -you change it again. +If you set the execution policy for the scopes **LocalMachine** or the +**CurrentUser**, the change is saved in the registry and remains effective +until you change it again. -If you set the execution policy for the current process, it is not saved in +If you set the execution policy for the **Process** scope, it's not saved in the registry. The execution policy is retained until the current process and any child processes are closed. > [!NOTE] -> In Windows Vista and later versions of Windows, to run commands that change -> the execution policy for the local computer (the default), start PowerShell -> with the **Run as administrator** option. +> In Windows Vista and later versions of Windows, to run commands that +> change the execution policy for the local computer, **LocalMachine** scope, +> start PowerShell with the **Run as administrator** option. To change your execution policy: @@ -211,7 +225,7 @@ Set-ExecutionPolicy -ExecutionPolicy -Scope For example: ```powershell -Set-ExecutionPolicy RemoteSigned -Scope CurrentUser +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` A command to change an execution policy can succeed but still not change the @@ -222,24 +236,24 @@ can succeed but be overridden by the execution policy for the current user. ## Remove Your Execution Policy -To remove the execution policy for a particular scope, set the execution -policy to Undefined. +To remove the execution policy for a particular scope, set the execution policy +to **Undefined**. For example, to remove the execution policy for all the users of the local computer: ```powershell -Set-ExecutionPolicy Undefined +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope LocalMachine ``` To remove the execution policy for a **Scope**: ```powershell -Set-ExecutionPolicy Undefined -Scope LocalMachine +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser ``` If no execution policy is set in any scope, the effective execution policy is -Restricted, which is the default for Windows clients. +**Restricted**, which is the default for Windows clients. ## Set a Different Execution Policy for One Session @@ -257,8 +271,8 @@ For example: pwsh.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it -is stored in the `$env:PSExecutionPolicyPreference` environment variable. The +The execution policy that you set is not stored in the registry. Instead, it is +stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. @@ -269,8 +283,8 @@ execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy -You can use the **Turn on Script Execution** Group Policy setting to manage -the execution policy of computers in your enterprise. The Group Policy setting +You can use the **Turn on Script Execution** Group Policy setting to manage the +execution policy of computers in your enterprise. The Group Policy setting overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: @@ -313,42 +327,43 @@ For more information, see [about_Group_Policy_Settings](about_Group_Policy_Setti When determining the effective execution policy for a session, PowerShell evaluates the execution policies in the following precedence order: -- Group Policy: Computer Configuration -- Group Policy: User Configuration +- Group Policy: MachinePolicy +- Group Policy: UserPolicy - Execution Policy: Process (or `pwsh.exe -ExecutionPolicy`) - Execution Policy: CurrentUser - Execution Policy: LocalMachine ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is RemoteSigned, PowerShell will not run -unsigned scripts that are downloaded from the Internet which includes e-mail -and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell will not +run unsigned scripts that are downloaded from the Internet which includes +e-mail and instant messaging programs. -You can sign the script or elect to run an unsigned script without changing -the execution policy. +You can sign the script or elect to run an unsigned script without changing the +execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the -`Get-Item` cmdlet to detect files that are blocked because they were -downloaded from the Internet, and you can use the `Unblock-File` cmdlet to -unblock the scripts so that you can run them in PowerShell. +`Get-Item` cmdlet to detect files that are blocked because they were downloaded +from the Internet, and you can use the `Unblock-File` cmdlet to unblock the +scripts so that you can run them in PowerShell. -For more information, see [about_Signing](about_Signing.md), -[Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). +For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), +and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). ## See Also [about_Environment_Variables](about_Environment_Variables.md) +[about_Group_Policy_Settings](about_Group_Policy_Settings.md) + [about_Signing](about_Signing.md) [Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) +[Pwsh Console Help](about_pwsh.md) + +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -[Pwsh Console Help](about_pwsh.md) \ No newline at end of file +[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md b/reference/6/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md index 558027bee874..075d72dd77d0 100644 --- a/reference/6/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md +++ b/reference/6/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md @@ -3,11 +3,12 @@ external help file: Microsoft.PowerShell.Security.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Security -ms.date: 06/09/2017 +ms.date: 3/22/2019 online version: http://go.microsoft.com/fwlink/?LinkId=821714 schema: 2.0.0 title: Get-ExecutionPolicy --- + # Get-ExecutionPolicy ## SYNOPSIS @@ -15,105 +16,157 @@ Gets the execution policies for the current session. ## SYNTAX +### All + ``` Get-ExecutionPolicy [[-Scope] ] [-List] [] ``` ## DESCRIPTION -The **Get-ExecutionPolicy** cmdlet gets the execution policies for the current session. - -The execution policy is determined by execution policies that you set by using Set-ExecutionPolicy and the Group Policy settings for the PowerShell execution policy. -The default value is Restricted. +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. -Without parameters, **Get-ExecutionPolicy** gets the execution policy that is effective in the session. -You can use the *List* parameter to get all execution policies that affect the session or the *Scope* parameter to get the execution policy for a particular scope. +The effective execution policy is determined by execution policies that are set by +`Set-ExecutionPolicy` and Group Policy settings. For more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). ## EXAMPLES -### Example 1: Get the current execution policy +### Example 1: Get all execution policies + +This command displays the execution policies for each scope in the order of precedence. ```powershell -PS C:\> Get-ExecutionPolicy -Restricted +Get-ExecutionPolicy -List +``` + +```Output +Scope ExecutionPolicy +----- --------------- +MachinePolicy Undefined +UserPolicy Undefined +Process Undefined +CurrentUser AllSigned +LocalMachine Undefined ``` -This command gets the current execution policy for the computer. +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. + +### Example 2: Set an execution policy -### Example 2: Set the execution policy +This example shows how to set an execution policy for the local computer. ```powershell -PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -PS C:\> Get-ExecutionPolicy -RemoteSigned +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List ``` -These commands set a new user preference for the execution policy and then display the effective execution policy. -In this example, because there is no Group Policy setting, the user preference is the effective policy for the computer. +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned +``` -### Example 3: Get all execution policies for the current session +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. -```powershell -PS C:\> Get-ExecutionPolicy -List +### Example 3: Get the effective execution policy -Scope ExecutionPolicy ------ --------------- -MachinePolicy Undefined -UserPolicy Undefined -Process Undefined -CurrentUser AllSigned -LocalMachine RemoteSigned +This example shows how to display the effective execution policy for a PowerShell session. + +``` +PS> Get-ExecutionPolicy -List + + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned + +PS> Get-ExecutionPolicy -PS C:\> Get-ExecutionPolicy AllSigned ``` -These commands get all execution policies in the current session and the effective execution policy. +The `Get-ExecutionPolicy` cmdlet uses the **List** parameter to display each scope's execution +policy. The `Get-ExecutionPolicy` cmdlet is run without a parameter to display the effective +execution policy, **AllSigned**. -The first command gets all execution policies that affect the current session. -The policies are listed in precedence order. +### Example 4: Unblock a script to run it without changing the execution policy -The second command gets only the effective execution policy, which is the one set in the CurrentUser scope. +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. -### Example 4: Prevent a unsigned script from running +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. + +``` +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + +PS> Get-ExecutionPolicy -```powershell -PS C:\> Get-ExecutionPolicy RemoteSigned -The second command shows what happens when you run a blocked script in a PowerShell session in which the execution policy is RemoteSigned. The RemoteSigned policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute -on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. +PS> .\Start-ActivityTracker.ps1 + +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [], PSSecurityException + FullyQualifiedErrorId : UnauthorizedAccess -The third command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path "Start-ActivityTracker.ps1" +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 + +PS> Get-ExecutionPolicy -This command shows the effect of the Unblock-File command. The command does not change the execution policy. However, it unblocks the script so that it runs in PowerShell. -PS C:\> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the RemoteSigned execution policy, which prevents you from running unsigned scripts that are downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. + +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. + +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. + +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. + +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. -The first command uses the **Get-ExecutionPolicy** cmdlet to get the effective execution policy in the current session. +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. ## PARAMETERS ### -List -Gets all execution policy values for the session listed in precedence order. -By default, **Get-ExecutionPolicy** gets only the effective execution policy. +Gets all execution policy values for the session listed in precedence order. By default, +`Get-ExecutionPolicy` gets only the effective execution policy. ```yaml Type: SwitchParameter @@ -129,43 +182,40 @@ Accept wildcard characters: False ### -Scope -Gets the execution policy in the specified scope. -By default, **Get-ExecutionPolicy** gets the effective execution policy for the current session. -The acceptable values for this parameter are: - -- MachinePolicy. -The execution policy set by a Group Policy for all users of the computer. -- UserPolicy. -The execution policy set by a Group Policy for the current user of the computer. -- Process. -The execution policy that is set for the current PowerShell process. -- CurrentUser. -The execution policy that is set for the current user. -- LocalMachine. -The execution policy that is set for all users of the computer. +Specifies the scope that is affected by an execution policy. + +The effective execution policy is determined by the order of precedence as follows: + +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: -Accepted values: Process, CurrentUser, LocalMachine, UserPolicy, MachinePolicy +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False Position: 0 -Default value: None +Default value: Effective execution policy Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### None -You cannot pipe input to this cmdlet. +`Get-ExecutionPolicy` doesn't accept input from the pipeline. ## OUTPUTS @@ -173,14 +223,15 @@ You cannot pipe input to this cmdlet. ## NOTES -* The execution policy is part of the security strategy of PowerShell. It determines whether you can load configuration files (including your PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. - The effective execution policy is determined by the policies that you set by using the Set-ExecutionPolicy cmdlet and the "Turn on Script Execution" group policies for computers and users. -The precedence order is Computer Group Policy \> User Group Policy \> Process (session) execution policy \> User execution policy \> Computer execution policy. +## RELATED LINKS - For more information about PowerShell execution policy, including definitions of the PowerShell policies, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). +[about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md) -## RELATED LINKS +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) diff --git a/reference/6/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md b/reference/6/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md index f1c5b46ebede..bc8e40ab654f 100644 --- a/reference/6/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md +++ b/reference/6/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md @@ -3,178 +3,282 @@ external help file: Microsoft.PowerShell.Security.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Security -ms.date: 06/09/2017 +ms.date: 3/22/2019 online version: http://go.microsoft.com/fwlink/?LinkId=821719 schema: 2.0.0 title: Set-ExecutionPolicy --- + # Set-ExecutionPolicy ## SYNOPSIS -Changes the user preference for the PowerShell execution policy. +Sets the PowerShell execution policies for Windows computers. ## SYNTAX +### All + ``` -Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] [-WhatIf] - [-Confirm] [] +Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] ] [-Force] +[-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Set-ExecutionPolicy** cmdlet changes the user preference for the PowerShell execution policy. +The `Set-ExecutionPolicy` cmdlet changes PowerShell execution policies for Windows computers. For +more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). + +For non-Windows computers, the default execution policy is **Unrestricted** and cannot be changed. +The `Set-ExecutionPolicy` cmdlet is available, but PowerShell displays a console message that it's +not supported. -The execution policy is part of the security strategy of PowerShell. -It determines whether you can load configuration files (including your PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. -For more information, see [about_Execution_Policies](../Microsoft.PowerShell.Core/about/about_Execution_Policies.md). +An execution policy is part of the PowerShell security strategy. Execution policies determine +whether you can load configuration files, such as your PowerShell profile, or run scripts. And, +whether scripts must be digitally signed before they are run. -To change the execution policy for the default (LocalMachine) scope, start PowerShell with the "Run as administrator" option. +The `Set-ExecutionPolicy` cmdlet's default scope is **LocalMachine**, which affects everyone who +uses the computer. To change the execution policy for **LocalMachine**, start PowerShell with **Run +as Administrator**. + +To display the execution policies for each scope in the order of precedence, use +`Get-ExecutionPolicy -List`. To see the effective execution policy for your PowerShell session use +`Get-ExecutionPolicy` with no parameters. ## EXAMPLES -### Example 1: Set the shell execution policy +### Example 1: Set an execution policy + +This example shows how to set the execution policy for the local computer. +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine +Get-ExecutionPolicy -List ``` -PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser RemoteSigned + LocalMachine RemoteSigned ``` -This command sets the user preference for the shell execution policy to RemoteSigned. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**RemoteSigned** policy. The **Scope** parameter specifies the default scope value, +**LocalMachine**. To view the execution policy settings, use the `Get-ExecutionPolicy` cmdlet with +the **List** parameter. -### Example 2: Set a shell execution policy that conflicts with the group policy +### Example 2: Set an execution policy that conflicts with a Group Policy + +This command attempts to set the **LocalMachine** scope's execution policy to **Restricted**. +**LocalMachine** is more restrictive, but isn't the effective policy because it conflicts with a +Group Policy. The **Restricted** policy is written to the registry hive **HKEY_LOCAL_MACHINE**. ``` -PS C:\> Set-ExecutionPolicy -ExecutionPolicy Restricted +PS> Set-ExecutionPolicy -ExecutionPolicy Restricted -Scope LocalMachine + Set-ExecutionPolicy : PowerShell updated your local preference successfully, but the setting is -overridden by the group policy applied to your system. Due to the override, your shell will retain its current -effective execution policy of "AllSigned". Contact your group policy administrator for more information. -At line:1 char:20 -+ Set-ExecutionPolicy <<<< restricted -``` +overridden by the Group Policy applied to your system. Due to the override, your shell will retain +its current effective execution policy of "AllSigned". Contact your Group Policy administrator for +more information. At line:1 char:20 + Set-ExecutionPolicy <<<< restricted -This command attempts to set the execution policy for the shell to Restricted. -The Restricted setting is written to the registry, but because it conflicts with a group policy, it is not effective, even though it is more restrictive than the group policy. +PS> Get-ChildItem -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds -### Example 3: Apply the execution policy from a remote computer to the local computer + Hive: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds +Name Property +---- -------- +Microsoft.PowerShell Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe + ExecutionPolicy : Restricted +ScriptedDiagnostics ExecutionPolicy : Unrestricted ``` -PS C:\> Invoke-Command -ComputerName "Server01" -ScriptBlock {Get-ExecutionPolicy} | Set-ExecutionPolicy -Force -``` - -This command gets the execution policy from a remote computer and applies that execution policy to the local computer. -The command uses the Invoke-Command cmdlet to send the command to the remote computer. -Because you can pipe an ExecutionPolicy (Microsoft.PowerShell.ExecutionPolicy) object to **Set-ExecutionPolicy**, the **Set-ExecutionPolicy** command does not require an *ExecutionPolicy* parameter. +The `Set-ExecutionPolicy` cmdlet uses the **ExecutionPolicy** parameter to specify the +**Restricted** policy. The **Scope** parameter specifies the default scope value, **LocalMachine**. +The `Get-ChildItem` cmdlet uses the **Path** parameter with the **HKLM** provider to specify +registry location. -The command uses the *Force* parameter to suppress the user prompt. +### Example 3: Apply the execution policy from a remote computer to a local computer -### Example 4: Set the scope for an execution policy +This command gets the execution policy object from a remote computer and sets the policy on the +local computer. `Get-ExecutionPolicy` sends a **Microsoft.PowerShell.ExecutionPolicy** object down +the pipeline. `Set-ExecutionPolicy` accepts pipeline input and doesn't require the +**ExecutionPolicy** parameter. ``` -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy AllSigned -Force +PS> Invoke-Command -ComputerName Server01 -ScriptBlock { Get-ExecutionPolicy } | Set-ExecutionPolicy +``` + +The `Invoke-Command` cmdlet is executed at the local computer and sends the **ScriptBlock** to the +remote computer. The **ComputerName** parameter specifies the remote computer, **Server01**. The +**ScriptBlock** parameter runs `Get-ExecutionPolicy` on the remote computer. The +`Get-ExecutionPolicy` object is sent down the pipeline to the `Set-ExecutionPolicy`. +`Set-ExecutionPolicy` applies the execution policy to the local computer's default scope, +**LocalMachine**. -The second command uses the *List* parameter of the Get-ExecutionPolicy cmdlet to get the execution policies set in each scope. The results show that the execution policy that is set for the current user differs from the execution policy set for all users of the computer. -PS C:\> Get-ExecutionPolicy -List -Scope ExecutionPolicy ------ --------------- -MachinePolicy Undefined -UserPolicy Undefined -Process Undefined -CurrentUser AllSigned -LocalMachine RemoteSigned +### Example 4: Set the scope for an execution policy + +This example shows how to set an execution policy for a specified scope, **CurrentUser**. The +**CurrentUser** scope only affects the user who sets this scope. +```powershell +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope CurrentUser +Get-ExecutionPolicy -List +``` -PS C:\> Get-ExecutionPolicy -AllSigned +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser AllSigned + LocalMachine RemoteSigned ``` -This example shows how to set an execution policy for a particular scope. +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. -The first command uses the **Set-ExecutionPolicy** cmdlet to set an execution policy of **AllSigned** for the current user. -It uses the *Force* parameter to suppress the user prompt. +The effective execution policy for the user becomes **AllSigned**. ### Example 5: Remove the execution policy for the current user +This example shows how use the **Undefined** execution policy to remove an execution policy for a +specified scope. + +```powershell +Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser +Get-ExecutionPolicy -List ``` -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process Undefined + CurrentUser Undefined + LocalMachine RemoteSigned ``` -This command uses an execution policy value of Undefined to effectively remove the execution policy that is set for the current user scope. -As a result, the execution policy that is set in Group Policy or in the LocalMachine (all users) scope is effective. +`Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **Undefined** policy. +The **Scope** parameter specifies the **CurrentUser**. To view the execution policy settings, use +the `Get-ExecutionPolicy` cmdlet with the **List** parameter. -If you set the execution policy in all scopes to Undefined and the Group Policy is not set, the default execution policy, Restricted, is effective for all users of the computer. +### Example 6: Set the execution policy for the current PowerShell session -### Example 6: Set the execution policy for the current session +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference` and is deleted when the session is +closed. +```powershell +Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope Process ``` -PS C:\> Set-ExecutionPolicy -Scope Process -ExecutionPolicy AllSigned + +```Output + Scope ExecutionPolicy + ----- --------------- +MachinePolicy Undefined + UserPolicy Undefined + Process AllSigned + CurrentUser RemoteSigned + LocalMachine RemoteSigned ``` -This command sets an execution policy of AllSigned for only the current PowerShell session. -This execution policy is saved in the PSExecutionPolicyPreference environment variable ($env:PSExecutionPolicyPreference), so it does not affect the value in the registry. -The variable and its value are deleted when the current session is closed. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **AllSigned** +policy. The **Scope** parameter specifies the value **Process**. To view the execution policy +settings, use the `Get-ExecutionPolicy` cmdlet with the **List** parameter. ### Example 7: Unblock a script to run it without changing the execution policy +This example shows how the **RemoteSigned** execution policy prevents you from running unsigned +scripts. + +A best practice is to read the script's code and verify it's safe **before** using the +`Unblock-File` cmdlet. The `Unblock-File` cmdlet unblocks scripts so they can run, but doesn't +change the execution policy. + ``` -The first command uses the **Set-ExecutionPolicy** cmdlet to change the execution policy to RemoteSigned. -PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned +PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine + +PS> Get-ExecutionPolicy -The second command uses the Get-ExecutionPolicy cmdlet to get the effective execution policy in the session. The output shows that it is RemoteSigned. -PS C:\> Get-ExecutionPolicy RemoteSigned -The third command shows what happens when you run a blocked script in a PowerShell session in which the execution policy is RemoteSigned. The RemoteSigned policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 -.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 -is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies -at http://go.microsoft.com/fwlink/?LinkID=135170. +PS> .\Start-ActivityTracker.ps1 + +.\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. +The file .\Start-ActivityTracker.ps1 is not digitally signed. +The script will not execute on the system. +For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + .\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:) [], PSSecurityException + FullyQualifiedErrorId : UnauthorizedAccess -The fourth command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path "Start-ActivityTracker.ps1" +PS> Unblock-File -Path .\Start-ActivityTracker.ps1 + +PS> Get-ExecutionPolicy -The fifth and sixth commands show the effect of the **Unblock-File** command. The **Unblock-File** command does not change the execution policy. However, it unblocks the script so it will run in PowerShell. -PS C:\> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 + +PS> .\Start-ActivityTracker.ps1 + Task 1: ``` -This example shows the effect of the RemoteSigned execution policy, which prevents you from running unsigned scripts that were downloaded from the Internet. -It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. +The `Set-ExecutionPolicy` uses the **ExecutionPolicy** parameter to specify the **RemoteSigned** +policy. The policy is set for the default scope, **LocalMachine**. + +The `Get-ExecutionPolicy` cmdlet shows that **RemoteSigned** is the effective execution policy for +the current PowerShell session. + +The **Start-ActivityTracker.ps1** script is executed from the current directory. The script is +blocked by **RemoteSigned** because the script isn't digitally signed. + +For this example, the script's code was reviewed and verified as safe to run. The `Unblock-File` +cmdlet uses the **Path** parameter to unblock the script. + +To verify that `Unblock-File` didn't change the execution policy, `Get-ExecutionPolicy` displays the +effective execution policy, **RemoteSigned**. + +The script, **Start-ActivityTracker.ps1** is executed from the current directory. The script begins +to run because it was unblocked by the `Unblock-File` cmdlet. ## PARAMETERS ### -ExecutionPolicy -Specifies the new execution policy. -The acceptable values for this parameter are: - -- Restricted. -Does not load configuration files or run scripts. -Restricted is the default execution policy. -- AllSigned. -Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- RemoteSigned. -Requires that all scripts and configuration files downloaded from the Internet be signed by a trusted publisher. -- Unrestricted. -Loads all configuration files and runs all scripts. -If you run an unsigned script that was downloaded from the Internet, you are prompted for permission before it runs. -- Bypass. -Nothing is blocked and there are no warnings or prompts. -- Undefined. -Removes the currently assigned execution policy from the current scope. -This parameter will not remove an execution policy that is set in a Group Policy scope. +Specifies the execution policy. If there are no Group Policies and each scope's execution policy is +set to **Undefined**, then **Restricted** becomes the effective policy for all users. + +The acceptable execution policy values are as follows: + +- **AllSigned**. Requires that all scripts and configuration files are signed by a trusted + publisher, including scripts written on the local computer. +- **Bypass**. Nothing is blocked and there are no warnings or prompts. +- **Default**. Sets the default execution policy. **Restricted** for Windows clients or + **RemoteSigned** for Windows servers. +- **RemoteSigned**. Requires that all scripts and configuration files downloaded from the Internet + are signed by a trusted publisher. The default execution policy for Windows server computers. +- **Restricted**. Doesn't load configuration files or run scripts. The default execution policy + Windows client computers. +- **Undefined**. No execution policy is set for the scope. Removes an assigned execution policy from + a scope that is not set by a Group Policy. If the execution policy in all scopes is **Undefined**, + the effective execution policy is **Restricted**. +- **Unrestricted**. Loads all configuration files and runs all scripts. If you run an unsigned + script that was downloaded from the Internet, you are prompted for permission before it runs. The + default execution policy for non-Windows computers and cannot be changed. ```yaml Type: ExecutionPolicy Parameter Sets: (All) Aliases: -Accepted values: Unrestricted, RemoteSigned, AllSigned, Restricted, Default, Bypass, Undefined +Accepted values: AllSigned, Bypass, Default, RemoteSigned, Restricted, Undefined, Unrestricted Required: True Position: 0 @@ -185,8 +289,8 @@ Accept wildcard characters: False ### -Force -Suppresses all prompts. -By default, **Set-ExecutionPolicy** displays a warning whenever you change the execution policy. +Suppresses all the confirmation prompts. Use caution with this parameter to avoid unexpected +results. ```yaml Type: SwitchParameter @@ -202,28 +306,35 @@ Accept wildcard characters: False ### -Scope -Specifies the scope of the execution policy. -The default is LocalMachine. -The acceptable values for this parameter are: +Specifies the scope that is affected by an execution policy. The default scope is **LocalMachine**. + +The effective execution policy is determined by the order of precedence as follows: -- Process: The execution policy affects only the current PowerShell process. -- CurrentUser: The execution policy affects only the current user. -- LocalMachine: The execution policy affects all users of the computer. +- **MachinePolicy**. Set by a Group Policy for all users of the computer. +- **UserPolicy**. Set by a Group Policy for the current user of the computer. +- **Process**. Affects only the current PowerShell session. +- **CurrentUser**. Affects only the current user. +- **LocalMachine**. Default scope that affects all users of the computer. -To remove an execution policy from a particular scope, set the execution policy for that scope to Undefined. +The **Process** scope only affects the current PowerShell session. The execution policy is saved in +the environment variable `$env:PSExecutionPolicyPreference`, rather than the registry. When the +PowerShell session is closed, the variable and value are deleted. -When the value of the *Scope* parameter is Process, the execution policy is saved in the PSExecutionPolicyPreference environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and the variable is deleted when the process is closed. -You cannot change the execution policy of the process by editing the variable. +Execution policies for the **CurrentUser** scope are written to the registry hive +**HKEY_LOCAL_USER**. + +Execution policies for the **LocalMachine** scope are written to the registry hive +**HKEY_LOCAL_MACHINE**. ```yaml Type: ExecutionPolicyScope Parameter Sets: (All) Aliases: -Accepted values: Process, CurrentUser, LocalMachine, UserPolicy, MachinePolicy +Accepted values: CurrentUser, LocalMachine, MachinePolicy, Process, UserPolicy Required: False Position: 1 -Default value: None +Default value: LocalMachine Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` @@ -246,8 +357,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -263,31 +373,52 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### Microsoft.PowerShell.ExecutionPolicy, System.String -You can pipe an execution policy object or a string that contains the name of an execution policy to **Set-ExecutionPolicy**. +You can pipe an execution policy object or a string that contains the name of an execution policy to +`Set-ExecutionPolicy`. ## OUTPUTS ### None -This cmdlet does not return any output. +`Set-ExecutionPolicy` doesn't return any output. ## NOTES -* When you use **Set-ExecutionPolicy** in any scope other than Process, the new user preference is saved in the registry and remains unchanged until you change it. When the value of the *Scope* parameter is Process, the user preference is stored in the PSExecutionPolicyPreference environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and it is deleted when the session in which it is effective is closed. +`Set-ExecutionPolicy` doesn't change the **MachinePolicy** and **UserPolicy** scopes because they +are set by Group Policies. + +`Set-ExecutionPolicy` doesn't override a Group Policy, even if the user preference is more +restrictive than the policy. + +If the Group Policy **Turn on Script Execution** is enabled for the computer or user, the user +preference is saved, but it is not effective. PowerShell displays a message that explains the +conflict. -* If the "Turn on Script Execution" group policy is enabled for the computer or user, the user preference is saved, but it is not effective, and PowerShell displays a message explaining the conflict. -You cannot use **Set-ExecutionPolicy** to override a Group Policy, even if the user preference is more restrictive than the policy. ## RELATED LINKS +[about_Execution_Policies](../Microsoft.PowerShell.Core/About/about_Execution_Policies.md) + +[about_Group_Policy_Settings](../Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) + [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) +[Get-ChildItem](../Microsoft.PowerShell.Management/Get-ChildItem.md) + [Get-ExecutionPolicy](Get-ExecutionPolicy.md) -[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) \ No newline at end of file +[Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md) + +[Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) + +[Unblock-File](../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file From 0a297a8d22b7c160db9881653b7cf9cad5792e3a Mon Sep 17 00:00:00 2001 From: davidsmatlak Date: Mon, 25 Mar 2019 08:24:04 -0700 Subject: [PATCH 2/3] fixed broken link --- .../About/about_Execution_Policies.md | 4 ++-- .../About/about_Execution_Policies.md | 4 ++-- .../About/about_Execution_Policies.md | 4 ++-- .../About/about_Execution_Policies.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index e69965327b51..1e28116c439a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -357,8 +357,8 @@ and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) -[Pwsh Console Help](about_pwsh.md) +[PowerShell.exe Command-Line Help](/powershell/scripting/components/console/powershell.exe-command-line-help) [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) +[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index b1e1f8da9545..0a41a197e85e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -357,8 +357,8 @@ and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) -[Pwsh Console Help](about_pwsh.md) +[PowerShell.exe Command-Line Help](/powershell/scripting/components/console/powershell.exe-command-line-help) [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) +[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index b1e1f8da9545..0a41a197e85e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -357,8 +357,8 @@ and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) -[Pwsh Console Help](about_pwsh.md) +[PowerShell.exe Command-Line Help](/powershell/scripting/components/console/powershell.exe-command-line-help) [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) +[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index b1e1f8da9545..0a41a197e85e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -357,8 +357,8 @@ and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) -[Pwsh Console Help](about_pwsh.md) +[PowerShell.exe Command-Line Help](/powershell/scripting/components/console/powershell.exe-command-line-help) [Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) +[Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md) \ No newline at end of file From 60aecc50884bf761bbcaa84a2534b0a544c0ad9f Mon Sep 17 00:00:00 2001 From: davidsmatlak Date: Mon, 25 Mar 2019 10:40:43 -0700 Subject: [PATCH 3/3] updated about_Execution_Policies based on review comments --- .../About/about_Execution_Policies.md | 57 ++++++++++--------- .../About/about_Execution_Policies.md | 57 ++++++++++--------- .../About/about_Execution_Policies.md | 57 ++++++++++--------- .../About/about_Execution_Policies.md | 57 ++++++++++--------- .../About/about_Execution_Policies.md | 57 ++++++++++--------- 5 files changed, 145 insertions(+), 140 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 1e28116c439a..65be46ff944e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -22,11 +22,11 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell profile. +registry. You don't need to set execution policies in your PowerShell profile. The execution policy for a particular session is stored only in memory and is lost when the session is closed. -The execution policy is not a security system that restricts user actions. For +The execution policy isn't a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at the command line when they cannot run a script. Instead, the execution policy helps users to set basic rules and prevents them from violating them @@ -41,7 +41,7 @@ The PowerShell execution policies are as follows: - Scripts can run. - Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- Prompts you before running scripts from publishers that you have not yet +- Prompts you before running scripts from publishers that you haven't yet classified as trusted or untrusted. - Risks running signed, but malicious, scripts. @@ -55,7 +55,7 @@ The PowerShell execution policies are as follows: ### Default - Sets the default execution policy. -- **Restricted** for Windows clients +- **Restricted** for Windows clients. - **RemoteSigned** for Windows servers. ### RemoteSigned @@ -63,13 +63,13 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows server computers. - Scripts can run. - Requires a digital signature from a trusted publisher on scripts and - configuration files that are downloaded from the Internet which includes - e-mail and instant messaging programs. -- Does not require digital signatures on scripts that you have written on the - local computer (not downloaded from the Internet). -- Runs scripts that are downloaded from the Internet and not signed, if the - scripts are unblocked, such as by using the Unblock-File cmdlet. -- Risks running unsigned scripts from sources other than the Internet and + configuration files that are downloaded from the internet which includes + email and instant messaging programs. +- Doesn't require digital signatures on scripts that are written on the local + computer and not downloaded from the internet. +- Runs scripts that are downloaded from the internet and not signed, if the + scripts are unblocked, such as by using the `Unblock-File` cmdlet. +- Risks running unsigned scripts from sources other than the internet and signed, but malicious, scripts. ### Restricted @@ -77,24 +77,25 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows client computers. - Permits individual commands, but will not run scripts. - Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). + files (`.ps1xml`), module script files (`.psm1`), and PowerShell profiles + (`.ps1`). ### Undefined - There is no execution policy set in the current scope. -- If the execution policy in all scopes is Undefined, the effective execution - policy is Restricted, which is the default execution policy. +- If the execution policy in all scopes is **Undefined**, the effective + execution policy is **Restricted**, which is the default execution policy. ### Unrestricted - Unsigned scripts can run. There is a risk of running malicious scripts. - Warns the user before running scripts and configuration files that are - downloaded from the Internet. + downloaded from the internet. > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths -> from Internet paths, scripts that are identified by a UNC path might not be -> permitted to run with the RemoteSigned execution policy. +> from internet paths, scripts that are identified by a UNC path might not be +> permitted to run with the **RemoteSigned** execution policy. ## Execution Policy Scope @@ -127,12 +128,12 @@ PowerShell session is closed, the variable and value are deleted. ### CurrentUser -The execution policy affects only the current user. It is stored in the +The execution policy affects only the current user. It's stored in the **HKEY_CURRENT_USER** registry subkey. ### LocalMachine -The execution policy affects all users on the current computer. It is stored in +The execution policy affects all users on the current computer. It's stored in the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy @@ -182,7 +183,7 @@ Get-ExecutionPolicy -Scope CurrentUser ## Change Your Execution Policy To change the PowerShell execution policy on your Windows computer, use the -`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not +`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You don't need to restart PowerShell. If you set the execution policy for the scopes **LocalMachine** or the @@ -266,14 +267,14 @@ For example: powershell.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it is +The execution policy that you set isn't stored in the registry. Instead, it's stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. During the session, the execution policy that is set for the session takes precedence over an execution policy that is set in the registry for the local -computer or current user. However, it does not take precedence over the +computer or current user. However, it doesn't take precedence over the execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy @@ -285,7 +286,7 @@ overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: - If you disable **Turn on Script Execution**, scripts do not run. This is - equivalent to the Restricted execution policy. + equivalent to the **Restricted** execution policy. - If you enable **Turn on Script Execution**, you can select an execution policy. The Group Policy settings are equivalent to the following execution policy settings: @@ -330,17 +331,17 @@ evaluates the execution policies in the following precedence order: ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is **RemoteSigned**, PowerShell will not -run unsigned scripts that are downloaded from the Internet which includes -e-mail and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell won't run +unsigned scripts that are downloaded from the internet which includes email and +instant messaging programs. You can sign the script or elect to run an unsigned script without changing the execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the `Get-Item` cmdlet to detect files that are blocked because they were downloaded -from the Internet, and you can use the `Unblock-File` cmdlet to unblock the -scripts so that you can run them in PowerShell. +from the internet. Use the `Unblock-File` cmdlet to unblock the scripts so that +you can run them in PowerShell. For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 0a41a197e85e..f810b823e200 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -22,11 +22,11 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell profile. +registry. You don't need to set execution policies in your PowerShell profile. The execution policy for a particular session is stored only in memory and is lost when the session is closed. -The execution policy is not a security system that restricts user actions. For +The execution policy isn't a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at the command line when they cannot run a script. Instead, the execution policy helps users to set basic rules and prevents them from violating them @@ -41,7 +41,7 @@ The PowerShell execution policies are as follows: - Scripts can run. - Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- Prompts you before running scripts from publishers that you have not yet +- Prompts you before running scripts from publishers that you haven't yet classified as trusted or untrusted. - Risks running signed, but malicious, scripts. @@ -55,7 +55,7 @@ The PowerShell execution policies are as follows: ### Default - Sets the default execution policy. -- **Restricted** for Windows clients +- **Restricted** for Windows clients. - **RemoteSigned** for Windows servers. ### RemoteSigned @@ -63,13 +63,13 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows server computers. - Scripts can run. - Requires a digital signature from a trusted publisher on scripts and - configuration files that are downloaded from the Internet which includes - e-mail and instant messaging programs. -- Does not require digital signatures on scripts that you have written on the - local computer (not downloaded from the Internet). -- Runs scripts that are downloaded from the Internet and not signed, if the - scripts are unblocked, such as by using the Unblock-File cmdlet. -- Risks running unsigned scripts from sources other than the Internet and + configuration files that are downloaded from the internet which includes + email and instant messaging programs. +- Doesn't require digital signatures on scripts that are written on the local + computer and not downloaded from the internet. +- Runs scripts that are downloaded from the internet and not signed, if the + scripts are unblocked, such as by using the `Unblock-File` cmdlet. +- Risks running unsigned scripts from sources other than the internet and signed, but malicious, scripts. ### Restricted @@ -77,24 +77,25 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows client computers. - Permits individual commands, but will not run scripts. - Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). + files (`.ps1xml`), module script files (`.psm1`), and PowerShell profiles + (`.ps1`). ### Undefined - There is no execution policy set in the current scope. -- If the execution policy in all scopes is Undefined, the effective execution - policy is Restricted, which is the default execution policy. +- If the execution policy in all scopes is **Undefined**, the effective + execution policy is **Restricted**, which is the default execution policy. ### Unrestricted - Unsigned scripts can run. There is a risk of running malicious scripts. - Warns the user before running scripts and configuration files that are - downloaded from the Internet. + downloaded from the internet. > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths -> from Internet paths, scripts that are identified by a UNC path might not be -> permitted to run with the RemoteSigned execution policy. +> from internet paths, scripts that are identified by a UNC path might not be +> permitted to run with the **RemoteSigned** execution policy. ## Execution Policy Scope @@ -127,12 +128,12 @@ PowerShell session is closed, the variable and value are deleted. ### CurrentUser -The execution policy affects only the current user. It is stored in the +The execution policy affects only the current user. It's stored in the **HKEY_CURRENT_USER** registry subkey. ### LocalMachine -The execution policy affects all users on the current computer. It is stored in +The execution policy affects all users on the current computer. It's stored in the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy @@ -182,7 +183,7 @@ Get-ExecutionPolicy -Scope CurrentUser ## Change Your Execution Policy To change the PowerShell execution policy on your Windows computer, use the -`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not +`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You don't need to restart PowerShell. If you set the execution policy for the scopes **LocalMachine** or the @@ -266,14 +267,14 @@ For example: powershell.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it is +The execution policy that you set isn't stored in the registry. Instead, it's stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. During the session, the execution policy that is set for the session takes precedence over an execution policy that is set in the registry for the local -computer or current user. However, it does not take precedence over the +computer or current user. However, it doesn't take precedence over the execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy @@ -285,7 +286,7 @@ overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: - If you disable **Turn on Script Execution**, scripts do not run. This is - equivalent to the Restricted execution policy. + equivalent to the **Restricted** execution policy. - If you enable **Turn on Script Execution**, you can select an execution policy. The Group Policy settings are equivalent to the following execution policy settings: @@ -330,17 +331,17 @@ evaluates the execution policies in the following precedence order: ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is **RemoteSigned**, PowerShell will not -run unsigned scripts that are downloaded from the Internet which includes -e-mail and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell won't run +unsigned scripts that are downloaded from the internet which includes email and +instant messaging programs. You can sign the script or elect to run an unsigned script without changing the execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the `Get-Item` cmdlet to detect files that are blocked because they were downloaded -from the Internet, and you can use the `Unblock-File` cmdlet to unblock the -scripts so that you can run them in PowerShell. +from the internet. Use the `Unblock-File` cmdlet to unblock the scripts so that +you can run them in PowerShell. For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 0a41a197e85e..f810b823e200 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -22,11 +22,11 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell profile. +registry. You don't need to set execution policies in your PowerShell profile. The execution policy for a particular session is stored only in memory and is lost when the session is closed. -The execution policy is not a security system that restricts user actions. For +The execution policy isn't a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at the command line when they cannot run a script. Instead, the execution policy helps users to set basic rules and prevents them from violating them @@ -41,7 +41,7 @@ The PowerShell execution policies are as follows: - Scripts can run. - Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- Prompts you before running scripts from publishers that you have not yet +- Prompts you before running scripts from publishers that you haven't yet classified as trusted or untrusted. - Risks running signed, but malicious, scripts. @@ -55,7 +55,7 @@ The PowerShell execution policies are as follows: ### Default - Sets the default execution policy. -- **Restricted** for Windows clients +- **Restricted** for Windows clients. - **RemoteSigned** for Windows servers. ### RemoteSigned @@ -63,13 +63,13 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows server computers. - Scripts can run. - Requires a digital signature from a trusted publisher on scripts and - configuration files that are downloaded from the Internet which includes - e-mail and instant messaging programs. -- Does not require digital signatures on scripts that you have written on the - local computer (not downloaded from the Internet). -- Runs scripts that are downloaded from the Internet and not signed, if the - scripts are unblocked, such as by using the Unblock-File cmdlet. -- Risks running unsigned scripts from sources other than the Internet and + configuration files that are downloaded from the internet which includes + email and instant messaging programs. +- Doesn't require digital signatures on scripts that are written on the local + computer and not downloaded from the internet. +- Runs scripts that are downloaded from the internet and not signed, if the + scripts are unblocked, such as by using the `Unblock-File` cmdlet. +- Risks running unsigned scripts from sources other than the internet and signed, but malicious, scripts. ### Restricted @@ -77,24 +77,25 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows client computers. - Permits individual commands, but will not run scripts. - Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). + files (`.ps1xml`), module script files (`.psm1`), and PowerShell profiles + (`.ps1`). ### Undefined - There is no execution policy set in the current scope. -- If the execution policy in all scopes is Undefined, the effective execution - policy is Restricted, which is the default execution policy. +- If the execution policy in all scopes is **Undefined**, the effective + execution policy is **Restricted**, which is the default execution policy. ### Unrestricted - Unsigned scripts can run. There is a risk of running malicious scripts. - Warns the user before running scripts and configuration files that are - downloaded from the Internet. + downloaded from the internet. > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths -> from Internet paths, scripts that are identified by a UNC path might not be -> permitted to run with the RemoteSigned execution policy. +> from internet paths, scripts that are identified by a UNC path might not be +> permitted to run with the **RemoteSigned** execution policy. ## Execution Policy Scope @@ -127,12 +128,12 @@ PowerShell session is closed, the variable and value are deleted. ### CurrentUser -The execution policy affects only the current user. It is stored in the +The execution policy affects only the current user. It's stored in the **HKEY_CURRENT_USER** registry subkey. ### LocalMachine -The execution policy affects all users on the current computer. It is stored in +The execution policy affects all users on the current computer. It's stored in the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy @@ -182,7 +183,7 @@ Get-ExecutionPolicy -Scope CurrentUser ## Change Your Execution Policy To change the PowerShell execution policy on your Windows computer, use the -`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not +`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You don't need to restart PowerShell. If you set the execution policy for the scopes **LocalMachine** or the @@ -266,14 +267,14 @@ For example: powershell.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it is +The execution policy that you set isn't stored in the registry. Instead, it's stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. During the session, the execution policy that is set for the session takes precedence over an execution policy that is set in the registry for the local -computer or current user. However, it does not take precedence over the +computer or current user. However, it doesn't take precedence over the execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy @@ -285,7 +286,7 @@ overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: - If you disable **Turn on Script Execution**, scripts do not run. This is - equivalent to the Restricted execution policy. + equivalent to the **Restricted** execution policy. - If you enable **Turn on Script Execution**, you can select an execution policy. The Group Policy settings are equivalent to the following execution policy settings: @@ -330,17 +331,17 @@ evaluates the execution policies in the following precedence order: ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is **RemoteSigned**, PowerShell will not -run unsigned scripts that are downloaded from the Internet which includes -e-mail and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell won't run +unsigned scripts that are downloaded from the internet which includes email and +instant messaging programs. You can sign the script or elect to run an unsigned script without changing the execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the `Get-Item` cmdlet to detect files that are blocked because they were downloaded -from the Internet, and you can use the `Unblock-File` cmdlet to unblock the -scripts so that you can run them in PowerShell. +from the internet. Use the `Unblock-File` cmdlet to unblock the scripts so that +you can run them in PowerShell. For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 0a41a197e85e..f810b823e200 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -22,11 +22,11 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell profile. +registry. You don't need to set execution policies in your PowerShell profile. The execution policy for a particular session is stored only in memory and is lost when the session is closed. -The execution policy is not a security system that restricts user actions. For +The execution policy isn't a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at the command line when they cannot run a script. Instead, the execution policy helps users to set basic rules and prevents them from violating them @@ -41,7 +41,7 @@ The PowerShell execution policies are as follows: - Scripts can run. - Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- Prompts you before running scripts from publishers that you have not yet +- Prompts you before running scripts from publishers that you haven't yet classified as trusted or untrusted. - Risks running signed, but malicious, scripts. @@ -55,7 +55,7 @@ The PowerShell execution policies are as follows: ### Default - Sets the default execution policy. -- **Restricted** for Windows clients +- **Restricted** for Windows clients. - **RemoteSigned** for Windows servers. ### RemoteSigned @@ -63,13 +63,13 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows server computers. - Scripts can run. - Requires a digital signature from a trusted publisher on scripts and - configuration files that are downloaded from the Internet which includes - e-mail and instant messaging programs. -- Does not require digital signatures on scripts that you have written on the - local computer (not downloaded from the Internet). -- Runs scripts that are downloaded from the Internet and not signed, if the - scripts are unblocked, such as by using the Unblock-File cmdlet. -- Risks running unsigned scripts from sources other than the Internet and + configuration files that are downloaded from the internet which includes + email and instant messaging programs. +- Doesn't require digital signatures on scripts that are written on the local + computer and not downloaded from the internet. +- Runs scripts that are downloaded from the internet and not signed, if the + scripts are unblocked, such as by using the `Unblock-File` cmdlet. +- Risks running unsigned scripts from sources other than the internet and signed, but malicious, scripts. ### Restricted @@ -77,24 +77,25 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows client computers. - Permits individual commands, but will not run scripts. - Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). + files (`.ps1xml`), module script files (`.psm1`), and PowerShell profiles + (`.ps1`). ### Undefined - There is no execution policy set in the current scope. -- If the execution policy in all scopes is Undefined, the effective execution - policy is Restricted, which is the default execution policy. +- If the execution policy in all scopes is **Undefined**, the effective + execution policy is **Restricted**, which is the default execution policy. ### Unrestricted - Unsigned scripts can run. There is a risk of running malicious scripts. - Warns the user before running scripts and configuration files that are - downloaded from the Internet. + downloaded from the internet. > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths -> from Internet paths, scripts that are identified by a UNC path might not be -> permitted to run with the RemoteSigned execution policy. +> from internet paths, scripts that are identified by a UNC path might not be +> permitted to run with the **RemoteSigned** execution policy. ## Execution Policy Scope @@ -127,12 +128,12 @@ PowerShell session is closed, the variable and value are deleted. ### CurrentUser -The execution policy affects only the current user. It is stored in the +The execution policy affects only the current user. It's stored in the **HKEY_CURRENT_USER** registry subkey. ### LocalMachine -The execution policy affects all users on the current computer. It is stored in +The execution policy affects all users on the current computer. It's stored in the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy @@ -182,7 +183,7 @@ Get-ExecutionPolicy -Scope CurrentUser ## Change Your Execution Policy To change the PowerShell execution policy on your Windows computer, use the -`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not +`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You don't need to restart PowerShell. If you set the execution policy for the scopes **LocalMachine** or the @@ -266,14 +267,14 @@ For example: powershell.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it is +The execution policy that you set isn't stored in the registry. Instead, it's stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. During the session, the execution policy that is set for the session takes precedence over an execution policy that is set in the registry for the local -computer or current user. However, it does not take precedence over the +computer or current user. However, it doesn't take precedence over the execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy @@ -285,7 +286,7 @@ overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: - If you disable **Turn on Script Execution**, scripts do not run. This is - equivalent to the Restricted execution policy. + equivalent to the **Restricted** execution policy. - If you enable **Turn on Script Execution**, you can select an execution policy. The Group Policy settings are equivalent to the following execution policy settings: @@ -330,17 +331,17 @@ evaluates the execution policies in the following precedence order: ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is **RemoteSigned**, PowerShell will not -run unsigned scripts that are downloaded from the Internet which includes -e-mail and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell won't run +unsigned scripts that are downloaded from the internet which includes email and +instant messaging programs. You can sign the script or elect to run an unsigned script without changing the execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the `Get-Item` cmdlet to detect files that are blocked because they were downloaded -from the Internet, and you can use the `Unblock-File` cmdlet to unblock the -scripts so that you can run them in PowerShell. +from the internet. Use the `Unblock-File` cmdlet to unblock the scripts so that +you can run them in PowerShell. For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md). diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/6/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index bbc51f3275e3..4b37bdaf6886 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -22,11 +22,11 @@ for the current user, or for a particular session. You can also use a Group Policy setting to set execution policies for computers and users. Execution policies for the local computer and current user are stored in the -registry. You do not need to set execution policies in your PowerShell profile. +registry. You don't need to set execution policies in your PowerShell profile. The execution policy for a particular session is stored only in memory and is lost when the session is closed. -The execution policy is not a security system that restricts user actions. For +The execution policy isn't a security system that restricts user actions. For example, users can easily circumvent a policy by typing the script contents at the command line when they cannot run a script. Instead, the execution policy helps users to set basic rules and prevents them from violating them @@ -45,7 +45,7 @@ The PowerShell execution policies are as follows: - Scripts can run. - Requires that all scripts and configuration files be signed by a trusted publisher, including scripts that you write on the local computer. -- Prompts you before running scripts from publishers that you have not yet +- Prompts you before running scripts from publishers that you haven't yet classified as trusted or untrusted. - Risks running signed, but malicious, scripts. @@ -59,7 +59,7 @@ The PowerShell execution policies are as follows: ### Default - Sets the default execution policy. -- **Restricted** for Windows clients +- **Restricted** for Windows clients. - **RemoteSigned** for Windows servers. ### RemoteSigned @@ -67,13 +67,13 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows server computers. - Scripts can run. - Requires a digital signature from a trusted publisher on scripts and - configuration files that are downloaded from the Internet which includes - e-mail and instant messaging programs. -- Does not require digital signatures on scripts that you have written on the - local computer (not downloaded from the Internet). -- Runs scripts that are downloaded from the Internet and not signed, if the - scripts are unblocked, such as by using the Unblock-File cmdlet. -- Risks running unsigned scripts from sources other than the Internet and + configuration files that are downloaded from the internet which includes + email and instant messaging programs. +- Doesn't require digital signatures on scripts that are written on the local + computer and not downloaded from the internet. +- Runs scripts that are downloaded from the internet and not signed, if the + scripts are unblocked, such as by using the `Unblock-File` cmdlet. +- Risks running unsigned scripts from sources other than the internet and signed, but malicious, scripts. ### Restricted @@ -81,13 +81,14 @@ The PowerShell execution policies are as follows: - The default execution policy for Windows client computers. - Permits individual commands, but will not run scripts. - Prevents running of all script files, including formatting and configuration - files (.ps1xml), module script files (.psm1), and PowerShell profiles (.ps1). + files (`.ps1xml`), module script files (`.psm1`), and PowerShell profiles + (`.ps1`). ### Undefined - There is no execution policy set in the current scope. -- If the execution policy in all scopes is Undefined, the effective execution - policy is Restricted, which is the default execution policy. +- If the execution policy in all scopes is **Undefined**, the effective + execution policy is **Restricted**, which is the default execution policy. ### Unrestricted @@ -95,12 +96,12 @@ The PowerShell execution policies are as follows: changed. - Unsigned scripts can run. There is a risk of running malicious scripts. - Warns the user before running scripts and configuration files that are - downloaded from the Internet. + downloaded from the internet. > [!NOTE] > On systems that do not distinguish Universal Naming Convention (UNC) paths -> from Internet paths, scripts that are identified by a UNC path might not be -> permitted to run with the RemoteSigned execution policy. +> from internet paths, scripts that are identified by a UNC path might not be +> permitted to run with the **RemoteSigned** execution policy. ## Execution Policy Scope @@ -133,12 +134,12 @@ PowerShell session is closed, the variable and value are deleted. ### CurrentUser -The execution policy affects only the current user. It is stored in the +The execution policy affects only the current user. It's stored in the **HKEY_CURRENT_USER** registry subkey. ### LocalMachine -The execution policy affects all users on the current computer. It is stored in +The execution policy affects all users on the current computer. It's stored in the **HKEY_LOCAL_MACHINE** registry subkey. ## Get Your Execution Policy @@ -188,7 +189,7 @@ Get-ExecutionPolicy -Scope CurrentUser ## Change Your Execution Policy To change the PowerShell execution policy on your Windows computer, use the -`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You do not +`Set-ExecutionPolicy` cmdlet. The change is effective immediately. You don't need to restart PowerShell. If you set the execution policy for the scopes **LocalMachine** or the @@ -271,14 +272,14 @@ For example: pwsh.exe -ExecutionPolicy AllSigned ``` -The execution policy that you set is not stored in the registry. Instead, it is +The execution policy that you set isn't stored in the registry. Instead, it's stored in the `$env:PSExecutionPolicyPreference` environment variable. The variable is deleted when you close the session in which the policy is set. You cannot change the policy by editing the variable value. During the session, the execution policy that is set for the session takes precedence over an execution policy that is set in the registry for the local -computer or current user. However, it does not take precedence over the +computer or current user. However, it doesn't take precedence over the execution policy set by using a Group Policy. ## Use Group Policy to Manage Execution Policy @@ -290,7 +291,7 @@ overrides the execution policies set in PowerShell in all scopes. The **Turn on Script Execution** policy settings are as follows: - If you disable **Turn on Script Execution**, scripts do not run. This is - equivalent to the Restricted execution policy. + equivalent to the **Restricted** execution policy. - If you enable **Turn on Script Execution**, you can select an execution policy. The Group Policy settings are equivalent to the following execution policy settings: @@ -335,17 +336,17 @@ evaluates the execution policies in the following precedence order: ## Manage Signed and Unsigned Scripts -If your PowerShell execution policy is **RemoteSigned**, PowerShell will not -run unsigned scripts that are downloaded from the Internet which includes -e-mail and instant messaging programs. +If your PowerShell execution policy is **RemoteSigned**, PowerShell won't run +unsigned scripts that are downloaded from the internet which includes email and +instant messaging programs. You can sign the script or elect to run an unsigned script without changing the execution policy. Beginning in PowerShell 3.0, you can use the **Stream** parameter of the `Get-Item` cmdlet to detect files that are blocked because they were downloaded -from the Internet, and you can use the `Unblock-File` cmdlet to unblock the -scripts so that you can run them in PowerShell. +from the internet. Use the `Unblock-File` cmdlet to unblock the scripts so that +you can run them in PowerShell. For more information, see [about_Signing](about_Signing.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), and [Unblock-File](../../Microsoft.PowerShell.Utility/Unblock-File.md).