Setting the Stage for Your GPMC Scripts | Group Policy, Profiles, and IntelliMirror for Windows2003, WindowsXP, and Windows 2000 (Mark Minasi Windows Administrator Library)

Before getting too involved with GPMC scripting, let's take a minute or two and review some terms commonly used in Windows scripting documentation.

Scripts cannot communicate directly with the computer in the way that compiled languages such as C++ can. Instead, scripts rely on interfaces created by the developers of a Windows executable. The developer packages information about the executable ( properties ) and ways to control the executable ( methods ) into a tidy bundle called an object. Microsoft defines the structure of a Windows object in a set of requirements called the Component Object Model, and an object that meets these requirements is called a COM object .

Scripts communicate with a special type of COM object called an automation object . An automation object exposes an interface called IDispatch that is used by languages such as VBScript, JavaScript, Visual Basic, and so forth.

When you install the GPMC, the setup program registers a set of automation objects for managing GPOs. Collectively, these are called the GPMC scripting objects. Figure 7.1 shows the hierarchy of these objects.

Figure 7.1: The GPMC object model

The principal object in the hierarchy, the GPM (Group Policy Management) object, has a set of methods for creating the other objects. For example, the GPM object has a GetDomain method that returns a GPMDomain object that you can use to create and query GPOs in an Active Directory domain.

The object model contains the acronym SOM, which stands for Scope of Management, a GPMC term indicating a container that can have a link to one or more GPOs. A SOM is any container that can be linked to a GPO. This includes domain objects, site objects, and OUs.

Tip	You were briefly introduced to the concept of SOM in Chapter 2.

Several objects in the GPMC object model are identified as collections . A collection is a special automation object that contains a set of objects indexed by a sequence number. A typical collection has a method for counting the items in the collection and a method for enumerating items by index number and not much else.

VBScript has a For Each ... In ... Next function designed to handle constructs such as objects and collections. You can use For Each ... In ... Next to walk through the properties of an object or a collection one item at a time, displaying the properties of each item or using method calls to perform operations on the items as you enumerate them.

The GPMConstants object contains a variety of constants used by other objects in the GPMC model. For example, if you use a script to generate a report containing the settings inside a GPO, you must set a flag specifying whether you want an HTML report or an XML report. Rather than memorizing the integers representing the options for this flag, you can use the ReportHTML or ReportXML properties of the GPMConstants object.

Initial GMPC Script Requirements

Each GPMC script you write should start with at least two initial method calls, one to create a GPM object and one to create a GPMConstants object. Use the VBScript CreateObject method to create the GPM object. Use the GetConstants method of GPM to create the GPMConstants object. Here's the example syntax. You can use any name you like for the variable names :

 Set gpm = CreateObject("gpmgmt.gpm") Set gpmConstants = gpm.GetConstants

Many code samples from Microsoft use Hungarian notation, in which a prefix letter describes the variable type. For example, in Hungarian notation, the GPM object created by CreateObject would have a name such as oGPM. This book does not use Hungarian notation so that the variable names are easier to read.

Once you have a GPM object and a GPMConstants object, you can begin crafting scripts to query and manage GPOs. Let's look at a short example that uses the GetDomain method of GPM to create a domain object and then prints the properties of this object. The GetDomain method call requires three parameters:

A DNS Domain Name For now, let's hard-code a domain name by instantiating a variable called dnsDomain. In the examples, I'll use company.com, but you can certainly change the name to suit your tests, such as corp.com or corp.com.local.
The Dns Name of a Domain Controller from Which to Obtain GPO Information Leave this as an empty string ("") if you simply want to use the PDC Emulator.
A Flag That Controls Which Domain Controller to Use for Lookups The GPMConstant object defines three properties for this flag: UsePDC specifies to use the PDC Emulator, UseAnyDC uses any Domain Controller, and DoNotUseW2KDC uses any DC as long as it runs Windows Server 2003.

Here's the GetDomain syntax for using the PDC Emulator:

 dnsDomain = "company.com " set gpmDomain = gpm.GetDomain(dnsDomain,"",gpmConstants.UsePDC)

Once you have a GPMDomain object, you can print its Domain and DomainController properties using the WScript.Echo method as follows :

 WScript.Echo "This script uses " & gpmDomain.DomainController &_              " in the & " gpmDomain.Domain & _              " domain to obtain its GPO settings."

An underscore at the end of a line tells the VBScript interpreter to include the code on the next line in the method call. You do not need to enter the underscores if you type all code on a single line in your script editor.

To get an object representing a site rather than a domain, use the GetSitesContainer method of GPM. This method requires four parameters:

