This is a part of an on-going blog series written by Adam Gordon. Each week, Adam will walk you through a PowerShell command, showing you when and how to use each one. This week, Adam covers Set-Acl.
When to use Set-Acl?
The Set-Acl cmdlet changes the security descriptor of a specified item, such as a file or a registry 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 security descriptor you want to change. Then, use the -AclObject or -SecurityDescriptor parameters to supply a security descriptor that has the values you want to apply.
Set-Acl applies the security descriptor that is supplied. It uses the value of the -AclObject parameter as a model and changes the values in the item’s security descriptor to match the values in the -AclObject parameter.
What version of PowerShell am I using?
Get the PowerShell Version from your machine:
This command shows you the PowerShell version information on your machine.
How to use Set-Acl?
Copy a security descriptor from one file to another:
$ITPACL = Get-Acl -Path “C:\PShellTest\ITP.txt”
Set-Acl -Path “C:\PShellTest\TV.txt” -AclObject $ITPACL
These commands copy the values from the security descriptor of the ITP.txt file to the security descriptor of the TV.txt file. When the commands complete, the security descriptors of the ITP.txt and TV.txt files are identical.
The first command uses the Get-Acl cmdlet to get the security descriptor of the ITP.txt file. The assignment operator (=) stores the security descriptor in the value of the $ITPACL variable.
The second command uses Set-Acl to change the values in the ACL of TV.txt to the values in $ITPACL.
The value of the –Path parameter is the path to the TV.txt file. The value of the –AclObject parameter is the model ACL, in this case, the ACL of ITP.txt as saved in the $ITPACL variable.
Use the pipeline operator to pass a descriptor:
Get-Acl -Path “C:\PShellTest\ITP.txt” | Set-Acl -Path “C:\PShellTest\TV.txt”
This command is almost the same as the command in the previous example, except that it uses a pipeline operator (|) to send the security descriptor from a Get-Acl command to a Set-Acl command.
The first command uses the Get-Acl cmdlet to get the security descriptor of the ITP.txt file. The pipeline operator (|) passes an object that represents the ITP.txt security descriptor to the Set-Acl cmdlet.
The second command uses Set-Acl to apply the security descriptor of ITP.txt to TV.txt. When the command completes, the ACLs of the ITP.txt and TV.txt files are identical.
Apply a security descriptor to multiple files:
$NewAcl = Get-Acl -Path “C:\PShellTest\ITP.txt”
Get-ChildItem -Path “C:\PShellTest\ITPTV1” -Recurse -Include “*.txt” -Force | Set-Acl -AclObject $NewAcl
These commands apply the security descriptors in the ITP.txt file to all text files in the C:\PShellTest\ITPTV1 directory and all of its subdirectories.
The first command gets the security descriptor of the ITP.txt file in the current directory and uses 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 the C:\PShellTest\ITPTV1 directory. The –Recurse parameter extends the command to all subdirectories of C:\PShellTest\ITPTV1. The –Include parameter limits the files retrieved to those with the .txt file name extension. The –Force parameter gets hidden files, which would otherwise be excluded. (You cannot use C:\PShellTest\ITPTV1\*.txt, because the –Recurse parameter works on directories, not on files.)
The pipeline operator (|) sends the objects representing the retrieved files to the Set-Acl cmdlet, which applies the security descriptor in the –AclObject parameter to all of the files in the pipeline.
NOTE: It is best to use the –WhatIf parameter with all Set-Acl commands that can affect more than one item. In this case, the second command in the pipeline would be Set-Acl -AclObject $NewAcl -WhatIf.
This command lists the files that would be affected by the command. After reviewing the result, you can run the command again without the –WhatIf parameter.
Learn last week’s command: New-PSRoleCapabilityFile.
Need PowerShell training? Check out ITProTV’s PowerShell online IT training courses.