Using WMI to Manage AD Replication in Windows Server 2003

Monitoring Active Directory (AD) replication is a crucial management activity, especially in large enterprise environments that have many servers and a complex replication topology. AD administrators often need to use different tools or UIs (e.g., Replmon, Repadmin, the Microsoft Management Console—MMC—Active Directory Sites and Services snap-in) to manage replication between various AD servers. A bridgehead server or other important AD server disappearing from the network because of network connection problems or a domain controller (DC) crash can seriously affect the replication topology. In this case, you might need to force a Knowledge Consistency Checker (KCC) execution to recalculate the replication topology. In some situations or environments, you might need to automate some typical AD management operations such as the KCC execution or force the replication of a specific naming context (NC) in response to some event. In Windows 2000 Server, these types of tasks are almost impossible to automate in a custom application without calling some specific AD Win32 APIs. However, Windows Server 2003 includes an AD replication Windows Management Instrumentation (WMI) provider that abstracts some KCC execution and replication APIs, simplifying some management operations. Let's take a look at the new AD replication WMI provider and its classes.

The AD Replication WMI Classes
The AD replication provider and its classes, which reside in the rootMicrosoftActiveDirectory namespace of the Common Information Model (CIM) repository, let you trigger KCC actions and retrieve AD replication information. Web Table 1 (http://www.winnetmag.com/windowsscripting, InstantDoc ID 40881) lists the classes and their properties. You can explore the rootMicrosoftActiveDirectory namespace and its set of classes by using CIM Studio, which is available at http://download.microsoft.com/download/.netstandardserver/install/v1.1/nt5xp/en-us/wmitools.exe. You can write a script that uses a WMI Query Language (WQL) query to gather AD replication information from these classes or to watch for AD replication events to occur.

For example, you can use the GenericEventAsyncConsumer.wsf script to submit the WQL query

Select * From  __InstanceModificationEvent  Within 10 Where  TargetInstance ISA  'MSAD_DomainController'

to poll a DC every 10 seconds for any modifications to that DC. MSAD_DomainController is an AD replication class that exposes DC properties. GenericEventAsyncConsumer.wsf is a script that I wrote to watch for any type of event monitoring specified by a WQL event query. For more information about how GenericEventAsyncConsumer.wsf submits an event query, see "Exchange 2000 SP2 WMI Updates," January 2003, http://www.winnetmag.com/microsoftexchangeoutlook, InstantDoc ID 27211.

Figure 1 shows partial output from running GenericEventAsyncConsumer.wsf with the WQL query above. At callout A, you can see that the DC isn't registered in DNS; at callout B, it's registered.

If you want to try using the script with the WQL event query to catch DC events in your environment, run the code on a local DC under any security context. (If you want to access the DC remotely, you must use an administrator security context because, by default, WMI grants remote access only to administrators.) While the script is running, force a change in the DNS registration state by deleting the DC's A record in your DNS. WMI will detect that the DC isn't registered in the DNS and send a notification to the script. The script will then display output that shows the DNS registration change.

WMIADRepl.wsf
GenericEventAsyncConsumer.wsf is designed to monitor any type of event based on a submitted WQL event query—it isn't dedicated to catching events from the AD replication provider. To manage AD replication and support all the features exposed by the AD replication classes, you need another of my scripts: WMIADRepl.wsf. I don't have room to show all of WMIADRepl.wsf here, but I've included excerpts, and you can download the entire script from http://www.winnetmag.com/windowsscripting, InstantDoc ID 40881.

When you run WMIADRepl.wsf, you specify on the command line a switch that tells the script which AD replication properties you want to update and methods you want to invoke. WMIADRepl.wsf uses the Windows Script Host (WSH) 5.6 XML command-line parsing feature described in "Secure Script Execution with WSH 5.6," August 2002, http://www.winnetmag.com/windowsscripting, InstantDoc ID 25644. After parsing the command-line parameters and establishing a connection to WMI, the script retrieves the WMI AD replication instances related to the command-line parameters you specified.

When you specify the /ReplPendingOp+ switch on the command line, the code that Listing 1 shows is executed. This code retrieves information about the replication tasks executing or pending execution on the DC by requesting all MSAD_ReplPendingOp instances. If one or more such instances are available, the script enumerates the collection. For each item in the collection, the script enumerates the properties of the MSAD_ReplPendingOp class, retrieves the property values, and calls the DisplayFormattedProperty() function to display the information on the screen as a list of properties per instance. The DisplayFormattedProperty() function is included in the DisplayFormattedPropertyFunction.vbs file, which you can download with WMIADRepl.wsf.

When you specify the /NC+ switch, WMIADRepl.wsf next retrieves MSAD_NamingContext instances. The scripting technique is basically the same as for the /ReplPendingOP+ switch. The code retrieves the MSAD_NamingContext objects, then enumerates them. For each instance, the code enumerates the MSAD_NamingContext class properties to retrieve and display the property values. Only the formatting of the information is different: The /NC+ switch code displays the information in several columns, so it doesn't call the DisplayFormattedProperty() function. Figure 2 shows sample output from the /NC+ switch code.

WMIADRepl.wsf's /ReplCsr+ switch code lists all inbound replication state information with respect to all replicas of a given NC. This section of code uses the same scripting technique as Listing 1 but with the MSAD_ReplCursor class. The code shows the distinguished name (DN) of each NC hosted on the DC along with the date and time of the last successful synchronization. It also shows the update sequence number (USN) of the NC, a 64-bit number that begins at 1 and increases by 1 each time a change is made to an AD object. Note that USNs on one DC change independently of USNs on other DCs, so the USN for the same NC on several DCs can have different values. For a better understanding of AD replication mechanisms such as USNs, see "Chapter 6 - Active Directory Replication" in Windows 2000 Server Distributed Systems Guide (http://www.microsoft.com/technet/prodtechnol/windows2000serv/reskit/distsys/part1/dsgch06.asp).

WMIADRepl.wsf's /DC+ switch code also follows the scripting technique that Listing 1 uses, but this time with the MSAD_DomainController class to retrieve the DC properties that Figure 1 shows. The Boolean values for the IsAdvertisingToLocator, IsGC, IsNextRIDPoolAvailable, IsRegisteredInDNS, and IsSysVolReady properties indicate the state of the DC and are useful for monitoring purposes.

You can use the /ReplNeighbor switch with WMIADRepl.wsf in two ways. If you specify no NC on the switch, as in

wmiadrepl.wsf /ReplNeighbor

the script displays a limited set of information for each available NC. If you specify an NC, as in

wmiadrepl.wsf /ReplNeighbor:  CN=Configuration,DC=LissWare,  DC=Net

the script displays the full set of information related to that NC. Listing 2 shows the code that handles both cases. The code displays MSAD_ReplNeighbor class property values, which expose the inbound replication state information for an AD NC and its source server. For example, the property values reveal whether the inbound replication is a scheduled replication, the source DC name, and the last synchronization result. Notice that the code in Listing 2 invokes the ErrorHandler() function to handle errors. This function is in the TinyErrorHandler.vbs file, which you can download with WMIADRepl.wsf.

The /ExecuteKCC switch leverages the MSAD_DomainController class's ExecuteKCC method, which, as its name suggests, forces the execution of the KCC. Among other things, the KCC calculates the replication topology (i.e., it calculates where to create the connection objects that establish the link for replication between DCs). The MSAD_DomainController class that exposes the ExecuteKCC method is a wrapper of the DsReplicaConsistencyCheck() API, so the method uses the same parameters as the API. Web Table 2 shows the values corresponding to the two method parameters, which are defined in constants at the beginning of WMIADRepl.wsf. To force KCC execution, you use the command

wmiadrepl.wsf /ExecuteKCC+

Web Listing 1 shows the ExecuteKCC method invocation.

The last switch is /SyncNC, which leverages another interesting method—the SyncNamingContext method exposed by the MSAD_ReplNeighbor class. You can use this method to force the replication of a specific AD NC. The MSAD_ReplNeighbor class is a wrapper of the DsReplicaSync() API, so the method requires the same parameters as the API. Like the ExecuteKCC method parameters, the SyncNamingContext method parameter is defined in a constant at the beginning of WMIADRepl.wsf. Web Table 3 shows the bitwise values that you can use to turn the associated bits on and thus determine the constant value passed as a parameter of the SyncNamingContext method. To force an NC replication, you use the command

wmiadrepl.wsf /SyncNC:  CN=Configuration,DC=LissWare,  DC=Net

Web Listing 2 shows the SyncNamingContext method invocation. To retrieve the NC to synchronize, the script executes a WQL data query with the NC that you specify on the command line to locate the NC's corresponding WMI instance.

AD Gets Easier
Managing directory replication isn't an easy task, whether you use AD or another directory. In Win2K AD, KCC limitations require some companies with many sites or domains to use some Active Directory Service Interfaces (ADSI) scripts to control KCC execution. (For more information, see the Microsoft article "How to Optimize Active Directory Replication in a Large Network" at http://support.microsoft.com/?kbid=244368.) In Windows 2003, Microsoft claims that KCC can handle as many as 5000 sites (up from 300 in Win2K) in a pure Windows 2003 forest. This scalability improvement and the AD replication WMI provider increase AD's manageability.

Win2K lets you use RepAdmin to force AD replication from the command line, but Windows 2003's exposure of replication properties and methods through WMI lets you develop on top of WMI your own customized logic from any type of application (e.g., WSH script; Visual Basic—VB—C, C++, or Windows .NET Framework application; enterprise management software such as HP OpenView for Windows). This new provider represents a huge step forward in both AD management and programmability that every administrator and developer will be pleased to exploit.