BWren's Management Space : Management Packs

SNMP Queries

Brian Wren — Wed, 21 Jan 2009 19:22:35 GMT

I recently help someone out getting a monitor working that uses the System.SnmpQueryProvider module in the System.Snmp.Library management pack to perform a query against an SNMP device. They were getting back an error message showing some cryptic characters in the community string. They were just providing simple text like "public" for the CommunityString parameter on the module, so this looked pretty strange.

After some research, it turns out that module wants the community string specified in Base64 format. Nothing special from the MP perspective – you just need to specify the Base64 equivalent of your community string in the CommunityString parameter rather than the simple text.

If you already have a means of converting a string to Base64, then you should be fine. If not, here’s bit of PowerShell that will do the conversion for you.

$communityString = 'public'
[System.Convert]::ToBase64String([System.Text.Encoding]::UNICODE.GetBytes($communityString))

If I run that code, I get the following value: cAB1AGIAbABpAGMA. Pasting that into the CommunityString parameter on the module should get you the results you want. Obviously, if you have a community name different than "public" you would paste that in and use the resulting converted value.

Update to the Maintenance Mode Sample MP

Brian Wren — Mon, 10 Mar 2008 17:59:32 GMT

Andrzej Lipka, a fellow consultant in Poland, took my maintenance mode sample MP and added some interesting features. Have a look at the specific post here. I also added a link to Andrzej's blog to my general list since he has some great posts on OpsMgr and SCCM.

Using Wildcards with the Windows Service Template

Brian Wren — Sat, 08 Mar 2008 10:25:20 GMT

The Windows Service template in the Operations Console lets you discover and monitor a Windows service by doing little more than typing in the service name. I was just talking with someone who had a situation where the name of the service includes the local computer name meaning that it's different on every computer. It's the same service and should be monitored as such - just a slightly different name on each agent. Unfortunately, the template won't allow us to provide a wildcard in the service name.

For those who are skilled with management pack authoring, you're probably not relying on the template anyway, and this wouldn't be too difficult of a task. As such, I'm going to write this post from the point of view of someone who primarily lives within the Operations Console. We do have to get exposed to a bit of XML in order to pull this off, but it really should be minimal.

First, let's understand what the Windows Service template does. It performs two functions: 1) creates a new class (aka target) for your service and 2) creates a discovery to find instances of that new class. The new class that the template created should be fine as is. We can provide the template with any name we want, and it doesn't have to have anything to do with the name of the service itself. The discovery is what we need to think about.

The discovery that the template uses is a special one specifically designed for finding a service, and it doesn't allow wildcards. We can replace that discovery with a WMI discovery module since we can pretty easily write a WMI query to find all services that match a certain criteria, and that criteria can include a wildcard. There is a module called WmiProviderWithClassSnapshotDataMapper in the Windows Library management pack that will work perfectly.

Let's go through this step by step. I have a virtual machine running under the beta of Hyper-V in Windows Server 2008. That includes a few services that start with the three letters "vmi". I know this is a bit of a difference scenario than I described above, but it will still illustrate the point of discovering services using a wildcard.

1. Walk through the Windows Template wizard as normal providing your wildcard string. Note that we are going to pass this off to WMI which uses % as a wildcard character, not *.

2. Export the management pack you just used for the template.

3. Open the XML file you just exported. Use an XML editor if you have one. Otherwise, you could use Notepad.

4. You have to locate the discovery you just created which can be a little tricky since the names generated by the Operations Console are pretty long and ugly. Probably the easiest method would be to search on the wildcard string you typed in.

5. The Discovery will look something like mine which I pasted below. The long ID strings will be different in yours, but the rest should be pretty similar. There's a lot going on here, but we're not going to have to worry about most of it. I highlighted in blue the parts that we're going to need to change, and that shouldn't be too intimidating.

<Discovery ID="ServiceStateProbePage_eaa08473602945a592b2a117b62c634f.DiscoveryRule" Enabled="true" Target="Windows!Microsoft.Windows.Computer" ConfirmDelivery="false" Remotable="true" Priority="Normal">
<Category>Discovery</Category>
<DiscoveryTypes>
    <DiscoveryClass TypeID="ServiceStateProbePage_eaa08473602945a592b2a117b62c634f" />
</DiscoveryTypes>
<DataSource ID="DS" TypeID="Windows!Microsoft.Windows.Win32ServiceInformationProviderWithClassSnapshotDataMapper">
    <ComputerName>$Target/Property[Type="Windows!Microsoft.Windows.Computer"]/NetworkName$</ComputerName>
    <ServiceName>vmi%</ServiceName>
    <Frequency>60</Frequency>
    <ClassId>$MPElement[Name="ServiceStateProbePage_eaa08473602945a592b2a117b62c634f"]$</ClassId>
    <InstanceSettings>
      <Settings>
        <Setting>
          <Name>$MPElement[Name="Windows!Microsoft.Windows.Computer"]/PrincipalName$</Name>
          <Value>$Target/Property[Type="Windows!Microsoft.Windows.Computer"]/PrincipalName$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="MicrosoftSystemCenterNTServiceLibrary!Microsoft.SystemCenter.NTService"]/ServiceName$</Name>
          <Value>$Data/Property[@Name='Name']$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="MicrosoftSystemCenterNTServiceLibrary!Microsoft.SystemCenter.NTService"]/ServiceProcessName$</Name>
          <Value>$Data/Property[@Name='BinaryPathName']$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="MicrosoftSystemCenterNTServiceLibrary!Microsoft.SystemCenter.NTService"]/DisplayName$</Name>
          <Value>$Data/Property[@Name='DisplayName']$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="MicrosoftSystemCenterNTServiceLibrary!Microsoft.SystemCenter.NTService"]/Description$</Name>
          <Value>$Data/Property[@Name='Description']$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="System!System.Entity"]/DisplayName$</Name>
          <Value>Hyper-V Services</Value>
        </Setting>
      </Settings>
    </InstanceSettings>
