How to use Xcacls.vbs to modify NTFS permissions

Article translations Article translations
Article ID: 825751 - View products that this article applies to.
Expand all | Collapse all

On This Page

SUMMARY

There is an updated version of the Extended Change Access Control List tool (Xcacls.exe) that is available as a Microsoft Visual Basic script (Xcacls.vbs) from Microsoft. This step-by-step article describes how to use the Xcacls.vbs script to modify and to view NTFS file system permissions for files or for folders. You can use Xcacls.vbs from the command line to set all the file system security options that are accessible in Microsoft Windows Explorer. Xcacls.vbs displays and modifies the access control lists (ACLs) of files.

Note Xcacls.vbs is only compatible with Microsoft Windows 2000, with Microsoft Windows XP, and with Microsoft Windows Server 2003. Xcacls.vbs is not supported by Microsoft.

Set Up and Use Xcacls.vbs

To set up and to use Xcacls.vbs, follow these steps:
  1. Obtain the latest version of Xcacls.vbs from the following Microsoft Web site:
    http://download.microsoft.com/download/f/7/8/f786aaf3-a37b-45ab-b0a2-8c8c18bbf483/XCacls_Installer.exe
  2. Double-click Xcacls_Installer.exe. When you are prompted for a location to place the extracted files, specify a folder that is in your computer's search-path setting, such as C:\Windows.
  3. Change the default scripting engine from Wscript to Cscript. (The Xcacls.vbs script works best in Cscript.) To do this, type the following at a command prompt, and then press ENTER:
    cscript.exe /h:cscript
    Note Changing the default scripting engine to Cscript only affects how scripts write to the screen. Wscript writes each line individually to an OK dialog box. Cscript writes each line to the command window. If you do not want to change the default scripting engine, you must run the script by using the following command
    cscript.exe xcacls.vbs
    whereas if you change the default to Cscript, you can run the script with the following command:
    xcacls.vbs
    .
  4. To see the Xcacls.vbs command syntax, type the following at a command prompt:
    xcacls.vbs /?

Syntax for the Xcacls.vbs Command

