IN THIS CHAPTER
• Operations Manager PowerShell Integration
• Comprehensive Operations Manager Cmdlet List
• Summary
One of the serious shortcomings of the early releases of the Microsoft Operations Management (MOM) product was the lack of a good scripting shell. This forced administrators to either use the GUI for all operations or become developers to leverage the APIs. The release of Microsoft System Center Operations Manager (SCOM) 2007 introduced a host of new features to the platform, including PowerShell integration. This gives administrators a powerful new set of tools to script and automate complex tasks without having to become developers.
The Operations Manager PowerShell interface is truly integrated in the sense that it defaults to the Operations Manger object tree rather than the directory structure. This enables the administrator and scripts to interact directly with the objects rather than use a complex set of command-line options or arguments.
The Operations Manager command shell is a customized PowerShell environment that loads the Operations Manager PowerShell snap-in, sets the location to the root of the Operations Manager Monitoring Object, and completes several other tasks. This lets an Operations Manager administrator execute management-specific commands easily and execute ad-hoc scripts natively in Operations Manager.
We explore the command shell in this section to familiarize you with the features, navigation around in the shell, and how to get help.
The command shell is installed when you install a SCOM management server. You launch it separately from the standard Windows PowerShell. To launch the Operations Manager command shell, execute the following steps:
1. Select Start.
2. Select All Programs.
3. Select System Center Operations Manager 2007.
4. Select Command Shell.
This opens the Operations Manager command shell. On launching the command shell, you get the following customized message:
This is the customized shell that enables you to execute the Operations Manager cmdlets and scripts. It is a little bit different from the standard Windows PowerShell, so the next sections explore how to navigate and use the customized shell. The prompt shows us that we are using the command shell and that we are connected to the om2.cco.com management server.
NOTE
The command shell displays a lot of information, and the default width of the command shell window is only 80 characters wide by default. You can adjust the properties of the command shell to show more information and make it easier to work with.
After launching the command shell, right-click on the window and select Properties. Select the Layout tab and change the Screen Buffer size width to 120 and the height to 300. Change the Window Size to 120 and 90. You can adjust these sizes to fit your screen. Click OK and select Modify shortcut that started this window to preserve the settings. Click OK to save.
After launching the command shell, you can get a list of the current location by executing the dir cmdlet, as shown here:
The cmdlet produces a stream of information of over a hundred objects depending on the Management Packs you have installed. To control this stream of information, you can display the results page by page:
Reviewing the results page by page, the objects shown are not files and folders, but Operations Manager objects. This is because the dir cmdlet is really just an alias for the select-object cmdlet, so the dir command returns objects from the current location. In the case of the standard Windows PowerShell prompt, this is the folder tree. In the case of the Operations Manager command shell, this is the Operations Manager Monitoring Object tree.
For each of the objects returned, the cmdlet shows the following:
• ID
• PathName
• DisplayName
• ManagmentMode
• ManagementGroup
• HealthState
• OperationalState
You can show just the DisplayName and the PathName by using the following command:
This still returns a large number of objects. You can narrow the results even further by using the where cmdlet (where-object) to filter the objects returned, as shown in the following:
Now we can see the path to the Windows Server Computer Group, which contains all the monitored Windows Server computer objects. To list the Windows Server computer objects, execute the following command dir Microsoft.Windows.Server.ComputerGroup with the following result:
The list was truncated after the first three computers. You can see that the health state for the gps.cco.com server is in a warning state, the rms.cco.com server is in an error state, and the archive.cco.com server is in a success state (which means it is healthy).
Similarly, we can quickly find the health state of Exchange 2007 servers using the following command:
This command shows the health state of all the Exchange 2007 servers.
The Operations Manager 2007 follows an object-contain model, meaning that objects contain other objects. You can also drill further into the objects to explore the objects that are contained within. To navigate the object tree, use the familiar cd cmdlet, which is an alias for the set-location cmdlet. We can navigate to the Windows Server Computer Group object using the following command:
Note that the prompt now shows where in the object tree we are located. We can use the dir cmdlet to explore the error state of the rms.cco.com server. Recalling that the pathname was rms.cco.com, we can use the following command to navigate to the rms.cco.com object:
Once again, note that the prompt shows where in the object tree we are located. We can quickly get the health state of the objects contained in the rms.cco.com computer object by executing the following command:
We can even return only the objects where the state is in error by using the where cmdlet in the following command:
Now we have the list of objects that are in an error state in the rms.cco.com Windows Server Computer Group object.
We can also move to the top of the tree by using the cd cmdlet. For example, to move up one level in the tree you can use the following command:
You can also move to the top of the tree using the following command:
This takes you all the way to the top of the tree, even above the management server where the console originally defaulted to (which in the case of the examples was om2.cco.com). You can navigate back to the management server by using the cd cmdlet, as shown in the following:
Now the location is back to the original location when the command shell was launched. You can use the dir and cd cmdlets to navigate around the operations management object tree and even between management servers.
The Operations Manager 2007 PowerShell snap-in loads a large number of new cmdlets to manipulate the management objects.
The Get-OperationsManagerCommand cmdlet shows all the cmdlets:
Executing this gives you a list of the 87 cmdlets added by the Operations Manager PowerShell snap-in. The cmdlet helpfully shows the name and the basic syntax for the cmdlet on a single line. You can narrow the results of the cmdlet by using the where cmdlet. The code that follows would return the five cmdlets that relate to alerts:
After you have identified a cmdlet, you can get additional help using the standard get-help cmdlet. The three levels of help provided by the cmdlet are shown in the three commands that follow:
This chapter covers the most common cmdlets and their uses, but it does not exhaustively cover all 87 of the cmdlets. At the end of the chapter, all the Operations Manager cmdlets are listed for reference along with their descriptions.
The command shell loads the Operations Manager snap-in and sets the location. However, when automating scripts, the shell that is launched is the default Windows PowerShell. Without a couple of lines of code, any scripts with Operations Manager cmdlets will fail.
For the purposes of creating automated scripts, there are two commands that will start all of your Operations Manager PowerShell scripts. These are shown in the code box that follows:
The first command adds the PowerShell snap-in that contains all the cmdlets for Operations Manager 2007. Without this, PowerShell does not recognize any of the Operations Manager cmdlets. The second command sets the location to the Operations Manager Monitoring Object, which allows management objects to be referenced directly.
The agent cmdlets enable you to get information about agents, install agents, and uninstall agents. These cmdlets are useful for doing bulk operations on agents that are tedious to do in the Operations Manager Console. They even enable you set some parameters that cannot be accessed in the console, such as specifying the failover management servers.
The get-agent cmdlet returns the agents that are contained in a management server. You can get the syntax of the get-agent cmdlet using get-help:
The basic command shown in the following returns all the agents associated with the current management server.
This returns all agents and might be a long list. We can select a single agent using the where cmdlet, as shown in the example that follows:
You can see some useful information such as the IPAddress, InstallTime, or if it was manually installed. For a large number of agents, you can find all manually installed agents in the management group using the following command:
This command would return agents from all management servers and filter it based on the ManuallyInstalled attribute being true.
The install-agent cmdlet installs agents on computers to be managed. This command is useful for scripting the install of agents onto computers. The syntax for the cmdlet using get-help is shown in the following:
The tricky part about the install-agent cmdlet is that before an agent can be installed on a computer to be managed, the computer must be discovered by the Operations Manager infrastructure. This requires a three-step process to install the agent, which is to configure the discovery of computers, to discover the computers, and to install the agent on the discovered computers. In the next set of examples, an agent is installed on a computer named webtest by its primary management server om2.cco.com.
The first step is to specify the computer to be discovered (that is, webtest) using the new-WindowsDiscoveryConfiguration cmdlet, as shown in the following command:
The results of the new-WindowsDiscoveryConfiguration cmdlet are stored in the $windows_discovery_config variable.
Using the results from the new-WindowsDiscoveryConfiguration enables the actual discovery of the webtest computer to be initiated with the start-discovery cmdlet. The command to do that is shown in the following:
The discovery results are stored in the $discovery_results variable to be used in the actual agent install. The agent-install cmdlet is used to initiate installation of the agent on the discovered computer webtest. The command is shown in the following:
The agent displays in the Operations Manager 2007 console as a managed computer.
The uninstall-agent cmdlet does the opposite of the install-agent cmdlet, which is to say it removes the agent from a managed computer. This would not be used to move a managed computer from one management server to another, which is done using the set-ManagementServer cmdlet and is covered later in the chapter. The uninstall-agent cmdlet is useful for automating the removal of agents from managed computers. The syntax for the cmdlet using get-help is shown in the following:
The command requires the agent objects to be passed in as parameters, rather than the agent names. Fortunately, you can use the aforementioned get-agent cmdlet to get the agent object to pass into the uninstall-agent cmdlet. The commands to uninstall the agent from webtest.cco.com managed computer are shown in the following.
The agent will be gone in the Operations Manager 2007 Console as a managed computer.
The task cmdlets are useful for running tasks automatically. This provides a way of triggering the task available in Operations Manager and returning the status of those tasks. This is a huge benefit, as it allows these tasks to be started from outside of the Operations Manager 2007 environment and facilitates integration with other platforms and systems.
The get-Task cmdlet returns the tasks available in the management group. Given that there are potentially hundreds of tasks available in a given management group and more are added each time a management pack is installed, it is important to locate a specific task. The get-Task cmdlet makes this possible. The syntax for the cmdlet using get-help is shown in the following:
The work of the get-Task cmdlet is complicated by the architecture of Operations Manager. For example, if you wanted to run the IPConfig task against a specific computer in the Operations Console, you simply select the computer object and click on the IPConfig action. For this example, we select a Windows Server 2003 computer named rms.cco.com. The IPConfig task is listed under the Actions for the rms.cco.com computer. Mission accomplished.
To locate the IPConfig task, we use the get-Task cmdlet. The first thing to try is to run the get-Task with no parameters, as shown in the following:
After a lot of scrolling, it becomes clear that this is not going to work as a way of locating a task. Given that there are hundreds of tasks, this list is far too long to search manually.
The next step is to use the where cmdlet to filter for the IPConfig task. The resulting command looks like this:
The list is much shorter, with only four task objects returned. However, we need to find the correct one to run against the rms.cco.com computer. The reason for the multiplicity of IPConfig tasks is that each one is associated with a different path, which is dependent on the operating system of the computer. The path can be seen in the name of the task object, as shown in the four paths listed here:
• Microsoft.Windows.Client.XP.Computer.IPConfig.Task
• Microsoft.Windows.Server.2000.Computer.IPConfig.Task
• Microsoft.Windows.Server.2003.Computer.IPConfig.Task
• Microsoft.Windows.Client.2000.Computer.IPConfig.Task
To return the correct task for the rms.cco.com computer, simply match the name to the operating system (Windows Server 2003) of the computer. The resulting command is:
This command will return the appropriate task for the rms.cco.com server. This task object can now be used with the start-Task cmdlet to execute a task.
The start-Task cmdlet starts an Operations Manager 2007 task. This enables an administrator to start a task programmatically and automate task execution. The syntax for the cmdlet using get-help is shown in the following:
Leveraging the work from the previous section on the get-Task cmdlet, we know the command to return the IPConfig task object that targets the rms.cco.com Windows Server 2003 computer. The following commands capture that IPConfig task object and then use the start-Task cmdlet to start the task:
The task status can be reviewed in the Operations Console in the Monitoring section in the Task Status view. The task status includes the output of the task.
If you want to run the command on a single command line in PowerShell, you can also nest the get-Task cmdlet in parentheses to have it executed inline as shown in the following command:
Rather than use the Operations Console to check the results of a task, you can use the get-TaskResult cmdlet to get that status. This enables the results to be captured automatically and logged in line with the script. The syntax for the cmdlet using get-help is shown in the following:
When the start-Task cmdlet is run, it returns the task result object. This can be captured to a variable and then used with the get-TaskResult cmdlet to check the results.
This shows the task results object, which includes the task status, who submitted it, the time started and finished, and the output of the task. You can select just the task status, Succeeded in this case, using the following simple change to the command using the select cmdlet:
The management server cmdlets enable administrators to manage management servers and their settings. These cmdlets are useful for moving agents between management servers and configuring the failover management servers for agents.
The get-ManagementServer returns management servers for the Operations Manager 2007 management group.
The syntax for the cmdlet using get-help is shown in the following:
By default, the get-ManagementServer cmdlet with no parameters returns all the management server objects in the management group. So, the command that follows returns all the management servers in the CCO management group:
These results can be filtered to select a specific management server or set of management servers. For example, the command that follows would return just the object for the om2.cco.com management server:
Finally, the command can also return the special case of the root management server for the management group. The command to return the root management server is:
The help text incorrectly references a -root parameter for the get-ManagementServer cmdlet, which does not exist. The previous command will correctly return the root management server.
The set-ManagementServer cmdlet enables an administrator to specify or change the primary and failover management servers for an agent or group of agents. The syntax for the cmdlet using get-help is shown in the following:
The cmdlet takes a management server and agent object, so pathnames will not work. The commands to get the agent object (rms.cco.com), get the management server object (om3.cco.com), and then set the primary management server on the agent are shown in the following:
The -AgentManagedComputer parameter can take multiple objects, so a single command can change the primary management server for a number of objects at once.
Another common task is setting the failover management server for agents. By default, the agents randomly select a management server to fail over to if they cannot connect to their primary management server. In many organizations, there may be a designated failover management server. However, the UI does not have an option to set this. The set-ManagementServer cmdlet enables administrators to set this using the following command:
In the case of the previous code, the commands set the failover management server on the rms.cco.com agent managed computer to om4.cco.com. Multiple management server objects can be passed in the $failovermanagementserver variable, allowing there to be multiple failover management servers specified.
The get-DefaultSetting cmdlet returns the settings for the management group. These are the settings that are exposed in the Operations Console, in the Administration section under the Settings folder. The cmdlet enables the settings to be queried programmatically. The syntax for the cmdlet using get-help is shown here:
The command returns the name of the path to the setting and its current value. To return all 49 settings, execute the following command:
To return just a single value, use the where cmdlet to filter the objects returned. The following commands return the agent heartbeats interval:
The default Settings Paths section in this chapter has tables with the complete listing of all paths.
The set-DefaultSetting cmdlet sets the default settings for the management group. These are the settings that are exposed in the SCOM Operations Console, in the Administration section under the Settings folder. The cmdlet enables the settings to be changed programmatically, rather than relying on the graphical user interface. The syntax for the cmdlet using get-help is shown here:
The set-DefaultSetting cmdlet requires that you know the setting that you want to change. These can be listed using the get-DefaultSetting cmdlet or in the next section that contains a complete list of all the paths.
For example, to change the number of days to keep task status to 14 days, execute the following command:
The setting can be viewed in the Operations Console by selecting the Administration section, the Settings folder, and then by opening the Database Grooming and looking at the Task history setting.
NOTE
If you have the Operations Console open, you may need to close and reopen the console to see the changes. The console has a local cache that can cause changes to seem delayed. This is a known problem with the console, but the settings are in effect as soon as the set-DefaultSetting command is completed.
The paths for the 49 default settings are listed in this section. They are used with the get-DefaultSetting and the set-DefaultSetting cmdlets. See the sections on those cmdlets for information on how to use these paths.
Listing 16.1 lists a set of miscellaneous paths that address the default settings for the agents and the management group.
Example 16.1. Miscellaneous Default Setting Paths
HealthServiceProxyingEnabled
AgentHeartbeatsInterval
NotificationServerWebAddressesWebConsole
ManagementGroupAlertResolutionAlertAutoResolveDays
ManagementGroupAlertResolutionHealthyAlertAutoResolveDays
ManagementGroupCustomerExperienceImprovementProgramEnabled
ManagementGroupSendOperationalDataReports
ManagementGroupErrorReportingSendErrorReports
ManagementGroupErrorReportingQueueErrorReports
ManagementGroupWebAddressesOnlineProductKnowledge
Listing 16.2 lists the paths for the default settings on management servers. These do not affect the settings on existing management servers, but change what the default settings would be for new management servers.
Listing 16.3 shows the paths that affect the settings for the data warehouse.
Listing 16.4 lists the client monitoring default settings paths.
Example 16.4. Client Monitoring Default Setting Paths
ManagementGroupClientMonitoringSettingsMaxNumberOfCabsToCollect
ManagementGroupClientMonitoringSettingsErrorTransmissionFilters
ManagementGroupClientMonitoringSettingsExceptionFolders
ManagementGroupClientMonitoringSettingsPublishMicrosoftSolutionLinks
ManagementGroupClientMonitoringSettingsPublishMicrosoftSurveyLinks
ManagementGroupClientMonitoringSettingsPublishMicrosoftDataCollectionRequests
ManagementGroupClientMonitoringSettingsPublishMicrosoftFileCollectionRequests
ManagementGroupClientMonitoringSettingsPublishMicrosoftRegistryCollectionRequests
ManagementGroupClientMonitoringSettingsPublishMicrosoftWMIQueryRequests
ManagementGroupClientMonitoringSettingsPublishMicrosoftMemoryDumpRequests
ManagementGroupClientMonitoringSettingsPolicyResponseUrl
Listing 16.5 lists the paths to the custom alert fields. These are populated into alerts if specified.
Example 16.5. Alert Custom Field Default Setting Paths
ManagementGroupAlertCustomFieldSettingsCustomField1
ManagementGroupAlertCustomFieldSettingsCustomField2
ManagementGroupAlertCustomFieldSettingsCustomField3
ManagementGroupAlertCustomFieldSettingsCustomField4
ManagementGroupAlertCustomFieldSettingsCustomField5
ManagementGroupAlertCustomFieldSettingsCustomField6
ManagementGroupAlertCustomFieldSettingsCustomField7
ManagementGroupAlertCustomFieldSettingsCustomField8
ManagementGroupAlertCustomFieldSettingsCustomField9
ManagementGroupAlertCustomFieldSettingsCustomField10
The grooming settings paths are listed in Listing 16.6. These set the retention times for the data in the Operations database.
Example 16.6. Grooming Default Setting Paths
ManagementGroupPartitioningAndGroomingSettingsEventDaysToKeep
ManagementGroupPartitioningAndGroomingSettingsPerformanceDataDaysToKeep
ManagementGroupPartitioningAndGroomingSettingsAlertDaysToKeep
ManagementGroupPartitioningAndGroomingSettingsStateChangeEventDaysToKeep
ManagementGroupPartitioningAndGroomingSettingsMaintenanceModeHistoryDaysToKeep
ManagementGroupPartitioningAndGroomingSettingsAvailabilityHistoryDaysToKeep
ManagementGroupPartitioningAndGroomingSettingsJobStatusDaysToKeep
ManagementGroupPartitioningAndGroomingSettingsMonitoringJobDaysToKeep
ManagementGroupPartitioningAndGroomingSettingsPerformanceSignatureDaysToKeep
Maintenance mode is one of the favorite targets of Operations Manager 2007 automation. Maintenance mode prevents the object or objects from generating alerts or notifications. This set of cmdlets enables an administrator to automate the setting of maintenance mode windows for objects. The PowerShell maintenance cmdlets enable administrators to integrate the setting of Operations Manager maintenance windows with other automated tasks being run.
The new-MaintenanceWindow and set-MaintenanceWindow cmdlets accept only specific reason codes. These are displayed differently than in the Operations Manager Console, though they represent the same values. Table 16.1 shows the planned and unplanned reason codes.
The new-MaintenanceWindow cmdlet puts an object or objects into maintenance mode, creating a new maintenance mode window. The new-MaintenanceWindow cmdlet is useful for automating the placement of an object into maintenance mode. The syntax for the cmdlet using get-help is shown here:
The new-MaintenanceWindow cmdlet accepts either a monitoring object or path to the object. A sample command to put the rms.cco.com Windows Server Computer object into maintenance mode for two hours is shown in the following:
The start time for the window is now, will last for two hours, and the reason is a planned application installation. The full path to rms.cco.com object is specified. After executing this command, the rms.cco.com computer would go into maintenance mode and exit automatically after two hours have passed.
If you get the health state of the object in maintenance mode, you will find that it shows as Uninitialized. For example:
This returns the rms.cco.com computer object and shows the health state as Uninitialized.
The get-MaintenanceWindow returns the parameters of an existing or historical maintenance mode window. The get-MaintenanceWindow cmdlet is useful for automating the querying of the object in maintenance mode or reviewing the history. The syntax for the cmdlet using get-help is shown here:
The command is straightforward to run. To get the information on the maintenance window for the rms.cco.com, the following command can be used:
This command shows the status of the maintenance mode window for the object, including the user who placed the object in maintenance mode.
If the object is not in maintenance mode, then the command generates an error. However, the maintenance mode history can be returned by adding the -history parameter to the command. The resulting command is shown in the following:
Sometimes it is necessary to extend or modify the maintenance mode window, which is where the set-MaintenceWindow cmdlet comes into play. The syntax for the cmdlet using get-help is shown in the following:
The cmdlet enables an administrator to adjust some of the parameters of the maintenance window, including the end time, the reason, and the comment.
The command sets the maintenance window to end one minute from now. The end time cannot be set to now, as the system interprets that as occurring in the past and generates an error. Unfortunately, the start time cannot be adjusted even if it is in the future.
NOTE
The set-MaintenanceWindow cmdlet with the -EndTime ([DateTime]::Now.AddMinutes(1)) parameter is useful for closing out the maintenance mode window after all IT tasks have wrapped up early. For example, maybe a planned maintenance window was scheduled to last four hours for patching. However, patching completes in one hour. The cmdlet can be used to close all the maintenance mode windows and put the object back into management at the time the patching is complete rather than wait for the window to expire.
It is difficult to get a complete listing of all the Operations Manager cmdlets and what they do. Microsoft does not list this information on its Web site, and there are few other resources on Operations Manager 2007 and PowerShell. To help address that gap, this section gives a comprehensive alphabetical listing of all the Operations Manager 2007 cmdlets.
Some of the cmdlets are explored in this chapter. For the others, get-help cmdlet provides a wealth of information.
Table 16.2 lists the get and set verb cmdlets that are available in the Operations Manager 2007 command shell.
Table 16.3 lists the add and remove verb cmdlets that are available in the Operations Manager 2007 command shell.
Table 16.4 lists the enable and disable verb cmdlets that are available in the Operations Manager 2007 command shell.
The Operations Manager PowerShell integration brings the scripting capabilities of the product to a whole new level. The PowerShell integration in Operations Manager 2007 in the command shell enables administrators to automate all Operations Manager 2007 administration tasks, from installing agents to changing management servers, to executing tasks, and to setting the maintenance windows for objects.
The command shell is a powerful new tool in the arsenal of the Operations Manager 2007 administrator.