</DataSource>
</Discovery>

6. Modify the discovery to use the WMI discovery module. I highlighted in red the modifications you want to make. You could just copy and paste right from this pots into your management pack. Obviously, in that query, you're going to use your wildcard string as opposed to the vmi% that I used. All we're doing is changing out the module we're using as the data source for the discovery. Then we're replacing the parameters that we were passing to the old module to the parameters expected by the new one.

<Discovery ID="ServiceStateProbePage_eaa08473602945a592b2a117b62c634f.DiscoveryRule" Enabled="true" Target="Windows!Microsoft.Windows.Computer" ConfirmDelivery="false" Remotable="true" Priority="Normal">
<Category>Discovery</Category>
<DiscoveryTypes>
    <DiscoveryClass TypeID="ServiceStateProbePage_eaa08473602945a592b2a117b62c634f" />
</DiscoveryTypes>
<DataSource ID="DS" TypeID="Windows!Microsoft.Windows.WmiProviderWithClassSnapshotDataMapper">
    <NameSpace>root\cimv2</NameSpace>
    <Query>select * from win32_service where name like 'vmi%'</Query>
    <Frequency>60</Frequency>
    <ClassId>$MPElement[Name="ServiceStateProbePage_eaa08473602945a592b2a117b62c634f"]$</ClassId>
    <InstanceSettings>
      <Settings>
        <Setting>
          <Name>$MPElement[Name="Windows!Microsoft.Windows.Computer"]/PrincipalName$</Name>
          <Value>$Target/Property[Type="Windows!Microsoft.Windows.Computer"]/PrincipalName$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="MicrosoftSystemCenterNTServiceLibrary!Microsoft.SystemCenter.NTService"]/ServiceName$</Name>
          <Value>$Data/Property[@Name='Name']$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="MicrosoftSystemCenterNTServiceLibrary!Microsoft.SystemCenter.NTService"]/ServiceProcessName$</Name>
          <Value>$Data/Property[@Name='PathName']$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="MicrosoftSystemCenterNTServiceLibrary!Microsoft.SystemCenter.NTService"]/DisplayName$</Name>
          <Value>$Data/Property[@Name='DisplayName']$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="MicrosoftSystemCenterNTServiceLibrary!Microsoft.SystemCenter.NTService"]/Description$</Name>
          <Value>$Data/Property[@Name='Description']$</Value>
        </Setting>
        <Setting>
          <Name>$MPElement[Name="System!System.Entity"]/DisplayName$</Name>
          <Value>Hyper-V Services</Value>
        </Setting>
      </Settings>
    </InstanceSettings>
</DataSource>
</Discovery>

7. Import the modified management pack. If you get an error on import, then you made a mistake in the modification. Go back and export the management pack and try again.

8. Go to Discovered Inventory and change the target type to your class. Within a minute or two, you should start to see instances showing up.

Scheduling Groups of Objects for Maintenance Mode

Brian Wren — Thu, 28 Feb 2008 18:08:00 GMT

I was given a challenge recently to come up with a solution for an organization that wanted to suppress any alerts for certain computers and services during a particular time window every night. The particular set of objects and the times in question had to be manageable by the administrators - preferably from the Operations Console.

This is a great example for a few concepts, so this will be a pretty long post where I'll describe each step along the way. If you just want the answer, scroll to the link at the end for the sample MP. Otherwise, you should find some good information on the following concepts:

Launching a PowerShell script from a rule
Composing a rule made up of a data source and write action
Replacing explicit values in a rule with overrides
Creating a simple custom class

First of all, the obvious answer to suppressing alerts is to get those objects into maintenance mode. That way we not only aren't bothered by the alerts, but we can also remove this time window from any availability reporting. The questions that we're faced with though are:

How can we schedule maintenance mode on a regular basis?
How can we set maintenance mode for a set of objects?
How can we give control to the administrators through the Operations Console?

One answer for our challenge might be to write a Command Shell script to put an object in maintenance mode and then launch it from the Windows Scheduler. That would handle question 1, but it would leave us hanging on questions 2 and 3.

A very straightforward solution would be to create a group in OpsMgr. Instead of setting maintenance mode for a single object, the script could put each member of the group in maintenance mode. Administrators could easily populate the group with any objects that should be included in the maintenance window. Assuming we had a script that could do that group enumeration, question 2 is covered. In order to really address question 3, we would need to launch the script from an OpsMgr management pack instead of the Windows Scheduler and have the ability to overwrite critical parameters.

So that leaves us with two challenges - setting maintenance mode for a group of objects and creating a rule to launch the script from a management pack. Let's take them one at a time. First the script.....

Setting Maintenance Mode on a Group of Objects

We're going to need Command Shell in order to enumerate the group and set maintenance mode. I'm assuming that we're going to end up creating a rule calling powershell.exe as described in my previous blog post, so we're going to need to need the script to include the code to load the Command Shell snap-in and setup the connection to the management server. When we launch Command Shell from the menu, this is done automatically done for us.

The script should accept the group name as an argument and then enumerate all members of that group. In specific OpsMgr terms, that means that we need to enumerate the objects that are target of a Containment relationship with the group's class.

If we use the New-MaintenanceWindow CmdLet, then we would need to write a function to recurs through the group members and follow each group members down through its set of hosted and contained objects. Rather than use that CmdLet, I'm going to use the ScheduleMaintenanceMode method on the monitoring object class. That method includes an argument called TraversalDepth. A value of "OneLevel" means that only the object itself will be put into maintenance while a value of "Recursive" means that we will follow hosting and containment relationships all the way down the object tree setting maintenance mode on each object along the way. A middle ground would be nice where we could just address the second level of objects, which in our case would be the specific group members and not their contained objects, but that's a scenario we're going to have to address on our own.

I thus have two scenarios I want the script to support - setting maintenance mode for just the objects contained in the group and setting maintenance mode for those objects in addition to all of their contained objects. The second scenario is actually easier since we just execute ScheduleMaintenanceMode against the group with TraversalDepth set the "Recursive". For the first method, we're going to have the enumerate the group contents ourselves and then set maintenance mode for each one.

With all of that said, my script is below. Notice that I'm accepting as arguments the name of the group (not to be confused with the Display Name), the number of hours for maintenance, whether to include hosted objects, and the description. We'll make most of these overrideable on the rule so the administrator has control over them.

$groupName = $args[0]
$HoursInMaintenance = $args[1]
$IncludeHostedObjects = $args[2]
$Description = $args[3]
$CommandShellPath = $args[4]

Add-PSSnapin "Microsoft.EnterpriseManagement.OperationsManager.Client";
cd "$CommandShellPath"
.\Microsoft.EnterpriseManagement.OperationsManager.ClientShell.Startup.ps1

$api = new-object -comObject "MOM.ScriptAPI"
$api.LogScriptEvent("SetMaintenanceMode",100,4,"Maintenance mode set for all members of group: $groupName")

$startTime = (Get-Date).ToUniversalTime()
$endTime = $startTime.AddHours($HoursInMaintenance)

$group = get-monitoringClass -name $groupName | get-monitoringObject

if ($IncludeHostedObjects -eq $true) 
{
    $group.ScheduleMaintenanceMode($startTime,$endTime,"PlannedOther",$Description,"Recursive")
}
else
{
    $classContain = get-relationshipClass -name 'System.Containment'
    $relations = $group | get-relationshipObject | where {$_.SourceMonitoringObject -eq $group} 
    $groupMembers = $relations | foreach {$_.TargetMonitoringObject}

    foreach ($object in $groupMembers)
    {
        $object.ScheduleMaintenanceMode($startTime,$endTime,"PlannedOther",$Description,"OneLevel")
    }
}

Creating the Rule

The next question is how we're going to launch that script and give administrators control over the schedule. We could do that from the Windows Scheduler, but it would be more straightforward for the administrator if we put it into an OpsMgr rule. If we configure it correctly, we can allow our administrators to use overrides to control the schedule, length of maintenance mode, and whether to include contained objects.

Data Source

The rule will need a data source and a write action. Since we want to execute the script on a nightly schedule, System.Scheduler will be a perfect data source. There is one little trick with that data source though. It allows you to define multiple schedules that have a start and a stop time. In the context we are going to use it though, the stop time is ignored. It will have to be larger than the start time to prevent errors, but other than that it won't be used.

You could just use System.Scheduler unchanged in which case you'll get the benefit of the dialog box for setting multiple schedules. In that case, you would need to modify the rule itself to change the schedule though. Since I want to control it through overrides I'm going to limit us to a single schedule, and I'm going to have to set the parameters myself. The Start and End times are pretty obvious. The DaysOfWeekMask is a little confusing. This is the integer value of a bit mask with each day representing a single bit. If you're familiar with bit masks you won't have a problem. If not, just determine the appropriate value by using the following values for each day of the week: Su-1, M-2, T-4, W-8, Th-16, F-32, Sa-64. Just add up the values for the days you want the script to run. If you want all days of the week, they'll add up to 127. If you just want Sunday, the value is 1. Just Tuesday and Thursday would be 20.

With all of that said, here's a valid data source for running the script every day of the week at 10:00 pm.

To define overrides though, we have to create a new module type. Rather than using this data source directly in the rule, I'll create a data source allowing the StartTime and DaysOfWeekMask to be overriden. The rule will then use the new data source module. Notice in the data source below that I've changed the changed the values for <Start> and <DaysOfTheWeeMask> to overrideable values that will be provided by the rule itself.

<DataSourceModuleType ID="bwren.Maintenance.DataSource.Scheduler" Accessibility="Public">
    <Configuration>
        <xsd:element name="StartTime" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>
        <xsd:element name="DaysOfWeekMask" type="xsd:integer" xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>
    </Configuration>
    <OverrideableParameters>
        <OverrideableParameter ID="StartTime" ParameterType="string" Selector="$Config/StartTime$"/>
        <OverrideableParameter ID="DaysOfWeekMask" ParameterType="int" Selector="$Config/DaysOfWeekMask$"/>
    </OverrideableParameters>
    <ModuleImplementation>
        <Composite>
            <MemberModules>
                <DataSource ID="DS" TypeID="System!System.Scheduler">
                    <Scheduler>
                        <WeeklySchedule>
                            <Windows>
                                <Daily>
                                    <Start>$Config/StartTime$</Start>
                                    <End>23:59</End>
                                    <DaysOfWeekMask>$Config/DaysOfWeekMask$</DaysOfWeekMask>
                                </Daily>
                            </Windows>
                        </WeeklySchedule>
                        <ExcludeDates/>
                    </Scheduler>
                </DataSource>
            </MemberModules>
            <Composition>
                <Node ID="DS"/>
            </Composition>
        </Composite>
    </ModuleImplementation>
    <OutputType>System!System.TriggerData</OutputType>
</DataSourceModuleType>

Write Action

The write action is just a matter of launching our PowerShell script. We'll again need a new module type to handle overrides. That strategy has other benefits anyway, since we can put the complexity in the module type and keep the rule simple. That will make it easy to create other rules for other groups.

The module type using our script is shown below. I won't bother explaining all the details since you can get that from the PowerShell post. The formatting gets pretty screwed up here, so you might just want to have a look at it in the sample MP.

            <WriteActionModuleType ID="bwren.Maintenance.WriteAction.SetMaintenance" Accessibility="Public">
                <Configuration>
                    <xsd:element name="GroupName" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>
                    <xsd:element name="HoursInMaintenance" type="xsd:integer" xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>
                    <xsd:element name="IncludeHostedObjects" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>
                    <xsd:element name="Description" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>
                </Configuration>
                <OverrideableParameters>
                    <OverrideableParameter ID="HoursInMaintenance" Selector="$Config/HoursInMaintenance$" ParameterType="int"/>
                    <OverrideableParameter ID="IncludeHostedObjects" Selector="$Config/IncludeHostedObjects$" ParameterType="string"/>
                </OverrideableParameters>
                <ModuleImplementation Isolation="Any">
                    <Composite>
                        <MemberModules>
                            <WriteAction ID="WA1" TypeID="System!System.CommandExecuter">
                                <ApplicationName>%windir%\system32\windowspowershell\v1.0\powershell.exe</ApplicationName>
                                <WorkingDirectory/>
                                <CommandLine>-Command "& {.\SetMaintenance.ps1 $Config/GroupName$ $Config/HoursInMaintenance$ $Config/IncludeHostedObjects$ '$Config/Description$'}"</CommandLine>
                                <SecureInput/>
                                <TimeoutSeconds>30</TimeoutSeconds>
                                <RequireOutput>true</RequireOutput>
                                <Files>
                                    <File>
                                        <Name>SetMaintenance.ps1</Name>
                                        <Contents><![CDATA[
$groupName = $args[0]
$HoursInMaintenance = $args[1]
$IncludeHostedObjects = $args[2]
$Description = $args[3]

Add-PSSnapin "Microsoft.EnterpriseManagement.OperationsManager.Client";
cd C:\"Program Files"\"System Center Operations Manager 2007"
.\Microsoft.EnterpriseManagement.OperationsManager.ClientShell.Startup.ps1

$startTime = (Get-Date).ToUniversalTime()
$endTime = $startTime.AddHours($HoursInMaintenance)

$group = get-monitoringClass -name $groupName | get-monitoringObject

if ($IncludeHostedObjects -eq $true)
{
    $group.ScheduleMaintenanceMode($startTime,$endTime,"PlannedOther",$Description,"Recursive")
}
else
{
    $classContain = get-relationshipClass -name 'System.Containment'
    $relations = $group | get-relationshipObject | where {$_.SourceMonitoringObject -eq $group}
    $groupMembers = $relations | foreach {$_.TargetMonitoringObject}

    foreach ($object in $groupMembers)
    {
        $object.ScheduleMaintenanceMode($startTime,$endTime,"PlannedOther",$Description,"OneLevel")
    }
}
                                        ]]></Contents>
                                        <Unicode>true</Unicode>
                                    </File>
                                </Files>
                            </WriteAction>
                        </MemberModules>
                        <Composition>
                            <Node ID="WA1"/>
                        </Composition>
                    </Composite>
                </ModuleImplementation>
                <OutputType>System!System.CommandOutput</OutputType>
                <InputType>System!System.BaseData</InputType>
            </WriteActionModuleType>

Setting the Rule Target

With those modules created, we need a rule that includes each data source and specifies the required arguments. The biggest question is what to use as its target. Technically, we can target anything that will end up deploying to an agent with PowerShell and Command Shell installed. We only want a single agent to get it though. We also want to make sure that our target is going to be accessible to the server admins. The root management server typically has Command Shell installed, and this is a perfect candidate for this task. Chances are pretty good though that we don't want to give permission to our administrators to author rules against our RMS.

I had thought of targeting the group itself since, as described in another previous post the root management server "hosts" groups, so that's where the rule would get deployed. I had some issues with this working reliably though, and I also thought it might get a bit confusing.

The solution I went with was to create a new class based on ComputerRole called CommandShellProxy. This can serve as the target for any rules I want to create that launch a Command Shell script. I can give permission to different people to override rules targeted at it without giving them access to the rules and monitors directly targeting the RMS. As an added benefit, I stored the path to the PowerShell executable and the Command Shell snap-in so I don't have to hardcode those into the rule.

I did a simple registry discovery for my new class and targeted it at the Root Management Server class. The only criteria I'm using is determining whether Command Shell is installed. If you want to use something other than the RMS as your Command Shell proxy, all you would have to do is change that discovery.

I didn't bother pasting in the discovery XML since I've already cluttered up this post with enough code. You can have a look at it in the sample MP though.

End Result

Go to the bottom of this post for a link to the sample MP. You can go through the following steps to get it up and running:

1. Load the management pack

2. Add an object or two to the group Maintenance Mode Group 1.

3. Make sure that you are discovering the Command Shell Proxy by selecting Discovered Inventory. Then click on Change Target and select Command Shell Proxy from the list.

4. Go to the Authoring tab and look at rules for the target Command Shell Proxy.

4. Create an override on the rule Set maintenance mode - group 1, and set appropriate values for StartTime, HoursInMaintenance, IncludeHostedObjects, and Description. The allowable values for IncludeHostedObjects are $true and $false (those are the PowerShell variables for True and False. You could do a little script work to allow a boolean in the override and then convert appropriately if you really want).

I know this is a long and detailed post, but it seemed like a good opportunity to illustrate a few points. Hope it's helpful.

Management Pack Authoring Guide (Told you)

Brian Wren — Mon, 25 Feb 2008 04:33:20 GMT

Just a few days ago, I mentioned that the new Operations Manager 2007 Management Pack Authoring Guide was going to be released "very soon". Sure enough, it's been posted at http://download.microsoft.com/download/7/4/d/74deff5e-449f-4a6b-91dd-ffbc117869a2/OM2007_AuthGuide.doc.

This is the guide that all of us in the authoring community have been waiting on for some time. At 238 pages, it provides a ton of information on management pack concepts, structuring work flows, creating custom modules, etc. It also includes a complete reference on the XML schema of a management pack.

This is a first version of the authoring guide, and it will be getting updated with additional information. One topic with minimal information in this version is the details of writing a script in a management pack. I'm going to get out a blog entry out later this week on this topic to get some of the basics out there until the guide itself provides complete details on it.

Running PowerShell Scripts from a Management Pack - Part 1

Brian Wren — Thu, 21 Feb 2008 02:04:11 GMT

Considering all my work with OpsMgr management packs and my infatuation with PowerShell, it's surprising that I've never put the two together in a public forum. I keep meaning to, just don't ever seem to get there. I finally committed myself to this blog post while sitting at my local It's a Grind (that's a coffee house to all you Seattle Starbucks fans. It's a Grind was born in Long Beach, and I am fanatically loyal to my home town).

So here's the basic question - can I use a PowerShell script in an OpsMgr management pack? In other words, can I execute a PowerShell script from a rule, monitor, diagnostic, recovery, or task? The answer is absolutely you can, but there are some considerations to keep in mind. First let's cover those considerations, then we'll get to concepts and code. If you just want the modules to copy and paste into your MP, go ahead and jump to the end.

The biggest issue is that most of the servers in your environment don't have PowerShell installed. Rules and monitors sent to an agent are executed locally on the agent computer, and any executables must be installed prior to the agent attempting to use them. In the case of VBScript and JScript, we rely on cscript.exe being present, but that's a safe bet since it is automatically installed on all Windows machines. Powershell is obviously not installed by default, and even in Windows Server 2008 it's an optional feature. If you want to use a PowerShell script for a console task, then you're going to need to make sure that it is installed on the client workstation the task is being executed from. This is less of a concern though since, while PowerShell and Command Shell are not required for the OpsMgr User Interfaces, they are pretty strongly suggested.

There can also be some significant overhead from launching PowerShell. Go ahead and launch a PowerShell window and then have a look at Task Manager. Powershell.exe will probably be consuming something like 30 MB of memory which is about 5x the typical cscript.exe instance in my personal testing. This is not surprising considering all the rich functionality that PowerShell provides. My only point is to try to stay away from scenarios where you need to launch a PowerShell script every couple of minutes. I've heard the OpsMgr product team is working on some strategies to reduce this overhead, but until then you want to use PowerShell scripts where they don't have to be launched too frequently.

Concepts

The basic idea of running a PowerShell script is to use of the Command Executer modules to launch powershell.exe with your script. This is actually the method that quite a few of the scripts in existing management packs use - calling cscript.exe with these modules. The Command Executer modules will launch the executable of your choice, allow you to specify command line arguments, and allow you to specify the name and contents of one or more text files (which will obviously be your script). These text files are created on the agent prior to command execution, so you can be guaranteed they will be in place when your specified command is launched.

Have a look at Microsoft.Windows.ScriptProbeAction in Microsoft.Windows.Library for example. That module uses System.CommandExecuterProbe from System.Library. It specifies cscript.exe as the command to execute, provides the appropriate command line arguments such as /nologo and the name of the script, and then passes in the body of the script as a file. In order to execute Powershell, we really just need to figure out the command line required to launch PowerShell, execute a script, and then exit.

PowerShell Command Line

If you run powershell.exe /?, you get the command line arguments for PowerShell. To launch a command and exit, you use the -command argument, the invoke operator (&), and a command to execute. The example syntax given by that help is as follows:

powershell -command "& {get-eventlog -logname security}"

We're going to need that basic syntax but put it in a format that the management pack can understand. It won't handle that ampersand, and we're go to have to have to specify a path for the script. PowerShell demands a complete path to a script even if it's in the current directory. The Command Executer will drop the script to a temporary directory and then use that directory as its default when it executes the script, so we can assume the script will be located in the current directory. Assuming that we are going to use a parameter called ScriptName for the name of the script, then the command line in the management pack would look like the following:

-command "& {.\$Config/ScriptName$}"

If you're completely baffled by that syntax, here's a quick explanation. We replace & with & because OpsMgr interprets the & as a special character. We get away with that character in the script itself if we enclose the script in CDATA tags, but we can't use CDATA tags on our command line. $Config/ScriptName$ is a context variable. OpsMgr will replace the variable inside the dollar signs with its actual value at run time. Config refers to the parameters of the module, and ScriptName is the name of the parameter. Finally, the .\ just refers to the current directory. So, if we used MyScript.ps1 for the script name, we would end up running the following command:

powershell -command "& {.\MyScript.ps1}"

Implementing the Modules

Rather than write a specific rule that uses the Command Executer modules and includes the specific PowerShell complexity, it is way more valuable to create a couple of base modules that can be leveraged by rules, monitors, and tasks. A Data Source module that runs a PowerShell script on a timed basis and returns a property bag could be used for a rule, monitor, or diagnostic. Another Data Source module returning discovery A Write Action module that just runs a PowerShell script on demand to perform some defined action would support a task or recovery.

I'll provide the data source below. Given this it should be pretty straightforward to create a write action (hint - use System!System.CommandExecuter). You could also create a discovery module based on System!System.CommandExecuterDiscoveryDataSource.

<DataSourceModuleType ID="PowerShell.Library.PSScriptPropertyBagSource" Accessibility="Public">
    <Configuration>
        <xsd:element xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="IntervalSeconds" type="xsd:integer"/>
        <xsd:element xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="TimeoutSeconds" type="xsd:integer"/>
        <xsd:element xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="ScriptName" type="xsd:string"/>
        <xsd:element xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="Arguments" type="xsd:string"/>
        <xsd:element xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="ScriptBody" type="xsd:string"/>
    </Configuration>
    <ModuleImplementation>
        <Composite>
            <MemberModules>
                <DataSource ID="DS" TypeID="System!System.CommandExecuterPropertyBagSource">
                    <IntervalSeconds>60</IntervalSeconds>
                    <ApplicationName>%windir%\system32\windowspowershell\v1.0\powershell.exe</ApplicationName>
                    <WorkingDirectory/>
                    <CommandLine>-Command "& '$Config/ScriptName$"</CommandLine>
                    <SecureInput/>
                    <TimeoutSeconds>30</TimeoutSeconds>
                    <RequireOutput>false</RequireOutput>
                    <Files>
                        <File>
                            <Name>$Config/ScriptName$</Name>
                            <Contents>$Config/ScriptBody$</Contents>
                            <Unicode>true</Unicode>
                        </File>
                    </Files>
                </DataSource>
            </MemberModules>
            <Composition>
                <Node ID="DS"/>
            </Composition>
        </Composite>
    </ModuleImplementation>
    <OutputType>System!System.PropertyBagData</OutputType>
</DataSourceModuleType>

Writing the Script

For the write action, there's really nothing special about the script. Any working PowerShell script will be fine. If you need to return a property bag or discovery data from a data source though, you're going to need to use MOM.ScriptAPI just like in VBScript. PowerShell works fine with COM objects, so this is not a problem at all. The following line will create an object variable, and using it is pretty similar to how you did it in VBScript.

$api = new-object -comObject "MOM.ScriptAPI"

For example, below is a PowerShell script to output the name and size of a specified file as a property bag. This could be called from a rule or monitor that uses a condition detection to map the property bag information to performance data. While this is coded in PowerShell, the basic process is identical to a script

$file = Get-Item $args[0]
$api = New-Object -comObject "MOM.ScriptAPI"
$bag = $api.CreatePropertyBag()
$bag.AddValue($file.Name,$file.Length)
$api.Return($bag)

More Later

This should be enough information to get people off and running. I'd like to provide some more samples and thought of actually writing a library MP with a complete set of PowerShell modules. No hard commitment on that, but I'll do my best in coming weeks.

Dynamically populating component groups in Operations Manager 2007 Distributed Applications

Brian Wren — Sun, 27 Jan 2008 07:29:00 GMT

This is one I've been asked about several times and am finally getting around to blogging the answer. The Distributed Application Designer in Operations Manager 2007 makes creating and modifying distributed applications quite easy. You can create a component group with a few clicks and then drag in managed objects that are related to the application. What cannot be done with the designer though is create a component group that is automatically populated through a rule like you can do with Operations Manager groups.

To illustrate this point, note the distributed application below that represents a simple application with a farm of web servers. I created this using the Line of Business Web Application template. The component group Monster Island Web Application Web Sites includes all web sites serving the application. These were manually added to the distributed application by dragging the appropriate instances into the group. This is the way that distributed applications are typically built.

In this example, any web site called Gargantua should be added to the Web Sites component group. If a new web server is installed, then we would need to open the Distributed Application Designer and drag this new web site instance to the group. If we had a means to create a discovery for the component group though, then it would automatically be added once the new web site instance were discovered by Operations Manager.

Creating such a discovery is entirely possible and actually not all that difficult. You won't be able to use the Operations Console though, and you will need to be familiar with either the Authoring Console or working with management packs in XML. The basic strategy is to modify the GroupPopulator module for the component group to use a membership rule instead of using specific managed objects.

I'm going to use the Authoring Console to have a look at this discovery. Since I created it in the Operations Console, the name of it is going to be pretty ugly. If you have a large management pack, it might take a little searching to find the right item. The name will start with SC_, and it will have Microsoft.SystemCenter.GroupPopulator as a data source. Here's a look at the details of mine.

Note the IncludeList section which has two MonitoringObjectID entries. Those are the GUIDs of the two web sites that I added to the component group. If I was to drag a third site into the group, we would see that entry.

The goal is to replace that Membership Rule with one that uses include logic instead of specific instances. That way whenever the discovery executes, it will dynamically find appropriate objects to add to the component group. It turns out that the same GroupPopulator that this discovery is based on is used for regular groups in Operations manager. Groups have a nice wizard in the Operations Console for creating a population rule. An easy strategy is to create a temporary group using the logic we want, and then copying and paste that logic into the component group discovery.

For this example, I'll create a rule that includes all web sites with the name Gargantua. I created a dummy group called Temp Group in the Operations Console and used the wizard to create the logic shown in the figure below.

Viewing the discovery for that group in the Authoring Console, we see an Expression instead of an Include List. That's exactly what we want to go into our component group discovery.

In order to pull this off, you're going to need to edit some XML. First, export the management pack into an XML file where you can open it with an XML editor or the Authoring Console. The Authoring Console will launch your editor of choice if you click the Edit button, or you could just open the management pack itself if you're more comfortable with that. If you don't have an XML editor, then Notepad should work without much trouble. Launching it from the Authoring Console will load just the XML for the discovery in question, so it shouldn't be too daunting.

The XML for the group discovery is as follows:

<RuleId>$MPElement$</RuleId>
<GroupInstanceId>$MPElement[Name="UINameSpace236d6bdf988b4598979fb687226e0729.Group"]$</GroupInstanceId>
<MembershipRules>
    <MembershipRule>
      <MonitoringClass>$MPElement[Name="System!System.WebSite"]$</MonitoringClass>
      <RelationshipClass>$MPElement[Name="MicrosoftSystemCenterInstanceGroupLibrary6062460!Microsoft.SystemCenter.InstanceGroupContainsEntities"]$</RelationshipClass>
      <Expression>
        <SimpleExpression>
          <ValueExpression>
            <Property>$MPElement[Name="System!System.Entity"]/DisplayName$</Property>
          </ValueExpression>
          <Operator>Equal</Operator>
          <ValueExpression>
            <Value>Gargantua</Value>
          </ValueExpression>
        </SimpleExpression>
      </Expression>
    </MembershipRule>
</MembershipRules>

We only care about the section highlighted in blue. That's the part of the membership rule that we want to move to our component group discovery. We can simply copy it out and then paste it over the IncludeList section.

If we edit the component group discovery, then we get the following XML:

<RuleId>$MPElement$</RuleId>
<GroupInstanceId>$Target/Id$</GroupInstanceId>
<MembershipRules>
    <MembershipRule>
      <MonitoringClass>$MPElement[Name="System!System.WebSite"]$</MonitoringClass>
      <RelationshipClass>$MPElement[Name="MicrosoftSystemCenterServiceDesignerLibrary6062460!Microsoft.SystemCenter.ServiceDesigner.WebSiteGroupContainsWebSite"]$</RelationshipClass>
      <IncludeList>
        <MonitoringObjectId>{fea25c09-8877-dcf3-5f1a-a67a03ffb34d}</MonitoringObjectId>
        <MonitoringObjectId>{4dd57b21-d581-ad4e-36b5-eafc3eeb6994}</MonitoringObjectId>
      </IncludeList>
    </MembershipRule>
</MembershipRules>

In this case, the blue section is the one we want to overwrite with the Expression from the group discovery. If we do that, we get the following XML which we can then save back into the component group discovery rule:

<RuleId>$MPElement$</RuleId>
<GroupInstanceId>$Target/Id$</GroupInstanceId>
<MembershipRules>
    <MembershipRule>
      <MonitoringClass>$MPElement[Name="System!System.WebSite"]$</MonitoringClass>
      <RelationshipClass>$MPElement[Name="MicrosoftSystemCenterServiceDesignerLibrary6062460!Microsoft.SystemCenter.ServiceDesigner.WebSiteGroupContainsWebSite"]$</RelationshipClass>
      <Expression>
        <SimpleExpression>
          <ValueExpression>
            <Property>$MPElement[Name="System!System.Entity"]/DisplayName$</Property>
          </ValueExpression>
          <Operator>Equal</Operator>
          <ValueExpression>
            <Value>Gargantua</Value>
          </ValueExpression>
        </SimpleExpression>
      </Expression>
    </MembershipRule>
</MembershipRules>

If you save the management pack after this modification and then import it back into the management group, anytime a new web site is discovered with the name Gargantua it will be added to the Web Sites group in the distributed application.

The big thing to keep in mind if you use this strategy is that you can't use the Distributed Applications Designer for that application anymore. If you edit and save it, you're going to overwrite that custom discovery that you just created. Obviously, the best strategy would be to create the entire application using the designer and then performing your custom modification.

Exporting Management Packs

Brian Wren — Wed, 22 Aug 2007 19:33:35 GMT

Obviously, /a great way to learn how to author a management pack is to look at existing ones. The problem is that most of the interesting ones are sealed so you can't read the file, and the Operations Console won't allow you to export a sealed management pack.

This is actually very easy using Command Shell. You can export a single management pack or export the entire set of installed management packs from a management group. This is my personal favorite as I like to have the entire set of management packs available for my reference.

Command Shell is an optional component of the Operations Manager User Interfaces, so it's probably something you already have installed.

Exporting a single management pack

To export a single management pack, use the following command:

get-managementPack -name <Name of MP> | export-managementPack -path <Directory to store exported file>

For example, to export the SQL Library MP to a directory called c:\mp:

get-managementPack -name Microsoft.SQLServer.Library | export-managementPack -path c:\mp

Exporting all management packs

It's actually easier to export all management packs since you don't have to specify the -name parameter on the get-managementPack CmdLet. Just use the following, and you will fill c:\mp with the entire set of management packs installed in your management group.

get-managementPack | export-managementPack -path c:\mp

Update on 2/17/2008

I would be completely remiss if I didn't update this post to refer to Boris' PowerShell script that can convert an MP file to XML from a command line. Certainly easier if you need to convert a sealed management pack that you don't already have imported into a management group.

http://blogs.msdn.com/boris_yanushpolsky/archive/2007/08/16/unsealing-a-management-pack.aspx

Targeting Rules and Monitors

Brian Wren — Wed, 22 Aug 2007 19:33:12 GMT

The concept of what target to use for a particular rule or monitor in OpsMgr 2007 seems to be one that people are struggling with. The confusion is most prevelant among people who have had experience with MOM 2005 since the methods have completely in changed. In MOM 2005, you would apply rule groups to computer groups. If a computer was in the group, it would get the rule - it was that simple. In OpsMgr 2007, we do not use groups to target rules/monitors. What adds to the confusion though is that groups are available in the list of targets when creating a rule/monitor in the console. Let's see if I can explain this.

The main conceptual difference between MOM 2005 and OpsMgr 2007 in this respect is that in MOM 2005 we thought about which computer we would retrieve a particular piece of information from, and we targeted rules at groups containing those computers. We had to think about the individual agents and view the environment in terms of the physical computers being managed. We had formulas for the groups to identify which computers held different components, but we were ultimately targeting groups of agents. In OpsMgr 2007, we think about what component is generating the information. That’s a distinctly different concept and ultimately more powerful. OpsMgr will figure out which agents hold instances of that component, deliver the rule/monitor to the appropriate agents, and execute the rule/monitor for each instance.

In 2007, we also work against multiple instances of a class on a particular agent. In MOM 2005, we only had a single rule sent to the agent, and that rule had to do the enumeration. A good example is SQL databases. The SQL scripts in MOM 2005 were enormous because they had to enumerate the whole list of databases and other SQL objects every single time they executed. In 2007, we just apply those rules to the SQL Database class, and OpsMgr executes the rule for each database instance discovered.

How does a rule get to an agent?

For any particular rule/monitor, OpsMgr will enumerate all instances of the target class and apply the rule to each. If there are no instances of the target class on a particular agent, then the rule will do nothing. It's that simple.

If I can't target groups, why are they listed when I select a target for a rule?

Groups are classes just like any other. They’re singleton classes where the class and the instance are one and the same, but they are classes nonetheless which is why they show up in the list with all other classes. There are really very few circumstances where you will target a rule at a group though.

What if I do target a group?

You can apply a rule/monitor directly to a group, but it will execute against the group object itself. OpsMgr will not enumerate members of the group and apply the rule to each. Any rules targeted at groups will actually operate on the Root Management Server since groups have no host and unhosted objects are managed by the RMS.

How do I target some group of objects then?

To the specific question of how to get a particular rule/monitor to a subset of components, you have two basic options. Let’s say for example, you have a particular subset of web sites that you need a particular rule to apply. You could target that rule at the IIS 2003 Web Site class for example, but that would apply the rule to all instances of that class. It would probably apply to sites that you didn’t want.

Option 1 would be to create a new class and target the rule at the class. In the case of an IIS site, this would mean that you would need to go to the Authoring Console or raw XML and create a new class and discovery. That’s a more advanced solution that most customers will do and probably overkill anyway.

Option 2 is the create a rule target at the whole class and disable it. Create a group with the sites you want and create an override for that group to enable your rule. This might sound like a workaround, but it's a completely valid solution.

How do I know if I'm selecting the right target?

The easiest method to validate you are using a target that actually has instances is to use the Discovered Inventory view in the Operations Console prior to creating your rule/monitor. In the Actions pane is an option called "Change target type..." that will bring up the same Select a Target Type dialog box that you see when you select the target for a rule/monitor. This view will list all instances of the target class you select. You can validate which agents have an instance of that class and how many instances each has. If there are no instances listed, then the rule isn't going to do anything. If there are instances, then you not only be confident that the rule/monitor will execute on the agent, but you can also view the properties of the instance that will be accessible to any rules/monitors targeted at it.