The following output of the xcacls.vbs /? command describes the Xcacls.vbs command syntax:
Usage:
XCACLS filename [/E] [/G user:perm;spec] [...] [/R user [...]]
                [/F] [/S] [/T]
                [/P user:perm;spec [...]] [/D user:perm;spec] [...]
                [/O user] [/I ENABLE/COPY/REMOVE] [/N
                [/L filename] [/Q] [/DEBUG]

   filename            [Required] If used alone, it displays ACLs.
                       (Filename can be a filename, directory name or
                       wildcard characters and can include the whole
                       path. If path is missing, it is assumed to be
                       under the current directory.)
                       Notes:
                       - Put filename in quotes if it has spaces or
                       special characters such as &, $, #, etc.
                       - If filename is a directory, all files and
                       subdirectories under it will NOT be changed
                       unless the /F or S is present.

   /F                  [Used with Directory or Wildcard] This will change all
                       files under the inputted directory but will NOT
                       traverse subdirectories unless /T is also present.
                       If filename is a directory, and /F is not used, no
                       files will be touched.

   /S                  [Used with Directory or Wildcard] This will change all
                       subfolders under the inputted directory but will NOT
                       traverse subdirectories unless /T is also present.
                       If filename is a directory, and /S is not used, no
                       subdirectories will be touched.

   /T                  [Used only with a Directory] Traverses each
                       subdirectory and makes the same changes.
                       This switch will traverse directories only if the
                       filename is a directory or is using wildcard characters.
   /E                  Edit ACL instead of replacing it.

   /G user:GUI         Grant security permissions similar to Windows GUI
                       standard (non-advanced) choices.
   /G user:Perm;Spec   Grant specified user access rights.
                       (/G adds to existing rights for user)

                       User: If User has spaces in it, enclose it in quotes.
                             If User contains #machine#, it will replace
                             #machine# with the actual machine name if it is a
                             non-domain controller, and replace it with the
                             actual domain name if it is a domain controller.

                             New to 3.0: User can be a string representing
                             the actual SID, but MUST be lead by SID#
                             Example: SID#S-1-5-21-2127521184-160...
                                      (SID string shown has been shortened)
                                      (If any user has SID# then globally all
                                       matches must match the SID (not name)
                                       so if your intention is to apply changes
                                       to all accounts that match Domain\User
                                       then do not specify SID# as one of the
                                       users.)

                       GUI: Is for standard rights and can be:
                             Permissions...
                                    F  Full control
                                    M  Modify
                                    X  read and eXecute
                                    L  List folder contents
                                    R  Read
                                    W  Write
                             Note: If a ; is present, this will be considered
                             a Perm;Spec parameter pair.

                       Perm: Is for "Files Only" and can be:
                             Permissions...
                                    F  Full control
                                    M  Modify
                                    X  read and eXecute
                                    R  Read
                                    W  Write
                             Advanced...
                                    D  Take Ownership
                                    C  Change Permissions
                                    B  Read Permissions
                                    A  Delete
                                    9  Write Attributes
                                    8  Read Attributes
                                    7  Delete Subfolders and Files
                                    6  Traverse Folder / Execute File
                                    5  Write Extended Attributes
                                    4  Read Extended Attributes
                                    3  Create Folders / Append Data
                                    2  Create Files / Write Data
                                    1  List Folder / Read Data
                       Spec is for "Folder and Subfolders only" and has the
                       same choices as Perm.

   /R user             Revoke specified user's access rights.
                       (Will remove any Allowed or Denied ACL's for user.)

   /P user:GUI         Replace security permissions similar to standard choices.

   /P user:perm;spec   Replace specified user's access rights.
                       For access right specification see /G option.
                       (/P behaves like /G if there are no rights set for user.)

   /D user:GUI         Deny security permissions similar to standard choices.
   /D user:perm;spec   Deny specified user access rights.
                       For access right specification see /G option.
                       (/D adds to existing rights for user.)

   /O user             Change the Ownership to this user or group.

   /I switch           Inheritance flag.  If omitted, the default is to not touch
                       Inherited ACL's. Switch can be:
                          ENABLE - This will turn on the Inheritance flag if
                                   it is not on already.
                          COPY   - This will turn off the Inheritance flag and
                                   copy the Inherited ACL's
                                   into Effective ACL's.
                          REMOVE - This will turn off the Inheritance flag and
                                   will not copy the Inherited
                                   ACL's.  This is the opposite of ENABLE.
                          If switch is not present, /I will be ignored and
                          Inherited ACL's will remain untouched.

   /L filename         Filename for Logging. This can include a path name
                       if the file is not under the current directory.
                       File will be appended to, or created if it does not
                       exit. Must be Text file if it exists or error will occur.

                       If filename is omitted, the default name of XCACLS will
                       be used.

   /Q                  Turn on Quiet mode.  By default, it is off.
                       If it is turned on, there will be no display to the screen.


   /DEBUG              Turn on Debug mode. By default, it is off.
                       If it is turned on, there will be more information
                       displayed and/or logged. Information will show
                       Sub/Function Enter and Exit as well as other important
                       information.

   /SERVER servername  Enter a remote server to run script against.

   /USER username      Enter Username to impersonate for Remote Connections
                            (requires PASS switch).  Will be ignored if it is for a Local Connection.

   /PASS password      Enter Password to go with USER switch
                            (requires USER switch).


Wildcard characters can be used to specify more than one file in a command, such as:
                                *       Any string of zero or more characters
                                ?       Any single character

You can specify more than one user in a command.
You can combine access rights.


Use Xcacls.vbs to View Permissions


You can also use Xcacls.vbs to view permissions for files or folders. For example, if you have a folder that is named C:\Test, type the following at a command prompt to view the folder permissions, and then press ENTER:
xcacls.vbs c:\test
The following example is a typical result:
C:\>XCACLS.VBS c:\test
Microsoft (R) Windows Script Host Version 5.6
Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

Starting XCACLS.VBS (Version: 3.4) Script at 6/11/2003 10:55:21 AM

Startup directory:
"C:\test"

Arguments Used:
        Filename = "c:\test"



**************************************************************************
Directory: C:\test

Permissions:
Type     Username                Permissions           Inheritance

Allowed  BUILTIN\Administrators  Full Control          This Folder, Subfolde
Allowed  NT AUTHORITY\SYSTEM     Full Control          This Folder, Subfolde
Allowed  Domain1\User1           Full Control          This Folder Only
Allowed  \CREATOR OWNER          Special (Unknown)     Subfolders and Files
Allowed  BUILTIN\Users           Read and Execute      This Folder, Subfolde
Allowed  BUILTIN\Users           Create Folders / Appe This Folder and Subfo
Allowed  BUILTIN\Users           Create Files / Write  This Folder and Subfo

No Auditing set

Owner: Domain1\User1


Note The output of the xcacls.vbs c:\test command in this example matches the text that is shown in the graphical user interface (GUI). Some words are incomplete in the command window.

The output also gives the version of the script, the startup directory, and the arguments that were used.

You can also use wildcard characters to display matching files under the directory. For example, if you type the following, all files with an extension of ".log" that are in the C:\Test folder are displayed:
xcacls.vbs c:\test\*.log

Examples


The following Xcacls.vbs commands provide some examples of Xcacls.vbs usage.

xcacls.vbs c:\test\ /g domain\testuser1:f /f /t /e
This command edits existing permissions. It grants Domain\TestUser1 full control on all files under C:\Test, it traverses subfolders under C:\Test, and then it changes any files that are found. This command does not touch directories.
xcacls.vbs c:\test\ /g domain\testuser1:f /s /l "c:\xcacls.log"
This command replaces existing permissions. It grants Domain\TestUser1 full control on all subfolders under C:\Test, and it logs to C:\Xcacls.log. This command does not touch files, and it does not traverse directories.
xcacls.vbs c:\test\readme.txt /o "machinea\group1"
This command changes the owner of Readme.txt to be the group MachineA\Group1.
xcacls.vbs c:\test\badcode.exe /r "machinea\group1" /r "domain\testuser1"
This command revokes the permissions to C:\Test\Badcode.exe for MachineA\Group1 and for Domain\TestUser1.
xcacls.vbs c:\test\subdir1 /i enable /q
This command turns on inheritance on the folder C:\Test\Subdir1. It suppresses any screen output.
xcacls.vbs \\servera\sharez\testpage.htm /p "domain\group2":14
This command remotely connects to \\ServerA\ShareZ by using Windows Management Instrumentation (WMI). It then obtains the local path for that share, and under that path, it changes the permissions on Testpage.htm. It leaves the existing permissions of Domain\Group2 intact, but it adds permissions 1 (read data) and 4 (read extended attributes). The command drops other permissions on the file because the /e switch was not used.
xcacls.vbs d:\default.htm /g "domain\group2":f /server servera /user servera\admin /pass password /e
This command uses WMI to remotely connect as ServerA\Admin to ServerA and then grants full permissions on Default.htm to Domain\Group2. Existing permissions for Domain\Group2 are lost and other permissions on the file remain.

REFERENCES

For additional information about how to use Xcacls.exe, click the following article number to view the article in the Microsoft Knowledge Base:
318754 How to use Xcacls.exe to modify NTFS permissions

Properties

Article ID: 825751 - Last Review: October 30, 2006 - Revision: 2.4
APPLIES TO
  • Microsoft Windows Server 2003, Datacenter Edition (32-bit x86)
  • Microsoft Windows Server 2003, Enterprise Edition (32-bit x86)
  • Microsoft Windows Server 2003, Standard Edition (32-bit x86)
  • Microsoft Windows Server 2003, Web Edition
  • Microsoft Windows XP Professional
  • Microsoft Windows XP Home Edition
  • Microsoft Windows 2000 Datacenter Server
  • Microsoft Windows 2000 Advanced Server
  • Microsoft Windows 2000 Server
  • Microsoft Windows 2000 Professional Edition
Keywords: 
kbhowtomaster KB825751

Give Feedback

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com