powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Set-Acl



NAME
Set-Acl

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

SYNTAX
Set-Acl [-Path] [-AclObject] [-Exclude ] [-Filter ] [-Include []>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] []


DESCRIPTION
The Set-Acl cmdlet changes the security descriptor of a specified resource, such as a file or a registry key, to ma
tch the values in a security descriptor that you supply.

To use Set-Acl, use the Path parameter to identify the resource whose security descriptor you want to change, and u
se the AclObject parameter to supply a security descriptor that has the values you want to apply. Set-Acl uses the
value of the AclObject parameter as a model and changes the values in the resource's security descriptor to match t
he values in the AclObject parameter.


PARAMETERS
-AclObject
Specifies an ACL with the desired property values. Set-Acl changes the ACL of resource specified by the Path pa
rameter to match the values in the specified security object.

You can save the output of a Get-Acl command in a variable and then use the AclObject parameter to pass the var
iable, or type a Get-Acl command.

Required? true
Position? 2
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

-Exclude
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pa
ttern, such as "*.txt". Wildcards are permitted.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Filter
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path paramet
er. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficie
nt than other parameters, because the provider applies them when retrieving the objects, rather than having Win
dows PowerShell filter the objects after they are retrieved.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Include
Changes only the specified items. The value of this parameter qualifies the Path parameter. Enter a path elemen
t or pattern, such as "*.txt". Wildcards are permitted.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-PassThru []
Returns an object representing the security descriptor. By default, this cmdlet does not generate any output.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Path
Identifies the resource whose security descriptor you want to change. Enter the path to a resource, such as a p
ath to a file or registry key. Wildcards are permitted.

If you pass a security object to Set-Acl (either by using the AclObject parameter or by passing an object from
Get-Acl to Set-Acl), and you omit the Path parameter (name and value), Set-Acl uses the path that is included i
n the security object.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Confirm []
Prompts you for confirmation before executing the command.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-WhatIf []
Describes what would happen if you executed the command without actually executing the command.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-UseTransaction []
Includes the command in the active transaction. This parameter is valid only when a transaction is in progress.
For more information, see about_Transactions.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
System.Security.AccessControl.ObjectSecurity
You can pipe a security descriptor to Set-Acl.


OUTPUTS
None or security object
By default, Set-Acl does not generate any output. However, if you use the -Passthru parameter, it generates a s
ecurity object. The type of the security object depends on the type of the resource.


NOTES


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

When specifying multiple values for a parameter, use commas to separate the values. For example, " me> , ".


-------------------------- EXAMPLE 1 --------------------------

C:\PS>$DogACL = get-acl c:\dog.txt

C:\PS>set-acl -path C:\cat.txt -AclObject $DogACL


Description
-----------
These commands copy the values from the security descriptor of the Dog.txt file to the security descriptor of the C
at.txt file. When the commands complete, the security descriptors of the Dog.txt and 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 operat
or (=) 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 AclObject parameter is the model
ACL, in this case, the ACL of Dog.txt as saved in the $DogACL variable.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>get-acl c:\dog.txt | set-acl -path C:\cat.txt


Description
-----------
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 retrieved in a Get-Acl command to a Set-Acl command.

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

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 --------------------------

C:\PS>$newACL = get-acl file0.txt

C:\PS>get-childitem c:\temp -recurse -include *.txt -force | set-acl -aclobject $newacl


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

The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignme
nt 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:\Temp directo
ry. The Recurse parameter extends the command to all subdirectories of C:\temp. The Include parameter limits the fi
les retrieved to those with the ".txt" file name extension. The Force parameter gets hidden files, which would othe
rwise be excluded. (You cannot use "c:\temp\*.txt", because the Recurse parameter works on directories, not on file
s.)

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

In practice, it is best to use the Whatif parameter with all Set-Acl commands that can affect more than one resourc
e. In this case, the second command in the pipeline would be "set-acl -aclobject $newacl -whatif". This command lis
ts the files that would be affected by the command. After reviewing the result, you can run the command again witho
ut the Whatif parameter.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113389
Get-Acl