Set-Acl (Microsoft.PowerShell.Security) - PowerShell (2024)

Changes the security descriptor of a specified item, such as a file or a registry key.

Syntax

Set-Acl [-Path] <String[]> [-AclObject] <Object> [-ClearCentralAccessPolicy] [-Passthru] [-Filter <String>] [-Include <String[]>] [-Exclude <String[]>] [-WhatIf] [-Confirm] [<CommonParameters>]

Set-Acl [-InputObject] <PSObject> [-AclObject] <Object> [-Passthru] [-Filter <String>] [-Include <String[]>] [-Exclude <String[]>] [-WhatIf] [-Confirm] [<CommonParameters>]

Set-Acl -LiteralPath <String[]> [-AclObject] <Object> [-ClearCentralAccessPolicy] [-Passthru] [-Filter <String>] [-Include <String[]>] [-Exclude <String[]>] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

This cmdlet is only available on the Windows platform.

The Set-Acl cmdlet changes the security descriptor of a specified item, such as a file or aregistry key, to match the values in a security descriptor that you supply.

To use Set-Acl, use the Path or InputObject parameter to identify the item whose securitydescriptor you want to change. Then, use the AclObject or SecurityDescriptor parameters tosupply a security descriptor that has the values you want to apply. Set-Acl applies the securitydescriptor that is supplied. It uses the value of the AclObject parameter as a model and changesthe values in the item's security descriptor to match the values in the AclObject parameter.

Examples

Example 1: Copy a security descriptor from one file to another

$DogACL = Get-Acl -Path "C:\Dog.txt"Set-Acl -Path "C:\Cat.txt" -AclObject $DogACL

These commands copy the values from the security descriptor of the Dog.txt file to the securitydescriptor of the Cat.txt file. When the commands complete, the security descriptors of the Dog.txtand Cat.txt files are identical.

The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file.The assignment operator (=) stores the security descriptor in the value of the $DogACL variable.

The second command uses Set-Acl to change the values in the ACL of Cat.txt to the values in$DogACL.

The value of the Path parameter is the path to the Cat.txt file. The value of the AclObjectparameter is the model ACL, in this case, the ACL of Dog.txt as saved in the $DogACL variable.

Example 2: Use the pipeline operator to pass a descriptor

Get-Acl -Path "C:\Dog.txt" | Set-Acl -Path "C:\Cat.txt"

This command is almost the same as the command in the previous example, except that it uses apipeline operator (|) to send the security descriptor from a Get-Acl command to a Set-Aclcommand.

The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. Thepipeline operator (|) passes an object that represents the Dog.txt security descriptor to theSet-Acl cmdlet.

The second command uses Set-Acl to apply the security descriptor of Dog.txt to Cat.txt.When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical.

Example 3: Apply a security descriptor to multiple files

$NewAcl = Get-Acl File0.txtGet-ChildItem -Path "C:\temp" -Recurse -Include "*.txt" -Force | Set-Acl -AclObject $NewAcl

These commands apply the security descriptors in the File0.txt file to all text files in the C:\Tempdirectory and all of its subdirectories.

The first command gets the security descriptor of the File0.txt file in the current directory anduses the assignment operator (=) to store it in the $NewACL variable.

The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in theC:\Temp directory. The Recurse parameter extends the command to all subdirectories ofC:\temp. The Include parameter limits the files retrieved to those with the .txt file nameextension. The Force parameter gets hidden files, which would otherwise be excluded. (You cannotuse c:\temp\*.txt, because the Recurse parameter works on directories, not on files.)

The pipeline operator (|) sends the objects representing the retrieved files to the Set-Aclcmdlet, which applies the security descriptor in the AclObject parameter to all of the files inthe pipeline.

In practice, it is best to use the WhatIf parameter with all Set-Acl commands that can affectmore than one item. In this case, the second command in the pipeline would beSet-Acl -AclObject $NewAcl -WhatIf. This command lists the files that would be affected by thecommand. After reviewing the result, you can run the command again without the WhatIf parameter.

Example 4: Disable inheritance and preserve inherited access rules

$NewAcl = Get-Acl -Path "C:\Pets\Dog.txt"$isProtected = $true$preserveInheritance = $true$NewAcl.SetAccessRuleProtection($isProtected, $preserveInheritance)Set-Acl -Path "C:\Pets\Dog.txt" -AclObject $NewAcl

These commands disable access inheritance from parent folders, while still preserving the existinginherited access rules.

The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file.

Next, variables are created to convert the inherited access rules to explicit access rules. Toprotect the access rules associated with this from inheritance, set the $isProtected variable to$true. To allow inheritance, set $isProtected to $false. For more information, seeset access rule protection.

Set the $preserveInheritance variable to $true to preserve inherited access rules or $false toremove inherited access rules. Then the access rule protection is updated using theSetAccessRuleProtection() method.

The last command uses Set-Acl to apply the security descriptor of to Dog.txt. When the commandcompletes, the ACLs of the Dog.txt that were inherited from the Pets folder will be applied directlyto Dog.txt, and new access policies added to Pets will not change the access to Dog.txt.

Example 5: Grant Administrators Full Control of the file

$NewAcl = Get-Acl -Path "C:\Pets\Dog.txt"# Set properties$identity = "BUILTIN\Administrators"$fileSystemRights = "FullControl"$type = "Allow"# Create new rule$fileSystemAccessRuleArgumentList = $identity, $fileSystemRights, $type$fileSystemAccessRule = New-Object -TypeName System.Security.AccessControl.FileSystemAccessRule -ArgumentList $fileSystemAccessRuleArgumentList# Apply new rule$NewAcl.SetAccessRule($fileSystemAccessRule)Set-Acl -Path "C:\Pets\Dog.txt" -AclObject $NewAcl

This command will grant the BUILTIN\Administrators group Full control of the Dog.txt file.

The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file.

Next variables are created to grant the BUILTIN\Administrators group full control of the Dog.txtfile. The $identity variable set to the name of auser account. The$fileSystemRights variable set to FullControl, and can be any one of theFileSystemRights values that specifiesthe type of operation associated with the access rule. The $type variable set to "Allow" tospecifies whether to allow or deny the operation. The $fileSystemAccessRuleArgumentList variableis an argument list is to be passed when making the new FileSystemAccessRule object. Then a newFileSystemAccessRule object is created, and the FileSystemAccessRule object is passed to theSetAccessRule() method, adds the new access rule.

The last command uses Set-Acl to apply the security descriptor of to Dog.txt. When the commandcompletes, the BUILTIN\Administrators group will have full control of the Dog.txt.

Parameters

-AclObject

-ClearCentralAccessPolicy

-Confirm

-Exclude

-Filter

-Include

-InputObject

-LiteralPath

-Passthru

-Path

-WhatIf

Inputs

ObjectSecurity

You can pipe an ACL object to this cmdlet.

CommonSecurityDescriptor

You can pipe a security descriptor to this cmdlet.

Outputs

None

By default, this cmdlet returns no output.

FileSecurity

When you use the PassThru parameter, this cmdlet returns a security object. The type of thesecurity object depends on the type of the item.

Notes

This cmdlet is only available on Windows platforms.

The Set-Acl cmdlet is supported by the PowerShell file system and registry providers. As such, youcan use it to change the security descriptors of files, directories, and registry keys.

• Get-Acl
• FileSystemAccessRule
• ObjectSecurity.SetAccessRuleProtection
• FileSystemRights