SCOMHelper PowerShell Module - A SCOM Admin’s Best Friend
*Note: after today (2019/06/19) I will no longer have access to update this blog. Check the PowerShell gallery (PSGallery) for updates.
(installation instructions at bottom)
There are a number of cool scripts that I’ve collected, borrowed, and written in my travels as a SCOM field engineer and PowerShell enthusiast. I decided to put them all together into one module for easier maintenance and use. Enjoy.
SCOMHelper Module Functions:
New-SCOMClassGraph
First and foremost my pride and joy is this brilliant work of art. I’m pretty sure I just tweaked my own arm patting myself on the back but you know what, I am really proud of this. This is a first of its kind tool (that I know of) for generating a graphical representation of a SCOM class. It will create a graphical structure (.png) that represents SCOM class taxonomy, all properties, hosting and discovery relationships for a SCOM class. This function relies on a few other brilliant modules but don’t worry, this function will automate the other module installations for you. (This is assuming you have connectivity to the interwebs. Yes, interwebs. Otherwise you will have to obtain the dependencies manually.) This tool will prove to be priceless for any SCOM admins, enthusiasts, and most importantly, MP authors, both new and seasoned.
Note: This function requires PowerShell v5 or greater due to some other module dependencies. Tested with SCOM 2019, 2016, 2012 R2.
Feed this function one or more of the following: a class object, class Name, class Display Name, or class ID, and it will do the rest. There are a few neat parameters to control caching of graphics files, include/exclude related class discovery workflows, and displaying the new graph file.
Examples:
Below is an example of class: Microsoft.SQL.Server.2014.DBEngine. The legend is shown on the top right of the graphic to help you understand the relationships between boxes.
The orange boxes represent classes that are HOSTing those connected below it.
The green boxes are hosted classes, which means they hosted by the orange class box connected above it. (see ‘orange’ definition above).
Orange arrows also help indicate a hosting relationship
The blue boxes represent discoveries which are capable of discovering those classes which are connected (along with the properties listed in blue).
The purple boxes represent ordinary abstract classes. Note: other colored boxes may also be abstract.
The remaining boxes and arrows represent ordinary class lineage (parent –> child) relationships.
Awesome. I know.
( References: Relationships, Understanding Classes and Objects, SCOM Fundamentals )
1)
New-SCOMClassGraph -ClassName 'Microsoft.SQLServer.Windows.Database'
2) This is a much fancier way to accomplish the same thing as Example 1, above, but with the help of GridView to select the class. This command will get all SCOM classes in the management group and select Name, DisplayName, and ManagementPackName to be presented in GridView for easy browsing and selection by the user. Select one or more classes from the Grid View, click OK. In the example below I’ve filtered on keyword “SQL” and selected a single line item. This selected class name gets piped into the function: New-SCOMClassGraph. The resulting graph (.png file) is shown above in Example 1.
Get-SCOMClass | Select Name,Displayname, @{N='ManagementPackName';E={$_.Identifier.Domain[0]} }| Out-GridView -PassThru | New-SCOMClassGraph
The graph file opens with your default ‘.png’ application. Your default viewer might be Internet Explorer, it might be Picture Viewer. You decide. Just be sure to associate .png file type to a default viewer.
You can optionally use the -ShowGraph:$false parameter to prevent the opening of the .png file. You might leverage this feature if you simply wanted to cache all of the files on disk without opening them. I did this in my lab and it took 45 minutes to generate 1688 graphs for a total of 276MB.
2) This is an example of piping a class object into the cmdlet:
Get-SCOMClass -Name 'Microsoft.SQLServer.2012.Publication' | New-SCOMClassGraph
You can even display multiple classes on a single graph with the '-Combine' parameter. Show below are two classes on the same graph:
Get-SCOMClass -Name 'Microsoft.SQLServer.Windows.ResourcePool','Microsoft.SQLServer.Windows.Database' | New-SCOMClassGraph -Combine
Start-SCOMOverrideTool
This tool is designed to make it easier to manipulate overrides and do a few other admin tasks:
- Bulk enabled/disable workflows for their target class
- Bulk delete overrides
- Bulk move overrides between unsealed management packs
- Remove all obsolete references in all unsealed packs
- Backup all unsealed management packs
- Create a new override management pack
Ideally normal overrides should be stored in a "buddy pack" directly related to the "base" MP of the affected workflow. (see this article: https://blogs.msdn.microsoft.com/tysonpaul/2016/05/24/how-to-correctly-create-an-override-for-a-scom-workflow/ ) Most of the time it seems that overrides are stored randomly in various unsealed packs with no system of organization. This tool can help get you organize your environment as well as quickly tune workflows in bulk/batches.
This tool can enable or disable a workflow by either deleting an existing
override or creating a new override to accomplish the desired effect. (The Enable
and Disable actions only affect the workflow Target class.)
This tool can also move (or relocate) an existing override to a different
unsealed management pack.
This tool doesn't technically "move" the override. It deletes the original
override and creates a new override in the destination MP. Only valid
candidates/overrides will be presented for selection. A valid candidate is
one that does not reference or depend on any other objects (workflows, targets)
contained within the same original unsealed MP.
Example: Overrides that might affect custom groups in the same MP would be ineligible.
For all operations that modify or change any management packs, all activities/actions
are written to the logfile and unsealed packs are backed up prior to any changes.
For Enable/Disable operation:
Typically the procedure would be as follows:
1) Select any number of "source" unsealed packs.
Only workflows (Rules/Monitors/Discoveries) from these packs will be presented for selection.
2) Select a "destination" unsealed pack into which to store any *necessary (new) override(s).
3) Select action type: Enable or Disable
4) Select 'type' of workflow(s) you wish to enable/disable: Rule, Monitor, or Override
5) Select any quantity of workflows.
6) Confirm to initiate the enable/disable action
*Note: a) In some cases an override might already exist which must be deleted to result in the
desired effect (enable/disable).
b) Enable/Disable actions only affect the workflow Target class.
For a "Move" operation:
Typically the procedure would be as follows:
1) Select any number of "source" unsealed packs from which to select overrides.
2) Select any number of eligible overrides from that set of source packs.
3) Select a "destination" unsealed pack into which to move the override(s).
4) Initiate the move.
You may select one or more 'source' MPs to limit the results shown
during the override selection process. This is effectively a way to
filter the overrides. Otherwise ALL valid overrides from ALL unsealed
MPs will be presented in the selection window. See menu details below.
*This tool does not currently move any overrides related to SecureReference,
Diagnostic, or Recovery objects.
Example: Bulk select workflows to disable:
Show-SCOMPropertyBag
This nifty function will neatly display your property bags when testing PowerShell scripts.
Ordinarily the property bag output test format would look like this (multiple bag output shown):
With this function, they will output like this.
In addition, you get a structured PowerShell object to do with as you please. An example of how to access the PB data in the resulting hash table object:
# Store property bag(s) in variable as hash table
$var = Show-SCOMPropertyBag -FilePath C:\test\MyTestPB_script.ps1 -Format HashTable
# Display property bags (basic summary table)
$var.values
# Display value in detail example
$var[1][3].Value
Clear-SCOMCache
This one’s pretty obvious. Will clear the agent cache and restart the HealthService (Microsoft Monitoring Agent) on the local machine.
Disable-SCOMAllEventRules
As you may know, collecting events with SCOM is mostly useless and often times results in performance problems and data bloat in the DBs. This will disable all event collection rules for the designated sealed management pack(s).
Feed this function one or more sealed management pack objects and it will create a corresponding unsealed pack for each in which it will store overrides which disable any/all event collection rules that are currently enabled. The resulting overrides will target the workflow class target.
Note: This will heavily tax your management server and Operations database during creation of the overrides. However, once the override files are created, they can be exported and imported wherever they are needed. You might consider running this in your Test environment first, then exporting the override packs to import into your production environment.
Example from my lab machine. The CPU was pegged for a while.
# -------------------------- EXAMPLE 1 --------------------------
# Disable all event collections found in the designated MP. Overrides stored in specific override pack.
Disable-SCOMAllEventRules -ManagementPack (Get-SCOMManagementPack -Name 'Microsoft.Windows.Server.2012.Monitoring')
# -------------------------- EXAMPLE 2 --------------------------
# Disable all event collections found in the designated MPs. A specific override pack will be created for each base pack.
Disable-SCOMAllEventRules -ManagementPack (Get-SCOMManagementPack -Name @('Microsoft.SQLServer.2012.Mirroring.Discovery','Microsoft.SQLServer.2008.Discovery') )
# -------------------------- EXAMPLE 3 --------------------------
# Create an array of MP names.
$names=@"
Microsoft.SystemCenter.2007
Microsoft.Windows.Server.2012.Monitoring
Microsoft.Windows.Server.2012.R2.Monitoring
Microsoft.Windows.Server.AD.2012.R2.Monitoring
Microsoft.SystemCenter.Apm.Infrastructure.Monitoring
Microsoft.SystemCenter.ACS.Internal
Microsoft.Windows.Server.DNS
"@ -split "\n" -replace "`r",""
# Retrieve array of management packs then pipe those MPs into the function.
# A specific override pack will be created for each base pack listed above.
Get-SCOMManagementPack -Name $names | Disable-SCOMAllEventRules
Export-EffectiveMonitoringConfiguration
The functionality is documented here (though I changed the function name slightly in this module).
Will recursively find contained instances of an object (or group of objects) and output the effective monitoring configurations/settings to individual output files. Then it will merge all resulting files into one .csv file, delimited by pipes '|', then output all data to Grid View. In the output directory you will be left with individual configuration files for each object as well as the master merged file containing all object configurations.
Export-SCOMEventsToCSV
This is a quick way to dump events from the Operations Manager event log to a CSV file.
Example:
Export-SCOMEventsToCSV -Newest 1000 -OutFileCSV 'C:\SCOMEvents.csv'
Export-SCOMKnowledge
This is pretty well documented here.
This script will get all rule and monitor knowledge article content (with hyperlinks) and output the information to separate files (Rules.html and Monitors.html) in the output folder path specified.
Get-SCOMClassInfo
Will display statistics about the total number of SCOM class instances and the management packs from which they originate.
Examples:
1) Statistics by class…
Get-SCOMClassInfo -Top 10
2) Statistics by management pack…
Get-SCOMClassInfo -Top 15 -MPStats -ShowGraph
Get-SCOMHealthCheckOpsConfig
This will generate an awesome HTML report including many of the popular Health report contents and SQL queries that we all know and love. This was originally written by Tim Culham and then rebooted by MBullwinkle in 2014. It made sense to include it in this module.
Get-SCOMMPFileInfo
Feed this function a folder path and it will list version and file path information for all management pack files (*.mp, *.mpb, *.xml) in all subdirectories.
If you’re environment is anything like mine, you probably have a spaghetti mess of folders upon folders stuffed with all kinds of management packs that you collected over the years for testing. It’s not always convenient or easy to keep all management packs organized in version-labeled folders. In fact, it’s a huge pain in the neck seeing as how there’s no easy way to determine versioning of MPs based on file properties. This is a friendly tool which will display all of the basic MP info for you.
Example:
1) Feed this function the path to the ‘ManagementPacks’ folder from my SCOM installation media:
Get-SCOMMPFileInfo -inDir 'C:\Temp\en_system_center_2012_r2_operations_manager_x86_and_x64_dvd_2920299\ManagementPacks'
Note: -Passthru is already enabled on the GridView to allow the user to select one or more MP items so they can be piped to another cmdlet that accepts management pack Name, DisplayName, or ID as piped input.
2) This is a super simple way to pick from a list of MPs to import.
Get-SCOMMPFileInfo -inDir 'C:\Temp\MyManagementPacks' | Import-SCOMManagementPack –Verbose
Get-SCOMRunAsAccountName
Feed this an account SSID and it will return the friendly name of a RunAs account.
When a RunAs account problem occurs the resulting errors will appear in Operations Manager event logs containing the account SSID instead of the friendly ‘Display Name’ which makes it difficult to determine which account is involved. This function will reveal the friendly name of the SSID.
Example:
Get-SCOMRunAsAccountName -SSID '0000F61CD9E515695ED4A018518C053E3CD87251D500000000000000000000000000000000000000'
Get-StringHash
This isn’t really specific to SCOM but I found it useful in the past so I included it in this module. Feed it an ordinary string (or any object) and it will generate a unique hash value.
Example:
1)
Get-SCOMClass -name 'microsoft.windows.server.computer' | Select-Object -Property Name | Get-StringHash
153a6dfafcb532c42793a355d2f69e83
2)
Get-StringHash "Creepy Cat Guy"
7d524c2e8c26ba908a2978300ba1d6eb
Ping-AllHosts
This also isn’t really specific to SCOM but I found it useful in my own (SCOM) lab environment so I included it in this module. In my lab environment I have to ping my network devices occasionally to refresh the forwarding table on my cheap 1Gb switch so that they can be reached without first establishing a path. (I hope I’m explaining that clearly). Otherwise, my first connection attempt to my lab servers fails and I have to wait for it to timeout. Upon my second connection attempt, I can successfully connect. I will often let this continue to run in the background to keep those paths fresh. Mmmmmm, fresh paths!
Example:
This will ping all hosts a total of 999 times while pausing for 3 seconds between attempts.
1)
Ping-AllHosts -DelayMS 3000 -Count 999
Remove-SCOMObsoleteReferenceFromMPFile
This function will remove obsolete aliases from unsealed management pack .xml files, offline. This will not alter the original file but rather will output modified versions to the designated output folder.
Example:
This will modify a single .xml file:
1)
Remove-SCOMObsoleteReferenceFromMPFile -inFile 'C:\Unsealed MPs\MyOverrides.xml' -outDir 'C:\Usealed MPs\Modified MPs'
This will retrieve all .xml files and pipe them into the function:
2)
Get-ChildItem -Path 'C:\CustomMPsExported' | Remove-SCOMObsoleteReferenceFromMPFile -outDir 'C:\Usealed MPs\Modified MPs'
Set-SCOMMPAliases
This will standardize all of the aliases in one or more unsealed (.xml) management pack files.
Occasionally (unfortunately) it is necessary to move elements from one unsealed pack to another unsealed pack by cutting/pasting. When unsealed MPs are created by activities within the Console, the references/aliases that get created are randomly named/assigned and often times are ambiguous and usually inconsistent between unsealed packs. This makes it very difficult to cut from one file and place into another file because the aliases won’t match (this is assuming that the same/necessary references exist in both files).
This function will inventory all of the MP reference IDs that can be found in the single file (or set of .XML files) specified by the InputPath parameter. It will create a customized set of condensed alias acronyms to be standardized across all of the unsealed management packs. It will then replace the aliases in the Manifest section of the file(s) as well as throughout the file in elements where the aliases are used.
Note: This will modify the unsealed MPs located in the designated ‘InputPath’ location. However, the functionality of the MPs will not be affected.
Example:
1)
Set-SCOMMPAliases -InputPath 'C:\UnSealedMPs\'
This is an example of what your updated unsealed MP file will look like.
Show-SCOMModules
Will display all known modules contained in all sealed management packs as well as basic schema information. Based on an original script found here: https://sc.scomurr.com/scom-2012-r2-mp-authoring-getting-modules-and-their-configurations/
This can prove to be useful when authoring or debugging.
I’m a big fan of Out-Gridview.
Example:
1)
Show-SCOMModules | Out-GridView
Test-Port
This will test any number of TCP ports on any number of hosts. It will accept piped Computers/IPs or Ports and then test those ports on the targets for connectivity.
Example:
1)
Test-Port -Computer db01,"192.168.1.1",'ms01.contoso.com' -Port 80,53,139
Unseal-SCOMMP
There are plenty of examples of how to unseal MP files but this version will Will unseal .MP and .MPB files along with any additional resources contained therein and place into version-coded folders.
Example:
1) This will unseal all of your Microsoft sealed packs (which normally get extracted/installed to the default SCOM MP folder location).
Unseal-SCOMMP -inDir 'C:\Program Files (x86)\System Center Management Packs' -outDir 'C:\Temp\Unsealed'
Installation:
Find-Module scomhelper -Repository PSGallery | Install-Module -Verbose
Here's an example from my lab:
Additionally you can view more info at the PSGallery.
Code snippets highlighted by hilite.me