mirror of https://github.com/raandree/NTFSSecurity
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
10197 lines
756 KiB
10197 lines
756 KiB
<?xml version="1.0" encoding="utf-8"?>
|
|
<helpItems schema="maml" xmlns="http://msh">
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Add-NTFSAccess</command:name>
|
|
<command:verb>Add</command:verb>
|
|
<command:noun>NTFSAccess</command:noun>
|
|
<maml:description>
|
|
<maml:para>Adds an access control entry (ACE) to a file, a folder, or a security descriptor.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>Adds an access control entry (ACE) to the discretionary access control list (DACL) of a file or a folder. Every account in `-Account` receives the rights in `-AccessRights`, either as an `Allow` or as a `Deny` entry.</maml:para>
|
|
<maml:para>`-AccessRights` accepts the basic rights such as `Read`, `Modify`, and `FullControl` as well as the granular rights such as `CreateFiles` or `WriteAttributes`, and several values can be combined, for example `-AccessRights ReadData, WriteData, Delete`. For the mapping between the values of this module, the rights that Windows displays, and the entries of the advanced security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
<maml:para>The cmdlet has four parameter sets. The `Path` sets read the item from disk and write the changed DACL back immediately, while the `SD` sets change a `Security2.FileSystemSecurity2` object returned by `Get-NTFSSecurityDescriptor` in memory until `Set-NTFSSecurityDescriptor` writes it back. The `Simple` sets take `-AppliesTo`, the `Complex` sets take `-InheritanceFlags` and `-PropagationFlags`; both describe the same ACE flags, and `PathComplex` is the default. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets.</maml:para>
|
|
<maml:para>When `-AccessType`, `-AppliesTo`, `-InheritanceFlags`, and `-PropagationFlags` are omitted, the cmdlet adds an `Allow` ACE that applies to this folder, subfolders, and files, which corresponds to the inheritance flags `ContainerInherit, ObjectInherit` and no propagation flags. An `Allow` ACE always receives the `Synchronize` right in addition to the requested rights, inheritance and propagation flags are ignored on files, and rights for an account that already has an ACE with the same access type and the same flags are merged into that ACE. The cmdlet writes no output unless `-PassThru` is used, and a failure on one item is reported as a non-terminating error while the remaining items are processed.</maml:para>
|
|
<maml:para>`-Path` accepts pipeline input by value and by property name through its alias `FullName`, so output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` can be piped in. `-Account`, `-AccessRights`, `-AccessType`, `-InheritanceFlags`, and `-PropagationFlags` bind by property name as well, which lets you pipe `Security2.FileSystemAccessRule2` objects, or rows imported from a CSV file created from them, directly into the cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Add-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders the ACE is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups the ACE applies to. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">Allow</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Deny</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the ACE in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. Without `-AppliesTo`, the cmdlet uses `-InheritanceFlags` and `-PropagationFlags`, whose defaults describe `ThisFolderSubfoldersAndFiles`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same ACE. The values ending in `OneLevel` limit inheritance to the direct children of the folder.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfolders</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfoldersOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnlyOneLevel</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Add-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, that the ACE is added to. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups the ACE applies to. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">Allow</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Deny</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the ACE in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. Without `-AppliesTo`, the cmdlet uses `-InheritanceFlags` and `-PropagationFlags`, whose defaults describe `ThisFolderSubfoldersAndFiles`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same ACE. The values ending in `OneLevel` limit inheritance to the direct children of the folder.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfolders</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfoldersOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnlyOneLevel</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Add-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders the ACE is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups the ACE applies to. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">Allow</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Deny</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which kind of child objects inherit the ACE. `ContainerInherit` passes the ACE on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the ACE on the item itself. The default is `ContainerInherit, ObjectInherit`. Inheritance flags have no effect on files, where the ACE is always created with `None`.</maml:para>
|
|
<maml:para>For details about the flags, see the .NET documentation of the InheritanceFlags Enum (https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ContainerInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ObjectInherit</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies how the ACE is propagated to child objects. `None` propagates the ACE to all levels that the inheritance flags allow, `InheritOnly` keeps the ACE from applying to the item it is defined on, and `NoPropagateInherit` limits inheritance to the direct children of the folder. The default is `None`, and propagation flags only have an effect in combination with `-InheritanceFlags`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NoPropagateInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">InheritOnly</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Add-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, that the ACE is added to. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups the ACE applies to. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">Allow</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Deny</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which kind of child objects inherit the ACE. `ContainerInherit` passes the ACE on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the ACE on the item itself. The default is `ContainerInherit, ObjectInherit`. Inheritance flags have no effect on files, where the ACE is always created with `None`.</maml:para>
|
|
<maml:para>For details about the flags, see the .NET documentation of the InheritanceFlags Enum (https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ContainerInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ObjectInherit</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies how the ACE is propagated to child objects. `None` propagates the ACE to all levels that the inheritance flags allow, `InheritOnly` keeps the ACE from applying to the item it is defined on, and `NoPropagateInherit` limits inheritance to the direct children of the folder. The default is `None`, and propagation flags only have an effect in combination with `-InheritanceFlags`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NoPropagateInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">InheritOnly</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups the ACE applies to. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the ACE in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. Without `-AppliesTo`, the cmdlet uses `-InheritanceFlags` and `-PropagationFlags`, whose defaults describe `ThisFolderSubfoldersAndFiles`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same ACE. The values ending in `OneLevel` limit inheritance to the direct children of the folder.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which kind of child objects inherit the ACE. `ContainerInherit` passes the ACE on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the ACE on the item itself. The default is `ContainerInherit, ObjectInherit`. Inheritance flags have no effect on files, where the ACE is always created with `None`.</maml:para>
|
|
<maml:para>For details about the flags, see the .NET documentation of the InheritanceFlags Enum (https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders the ACE is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies how the ACE is propagated to child objects. `None` propagates the ACE to all levels that the inheritance flags allow, `InheritOnly` keeps the ACE from applying to the item it is defined on, and `NoPropagateInherit` limits inheritance to the direct children of the folder. The default is `None`, and propagation flags only have an effect in combination with `-InheritanceFlags`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, that the ACE is added to. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more paths of files or folders, piped by value or by the property `FullName`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more security descriptors returned by `Get-NTFSSecurityDescriptor`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The accounts the ACE is created for, bound from a property named `Account`, `IdentityReference`, or `ID`. The output of `Get-NTFSAccess` supplies `Account`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemRights2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The rights of the ACE, piped by the property `AccessRights` or `FileSystemRights`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.AccessControlType</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The type of the ACE, piped by the property `AccessType` or `AccessControlType`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.InheritanceFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The inheritance flags of the ACE, piped by the property `InheritanceFlags` in the `Complex` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.PropagationFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The propagation flags of the ACE, piped by the property `PropagationFlags` in the `Complex` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.ApplyTo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The scope of the ACE, piped by the property `AppliesTo` in the `Simple` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemAccessRule2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru`, the cmdlet writes all access control entries, explicit and inherited, of every item it changed; an item it could not change produces only an error. Before 5.0.0, `-PassThru` also wrote the unchanged entries of such an item. Without `-PassThru` it writes nothing.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>If the ACL of an item cannot be written because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them.</maml:para>
|
|
<maml:para>In the `Path` parameter sets, the cmdlet reads and writes only the DACL of the item and leaves its owner, its group, and its SACL as they are. Before 5.0.0, it also wrote the owner back, which failed with error 1307, "This security ID may not be assigned as the owner of this object", when the account may not assign that owner, such as on some file servers. In an elevated session, it could also store the inherited entries of the item as explicit entries.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>----------- Example 1: Grant read access to a folder -----------</maml:title>
|
|
<dev:code>PS C:\> Add-NTFSAccess -Path C:\Data -Account 'NT AUTHORITY\Authenticated Users' -AccessRights Read</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command grants read access to the built-in group of authenticated users. The ACE applies to the folder, its subfolders, and its files, because `-AppliesTo` defaults to `ThisFolderSubfoldersAndFiles`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--- Example 2: Grant full control and show the resulting ACL ---</maml:title>
|
|
<dev:code>PS C:\> Add-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Admins' -AccessRights FullControl -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command grants full control to a domain group. `-PassThru` writes all access control entries of the folder, explicit and inherited, after the change.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---------- Example 3: Deny a right on a single folder ----------</maml:title>
|
|
<dev:code>PS C:\> Add-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights CreateFiles -AccessType Deny -AppliesTo ThisFolderOnly</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command denies the creation of files in `C:\Data` to the members of a domain group. The ACE is not inherited by subfolders or files, because `-AppliesTo` is set to `ThisFolderOnly`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-- Example 4: Restore explicit permissions from a CSV backup --</maml:title>
|
|
<dev:code>PS C:\> Import-Csv -Path C:\Backup\acl.csv | Add-NTFSAccess</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command restores the access control entries that `Get-NTFSAccess` exported to a CSV file. The columns `FullName`, `Account`, `AccessRights`, `AccessControlType`, `InheritanceFlags`, and `PropagationFlags` bind to the matching parameters, so every row recreates the ACE it was exported from.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Add-NTFSAccess.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Clear-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSEffectiveAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Add-NTFSAudit</command:name>
|
|
<command:verb>Add</command:verb>
|
|
<command:noun>NTFSAudit</command:noun>
|
|
<maml:description>
|
|
<maml:para>Adds an audit entry to a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Add-NTFSAudit` cmdlet adds an audit entry to the system access control list (SACL) of a file or folder. Windows then writes an event to the security log when the audited account uses one of the audited access rights on the item. `-AuditFlags Success` audits successful attempts, `-AuditFlags Failure` audits failed attempts, and the default audits both. For what the individual access rights permit, see Concepts (../Concepts.md).</maml:para>
|
|
<maml:para>In the `PathSimple` and `PathComplex` parameter sets the cmdlet reads the security descriptor of every item in `-Path`, adds the entry, and writes the descriptor back right away. In the `SDSimple` and `SDComplex` parameter sets it adds the entry to an in-memory `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned; that change only reaches the file system when you pass the object to `Set-NTFSSecurityDescriptor`. The simple sets describe the scope of the entry with the single `-AppliesTo` parameter, the complex sets with `-InheritanceFlags` and `-PropagationFlags`.</maml:para>
|
|
<maml:para>`PathComplex` is the default parameter set. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets.</maml:para>
|
|
<maml:para>When you omit them, `-AuditFlags` is `Success, Failure`, `-InheritanceFlags` is `ContainerInherit, ObjectInherit`, `-PropagationFlags` is `None`, and `-AppliesTo` is `ThisFolderSubfoldersAndFiles`, so both the simple and the complex set audit the item, its subfolders, and its files by default. Inheritance applies to folders only: when the item is a file, the cmdlet stores the entry without inheritance and propagation flags.</maml:para>
|
|
<maml:para>`-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it, and the remaining parameters bind by property name. The cmdlet writes no object unless you use `-PassThru`.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Add-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders the audit entry is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the audit entry with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. `ThisFolderOnly` audits the folder itself, `ThisFolderSubfoldersAndFiles` audits the folder and everything below it, `SubfoldersAndFilesOnly` audits the content but not the folder itself, and the values ending in `OneLevel` limit inheritance to the direct children. Without `-AppliesTo`, the cmdlet uses `-InheritanceFlags` and `-PropagationFlags`, whose defaults describe `ThisFolderSubfoldersAndFiles`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfolders</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfoldersOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnlyOneLevel</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Success</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Failure</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Add-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet adds the audit entry to the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the audit entry with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. `ThisFolderOnly` audits the folder itself, `ThisFolderSubfoldersAndFiles` audits the folder and everything below it, `SubfoldersAndFilesOnly` audits the content but not the folder itself, and the values ending in `OneLevel` limit inheritance to the direct children. Without `-AppliesTo`, the cmdlet uses `-InheritanceFlags` and `-PropagationFlags`, whose defaults describe `ThisFolderSubfoldersAndFiles`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfolders</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfoldersOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnlyOneLevel</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Success</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Failure</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Add-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders the audit entry is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Success</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Failure</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which child items inherit the audit entry. `ContainerInherit` passes the entry on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the entry on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. Use `-PropagationFlags` to control whether the entry also applies to the item itself and how far it propagates.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ContainerInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ObjectInherit</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies how the inheritance selected with `-InheritanceFlags` propagates. `None` applies the entry to the item itself and to all inheriting child items, `InheritOnly` applies it to the inheriting child items but not to the item itself, and `NoPropagateInherit` limits inheritance to the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. The parameter has no effect when `-InheritanceFlags` is `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NoPropagateInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">InheritOnly</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Add-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet adds the audit entry to the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Success</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Failure</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which child items inherit the audit entry. `ContainerInherit` passes the entry on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the entry on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. Use `-PropagationFlags` to control whether the entry also applies to the item itself and how far it propagates.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ContainerInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ObjectInherit</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies how the inheritance selected with `-InheritanceFlags` propagates. `None` applies the entry to the item itself and to all inheriting child items, `InheritOnly` applies it to the inheriting child items but not to the item itself, and `NoPropagateInherit` limits inheritance to the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. The parameter has no effect when `-InheritanceFlags` is `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NoPropagateInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">InheritOnly</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the audit entry with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. `ThisFolderOnly` audits the folder itself, `ThisFolderSubfoldersAndFiles` audits the folder and everything below it, `SubfoldersAndFilesOnly` audits the content but not the folder itself, and the values ending in `OneLevel` limit inheritance to the direct children. Without `-AppliesTo`, the cmdlet uses `-InheritanceFlags` and `-PropagationFlags`, whose defaults describe `ThisFolderSubfoldersAndFiles`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which child items inherit the audit entry. `ContainerInherit` passes the entry on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the entry on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. Use `-PropagationFlags` to control whether the entry also applies to the item itself and how far it propagates.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders the audit entry is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies how the inheritance selected with `-InheritanceFlags` propagates. `None` applies the entry to the item itself and to all inheriting child items, `InheritOnly` applies it to the inheriting child items but not to the item itself, and `NoPropagateInherit` limits inheritance to the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. The parameter has no effect when `-InheritanceFlags` is `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet adds the audit entry to the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The accounts passed to `-Account` are converted to this type from an account name or a SID string. The parameter binds by property name through its own name and its aliases `IdentityReference` and `ID`, so the `Account` property of the entries this module returns supplies the value.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemRights2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-AccessRights` is converted to this type. The parameter binds by property name, so an object with an `AccessRights` or `FileSystemRights` property supplies the value.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.AuditFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-AuditFlags` is converted to this type and binds by property name.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.InheritanceFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-InheritanceFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.PropagationFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-PropagationFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.ApplyTo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-AppliesTo` is converted to this type and binds by property name in the `PathSimple` and `SDSimple` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemAuditRule2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the cmdlet writes all audit entries of the item or the security descriptor, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects. Before 5.0.0, the `SecurityDescriptor` sets wrote the access entries of the descriptor instead. An item whose audit entries could not be changed produces only an error; before 5.0.0, `-PassThru` also wrote its unchanged entries.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Writing the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it, the cmdlet writes a non-terminating `AddAceError` whose message states that a required privilege is not held by the client, and the item is left unchanged.</maml:para>
|
|
<maml:para>A security descriptor that was read without the Security privilege doesn't contain the audit entries. With such a descriptor, the cmdlet writes a `ReadSecurityError` and changes nothing, like `Get-NTFSAudit`; before 5.0.0, it added the entry to the missing audit entries in memory and wrote no error.</maml:para>
|
|
<maml:para>If the security descriptor cannot be read or written because access is denied, the cmdlet takes ownership of the item, repeats the operation, and restores the previous owner. If the second attempt fails as well, the cmdlet restores the previous owner and writes an error. Before 5.0.0, the account that ran the cmdlet stayed the owner of the item in that case.</maml:para>
|
|
<maml:para>In the `Path` parameter sets, the cmdlet reads and writes only the SACL of the item and leaves its owner, its group, and its DACL as they are. Before 5.0.0, it also wrote the owner and the DACL back, which failed with error 1307, "This security ID may not be assigned as the owner of this object", when the account may not assign that owner, such as on some file servers. In an elevated session, it could also store the inherited access entries of the item as explicit entries.</maml:para>
|
|
<maml:para>`-Path` or `-SecurityDescriptor`, `-Account`, and `-AccessRights` are positional parameters at positions 1, 2, and 3, like in `Remove-NTFSAudit`. Before 5.0.0, `-Account` and `-AccessRights` were both declared at position 2, so a command that passed them by position failed.</maml:para>
|
|
<maml:para>An audit entry alone does not create events. Windows writes the events to the security log only while the "Audit object access" policy, or the corresponding "Audit File System" advanced audit policy, is enabled for success, failure, or both. That policy is a Windows setting and is not managed by this module.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>---------- Example 1: Audit failed access to a folder ----------</maml:title>
|
|
<dev:code>PS C:\> Add-NTFSAudit -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights FullControl -AuditFlags Failure</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command audits every failed attempt of the group `CONTOSO\Domain Users` to use one of the rights contained in `FullControl` on `C:\Data`. Because `-AppliesTo` and the inheritance parameters are omitted, the entry applies to the folder, its subfolders, and its files.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----- Example 2: Audit successful deletions in one folder -----</maml:title>
|
|
<dev:code>PS C:\> Add-NTFSAudit -Path C:\Data -Account Everyone -AccessRights Delete, DeleteSubdirectoriesAndFiles -AuditFlags Success -AppliesTo ThisFolderOnly</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command audits successful deletions performed by any account in the folder `C:\Data`. `-AppliesTo ThisFolderOnly` keeps the entry from being inherited by subfolders and files.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 3: Audit several folders from the pipeline ------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Directory | Add-NTFSAudit -Account 'BUILTIN\Users' -AccessRights ReadData -AuditFlags Success -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command adds the same audit entry to every subfolder of `C:\Data` and returns all audit entries of each folder afterwards, including the inherited ones, so that you can check the result.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---- Example 4: Add an audit entry to a security descriptor ----</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Add-NTFSAudit -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AuditFlags Success, Failure -AppliesTo SubfoldersAndFilesOnly
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command adds an audit entry for `CONTOSO\JohnDoe` to the in-memory security descriptor of `C:\Data` and then writes the descriptor back. The entry applies to the subfolders and files of `C:\Data` but not to the folder itself.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Add-NTFSAudit.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Clear-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSOrphanedAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Clear-NTFSAccess</command:name>
|
|
<command:verb>Clear</command:verb>
|
|
<command:noun>NTFSAccess</command:noun>
|
|
<maml:description>
|
|
<maml:para>Removes all explicit access control entries from a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>Removes every access control entry (ACE) that is defined on a file or a folder itself. Inherited entries are not touched and continue to apply, so an item whose permissions come from its parent folder keeps them.</maml:para>
|
|
<maml:para>`-DisableInheritance` additionally protects the item from its parents and discards the inherited entries instead of copying them into the item. An item that is cleared with `-DisableInheritance` therefore ends up with an empty DACL, which denies access to everyone; only its owner can still change the permissions. Grant the required rights with `Add-NTFSAccess` right after clearing, or re-enable inheritance with `Enable-NTFSAccessInheritance`.</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet reads the item from disk and writes the changed DACL back immediately; relative paths are resolved against the current location. In the `SD` parameter set it changes a `Security2.FileSystemSecurity2` object returned by `Get-NTFSSecurityDescriptor` in memory until `Set-NTFSSecurityDescriptor` writes it back. The cmdlet writes no output, and a failure on one item is reported as a non-terminating error while the remaining items are processed.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Clear-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose explicit access control entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>DisableInheritance</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that inheritance is disabled after the explicit entries are removed, and that the inherited entries are discarded rather than copied into the item. The item is left with an empty DACL, which denies access to everyone; only its owner can still change the permissions. Without this switch the inherited entries remain in effect.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Clear-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose explicit access control entries are removed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>DisableInheritance</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that inheritance is disabled after the explicit entries are removed, and that the inherited entries are discarded rather than copied into the item. The item is left with an empty DACL, which denies access to everyone; only its owner can still change the permissions. Without this switch the inherited entries remain in effect.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>DisableInheritance</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that inheritance is disabled after the explicit entries are removed, and that the inherited entries are discarded rather than copied into the item. The item is left with an empty DACL, which denies access to everyone; only its owner can still change the permissions. Without this switch the inherited entries remain in effect.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose explicit access control entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose explicit access control entries are removed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more paths of files or folders, piped by value or by the property `FullName`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more security descriptors returned by `Get-NTFSSecurityDescriptor`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>System.Object</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet writes nothing. Use `Get-NTFSAccess` to inspect the result.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>If the ACL of an item cannot be written because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them.</maml:para>
|
|
<maml:para>In the `Path` parameter set, the cmdlet reads and writes only the DACL of the item and leaves its owner, its group, and its SACL as they are. Before 5.0.0, it also wrote the owner back, which failed with error 1307, "This security ID may not be assigned as the owner of this object", when the account may not assign that owner, such as on some file servers.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>---- Example 1: Remove the explicit permissions of a folder ----</maml:title>
|
|
<dev:code>PS C:\> Clear-NTFSAccess -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes all access control entries that are defined on `C:\Data` itself. The entries that the folder inherits from its parent remain in effect.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--- Example 2: Remove all permissions and break inheritance ---</maml:title>
|
|
<dev:code>PS C:\> Clear-NTFSAccess -Path C:\Data -DisableInheritance</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes the explicit entries of `C:\Data` and disables inheritance without copying the inherited entries. The folder is left with an empty DACL and is inaccessible until new permissions are granted.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----- Example 3: Reset the permissions of several folders -----</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Clear-NTFSAccess</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes the explicit entries of every subfolder of `C:\Data` so that all of them rely on the permissions inherited from `C:\Data`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------- Example 4: Rebuild an ACL in memory -------------</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Clear-NTFSAccess -SecurityDescriptor $sd -DisableInheritance
|
|
PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'BUILTIN\Administrators' -AccessRights FullControl -AppliesTo ThisFolderSubfoldersAndFiles
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>These commands replace the complete ACL of `C:\Data` in one write. The security descriptor is changed in memory, and the file system is only touched by `Set-NTFSSecurityDescriptor`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Clear-NTFSAccess.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Clear-NTFSAudit</command:name>
|
|
<command:verb>Clear</command:verb>
|
|
<command:noun>NTFSAudit</command:noun>
|
|
<maml:description>
|
|
<maml:para>Removes all explicit audit entries from a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Clear-NTFSAudit` cmdlet removes every audit entry that is set on a file or folder itself from its system access control list (SACL). Entries that the item inherits from a parent folder are left alone, because they are stored on that parent. Add `-DisableInheritance` to protect the item from its parent and to drop the inherited entries as well, which leaves the item without any auditing.</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet reads the security descriptor of every item in `-Path`, removes the entries, and writes the descriptor back right away. Relative paths are resolved against the current location, and the parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. In the `SD` parameter set the cmdlet changes an in-memory `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned, and the change reaches the file system only when you pass the object to `Set-NTFSSecurityDescriptor`.</maml:para>
|
|
<maml:para>To remove a single audit entry instead of all of them, use `Remove-NTFSAudit`. The cmdlet writes no object; use `Get-NTFSAudit` to check the result.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Clear-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders whose audit entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>DisableInheritance</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the item no longer inherits audit entries from its parent folder. The inherited entries are discarded rather than copied to the item, so the item is left with no audit entries at all. Without this switch the item keeps inheriting audit entries from its parent.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Clear-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the explicit audit entries from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>DisableInheritance</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the item no longer inherits audit entries from its parent folder. The inherited entries are discarded rather than copied to the item, so the item is left with no audit entries at all. Without this switch the item keeps inheriting audit entries from its parent.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>DisableInheritance</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the item no longer inherits audit entries from its parent folder. The inherited entries are discarded rather than copied to the item, so the item is left with no audit entries at all. Without this switch the item keeps inheriting audit entries from its parent.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders whose audit entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the explicit audit entries from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>System.Object</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>This cmdlet writes nothing to the pipeline. Use `Get-NTFSAudit` to check which audit entries an item has after the operation.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Reading and writing the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it, the cmdlet writes a non-terminating `ClearAclError` whose message states that a required privilege is not held by the client, and the item is left unchanged. Before 5.0.0, the cmdlet read the security descriptor without its SACL in that situation, found no audit entries to remove, and finished without an error although nothing was changed.</maml:para>
|
|
<maml:para>In the `Path` parameter set, the cmdlet reads and writes only the SACL of the item and leaves its owner, its group, and its DACL as they are; it writes nothing for an item without a SACL. Before 5.0.0, it also wrote the owner back, which failed with error 1307, "This security ID may not be assigned as the owner of this object", when the account may not assign that owner, such as on some file servers.</maml:para>
|
|
<maml:para>A security descriptor that was read without the Security privilege doesn't contain the audit entries. With such a descriptor, the cmdlet writes a `ReadSecurityError` and changes nothing, like `Get-NTFSAudit`; before 5.0.0, it wrote no error.</maml:para>
|
|
<maml:para>If the security descriptor cannot be read or written because access is denied, the cmdlet takes ownership of the item, repeats the operation, and restores the previous owner. If the second attempt fails as well, the cmdlet restores the previous owner and writes an error. Before 5.0.0, the account that ran the cmdlet stayed the owner of the item in that case.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>--- Example 1: Remove the explicit audit entries of a folder ---</maml:title>
|
|
<dev:code>PS C:\> Clear-NTFSAudit -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes every audit entry that is set on `C:\Data` itself. The entries that the folder inherits from its parent stay in place.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--------- Example 2: Remove all auditing from a folder ---------</maml:title>
|
|
<dev:code>PS C:\> Clear-NTFSAudit -Path C:\Data -DisableInheritance</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes the explicit audit entries of `C:\Data` and then stops the folder from inheriting audit entries, discarding the inherited entries instead of copying them to the folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----- Example 3: Clear the audit entries of a folder tree -----</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Clear-NTFSAudit</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command pipes every item below `C:\Data` into `Clear-NTFSAudit` and removes the audit entries that are set on those items themselves.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>- Example 4: Clear the audit entries of a security descriptor -</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Clear-NTFSAudit -SecurityDescriptor $sd
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes the explicit audit entries from the in-memory security descriptor of `C:\Data` and then writes the descriptor back to the file system.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Clear-NTFSAudit.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Clear-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Copy-Item2</command:name>
|
|
<command:verb>Copy</command:verb>
|
|
<command:noun>Item2</command:noun>
|
|
<maml:description>
|
|
<maml:para>Copies a file to another location, including paths longer than 260 characters.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Copy-Item2` cmdlet copies the items in `-Path` to the location in `-Destination`. It is the long-path counterpart of the built-in `Copy-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), so source and destination may be longer than the 260-character `MAX_PATH` limit.</maml:para>
|
|
<maml:para>How `-Destination` is interpreted depends on what is already there. If the value names an existing folder, the cmdlet keeps the name of the source item and copies it into that folder. In every other case the value is the full path of the new item, which lets you copy and rename in one step. `-Destination` is resolved against the current location once, when the cmdlet starts.</maml:para>
|
|
<maml:para>Without `-Force`, the cmdlet checks whether a file or folder already exists at the destination and writes a `DestinationFileAlreadyExists` error instead of overwriting it or merging into it. With `-WhatIf`, it names an existing destination in a verbose message instead; before 5.0.0, it wrote the error also with `-WhatIf`. With `-Force`, an existing file is replaced, and a folder is copied into an existing folder of the same name, replacing the files that exist in both. The folder that is to contain the new item must exist; otherwise the cmdlet writes an error that names that folder. Relative paths and the `.` and `..` notations in `-Path` are resolved against the current location, and wildcard characters are not supported.</maml:para>
|
|
<maml:para>The cmdlet supports `-WhatIf` and `-Confirm`, and it writes nothing to the pipeline unless you specify `-PassThru $true`.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Copy-Item2</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more items to copy. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none">
|
|
<maml:name>Destination</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the target of the copy operation. If the value names an existing folder, the cmdlet copies the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
|
|
<maml:name>Confirm</maml:name>
|
|
<maml:description>
|
|
<maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Force</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet overwrites an existing destination file, and copies a folder into an existing folder of the same name. Without `-Force`, an existing file or folder at the destination causes the error `DestinationFileAlreadyExists` and the item is not copied.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the cmdlet returns an object for each item that it copied. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. After a successful file copy, the returned object describes the file at the destination path.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
|
|
<maml:name>WhatIf</maml:name>
|
|
<maml:description>
|
|
<maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
|
|
<maml:name>Confirm</maml:name>
|
|
<maml:description>
|
|
<maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none">
|
|
<maml:name>Destination</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the target of the copy operation. If the value names an existing folder, the cmdlet copies the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Force</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet overwrites an existing destination file, and copies a folder into an existing folder of the same name. Without `-Force`, an existing file or folder at the destination causes the error `DestinationFileAlreadyExists` and the item is not copied.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the cmdlet returns an object for each item that it copied. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. After a successful file copy, the returned object describes the file at the destination path.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more items to copy. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
|
|
<maml:name>WhatIf</maml:name>
|
|
<maml:description>
|
|
<maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe an object that has a `Destination` property to supply the target of the copy operation.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.FileInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>By default this cmdlet returns nothing. With `-PassThru $true` it returns a file object for each file that it copied, pointing at the copy.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.DirectoryInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru $true` the cmdlet returns a folder object for each folder that it copied, pointing at the copy.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>`Copy-Item2` copies through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it handles source and destination paths that exceed the 260-character `MAX_PATH` limit of the built-in `Copy-Item` cmdlet.</maml:para>
|
|
<maml:para>Before 5.0.0, `-PassThru` also wrote the item when `-WhatIf` or a declined confirmation skipped the operation.</maml:para>
|
|
<maml:para>Before 5.0.0, copying a folder that contained files failed with a `CopyError` that reported a `DirectoryNotFoundException` for the first file in the folder.</maml:para>
|
|
<maml:para>If a path in `-Path` does not exist, a file or folder exists at the destination and `-Force` is missing, or the folder that is to contain the copy does not exist, the cmdlet writes a non-terminating error and continues with the next path. Before 5.0.0, it skipped the remaining paths that were passed in the same call. Before 5.0.0, it also didn't detect an existing destination folder, so that the copy failed in the middle with a `CopyError` after it had copied a part of the folder; it reported a missing destination folder as a `DirectoryNotFoundException` that named the source item; and, in the prereleases of 5.0.0, it created the missing folders of the destination for a folder.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------------- Example 1: Copy a file into a folder -------------</maml:title>
|
|
<dev:code>PS C:\> Copy-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Copies `report.docx` into the existing folder `C:\Data\Archive`, where it keeps its name. The command fails if `C:\Data\Archive\report.docx` already exists.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-------- Example 2: Copy and rename a file in one step --------</maml:title>
|
|
<dev:code>PS C:\> Copy-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive\report-2026.docx -Force</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Copies the file under a new name and, because of `-Force`, replaces an existing `report-2026.docx`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---------- Example 3: Copy files with very long paths ----------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data\Projects -Recurse -File -Filter '*.log' | Copy-Item2 -Destination C:\Data\Logs -Force</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Collects every log file below `C:\Data\Projects`, no matter how long its path is, and copies them all into `C:\Data\Logs`. Because each file keeps only its name, the files from the different source folders end up side by side in the target folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------- Example 4: Preview a copy operation -------------</maml:title>
|
|
<dev:code>PS C:\> Copy-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive -WhatIf</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Shows which operation the cmdlet would perform without copying anything.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Copy-Item2.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Move-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Test-Path2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Disable-NTFSAccessInheritance</command:name>
|
|
<command:verb>Disable</command:verb>
|
|
<command:noun>NTFSAccessInheritance</command:noun>
|
|
<maml:description>
|
|
<maml:para>Blocks the inheritance of access rules on a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Disable-NTFSAccessInheritance` cmdlet protects the discretionary access control list (DACL) of a file or folder, so that the access rules of the parent folder no longer apply to the item. From then on, only the access rules stored in the item's own DACL grant or deny access to it.</maml:para>
|
|
<maml:para>By default, the rules that the item currently inherits are copied into its DACL before inheritance is blocked. The effective permissions therefore stay the same, and the copies become explicit rules that you can change or remove individually. The `-RemoveInheritedAccessRules` switch discards the inherited rules instead of copying them. If the item has no explicit rules of its own, that leaves an empty DACL, which denies access to everyone except the owner, so check the item with `Get-NTFSAccess` before you use the switch.</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet reads the access section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`.</maml:para>
|
|
<maml:para>`-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. Relative paths are resolved against the current location. The cmdlet affects only the access rules; use `Disable-NTFSAuditInheritance` for the audit rules.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Disable-NTFSAccessInheritance</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose access inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveInheritedAccessRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access rules the item currently inherits are discarded. By default, when the switch is omitted, those rules are copied into the item's own DACL as explicit rules and the effective permissions stay the same. With the switch, the item keeps only the access rules that were already explicit on it, which can be none at all.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Disable-NTFSAccessInheritance</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveInheritedAccessRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access rules the item currently inherits are discarded. By default, when the switch is omitted, those rules are copied into the item's own DACL as explicit rules and the effective permissions stay the same. With the switch, the item keeps only the access rules that were already explicit on it, which can be none at all.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose access inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveInheritedAccessRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access rules the item currently inherits are discarded. By default, when the switch is omitted, those rules are copied into the item's own DACL as explicit rules and the effective permissions stay the same. With the switch, the item keeps only the access rules that were already explicit on it, which can be none at all.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemInheritanceInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Blocking access inheritance requires permission to change the DACL of the item, which the owner of an item always has. If the descriptor cannot be opened, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item.</maml:para>
|
|
<maml:para>A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet enabled the privileges even when `EnablePrivileges` was `$false`, and left them enabled.</maml:para>
|
|
<maml:para>Before 5.0.0, `-PassThru` returned the unchanged state of an item also when the change failed, and stopped the command when the item could not be read.</maml:para>
|
|
<maml:para>In the `Path` parameter set, the cmdlet writes only the DACL of the item and leaves its owner, its group, and its SACL as they are. Before 5.0.0, it could also write the owner back, which failed with error 1307, "This security ID may not be assigned as the owner of this object", when the account may not assign that owner, such as on some file servers.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title> Example 1: Block inheritance and keep the current permissions </maml:title>
|
|
<dev:code>PS C:\> Disable-NTFSAccessInheritance -Path C:\Data\Projects</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command protects the DACL of `C:\Data\Projects` and copies the access rules that the folder inherited from `C:\Data` into its own DACL. The effective permissions do not change, but later permission changes on `C:\Data` no longer reach the folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>- Example 2: Block inheritance and discard the inherited rules -</maml:title>
|
|
<dev:code>PS C:\> Disable-NTFSAccessInheritance -Path C:\Data\Projects -RemoveInheritedAccessRules -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command protects the DACL and removes the inherited access rules instead of copying them, which leaves only the rules that were already explicit on the folder. `-PassThru` returns the resulting state, in which `AccessInheritanceEnabled` is `$false`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------- Example 3: Block inheritance on every subfolder -------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Directory | Disable-NTFSAccessInheritance -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command pipes every subfolder of `C:\Data` to the cmdlet, which binds the `FullName` property of each item to `-Path`. Each folder keeps its current permissions as explicit rules, and `-PassThru` reports the new state of each of them.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 4: Change a security descriptor in memory ------</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects
|
|
PS C:\> Disable-NTFSAccessInheritance -SecurityDescriptor $sd
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first two commands read the security descriptor and protect its DACL in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Disable-NTFSAccessInheritance.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Disable-NTFSAuditInheritance</command:name>
|
|
<command:verb>Disable</command:verb>
|
|
<command:noun>NTFSAuditInheritance</command:noun>
|
|
<maml:description>
|
|
<maml:para>Blocks the inheritance of audit rules on a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Disable-NTFSAuditInheritance` cmdlet protects the system access control list (SACL) of a file or folder, so that the audit rules of the parent folder no longer apply to the item. From then on, only the audit rules stored in the item's own SACL decide which access attempts are written to the security event log.</maml:para>
|
|
<maml:para>By default, the audit rules that the item currently inherits are copied into its SACL before inheritance is blocked, so the auditing behavior stays the same. The `-RemoveInheritedAuditRules` switch discards the inherited audit rules instead of copying them, which leaves only the audit rules that were already explicit on the item. Before 5.0.0, the switch was named `-RemoveInheritedAccessRules`; that name still works as an alias.</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet reads the audit section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`.</maml:para>
|
|
<maml:para>Reading and writing the audit section requires the Security privilege, so run this cmdlet in an elevated session. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet affects only the audit rules; use `Disable-NTFSAccessInheritance` for the access rules.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Disable-NTFSAuditInheritance</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose audit inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="RemoveInheritedAccessRules">
|
|
<maml:name>RemoveInheritedAuditRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the audit rules the item currently inherits are discarded. By default, when the switch is omitted, the inherited audit rules are copied into the item's own SACL as explicit rules and auditing continues unchanged. Before 5.0.0, the switch was named `-RemoveInheritedAccessRules`, which remains an alias.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Disable-NTFSAuditInheritance</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="RemoveInheritedAccessRules">
|
|
<maml:name>RemoveInheritedAuditRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the audit rules the item currently inherits are discarded. By default, when the switch is omitted, the inherited audit rules are copied into the item's own SACL as explicit rules and auditing continues unchanged. Before 5.0.0, the switch was named `-RemoveInheritedAccessRules`, which remains an alias.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose audit inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="RemoveInheritedAccessRules">
|
|
<maml:name>RemoveInheritedAuditRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the audit rules the item currently inherits are discarded. By default, when the switch is omitted, the inherited audit rules are copied into the item's own SACL as explicit rules and auditing continues unchanged. Before 5.0.0, the switch was named `-RemoveInheritedAccessRules`, which remains an alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemInheritanceInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>The audit section of a security descriptor can only be read and written with the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, the cmdlet writes a non-terminating error that reports Windows error 1314, "A required privilege is not held by the client", and the audit rules of the item stay unchanged.</maml:para>
|
|
<maml:para>If the descriptor cannot be opened because the account has no permission to the item, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; a missing Security privilege is not an access problem and is not repaired by it.</maml:para>
|
|
<maml:para>A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet enabled the privileges even when `EnablePrivileges` was `$false`, and left them enabled.</maml:para>
|
|
<maml:para>Before 5.0.0, `-PassThru` returned the unchanged state of an item also when the change failed, and stopped the command when the item could not be read.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>Example 1: Block audit inheritance and keep the current auditing</maml:title>
|
|
<dev:code>PS C:\> Disable-NTFSAuditInheritance -Path C:\Data\Projects</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command protects the SACL of `C:\Data\Projects` and copies the audit rules that the folder inherited from `C:\Data` into its own SACL. Auditing continues to work the same way, but later changes to the audit rules of `C:\Data` no longer reach the folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 2: Block audit inheritance and discard the inherited rules</maml:title>
|
|
<dev:code>PS C:\> Disable-NTFSAuditInheritance -Path C:\Data\Projects -RemoveInheritedAuditRules -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command protects the SACL and removes the inherited audit rules instead of copying them, so the folder is audited only by the rules that were already explicit on it. `-PassThru` returns the resulting state, in which `AuditInheritanceEnabled` is `$false`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---- Example 3: Block audit inheritance on every subfolder ----</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Directory | Disable-NTFSAuditInheritance</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command pipes every subfolder of `C:\Data` to the cmdlet, which binds the `FullName` property of each item to `-Path`. Each folder keeps its current audit rules as explicit rules.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 4: Change a security descriptor in memory ------</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects
|
|
PS C:\> Disable-NTFSAuditInheritance -SecurityDescriptor $sd
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first two commands read the security descriptor and protect its SACL in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Disable-NTFSAuditInheritance.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Disable-Privileges</command:name>
|
|
<command:verb>Disable</command:verb>
|
|
<command:noun>Privileges</command:noun>
|
|
<maml:description>
|
|
<maml:para>Disables the file system privileges in the access token of the current PowerShell process.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Disable-Privileges` cmdlet disables the Take Ownership, Restore, Backup, and Security privileges in the access token of the current PowerShell process. It is the counterpart of `Enable-Privileges`, which leaves those privileges enabled for the rest of the session.</maml:para>
|
|
<maml:para>Before it changes anything, the cmdlet checks whether at least one of the Take Ownership, Restore, and Backup privileges is currently enabled. If none of them is, it writes a non-terminating error that reports that the privileges are not enabled and does nothing. This is what happens in a session that never enabled the privileges or that does not hold them at all. A privilege that cannot be disabled produces a warning, and the cmdlet continues with the remaining privileges.</maml:para>
|
|
<maml:para>The change affects nothing but the access token of the PowerShell process that runs the cmdlet. Disabling a privilege does not remove it from the account; it only takes it out of use until something enables it again, which the file system cmdlets of the module do on their own while they run.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Disable-Privileges</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns the privileges of the current process after disabling them. Without this parameter, the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns the privileges of the current process after disabling them. Without this parameter, the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>None</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>This cmdlet does not accept pipeline input.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>ProcessPrivileges.PrivilegeAndAttributes</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru`, the cmdlet writes one `ProcessPrivileges.PrivilegeAndAttributes` object per privilege of the current process, each with a `Privilege`, a `PrivilegeAttributes`, and a `PrivilegeState` property. Without `-PassThru`, the cmdlet writes nothing. Before 5.0.0, it wrote the privileges as one collection.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), the file system cmdlets of the module try to enable the Backup, Restore, Take Ownership, and Security privileges while they run and disable the privileges they enabled when they finish. You therefore need `Disable-Privileges` only after an explicit `Enable-Privileges`. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group.</maml:para>
|
|
<maml:para>Before 5.0.0, when `EnablePrivileges` was `$false`, the cmdlet wrote warnings that it could not disable the privileges and left them enabled.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>--- Example 1: Disable the privileges in the current session ---</maml:title>
|
|
<dev:code>PS C:\> Disable-Privileges</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command disables the Take Ownership, Restore, Backup, and Security privileges in the current PowerShell process.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--- Example 2: Disable the privileges and return the result ---</maml:title>
|
|
<dev:code>PS C:\> Disable-Privileges -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command disables the privileges and returns all privileges of the current process, so you can confirm their new state right away.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 3: Enable the privileges for a task and turn them off afterwards</maml:title>
|
|
<dev:code>PS C:\> Enable-Privileges
|
|
PS C:\> Set-NTFSOwner -Path C:\Data -Account 'BUILTIN\Administrators'
|
|
PS C:\> Disable-Privileges</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The privileges stay enabled while the owner of the folder is changed and are turned off again by the last command, which returns the session to its normal rights.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 4: Check the state of the privileges after disabling them</maml:title>
|
|
<dev:code>PS C:\> Disable-Privileges
|
|
PS C:\> Get-Privileges | Where-Object { $_.Privilege -in 'Backup', 'Restore', 'TakeOwnership', 'Security' }</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The second command lists the four file system privileges with their current state, which shows that they are no longer enabled.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Disable-Privileges.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-Privileges</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Privileges</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSOwner</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Enable-NTFSAccessInheritance</command:name>
|
|
<command:verb>Enable</command:verb>
|
|
<command:noun>NTFSAccessInheritance</command:noun>
|
|
<maml:description>
|
|
<maml:para>Restores the inheritance of access rules on a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Enable-NTFSAccessInheritance` cmdlet removes the protection from the discretionary access control list (DACL) of a file or folder, so that the item inherits access rules from its parent folder again.</maml:para>
|
|
<maml:para>By default, the access rules that are stored directly on the item are kept, and the inherited rules are added to them. An item that was processed by `Disable-NTFSAccessInheritance` therefore ends up with the inherited rules twice: once as the explicit copies that were created when inheritance was blocked, and once as true inherited rules. The `-RemoveExplicitAccessRules` switch deletes every access rule that is stored directly on the item, which leaves only the inherited rules and restores the permission model of the parent folder.</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet reads the access section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`.</maml:para>
|
|
<maml:para>`-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. Relative paths are resolved against the current location. The cmdlet affects only the access rules; use `Enable-NTFSAuditInheritance` for the audit rules.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Enable-NTFSAccessInheritance</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose access inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveExplicitAccessRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that every access rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited rules only. By default, when the switch is omitted, the explicit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAccessInheritance` copied earlier.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Enable-NTFSAccessInheritance</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveExplicitAccessRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that every access rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited rules only. By default, when the switch is omitted, the explicit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAccessInheritance` copied earlier.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose access inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveExplicitAccessRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that every access rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited rules only. By default, when the switch is omitted, the explicit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAccessInheritance` copied earlier.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemInheritanceInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Restoring access inheritance requires permission to change the DACL of the item, which the owner of an item always has. If the descriptor cannot be opened, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item.</maml:para>
|
|
<maml:para>A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet enabled the privileges even when `EnablePrivileges` was `$false`, and left them enabled.</maml:para>
|
|
<maml:para>Before 5.0.0, `-PassThru` returned the unchanged state of an item also when the change failed, and stopped the command when the item could not be read.</maml:para>
|
|
<maml:para>In the `Path` parameter set, the cmdlet writes only the DACL of the item and leaves its owner, its group, and its SACL as they are. Before 5.0.0, it could also write the owner back, which failed with error 1307, "This security ID may not be assigned as the owner of this object", when the account may not assign that owner, such as on some file servers.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>-- Example 1: Restore inheritance and keep the explicit rules --</maml:title>
|
|
<dev:code>PS C:\> Enable-NTFSAccessInheritance -Path C:\Data\Projects</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command lets `C:\Data\Projects` inherit the access rules of `C:\Data` again. The rules that are stored directly on the folder stay in place and are added to the inherited ones.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-- Example 2: Restore inheritance and drop the explicit rules --</maml:title>
|
|
<dev:code>PS C:\> Enable-NTFSAccessInheritance -Path C:\Data\Projects -RemoveExplicitAccessRules -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes every access rule that is stored directly on the folder and lets it inherit from `C:\Data` again, so the folder ends up with exactly the permissions of its parent. `-PassThru` returns the resulting state, in which `AccessInheritanceEnabled` is `$true`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------ Example 3: Repair a whole folder tree ------------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSInheritance | Where-Object { -not $_.AccessInheritanceEnabled } | Enable-NTFSAccessInheritance -RemoveExplicitAccessRules</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command finds every item below `C:\Data` whose access inheritance is blocked and restores it. `Get-NTFSInheritance` writes objects with a `FullName` property, which binds to `-Path`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 4: Change a security descriptor in memory ------</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects
|
|
PS C:\> Enable-NTFSAccessInheritance -SecurityDescriptor $sd -RemoveExplicitAccessRules
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first two commands read the security descriptor and restore inheritance in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Enable-NTFSAccessInheritance.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Enable-NTFSAuditInheritance</command:name>
|
|
<command:verb>Enable</command:verb>
|
|
<command:noun>NTFSAuditInheritance</command:noun>
|
|
<maml:description>
|
|
<maml:para>Restores the inheritance of audit rules on a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Enable-NTFSAuditInheritance` cmdlet removes the protection from the system access control list (SACL) of a file or folder, so that the item inherits audit rules from its parent folder again.</maml:para>
|
|
<maml:para>By default, the audit rules that are stored directly on the item are kept, and the inherited rules are added to them. An item that was processed by `Disable-NTFSAuditInheritance` therefore ends up with the inherited audit rules twice: once as the explicit copies that were created when inheritance was blocked, and once as true inherited rules. The `-RemoveExplicitAuditRules` switch deletes every audit rule that is stored directly on the item, which leaves only the inherited ones. Before 5.0.0, the switch was named `-RemoveExplicitAccessRules`; that name still works as an alias.</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet reads the audit section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`.</maml:para>
|
|
<maml:para>Reading and writing the audit section requires the Security privilege, so run this cmdlet in an elevated session. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet affects only the audit rules; use `Enable-NTFSAccessInheritance` for the access rules.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Enable-NTFSAuditInheritance</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose audit inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="RemoveExplicitAccessRules">
|
|
<maml:name>RemoveExplicitAuditRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that every audit rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited audit rules only. By default, when the switch is omitted, the explicit audit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAuditInheritance` copied earlier. Before 5.0.0, the switch was named `-RemoveExplicitAccessRules`, which remains an alias.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Enable-NTFSAuditInheritance</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="RemoveExplicitAccessRules">
|
|
<maml:name>RemoveExplicitAuditRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that every audit rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited audit rules only. By default, when the switch is omitted, the explicit audit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAuditInheritance` copied earlier. Before 5.0.0, the switch was named `-RemoveExplicitAccessRules`, which remains an alias.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose audit inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="RemoveExplicitAccessRules">
|
|
<maml:name>RemoveExplicitAuditRules</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that every audit rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited audit rules only. By default, when the switch is omitted, the explicit audit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAuditInheritance` copied earlier. Before 5.0.0, the switch was named `-RemoveExplicitAccessRules`, which remains an alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemInheritanceInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>The audit section of a security descriptor can only be read and written with the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, the cmdlet writes a non-terminating error that reports Windows error 1314, "A required privilege is not held by the client", and the audit rules of the item stay unchanged.</maml:para>
|
|
<maml:para>If the descriptor cannot be opened because the account has no permission to the item, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; a missing Security privilege is not an access problem and is not repaired by it.</maml:para>
|
|
<maml:para>A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet enabled the privileges even when `EnablePrivileges` was `$false`, and left them enabled.</maml:para>
|
|
<maml:para>Before 5.0.0, `-PassThru` returned the unchanged state of an item also when the change failed, and stopped the command when the item could not be read.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>Example 1: Restore audit inheritance and keep the explicit rules</maml:title>
|
|
<dev:code>PS C:\> Enable-NTFSAuditInheritance -Path C:\Data\Projects</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command lets `C:\Data\Projects` inherit the audit rules of `C:\Data` again. The audit rules that are stored directly on the folder stay in place and are added to the inherited ones.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 2: Restore audit inheritance and drop the explicit rules</maml:title>
|
|
<dev:code>PS C:\> Enable-NTFSAuditInheritance -Path C:\Data\Projects -RemoveExplicitAuditRules -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes every audit rule that is stored directly on the folder and lets it inherit from `C:\Data` again, so the folder is audited exactly like its parent. `-PassThru` returns the resulting state, in which `AuditInheritanceEnabled` is `$true`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------ Example 3: Repair a whole folder tree ------------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSInheritance | Where-Object { $_.AuditInheritanceEnabled -eq $false } | Enable-NTFSAuditInheritance -RemoveExplicitAuditRules</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command finds every item below `C:\Data` whose audit inheritance is blocked and restores it. The comparison with `$false` is deliberate: `AuditInheritanceEnabled` is `$null` for items whose audit section could not be read, and those items are skipped instead of being processed.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 4: Change a security descriptor in memory ------</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects
|
|
PS C:\> Enable-NTFSAuditInheritance -SecurityDescriptor $sd -RemoveExplicitAuditRules
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first two commands read the security descriptor and restore audit inheritance in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Enable-NTFSAuditInheritance.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Enable-Privileges</command:name>
|
|
<command:verb>Enable</command:verb>
|
|
<command:noun>Privileges</command:noun>
|
|
<maml:description>
|
|
<maml:para>Enables the file system privileges in the access token of the current PowerShell process.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Enable-Privileges` cmdlet enables the Take Ownership, Restore, Backup, and Security privileges in the access token of the current PowerShell process. Together these privileges let the other cmdlets of the module read and change the security of files and folders that your account has no permissions on, take ownership of them, and work with audit entries.</maml:para>
|
|
<maml:para>The change affects nothing but the access token of the PowerShell process that runs the cmdlet. Other processes, other PowerShell sessions, and the computer configuration stay untouched, and the privileges are gone as soon as the process ends.</maml:para>
|
|
<maml:para>Unlike the other cmdlets of the module, `Enable-Privileges` leaves the privileges enabled after it finishes, which is the point of the cmdlet: the file system cmdlets enable the same privileges only for the duration of a single call. Calling `Enable-Privileges` is therefore useful when you want the privileges to stay enabled for a whole sequence of commands, or when you turned the automatic handling off by setting `EnablePrivileges` to `$false` in the `PrivateData` section of NTFSSecurity.psd1. When you call the cmdlet yourself, it enables the privileges regardless of that setting.</maml:para>
|
|
<maml:para>A privilege can only be enabled when it is present in the access token, which in practice means an elevated session of an account that holds the privilege, such as a member of the local Administrators group. When all four privileges are enabled, the cmdlet writes a verbose message that names them; otherwise it writes a non-terminating error that reports that the requested privileges could not be enabled and that the cmdlets of the module will only work on resources you have access to.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Enable-Privileges</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns the privileges of the current process after enabling them. Without this parameter, the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns the privileges of the current process after enabling them. Without this parameter, the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>None</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>This cmdlet does not accept pipeline input.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>ProcessPrivileges.PrivilegeAndAttributes</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru`, the cmdlet writes one `ProcessPrivileges.PrivilegeAndAttributes` object per privilege of the current process, each with a `Privilege`, a `PrivilegeAttributes`, and a `PrivilegeState` property. Without `-PassThru`, the cmdlet writes nothing. Before 5.0.0, it wrote the privileges as one collection.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), the file system cmdlets of the module try to enable the Backup, Restore, Take Ownership, and Security privileges while they run and disable the privileges they enabled when they finish. `Enable-Privileges` enables the same privileges but keeps them enabled, so they remain available to every later command in the session until you run `Disable-Privileges` or close the session. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group.</maml:para>
|
|
<maml:para>The cmdlet reads the `EnablePrivileges` entry from the `PrivateData` section of the module manifest. If that entry is missing or cannot be read as a Boolean value, the cmdlet throws a parse error that points to the manifest.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>--- Example 1: Enable the privileges for the current session ---</maml:title>
|
|
<dev:code>PS C:\> Enable-Privileges</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command enables the Take Ownership, Restore, Backup, and Security privileges in the current PowerShell process and leaves them enabled.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---- Example 2: Enable the privileges and check the result ----</maml:title>
|
|
<dev:code>PS C:\> Enable-Privileges
|
|
PS C:\> Get-Privileges | Where-Object { $_.Privilege -in 'Backup', 'Restore', 'TakeOwnership', 'Security' }</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The second command lists the four file system privileges with their current state, which confirms whether the session now holds them in the enabled state.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>- Example 3: Enable the privileges and return them in one step -</maml:title>
|
|
<dev:code>PS C:\> Enable-Privileges -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command enables the privileges and returns all privileges of the current process, so you can see the result without a second call to `Get-Privileges`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 4: Work with enabled privileges and turn them off afterwards</maml:title>
|
|
<dev:code>PS C:\> Enable-Privileges
|
|
PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner
|
|
PS C:\> Disable-Privileges</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The privileges stay enabled while the folder tree is read and are turned off again by the last command. Running `Disable-Privileges` when you are done keeps the session at its normal rights.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Enable-Privileges.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-Privileges</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Privileges</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSOwner</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-ChildItem2</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>ChildItem2</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the files and folders in one or more folders, including paths longer than 260 characters.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-ChildItem2` cmdlet lists the files and folders in the folders that you specify with `-Path`. It returns an `Alphaleonis.Win32.Filesystem.FileInfo` object for every file and an `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for every folder. The cmdlet is the long-path counterpart of the built-in `Get-ChildItem` cmdlet: it enumerates the file system through the AlphaFS library (`Alphaleonis.Win32.Filesystem`) instead of `System.IO`, so it also returns items whose path is longer than the 260-character `MAX_PATH` limit.</maml:para>
|
|
<maml:para>If you omit `-Path`, the cmdlet lists the current location. Relative paths and the `.` and `..` notations are resolved against the current location. Each path must name a folder, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe folders from `Get-ChildItem2` or `Get-Item2` into another `Get-ChildItem2` call, and you can pipe the result into `Get-NTFSAccess` and the other NTFSSecurity cmdlets.</maml:para>
|
|
<maml:para>By default the cmdlet returns the immediate content of each folder and omits hidden items. Use `-Recurse` to walk the whole tree, `-Depth` to limit how deep the recursion goes, `-Filter` to restrict the result by name, `-Directory` or `-File` to restrict it by item type, and `-Force`, `-Hidden`, `-System`, `-ReadOnly`, or `-Attributes` to restrict it by file attributes.</maml:para>
|
|
<maml:para>Two settings in the `PrivateData` section of the module manifest change the objects that this cmdlet emits. `GetFileSystemModeProperty` adds the `Mode` property, which shows the directory, archive, read-only, hidden, and system attributes in `darhs` notation. `IdentifyHardLinks` adds a `HardLinkCount` property to every file object. Both are `$true` by default and are read once when the cmdlet starts.</maml:para>
|
|
<maml:para>A folder that the cmdlet cannot read produces a non-terminating error, and the enumeration continues with the next folder. If a folder cannot be opened while `-Recurse` looks for subfolders, the cmdlet reports the problem as a verbose message instead, so run the command with the `-Verbose` common parameter if you need to know which branches were skipped.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-ChildItem2</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the folders whose content you want to list. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet lists the current location. A value that points to a file returns that file, like `Get-ChildItem`, unless you use `-Directory`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none">
|
|
<maml:name>Filter</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies a name pattern that an item must match to be returned. The pattern supports the ` ` and `?` wildcard characters, and the match ignores case. The default value is ` `, which returns every item. The pattern is applied to the name of each item, not to its path, and during a recursive listing it restricts only the returned items; the cmdlet still descends into every subfolder.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>*</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Attributes</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies a set of file attributes. Like `Get-ChildItem`, the cmdlet returns the items that have at least one of the attributes you list; separate several values with commas, as in `-Attributes Hidden, System`. Unlike `Get-ChildItem`, the parameter takes only such a list, not the `+` and `!` operators; to get only the items that have all the attributes, filter the result, for example with `Where-Object { ($_.Attributes -band [IO.FileAttributes]'Hidden, System') -eq [IO.FileAttributes]'Hidden, System' }`. An empty value, such as `0`, stops the cmdlet with the error `AttributesEmpty`. When you use this parameter, the cmdlet ignores `-Force`, `-Hidden`, `-System`, and `-ReadOnly`, and it returns matching hidden items without `-Force`. The parameter restricts the returned items only; `-Recurse` still descends into every subfolder, including hidden ones.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Hidden</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">System</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Directory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Archive</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Device</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Normal</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Temporary</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SparseFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReparsePoint</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Compressed</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Offline</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NotContentIndexed</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Encrypted</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">IntegrityStream</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NoScrubData</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileAttributes</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileAttributes</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Depth</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies how many additional levels of subfolders a recursive listing covers. `-Depth` takes effect only together with `-Recurse`: `-Depth 0` limits the result to the content of the folders in `-Path`, `-Depth 1` adds one more level of subfolders, and so on. If you omit the parameter, `-Recurse` walks the entire tree.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Int32</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Int32</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Directory</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only folders. If you specify `-Directory` and `-File` together, `-Directory` wins. The parameter restricts the returned items only; `-Recurse` still descends into every subfolder.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>File</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only files. The parameter is ignored if you also specify `-Directory`.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Force</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet also returns hidden items. Without `-Force`, hidden items are left out of the result. The parameter is ignored when you use `-Attributes`.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Hidden</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only hidden items. You do not need `-Force` in addition, because `-Hidden` implies it.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ReadOnly</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only items that have the read-only attribute. Hidden read-only items appear in the result only if you add `-Force`.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Recurse</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet lists the content of all subfolders as well. Without `-Recurse`, only the immediate content of each folder in `-Path` is returned. Use `-Depth` to limit how far the recursion goes.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>SkipMountPoints</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet does not descend into volume mount points. The mount point itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>SkipSymbolicLinks</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet does not descend into folders that are symbolic links. The link itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`, and it protects a recursive listing against loops that symbolic links can create.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>System</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only items that have the system attribute. System files are often hidden as well, so combine this parameter with `-Force` or `-Hidden` to see them.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Attributes</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies a set of file attributes. Like `Get-ChildItem`, the cmdlet returns the items that have at least one of the attributes you list; separate several values with commas, as in `-Attributes Hidden, System`. Unlike `Get-ChildItem`, the parameter takes only such a list, not the `+` and `!` operators; to get only the items that have all the attributes, filter the result, for example with `Where-Object { ($_.Attributes -band [IO.FileAttributes]'Hidden, System') -eq [IO.FileAttributes]'Hidden, System' }`. An empty value, such as `0`, stops the cmdlet with the error `AttributesEmpty`. When you use this parameter, the cmdlet ignores `-Force`, `-Hidden`, `-System`, and `-ReadOnly`, and it returns matching hidden items without `-Force`. The parameter restricts the returned items only; `-Recurse` still descends into every subfolder, including hidden ones.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileAttributes</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileAttributes</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Depth</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies how many additional levels of subfolders a recursive listing covers. `-Depth` takes effect only together with `-Recurse`: `-Depth 0` limits the result to the content of the folders in `-Path`, `-Depth 1` adds one more level of subfolders, and so on. If you omit the parameter, `-Recurse` walks the entire tree.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Int32</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Int32</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Directory</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only folders. If you specify `-Directory` and `-File` together, `-Directory` wins. The parameter restricts the returned items only; `-Recurse` still descends into every subfolder.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>File</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only files. The parameter is ignored if you also specify `-Directory`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none">
|
|
<maml:name>Filter</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies a name pattern that an item must match to be returned. The pattern supports the ` ` and `?` wildcard characters, and the match ignores case. The default value is ` `, which returns every item. The pattern is applied to the name of each item, not to its path, and during a recursive listing it restricts only the returned items; the cmdlet still descends into every subfolder.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>*</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Force</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet also returns hidden items. Without `-Force`, hidden items are left out of the result. The parameter is ignored when you use `-Attributes`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Hidden</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only hidden items. You do not need `-Force` in addition, because `-Hidden` implies it.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the folders whose content you want to list. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet lists the current location. A value that points to a file returns that file, like `Get-ChildItem`, unless you use `-Directory`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ReadOnly</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only items that have the read-only attribute. Hidden read-only items appear in the result only if you add `-Force`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Recurse</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet lists the content of all subfolders as well. Without `-Recurse`, only the immediate content of each folder in `-Path` is returned. Use `-Depth` to limit how far the recursion goes.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>SkipMountPoints</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet does not descend into volume mount points. The mount point itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>SkipSymbolicLinks</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet does not descend into folders that are symbolic links. The link itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`, and it protects a recursive listing against loops that symbolic links can create.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>System</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns only items that have the system attribute. System files are often hidden as well, so combine this parameter with `-Force` or `-Hidden` to see them.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more folder paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.FileInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns this object for every file it finds. Depending on the module settings, the object carries the additional properties `Mode` and `HardLinkCount`.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.DirectoryInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns this object for every folder it finds. Depending on the module settings, the object carries the additional property `Mode`.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>`Get-ChildItem2` enumerates the file system through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it returns items whose path exceeds the 260-character `MAX_PATH` limit that the built-in `Get-ChildItem` cmdlet is bound to. The objects are AlphaFS objects, not `System.IO` objects, and the other NTFSSecurity cmdlets accept them directly because their `-Path` parameters have the alias `FullName`.</maml:para>
|
|
<maml:para>The module defines the alias `dir2` for this cmdlet.</maml:para>
|
|
<maml:para>The default table view shows the `Mode`, `Inherits`, `LastWriteTime`, `Size(M)`, and `Name` columns. `Inherits` is `False` for an item whose access inheritance is disabled. Reading that value costs one access to the ACL of each displayed item, which slows down the display of large listings; to avoid it, select the properties you need, for example with `Format-Table -Property Mode, LastWriteTime, Length, Name`. Objects that you pipe to another command are not affected. Before 5.0.0, the column showed `True` for every item.</maml:para>
|
|
<maml:para>The `PrivateData` section of the module manifest `NTFSSecurity.psd1` contains two settings that this cmdlet reads when it starts. `GetFileSystemModeProperty` adds the calculated `Mode` property to every item. `IdentifyHardLinks` adds the `HardLinkCount` property to every file, which requires an extra call into the file system for each file and therefore slows down large listings noticeably. Set either value to `$false` in the manifest and import the module again if you prefer the faster enumeration over the additional properties.</maml:para>
|
|
<maml:para>A folder that cannot be read produces a non-terminating error with the ID `DirUnauthorizedAccessError` for an access denial or `DirUnspecifiedError` for any other failure, and a path that does not exist produces the error `FileNotFound`. In each case the cmdlet continues with the next path. Failures that occur while `-Recurse` collects the subfolders of a folder are reported as verbose messages only, not as errors.</maml:para>
|
|
<maml:para>Before 5.0.0, a `-Path` value that points to a file stopped the cmdlet with an `InvalidCastException`, `-Attributes` returned only the items that had all the listed attributes, and an empty `-Attributes` value returned every item, also the hidden ones.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>---- Example 1: Find files with a path longer than MAX_PATH ----</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -File | Where-Object { $_.FullName.Length -gt 260 }</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Walks the whole folder tree below `C:\Data` and returns the files whose full path is too long for the built-in `Get-ChildItem` cmdlet.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 2: Read the permissions of every subfolder ------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSAccess</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Lists every subfolder of `C:\Data` and pipes the objects to `Get-NTFSAccess`, which binds their `FullName` property to its own `-Path` parameter and returns the access control entries of each folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 3: Limit the depth of a recursive listing ------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Depth 1 -Filter '*.log'</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Returns the log files in `C:\Data` and in its immediate subfolders. Without `-Depth`, the command would descend through the entire tree.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------ Example 4: List hidden or system files ------------</maml:title>
|
|
<dev:code>PS C:\> dir2 -Path C:\Data -Attributes Hidden, System</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Uses the `dir2` alias and returns the items of `C:\Data` that have the hidden or the system attribute, like `Get-ChildItem -Attributes Hidden, System`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-ChildItem2.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Copy-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Move-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Test-Path2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-DiskSpace</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>DiskSpace</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets size, free space, and cluster information for the volumes of a computer.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-DiskSpace` cmdlet returns one `DiskSpaceInfo` object per volume. The object describes how large the volume is, how much space is free, and how the volume is organized into sectors and clusters.</maml:para>
|
|
<maml:para>When you omit `-DriveLetter`, the cmdlet enumerates all volumes of the computer, including volumes that have no drive letter, and returns the ones that report a total size greater than zero. Volumes that report a size of zero, such as an empty removable drive, are skipped silently, and a volume whose details cannot be read produces a warning instead of an object.</maml:para>
|
|
<maml:para>Each returned object exposes the following properties:</maml:para>
|
|
<maml:para>- `DriveName`: the volume the object describes.</maml:para>
|
|
<maml:para>- `TotalNumberOfBytes`, `TotalNumberOfFreeBytes`, and `FreeBytesAvailable`: the size of the volume, the free space on it, and the free space that is available to the account that runs the cmdlet, all as 64-bit byte counts.</maml:para>
|
|
<maml:para>- `TotalSizeUnitSize`, `UsedSpaceUnitSize`, and `AvailableFreeSpaceUnitSize`: the same figures formatted as readable strings.</maml:para>
|
|
<maml:para>- `UsedSpacePercent` and `AvailableFreeSpacePercent`: used and free space as formatted percentage strings.</maml:para>
|
|
<maml:para>- `BytesPerSector`, `SectorsPerCluster`, `ClusterSize`, `TotalNumberOfClusters`, and `NumberOfFreeClusters`: the sector and cluster layout of the volume.</maml:para>
|
|
<maml:para></maml:para>
|
|
<maml:para>The percentage and unit-size properties are strings that are meant for display. Use the byte and cluster properties when you need to calculate or compare values.</maml:para>
|
|
<maml:para>The cmdlet only reads volume information and does not change anything on disk. `-DriveLetter` does not accept pipeline input.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-DiskSpace</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none">
|
|
<maml:name>DriveLetter</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more drives to query. Each value must be a single letter followed by a colon, such as `C:`; other forms, including `C` and `C:`, are rejected. When you omit this parameter, the cmdlet queries all volumes of the computer, including volumes without a drive letter.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none">
|
|
<maml:name>DriveLetter</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more drives to query. Each value must be a single letter followed by a colon, such as `C:`; other forms, including `C` and `C:`, are rejected. When you omit this parameter, the cmdlet queries all volumes of the computer, including volumes without a drive letter.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>None</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>This cmdlet does not accept pipeline input. Pass the drives to query with the `-DriveLetter` parameter.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.DiskSpaceInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet writes one `DiskSpaceInfo` object per queried volume that reports a total size greater than zero. The object carries the size, free space, percentage, and cluster properties that are listed in the description.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>A volume that cannot be queried, for example a drive that is not ready, produces a warning that names the volume. Use `-WarningAction SilentlyContinue` to suppress those warnings when you query all volumes.</maml:para>
|
|
<maml:para>Because the cmdlet enumerates volumes rather than drive letters when `-DriveLetter` is omitted, the result can contain volumes that are mounted into a folder or that have no mount point at all.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>-------- Example 1: Get the disk space of every volume --------</maml:title>
|
|
<dev:code>PS C:\> Get-DiskSpace</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns one object for every volume of the computer, including volumes that are mounted without a drive letter.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------- Example 2: Get the disk space of a single drive -------</maml:title>
|
|
<dev:code>PS C:\> Get-DiskSpace -DriveLetter C:</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the size and free space of drive C. The drive letter must be written as a letter followed by a colon.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------- Example 3: Show a readable summary of two drives -------</maml:title>
|
|
<dev:code>PS C:\> Get-DiskSpace -DriveLetter C:, D: | Select-Object -Property DriveName, TotalSizeUnitSize, AvailableFreeSpaceUnitSize, AvailableFreeSpacePercent</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the formatted size and free space strings of drives C and D, which are easier to read than the raw byte counts.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-------- Example 4: Find volumes with little free space --------</maml:title>
|
|
<dev:code>PS C:\> Get-DiskSpace | Where-Object { $_.TotalNumberOfFreeBytes -lt 10GB }</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns every volume that has less than 10 GB of free space. The filter uses `TotalNumberOfFreeBytes` because the percentage properties are formatted strings and cannot be compared numerically.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-DiskSpace.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-FileHash2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-FileHash2</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>FileHash2</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the hash value of one or more files.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-FileHash2` cmdlet calculates the hash value of each file that `-Path` points to and returns the file object with the result attached. The returned object is the file object of the file, extended with a `Hash` property that holds the hash as an uppercase hexadecimal string and an `Algorithm` property that names the algorithm that was used. The module's formatting data displays those objects as a table with the `Algorithm`, `Hash`, and `FullName` columns.</maml:para>
|
|
<maml:para>`-Algorithm` selects the hash algorithm and accepts `SHA1`, `SHA256`, `SHA384`, `SHA512`, `MACTripleDES`, `MD5`, and `RIPEMD160`. The default is `SHA256`.</maml:para>
|
|
<maml:para>The cmdlet hashes files only and skips paths that point to folders. A path that does not exist produces a non-terminating `ReadFileError`.</maml:para>
|
|
<maml:para>`-Path` accepts pipeline input by value and by property name through its `FullName` alias, so you can pipe the output of `Get-ChildItem2`, `Get-Item2`, or `Get-ChildItem` into the cmdlet; folders that arrive through the pipeline are skipped individually. Because the cmdlet reads files through the AlphaFS library, it also hashes files whose path exceeds the 260-character `MAX_PATH` limit. Relative paths are resolved against the current location.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-FileHash2</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files to hash. Folders are skipped. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none">
|
|
<maml:name>Algorithm</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the hash algorithm to use. The accepted values are `SHA1`, `SHA256`, `SHA384`, `SHA512`, `MACTripleDES`, `MD5`, and `RIPEMD160`. When you omit this parameter, the cmdlet uses `SHA256`. `RIPEMD160` and `MACTripleDES` are available only in Windows PowerShell 5.1, and `MACTripleDES` is deprecated.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">SHA1</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SHA256</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SHA384</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SHA512</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">MACTripleDES</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">MD5</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">RIPEMD160</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">HashAlgorithms</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>HashAlgorithms</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>SHA256</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none">
|
|
<maml:name>Algorithm</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the hash algorithm to use. The accepted values are `SHA1`, `SHA256`, `SHA384`, `SHA512`, `MACTripleDES`, `MD5`, and `RIPEMD160`. When you omit this parameter, the cmdlet uses `SHA256`. `RIPEMD160` and `MACTripleDES` are available only in Windows PowerShell 5.1, and `MACTripleDES` is deprecated.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">HashAlgorithms</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>HashAlgorithms</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>SHA256</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files to hash. Folders are skipped. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2` and `Get-Item2`, to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystem.FileInfo.HashAlgorithms</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can supply the `-Algorithm` value through a pipeline object that has an `Algorithm` property.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.FileInfo+Hash</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>For every hashed file, the cmdlet writes the file object of that file, decorated with the type name `Alphaleonis.Win32.Filesystem.FileInfo+Hash` and extended with the `Hash` and `Algorithm` note properties, so all regular file properties such as `FullName`, `Name`, and `Length` remain available. Before 5.0.0, the cmdlet declared `Alphaleonis.Win32.Filesystem.FileInfo` as its output type.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>In PowerShell 7, the cmdlet supports `SHA1`, `SHA256`, `SHA384`, `SHA512`, and `MD5`. .NET no longer includes `RIPEMD160` and `MACTripleDES`, so requesting one of them there stops the cmdlet with the error `HashAlgorithmNotAvailable`, which names the algorithm; use Windows PowerShell 5.1 to calculate those hashes. Before 5.0.0, the cmdlet failed in PowerShell 7 for every algorithm with the error `Could not load type 'System.Security.Cryptography.RIPEMD160'`.</maml:para>
|
|
<maml:para>If the file cannot be opened because access is denied, the cmdlet takes ownership of the file with the account that runs it, calculates the hash, and restores the previous owner afterward. That fallback fails with a `GetHashError` when the account is not allowed to change the owner of the file. A file that cannot be read produces a `GetHashError` and no result.</maml:para>
|
|
<maml:para>The hash is returned as an uppercase hexadecimal string without separators, which differs from the lowercase output of some other hashing tools. Compare hash values case-insensitively.</maml:para>
|
|
<maml:para>`MACTripleDES` is a keyed message authentication code that is created with a key that is generated for each call, so its result is not reproducible across invocations and is not suitable for comparing files. The value is deprecated: the cmdlet writes a warning when you use it, and a future version will remove it.</maml:para>
|
|
<maml:para>Before 5.0.0, a folder in a `-Path` array stopped the processing of that array, so the files that followed the folder were not hashed, and a file that could not be read got a result with the hash of the previous file.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>----------- Example 1: Get the SHA256 hash of a file -----------</maml:title>
|
|
<dev:code>PS C:\> Get-FileHash2 -Path C:\Data\Report.txt</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command calculates the hash of `Report.txt` with the default `SHA256` algorithm and returns the file object with the `Algorithm` and `Hash` properties attached.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------ Example 2: Get the MD5 hash of a file ------------</maml:title>
|
|
<dev:code>PS C:\> Get-FileHash2 -Path C:\Data\Report.txt -Algorithm MD5</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command calculates the `MD5` hash of the same file. `MD5` and `SHA1` are fast but are no longer considered collision resistant, so use them for change detection rather than for security decisions.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--------- Example 3: Hash every file in a folder tree ---------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-FileHash2 -Algorithm SHA1 | Select-Object -Property Algorithm, Hash, FullName</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command pipes all items below `C:\Data` into `Get-FileHash2`. The cmdlet binds the `FullName` property of each item to `-Path`, hashes the files, and skips the folders.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--------- Example 4: Find files with identical content ---------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-FileHash2 | Group-Object -Property Hash | Where-Object { $_.Count -gt 1 }</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command groups the files below `C:\Data` by hash value and returns the groups that contain more than one file, which identifies files whose content is identical.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-FileHash2.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Test-Path2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Copy-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-Item2</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>Item2</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the file or folder at a specified path, including paths longer than 260 characters.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-Item2` cmdlet gets the item at a location and returns an `Alphaleonis.Win32.Filesystem.FileInfo` object for a file or an `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for a folder. It is the long-path counterpart of the built-in `Get-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`) instead of `System.IO`, so it also reaches items whose path is longer than the 260-character `MAX_PATH` limit.</maml:para>
|
|
<maml:para>If you omit `-Path`, the cmdlet returns the item for the current location. Relative paths and the `.` and `..` notations are resolved against the current location as well. Wildcard characters are not supported, so each value of `-Path` must name one existing file or folder. For a path that does not exist, the cmdlet writes a non-terminating error and continues with the remaining paths.</maml:para>
|
|
<maml:para>Every returned object carries an additional `Mode` property that reports the directory, archive, read-only, hidden, and system attributes in the same `darhs` notation that `Get-ChildItem` uses. Because the objects expose a `FullName` property and the `-Path` parameters of the NTFSSecurity cmdlets have the alias `FullName`, you can pipe the result straight into cmdlets such as `Get-NTFSAccess`, `Add-NTFSAccess`, or `Get-NTFSOwner`.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-Item2</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet returns the item for the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet returns the item for the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.FileInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns this object for every path that points to a file, extended with a `Mode` property.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.DirectoryInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns this object for every path that points to a folder, extended with a `Mode` property.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>`Get-Item2` builds on the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it reaches files and folders whose path exceeds the 260-character `MAX_PATH` limit that the built-in `Get-Item` cmdlet is bound to. The objects it returns are AlphaFS objects, not `System.IO` objects, and the other NTFSSecurity cmdlets accept them directly through the `FullName` alias of their `-Path` parameters.</maml:para>
|
|
<maml:para>The module defines the alias `gi2` for this cmdlet.</maml:para>
|
|
<maml:para>`Get-Item2` always adds the `Mode` property. The `GetFileSystemModeProperty` setting in the `PrivateData` section of the module manifest controls only `Get-ChildItem2`.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------------------- Example 1: Get a folder -------------------</maml:title>
|
|
<dev:code>PS C:\> Get-Item2 -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Returns the `DirectoryInfo` object for the `C:\Data` folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--- Example 2: Read the permissions of a deeply nested file ---</maml:title>
|
|
<dev:code>PS C:\> Get-Item2 -Path C:\Data\Projects\Archive\2026\Q1\Reports\Regional\Summary.docx | Get-NTFSAccess</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Gets the file and pipes it to `Get-NTFSAccess`, which binds the `FullName` property of the object to its own `-Path` parameter. The command also works when the full path is longer than 260 characters.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-------- Example 3: Get several items from the pipeline --------</maml:title>
|
|
<dev:code>PS C:\> 'C:\Data', 'C:\Data\Reports' | Get-Item2 | Select-Object Mode, LastWriteTime, FullName</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Pipes two paths into the cmdlet and shows the attribute mode, the last write time, and the full path of each item.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---- Example 4: Use the alias and the positional parameter ----</maml:title>
|
|
<dev:code>PS C:\> gi2 C:\Data\report.docx</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Uses the `gi2` alias and passes the path positionally to get a single file.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-Item2.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Copy-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Move-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Test-Path2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSAccess</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSAccess</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the access control entries (ACEs) of a file, a folder, or a security descriptor.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>Reads the discretionary access control list (DACL) of a file or a folder and writes one `Security2.FileSystemAccessRule2` object for every access control entry (ACE) it contains. Each object carries the account, the rights, the access type, the inheritance and propagation flags, whether the ACE is inherited, and the path of the item it was read from.</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet reads the item from disk; relative paths are resolved against the current location, and when `-Path` is omitted the current location is used. In the `SD` parameter set it reads the ACEs from a `Security2.FileSystemSecurity2` object returned by `Get-NTFSSecurityDescriptor`, which also reflects changes that have not been written back yet.</maml:para>
|
|
<maml:para>By default both explicit and inherited entries are returned. `-ExcludeInherited` limits the result to the entries defined on the item itself, `-ExcludeExplicit` limits it to the entries the item inherits from its parents, and combining both returns nothing. `-Account` filters the result to a single account; an entry matches when the account resolves to the same SID.</maml:para>
|
|
<maml:para>When the module setting `GetInheritedFrom` is `$true`, which is the default in the `PrivateData` section of NTFSSecurity.psd1, the `InheritedFrom` property of every inherited entry contains the path of the folder the entry originates from. The default table view shows the account, the rights, the scope of the ACE in the wording of the Windows security dialog, the access type, and the inheritance information; setting `ShowAccountSid` to `$true` adds the SID to the account column.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSAccess</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose access control entries are read. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose access control entries are returned. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. When the parameter is omitted, the entries of all accounts are returned.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are returned.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are returned.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are read. This includes changes that were made to the object in memory and not written back yet.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose access control entries are returned. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. When the parameter is omitted, the entries of all accounts are returned.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are returned.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are returned.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose access control entries are returned. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. When the parameter is omitted, the entries of all accounts are returned.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are returned.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are returned.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose access control entries are read. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are read. This includes changes that were made to the object in memory and not written back yet.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more paths of files or folders, piped by value or by the property `FullName`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more security descriptors returned by `Get-NTFSSecurityDescriptor`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The account to filter on. The parameter does not take pipeline input; it is listed here because it accepts the remaining arguments of the command line.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemAccessRule2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One object per access control entry, with the account, the rights, the access type, the inheritance and propagation flags, the `IsInherited` and `InheritedFrom` properties, and the path of the item.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>If the ACL of an item cannot be read because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them.</maml:para>
|
|
<maml:para>Entries whose account cannot be translated into a name are returned with their SID. Use `Get-NTFSOrphanedAccess` to list only those entries.</maml:para>
|
|
<maml:para>Before 5.0.0, after a path whose ACL could not be read, the cmdlet returned the entries of the previous item again.</maml:para>
|
|
<maml:para>For the root of a drive, such as `C:`, or of a volume, such as `\?\Volume{GUID}`, the cmdlets that read and change security use the root folder of the volume, like Explorer, `icacls`, and `Get-Acl`. Before 5.0.0, they read and changed the security descriptor of the drive itself, a device object with other entries.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>---- Example 1: Get all access control entries of a folder ----</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSAccess -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the explicit and the inherited access control entries of `C:\Data`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 2: Get only the permissions defined on the item itself</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSAccess -Path C:\Data -ExcludeInherited</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the explicit access control entries of `C:\Data` and omits everything the folder inherits from its parents.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 3: Find the permissions of one account in a folder tree</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSAccess -Account 'CONTOSO\JohnDoe' -ExcludeInherited</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command searches all subfolders of `C:\Data` for access control entries that were defined for a single account. `Get-ChildItem` and `Get-Item2` can be used in the same way, because the `FullName` property of their output binds to `-Path`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 4: Export the explicit permissions of a folder tree to a CSV file</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAccess -ExcludeInherited | Export-Csv -Path C:\Backup\acl.csv -NoTypeInformation</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command writes a backup of all explicit access control entries below `C:\Data`. `Import-Csv C:\Backup\acl.csv | Add-NTFSAccess` recreates them, because the exported columns bind to the parameters of `Add-NTFSAccess`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSAccess.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSOrphanedAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSimpleAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSEffectiveAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSAudit</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSAudit</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the audit entries of a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-NTFSAudit` cmdlet returns the audit entries that are stored in the system access control list (SACL) of a file or folder. Each entry is a `Security2.FileSystemAuditRule2` object that reports the audited account, the audited access rights, the audit flags (`Success`, `Failure`, or both), the inheritance and propagation flags, whether the entry is inherited, and the item it is inherited from. The access rights are the same values that `Add-NTFSAccess` and `Add-NTFSAudit` use; for what each right permits, see Concepts (../Concepts.md).</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet reads the security descriptor of every item in `-Path`. Relative paths are resolved against the current location, and when you omit `-Path` the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. In the `SD` parameter set the cmdlet reads the audit entries from an in-memory `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned instead of reading the item again.</maml:para>
|
|
<maml:para>By default the cmdlet returns explicit and inherited entries. Use `-ExcludeInherited` to return only the entries that are set on the item itself, and `-ExcludeExplicit` to return only the entries that the item inherits from a parent folder. `-Account` filters the result to a single account; the comparison is made on the security identifier (SID), so an account name and its SID select the same entries.</maml:para>
|
|
<maml:para>The `InheritedFrom` property is filled only when the module setting `GetInheritedFrom` is `$true`, which is the default in the `PrivateData` section of `NTFSSecurity.psd1`.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSAudit</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders whose audit entries are returned. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose audit entries are returned. The value is an account name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. Entries are matched by SID, and when you omit the parameter the entries of all accounts are returned.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries that are set on the item itself are left out, so that only the inherited entries are returned. By default the cmdlet returns explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are returned. By default the cmdlet returns explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the audit entries from the system access control list (SACL) of the in-memory object instead of reading the item from disk again.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose audit entries are returned. The value is an account name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. Entries are matched by SID, and when you omit the parameter the entries of all accounts are returned.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries that are set on the item itself are left out, so that only the inherited entries are returned. By default the cmdlet returns explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are returned. By default the cmdlet returns explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose audit entries are returned. The value is an account name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. Entries are matched by SID, and when you omit the parameter the entries of all accounts are returned.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries that are set on the item itself are left out, so that only the inherited entries are returned. By default the cmdlet returns explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are returned. By default the cmdlet returns explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders whose audit entries are returned. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the audit entries from the system access control list (SACL) of the in-memory object instead of reading the item from disk again.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pass an account name or a SID string to `-Account`, which the cmdlet converts to this type. The parameter does not accept pipeline input.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemAuditRule2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns one object per audit entry, with the audited account, the audited access rights, the audit flags, the inheritance and propagation flags, the `IsInherited` flag, and the `InheritedFrom` path. When an item has no audit entries, the cmdlet returns nothing for that item; when its SACL cannot be read, the cmdlet writes an error.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Reading the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it, the cmdlet writes the non-terminating error `ReadSecurityError` for each item, which reports "A required privilege is not held by the client". `Get-NTFSSecurityDescriptor` reads a security descriptor without its SACL when the privilege is missing; for such a descriptor, the cmdlet writes a `ReadSecurityError` as well.</maml:para>
|
|
<maml:para>If reading the audit entries is denied, the cmdlet writes a `ReadSecurityError` with the category `PermissionDenied`. It doesn't take ownership of the item, because ownership grants no access to the SACL.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet returned no entries and no error without the Security privilege, and after a path whose security descriptor could not be read, it returned the entries of the previous item again. The `InheritanceEnabled` property of the entries also reported whether the access entries were inherited instead of the audit entries.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>--------- Example 1: Get the audit entries of a folder ---------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSAudit -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns every audit entry of the folder `C:\Data`, including the entries that the folder inherits from its parent.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>- Example 2: List the explicit audit entries of a folder tree -</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAudit -ExcludeInherited</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command pipes every item below `C:\Data` into `Get-NTFSAudit` and returns only the audit entries that are set on the items themselves.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-------- Example 3: Filter the audit entries by account --------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSAudit -Path C:\Data -Account 'CONTOSO\JohnDoe'</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns only the entries that audit the account `CONTOSO\JohnDoe`. Passing the SID of the account instead of its name returns the same entries.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>- Example 4: Read the audit entries from a security descriptor -</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Get-NTFSAudit -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command reads the security descriptor of `C:\Data` once and then lists its audit entries from the in-memory object.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSAudit.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Clear-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSOrphanedAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSEffectiveAccess</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSEffectiveAccess</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the rights an account effectively has on a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>Calculates the rights an account really has on a file or a folder and writes the result as a single `Security2.FileSystemAccessRule2` object per item. The cmdlet evaluates the complete discretionary access control list (DACL) of the item against the group memberships of the account with the Windows Authorization API, so allow entries, deny entries, and inherited entries are combined the same way the Windows access check combines them. This is the equivalent of the "Effective Access" tab of the advanced security dialog.</maml:para>
|
|
<maml:para>The calculation covers the NTFS permissions of the item only. Share permissions are stored in a separate security descriptor and are not part of the result, so access over a network share can be more restrictive than this cmdlet reports.</maml:para>
|
|
<maml:para>When `-Account` is omitted, the account that runs the session is used. `-ServerName` selects the computer whose authorization manager resolves the group memberships of the account and defaults to `localhost`; when the remote authorization manager of the named computer cannot be reached, the cmdlet falls back to the local one and warns that the result is based on the group memberships known on this computer and may be inaccurate. Reading effective access relies on the Security privilege, and the cmdlet warns when the account does not hold it or the privilege is disabled.</maml:para>
|
|
<maml:para>When `-Path` is omitted, the cmdlet calculates the effective access to the current location. In the `SecurityDescriptor` parameter set, it calculates the effective access from a `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned, without reading the item again.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSEffectiveAccess</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders the effective access is calculated for. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. When you omit the parameter, the cmdlet uses the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="NTAccount, IdentityReference">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account the effective access is calculated for. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. The default is the account that runs the current session.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Current user</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeNoneAccessEntries</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that items on which the account has no rights at all are left out of the result. Because every calculated result includes the `Synchronize` right, an item counts as without rights when `Synchronize` is the only right.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ServerName</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the computer whose authorization manager resolves the group memberships of the account. The default is `localhost`. Name the computer that stores the item when you query a network path, because the group memberships known there determine the result; if that computer cannot be reached, the cmdlet falls back to the local authorization manager and warns that the result may be inaccurate.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>localhost</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSEffectiveAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet calculates the effective access from the in-memory object instead of reading the item again.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="NTAccount, IdentityReference">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account the effective access is calculated for. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. The default is the account that runs the current session.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Current user</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeNoneAccessEntries</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that items on which the account has no rights at all are left out of the result. Because every calculated result includes the `Synchronize` right, an item counts as without rights when `Synchronize` is the only right.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ServerName</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the computer whose authorization manager resolves the group memberships of the account. The default is `localhost`. Name the computer that stores the item when you query a network path, because the group memberships known there determine the result; if that computer cannot be reached, the cmdlet falls back to the local authorization manager and warns that the result may be inaccurate.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>localhost</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="NTAccount, IdentityReference">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account the effective access is calculated for. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. The default is the account that runs the current session.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Current user</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeNoneAccessEntries</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that items on which the account has no rights at all are left out of the result. Because every calculated result includes the `Synchronize` right, an item counts as without rights when `Synchronize` is the only right.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders the effective access is calculated for. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. When you omit the parameter, the cmdlet uses the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet calculates the effective access from the in-memory object instead of reading the item again.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ServerName</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the computer whose authorization manager resolves the group memberships of the account. The default is `localhost`. Name the computer that stores the item when you query a network path, because the group memberships known there determine the result; if that computer cannot be reached, the cmdlet falls back to the local authorization manager and warns that the result may be inaccurate.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>localhost</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more paths of files or folders, piped by value or by the property `FullName`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet calculates the effective access from the descriptor in memory instead of reading the item again.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The account the effective access is calculated for, piped by the property `Account`, `NTAccount`, or `IdentityReference`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemAccessRule2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One object per item, with the calculated rights in `AccessRights` and the account in `Account`. The object describes a result, not an entry of the ACL, so it is always of the access type `Allow`, it is never inherited, and it carries no inheritance or propagation flags.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Reading effective access needs the Security privilege. In a session that does not hold it, the cmdlet warns before it starts and the calculation may fail with an error. Use `Enable-Privileges` in an elevated session to enable the privilege, and `Get-Privileges` to see which privileges the session holds. When the calculation fails, the error names the cause that Windows reported, such as a security descriptor without an owner; before 5.0.0, it blamed a missing Security privilege whenever the privilege wasn't enabled.</maml:para>
|
|
<maml:para>Before 5.0.0, `-ExcludeNoneAccessEntries` had no effect, and the cmdlet returned nothing without `-Path` or for `-SecurityDescriptor`. When the computer of `-ServerName` couldn't be reached, the cmdlet warned that it had calculated the result on this computer, but returned no access instead of that result.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>--- Example 1: Get the effective access of the current user ---</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSEffectiveAccess -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the rights the account that runs the session has on `C:\Data`, combining all allow and deny entries of the folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---- Example 2: Get the effective access of another account ----</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSEffectiveAccess -Path C:\Data -Account 'CONTOSO\JohnDoe'</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the rights of a domain user on `C:\Data`. A group such as `CONTOSO\Domain Users` or `BUILTIN\Users` can be used in the same way.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--- Example 3: Compare the effective access of a folder tree ---</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSEffectiveAccess -Account 'CONTOSO\JohnDoe'</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command shows for every subfolder of `C:\Data` what an account is allowed to do there, which makes the folders visible where inheritance is broken or a deny entry applies.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 4: Calculate effective access with the group memberships of a file server</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSEffectiveAccess -Path \\FileServer\Data -Account 'CONTOSO\JohnDoe' -ServerName FileServer</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command asks the authorization manager of the file server to resolve the group memberships of the account, which gives a more accurate result than the local fallback.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSEffectiveAccess.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSimpleAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-Privileges</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Privileges</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSHardLink</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSHardLink</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets all hard links that refer to the same file as the specified path.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>On an NTFS volume, a file is a block of data that one or more directory entries, called hard links, refer to. The `Get-NTFSHardLink` cmdlet asks the file system for every hard link of the file that `-Path` points to and writes a file object for each of them, including the name that you passed in.</maml:para>
|
|
<maml:para>A file that has only one name returns a single object. A file that has additional hard links returns one object per name, which lets you find all the places on the volume from which the same data is reachable. The file system reports the links relative to the root of the volume, and the cmdlet combines them with the root of the path you specify, so the result contains full paths. All hard links of a file are always on the same volume as the file.</maml:para>
|
|
<maml:para>`-Path` must point to a file. A folder causes a non-terminating `GetHardLinkError`, because NTFS does not support hard links to folders, and the cmdlet continues with the next path. If you omit `-Path`, the cmdlet falls back to the current location, which is a folder and therefore produces the same error, so always pass the path of a file.</maml:para>
|
|
<maml:para>The parameter accepts an array of paths and takes pipeline input by value and by property name through its `FullName` alias. `Get-ChildItem2` adds a `HardLinkCount` property to each file as long as the `IdentifyHardLinks` entry in the `PrivateData` section of the module manifest is `$true`, which lets you select the files that have more than one name before you resolve them.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSHardLink</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files whose hard links you want to resolve. The path must point to a file; folders cause an error. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files whose hard links you want to resolve. The path must point to a file; folders cause an error. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more file path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2` and `Get-Item2`, to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.FileInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet writes one file object per hard link of the file, extended with a `Mode` property that renders the file attributes in the same notation as `Get-ChildItem2`.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.DirectoryInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet never writes folder objects, because it rejects folders with the error `The item must be a file`.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>Hard links exist only within a single NTFS volume. Every object that this cmdlet returns therefore refers to a path on the volume of the file that you passed in.</maml:para>
|
|
<maml:para>Windows can't list the names of a file on a network share, also when the share lies on an NTFS volume of the file server. For such a file the cmdlet writes a non-terminating `GetHardLinkError` with the message "The request is not supported" and continues with the next path; run the cmdlet on the file server itself instead. Before 5.0.0, a file on a network share and a folder stopped the cmdlet with a terminating error, so that it skipped the remaining paths.</maml:para>
|
|
<maml:para>Because all hard links of a file share the same data, they also share the file content, the file size, and the time stamps. The security descriptor is stored with the file as well, so changing permissions through one name changes them for every name.</maml:para>
|
|
<maml:para>The cmdlet resolves paths through the AlphaFS library and therefore also works with paths that exceed the 260-character `MAX_PATH` limit.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>-------------- Example 1: Get all names of a file --------------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSHardLink -Path C:\Data\Report.txt</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns one object for every hard link of `Report.txt`, including `Report.txt` itself. If the file has no additional links, the command returns that single file.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------- Example 2: List the full paths of all hard links -------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSHardLink -Path C:\Data\Report.txt | Select-Object -ExpandProperty FullName</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the full path of every name under which the data of `Report.txt` is reachable on the volume.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 3: Resolve the hard links of all multi-link files in a folder</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Where-Object { $_.HardLinkCount -gt 1 } | Get-NTFSHardLink</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command uses the `HardLinkCount` property that `Get-ChildItem2` adds to files to select the files that have more than one name, and then resolves all names of each of them.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------- Example 4: Count the names of a file -------------</maml:title>
|
|
<dev:code>PS C:\> (Get-NTFSHardLink -Path C:\Data\Report.txt).Count</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the number of hard links that refer to the data of `Report.txt`. A result of `1` means that deleting the file releases its data.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSHardLink.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>New-NTFSHardLink</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>New-NTFSSymbolicLink</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSInheritance</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSInheritance</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the inheritance state of the access rules and the audit rules of a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-NTFSInheritance` cmdlet reports whether a file or folder inherits access rules from its parent folder and whether it inherits audit rules. For each item it writes one `Security2.FileSystemInheritanceInfo` object with the `Name`, `FullName`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled` properties, plus the underlying file system object in the `Item` property. The default table view shows `Name`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled`.</maml:para>
|
|
<maml:para>`AccessInheritanceEnabled` is `$false` when the discretionary access control list (DACL) of the item is protected, which is the state that `Disable-NTFSAccessInheritance` produces. `AuditInheritanceEnabled` reports the same for the system access control list (SACL), which holds the audit rules. When the audit section cannot be read because the session does not hold the Security privilege, `AuditInheritanceEnabled` is `$null` and its column stays empty; the access value is still reported and no error is written.</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet reads the security descriptor of each item from disk. In the `SecurityDescriptor` parameter set it reads the state from the `Security2.FileSystemSecurity2` objects that `Get-NTFSSecurityDescriptor` returns, without touching the file system. A descriptor that was read without its audit section, because the session doesn't hold the Security privilege, reports `AuditInheritanceEnabled` as `$null`, like the `Path` parameter set.</maml:para>
|
|
<maml:para>`-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. Relative paths are resolved against the current location, and when no path is supplied at all, the cmdlet reports the current location.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSInheritance</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders to report on. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted and no item arrives from the pipeline. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSInheritance</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet reads the inheritance state from the descriptor in memory and does not access the file system for it.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders to report on. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted and no item arrives from the pipeline. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet reads the inheritance state from the descriptor in memory and does not access the file system for it.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemInheritanceInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>For each item the cmdlet writes one object with the `Name`, `FullName`, `Item`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled` properties. `AccessInheritanceEnabled` and `AuditInheritanceEnabled` are `$true` when the item inherits the rules of the corresponding section from its parent folder, and `AuditInheritanceEnabled` is `$null` when the audit section could not be read.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Reading the audit section (SACL) of an item requires the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, the cmdlet still reports the access state and sets `AuditInheritanceEnabled` to `$null` instead of writing an error.</maml:para>
|
|
<maml:para>Before 5.0.0, a security descriptor that was read without its audit section reported `AuditInheritanceEnabled` as `$true`.</maml:para>
|
|
<maml:para>If the security descriptor of an item cannot be opened because the account has no permission to it, the cmdlet takes ownership of the item, reads the state, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item.</maml:para>
|
|
<maml:para>A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet enabled the privileges even when `EnablePrivileges` was `$false`, and left them enabled.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------- Example 1: Get the inheritance state of a folder -------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSInheritance -Path C:\Data\Projects</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command reports whether `C:\Data\Projects` inherits access rules and audit rules from `C:\Data`. In a session that does not hold the Security privilege, the `AuditInheritanceEnabled` column stays empty.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title> Example 2: Find the items whose access inheritance is blocked </maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSInheritance | Where-Object { -not $_.AccessInheritanceEnabled }</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command walks the whole tree below `C:\Data` and returns only the items whose DACL is protected. These are the places where the permission model of the tree is interrupted and permissions have to be maintained separately.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------ Example 3: Report the current location ------------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSInheritance</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command reports the inheritance state of the current location, because `-Path` is omitted and no item arrives from the pipeline.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----- Example 4: Read the state from a security descriptor -----</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSSecurityDescriptor -Path C:\Data\Projects | Get-NTFSInheritance</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command reads the security descriptor once and reports its inheritance state from memory. The access value is always accurate; the audit value is only meaningful when the descriptor was retrieved with its audit section, which requires the Security privilege.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSInheritance.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSOrphanedAccess</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSOrphanedAccess</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the access control entries whose account cannot be resolved to a name.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>Reads the discretionary access control list (DACL) of a file or a folder like `Get-NTFSAccess` and returns only the access control entries whose account name is empty. The account name of an entry is empty when Windows cannot translate the SID stored in the entry into an account name, which is what remains after the account the entry was created for has been deleted.</maml:para>
|
|
<maml:para>An entry counts as orphaned only as long as the name resolution fails, and the cmdlet cannot tell a deleted account from an account that cannot be looked up right now. A domain controller that is unreachable, a broken trust, or a SID from a domain the computer does not know make intact entries look orphaned as well. Confirm that the accounts are really gone before you remove anything, and run the search from a computer that can resolve all domains involved.</maml:para>
|
|
<maml:para>Relative paths are resolved against the current location, and the current location is searched when `-Path` is omitted. By default both explicit and inherited entries are returned, which means that the same orphaned entry appears on every item that inherits it; `-ExcludeInherited` reports it only on the item where it is defined. With `-Verbose`, the cmdlet reports the number of orphaned entries per item and the total at the end.</maml:para>
|
|
<maml:para>`-Account` limits the result to the entries of one account, which you specify by its SID. With `-SecurityDescriptor`, the cmdlet examines a `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned instead of reading the item again.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSOrphanedAccess</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders that are searched for orphaned access control entries. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose orphaned entries are returned. Because the account cannot be resolved, specify it by its SID. When you omit the parameter, the cmdlet returns the entries of all accounts that cannot be resolved.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are searched.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are searched. Use this switch to report an orphaned entry once instead of on every item that inherits it.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSOrphanedAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet examines the in-memory objects instead of reading the items again.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose orphaned entries are returned. Because the account cannot be resolved, specify it by its SID. When you omit the parameter, the cmdlet returns the entries of all accounts that cannot be resolved.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are searched.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are searched. Use this switch to report an orphaned entry once instead of on every item that inherits it.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose orphaned entries are returned. Because the account cannot be resolved, specify it by its SID. When you omit the parameter, the cmdlet returns the entries of all accounts that cannot be resolved.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are searched.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are searched. Use this switch to report an orphaned entry once instead of on every item that inherits it.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders that are searched for orphaned access control entries. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet examines the in-memory objects instead of reading the items again.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more paths of files or folders, piped by value or by the property `FullName`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>An account name or a SID string binds to `-Account`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemAccessRule2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One object per orphaned access control entry. The `Account` property holds the unresolved SID and reports an empty account name.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>If the ACL of an item cannot be read because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet ignored `-Account` and `-SecurityDescriptor`, and after a path whose ACL could not be read, it returned the orphaned entries of the previous item again.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>--------- Example 1: Find orphaned entries in a folder ---------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSOrphanedAccess -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the access control entries of `C:\Data` whose SID cannot be resolved, including the entries the folder inherits from its parent.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----- Example 2: Search a folder tree for orphaned entries -----</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess -ExcludeInherited</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command searches all files and folders below `C:\Data` and reports every orphaned entry on the item where it is defined. Without `-ExcludeInherited` the same entry would also be reported on every item that inherits it.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-------------- Example 3: Remove orphaned entries --------------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess -ExcludeInherited | Remove-NTFSAccess</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command deletes the orphaned entries from the items they are defined on. The piped objects supply the path, the SID, the rights, the access type, and the flags, so each entry is matched exactly as it exists.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSOrphanedAccess.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSOrphanedAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSimpleAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSOrphanedAudit</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSOrphanedAudit</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the audit entries whose account cannot be resolved.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-NTFSOrphanedAudit` cmdlet returns the audit entries of a file or folder whose account cannot be translated into a name. An entry is called orphaned when its security identifier (SID) is still stored in the system access control list (SACL) but Windows cannot map that SID to a user or group, which usually happens after the account was deleted. Orphaned entries are shown with their SID instead of a name, and they keep auditing a security principal that no longer exists.</maml:para>
|
|
<maml:para>An entry is reported as orphaned whenever the name resolution fails at that moment, not only when the account is really gone. A domain account whose domain controller cannot be reached, an account from a domain whose trust relationship is broken, and an account from a forest the computer currently cannot contact all look exactly like a deleted account. Verify that an account no longer exists before you remove its entries with `Remove-NTFSAudit`.</maml:para>
|
|
<maml:para>The cmdlet is built on `Get-NTFSAudit` and reads the SACL of every item in `-Path`, using the current location when you omit the parameter. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. `-ExcludeExplicit` and `-ExcludeInherited` narrow the entries that are examined, and `-Verbose` reports how many orphaned entries each item has and their total.</maml:para>
|
|
<maml:para>`-Account` limits the result to the entries of one account, which you specify by its SID. With `-SecurityDescriptor`, the cmdlet examines a `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned; a descriptor that was read without the Security privilege doesn't contain the audit entries, and the cmdlet writes an error for it.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSOrphanedAudit</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders that are examined. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose orphaned audit entries are returned. Because the account cannot be resolved, specify it by its SID. When you omit the parameter, the cmdlet returns the entries of all accounts that cannot be resolved.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries that are set on the item itself are left out, so that only inherited entries are examined. By default the cmdlet examines explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are examined. By default the cmdlet examines explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSOrphanedAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet examines the in-memory objects instead of reading the items again.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose orphaned audit entries are returned. Because the account cannot be resolved, specify it by its SID. When you omit the parameter, the cmdlet returns the entries of all accounts that cannot be resolved.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries that are set on the item itself are left out, so that only inherited entries are examined. By default the cmdlet examines explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are examined. By default the cmdlet examines explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose orphaned audit entries are returned. Because the account cannot be resolved, specify it by its SID. When you omit the parameter, the cmdlet returns the entries of all accounts that cannot be resolved.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries that are set on the item itself are left out, so that only inherited entries are examined. By default the cmdlet examines explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are examined. By default the cmdlet examines explicit and inherited entries.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders that are examined. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet examines the in-memory objects instead of reading the items again.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>Security descriptors bind to the inherited `-SecurityDescriptor` parameter, but this cmdlet does not read their audit entries.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>An account name or a SID string binds to `-Account`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemAuditRule2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns the audit entries whose account SID cannot be translated into a name, each with the item, the unresolved account, the audited access rights, the audit flags, and the inheritance information. The cmdlet writes one object per entry.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Reading the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it the cmdlet reads the security descriptor without its SACL and reports no orphaned entries at all, which looks the same as a tree that has none.</maml:para>
|
|
<maml:para>If an item cannot be read, the cmdlet writes a warning and continues with the next item. Unlike `Get-NTFSAudit`, it does not try to take ownership of the item when access is denied.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet ignored `-Account` and `-SecurityDescriptor` and wrote the entries of each item as one collection.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>--- Example 1: Find orphaned audit entries in a folder tree ---</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAudit</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command examines every item below `C:\Data` and returns the audit entries whose account cannot be resolved.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 2: Find orphaned entries that are set on the item itself</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSOrphanedAudit -Path C:\Data -ExcludeInherited</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command skips the audit entries that `C:\Data` inherits from its parent and reports only the orphaned entries that are set on the folder itself. Those are the entries that can be removed on this item.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----- Example 3: Collect the orphaned entries for a report -----</maml:title>
|
|
<dev:code>PS C:\> $orphaned = Get-NTFSOrphanedAudit -Path C:\Data -Verbose
|
|
PS C:\> $orphaned | Select-Object FullName, Account, AccessRights, AuditFlags</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command stores the result in a variable and then lists the item, the unresolved SID, the audited rights, and the audit flags of every orphaned entry.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------ Example 4: Check the current location ------------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSOrphanedAudit</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command examines the current location, because `-Path` is omitted.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSOrphanedAudit.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Clear-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSOrphanedAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSOwner</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSOwner</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the owner of a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-NTFSOwner` cmdlet reads the owner from the security descriptor of a file or folder and returns a `Security2.FileSystemOwner` object. That object exposes the item in the `Item` property, its full path in `FullName`, and the owning account in both the `Owner` and the `Account` property.</maml:para>
|
|
<maml:para>The `Path` parameter set reads the owner from the file system. The `SecurityDescriptor` parameter set reads the owner from a security descriptor that `Get-NTFSSecurityDescriptor` returned. The second form also shows an owner that `Set-NTFSOwner` changed in memory but that has not been written back with `Set-NTFSSecurityDescriptor` yet.</maml:para>
|
|
<maml:para>The `Path` parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem` binds to it. Relative paths are resolved against the current location. Unlike `Get-NTFSSecurityDescriptor`, this cmdlet does not fall back to the current location: when you omit `-Path`, it returns nothing.</maml:para>
|
|
<maml:para>Every path is processed on its own. When a path does not exist or its owner cannot be read, the cmdlet writes a non-terminating error and continues with the next path.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSOwner</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose owner you want to read. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet returns nothing.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSOwner</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the owner from the descriptor in memory instead of from the file system, which includes an owner that `Set-NTFSOwner -SecurityDescriptor` changed but that has not been written back yet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose owner you want to read. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet returns nothing.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the owner from the descriptor in memory instead of from the file system, which includes an owner that `Set-NTFSOwner -SecurityDescriptor` changed but that has not been written back yet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more paths to this cmdlet. Objects that expose a `Path` or `FullName` property, such as the output of `Get-ChildItem2` and `Get-Item2`, bind to `-Path` as well.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe security descriptors that `Get-NTFSSecurityDescriptor` returned to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemOwner</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns one object per item. It contains the item itself in `Item`, an `Alphaleonis.Win32.Filesystem.FileInfo` or `DirectoryInfo`, the path of the item in `FullName`, and the owning account in `Owner` and `Account`, both of type `Security2.IdentityReference2`.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>The module also adds an `Owner` script property to `System.IO.FileInfo` and `System.IO.DirectoryInfo`, so `(Get-Item C:\Data).Owner` returns the owning account as a `Security2.IdentityReference2` object as well.</maml:para>
|
|
<maml:para>If the owner of an item cannot be read because access is denied, the cmdlet writes the non-terminating error `ReadSecurityError` with the category `PermissionDenied` and continues with the next path. It does not take ownership of the item, which would replace the owner that it reports.</maml:para>
|
|
<maml:para>Before 5.0.0, a command that stopped the pipeline early, such as `Select-Object -First 1`, made the cmdlet write a `ReadSecurityError` with the message "The pipeline has been stopped" for every path.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------------- Example 1: Get the owner of a folder -------------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSOwner -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command reads the owner of the `C:\Data` folder and returns a single `FileSystemOwner` object.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--- Example 2: Get the owner of every item in a folder tree ---</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command pipes every file and folder below `C:\Data` to `Get-NTFSOwner`. The items bind to `-Path` through the `FullName` alias, so the cmdlet returns one result per item.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-- Example 3: Find items that a specific account does not own --</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner | Where-Object { $_.Account.AccountName -ne 'CONTOSO\JohnDoe' }</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the items below `C:\Data` whose owner is not `CONTOSO\JohnDoe`. The `AccountName` property holds the resolved account name; compare the `Sid` property instead when an account cannot be resolved.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 4: Read the owner from a security descriptor in memory</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Get-NTFSOwner -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first command reads the security descriptor of `C:\Data` into a variable. The second command returns the owner that is stored in that descriptor without reading the file system again.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSOwner.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSOwner</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSSecurityDescriptor</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSSecurityDescriptor</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the security descriptor of a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-NTFSSecurityDescriptor` cmdlet reads the security descriptor of a file or folder into memory and returns it as a `Security2.FileSystemSecurity2` object. A security descriptor holds the owner of an item, its primary group, the discretionary access control list (DACL) that grants or denies access, and the system access control list (SACL) that controls auditing.</maml:para>
|
|
<maml:para>The returned object is the starting point of the security descriptor workflow. Many cmdlets of the module accept it through a `-SecurityDescriptor` parameter and then change the copy in memory instead of the file system, among them `Add-NTFSAccess`, `Remove-NTFSAccess`, `Clear-NTFSAccess`, `Add-NTFSAudit`, `Remove-NTFSAudit`, `Clear-NTFSAudit`, `Set-NTFSInheritance`, `Enable-NTFSAccessInheritance`, `Disable-NTFSAccessInheritance`, and `Set-NTFSOwner`. Nothing reaches the disk until you pass the descriptor to `Set-NTFSSecurityDescriptor`, which makes it possible to collect several changes and apply them in a single write; that cmdlet writes only the sections that changed. Discard the variable to discard the changes.</maml:para>
|
|
<maml:para>The cmdlet reads all sections of the descriptor. When that fails, for example because the session may not read the SACL, it falls back to the access, owner, and group sections, and then to the access section alone. When the cmdlet reads the SACL, it reads the DACL in a separate call, so that the inherited access entries keep their inherited flag. Before 5.0.0, it read the DACL together with the SACL, and Windows could return the inherited entries without that flag; a descriptor written back then stored them as explicit entries. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem` binds to it. Relative paths are resolved against the current location, and when you omit `-Path` entirely, the cmdlet returns the descriptor of the current location.</maml:para>
|
|
<maml:para>Every path is processed on its own. When a path does not exist, the cmdlet writes a non-terminating error and continues with the next one. When reading the descriptor fails because access is denied, the cmdlet takes ownership of the item with the account of the current session, reads the descriptor, and restores the previous owner; if that fails as well, it writes a non-terminating error.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSSecurityDescriptor</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose security descriptor you want to read. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet uses the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose security descriptor you want to read. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet uses the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more paths to this cmdlet. Objects that expose a `Path` or `FullName` property, such as the output of `Get-ChildItem2` and `Get-Item2`, bind to `-Path` as well.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns one object per item. It wraps the item in `Item` and the underlying `System.Security.AccessControl.FileSecurity` or `DirectorySecurity` object in `SecurityDescriptor`, and it exposes the path in `FullName`, the item name in `Name`, and whether the item is a file in `IsFile`.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>`Add-NTFSAccess`, `Remove-NTFSAccess`, `Add-NTFSAudit`, and `Remove-NTFSAudit` offer two parameter sets for a security descriptor, one with `-AppliesTo` and one with `-InheritanceFlags` and `-PropagationFlags`. Specify at least one of those parameters when you pass a descriptor to them; otherwise PowerShell cannot decide which parameter set to use and reports an ambiguous parameter set.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------ Example 1: Get the security descriptor of a folder ------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSSecurityDescriptor -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command reads the security descriptor of `C:\Data` and returns it as a `FileSystemSecurity2` object.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 2: Collect several changes and apply them in one write</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles
|
|
PS C:\> Remove-NTFSAccess -SecurityDescriptor $sd -Account 'BUILTIN\Users' -AccessRights ReadAndExecute -AppliesTo ThisFolderSubfoldersAndFiles
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first three commands read the descriptor of `C:\Data` and change its access control list in memory, which leaves the folder untouched. The last command writes both changes to the folder at once.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 3: Inspect the access control list of the descriptor before writing it</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights FullControl -AppliesTo ThisFolderOnly
|
|
PS C:\> Get-NTFSAccess -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The third command lists the access control entries of the descriptor in memory, which already include the permissions that were just added. Compare the result with `Get-NTFSAccess -Path C:\Data` to see that the folder itself has not changed yet.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 4: Get the security descriptor of the current location</maml:title>
|
|
<dev:code>PS C:\> Set-Location -Path C:\Data
|
|
PS C:\Data> Get-NTFSSecurityDescriptor</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Without `-Path`, the cmdlet returns the security descriptor of the current location.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSSecurityDescriptor.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSOwner</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-NTFSSimpleAccess</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>NTFSSimpleAccess</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the permissions of folders reduced to read, write, and delete.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>Reads the access control entries of folders and writes them as `Security2.SimpleFileSystemAccessRule` objects whose rights are reduced to the three values `Read`, `Write`, and `Delete`. Reading rights such as `ReadAttributes` or `Traverse` become `Read`, changing rights such as `CreateFiles`, `WriteAttributes`, `ChangePermissions`, or `TakeOwnership` become `Write`, and `Delete` and `DeleteSubdirectoriesAndFiles` become `Delete`; `FullControl` becomes all three. The result answers who may read, change, or delete in a folder without the detail of the full ACL.</maml:para>
|
|
<maml:para>The second simplification is that repetitions are left out. The first folder the cmdlet processes is reported with all of its entries, and for every folder that follows only the entries are reported that its parent folder does not already cover. An entry is covered when the parent has an entry for the same account and access type that includes at least the same simple rights. This makes a recursive listing show where permissions actually change instead of repeating the inherited ones on every level, and it requires the parent folder to be processed before its children, which `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` do by default.</maml:para>
|
|
<maml:para>`-IncludeRootFolder` is on by default and adds the parent folder of the first path as the baseline for the comparison, which is why the first result usually belongs to the folder above the one that was asked for. Use `-IncludeRootFolder:$false` to start the comparison at the first path itself.</maml:para>
|
|
<maml:para>The cmdlet only processes folders; a path that points to a file is skipped silently, while the security descriptor of a file is reported. Relative paths are resolved against the current location, and the current location is used when `-Path` is omitted. `-ExcludeInherited`, `-ExcludeExplicit`, and `-Account` work as in `Get-NTFSAccess`. With `-SecurityDescriptor`, the cmdlet reports the entries of a `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned, without comparing them with a parent folder.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSSimpleAccess</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more folders whose permissions are reported. Paths that point to a file are skipped. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose entries are returned. When you omit the parameter, the cmdlet returns the entries of all accounts.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access control entries defined on the folder itself are omitted and only the inherited entries are reported.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the inherited access control entries are omitted and only the entries defined on the folder itself are reported.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>IncludeRootFolder</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the parent folder of the first path is reported as well and serves as the baseline the following folders are compared against. This behavior is on by default; use `-IncludeRootFolder:$false` to start with the first path itself.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-NTFSSimpleAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reports the entries of the in-memory objects instead of reading the items again.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose entries are returned. When you omit the parameter, the cmdlet returns the entries of all accounts.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access control entries defined on the folder itself are omitted and only the inherited entries are reported.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the inherited access control entries are omitted and only the entries defined on the folder itself are reported.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>IncludeRootFolder</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the parent folder of the first path is reported as well and serves as the baseline the following folders are compared against. This behavior is on by default; use `-IncludeRootFolder:$false` to start with the first path itself.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account whose entries are returned. When you omit the parameter, the cmdlet returns the entries of all accounts.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeExplicit</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the access control entries defined on the folder itself are omitted and only the inherited entries are reported.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>ExcludeInherited</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the inherited access control entries are omitted and only the entries defined on the folder itself are reported.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>IncludeRootFolder</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the parent folder of the first path is reported as well and serves as the baseline the following folders are compared against. This behavior is on by default; use `-IncludeRootFolder:$false` to start with the first path itself.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more folders whose permissions are reported. Paths that point to a file are skipped. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reports the entries of the in-memory objects instead of reading the items again.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more paths of folders, piped by value or by the property `FullName`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>An account name or a SID string binds to `-Account`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.SimpleFileSystemAccessRule</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One object per reported entry, with the folder in `FullName` and `Name`, the account in `Identity`, the access type in `AccessControlType`, and the simplified rights `Read`, `Write`, and `Delete` in `AccessRights`. The default view is a table with the `Account`, `Access Rights`, and `Type` columns, grouped by folder.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>The simplified rights hide which exact rights an account holds. Use `Get-NTFSAccess` when you need the full access control entry, and `Get-NTFSEffectiveAccess` when you need the rights that result from all entries together.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet ignored `-Account` and `-SecurityDescriptor`, and its output had no table view. It also showed no rights for an entry that grants only `ReadData`, which other tools than .NET create, and it left out the parent folder of a relative path with a single folder name, such as `Data`.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------ Example 1: Get the simple permissions of a folder ------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSSimpleAccess -Path C:\Data</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command shows who may read, write, or delete in `C:\Data`. The permissions of the parent folder are shown first, because `-IncludeRootFolder` is on by default.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----- Example 2: Find the folders whose permissions differ -----</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSSimpleAccess</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command walks the folder tree below `C:\Data` and reports only the entries that a folder does not already inherit in the same form from its parent, which reveals where permissions were added or broken.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 3: Report only the permissions defined on the folder itself</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSSimpleAccess -Path C:\Data -ExcludeInherited -IncludeRootFolder:$false</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command shows the explicit entries of `C:\Data` in simplified form and leaves both the inherited entries and the parent folder out of the result.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSSimpleAccess.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSEffectiveAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Get-Privileges</command:name>
|
|
<command:verb>Get</command:verb>
|
|
<command:noun>Privileges</command:noun>
|
|
<maml:description>
|
|
<maml:para>Gets the privileges in the access token of the current PowerShell process.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Get-Privileges` cmdlet reads the access token of the current PowerShell process and returns one `ProcessPrivileges.PrivilegeAndAttributes` object for every privilege the token contains. Each object names the privilege in the `Privilege` property, the raw token attributes in `PrivilegeAttributes`, and the resulting state in `PrivilegeState`, which is `Enabled`, `Disabled`, or `Removed`.</maml:para>
|
|
<maml:para>The cmdlet only reads; it never changes a privilege. Use it to check whether the four privileges that NTFSSecurity depends on (Backup, Restore, Take Ownership, and Security) are available before you run the file system cmdlets, and to confirm the result of `Enable-Privileges` and `Disable-Privileges`.</maml:para>
|
|
<maml:para>Only privileges that the account holds in this session appear in the list; privileges the account does not have are not listed at all. Because Windows removes the administrative privileges from the token of a session that is not elevated, a standard session returns a much shorter list than an elevated one.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Get-Privileges</maml:name>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters />
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>None</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>This cmdlet does not accept pipeline input.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>ProcessPrivileges.PrivilegeAndAttributes</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns one object per privilege in the token of the current process. `Privilege` names the privilege, `PrivilegeAttributes` holds the token attributes as a combination of `Disabled`, `EnabledByDefault`, `Enabled`, `Removed`, and `UsedForAccess`, and `PrivilegeState` reduces those attributes to `Enabled`, `Disabled`, or `Removed`.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>This cmdlet reads the access token of the current PowerShell process only. It reports no privileges of other processes or sessions, and it changes nothing. Use `Enable-Privileges` and `Disable-Privileges` to change the state of the file system privileges.</maml:para>
|
|
<maml:para>Unlike the file system cmdlets of the module, `Get-Privileges` is not affected by the `EnablePrivileges` setting in the `PrivateData` section of NTFSSecurity.psd1 and never enables a privilege on its own.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>---- Example 1: List the privileges of the current session ----</maml:title>
|
|
<dev:code>PS C:\> Get-Privileges</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns every privilege in the access token of the current PowerShell process together with its state.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 2: List only the privileges that are currently enabled</maml:title>
|
|
<dev:code>PS C:\> Get-Privileges | Where-Object { $_.PrivilegeState -eq 'Enabled' }</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command filters the result down to the privileges that are in use, which is a short list in a session that has not enabled anything.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---- Example 3: Check the privileges that NTFSSecurity uses ----</maml:title>
|
|
<dev:code>PS C:\> Get-Privileges | Where-Object { $_.Privilege -in 'Backup', 'Restore', 'TakeOwnership', 'Security' }</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command shows the four file system privileges. An empty result means that the session does not hold them, which is the normal case outside an elevated session.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-- Example 4: Test a single privilege before taking ownership --</maml:title>
|
|
<dev:code>PS C:\> (Get-Privileges | Where-Object { $_.Privilege -eq 'TakeOwnership' }).PrivilegeState</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns the state of the Take Ownership privilege alone and returns nothing when the session does not hold it.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-Privileges.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-Privileges</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-Privileges</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSOwner</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Move-Item2</command:name>
|
|
<command:verb>Move</command:verb>
|
|
<command:noun>Item2</command:noun>
|
|
<maml:description>
|
|
<maml:para>Moves a file or folder to another location, including paths longer than 260 characters.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Move-Item2` cmdlet moves the items in `-Path` to the location in `-Destination`. It is the long-path counterpart of the built-in `Move-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), so source and destination may be longer than the 260-character `MAX_PATH` limit. Files and folders can both be moved, and a folder is moved with everything it contains.</maml:para>
|
|
<maml:para>How `-Destination` is interpreted depends on what is already there. If the value names an existing folder, the cmdlet keeps the name of the source item and moves it into that folder. In every other case the value is the full path of the new item, which lets you move and rename in one step, or rename an item in place. `-Destination` is resolved against the current location once, when the cmdlet starts.</maml:para>
|
|
<maml:para>Without `-Force`, the cmdlet checks whether a file or folder already exists at the destination and writes a `DestinationFileAlreadyExists` error instead of overwriting it; the move itself then runs with the `CopyAllowed` option, which allows a file to move to a different volume. With `-WhatIf`, the cmdlet names an existing destination in a verbose message instead; before 5.0.0, it wrote the error also with `-WhatIf`. With `-Force`, the move runs with the `ReplaceExisting` option and overwrites an existing destination item. The folder that is to contain the moved item must exist; otherwise the cmdlet writes an error that names that folder.</maml:para>
|
|
<maml:para>The cmdlet supports `-WhatIf` and `-Confirm`, and it writes nothing to the pipeline unless you specify `-PassThru $true`.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Move-Item2</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more items to move. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none">
|
|
<maml:name>Destination</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the target of the move operation. If the value names an existing folder, the cmdlet moves the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
|
|
<maml:name>Confirm</maml:name>
|
|
<maml:description>
|
|
<maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Force</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet replaces an existing destination item. Without `-Force`, an existing file or folder at the destination causes the error `DestinationFileAlreadyExists` and the item is not moved.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the cmdlet returns an object for each item that it moved. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. The returned object describes the item at its new location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
|
|
<maml:name>WhatIf</maml:name>
|
|
<maml:description>
|
|
<maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
|
|
<maml:name>Confirm</maml:name>
|
|
<maml:description>
|
|
<maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none">
|
|
<maml:name>Destination</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the target of the move operation. If the value names an existing folder, the cmdlet moves the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Force</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet replaces an existing destination item. Without `-Force`, an existing file or folder at the destination causes the error `DestinationFileAlreadyExists` and the item is not moved.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the cmdlet returns an object for each item that it moved. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. The returned object describes the item at its new location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more items to move. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
|
|
<maml:name>WhatIf</maml:name>
|
|
<maml:description>
|
|
<maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe an object that has a `Destination` property to supply the target of the move operation.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.FileInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>By default this cmdlet returns nothing. With `-PassThru $true` it returns a file object for each file that it moved, pointing at the new location.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.DirectoryInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru $true` the cmdlet returns a folder object for each folder that it moved, pointing at the new location.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>`Move-Item2` moves through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it handles source and destination paths that exceed the 260-character `MAX_PATH` limit of the built-in `Move-Item` cmdlet.</maml:para>
|
|
<maml:para>Before 5.0.0, `-PassThru` also wrote the item when `-WhatIf` or a declined confirmation skipped the operation.</maml:para>
|
|
<maml:para>The cmdlet chooses between two mutually exclusive move options. Without `-Force` it moves with `CopyAllowed`, which permits a file to cross volume boundaries because Windows then copies and deletes it. With `-Force` it moves with `ReplaceExisting`, which overwrites the destination but does not request `CopyAllowed`, so a move across volumes can fail when `-Force` is specified. A folder can't move to another volume: the cmdlet writes a `MoveError` and leaves the folder in place, so copy it with `Copy-Item2` and remove it with `Remove-Item2` instead.</maml:para>
|
|
<maml:para>If a path in `-Path` does not exist, a file or folder exists at the destination and `-Force` is missing, or the folder that is to contain the moved item does not exist, the cmdlet writes a non-terminating error and continues with the next path. Before 5.0.0, it skipped the remaining paths that were passed in the same call. Before 5.0.0, it also reported an existing destination folder as a `MoveError`, and a missing destination folder as a `DirectoryNotFoundException` that named the source item ( #21 (https://github.com/raandree/NTFSSecurity/issues/21)).</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------------- Example 1: Move a file into a folder -------------</maml:title>
|
|
<dev:code>PS C:\> Move-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Moves `report.docx` into the existing folder `C:\Data\Archive`, where it keeps its name.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------------ Example 2: Rename an item ------------------</maml:title>
|
|
<dev:code>PS C:\> Move-Item2 -Path C:\Data\Archive\report.docx -Destination C:\Data\Archive\report-2026.docx</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Moves the file to a new path inside the same folder, which renames it.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-------- Example 3: Move a folder with a very long path --------</maml:title>
|
|
<dev:code>PS C:\> Move-Item2 -Path C:\Data\Projects\Archive\2026\Q1\Reports\Regional\Northwest -Destination C:\Data\Archive\Northwest -PassThru $true</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Moves the folder and everything it contains, even when the paths below it exceed 260 characters, and returns the folder object at its new location.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------- Example 4: Preview a move operation -------------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -File -Filter '*.tmp' | Move-Item2 -Destination C:\Data\Temp -WhatIf</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Shows which temporary files the cmdlet would move into `C:\Data\Temp` without moving anything. Remove `-WhatIf` to carry the operation out.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Move-Item2.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Copy-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Test-Path2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>New-NTFSHardLink</command:name>
|
|
<command:verb>New</command:verb>
|
|
<command:noun>NTFSHardLink</command:noun>
|
|
<maml:description>
|
|
<maml:para>Creates a hard link to an existing file.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `New-NTFSHardLink` cmdlet gives an existing file an additional name. `-Path` is the new hard link that the cmdlet creates, and `-Target` is the existing file that the new link refers to. Read the command as "create Path , which points to Target ".</maml:para>
|
|
<maml:para>The cmdlet validates both ends before it creates the link. `-Path` must not exist yet, so the cmdlet never overwrites an existing file, and `-Target` must exist and must be a file. A folder as `-Target` is rejected, because NTFS supports hard links for files only. Relative paths are resolved against the current location.</maml:para>
|
|
<maml:para>After the link is created, both names refer to the same data on the volume. Writing through one name changes what the other name returns, and the file is only released when its last name is deleted.</maml:para>
|
|
<maml:para>By default the cmdlet produces no output. With `-PassThru` it returns one object for every hard link that the file has after the operation, which includes the original name and the new link, not just the link that was created.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>New-NTFSHardLink</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of the new hard link that the cmdlet creates. The path must not exist yet, and it must be on the same NTFS volume as `-Target`. Relative paths are resolved against the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="2" aliases="none">
|
|
<maml:name>Target</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of the existing file that the new link refers to. The target must exist and must be a file; folders are rejected, because NTFS supports hard links for files only.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns an object for every hard link of the file after the new link has been created, including the names that already existed. By default, this cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns an object for every hard link of the file after the new link has been created, including the names that already existed. By default, this cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of the new hard link that the cmdlet creates. The path must not exist yet, and it must be on the same NTFS volume as `-Target`. Relative paths are resolved against the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="2" aliases="none">
|
|
<maml:name>Target</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of the existing file that the new link refers to. The target must exist and must be a file; folders are rejected, because NTFS supports hard links for files only.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pass the path of the new link and the path of the target as strings.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.FileInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru`, the cmdlet writes one file object per hard link of the file, extended with a `Mode` property that renders the file attributes in the same notation as `Get-ChildItem2`. Without `-PassThru`, the cmdlet writes nothing.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.DirectoryInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet never writes folder objects, because hard links are supported for files only.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>Windows supports hard links only for files on the same NTFS volume. A link that points to a file on another volume, or a target on a file system that does not implement hard links, cannot be created.</maml:para>
|
|
<maml:para>The cmdlet creates hard links on a network share as well, but Windows can't list the names of a file there. With `-PassThru` on a share, the cmdlet creates the link and writes a non-terminating `GetHardLinkError` with the message "The request is not supported" instead of the objects. Before 5.0.0, it stopped with a terminating error after it had created the link.</maml:para>
|
|
<maml:para>The cmdlet does not overwrite anything. If `-Path` already exists, or if `-Target` is missing or is a folder, the cmdlet reports an error and leaves the file system unchanged.</maml:para>
|
|
<maml:para>Because all names of a file share the same data, the number of hard links is a property of the file, not of an individual name. Use `Get-NTFSHardLink` to list them, and delete a link with `Remove-Item2` or `Remove-Item`, which removes only that name as long as other names remain.</maml:para>
|
|
<maml:para>Before 5.0.0, the error for a missing `-Target` said "The target path exist", the opposite of the cause.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------------- Example 1: Give a file a second name -------------</maml:title>
|
|
<dev:code>PS C:\> New-NTFSHardLink -Path C:\Data\Report-Current.txt -Target C:\Data\Report-2026.txt</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command creates the new hard link `Report-Current.txt` for the existing file `Report-2026.txt`. Both names now refer to the same data, and no second copy of the content is stored.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--- Example 2: Create a hard link with positional parameters ---</maml:title>
|
|
<dev:code>PS C:\> New-NTFSHardLink C:\Data\Archive\Report.txt C:\Data\Report.txt</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command uses the positional form of the parameters. The first position is `-Path`, the new link, and the second position is `-Target`, the existing file. Both paths are on drive C, as a hard link and its target must be on the same volume.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--- Example 3: Create a link and list all names of the file ---</maml:title>
|
|
<dev:code>PS C:\> New-NTFSHardLink -Path C:\Data\Report-Current.txt -Target C:\Data\Report-2026.txt -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command creates the link and then returns one object for every hard link of the file, so the output contains both `Report-2026.txt` and the new `Report-Current.txt`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----------------- Example 4: Verify the result -----------------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSHardLink -Path C:\Data\Report-2026.txt | Select-Object -ExpandProperty FullName</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command lists all names of the file after the link was created, which is the same information that `-PassThru` returns.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/New-NTFSHardLink.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSHardLink</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>New-NTFSSymbolicLink</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>New-NTFSSymbolicLink</command:name>
|
|
<command:verb>New</command:verb>
|
|
<command:noun>NTFSSymbolicLink</command:noun>
|
|
<maml:description>
|
|
<maml:para>Creates a symbolic link to an existing file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `New-NTFSSymbolicLink` cmdlet creates a symbolic link that redirects to another file or folder. `-Path` is the new link that the cmdlet creates, and `-Target` is the existing item that the link points to. Read the command as "create Path , which points to Target ".</maml:para>
|
|
<maml:para>The cmdlet inspects the target first and creates a file symbolic link when the target is a file and a directory symbolic link when the target is a folder, so you do not select the link type yourself. `-Target` must exist when the link is created, and `-Path` must not exist yet, so the cmdlet never overwrites an existing item.</maml:para>
|
|
<maml:para>Relative paths are resolved against the current location before the link is created, which means that the link always stores an absolute target path.</maml:para>
|
|
<maml:para>By default the cmdlet produces no output. With `-PassThru` it returns an object for the new link: a file object for a link to a file, and a folder object for a link to a folder.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>New-NTFSSymbolicLink</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of the new symbolic link that the cmdlet creates. The path must not exist yet. Relative paths are resolved against the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="2" aliases="none">
|
|
<maml:name>Target</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of the existing file or folder that the new link points to. The target must exist when the link is created and determines whether the cmdlet creates a file symbolic link or a directory symbolic link. Relative paths are resolved against the current location, so the link stores an absolute target path.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns an object for the new link. By default, this cmdlet produces no output. The returned object is a file object for a link to a file and a folder object for a link to a folder.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns an object for the new link. By default, this cmdlet produces no output. The returned object is a file object for a link to a file and a folder object for a link to a folder.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of the new symbolic link that the cmdlet creates. The path must not exist yet. Relative paths are resolved against the current location.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="2" aliases="none">
|
|
<maml:name>Target</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of the existing file or folder that the new link points to. The target must exist when the link is created and determines whether the cmdlet creates a file symbolic link or a directory symbolic link. Relative paths are resolved against the current location, so the link stores an absolute target path.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pass the path of the new link and the path of the target as strings.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.FileInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru`, the cmdlet writes a file object for a new link to a file. Without `-PassThru`, the cmdlet writes nothing.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.DirectoryInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru`, the cmdlet writes a folder object for a new link to a folder. Before 5.0.0, it wrote a file object for those links as well.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>Creating a symbolic link on Windows requires the "Create symbolic links" user right, `SeCreateSymbolicLinkPrivilege`, which is granted to the Administrators group by default. Without that right, Windows rejects the operation with error 1314, "A required privilege is not held by the client", so run the cmdlet from an elevated session or grant the right to the account. Windows Developer Mode doesn't change this: it lets accounts without that right create symbolic links only in programs that request it, such as `mklink`, and the cmdlet doesn't.</maml:para>
|
|
<maml:para>Unlike a hard link, a symbolic link is a separate file system entry that stores a path, so it can point to an item on another volume and the link and its target can be managed independently. The cmdlet still requires the target to exist at the moment the link is created. If the target is removed later, the link remains and stops resolving.</maml:para>
|
|
<maml:para>Deleting a symbolic link removes the link only and leaves the target untouched. Delete a directory symbolic link as a link rather than recursively, so that the content of the target folder is not affected.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>--------- Example 1: Create a symbolic link to a file ---------</maml:title>
|
|
<dev:code>PS C:\> New-NTFSSymbolicLink -Path C:\Data\Report-Current.txt -Target C:\Data\Archive\Report-2026.txt</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command creates the symbolic link `Report-Current.txt`, which redirects to the existing file `Report-2026.txt`. Because the target is a file, the cmdlet creates a file symbolic link.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-------- Example 2: Create a symbolic link to a folder --------</maml:title>
|
|
<dev:code>PS C:\> New-NTFSSymbolicLink -Path C:\Data\Current -Target C:\Data\Archive\2026</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command creates the symbolic link `C:\Data\Current`, which redirects to the existing folder `C:\Data\Archive\2026`. Because the target is a folder, the cmdlet creates a directory symbolic link, and paths below `C:\Data\Current` resolve to the corresponding items in the target folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------ Example 3: Create a link and return it ------------</maml:title>
|
|
<dev:code>PS C:\> New-NTFSSymbolicLink -Path C:\Data\Current -Target C:\Data\Archive\2026 -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command creates the link and returns an object for the new link, which you can use to confirm the result in a script.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----------- Example 4: Verify that the link resolves -----------</maml:title>
|
|
<dev:code>PS C:\> Test-Path2 -Path C:\Data\Current\Report.txt -PathType Leaf</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command tests a path that leads through the symbolic link. It returns `$true` when the link resolves and the file exists in the target folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/New-NTFSSymbolicLink.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>New-NTFSHardLink</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSHardLink</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Test-Path2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Remove-Item2</command:name>
|
|
<command:verb>Remove</command:verb>
|
|
<command:noun>Item2</command:noun>
|
|
<maml:description>
|
|
<maml:para>Deletes a file or folder, including paths longer than 260 characters.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Remove-Item2` cmdlet deletes the files and folders in `-Path`. It is the long-path counterpart of the built-in `Remove-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), so it also deletes items whose path exceeds the 260-character `MAX_PATH` limit. The items are deleted permanently and are not moved to the Recycle Bin.</maml:para>
|
|
<maml:para>Relative paths and the `.` and `..` notations are resolved against the current location, and wildcard characters are not supported. `-Path` has no default value: if you omit it, the cmdlet does nothing. Use `-Recurse` to delete a folder that is not empty and `-Force` to delete items that have the read-only attribute.</maml:para>
|
|
<maml:para>The cmdlet supports `-WhatIf` and `-Confirm`, and it writes nothing to the pipeline unless you specify `-PassThru`.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Remove-Item2</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more items to delete. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter has no default value, so the cmdlet deletes nothing if you omit it. It accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
|
|
<maml:name>Confirm</maml:name>
|
|
<maml:description>
|
|
<maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Force</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet also deletes items that have the read-only attribute. Without `-Force`, a read-only item causes a `DeleteError`. Combine `-Force` with `-Recurse` to delete a folder that contains read-only files.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="PassThur">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns an object for each item that it deleted. By default, the cmdlet produces no output. The object describes a path that no longer exists, so use it for logging rather than for further file operations. `-PassThur`, the name of this parameter in NTFSSecurity 4.2.6 and earlier, still works as an alias.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Recurse</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet deletes a folder together with everything it contains. Without `-Recurse`, a folder that is not empty causes a `DeleteError`. The parameter has no effect on files.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
|
|
<maml:name>WhatIf</maml:name>
|
|
<maml:description>
|
|
<maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
|
|
<maml:name>Confirm</maml:name>
|
|
<maml:description>
|
|
<maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Force</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet also deletes items that have the read-only attribute. Without `-Force`, a read-only item causes a `DeleteError`. Combine `-Force` with `-Recurse` to delete a folder that contains read-only files.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="PassThur">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns an object for each item that it deleted. By default, the cmdlet produces no output. The object describes a path that no longer exists, so use it for logging rather than for further file operations. `-PassThur`, the name of this parameter in NTFSSecurity 4.2.6 and earlier, still works as an alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more items to delete. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter has no default value, so the cmdlet deletes nothing if you omit it. It accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>Recurse</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet deletes a folder together with everything it contains. Without `-Recurse`, a folder that is not empty causes a `DeleteError`. The parameter has no effect on files.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
|
|
<maml:name>WhatIf</maml:name>
|
|
<maml:description>
|
|
<maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.FileInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>By default this cmdlet returns nothing. With `-PassThru` it returns a file object for each file that it deleted.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Alphaleonis.Win32.Filesystem.DirectoryInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru` the cmdlet returns a folder object for each folder that it deleted.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>`Remove-Item2` deletes through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it reaches items whose path exceeds the 260-character `MAX_PATH` limit of the built-in `Remove-Item` cmdlet. Deletion is permanent; the cmdlet does not use the Recycle Bin.</maml:para>
|
|
<maml:para>Before 5.0.0, `-PassThru` also wrote the item when `-WhatIf` or a declined confirmation skipped the operation.</maml:para>
|
|
<maml:para>The module defines the aliases `rm2` and `del2` for this cmdlet.</maml:para>
|
|
<maml:para>A path that does not exist causes the error `FileNotFound`, and a deletion that the file system rejects causes a `DeleteError`. In both cases the cmdlet continues with the next path. Before 5.0.0, a path that did not exist made the cmdlet skip the remaining paths that were passed in the same call.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------------------- Example 1: Delete a file -------------------</maml:title>
|
|
<dev:code>PS C:\> Remove-Item2 -Path C:\Data\report.docx</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Deletes a single file. If the file is read-only, the command fails with a `DeleteError` until you add `-Force`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----- Example 2: Delete a folder tree with very long paths -----</maml:title>
|
|
<dev:code>PS C:\> Remove-Item2 -Path C:\Data\Projects\Archive -Recurse -Force</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Deletes the folder with everything it contains, including read-only files and files whose path is too long for the built-in `Remove-Item` cmdlet.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----------- Example 3: Preview what would be deleted -----------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -File -Filter '*.tmp' | Remove-Item2 -WhatIf</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Lists every temporary file below `C:\Data` and shows which of them the cmdlet would delete. Remove `-WhatIf` to delete them.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 4: Delete items and keep a record of them ------</maml:title>
|
|
<dev:code>PS C:\> rm2 -Path C:\Data\Logs\old.log -PassThru | Select-Object -ExpandProperty FullName</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>Uses the `rm2` alias and returns the object of the deleted file, from which the command takes the full path for a log. Since the item no longer exists, only its path information is still meaningful; properties such as `Length` are empty.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Remove-Item2.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Copy-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Move-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Test-Path2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Remove-NTFSAccess</command:name>
|
|
<command:verb>Remove</command:verb>
|
|
<command:noun>NTFSAccess</command:noun>
|
|
<maml:description>
|
|
<maml:para>Removes rights from the access control entries (ACEs) of a file, a folder, or a security descriptor.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>Removes the rights in `-AccessRights` from the access control entries (ACEs) of a file or a folder. An entry is addressed by the account in `-Account`, the access type in `-AccessType`, and the inheritance and propagation flags, which are given either as `-AppliesTo` or as `-InheritanceFlags` and `-PropagationFlags`.</maml:para>
|
|
<maml:para>Only the specified rights are taken away: when an entry grants more than `-AccessRights` names, the remaining rights stay in place, and the entry disappears only when all of its rights are removed. An `Allow` entry is always matched with the `Synchronize` right added to the specified rights. The flags must describe the entry as it exists on the item; when they do not, Windows splits the entry instead of removing the rights, so use the values that `Get-NTFSAccess` reports for the entry you want to change. With `-RemoveSpecific`, the cmdlet removes only an entry that matches exactly.</maml:para>
|
|
<maml:para>Inherited entries cannot be removed from the item that inherits them. Remove them from the folder named in the `InheritedFrom` property, or run `Disable-NTFSAccessInheritance` on the item first, which copies the inherited entries into it as explicit ones that this cmdlet can then remove.</maml:para>
|
|
<maml:para>The cmdlet has four parameter sets. The `Path` sets read the item from disk and write the changed DACL back immediately, while the `SD` sets change a `Security2.FileSystemSecurity2` object returned by `Get-NTFSSecurityDescriptor` in memory until `Set-NTFSSecurityDescriptor` writes it back. The `Simple` sets take `-AppliesTo`, the `Complex` sets take `-InheritanceFlags` and `-PropagationFlags`, and `PathComplex` is the default. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. All relevant parameters bind by property name, so the output of `Get-NTFSAccess` and `Get-NTFSOrphanedAccess` can be piped directly into this cmdlet. The cmdlet writes no output unless `-PassThru` is used.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Remove-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose access control entries are changed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups whose entries are changed. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">Allow</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Deny</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the entry that is addressed, in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same entry. Use the scope that `Get-NTFSAccess` shows in the "Applies to" column of the entry.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfolders</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfoldersOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnlyOneLevel</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an entry that matches the account, the access rights, the access type, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Remove-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are changed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups whose entries are changed. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">Allow</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Deny</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the entry that is addressed, in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same entry. Use the scope that `Get-NTFSAccess` shows in the "Applies to" column of the entry.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfolders</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfoldersOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnlyOneLevel</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an entry that matches the account, the access rights, the access type, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Remove-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose access control entries are changed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups whose entries are changed. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">Allow</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Deny</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the inheritance flags of the entry that is addressed. `ContainerInherit` marks an entry that child folders inherit, `ObjectInherit` marks an entry that child files inherit, and `None` marks an entry that is not inherited at all. The default is `ContainerInherit, ObjectInherit`, which is the scope `ThisFolderSubfoldersAndFiles`. Entries on files always carry `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ContainerInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ObjectInherit</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the propagation flags of the entry that is addressed. `None` marks an entry that is inherited by all levels allowed by its inheritance flags, `InheritOnly` marks an entry that does not apply to the item it is defined on, and `NoPropagateInherit` marks an entry that is only inherited by the direct children of the folder. The default is `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NoPropagateInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">InheritOnly</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an entry that matches the account, the access rights, the access type, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Remove-NTFSAccess</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are changed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups whose entries are changed. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">Allow</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Deny</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the inheritance flags of the entry that is addressed. `ContainerInherit` marks an entry that child folders inherit, `ObjectInherit` marks an entry that child files inherit, and `None` marks an entry that is not inherited at all. The default is `ContainerInherit, ObjectInherit`, which is the scope `ThisFolderSubfoldersAndFiles`. Entries on files always carry `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ContainerInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ObjectInherit</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the propagation flags of the entry that is addressed. `None` marks an entry that is inherited by all levels allowed by its inheritance flags, `InheritOnly` marks an entry that does not apply to the item it is defined on, and `NoPropagateInherit` marks an entry that is only inherited by the direct children of the folder. The default is `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NoPropagateInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">InheritOnly</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an entry that matches the account, the access rights, the access type, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="AccessControlType">
|
|
<maml:name>AccessType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">AccessControlType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AccessControlType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Allow</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more accounts or groups whose entries are changed. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the entry that is addressed, in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same entry. Use the scope that `Get-NTFSAccess` shows in the "Applies to" column of the entry.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the inheritance flags of the entry that is addressed. `ContainerInherit` marks an entry that child folders inherit, `ObjectInherit` marks an entry that child files inherit, and `None` marks an entry that is not inherited at all. The default is `ContainerInherit, ObjectInherit`, which is the scope `ThisFolderSubfoldersAndFiles`. Entries on files always carry `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose access control entries are changed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the propagation flags of the entry that is addressed. `None` marks an entry that is inherited by all levels allowed by its inheritance flags, `InheritOnly` marks an entry that does not apply to the item it is defined on, and `NoPropagateInherit` marks an entry that is only inherited by the direct children of the folder. The default is `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are changed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an entry that matches the account, the access rights, the access type, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more paths of files or folders, piped by value or by the property `FullName`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>One or more security descriptors returned by `Get-NTFSSecurityDescriptor`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The accounts whose entries are changed, bound from a property named `Account`, `IdentityReference`, or `ID`. The output of `Get-NTFSAccess` and `Get-NTFSOrphanedAccess` supplies `Account`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemRights2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The rights to remove, piped by the property `AccessRights` or `FileSystemRights`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.AccessControlType</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The type of the entry, piped by the property `AccessType` or `AccessControlType`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.InheritanceFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The inheritance flags of the entry, piped by the property `InheritanceFlags` in the `Complex` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.PropagationFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The propagation flags of the entry, piped by the property `PropagationFlags` in the `Complex` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.ApplyTo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The scope of the entry, piped by the property `AppliesTo` in the `Simple` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemAccessRule2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>With `-PassThru`, the cmdlet writes all access control entries, explicit and inherited, of every item it changed; an item it could not change produces only an error. Before 5.0.0, `-PassThru` also wrote the unchanged entries of such an item. Without `-PassThru` it writes nothing.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>If the ACL of an item cannot be written because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them.</maml:para>
|
|
<maml:para>Removing rights from an entry that does not exist is not an error; the cmdlet leaves the ACL unchanged.</maml:para>
|
|
<maml:para>In the `Path` parameter sets, the cmdlet writes only the DACL of the item and leaves its owner, its group, and its SACL as they are. Before 5.0.0, it could also write the owner back, which failed with error 1307, "This security ID may not be assigned as the owner of this object", when the account may not assign that owner, such as on some file servers.</maml:para>
|
|
<maml:para>An entry with a generic right, such as `GenericAll`, can be removed, for example by piping it from `Get-NTFSAccess`. Windows keeps generic rights in the inherit-only entries of folders. Before 5.0.0, the cmdlet failed for such an entry with the error "The value '269484032' is not valid for this usage of the type FileSystemRights".</maml:para>
|
|
<maml:para>Before 5.0.0, the `-RemoveSpecific` switch was missing, although version 4.1 had introduced it.</maml:para>
|
|
<maml:para>A path that does not exist produces the non-terminating error `ReadFileError`, and the cmdlet continues with the next path. Before 5.0.0, the cmdlet also wrote a misleading `RemoveAceError` for that path, and with `-PassThru` it stopped with a `NullReferenceException`.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>--------- Example 1: Remove a permission from a folder ---------</maml:title>
|
|
<dev:code>PS C:\> Remove-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -AccessRights Modify</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes the modify rights of an account from `C:\Data`. The entry is matched with the default values of the remaining parameters, which are the access type `Allow` and the inheritance flags `ContainerInherit, ObjectInherit` with no propagation flags.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>-- Example 2: Take a single right away from an existing entry --</maml:title>
|
|
<dev:code>PS C:\> Remove-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights DeleteSubdirectoriesAndFiles -AppliesTo ThisFolderSubfoldersAndFiles</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes one right from the entry of a domain group and leaves the other rights of that entry untouched.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>--- Example 3: Remove all explicit permissions of an account ---</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -ExcludeInherited | Remove-NTFSAccess</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes every access control entry that was defined for an account on `C:\Data`. The piped objects supply the path, the account, the rights, the access type, and the flags, so each entry is matched exactly as it exists.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---- Example 4: Clean up orphaned entries in a folder tree ----</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess -ExcludeInherited | Remove-NTFSAccess</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes the access control entries of deleted accounts from all items below `C:\Data`. `-ExcludeInherited` makes sure that each entry is removed where it is defined instead of where it is inherited.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Remove-NTFSAccess.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Clear-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSOrphanedAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Remove-NTFSAudit</command:name>
|
|
<command:verb>Remove</command:verb>
|
|
<command:noun>NTFSAudit</command:noun>
|
|
<maml:description>
|
|
<maml:para>Removes an audit entry from a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Remove-NTFSAudit` cmdlet removes an audit entry from the system access control list (SACL) of a file or folder. The cmdlet builds an audit entry from `-Account`, `-AccessRights`, `-AuditFlags`, and the inheritance and propagation flags, and removes that entry from the SACL. The audit entries of the account are matched by their inheritance and propagation flags, and the requested access rights and audit flags are then taken away from them: an entry that audits further rights keeps those rights and disappears only when nothing is left. To remove an entry completely, pass the same values that `Get-NTFSAudit` reports for it. With `-RemoveSpecific`, the cmdlet removes only an entry that matches exactly.</maml:para>
|
|
<maml:para>Because the inheritance and propagation flags take part in the match, they must describe the entry you want to remove. `-AppliesTo ThisFolderOnly` removes an entry that is not inherited by child items, which is also the shape of every audit entry on a file, while the default of the complex parameter sets removes an entry that applies to the folder, its subfolders, and its files. An entry that an item inherits from a parent folder is stored on that parent, so remove it there, or use `Clear-NTFSAudit` with `-DisableInheritance` to drop the inherited entries on the item.</maml:para>
|
|
<maml:para>In the `PathSimple` and `PathComplex` parameter sets the cmdlet reads the security descriptor of every item in `-Path` and writes it back right away. In the `SDSimple` and `SDComplex` parameter sets it changes an in-memory `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned, and the change reaches the file system only when you pass the object to `Set-NTFSSecurityDescriptor`. `PathComplex` is the default parameter set. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets.</maml:para>
|
|
<maml:para>When you omit them, `-AuditFlags` is `Success, Failure`, `-InheritanceFlags` is `ContainerInherit, ObjectInherit`, `-PropagationFlags` is `None`. All parameters bind by property name, and `-Path` also binds by value and through its `FullName` alias, so you can pipe the output of `Get-NTFSAudit`, `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` into the cmdlet. The cmdlet writes no object unless you use `-PassThru`.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Remove-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders the audit entry is removed from. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the audit entry to remove with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. The value must describe the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. Without `-AppliesTo`, the cmdlet uses `-InheritanceFlags` and `-PropagationFlags`, whose defaults describe `ThisFolderSubfoldersAndFiles`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfolders</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfoldersOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnlyOneLevel</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Success</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Failure</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an audit entry that matches the account, the access rights, the audit flags, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights and audit flags away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Remove-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the audit entry from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the audit entry to remove with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. The value must describe the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. Without `-AppliesTo`, the cmdlet uses `-InheritanceFlags` and `-PropagationFlags`, whose defaults describe `ThisFolderSubfoldersAndFiles`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfolders</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnly</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderSubfoldersAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndSubfoldersOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ThisFolderAndFilesOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersAndFilesOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">SubfoldersOnlyOneLevel</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FilesOnlyOneLevel</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Success</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Failure</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an audit entry that matches the account, the access rights, the audit flags, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights and audit flags away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Remove-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders the audit entry is removed from. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Success</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Failure</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the inheritance flags of the audit entry to remove. `ContainerInherit` addresses an entry that child folders inherit, `ObjectInherit` an entry that child files inherit, and `None` an entry that stays on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. The flags must match the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ContainerInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ObjectInherit</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the propagation flags of the audit entry to remove. `None` addresses an entry that applies to the item itself and to all inheriting child items, `InheritOnly` an entry that applies to the child items only, and `NoPropagateInherit` an entry whose inheritance stops at the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NoPropagateInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">InheritOnly</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an audit entry that matches the account, the access rights, the audit flags, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights and audit flags away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Remove-NTFSAudit</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the audit entry from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ListDirectory</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">AppendData</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">CreateDirectories</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteExtendedAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ExecuteFile</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Traverse</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">DeleteSubdirectoriesAndFiles</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">WriteAttributes</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Write</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadPermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Read</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ReadAndExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Modify</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ChangePermissions</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">TakeOwnership</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">FullControl</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Success</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Failure</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the inheritance flags of the audit entry to remove. `ContainerInherit` addresses an entry that child folders inherit, `ObjectInherit` an entry that child files inherit, and `None` an entry that stays on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. The flags must match the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ContainerInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">ObjectInherit</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the propagation flags of the audit entry to remove. `None` addresses an entry that applies to the item itself and to all inheriting child items, `InheritOnly` an entry that applies to the child items only, and `NoPropagateInherit` an entry whose inheritance stops at the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">None</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">NoPropagateInherit</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">InheritOnly</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an audit entry that matches the account, the access rights, the audit flags, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights and audit flags away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="FileSystemRights">
|
|
<maml:name>AccessRights</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md).</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemRights2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemRights2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="IdentityReference, ID">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AppliesTo</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the scope of the audit entry to remove with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. The value must describe the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. Without `-AppliesTo`, the cmdlet uses `-InheritanceFlags` and `-PropagationFlags`, whose defaults describe `ThisFolderSubfoldersAndFiles`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">ApplyTo</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>ApplyTo</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">AuditFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>AuditFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Success, Failure</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the inheritance flags of the audit entry to remove. `ContainerInherit` addresses an entry that child folders inherit, `ObjectInherit` an entry that child files inherit, and `None` an entry that stays on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. The flags must match the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">InheritanceFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>InheritanceFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>ContainerInherit, ObjectInherit</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the files or folders the audit entry is removed from. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the propagation flags of the audit entry to remove. `None` addresses an entry that applies to the item itself and to all inheriting child items, `InheritOnly` an entry that applies to the child items only, and `NoPropagateInherit` an entry whose inheritance stops at the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">PropagationFlags</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>PropagationFlags</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the audit entry from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>RemoveSpecific</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet removes only an audit entry that matches the account, the access rights, the audit flags, and the inheritance and propagation flags exactly, and leaves all other entries unchanged. Without this switch, the cmdlet takes the specified rights and audit flags away from the matching entries.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-NTFSAudit`, `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The accounts passed to `-Account` are converted to this type from an account name or a SID string. The parameter binds by property name through its own name and its aliases `IdentityReference` and `ID`, so the `Account` property of the entries this module returns supplies the value.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemRights2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-AccessRights` is converted to this type. The parameter binds by property name, so an object with an `AccessRights` or `FileSystemRights` property supplies the value.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.AuditFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-AuditFlags` is converted to this type and binds by property name.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.InheritanceFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-InheritanceFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Security.AccessControl.PropagationFlags</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-PropagationFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.ApplyTo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The value passed to `-AppliesTo` is converted to this type and binds by property name in the `PathSimple` and `SDSimple` parameter sets.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemAuditRule2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the cmdlet writes all audit entries of the item or the security descriptor, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects. Before 5.0.0, the `Path` sets wrote the access entries of the item instead. An item whose audit entries could not be changed produces only an error; before 5.0.0, `-PassThru` also wrote its unchanged entries.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Reading and writing the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it, the cmdlet writes a non-terminating `RemoveAceError` whose message states that a required privilege is not held by the client, and the item is left unchanged.</maml:para>
|
|
<maml:para>A security descriptor that was read without the Security privilege doesn't contain the audit entries. With such a descriptor, the cmdlet writes a `ReadSecurityError` and changes nothing, like `Get-NTFSAudit`; before 5.0.0, it wrote no error, and `-PassThru` returned nothing.</maml:para>
|
|
<maml:para>A file or folder without audit entries can have no SACL at all. For such an item, the cmdlet writes nothing and no error; before 5.0.0, it failed with the error "(5) Access is denied".</maml:para>
|
|
<maml:para>If the security descriptor cannot be read or written because access is denied, the cmdlet takes ownership of the item, repeats the operation, and restores the previous owner. If the second attempt fails as well, the cmdlet restores the previous owner and writes an error. Before 5.0.0, the account that ran the cmdlet stayed the owner of the item in that case.</maml:para>
|
|
<maml:para>The cmdlet reports no error when no entry matches the supplied values. Compare the result with `Get-NTFSAudit` to confirm that the entry is gone.</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet had no `-RemoveSpecific` switch.</maml:para>
|
|
<maml:para>A path that does not exist produces the non-terminating error `ReadFileError`, and the cmdlet continues with the next path. Before 5.0.0, the cmdlet also wrote a misleading `RemoveAceError` for that path, and with `-PassThru` it stopped with a `NullReferenceException`.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>-------- Example 1: Remove an audit entry from a folder --------</maml:title>
|
|
<dev:code>PS C:\> Remove-NTFSAudit -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights FullControl -AuditFlags Failure</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes the entry that audits failed access of `CONTOSO\Domain Users` to `C:\Data`, its subfolders, and its files.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>- Example 2: Remove an audit entry that applies to one folder -</maml:title>
|
|
<dev:code>PS C:\> Remove-NTFSAudit -Path C:\Data -Account Everyone -AccessRights Delete, DeleteSubdirectoriesAndFiles -AuditFlags Success -AppliesTo ThisFolderOnly</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes the entry that audits successful deletions in the folder `C:\Data` itself. Use the same `-AppliesTo` value to remove an audit entry from a file, because audit entries on files are never inherited by child items.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 3: Remove the audit entries of one account ------</maml:title>
|
|
<dev:code>PS C:\> Get-NTFSAudit -Path C:\Data -Account 'CONTOSO\JohnDoe' -ExcludeInherited | Remove-NTFSAudit</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command reads the explicit audit entries of `CONTOSO\JohnDoe` and pipes them back into `Remove-NTFSAudit`, which removes each of them from the item it came from. The path, account, access rights, audit flags, and inheritance flags all bind from the properties of the piped entries.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>- Example 4: Remove an audit entry from a security descriptor -</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Remove-NTFSAudit -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AuditFlags Success, Failure -AppliesTo SubfoldersAndFilesOnly
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command removes the entry from the in-memory security descriptor of `C:\Data` and then writes the descriptor back to the file system.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Remove-NTFSAudit.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Clear-NTFSAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSOrphanedAudit</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Set-NTFSInheritance</command:name>
|
|
<command:verb>Set</command:verb>
|
|
<command:noun>NTFSInheritance</command:noun>
|
|
<maml:description>
|
|
<maml:para>Sets the inheritance of the access rules and the audit rules of a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Set-NTFSInheritance` cmdlet turns the inheritance of access rules and audit rules on or off in a single call. It reads the current state of the item first and changes a section only when the requested value differs from the current one, which makes the cmdlet suitable for repeatedly applying a desired state to a folder tree.</maml:para>
|
|
<maml:para>The cmdlet performs the same operations as `Enable-NTFSAccessInheritance`, `Disable-NTFSAccessInheritance`, `Enable-NTFSAuditInheritance`, and `Disable-NTFSAuditInheritance`, but it does not expose their switches; it uses their defaults instead. `-AccessInheritanceEnabled $false` copies the inherited access rules into the item's own DACL, `-AccessInheritanceEnabled $true` keeps the explicit access rules, `-AuditInheritanceEnabled $false` copies the inherited audit rules into the item's own SACL, and `-AuditInheritanceEnabled $true` keeps the explicit audit rules. To remove the rules instead, use `Disable-NTFSAccessInheritance -RemoveInheritedAccessRules` or `Enable-NTFSAuditInheritance -RemoveExplicitAuditRules`. Before 5.0.0, `-AccessInheritanceEnabled $false` discarded the inherited access rules, and `-AuditInheritanceEnabled $true` removed the explicit audit rules. Review scripts that used `-AccessInheritanceEnabled $false` to drop the inherited access rules: they now keep them, which leaves broader access in place; `Disable-NTFSAccessInheritance -RemoveInheritedAccessRules` gives the old result.</maml:para>
|
|
<maml:para>Omit `-AccessInheritanceEnabled` or `-AuditInheritanceEnabled` to leave that section unchanged. Changing the audit section requires the Security privilege and therefore an elevated session.</maml:para>
|
|
<maml:para>In the `Path` parameter set the cmdlet writes each changed section back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. `-Path`, `-AccessInheritanceEnabled`, and `-AuditInheritanceEnabled` all accept pipeline input by property name, so a `Security2.FileSystemInheritanceInfo` object from `Get-NTFSInheritance` binds to all three at once.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Set-NTFSInheritance</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose inheritance is set. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AccessInheritanceEnabled</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the item inherits access rules from its parent folder. `$true` removes the protection from the DACL and keeps the access rules that are stored directly on the item; `$false` protects the DACL and copies the rules the item currently inherits into it, so the effective permissions stay the same. Before 5.0.0, `$false` discarded the inherited rules. The section is left untouched when the requested value already matches the current state. When you omit the parameter, the access section is left unchanged.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditInheritanceEnabled</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the item inherits audit rules from its parent folder. `$true` removes the protection from the SACL and keeps the audit rules that are stored directly on the item (before 5.0.0, it removed them); `$false` protects the SACL and copies the inherited audit rules into it. The section is left untouched when the requested value already matches the current state. When you omit the parameter, the audit section is left unchanged. Reading and writing the audit section requires the Security privilege and therefore an elevated session.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the changes were attempted, so an object is also written when a change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Set-NTFSInheritance</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AccessInheritanceEnabled</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the item inherits access rules from its parent folder. `$true` removes the protection from the DACL and keeps the access rules that are stored directly on the item; `$false` protects the DACL and copies the rules the item currently inherits into it, so the effective permissions stay the same. Before 5.0.0, `$false` discarded the inherited rules. The section is left untouched when the requested value already matches the current state. When you omit the parameter, the access section is left unchanged.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditInheritanceEnabled</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the item inherits audit rules from its parent folder. `$true` removes the protection from the SACL and keeps the audit rules that are stored directly on the item (before 5.0.0, it removed them); `$false` protects the SACL and copies the inherited audit rules into it. The section is left untouched when the requested value already matches the current state. When you omit the parameter, the audit section is left unchanged. Reading and writing the audit section requires the Security privilege and therefore an elevated session.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the changes were attempted, so an object is also written when a change failed.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AccessInheritanceEnabled</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the item inherits access rules from its parent folder. `$true` removes the protection from the DACL and keeps the access rules that are stored directly on the item; `$false` protects the DACL and copies the rules the item currently inherits into it, so the effective permissions stay the same. Before 5.0.0, `$false` discarded the inherited rules. The section is left untouched when the requested value already matches the current state. When you omit the parameter, the access section is left unchanged.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>AuditInheritanceEnabled</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies whether the item inherits audit rules from its parent folder. `$true` removes the protection from the SACL and keeps the audit rules that are stored directly on the item (before 5.0.0, it removed them); `$false` protects the SACL and copies the inherited audit rules into it. The section is left untouched when the requested value already matches the current state. When you omit the parameter, the audit section is left unchanged. Reading and writing the audit section requires the Security privilege and therefore an elevated session.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>Boolean</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the changes were attempted, so an object is also written when a change failed.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose inheritance is set. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors.</maml:para>
|
|
<maml:para>A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object.</maml:para>
|
|
<maml:para>This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.Nullable`1[[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can supply `-AccessInheritanceEnabled` and `-AuditInheritanceEnabled` through a pipeline object that has properties of those names, such as the `Security2.FileSystemInheritanceInfo` objects that `Get-NTFSInheritance` returns.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemInheritanceInfo</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>The audit section of a security descriptor can only be read and written with the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, a requested change of `-AuditInheritanceEnabled` produces a non-terminating error that reports Windows error 1314, "A required privilege is not held by the client". The access section is processed first, so a change of `-AccessInheritanceEnabled` in the same command is applied even when the audit change fails.</maml:para>
|
|
<maml:para>If the descriptor cannot be opened because the account has no permission to the item, the cmdlet takes ownership of the item, applies the changes, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item.</maml:para>
|
|
<maml:para>A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths.</maml:para>
|
|
<maml:para>Before 5.0.0, omitting `-AccessInheritanceEnabled` or `-AuditInheritanceEnabled` could fail with the error "Nullable object must have a value".</maml:para>
|
|
<maml:para>Before 5.0.0, the cmdlet enabled the privileges even when `EnablePrivileges` was `$false`, and left them enabled.</maml:para>
|
|
<maml:para>Before 5.0.0, `-PassThru` returned the unchanged state of an item also when the change failed, and stopped the command when the item could not be read.</maml:para>
|
|
<maml:para>In the `Path` parameter set, the cmdlet writes only the section that it changes, the DACL or the SACL, and leaves the owner and the group of the item as they are. Before 5.0.0, a change of the access inheritance could also write the owner back, which failed with error 1307, "This security ID may not be assigned as the owner of this object", when the account may not assign that owner, such as on some file servers.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>-------- Example 1: Block inheritance of both sections --------</maml:title>
|
|
<dev:code>PS C:\> Set-NTFSInheritance -Path C:\Data\Projects -AccessInheritanceEnabled $false -AuditInheritanceEnabled $false</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command protects the DACL and the SACL of `C:\Data\Projects`. The inherited access and audit rules are copied into the folder's DACL and SACL, so the effective permissions and the auditing stay the same. Changing the audit section requires an elevated session.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------- Example 2: Restore inheritance of both sections -------</maml:title>
|
|
<dev:code>PS C:\> Set-NTFSInheritance -Path C:\Data\Projects -AccessInheritanceEnabled $true -AuditInheritanceEnabled $true -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command lets the folder inherit from `C:\Data` again. The explicit access and audit rules are kept, and `-PassThru` returns the resulting state.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---------- Example 3: Save a state and apply it again ----------</maml:title>
|
|
<dev:code>PS C:\> $state = Get-NTFSInheritance -Path C:\Data\Projects
|
|
PS C:\> Disable-NTFSAccessInheritance -Path C:\Data\Projects
|
|
PS C:\> $state | Set-NTFSInheritance</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first command records the inheritance state of the folder. After the second command changed it, the third command pipes the recorded object back and restores both values, because `FullName`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled` bind by property name.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 4: Change a security descriptor in memory ------</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects
|
|
PS C:\> Set-NTFSInheritance -SecurityDescriptor $sd -AccessInheritanceEnabled $false -AuditInheritanceEnabled $false
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first two commands read the security descriptor and change its inheritance in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Set-NTFSInheritance.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAuditInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Set-NTFSOwner</command:name>
|
|
<command:verb>Set</command:verb>
|
|
<command:noun>NTFSOwner</command:noun>
|
|
<maml:description>
|
|
<maml:para>Sets the owner of a file or folder.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Set-NTFSOwner` cmdlet writes the account given in `-Account` into the owner field of the security descriptor of a file or folder.</maml:para>
|
|
<maml:para>The two parameter sets differ in where the change lands. With `-Path`, the cmdlet reads the owner section of the item, replaces the owner, and writes the change to the file system immediately. With `-SecurityDescriptor`, it changes only the descriptor in memory; the new owner reaches the file system when you pass the descriptor to `Set-NTFSSecurityDescriptor`.</maml:para>
|
|
<maml:para>The cmdlet returns nothing unless you use `-PassThru`, which returns the owner of each processed item as a `Security2.FileSystemOwner` object. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem` binds to it. Relative paths are resolved against the current location, and omitting `-Path` leaves the cmdlet without work to do.</maml:para>
|
|
<maml:para>Every item is processed on its own. When a path does not exist or the owner cannot be written, the cmdlet writes a non-terminating error and continues with the next item. Windows itself decides whether the change is allowed: taking ownership requires the Take Ownership right on the item or the Take Ownership privilege (`SeTakeOwnershipPrivilege`), and assigning ownership to an account other than your own requires the Restore privilege (`SeRestorePrivilege`). The module tries to enable both privileges while the cmdlet runs, as described in the Notes section.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Set-NTFSOwner</maml:name>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose owner you want to change. The change is written to the file system immediately. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet does nothing.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account that becomes the new owner. The value is a `Security2.IdentityReference2` object, which the module creates from an account name such as `CONTOSO\JohnDoe` or `BUILTIN\Administrators`, or from a security identifier such as `S-1-5-32-544`. An account name that cannot be resolved fails during parameter binding.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns the owner of each processed item as a `Security2.FileSystemOwner` object. Without this parameter, the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
<command:syntaxItem>
|
|
<maml:name>Set-NTFSOwner</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet changes the owner only in memory; pass the descriptor to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account that becomes the new owner. The value is a `Security2.IdentityReference2` object, which the module creates from an account name such as `CONTOSO\JohnDoe` or `BUILTIN\Administrators`, or from a security identifier such as `S-1-5-32-544`. An account name that cannot be resolved fails during parameter binding.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns the owner of each processed item as a `Security2.FileSystemOwner` object. Without this parameter, the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none">
|
|
<maml:name>Account</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the account that becomes the new owner. The value is a `Security2.IdentityReference2` object, which the module creates from an account name such as `CONTOSO\JohnDoe` or `BUILTIN\Administrators`, or from a security identifier such as `S-1-5-32-544`. An account name that cannot be resolved fails during parameter binding.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">IdentityReference2</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>IdentityReference2</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet returns the owner of each processed item as a `Security2.FileSystemOwner` object. Without this parameter, the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the path of one or more files or folders whose owner you want to change. The change is written to the file system immediately. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet does nothing.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet changes the owner only in memory; pass the descriptor to `Set-NTFSSecurityDescriptor` to write the change to the file system.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more paths to this cmdlet. Objects that expose a `Path` or `FullName` property, such as the output of `Get-ChildItem2` and `Get-Item2`, bind to `-Path` as well.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe security descriptors that `Get-NTFSSecurityDescriptor` returned to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.IdentityReference2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>An account binds to `-Account` by property name, so an object that exposes an `Account` property supplies the new owner.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemOwner</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns one object per processed item only when you use `-PassThru`. It contains the item in `Item`, its path in `FullName`, and the new owner in `Owner` and `Account`.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>Without those privileges, Windows allows the change only when your account already holds the Take Ownership right on the item, and it refuses to assign ownership to another account. In a session that is not elevated, setting an owner other than your own account therefore fails with a non-terminating error.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------------- Example 1: Set the owner of a folder -------------</maml:title>
|
|
<dev:code>PS C:\> Set-NTFSOwner -Path C:\Data -Account 'CONTOSO\JohnDoe'</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command makes `CONTOSO\JohnDoe` the owner of the `C:\Data` folder and writes the change immediately.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title> Example 2: Set the owner of a folder tree and show the result </maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Set-NTFSOwner -Account 'BUILTIN\Administrators' -PassThru</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command makes the local Administrators group the owner of every file and folder below `C:\Data`. The `-PassThru` parameter returns the new owner of each item.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>Example 3: Change the owner in a security descriptor and write it back</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Set-NTFSOwner -SecurityDescriptor $sd -Account 'BUILTIN\Administrators'
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first two commands read the security descriptor of `C:\Data` and change its owner in memory. The third command writes the descriptor, which applies the new owner together with every other change made to `$sd`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------- Example 4: Set the owner by security identifier -------</maml:title>
|
|
<dev:code>PS C:\> Set-NTFSOwner -Path C:\Data\Report.docx -Account 'S-1-5-32-544'</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command makes the account with the security identifier `S-1-5-32-544`, which is the local Administrators group, the owner of the file. Use a SID when an account name cannot be resolved on the current computer.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Set-NTFSOwner.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSOwner</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Enable-Privileges</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Set-NTFSSecurityDescriptor</command:name>
|
|
<command:verb>Set</command:verb>
|
|
<command:noun>NTFSSecurityDescriptor</command:noun>
|
|
<maml:description>
|
|
<maml:para>Writes a security descriptor to the file or folder it was read from.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Set-NTFSSecurityDescriptor` cmdlet writes a `Security2.FileSystemSecurity2` object to the file system. It is the final step of the security descriptor workflow: `Get-NTFSSecurityDescriptor` reads a descriptor into memory, cmdlets such as `Add-NTFSAccess`, `Remove-NTFSAccess`, `Set-NTFSOwner`, and `Disable-NTFSAccessInheritance` change that copy through their `-SecurityDescriptor` parameter, and this cmdlet applies all of those changes in a single write.</maml:para>
|
|
<maml:para>Each descriptor remembers the item it was read from, and the cmdlet writes it back to exactly that item. There is no parameter that redirects the write to a different path. The cmdlet writes only the sections of the descriptor that changed since it was read or last written, such as the DACL after `Add-NTFSAccess`, and leaves the other sections of the item as they are, so a descriptor that you did not change writes nothing. With `-Verbose`, the cmdlet names the sections that it writes, or says that it writes nothing. Before 5.0.0, the cmdlet wrote every section that it had read, also an unchanged owner, which failed with error 1307, "This security ID may not be assigned as the owner of this object", when the account may not assign that owner, such as on some file servers.</maml:para>
|
|
<maml:para>The cmdlet produces no output unless you use `-PassThru`, which reads the item again after the write and returns a new `FileSystemSecurity2` object that reflects what is now stored on disk. Descriptors can be passed as an array or through the pipeline, and each one is processed on its own.</maml:para>
|
|
<maml:para>When the write fails because access is denied, the cmdlet takes ownership of the item with the account of the current session, writes the descriptor, and restores the previous owner, also when that write fails. A descriptor that sets a new owner keeps it; before 5.0.0, the cmdlet set the previous owner back over it. If the write fails as well, the cmdlet writes a non-terminating error and continues with the next descriptor. Windows checks each section separately: changing the access control list requires the Change Permissions right on the item, changing the owner requires the Take Ownership right or the Take Ownership privilege, assigning ownership to another account requires the Restore privilege, and writing audit entries requires the Security privilege.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Set-NTFSSecurityDescriptor</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="2" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. Each descriptor is written to the file or folder it was read from, including every change that was made to it in memory.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet reads each item again after the write and returns its current security descriptor. Without this parameter, the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
|
|
<maml:name>PassThru</maml:name>
|
|
<maml:description>
|
|
<maml:para>Indicates that the cmdlet reads each item again after the write and returns its current security descriptor. Without this parameter, the cmdlet produces no output.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>SwitchParameter</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>False</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="2" aliases="none">
|
|
<maml:name>SecurityDescriptor</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. Each descriptor is written to the file or folder it was read from, including every change that was made to it in memory.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">FileSystemSecurity2[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>FileSystemSecurity2[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more security descriptors that `Get-NTFSSecurityDescriptor` returned to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>Security2.FileSystemSecurity2</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>The cmdlet returns a descriptor per written item only when you use `-PassThru`. That descriptor is read from the item after the write, so it is a new object and not the one you passed in.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.</maml:para>
|
|
<maml:para>The cmdlet always writes to the item that is stored in the descriptor, so it cannot apply the descriptor of one item to another file or folder. To copy permissions, read the descriptor of the target item, add the entries you need with `Add-NTFSAccess`, and write the target descriptor.</maml:para>
|
|
<maml:para>`Add-NTFSAccess`, `Remove-NTFSAccess`, `Add-NTFSAudit`, and `Remove-NTFSAudit` offer two parameter sets for a security descriptor, one with `-AppliesTo` and one with `-InheritanceFlags` and `-PropagationFlags`. Specify at least one of those parameters when you pass a descriptor to them; otherwise PowerShell cannot decide which parameter set to use and reports an ambiguous parameter set.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>-------- Example 1: Write a changed security descriptor --------</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
|
|
PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The first two commands add an access control entry to the descriptor in memory, which leaves `C:\Data` untouched. The third command writes the descriptor and applies the new entry to the folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----- Example 2: Write several descriptors in one pipeline -----</maml:title>
|
|
<dev:code>PS C:\> $descriptors = Get-ChildItem2 -Path C:\Data | Get-NTFSSecurityDescriptor
|
|
PS C:\> $descriptors | ForEach-Object { Add-NTFSAccess -SecurityDescriptor $_ -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles }
|
|
PS C:\> $descriptors | Set-NTFSSecurityDescriptor</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>The descriptors of all items in `C:\Data` are read, changed in memory, and then written back. Each descriptor goes to the item it came from.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>----------------- Example 3: Write a new owner -----------------</maml:title>
|
|
<dev:code>PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Report.docx
|
|
PS C:\> Set-NTFSOwner -SecurityDescriptor $sd -Account 'BUILTIN\Administrators'
|
|
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This sequence changes the owner inside the descriptor and then writes the owner section to the file.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---------- Example 4: Verify the result after writing ----------</maml:title>
|
|
<dev:code>PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd -PassThru | Get-NTFSAccess</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command writes the descriptor, reads the item again, and lists the access control entries that are now stored on it.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Set-NTFSSecurityDescriptor.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-NTFSSecurityDescriptor</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Add-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-NTFSAccess</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Set-NTFSOwner</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Disable-NTFSAccessInheritance</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
|
|
<command:details>
|
|
<command:name>Test-Path2</command:name>
|
|
<command:verb>Test</command:verb>
|
|
<command:noun>Path2</command:noun>
|
|
<maml:description>
|
|
<maml:para>Determines whether a file or folder exists at the specified path.</maml:para>
|
|
</maml:description>
|
|
</command:details>
|
|
<maml:description>
|
|
<maml:para>The `Test-Path2` cmdlet returns `$true` when an item exists at the specified path and `$false` when it does not. It resolves paths with the AlphaFS library instead of the Windows PowerShell file system provider, so it also reports items whose full path exceeds the 260-character `MAX_PATH` limit, where the built-in `Test-Path` cmdlet returns `$false`.</maml:para>
|
|
<maml:para>The `-PathType` parameter narrows the test. `Any`, the default, returns `$true` for a file and for a folder, `Container` returns `$true` only for a folder, and `Leaf` returns `$true` only for a file. A path that does not exist returns `$false` for every `-PathType` value.</maml:para>
|
|
<maml:para>`-Path` accepts an array of paths and writes one Boolean value for each of them, in the order in which they are passed. The parameter takes pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem` binds to it. Relative paths are resolved against the current location.</maml:para>
|
|
</maml:description>
|
|
<command:syntax>
|
|
<command:syntaxItem>
|
|
<maml:name>Test-Path2</maml:name>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more paths to test. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PathType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the kind of item that the path must point to. `Any`, the default, matches a file and a folder, `Container` matches only a folder, and `Leaf` matches only a file.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValueGroup>
|
|
<command:parameterValue required="false" command:variableLength="false">Any</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Container</command:parameterValue>
|
|
<command:parameterValue required="false" command:variableLength="false">Leaf</command:parameterValue>
|
|
</command:parameterValueGroup>
|
|
<command:parameterValue required="true" variableLength="false">TestPathType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>TestPathType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Any</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:syntaxItem>
|
|
</command:syntax>
|
|
<command:parameters>
|
|
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="FullName">
|
|
<maml:name>Path</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies one or more paths to test. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>String[]</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>None</dev:defaultValue>
|
|
</command:parameter>
|
|
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
|
|
<maml:name>PathType</maml:name>
|
|
<maml:description>
|
|
<maml:para>Specifies the kind of item that the path must point to. `Any`, the default, matches a file and a folder, `Container` matches only a folder, and `Leaf` matches only a file.</maml:para>
|
|
</maml:description>
|
|
<command:parameterValue required="true" variableLength="false">TestPathType</command:parameterValue>
|
|
<dev:type>
|
|
<maml:name>TestPathType</maml:name>
|
|
<maml:uri />
|
|
</dev:type>
|
|
<dev:defaultValue>Any</dev:defaultValue>
|
|
</command:parameter>
|
|
</command:parameters>
|
|
<command:inputTypes>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>System.String[]</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2` and `Get-Item2`, to this cmdlet.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
<command:inputType>
|
|
<dev:type>
|
|
<maml:name>NTFSSecurity.TestPathType</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>You can supply the `-PathType` value through a pipeline object that has a `PathType` property.</maml:para>
|
|
</maml:description>
|
|
</command:inputType>
|
|
</command:inputTypes>
|
|
<command:returnValues>
|
|
<command:returnValue>
|
|
<dev:type>
|
|
<maml:name>System.Boolean</maml:name>
|
|
</dev:type>
|
|
<maml:description>
|
|
<maml:para>For each path, the cmdlet writes `$true` when the item exists and matches `-PathType`, and `$false` otherwise.</maml:para>
|
|
</maml:description>
|
|
</command:returnValue>
|
|
</command:returnValues>
|
|
<maml:alertSet>
|
|
<maml:alert>
|
|
<maml:para>The cmdlet resolves paths through the AlphaFS library, which is not bound by the 260-character `MAX_PATH` limit of the Windows PowerShell file system provider. Use `Test-Path2` instead of `Test-Path` when a path can be longer than that limit.</maml:para>
|
|
<maml:para>A path that does not exist is not an error condition. The cmdlet writes `$false` and continues with the next path. This also applies to a path with a character that Windows doesn't allow in names, such as `|` or `<`; Windows PowerShell rejects such a path, and the cmdlet writes the reason as a debug message. Before 5.0.0, such a path stopped the cmdlet with the terminating error "Illegal characters in path" in Windows PowerShell.</maml:para>
|
|
</maml:alert>
|
|
</maml:alertSet>
|
|
<command:examples>
|
|
<command:example>
|
|
<maml:title>------------ Example 1: Test whether a file exists ------------</maml:title>
|
|
<dev:code>PS C:\> Test-Path2 -Path C:\Data\Report.txt</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns `$true` when `Report.txt` exists in the `C:\Data` folder, regardless of whether it is a file or a folder.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>---------- Example 2: Test whether a path is a folder ----------</maml:title>
|
|
<dev:code>PS C:\> Test-Path2 -Path C:\Data -PathType Container</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command returns `$true` only when `C:\Data` exists and is a folder. If `C:\Data` is a file, the command returns `$false`.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------------ Example 3: Test several paths at once ------------</maml:title>
|
|
<dev:code>PS C:\> Test-Path2 -Path C:\Data\Report.txt, C:\Data\Archive\Report.txt -PathType Leaf</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command tests both paths and writes one Boolean value for each of them, in the order in which they are given.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
<command:example>
|
|
<maml:title>------ Example 4: Test paths that come from the pipeline ------</maml:title>
|
|
<dev:code>PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Test-Path2 -PathType Leaf</dev:code>
|
|
<dev:remarks>
|
|
<maml:para>This command pipes every item below `C:\Data` to `Test-Path2`, which binds the `FullName` property of each item to `-Path` and reports `$true` for the files and `$false` for the folders.</maml:para>
|
|
</dev:remarks>
|
|
</command:example>
|
|
</command:examples>
|
|
<command:relatedLinks>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Online Version:</maml:linkText>
|
|
<maml:uri>https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Test-Path2.md</maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-ChildItem2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Get-FileHash2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
<maml:navigationLink>
|
|
<maml:linkText>Remove-Item2</maml:linkText>
|
|
<maml:uri></maml:uri>
|
|
</maml:navigationLink>
|
|
</command:relatedLinks>
|
|
</command:command>
|
|
</helpItems>
|