GPMC Scripting

In April, Microsoft released the Group Policy Management Console (GPMC), which provides a Microsoft Management Console (MMC)—based UI for easy management of Windows Server 2003 and Windows 2000 Group Policy. The GPMC represents a big step forward in Group Policy Object (GPO) management capabilities as compared with Win2K's native tools. With the native tools, scripting GPO management is difficult. However, GPMC includes a set of scripting interfaces for automating many common GPO management tasks. Using these scripting interfaces, you can manage the Group Policy environment, including generating reports of GPO settings, creating and copying GPOs, and finding unlinked GPOs. Microsoft provides several GPMC scripts that cover many common scripting tasks. You can also create your own scripts to perform custom GPO management tasks.

Although you can manage Win2K domain-based Group Policies, GPMC runs only on Windows 2003 and Windows XP Professional computers. (For more information about GPMC's requirements and features, see "Windows Server 2003's Group Policy Management Console," July 2003, http://www.winnetmag.com, InstantDoc ID 39190.) You can download the GPMC from the Microsoft Download Center (http://www.microsoft.com/downloads/details.aspx?familyid=f39e9d60-7e41-4947-82f5-3330f37adfeb&displaylang=en). When you install the GPMC, the system creates a folder called Scripts, which contains all the prewritten GPMC scripts. On a Windows 2003 or XP client, this folder is in the %programfiles%gpmc directory. The main administrative scripts have a .wsf extension, which is one of the file formats associated with Windows Script Host (WSH). Scripts with the .wsf extension are XML-formatted files that can call other scripts written in VBScript or JScript, which means that one script can take advantage of both the VBScript and JScript scripting engines. For the scripts in this article, I use VBScript without relying on .wsf files.

The GPMC interfaces are implemented in gpmgmt.dll, which resides in the %programfiles%gpmc directory. Microsoft geared these interfaces toward automating the GPMC functions as well as managing GPOs. Thus, you can use the interfaces not only to script GPMC operations such as creating mapping tables for GPO migrations but also to query and modify GPOs. However, the GPMC interfaces don't let you read or configure policy settings within a GPO. For example, you can't create a script that enables the Remove Run from Start Menu Administrative Template policy within a GPO. This limitation is unfortunate; nonetheless, the GPMC interfaces still provide a level of automation that surpasses what has been available to date. Let's take a look at how to get started with GPMC scripting and how you can use the GPMC objects to perform various administrative tasks, such as retrieving permissions for a GPO and obtaining Resultant Set of Policies (RSoP) reports.

Getting Started with GPMC Scripting
Learning to write GPMC scripts is fairly straightforward. All GPMC scripts that you write will follow the same basic steps. As with most new objects that you use in the WSH environment, you first need to create instances of, or instantiate, the objects you want to use. In all GPMC scripts, the first object you need to instantiate is the GPM object. This object is the root object in the GPMC object model. You need the GPM object to access other GPMC interfaces, which then provide access to further capabilities. For example, you need the GPM object to access the IGPMDomain interface, which lets you create a reference to an Active Directory (AD) domain. After you have the reference to the AD domain, you can call IGPMDomain's GetGPO method to access the IGPMGPO interface and create a reference to a particular GPO that you want to manage. From here, the IGPMGPO interface contains methods and properties for managing that GPO. You can learn more about the GPMC object model in the Help file called gpmc.chm, which is in the Scripts folder. You can also learn about the object model in the Microsoft Developer Network's (MSDN's) Group Policy Management Console Reference at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/gpmc/gpmc/group_policy_management_console_reference.asp.

Another interface that you're likely to run across is IGPMConstants, which is a special interface in GPMC scripting. This interface provides a set of properties that represent GPO-related constants that you'll often need in your GPMC scripts. For example, suppose you need to set the permissions to control who can edit a GPO. You could use a complex set of file-system and AD ACLs to represent the Edit permission, but that approach would take a lot of code work. So, Microsoft provided the IGPMConstants interface to do the work for you. You can simply call the IGPMConstants interface's PermGPOEdit property to represent the appropriate permission. To access the IGPMConstants interface, you use the GPM object's GetConstants method. After using the GetConstants method to obtain a reference to the GPMConstants object, you can then use any of the GPMConstants properties within your scripts.

Listing 1 shows the code that you use to create the GPM and GPMConstants objects. Let's look at two sample scripts—GetGPOPerms.vbs and RSoPLogging.vbs—to see how you build on this code. Admittedly, these scripts aren't the most basic. I didn't want to duplicate the GPMC scripts that Microsoft provides.

Retrieving Permissions for a GPO
The script in Listing 2, GetGPOPerms.vbs, demonstrates how to use several GPMC objects to list the permissions for a GPO in a test domain. GetGPOPerms.vbs begins by instantiating the GPM and GPMConstants objects. Next, the script accesses IGPMDomain, a useful interface that lets you retrieve information about a domain and manage GPOs within it. To access IGPMDomain, you use the GPM object's GetDomain method, which returns a GPMDomain object. As callout A in Listing 2 shows, the GetDomain method takes three arguments. The first argument is the name of the domain that stores the GPOs you want to manage. The domain name must be the domain's DNS name (e.g., mycompany.net). As callout A shows, you can hard-code this argument's value in the script. Another approach is to have the scripts' users provide the domain name at the command line when they launch the script.

The second argument lets you specify which domain controller (DC) you want to use to connect to the domain. A null string ("") signifies that you don't have a DC preference, which means that the GetDomain method will use the PDC emulator. For the third argument, you specify the option you want to use to find a DC with which to connect. You have three options: GPM_USE_ANYDC, (use any available DC), GPM_USE_PDC (use the PDC emulator DC), or GPM_DONOTUSE_W2KDC (use a DC running Windows 2003). As callout A shows, GetGPOPerms.vbs uses the GPMConstants object's UseAnyDC property to specify the GPM_USE_ANYDC option.

After you connect to the domain, the real fun starts. As the code at callout B in Listing 2 shows, you use the GPMDomain object's GetGPO method to retrieve the GPMGPO object that represents the GPO for which you want to list the permissions. To use GetGPOPerms.vbs, you need to replace the domain name mycompany.net with the DNS name of your AD domain. Notice that the GetGPO method's argument is the GPO's globally unique identifier (GUID) and not the GPO's friendly name. In this script, I included the GUID for the Default Domain Policy that's present in every AD domain. This GUID is the same for all AD domains.

If the scripts' users will be providing the necessary GPO information at the command line, having them input the hard-to-type GUID might not be an option. An alternative is to have the users provide the GPOs' friendly names; you can then obtain the corresponding GUID by using the GetGPObyName function, which Microsoft provides in the lib_commongpmcfunctions.js file in the Scripts folder. GetGPObyName uses the IGPMSearchCriteria interface to search all the GPOs in a domain and, on matching the friendly name entered, returns a GUID that the script can pass to GetGPO. However, GetGPObyName is a JScript function. If you'd rather use VBScript, you can write a VBScript version of GetGPObyName or use the GetGPOs, GPOName, and GPOGuid methods in the IADsTools COM object, which is part of the Win2K Support Tools. For more information about these methods, see the article "Scripting with IADsTools," April 2003, http://www.winnetmag.com, InstantDoc ID 38286.

Next, the script uses the GPMGPO object's GetSecurityInfo method to retrieve the permissions for the GPO. The GetSecurityInfo method returns a reference to a GPMSecurityInfo collection object, which the script assigns to the GPOSec variable. The GPMSecurityInfo object contains the set of permissions assigned to the GPO. The script then iterates through the collection and uses the GPMSecurityInfo object's Count property to count and return the number of permission entries in the collection.

To retrieve each permission entry, the script uses the GPMSecurityInfo object's Item property, which returns a reference to a GPMPermission object. After the script assigns this reference to the Ace variable, the script uses the GPMPermission object's Trustee property to access the GPMTrustee object. By calling the GPMTrustee object's TrusteeName property, the script determines the name of the user or group assigned to the current permission, then assigns the name to the PrincipalName variable.

The code at callout C in Listing 2 uses a Select Case statement to determine the security right assigned to that user or group. A GPO can have five different security rights, as defined in the IGPMConstants interface. The Select Case statement contains these five rights.

The first line in the Select Case statement tells the VBScript runtime engine to compare the Ace.Permission value (i.e., the GPMPermission object's Permission property value) to each case. When the Permission property value matches one of the five security rights, the script assigns a user-friendly description of that permission to the Perm variable. Finally, the script uses WSH's WScript.Echo command to output the user's or group's name and permission to the console screen.

Obtaining RsoP Reports
A useful feature of the GPMC is its ability to perform Group Policy logging and Group Policy planning. Using the GPMC interfaces, you can programmatically obtain the results from Group Policy—logging and Group Policy—planning sessions. For example, to obtain the results from a Group Policy—logging session, you need to use RSoP Windows Management Instrumentation (WMI) providers.

RSoPLogging.vbs, which Listing 3 shows, demonstrates how you can use the RSoP interfaces to execute a logging query and create a logging report in HTML format. The first few lines in the script create the GPM and GPMConstants objects. Next, the script uses the GPM object's GetRSOP method to create an instance of the GPMRSOP object. This method takes three parameters, the first of which specifies the RSoP mode. As the code at callout A in Listing 3 shows, one way you can provide this mode is to use the GPMConstants object's RSOPModeLogging property. If you were performing an RSoP planning session, you would use the RSOPModePlanning property instead. The second parameter specifies the path to the WMI namespace in which previous RSoP data reside. In this case, the parameter is a null string because no previous data exists. The last parameter is always 0.

After creating an instance of the GPMRSOP object, the script sets two properties—GPMRSOP object's LoggingComputer and LoggingUser properties—for the RSoP logging query. The LoggingComputer property specifies the name of the target machine (in this case, myworkstation), whereas the LoggingUser property specifies the name of the target user (in this case, Darren). Next, the script executes the logging query by calling the GPMRSOP object's CreateQueryResults method, which has no parameters.

Finally, the script calls the GPMRSOP object's GenerateReportToFile method, which takes two parameters. The first parameter specifies the type of report to generate (HTML or XML). The script uses the Constants object's ReportHTML property to specify an HTML report. If you prefer to receive an XML report, you can use the ReportXML property instead of the ReportHTML property. The second parameter specifies the pathname for the report.

The GenerateReportToFile method can return a reference to the GPMResult object. The GPMResult object has two properties—Result and Status—that you can use to determine when the report has finished running or failed to run successfully. However, in RSoPLogging.vbs, the generation of the report is the last task, so you don't need to know when the report is done. (You'll know the report is done when the script finishes executing.) Thus, the script doesn't store the reference to GPMResult.

GPMC Opens New Possibilities
The new GPMC interfaces are extremely flexible, powerful, and fairly well documented by Microsoft. They provide a lot more control over the Group Policy infrastructure than the Win2K native tools. If you create custom scripts and use them in conjunction with the scripts that Microsoft provides, you can automate most GPO management tasks.