SubInAcl

    More info:

    Subinacl.exe

    Overview | Remarks | Syntax | Examples | Related Tools

    Overview

    SubInACL is a command-line tool that enables administrators to obtain security information about files, registry keys, and services, and transfer this information from user to user, from local or global group to group, and from domain to domain.

    For example, if a user has moved from one domain (DomainA) to another (DomainB), the administrator can replace DomainA\User with DomainB\User in the security information for the user's files. This gives the user access to the same files from the new domain.

    SubInACL enables administrators to do the following:

    Corresponding Operating System Features

    The operating system provides no GUI functionality that corresponds to this tool.

    Concepts

    For an introduction to security descriptors and the role they play in access control, see Understanding access control in Help and Support Center for Windows Server 2003.

    System Requirements

    The following are the system requirements for SubInACL:

    This tool is designed for use by administrators. Some actions may fail or generate error messages if the user does not have the following privileges:

    File Required

     

    Remarks


    Comparing SubInACL to the find Tool in UNIX

    The syntax of SubInACL is analogous to that of the find tool in UNIX. For each object, SubInACL:

    If the security descriptor has been modified and the /testmode switch has not been specified, the changes are applied to the object. You can specify as many actions as you need. You must specify at least three characters for each action. The syntax is not case-sensitive.

    Editing in SubInACL

    SubInACL allows you to modify each part of a security descriptor:

    Using SIDs in SubInACL

    The security descriptor references a user group by using a security identifier (SID). An SID can be expressed in one of the following forms:

    SubInACL maintains a local cache of SIDs to minimize "SID-to-human name" translation costs for the network.

    Using PACEs in SubInACL

    The following permission ACEs (PACEs) are used with the /grant and /deny parameters.

    File PACEs

    The following PACEs are valid for file objects:
    PACE Description
    F Full Control
    C Change
    R Read
    P Change Permissions
    O Take Ownership
    X eXecute
    E Read eXecute
    W Write
    D Delete

    Cluster Share PACEs

    The following PACEs are valid for cluster share objects:
    PACE Description
    F Full Control
    R Read
    C Change

    Printer PACEs

    The following PACEs are valid for printer objects:
    PACE Description
    F Full Control
    M Manage Documents
    P Print

    Registry PACEs

    The following PACEs are valid for registry key and registry subkey objects:
    PACE Description
    F Full Control
    R Read
    A ReAd Control
    Q Query Value
    S Set Value
    C Create SubKey
    E Enumerate Subkeys
    Y NotifY
    L Create Link
    D Delete
    W Write DAC
    O Write Owner

    Services PACEs

    The following PACEs are valid for services:
    PACE Description
    F Full Control
    R Generic Read
    W Generic Write
    X Generic eXecute
    L Read controL
    Q Query Service Configuration
    S Query Service Status
    E Enumerate Dependent Services
    C Service Change Configuration
    T Start Service
    O Stop Service
    P Pause/Continue Service
    I Interrogate Service
    U Service User-Defined Control Commands

    Share PACEs

    The following PACEs are valid for share objects:
    PACE Description
    F Full Control
    R Read
    C Change

    Metabase PACEs

    The following PACEs are valid for metabase objects:
    PACE Description
    F Full Control
    R Read - MD_ACR_READ
    W Write - MD_ACR_WRITE
    I Restricted Write - MD_ACR_RESTRICTED_WRITE
    U Unsecure Props Read - MD_ACR_UNSECURE_PROPS_READ
    E Enum Keys - MD_ACR_ENUM_KEYS
    D Write DAC - MD_ACR_WRITE_DAC

    Process PACEs

    The following PACEs are valid for process objects:
    PACE Description
    F Full Control
    R Read
    W Write
    E Execute

    SAM Object PACEs

    The following PACEs are valid for Security Accounts Manager (SAM) objects:
    PACE Description
    F Full Control
    R Read
    W Write
    E Execute

    Minimizing Bandwidth Usage

     

    Syntax


    The syntax descriptions below are grouped by how you use SubInACL: getting Help about its features, using it interactively in a console window, or using it within its own scripting environment.

    Syntax for Getting Help

    4subinacl /help [/full | Keyword]

    Parameters

    /full
    Displays all of the information about SubInACL.
    Keyword
    [ /noverbose | /verbose | /verbose=1 | /verbose=2 | /testmode | /notestmode | /file | /subdirectories | /onlyfile | /share | /clustershare | /keyreg | /subkeyreg | /service | /printer | /kernelobject | /metabase | /display | /setowner | /replace | /changedomain | /migratetodomain | /findsid | /suppresssid | /confirm | /perm | /audit | /ifchangecontinue | /cleandeletedsidsfrom | /accesscheck | /setprimarygroup | /grant | /deny | /revoke ]
    Displays information about the specified option, object_type, or action.
    /option
    Displays information about all SubInACL options.
    /action
    Displays information about all SubInACL actions.
    /object_type
    Displays information about all SubInACL object_types.
    features
    Displays information about the feature set.
    usage
    Displays a summary of SubInACL syntax.
    syntax
    Displays an conceptual overview of the SubInACL syntax.
    sids
    Displays information about how SIDs are expressed, and how SubInACL attempts to translate SIDs.
    view_mode
    Displays information about using SubInACL to view security information.
    test_mode
    Displays information about using a testing mode to ensure that a SubInACL command is correct.
    object_type
    Displays information about the types of object that SubInACL can work with.
    domain_migration
    Displays information about moving a user from one domain to another.
    server_migration
    Displays information about moving the file system of a server from one domain to another.
    editing_features
    Displays information about features of SubInACL that edit security descriptors.

    For more information, see /help under Option Syntax Examples on the Examples page.

    Syntax for Using SubInACL in a Console Window

    4subinacl [/Option] /object_type object_name [[/Action[=Parameter]..]

    Parameters

    /Option can be any of the following:
    /outputlog=FileName
    Redirects the output of the command to the specified file. The output will include errors unless the /errorlog option is used, in which case errors are sent to the error log file and all other output is sent to the output log file.
    /errorlog=FileName
    Redirects all errors to the specified file.
    /alternatesamserver=ServerName
    Specifies the server that SubInACL will use to look up SIDs, if its first attempt fails. This is useful during some server and domain migrations.
    /offlinesam=FileName
    Specifies a text file that matches user names to their SIDs, and directs SubInACL to look up SIDs in this file instead of on the server on which the object is located. This is useful if the domain is unaccessible or no longer exists.
    /stringreplaceonoutput=String1=String2
    Causes SubInACL to replace all occurrences of String1 in its output with String2.
    /expandenvironmentsymbols
    Allows SubInACL to use environment variables, such as %username%. This is the default value, and the opposite of /noexpandenvironmentvariables.
    /noexpandenvironmentsymbols
    Prevents SubInACL from using environment variables. This is useful when SubInACL operates on command files.
    /statistic
    Displays statistics when processing is finished. This is the default value.
    /nostatistic
    Suppresses the display of statistics when processing is finished.
    /dumpcachedsids=FileName
    After you run SubInACL, you can dump the contents of the local cache SIDs to a file. This file can be used for future SubInACL execution (see /offlinesam) to speed up the SIDs resolution process.
    /separator=character
    Specifies a character for SubInACL to use in place of the equal sign (=) when it interprets a command. This allows you to specify a string that contains an equal sign within a SubInACL command.
    /noverbose
    Causes SubInACL to produce shortened output that is easier for people to read. The output of a SubInACL command in /noverbose mode can be saved in a command file and replayed later.
    /verbose
    Causes SubInACL to produce detailed output. This is the default level of detail.
    /verbose=1
    This display mode is identical to /verbose mode.
    /verbose=2
    This display mode is identical to /verbose mode.
    /testmode
    Runs SubInACL in testing mode so that changes will not be applied to the specified object's security descriptor.
    /notestmode
    Runs SubInACL in update mode, so that any changes defined by a SubInACL command will be applied. This is the default value.
     
    /object_type can be any of the following:
    /file [=directoriesonly | =filesonly]
    Specifies that object_name is a file object. When the /file parameter is specified, object_name can identify files by using the Universal Naming Convention (UNC) format or by using a local drive letter and path. object_name can contain the * wildcard character.

    Note

    • SubInACL is not supported on distributed file system (DFS) volumes.
     
    /subdirectories | /subdirec [=directoriesonly | =filesonly]
    Specifies that object_name is a folder (directory) and that SubInACL will use all the files in it and in all its subfolders. When either the /subdirectories or /subdirec parameter is specified, object_name can identify files by using the UNC format or by using a local drive letter and path. object_name can include the * wildcard character.
    /onlyfile
    Opens a file without using the FindFilexxx mechanism. Valid values for object_name when the /onlyfile parameter is specified are named pipes or mailslots.
    /samobject
    Specifies that object_name is a Security Accounts Manager (SAM) object, such as a user, local group, or global group.
    /share
    Specifies that object_name is a network file share.
    /clustershare
    Specifies that object_name is a cluster file share.
    /keyreg
    Specifies that object_name is a registry key.
    /subkeyreg
    Specifies that object_name is a registry subkey.
    /service
    Specifies that object_name is a service.
    /process
    Specifies that object_name is a process.
    /printer
    Specifies that object_name is a printer.
    /kernelobject
    Specifies that object_name is a kernel object. Valid values for object_name can include mutexes, sections, or event objects.
    /metabase
    Specifies that object_name is an AdminACL metabase property of the Microsoft Internet Information Services (IIS) metabase.

    Notes

    • This object_type can be used only with the following metabase paths:
      • \LM\MSFTPSVC
      • \LM\MSFTPSVC/n
      • \LM\W3SVC
    • This object_type does not support enumeration
     
    object_name
    Specifies the name of the object. For examples, see specific object_type descriptions.
     
    /Action can be any of the following:
    /display [=dacl | =sacl | =owner | =primarygroup | =sdsize | =sddl]
    Displays the security descriptor for the specified object. This is the default action. The optional parameters allow you to specify which parts of the security descriptor SubInACL should search. When used in conjunction with /noverbose, /display reapplies the security descriptor to the specified object.
    /setowner
    Changes the owner of the object. Using /owner=SID or /setowner=SID owner = DomainName\Administrators will retrieve the Administrators SID on the server where the object is located.
    /owner=Owner
    Changes the owner of the specified object. Owner is a valid SID that can be expressed in four different formats. For more information, see Using SIDs in SubInACL on the Remarks page.
    /replace=[DomainName\]OldAccount=[DomainName\]NewAccount
    Replaces all access control entries (ACEs) (audit ACEs and permissions ACEs) in the specified object.
    /accountmigration=DomainName\OldAccount=DomainName\NewAccount
    Replaces the owner or primary group if one of them is DomainName\OldAccount. For example: /accountmigration=DOM_MARKETING\ChairMan=NEWDOM\NewChairMan will duplicate all ACEs containing DOM_MARKETING\ChairMan with NewChairMan SID retrieves from NEWDOM domain. For more information, see the /replace action.

    Caution

    • If DomainName\NewAccount has an ACE already, ACE replacement is skipped.
     
    /changedomain=OldDomainName=NewDomainName
    Replaces all ACEs with an SID from OldDomainName with the equivalent SID found in NewDomainName.
    /migratetodomain=SourceDomain=DestinationDomain
    Adds ACEs found in SourceDomain for the specified object to DestinationDomain, while preserving the ACEs in SourceDomain.
    /findsid=DomainName\Account[=stop | =continue]
    Displays the object_name containing a reference to DomainName\Account in the security descriptor. If =stop is specified and the Account is found, the next parameters will be skipped and changes will not be applied. If =stop is specified and the Account is not found, the next parameters will be executed. If =continue is specified and the Account is found, the next parameters will be executed. If =continue is specified and the Account is not found, the next parameters will be skipped and changes will not be applied.
    /suppresssid=[DomainName\]Account
    Suppresses (deletes) all ACEs containing the [DomainName\]Account. If the object's owner is [DomainName\]Account, the owner is set to Everyone's SID.
    /confirm
    If placed inside a set of actions, prompts the user before processing the next action.
    /perm
    Suppresses all existing PACEs.
    /audit
    Suppresses all existing AACEs.
    /ifchangecontinue
    Continues to process the next actions only if changes have been made by the previous actions.
    /cleandeletedsidsfrom=DomainName [=dacl | =sacl | =owner | =primarygroup | =sdsize]
    Deletes all ACEs containing deleted (not valid) SIDs from DomainName. The optional parameters allow you to specify certain parts of the security descriptor in which to search for invalid SIDs.
    /testmode
    Prevents changes from being applied to the object. This allows you to test the modifications that SubInACL will make.
    /accesscheck=[DomainName\]UserName
    Displays the access granted to the [DomainName\]UserName. This option requires the SeTcbName privilege (Act As Part of the Operating System), and cannot be used with remote objects.
    /setprimarygroup=[DomainName\]Group
    Changes the primary group.
    /grant=[DomainName\]UserName[=Access]
    Adds a PACE for UserName. Valid values for Access depend on the type of object specified in object_name. Valid PACEs are listed in Using PACEs in SubInACL on the Remarks page. If Access is not specified, Full Control access is granted.
    /deny=[DomainName\]UserName[=Access]
    Adds a denied PACE for the specified user or group. Valid values for Access depend on the type of object specified in object_name. Valid PACEs are listed in Using PACEs in SubInACL on the Remarks page. If Access is not specified, all accesses are denied.
    /sgrant=[DomainName\]UserName[=Access]
    Adds a successful AACE for the specified user. If Access is not specified, Full Control access is granted. Valid permission ACEs are listed in Using PACEs in SubInACL on the Remarks page.
    /sdeny=[DomainName\]UserName[=Access]
    Adds a failed AACE for the specified user. If Access is not specified, all accesses are denied. Valid PACEs are listed in Using PACEs in SubInACL on the Remarks page.
    /revoke=[DomainName\]UserName
    Denies all PACEs for the specified user or group.
    /compactsecuritydescriptor
    Compresses security descriptors by removing unused entries.
    /pathexclude=Pattern
    Excludes all containers matching the description of Pattern, and all the objects within those paths. The * wildcard character can be used within Pattern to represent any number of any characters.
    /objectexclude=Pattern
    Excludes all objects with names that match Pattern. The * wildcard character can be used within Pattern to represent any number of any characters.
     
    Parameter
    The parameter of /Action, if required.

    Syntax for Using SubInACL Within Its Own Scripting Environment

    4subinacl [/Option ..] /playfile FileName

    Parameters

    /Option
    Any of the SubInACL options defined above.
    FileName
    The name of the SubInACL command file (script file). You can create the file manually, or by issuing a SubInACL command that uses the /noverbose and /display options.

    The syntax of the /playfile command file is the same as the syntax of SubInACL when used in a console window, except that:

    • /Option is not used.
    • Each /object_type is preceded by a plus symbol (+) rather than a slash (/).
    • Each /object_type and object_name pair appear together, on the same line.
    • Each action appears on its own line, followed by any applicable parameters.

    For more information, see /playfile under Action Syntax Examples on the Examples page.

     

    Examples


    Scenario Examples

    Scenario Example 1

    The task in this example is to adjust the files on \\Server\Share after you move User1 from OldDomain to NewDomain. Type the following at the command line:

    subinacl /subdirec \\server\share\*.* /replace=OLDDOMAIN\USER1=NEWDOMAIN\User1

    Press ENTER.

        Note

    Scenario Example 2

    The task in this example is to migrate a backup domain controller (BDC) named MigrControl with all its files to NewDomain, and migrate users from OldDomain to NewDomain.

    1. Reinstall MigrControl as a primary domain controller (PDC) of NewDomain, and do not erase the files.
    2. Create the users on NewDomain.
    3. Create a trust relationship with OldDomain.
    4. To migrate the files, type the following at the command line:
      subinacl /noverbose /subdirectories x:\*.* /changedomain=OLDDOMAIN=NEWDOMAIN
    5. Press ENTER.
    6. To verify the changes, type the following at the command line:
      subinacl /noverbose /subdirectories x:\*.*
    7. Press ENTER.

    Scenario Example 3

    The task in this example is to move a stand-alone server and its users to NewDomain.

    1. Move the server to NewDomain.
    2. Create the users in NewDomain.
    3. Type the following at the command line:
      subinacl /noverbose /subdirectories \\SERVER\SHARE /changedomain=SERVER=NEWDOMAIN
    4. Press ENTER.

    Scenario Example 4

    The task in this example is to replace "Jim" with "Kim" in each .txt file in the C:\Temp folder, display the security descriptor for each such file, and apply any changes. Type the following at the command line:

    subinacl /file c:\temp\*.txt /replace=Jim=Kim/display

    Press ENTER.

    Option Syntax Examples

    /help

    /outputlog

    /errorlog

    /alternatesamserver

    /offlinesam

    /stringreplaceonoutput

    /noexpandenvironmentsymbols

    /separator

    /noverbose

    /verbose

    /testmode

    Object Syntax Examples

    /file

    /subdirectory

    /onlyfile

    /samobject

    /share

    /clustershare

    /keyreg

    /subkeyreg

    /service

    /printer

    /kernelobject

    /process

    /metabase

    Action Syntax Examples

    /display

    /owner

    /replace

    /changedomain

    /migratetodomain

    /findsid

    /suppresssid

    /confirm

    /perm

    /audit

    /accesscheck

    /setprimarygroup

    /grant

    /deny

    /revoke

    /compactsecuritydescriptor

    /pathexclude

    /objectexclude

    /playfile

     

    Related Tools


    Tools related to Subinacl.exe include: