Set-acl

Set Access Control List permissions from on a file (or object).

Syntax
      Set-Acl [-path] string[] [-aclObject] ObjectSecurity
                 [-Include String] [-Exclude String]
                    [-filter string] [-passThru] [-whatIf]
                       [-confirm] [-UseTransaction] [CommonParameters]

Key
   -Path path
       Path to the item to be changed {accepts wildcards}

       If a security object is passed to Set-Acl (either via -AclObject 
       or by passing an object from Get-Acl), and -Path is omitted,
       Set-Acl will use the path that is included in the security object.

   -AclObject ObjectSecurity
       An ACL with the desired property values.
       Often the output of a Get-Acl command saved in a variable.

   -Filter string
       A filter in the provider’s format or language. 
       The exact syntax of the filter (wildcard support etc) depends on the provider.
       Filters are more efficient than -include/-exclude, because the provider
       applies the filter when retrieving the objects, rather than having 
       PowerShell filter the objects after they are retrieved.

   -include string
       Include only the specified items from the Path. e.g. "May*"
       This qualifies the -Path parameter and normally includes a wildcard.
        
   -Exclude string
       Omit the specified items from the Path e.g. "*windevcluster*"
       This qualifies the -Path parameter and normally includes a wildcard.

   -PassThru 
       Pass the object created by Set-Acl through the pipeline.

   -WhatIf
       Describe what would happen if you executed the command without
       actually executing the command.

   -Confirm
       Prompt for confirmation before executing the command.

   -UseTransaction
       Include the command in the active transaction.

To apply a new rule to an ACL, requires an AccessRule Object of Type System.Security.AccessControl.FileSystemAccessRule

The ability to delete or rename a folder is decided by a combination of the Delete permissions on the folder in question, plus the Delete subfolders and files permission on the parent folder.

Permissions

The permissions that you can set are similar to the values shown in other tools, but with all spaces removed from the name:

Access Right	Name in PowerShell
Full Control	FullControl
Traverse Folder / Execute File	ExecuteFile
List Folder / Read Data	ReadData
Read Attributes	ReadAttributes
Read Extended Attributes	ReadExtendedAttributes
Create Files / Write Data	CreateFiles
Create Folders / Append Data	AppendData
Write Attributes	WriteAttributes
Write Extended Attributes	WriteExtendedAttributes
Delete Subfolders and Files	DeleteSubdirectoriesAndFiles
Delete	Delete
Read Permissions	ReadPermissions

Basic access rights are a combination of the above:

Basic access right	Rights included	Name of the set in PowerShell
Read	List Folder / Read data	Read
	Read Attributes
	Read Extended Attributes
	Read Permissions
Write	Create Files / Write Data	Write
	Create Folders / Append Data
	Write Attributes
	Write Extended Attributes
Read and Execute	Traverse Folder / Execute File	ReadAndExecute
	List Folder / Read data
	Read Attributes
	Read Extended Attributes
	Read Permissions
Modify	Traverse Folder / Execute File	Modify
	List Folder / Read data
	Read Attributes
	Read Extended Attributes
	Create Files / Write Data
	Create Folders / Append Data
	Write Attributes
	Write Extended Attributes
	Delete
	Read Permissions

To build a set of Access Rules ready to apply:

$rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
   "Username","Right1"[,"Right2",...]
)

A set of Access Rules can then be Added or Removed or Set to replace the current rules:

.AddAccessRule will add a permission, leaving existing ACLs unchanged:
$acl.AddAccessRule($rule)

.RemoveAccessRule will remove them:
$acl.RemoveAccessRule($rule)

.SetAccessRule will overwrite any existing ACLs (other than inherited rights):
$acl.SetAccessRule($rule)

.SetAccessRuleProtection will set Inheritance:
$acl.SetAccessRuleProtection(Block_inheritance_from_parent,Retain_inherited_permissions)
The two options can be supplied as $True or $False

.SetOwner Will set a new owner of the object:
$acl.SetOwner($object)

Inherited folder permissions:

Object inherit    - This folder and files. (no inheritance to subfolders)
Container inherit - This folder and subfolders.
Inherit only      - The ACE does not apply to the current file/directory

By default, an object will inherit permissions from its parent object, either at the time of creation or when it is copied or moved. The only exception to this rule occurs when you move an object to a different folder on the same volume. In this case, the original permissions are retained. In controlled environments this ensures that users cannot change file permissions by just moving items to a different folder. This behaviour can be disabled by setting a system-wide registry key, see Q310316.

Permissions on UNC paths

If you are setting permissions on files and folders hosted on a remote server via a UNC path, you will need admin permission not just to the parent Folder but also to the folder SHARE. If the share permissions only grant read or modify, then you will either need to add an additional share permission for your admin account, or just make the changes directly on the file server.

Examples

Copy the security settings from Dog.txt to Cat.txt

PS C:\> $DogACL = Get-Acl c:\demo\dog.txt
PS C:\> Set-Acl -path C:\demo\cat.txt -AclObject $DogACL

Or the same thing with a pipeline:

PS C:\> Get-Acl c:\demo\dog.txt | Set-Acl -path C:\demo\cat.txt

Apply the same $Dog ACL to all the files in C:\animals\ and all of its subdirectories:

PS C:\> Get-ChildItem c:\animals -recurse -force | Set-Acl -aclobject $DogACL -whatif

Disable inheritance for the folder 'C:\DemoFolder' (If inheritance is left in place the folder will inherit all the permissions of the parent folder.)

PS C:\> $acl = Get-Acl -Path 'C:\DemoFolder'
PS C:\> $acl.SetAccessRuleProtection($true, $false)
PS C:\> $acl | Set-Acl -Path 'C:\DemoFolder'

Add 'Read and Modify' permission to a folder only for the current user:

$acl = Get-Acl -Path 'C:\DemoFolder'
$permission = $env:username, 'Read,Modify', 'ContainerInherit, ObjectInherit', 'None', 'Allow' 
$rule = New-Object -TypeName System.Security.AccessControl.FileSystemAccessRule -ArgumentList $permission
$acl.SetAccessRule($rule)
# Save the access rule to disk:
$acl | Set-Acl -Path 'C:\DemoFolder'

Script that creates a new User folder, and then grants a user account 'Modify' permission to the folder, its subfolders and files:

$user = 'DemoUser'
$newPath = Join-Path "\\server64\Users" -childpath $user
# Create a folder for this user:
New-Item $newPath -type directory

$acl = Get-Acl $newpath

# Set an Access rule for 'Subfolders and files' only
$permission = "windevcluster.com\$user",'Modify', 'DeleteSubdirectoriesAndFiles','ContainerInherit, ObjectInherit', 'InheritOnly', 'Allow'
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule $permission
$acl.SetAccessRule($rule)
     
# Add an Access rule for 'This folder' only.
$permission = "windevcluster.com\$user",'Modify', 'DeleteSubdirectoriesAndFiles','none', 'InheritOnly', 'Allow'
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule $permission
$acl.AddAccessRule($rule)

# Save the access rules to disk:
$acl | Set-Acl $newpath

“If it’s a good idea - go ahead and do it. It’s easier to ask forgiveness than it is to get permission” ~ Grace Murray Hopper

Related PowerShell Cmdlets

Get-Acl - Get permission settings for a file or registry key.
CMD: iCACLS - Change file and folder permissions (ACLs).
CMD: CACLS - Display or modify Access Control Lists (ACLs) for files and folders.
NTFS Security Module - Get/Set ACLs, inheritance, ownership and other permissions missing from Get/Set-Acl [Raimund Andrée MSFT].
Equivalent bash command: chmod - Change access permissions.