The GPMC scripting object model provides a set of interfaces for performing tasks related to everything from creating and backing up GPOs to generating Resultant Set of Policy (RSOP) logging reports and modifying GPO permissions. However, the scripting interfaces provided by GPMC do now allow for editing of policy settings within a GPO. They provide only for management and reporting of GPOs as whole objects. Figure C-1 shows a map of the GPMC object model.

Figure C-1. The GPMC scripting object model

The GPMC object model is implemented within the file Gpmgmt.dll. As Figure C-1 shows, the root of the GPMC object model is an object called GPM, which is the starting for any scripts you write based on the GPMC. In fact, most anything you do with the GPMC scripting interfaces starts with creating an instance of the GPM object, then connecting to an Active Directory domain, then performing operations on one or more GPOs.

Many of the methods on the IGPMDomain interface, when called, create instances of other interfaces that support most of the operations you will want to perform against your Group Policy infrastructure. If we were to write a VBScript-based WSH script, this initial instantiation of the GPM object would look like Example C-1.

Set GPM = CreateObject("GPMgmt.GPM")

This command creates an instance of the IGPM interface, which has a set of methods that provide access to other interfaces that are useful for managing GPOs. For example, the next thing you usually need in your scripts to start managing GPO is to connect to an Active Directory domain so you can begin referencing GPOs within that domain. To do that, you need to create an instance of the IGPMDomain interface.

The GetDomain method on the IGPM interface returns just such an instance. Once you’ve created an instance of IGPM, as just shown, you can call the GetDomain method on that instance to get a reference to IGPMDomain, as shown in Example C-2.

Set GPMDomain = GPM.GetDomain(DomainName, "", GPM_USE_PDC)

DomainName is the DNS domain name of the Active Directory domain you want to connect to, and the constant GPM_USE_PDC simply tells the command to connect to the domain’s PDC emulator rather than another domain controller. You can optionally use a "" string parameter to specify a specific domain controller to connect to by DNS name. In most cases, the statement shown is sufficient.

Note

If you specify the domain name as a literal value, you must enclose it in quotation marks. See Example C-3 for an example.

Once you have an instance of the IGPMDomain interface, you can call a number of methods to connect to a particular GPO, create new GPOs, search for a particular GPO, or restore a GPO from backup. For example, to create a new GPO with the name Desktop Configuration Policy, you can create a simple WSH script in VBScript, as shown in Example C-3.

Set GPM = CreateObject("GPMgmt.GPM")
Set GPMDomain = GPM.GetDomain("cpandl.com", "", GPM_USE_PDC)
Set GPMGPO = GPMDomain.CreateGPO()
GPMGPO.DisplayName = "Desktop Configuration Policy"

The first two lines create the familiar IGPM instance and use it to call the GetDomain method to connect to the Active Directory domain (cpandl.com). The third line calls the CreateGPO method on GPMDomain and creates an instance of the IGPMGPO interface, which holds the reference to the newly created GPO. When the GPO is created, it is created with a generic friendly name of "New Group Policy Object," so in the fourth line we set the DisplayName property on the GPMGPO instance to the desired name.

The new GPO is created unlinked to any container object. To link the GPO to a container object, you must specify a scope of management (SOM) using the GetSOM method on the GPMDomain object we created earlier. GetSOM returns a reference to the IGPMSOM interface, and that interface has a CreateGPOLink method that creates the actual Group Policy link on the SOM you specified. For example, if we modify the script shown earlier, we can create the Desktop Configuration Policy and link it to the Marketing OU within the Active Directory domain called cpandl.com, as shown in Example C-4.

Set GPM = CreateObject("GPMgmt.GPM")
Set GPMDomain = GPM.GetDomain("cpandl.com", "", GPM_USE_PDC)
Set GPMGPO = GPMDomain.CreateGPO()
GPMGPO.DisplayName = "Desktop Configuration Policy"
Set GPMSOM = GPMDomain.GetSOM("OU=marketing,DC=cpandl,dc=com")
Set GPMLink = GPMSOM.CreateGPOLink(-1,GPMGPO)

Example C-4 differs from Example C-3 in the two additional lines at the end. The second-to-last line creates an instance of the IGPMSOM interface by calling the GetSOM method on the GPMDomain object. The parameter provided to the GetSOM method is the distinguished name (DN) of the container object you want to link to. This can be a site, domain, or OU. Site objects are stored within the configuration naming context rather than the domain naming context, so in the case of a site object the path to a site looks something like the following (where NewYork is the name of the site):

CN=NewYork,CN=Sites,CN=Configuration,DC=cpandl,DC=com

The last line of Example C-4 creates the GPO link on the SOM using the CreateGPOLink method of the GPMSOM object. The first parameter indicates the order the GPO link should appear on the container object. As you know, a container object can have multiple GPOs linked to it, and the order in which the GPOs are linked affects the processing precedence and thus the effective policy for the computers and users within that container object. Passing –1 to the CreateGPOLink method indicates that this GPO should be linked at the end of the list. Alternatively, you can link the GPO at a particular position by specifying that position in this parameter. The position numbering starts at 1, and if you specify a number that is greater than the number of GPO links that exist on that container object, an error will be generated. The second parameter is simply a reference to the GPO object that was created earlier in the script.

Unlinking a GPO is bit more complicated and involves a different set of interfaces. At a high level, you must first enumerate the links on a particular container (SOM) and then, after finding the correct link based on the GPO GUID, you delete the link using a method on the IGPMGPOLink interface. Example C-5 shows the process for removing the link on the Marketing OU for the Desktop Configuration Policy we created earlier in Example C-4.

Set GPM = CreateObject("GPMgmt.GPM")
Set GPMDomain = GPM.GetDomain("cpandl.com", "", GPM_USE_PDC)
Set GPMSOM = GPMDomain.GetSOM("OU=marketing,DC=cpandl,dc=com")
Set GPMLinkColl= GPMSOM.GetGPOLinks
For Each GPLink in GPMLinkColl
   If GPLink.GPOID="{5281266F-081E-4433-9218-22AEF9F313B0}" Then
      GPLink.Delete
   End If
Next

In Example C-5, the first three lines are familiar from Example C-4. Line 3 provides an instance of the IGPMSOM interface that references the Marketing OU for which we want to delete the link. In line 4, we use the GetGPOLinks method on the GPMSOM object to return a collection of a links on that Marketing OU. Because a container object such as an OU can have multiple GPOs linked to it, the collection returns each of the links as an array of items that can be iterated through. In fact, in line 5 that is exactly what we do: we use the VBScript For Each...Next loop to iterate through each link. The current link is stored in the variable called GPLink. In line 6, we use an If...Then statement to find the link to the GPO we’re interested in by using the GPOID property on that link object.

The GPOID must be the GUID of the GPO. A fast and easy way to find the GUID of a GPO is to use Gpotool, which is part of the Windows Server 2003 Resource Kit Tools. You use the following syntax with Gpotool to get the desired result:

gpotool /gpo:"GPOName" /domain:DomainName | find "Policy {"

GPOName is the friendly name of the GPO you want to work with, and DomainName is the name of the domain in which the GPO is stored. You pipe the output through the find command by using the search string "Policy {" to ensure that only the line of output containing the GUID of the policy is returned.

As an example, let’s say you want the GUID of the Default Domain Policy GPO in the cpandl.com domain. You use the following syntax with Gpotool to get the desired result:

gpotool /gpo:"Default Domain Policy" /domain:cpandl.com | find "Policy {"

The output returned contains the GUID of the Default Domain Policy GPO, as shown here:

Policy {31B2F340-016D-11D2-945F-00C04FB984F9}

You can also find the GUID of a GPO in the GPMC. Select the GUID, and then click the Details tab. The Unique ID field on the Details tab provides the GUID of the GPO, as shown in Figure C-2.

Figure C-2. Obtaining a GPO’s GUID using the GPMC

After we locate the correct GPO link by its GUID, line 7 uses the Delete method to remove the link from the SOM. Note that the GPO itself is not deleted—just the link to the SOM. In addition to creating and deleting links, you can manage the properties on a link. For example, you can enable and disable links and set a link to Enforced. For example, instead of deleting the link to the Marketing OU as we did in Example C-5, we can modify that script slightly to set the link to Enforced, as shown in Example C-6.

Set GPM = CreateObject("GPMgmt.GPM")
Set GPMDomain = GPM.GetDomain("cpandl.com", "", GPM_USE_PDC)
Set GPMSOM = GPMDomain.GetSOM("OU=marketing,DC=cpandl,dc=com")
Set GPMLinkColl= GPMSOM.GetGPOLinks
For each GPLink in GPMLinkColl
   If GPLink.GPOID="{5281266F-081E-4433-9218-22AEF9F313B0}" Then
      GPLink.Enforced=True
   End If
Next

Example C-6 differs from Example C-7 in the last line. Instead of deleting the Group Policy link, we set the Enforced property on that link to True.

The GPMC lets you manage security on GPOs by controlling which computers and users can process a particular GPO (referred to as security filtering) and which user groups can modify GPOs (referred to as delegation). You can also automate security management using the GPMC scripting interfaces.

The GPMC’s prebuilt scripts include two scripts for setting permissions on a GPO:SetGPOPermissions.wsf and SetGPOPermissionsBySOM.wsf. No prebuilt scripts are provided for listing permissions on a GPO, but you can easily accomplished this task by using the GPMC scripting interfaces. Example C-7 shows the script code that returns each permission entry on our Desktop Configuration Policy GPO object.

Set GPM = CreateObject("GPMgmt.GPM")
Set GPMDomain = GPM.GetDomain("cpandl.com", "", GPM_USE_PDC)
Set GPMGPO = GPMDomain.GetGPO("{5281266F-081E-4433-9218-22AEF9F313B0}")
Set Constants = GPM.GetConstants
Set GPMSecurity = GPMGPO.GetSecurityInfo

Wscript.Echo "Permissions on GPO: "+GPMGPO.DisplayName+VbCRLF
For Each GPMPermission in GPMSecurity
    If GPMPermission.Denied then
   AllowDeny = "Deny"
    Else
   AllowDeny = "Allow"
    End If
    If GPMPermission.Inherited then
   Inherit = "Inherited"
    Else
   Inherit = "Not Inherited"
    End If
    Select Case GPMPermission.Permission
      Case Constants.permGPOApply
        Perm="Read and Apply Group Policy"
      Case Constants.permGPOEdit
        Perm="Edit Group Policy"
      Case Constants.permGPOEditSecurityAndDelete
        Perm="Edit Group Policy, Modify Security and Delete Group Policy"
      Case Constants.permGPORead
        Perm="Read Group Policy"
    End Select
    Set GPMTrustee = GPMPermission.Trustee
    Trustee = GPMTrustee.TrusteeDomain+""+GPMTrustee.TrusteeName
    Wscript.Echo AllowDeny+", "+Inherit+", "+Trustee+": "+Perm
Next

Example C-7 might seem long, but most of the code is used to set up the output of the permissions themselves. Let’s look at what this script does. The first three lines should be familiar by now. Line 3 gets a reference to our Desktop Configuration Policy by using its GUID. (You could pass this into the script using a command-line parameter, of course, if you wanted to make the script more portable to other GPOs.) Line 4 is new. It calls the GetConstants method on the GPM object. GetConstants returns a reference to the IGPMConstants interface. This interface contains a set of properties that are used to manage various aspects of Group Policy from the GPMC scripting interfaces. For our purposes, we created this reference to leverage the permission constants that define the permission types that can be used on a GPO.

Line 5 calls the GetSecurityInfo method on the GPMGPO object. The GetSecurityInfo method returns the permissions on a GPO in the form of a reference to the IGPMSecurityInfo interface. The IGPMSecurityInfo interface contains methods that let you enumerate each permission on a GPO. In line 6, we use the VBScript Wscript.Echo command to create a header for our output that calls the DisplayName property on the GPMGPO object to display the GPO’s friendly name instead of the GUID in the output.

After setting up the header, we enter a For...Each loop to enumerate each permission on the GPO. The first line of the For...Each loop calls the Denied property on the GPMPermission object and tests for it to be true. A permission can be Allow or Deny, so we want to be able to know in the output if the permission is a Deny. If the Denied property is true, we set a variable called AllowDeny to "Deny"; otherwise, we set it to "Allow" .

In the next statement, we call the Inherited property on GPMPermission to determine whether the permission is inherited. In most cases, a normal permission on a GPO should not be inherited, but returning this information can be useful in determining whether a particular GPO has permission inconsistencies. After we populate the Inherit variable with information about whether the permission was inherited, we use a Select Case statement to iterate through the Permission property on the GPMPermission object and compare it to the constants related to permissions (for example, permGPOApply or permGPOEdit.). When there is a match on the Permission property with the appropriate Constants property, we translate those constants into something more descriptive for the output and store that in the Perm variable.

The next command, Set GPMTrustee = GPMPermission.Trustee, is used to obtain trustee information about the permission. The trustee is basically the "who" of the permission. That is, it specifies which user or computer group or other security principal has the permission. This is, of course, important information to have in our script. The GPMTrustee variable that is returned on this command is actually an instance of the IGPMTrustee interface, which has methods that let us extract the trustee information from the Trustee property on the GPMPermission object. In fact, in the next line, we create the Trustee variable and form the string that will display the trustee by calling the TrusteeDomain and TrusteeName properties on the GPMTrustee object. TrusteeDomain returns the NetBIOS form of the domain name, so in that command we create the trustee variable by concatenating the NetBIOS domain name with the username and separating them with a backslash () to display the trustee using the familiar domaingroup representation.

The next-to-last line in the script uses the Wscript.Echo command to output each permission to the screen or to the command line, using the variables that we defined within the For...Each loop. The Next command loops back to get the next permission and repeat the process. This script is best run using the command line–based Cscript.exe WSH processor because the script outputs each permission to the command shell if run that way. If it is run using Wscript.exe, each permission appears as a pop-up dialog box as the script is written, which is probably not as useful.

When the script is run, it returns a list of the permissions on a given GPO, as shown in Figure C-3.

Figure C-3. Viewing the output from the GPO permissions script