OpsMgr: R2 PowerShell Modules Example – DNS Resolution Monitor

While I’m finalizing some work on the Oracle SCX management pack,  I wanted to interrupt that series of posts to make a post walking through the use of one of the OpsMgr R2 PowerShell modules –something that I have been meaning to write up for some time.

The addition of native PowerShell modules was one of the major improvements in OpsMgr R2, and these modules collectively introduce an incredible degree of flexibility and improved efficiency in highly customized script-based monitoring.  There are a total of six PowerShell modules available in R2, and in this post, I will walkthrough an example using the Microsoft.Windows.PowerShellPropertyBagProbe module.   The monitor created in this example is a simple DNS resolution check that can be deployed to Windows agent-managed systems for perspective monitoring of DNS client resolution.

The example management pack can be downloaded here.

Management Pack, Class, and Discovery

Firstly, to build this monitor, a new management pack named DNSClientMonitoring is created. 

A class definition is then created for the DNS Client Perspective class, with a base class of Microsoft.Windows.LocalApplication.

An object discovery rule (filtered registry provider) is then created to discover this newly created class.  The discovery will be disabled by default, and enabled for specific systems with an override.  The discovery rule will discover the DNS Client Perspective class for any system that the rule is enabled for as long as the DNS Client Service is installed on the system.

Composite Data Source

In order to create the monitor, a composite data source is first required. 

The composite data source will accept as configuration parameters

• Interval  – interval in seconds
• RecursiveFQDN –  internal FQDN for testing recursive resolution
• ExternalFQDN – external FQDN for testing forwarded or Internet DNS resolution

All of these parameters will also be configured as overridable parameters.

A System.Scheduler module is then added to schedule the data source, simply accepting the Interval parameter as the defined interval.

This is followed by a Microsoft.Windows.PowerShellPropertyBagProbe module.

The PowerShell module requires several configuration items to be addresssed; skipping over the script body for the moment, the ScriptName and TimoutSeconds parameters first require values.  

In order to pass the configuration parameters for the FQDN’s to the script, the XML for the probe needs to be edited (with the “Edit” button in the Authoring console).  An XML element named “Parameters” is added between the ScriptBody and TimeoutSeconds elements, and individual “Parameter” elements are added underneath “Parameters.”  Each Parameter element requires a Name and Value element.  The name corresponds to the parameter name as defined in a PARAM block in the PowerShell script (i.e. param([string]$RecursiveFQDN,[string]$ExternalFQDN)).  The values will be supplied from the data source configuration parameters.

Now, back to the script body.   The PowerShell script used by this monitor is:

param([string]$RecursiveFQDN,[string]$ExternalFQDN)
$api = New-Object -comObject ‘Mom.ScriptAPI’

function fn_GetHost($sHostName){
$ErrorMsg = “”
 trap [Exception] {
      continue;
   }
$ips = [System.net.Dns]::GetHostAddresses($sHostName)
return $ips
}

$RecursiveErrorMsg = “”
$ExternalErrorMsg = “”

$RecursiveIPs = fn_GetHost($RecursiveFQDN)
if($RecursiveIPs -ne $null){
 $RecursiveResult = “OK”
}Else{
 $RecursiveResult = “Error”
 [string]$RecursiveErrorMsg = $error[0].Exception.Message
}

$ExternalIPs = fn_GetHost($ExternalFQDN)

If ($ExternalIPs  -ne $null){
 $ExternalResult = “OK”
}Else{
 $ExternalResult = “Error”
 [string]$ExternalErrorMsg = $error[0].Exception.Message
}

$bag = $api.CreatePropertyBag()
$bag.addValue(“RecursiveCheckStatus”,$RecursiveResult)
$bag.addValue(“RecursiveErrorMsg”,$RecursiveErrorMsg)
$bag.addValue(“ExternalCheckStatus”,$ExternalResult)
$bag.addValue(“ExternalErrorMsg”,$ExternalErrorMsg)
$bag

Remove-Variable bag
Remove-Variable api

While the syntax is a little different in PowerShell, a reference to the ‘Mom.ScriptAPI’ and Property Bag handling are created in a similar fashion to the WSH-based PropertyBagProbe module (note the bolded text in this script).   This script uses a simple function to test for DNS resolution for each defined FQDN with: the [System.net.Dns]::GetHostAddresses function.  Some basic error handling is added to facilitate passing the error message in the property bag in the event of a resolution failure.

Composite Monitor Type

After the creation of the data source, a composite monitor type is then required to handle the health state calculations.   This monitor type will accept the same configuration parameters as the data source, again configured as overridable parameters.

Two health states are defined to reflect healthy and error status.

The actual construction of the composite monitor type requires a data source module to reference the DNS test data source described above, as well as two System.Expression filter modules to detect healthy and error status. 

The monitor type configuration parameters are passed through to the data source configuration parameters.

For the two condition detection modules, the output of the property bag will be examined to filter for health states.  In XPATH queries, the property bag items can be access with the following syntax: Property[@Name='<NAME>’].  So, the condition detection ExpressionFilter modules that will determine the monitor health state will check both:   Property[@Name=’RecursiveCheckStatus’] and  Property[@Name=’ExternalCheckStatus’].   If both values equal “OK” the health state will be DNSResolutionOK.  If either value is not OK, then the health state will be set to DNSResolutionError.

Healthy state logic:

Unhealthy state logic:

And the regular detection data flow is then set.

Unit Monitor

Once the monitor type is created, creation of a monitor is the final step in the authoring process.   The monitor will target the DNS Client Perspective Windows Local Application class.

The custom DNS Test monitor type is selected and configured.

Health states are assigned:

An alert is configured, with alert text using the following syntax to reference property bag values: $Data/Context/Property[@Name='<NAME>’]$

Because this monitor requires the configuration of FQDN’s to monitor through overrides, I have disabled it by default.   When the overrides are created to define the test FQDN’s, the monitor can also easily be enabled with an override.

Using the DNS Resolution Monitor

Following the import of the management pack, two general steps must be executed to enable monitoring:

1) Override the DNS Client Perspective discovery to enable for desired watcher nodes
2) Override the monitor for each DNS Client Perspective node to define FQDN’s to test as well as enable the monitor

The discovery is enabled simply by overriding the DNS Client Perspective object discovery for specific Windows Computer objects to set the enabled property to “true.”

The monitor can be configured and enabled by overriding the properties of the “DNS Resolution Test” unit monitor for the specific DNS Client Perspective objects.   The enabled property should be set to “true” and the RecursiveFQDN and ExternalFQDN parameters can be set to the internal and external host names to test DNS resolution for.

Testing the alert: