1. Overview

This article describes a step-by-step procedure on authoring a custom PowerShell agent task targeting the F5 Management Pack in System Center Operations Manager (SCOM) 2007 R2. I will use the Authoring Console shipped with the System Center Operations Manager 2007 R2 Authoring Resource Kit (downloadable here) to create the override management pack defining the agent task. The procedure for authoring an agent task with SCOM 2007 SP1 would be similar, with the difference that the authoring tool would be the Authoring Console supporting SCOM 2007 SP1 (downloadable here) and some of the module types targeted by the agent task would be different.

The agent task that we’re going to create here for the F5 Management Pack as an example, will create an array of LTM Pool Member objects for an F5 device, using PowerShell. The same authoring concept can be extended to any generic scenario for creating a PowerShell agent task in SCOM 2007 R2.

 

2. Preliminary Steps

Make sure the F5 Management Pack is correctly installed on the SCOM 2007 R2 Root Management Server. In addition, you'll need to have the System Center Operations Manager 2007 R2 installed on the management server where you plan to author the override management pack described in this article, for implementing the custom agent task. For testing purposes it is also recommended to have at least one F5 device discovered, in order to run the custom agent task that we're creating.

Also, for a good understanding of the agent task implementation described in this article, some minimal SCOM Management Pack authoring skills are required as well as basic PowerShell programming skills. Since the agent task is targeting an F5 device and attempts to change the device configuration, by adding LTM Pool Members, make sure you have the necessary rights to perform this action on the F5 device.

For more information on F5 Management Pack related topics visit the F5 Management Pack Solution page here.

 

3. Authoring the Agent Task

At a high level here are the basic steps for creating the PowerShell agent task for adding an array of LTM Pool Members:

  • Create an override management pack (F5.Override.ManagementPack) referencing the F5 Management Pack. This override management pack will implement the custom PowerShell agent task.
  • Create a WriteAction Module Type (F5.WriteActionModuleType.AddLtmPoolMembers) containing the PowerShell script and override parameters needed for the agent task.
  • Create an Agent Task (F5.Task.AddLtmPoolMembers) as the actual task that would target the F5 LTM Pool object (for creating the LTM Pool Members in). This agent task will use (implement) the F5.WriteActionModuleType.AddLtmPoolMembers write-action module.
  • Save the F5.Override.ManagementPack and import it in SCOM 2007 R2.

The following sections will describe the step-by-step procedure for authoring the override management pack implementing the custom agent task for adding an array of LTM Pool Members.

 

3.1. Creating the Override Management Pack

  • Open the SCOM 2007 R2 Authoring Console and go to File > New... to create a new override management pack. Or you can open an existing override management pack if you already have one, referencing the F5 Management Pack. For the purpose of this article we'll just create a new override management pack.
  • In the New Management Pack window select Empty Management Pack and name the management pack F5.Override.ManagementPack, for example. Click Next.
  • Enter a display name (such as F5 Override Management Pack) and a description (optional) for the override management pack. Click Create.
  • In the SCOM 2007 R2 Authoring Console go to File > Management Pack Properties and choose the References tab. Click Add Reference... and browse to the location of the F5 Management Pack file(F5_ManagementPack.mp) located in the F5 Management Pack deployment folder (which by default is %Program Files%\F5 Networks\Management Pack). Select F5_ManagementPack.mp and click Open. Click OK in the override management pack window properties, when done.
  • Figure 1 shows the references required by the override management pack. All of them should be created by default except the F5_ManagementPack, which we just added in the previous step.
  • In the SCOM 2007 R2 Authoring Console save the changes by going to File > Save (or clicking the Save icon in the toolbar), and save the override management pack to the desired location (in our case we're going to save it in the same location where the F5_ManagementPack.mp file is located).

override-mp-properties

Figure 1 - The override management pack references

 

3.2. Creating the WriteAction Module Type for the Agent Task

  1. In the SCOM 2007 R2 Authoring Console select the Type Library section and under Module Types select Write Actions.
  2. In the Write Actions panel right click > New... > Composite Write Action... and choose a unique identifier for the Write Action. We'll name this F5.WriteActionModuleType.AddLtmPoolMember. Click OK.
  3. In the General tab enter the name for the module type ("LTM Pool Member Write Action Module Type") and description (optional) - see Figure 2.

write-action-module-type-general

Figure 2 - The Id, Name and Description of the Write Action Module Type

 

  • In the Member Modules tab click Add... and in the Choose Module Type window's list-view locate and select the Microsoft.Windows.PowerShellWriteAction type. In the Module ID text box enter F5.WriteAction.AddLtmPoolMembers. Click OK.
  • In the Member Modules tab select the F5.WriteActionModuleType.AddLtmPoolMembers and click Edit.
  • In the Configuration window enter AddLtmPoolMembers.ps1 for the ScriptName value and 60 for the TimeoutSeconds value.
  • In the Configuration window select ScriptBody and click Edit... An external editor window will open (Notepad) and inside the <ScriptBody></ScriptBody> tags copy/paste the PowerShell code shown in Code Snippet 1. This is the PowerShell script referenced by AddLtmPoolMembers.ps1 and we’ll refer to this script in the following sections simply as AddLtmPoolMembers.ps1.  This is the PowerShell script that eventually gets executed when the “Add LTM Pool Members” task will run.
param($mgmtAddress, $poolName, $targetAddresses);
 
# validate input parameters
if ([String]::IsNullOrEmpty($mgmtAddress)) { throw "Management address required." }
if ([String]::IsNullOrEmpty($poolName)) { throw "Pool name required." }
if ([String]::IsNullOrEmpty($targetAddresses)) { throw "Target addresses required." }
 
# trap and re-throw exceptions (if any), to correctly reflect task status on errors
trap [Exception] { throw $_; }
 
# get the F5 device connection info
$token = Get-F5.DeviceConfigurationToken $mgmtAddress;
 
# make sure we have a valid device configuration token
if ([String]::IsNullOrEmpty($token))
{
    throw "Invalid device configuration token. Run the Set-F5.DeviceConfigurationToken task and try again."
}
 
# split the comma separated value string into an array of items
$targetAddresses = $targetAddresses.Split("`,");
 
foreach ($member in $targetAddresses)
{    
    Write-Host "Adding LTM Pool Member $member to LTM Pool $poolName...";
    
    # add the LTM pool member
    #Add-F5.LTMPoolMember -DeviceIP $mgmtAddress -Pool $poolName -Member $member -Token $token;
    
    Write-Host "LTM Pool Member $member has been successfully added to the LTM Pool $poolName."
}

Code Snippet 1 - The PowerShell script within the <ScriptBody> tags of the write action module type (AddLtmPoolMembers.ps1 )

 

  • In the same external editor window (Notepad), immediately after the closing </ScriptBody> tag (the order is very important!) add the XML code describing the PowerShell snap-ins required by the script (see Code Snippet 2). These snap-ins are F5.Networks.ManagementPack and F5.Networks.iControl and are installed with the F5 Management Pack.
<SnapIns>
    <SnapIn>F5.Networks.ManagementPack</SnapIn>
    <SnapIn>F5.Networks.iControl</SnapIn>
</SnapIns>

Code Snippet 2 – The PowerShell snap-ins required by the AddLtmPoolMembers.ps1 script

 

  • in the same external editor window (Notepad), immediately after the closing </SnapIn> tag (the order is very important!) add the XML code describing the parameters needed by the script (see Code Snippet 3).
<Parameters>
    <Parameter>
        <Name>mgmtAddress</Name>
        <Value>$Config/mgmtAddress$</Value>
    </Parameter>
    <Parameter>
        <Name>poolName</Name>
        <Value>$Config/poolName$</Value>
    </Parameter>
    <Parameter>
        <Name>targetAddresses</Name>
        <Value>$Config/targetAddresses$</Value>
    </Parameter>
</Parameters>

Code Snippet 3 – The parameters required by the AddLtmPoolMembers.ps1 script

 

  • close the external editor window (Notepad) when done and save the content when prompted.
  • back in the Member Modules tab of the Write Action Module Types property window select the F5.WriteActionsModuleType.AddLtmPoolMembers and set the NextModule field to Module Output. The settings on the Member Modules tab should look similar to the ones shown in Figure 3.

write-action-module-type-member-modules 

Figure 3 - The Write Action Member Module settings

 

  • Go to the Configuration Schema tab and add the parameters of the Write Action Module Type, as shown in Figure 4.

write-action-module-type-config-schema

Figure 4 - The parameters of the Write Action Module Type configuration schema

 

  • Go to the Overridable Parameters tab and add the overridable parameters of the Write Action Module Type, as shown in Figure 5.

write-action-module-type-overridable-params

Figure 5 - The overridable parameters of the Write Action Module Type configuration schema

 

  • Go to the Data Types tab, check the This module outputs data checkbox and set the Data Type to System.BaseData (see Figure 6).

write-action-module-type-data-types

Figure 6 - The Output Data type of the Write Action Module Type

 

  • Go to the Options tab and set the execution options for the Write Action Module Type as shown in Figure 7.

write-action-module-type-options

Figure 7 - Execution options for the Write Action Module Type

 

3.3. Creating the Agent Task

  • In the SCOM 2007 R2 Authoring Console select the Health Model section and under Tasks select Agent Tasks.
  • In the Agent Tasks pane right click > New > Custom Task... and choose a unique ID for the agent task, for example F5.Task.AddLtmPoolMembers.
  • In the Agent Task Properties window select the General tab and enter a name for the agent task ("Add LTM Pool Members") and a description (optional), see Figure 8). Set the Target of the Agent Task to F5.LTM.Pool (see Figure 9).

agent-task-general

Figure 8 - Agent Task general properties

 

agent-task-target 

Figure 9 - Setting the Target for the Agent Task to F5.LTM.Pool

 

  • In the Configuration tab click on the Browse for type... hyperlink and in the Choose module type window look for the F5.WriteActionModuleType.AddLtmPoolMembers, defined in the previous section (see 3.2. Creating the WriteAction Module Type for the Agent Task). In the Module ID text box enter a module identifier, for example F5.WriteAction.AddLtmPoolMembers (see Figure 10). Click OK.

 

agent-task-module-type

Figure 10 - Setting the Module Type for the Agent Task to F5.WriteActionModuleType.AddLtmPoolMembers (see section 3.2)

 

  • In the Configuration tab verify that the parameters defined for the F5.WriteActionModuleType.AddLtmPoolMembers are correctly shown. Set the following values for the parameters (see Figure 11).:

mgmtAddress = $Target/Host/Property[Type="F5_ManagementPack!F5.Device"]/MgmtAddress$

poolName = $Target/Property[Type="F5_ManagementPack!F5.LTM.Pool"]/PoolName$

timeoutSeconds = 60

  • Click OK to save the Agent Task and conclude the configuration.

At this point the custom agent task should be properly set up. Save the F5.Override.ManagementPack (File > Save in the SCOM 2007 R3 Authoring Console). The last step would be to import the F5.Override.ManagementPack in SCOM 2007 R2. Open the SCOM 2007 R2 Management Console, go to the Administration section, select Management Packs, right click > Import Management Packs > Add > Add from disk... and browse to the location where the override management pack is saved, select and click Install.

 

 

5. Running the Agent Task

When running F5 device related agent tasks in SCOM 2007, we need to have an appropriate device configuration token created (or cached) for the specific device, in order to have a successful task run. This behavior ties into the "Authorization Roles and Groups" model of the F5 Management Pack, i.e. supporting various authorization roles and groups via Microsoft SCOM 2007, Active Directory, and F5 BIG-IP’s user authentication model. The F5 Management Pack includes built-in roles for discovery and device configuration and Microsoft Windows and Active Directory accounts can be correlated with BIG-IP user accounts via a one time device authentication (performed through an F5 Management Pack agent task action).

task-set-device-config-token

Figure 11 - Running the Set F5 Device Configuration Token agent task

 

In other words, prior to run any configuration related agent task against an F5 device (such as Rediscovery, Enable/Disable LTM Virtual Server, Enable/Disable LTM Pool Member, etc.) we have to make sure we have a valid device configuration token. This is accomplished by running the "Set F5 Device Configuration Token" agent task. In the F5 Device diagram view, select the F5 device > right click > F5 Device Tasks > Set F5 Device Configuration Token), where we’ll have to provide the device authentication credentials for the appropriate overrides (see Figure 11). These credentials will be mapped to the account running the agent task(s), making up a 'device configuration token'. This is a one-time deal and we don't have to set the device configuration token with every agent-task run, assuming that we will use the same (Windows/Active Directory) account running the agent task(s). If the device configuration token has been set up successfully, we should get an output similar to Figure 12, at the end of the Set F5 Device Configuration Token task run.

task-set-device-config-token-done

Figure 12 - The output for a successful run of the Set F5 Device Configuration Token agent task

 

Once we have the device configuration token (credentials) cached, we can finally run the Add LTM Pool Members agent task: in the F5 Device diagram view, expand the F5 device hierarchy and navigate to the desired LTM Pool, right click > F5 LTM Pool Tasks > Add LTM Pool Members. In the agent task property window set the appropriate override values (see Figure 13). The target LTM Pool Member addresses should be entered as a comma-separated value string, e.g. similar to “10.10.10.1:80, 10.10.10.2:80”.

task-add-ltm-pool-members

Figure 13 - Running the Add LTM Pool Member agent task

 

For a successful run of the Add LTM Pool Members task we should get an output similar to Figure 14.

task-add-ltm-pool-members-done

Figure 14 - The output for a successful run of the Add LTM Pool Members agent task

 

6. Conclusion

 

 

Creating a custom PowerShell agent task in SCOM 2007 R2 is not a trivial procedure, but it’s definitely made possible by the SCOM 2007 R2 Authoring Console with an acceptable degree of flexibility. Scripting the agent task PowerShell script, targeting F5 Management Pack objects (such as LTM Pool Members, LTM Virtual Servers, etc.) would require a couple of PowerShell snap-ins shipped with the F5 Management Pack: F5.Networks.ManagementPack and F5.Networks.iControl. These snap-ins allow to some extent a native API interaction (wrapped around iControl), programming against the F5 Device objects (LTM Pool Members, LTM Virtual Servers, etc.).

You download the override management pack discurssed in this article here: