Scripting Group Policy Objects

Group Policy has always been one of Active Directory's (AD's) big selling points, and in Windows Server 2003, Microsoft has greatly extended Group Policy Object (GPO) functionality and management through the release of the Microsoft Management Console (MMC) Group Policy Management Console (GPMC) snap-in. Because GPMC is a large, complex topic, you need to have a good understanding of the subject to get the most out of GPOs in your environment. For some background about GPMC and to download the snap-in, I recommend you read the Microsoft article "Enterprise Management with the Group Policy Management Console" (http://www.microsoft.com/windowsserver2003/gpmc) and the Group Policy Management Console Reference on the Microsoft Web site at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/gpmc/gpmc/group_policy_management_console_reference.asp.

The arrival of Windows 2003 opens the doors to some great new scripting opportunities, not the least of which is GPMC's support for automation. As a result, you can now script GPOs to perform common policy-based tasks. Let's review the basics of enabling and disabling a GPO; linking and unlinking a GPO from a site, domain, or organizational unit (OU); and configuring other options that you can automate within the GPMC.

Understanding GPOs
Policy-based administration lets an administrator configure detailed settings to define an environment for users and computers once, then rely on the system to enforce that state. Under Windows NT, creating such an enforceable environment was challenging, but AD's group policies simplify and extend the process and the options you can configure. You can even come up with your own ways of categorizing users according to the work they do and the roles they perform. As a result, whenever you add a new user to an AD group, you can trigger automatic configuration and software installation for that user in a way that's appropriate for his or her role. Each GPO can contain two parts—one that applies to a computer (e.g., a startup script or a change to the system portion of the registry) and one that applies to a user (e.g., a logoff script or a change to the user portion of the registry). GPOs can contain only computer policies, only user policies, or a combination of the two.

GPO creation is a standalone process. Then, through a process known as linking, you associate the GPO with one or more locations (i.e., local machines, sites, domains, OUs) in the AD tree that you want to receive the policy. You use the Group Policy Object Editor snap-in, formerly known as the Group Policy Editor (GPE), to edit GPOs. Group Policy Object Editor can manage only one GPO at a time, and you can't use it to link a GPO. For this reason, Microsoft developed GPMC.

With GPMC, you can perform almost any GPO-related task (including editing GPOs through Group Policy Object Editor) from one interface, as opposed to using Windows 2000's three or four tools. GPMC installs several COM objects that let you script 90 percent of your GPO management functions. It also installs a directory full of sample scripts that address many common administrative tasks. Another long-awaited feature now available is Resultant Set of Policies (RSoP), which lets you model and test GPOs. With RSoP, you can configure several different settings, including which container to process, which security groups to include, whether to use a specific site, whether to use loopback mode, and whether to use a specific Windows Management Instrumentation (WMI) filter. When you use RSoP, you ultimately end up with a Group Policy Object Editor—looking treeview of the settings to be applied by the GPO.

GPMC lets you manage Windows 2003 and Win2K-based domains. However, GPMC must run on a Windows 2003 or a Windows XP Professional Edition Service Pack 1 (SP1) machine that's running the Windows .NET Framework and the Quick Fix Engineering (QFE) update, which is an additional post-SP1 hotfix that the tool will install if it's not already present. For more information about QFE, see the Microsoft article "You Must Install a Hotfix to Install GPMC on Windows XP Professional" (http://support.microsoft.com/?kbid=326469). Although you can install the software on a computer that isn't a member of a domain, doing so has little practical use and the installer will let you know that the computer needs to be a member of a domain to make effective use of the tool.

Scripting Using GPMC
As we look through some scripting examples, keep in mind that GPMC's objects let you script GPO operations that are exposed within the GPMC tool but don't let you script a GPO's settings. To create a GPO, you must use Group Policy Object Editor—you can't use GPMC. When you create a GPO, its user and computer components are enabled by default: You can use GPMC to disable one or both of these components. DisableAll.vbs, which Listing 1 shows, is a simple script that disables both the user and computer components of a GPO in a domain. The script starts by using VBScript's CreateObject function to create a GPMC automation object and assigns it to the gpm variable. The script then uses the IGPM::GetDomain method to get a handle to the mydomain.mycorp.com domain.

The IGPM::GetDomain method takes three parameters. The first specifies the domain, the second is an optional parameter that lets you select a specific domain controller (DC), and the third signifies whether specific Windows 2003 or Win2K DCs can be used. I leave the second parameter as an empty string (i.e., I don't name a DC) and set the third parameter to 0, which together signify that the script should connect to the Flexible Single-Master Operation (FSMO) PDC Emulator role owner. Rather than hard-coding a DC into your script and discovering that the DC is unavailable when the script runs, you can select the FSMO PDC Emulator role owner to pick a DC that will likely be online at any time. As a result, AD has singled out the DC that's providing the FSMO PDC Emulator role (or the DC has been nominated by an administrator) to have one of the FSMO roles assigned to it, in this case emulating the PDC for earlier NT domains.

After the script connects to the domain, it uses the IGPMDomain::GetGPO method to return a GPO object and retrieve details about that GPO. The script relies on each GPO's globally unique identifier (GUID) to identify a particular GPO. Because we're automating the process of disabling a GPO's components, knowing which GPO you want to automate (rather than incorporating some form of search to find the GUID) seems reasonable. The challenge here is knowing which GUID to address. Fortunately, GPMC's sample scripts come with a listallgpos.wsf script that lists all the domain GPOs by name and GUID. After the script connects to the GPO of interest, it uses the IGPMGPO::IsUserEnabled property to determine whether the user portion of the GPO is enabled. If the user portion is enabled, the script uses the IGPMGPO::SetUserEnabled method to disable the user component by passing it a value of FALSE. The script then proceeds to test and disable the computer component of the GPO in the same way. You can easily modify Listing 1 to disable only the user component or computer component. You can also modify the script to enable the relevant parts by simply changing the main lines as follows:

If Not gpmGPO.IsUserEnabled Then   gpmGPO.SetUserEnabled TRUEEnd If

Linking GPOs to an AD Tree
As I mentioned earlier, GPOs apply only when you link them to local machines, sites, domains, or OUs. To link a GPO to an AD tree, we must specify the location that we want to manage—in GPMC terms, this process is known as the scope of management (SOM). Because Windows 2003 and Win2K apply GPOs according to a set order, linking a GPO to the SOM lets us account for that order, if necessary. For example, we can link a GPO to position 4 out of 7. Then, if another GPO link occupies the specified position, the method inserts the new link ahead of the old link and moves the old link and all subsequent links in the list down by one.

Imagine that we want to link a GPO to an OU in a domain and we know both the GPO and the OU to which we want to link. Listing 2 shows you how to link a GPO to an OU. The script starts off the same as Listing 1, by getting a handle to both the domain and the GPO. Next, the script uses the IGPMDomain::GetSOM method to retrieve a SOM object. To link a GPO to an OU, the script must pass in a Fully Qualified Domain Name (FQDN) to the OU that we're targeting. After the script connects to the correct SOM, we can use the IGPMSOM::CreateGPOLink method to link the specified GPO to the SOM. The first parameter for this method lets us specify a position in the list of GPOs that are linked to that particular SOM. The second parameter is the GPO handle that we retrieved earlier.

In Listing 2, the script passes a value of -1 for the first parameter, which identifies that we want to append the GPO to the end of the list that Windows 2003 and Win2K use to order GPOs. Be careful when inserting a GPO into a certain position—if the position you specify is greater than the current number of GPO links, the method will fail. I recommend using the IGPMSOM::GetGPOLink method to return a GPOLinksCollection object, then using the IGPMGPOLinksCollection::Count property to count the number of items.

To link a GPO to a domain rather than an OU, you use the IGPMDomain::GetSOM method to pass in an empty string.

Set gpmSOM = gpmDomain.GetSOM   ("")

Linking to sites is just as easy as linking to a domain. Listing 3 shows a modified version of the script in Listing 2 that links GPOs to sites. Listing 3 starts the same way as Listing 2, by getting a handle to the domain so that we can retrieve a link to a specific GPO. However, the script then uses a great new interface called IGPM::GetConstants to access the values of key constants. As a result, we don't have to use Const lines to declare any GPMC constants in our script because we can dynamically retrieve these constants as the script executes. The IGPM::GetConstants method also provides a degree of future-proofing, if Microsoft ever decides to change the value of these constants. Next, the script uses the IGPM::GetSitesContainer to get a handle to a GPMSitesContainer object so that we can connect to a particular site. This method uses four parameters. The first parameter is the full DNS name of the root domain for the forest in which the site of interest exists. The second parameter is an empty string that the method uses to signify that we're not specifying a particular domain so that the script will use the forest root domain instead. (If we were specifying a particular domain, we'd need to use the domain's DNS name.) The third parameter is an empty string that the method uses to signify that the script should use the forest root domain PDC instead of searching for the NetBIOS or DNS name of any specific DC to use. The fourth parameter passes in the IGPMConstants::UseAnyDC constant to confirm that the script should use the FSMO PDC Emulator role owner as the DC. If we had specified a particular DC in the third parameter, the value for the fourth parameter would have had to be 0. Next, the script uses the IGPMSitesContainer::GetSite method to get a handle to the SOM for the specific site. The only parameter to pass in is the site name. As a final step, the script uses a method similar to the method Listing 2 uses to link the GPO to the site. However, this last step is slightly more long-winded because we need to connect to both the GPMDomain object to get a handle to the GPO and connect to the GPMSitesContainer object for linking purposes.

Beyond the Basics
Although this article only touches on the basics of what's possible with GPMC, you can accomplish many other GPO-related automation tasks. In addition to the scripts presented here to disable a GPO and link a GPO to an OU, domain, or site, the large number of sample scripts provided with GPMC provide a good starting point for addressing many common administrative tasks.