The DNS Name of the Forest Root Domain The forest root domain is the first Active Directory domain in the forest. If you don't know the name of the root domain, launch Active Directory Sites And Services, open the Properties dialog box for any object, and click the Object tab. The DNS name at the left of the Canonical Name field is the name of the forest root domain. For now, let's hard-code the forest root DNS name as follows: dnsForestRoot = "Company.com" .
The DNS Name of a Domain This is used in conjunction with the Domain Controller name in the next parameter. If you leave these two parameter null (""), the method uses the PDC Emulator in the forest root domain.
The DNS Name of a Domain Controller From this, you obtain GPO information.
A Flag This controls which Domain Controller to use for lookups.

The GetSitesContainer syntax that uses the PDC Emulator in the forest root domain looks like this:

 Set gpmSitesContainer =_ gpm.GetSitesContainer(dnsForestRoot,"","",gpmConstants.UsePDC)

Now use WScript.Echo to list the properties of the GPMSitesContainer object. The following code snippet uses the With End With function in VBScript to avoid typing the same object name over and over again.

 WScript.Echo "Here's a little information about the Sites container:" With gpmSitesContainer   WScript.Echo "The forest root domain is " & .forest & "."   WScript.Echo "This script obtains site settings from " & ._     DomainController & " in the " & .Domain & " domain." End With

With these preliminary objects populated , it's time to write some scripts. But first let's see how to make those scripts a little more portable.

Obtaining Domain DNS Names Automatically

Every Active Directory Domain Controller exposes a special LDAP (Lightweight Directory Access Protocol) object called RootDSE that contains information about the directory service hosted by the server. You can use Active Directory Services Interface (ADSI) code in a script to query RootDSE for the name of the Domain Controller's domain, the name of the forest root domain, and other useful information. Using this technique, you don't need to hard-code domain and forest names into your scripts.

You'll need to do a bit of string manipulation because RootDSE stores names in LDAP Distinguished Name format, whereas GPMC uses Fully Qualified DNS Names (FQDNs). VBScript has a Replace function that's useful in these situations, as the following code snippet shows:

 Set RootDSE = GetObject("LDAP://RootDSE") adsiDomain = RootDSE.Get("DefaultNamingContext") dnsDomain = ConvertToDNS(adsiDomain) adsiForestRoot = RootDSE.Get("RootDomainNamingContext") dnsForestRoot = ConvertToDNS(adsiForestRoot) Function ConvertToDNS(distinguishedName) 'Skip past the first "DC=" in the DN initialStrip = Mid(distinguishedName,4) 'Replace the remaining typeful prefixes with periods rs = Replace(initialSTrip,",dc=",".",1,-1,1) 'Return the FQDN to the calling program ConvertToDNS = rs End Function

The ConvertToDNS function starts at the leftmost element of the domain's distinguished name, skips the first typeful prefix, and then converts the remaining typeful prefixes to periods, which is the format used by DNS names.

Obtaining Basic Domain and Site Information

Let's put together everything we've seen so far into a script that lists GPMC domain and site information. This script is available on the Sybex website for this book.

Note	The script is called List_GPMC_Information.vbs .

 Set gpm = CreateObject("gpmgmt.gpm") Set gpmConstants = gpm.GetConstants Set RootDSE = GetObject("LDAP://RootDSE") adsiDomain = RootDSE.Get("DefaultNamingContext") dnsDomain = ConvertToDNS(adsiDomain) adsiForestRoot = RootDSE.Get("RootDomainNamingContext") dnsForestRoot = ConvertToDNS(adsiForestRoot) set gpmDomain = gpm.GetDomain(dnsDomain,"",gpmConstants.UsePDC) Set gpmSitesContainer =_ gpm.GetSitesContainer(dnsForestRoot,"","",gpmConstants.UsePDC) WScript.Echo "Here's a little information from the GPMDomain object:" With gpmDomain   WScript.Echo "This script uses domain controller " & .DomainController &_     "in the " & .Domain & " domain to obtain its GPO settings." End With 'The vbNL constant adds a blank line to the listing WScript.Echo vbNL WScript.Echo "Here's a little information from the GPMSitesContainer object:" With gpmSitesContainer   WScript.Echo "The forest root domain is " & .forest & "."   WScript.Echo "This script obtains settings from " & .DomainController & _                "in the " & .Domain & " domain." End With '=====Functions and Subroutines================ 'This function converts a DN to a FQDN Function ConvertToDNS(distinguishedName) 'Skip past the first "DC=" in the DN initialStrip = Mid(distinguishedName,4) 'Replace the remaining typeful prefixes with periods rs = Replace(initialSTrip,",dc=", .",1,-1,1) 'Return the FQDN ConvertToDNS = rs End Function

Here's a sample of the output from this script:

 Here's a little information from the GPMDomain object: This script uses W2K3-S3.company.com in the company.com domain to obtain its     GPO settings. Here's a little information from the GPMSitesContainer object: The forest root domain is company.com. This script obtains site settings from W2K3-S3.company.com in the     company.com domain.