Almost everyone who has looked at IBM Systems Director is familiar with the web-based user interface (UI) that provides access to Systems Director's rich set of functions for managing heterogeneous environments. But fewer Systems Director users are aware of its extensive command-line interface (CLI). In this article, I’ll attempt to rectify that lack of knowledge by showing you various CLI commands and the functions that they perform.
All the commands within the Systems Director CLI are invoked by running the command smcli (for Systems Management CLI) followed by the command itself and any options. To display all the commands available in the CLI, run the lsbundle command:
When you work with the Systems Director CLI, it's important to understand the command syntax, especially in regard to providing arguments or parameters both to the smcli interface itself and the command to be executed. According to the IBM Systems Director Information Center, the syntax is:
The parameters shown for the smcli command itself are related to authentication, which I’ll describe shortly. Command_string refers to the command that will be executed within the smcli interface as well as any parameters specific to that command. I’ll show you some command-string examples later in this article.
Just as the web interface requires user authentication, so, too, does the CLI. The CLI supports several ways to provide user credentials (username and password):
- For each CLI command, you can provide user credentials consisting of a username and password by specifying the -user and -pw options, respectively.
- You can provide user credentials through prompts. This method allows for the username and password to be provided after the command string itself is specified. From a security perspective, this method is preferred over the first method because the password isn't visible. You specify prompting either via the -prompt option (e.g., smcli -prompt lsbundle) or by setting the CLIPROMPT environment variable to true.
- You can create a persistent copy of the user credentials that will be used by all future CLI commands. This persistent copy can be useful when multiple commands will be executed because it eliminates the need to enter the credentials for each individual command. You specify caching of credentials with the -c option, which caches the credentials entered for that command (e.g., smcli -c -prompt lsbundle). If you need to delete the cached credentials, you can do so using the -d option (e.g., smcli -d).
Because there are multiple ways to provide user credentials to the CLI, it's important that you understand the order of precedence for checking the credentials. If user credentials are provided with the command (i.e., through the -user and -pw parameters) or through prompting, they’re used; otherwise, a check is made to see whether the credentials have been cached. If credentials haven't been cached and weren’t provided with the command, a check will be made to determine whether the credentials of the user running the command are sufficient (i.e., the user has the correct authorization).
Multiple commands can be executed concurrently. The default setting for the number of concurrent commands is 5; you can specify up to 20 concurrent commands. To support more than 5 commands, you’ll need to change the max.cli.threads setting in the USMIKernel.properties file. The file is located in the /opt/ibm/director/lwi/conf/overrides directory, and the specific setting is:
Systems Director installations or configurations typically won't have the max.cli.threads set. Thus, if you’re changing this setting from the default, simply add the entry to the bottom of the USMIKernel.properties file, then restart the Systems Director management server to put the change into effect.
The smcli interface provides a wealth of commands that can be used for many different purposes: automation of Systems Director tasks, creation of resource monitor recordings, analysis of endpoint inventories, generation of reports from the Systems Director database, customization and management of the Systems Director management console, and running Systems Director tasks from the OS console. The following list provides a summary of the command categories available in the CLI. You can find information about the commands in each category in the Systems Director information center (see the IBM Systems Director resources page for links to the information centers for the different Systems Director versions).
- System commands for performing administrative operations on the IBM Systems Director server
- Web interface commands for managing the web interface and its users
- Group commands for working with Systems Director system groups
- Discovery and inventory commands
- Configuration plans and templates commands
- Status commands for monitoring the status of systems
- Resource monitor commands
- Process monitor commands
- Event and event action plan commands
- Remote access commands for working with remote systems
- Tasks and scheduled jobs commands
- Update commands for managing updates for systems
- Security commands for working with security certificates and authorizations for users and user groups
Shops that activate the IBM Systems Director VMControl plug-in can use these additional commands:
- Host commands for working with virtual farms and virtual hosts
- Storage commands
- System pools commands for workings with servers and storage
- Virtual appliance commands for creating, deleting, and managing virtual appliances
- Virtual server commands
- Workload commands
Refer to the IBM System Director plug-ins section in the Information Center for information about CLI commands for other Systems Director plug-ins, such as Active Energy Manager and Service and Support Manager.
CLI Command Examples
The best way to start to understand the CLI commands available in Systems Director is to look at a few usage examples. Let's examine sample commands for discovery, access, and inventory; resource-monitor recording; and managing the web interface.
Discovery, access, and inventory. Three of the most common tasks performed in Systems Director are discovering resources to manage, requesting access to those resources, and collecting inventory from those resources. Although all these functions can be executed through the web console, they also have CLI counterparts.
Let's look first at the discovery function:
The discover command provides some diagnostic output, such as a running percentage of task completion; however, it doesn’t provide an indication of whether the resource was actually discovered. One way to determine whether the managed resource was found is to use another smcli command—the lssys command:
If the endpoint exists in the Systems Director database (i.e., it was successfully discovered), the command will respond with the system name. Otherwise, a message will be output indicating that the system with the specified IP address or hostname wasn’t found.
The discover command example is perhaps the simplest form of the smcli command: It provides an IP address and performs a discovery across all the protocols known to Systems Director. The discover command supports the ability to discover multiple resources using a single command. When you specify the -i option (for discovery based on IP addresses), you can include multiple IP addresses separated by commas (e.g., -i 10.10.10.10,10.10.10.15,10.10.10.20). You could also specify a range of IP addresses by separating the low and high ends of the range with a hyphen (e.g., -i 10.10.10.10-10.10.10.50). You use the -h option to specify hostnames and separate multiple hostnames by commas. You use the -t option to specify the system type to discover. Use the following command to display a list of valid system types:
Once the resource has been discovered, the next step is to request access. The CLI command to request access is accessys. Here's an example:
This form of the command will prompt for the username and password for the targeted system.
Once access has been granted, the final step is to collect the inventory from the resource:
The -p option for the collectinv command is used to specify the inventory profile to use for the inventory collection. As with the discovery profile for the discover command, you can display the available inventory profiles in the web interface.
Resource-monitor recording. The Systems Director web-based interface provides real-time monitoring capabilities, but it doesn’t let you store, retrieve, or view historical monitor data. However, there are CLI commands that let you access historical monitor data, which you can use for trend analysis and other purposes. The commands in this portion of the CLI let you define data recorders and retention periods for the recorders. You can export the recorder data to .csv, .txt, .htm, or .xml files, which can be used in reports or saved for later analysis.
There are four CLI commands for working with resource-monitor recording:
- lsresmonrec: lists information about previously configured resource-monitor recordings
- mkresmonrec: records resource-monitor values
- rmresmonrec: deletes one or more resource-monitor recordings
- stopresmonrec: stops recording resource-monitor values
Here's an example of how to start a resource-monitor recorder:
-m "[Agent][CPU Monitors][CPU Utilization]"
This command records the CPU utilization monitor data for 15 minutes for localhost and places the recorded values in Recording1.
The mkresmonrec command's optional -m parameter indicates the resource monitor to be recorded. There are a couple of ways to figure out which resource monitors are available. The first is to use the lsresmon smcli command to list the resource monitors that are available for a particular system:
The -m parameter specifies the monitor/submonitor to display, and the -n option indicates the managed endpoint to display the available monitors for. If the -m option isn’t specified, all the monitors for the indicated endpoint will be displayed. Here's an example of the output from the lsresmon command:
Data Node: [Process Count]
Data Node: [CPU Utilization]
Another way to determine the available resource monitors is through the Systems Director web interface. In this case, right-clicking the managed endpoint and selecting System Status and Health, Monitors will display the monitors view page. Clicking the Create button on the monitors view page lets you navigate through the monitors specific to the endpoint, as shown in Figure 1.
You can use the lsresmonrec command both to list the resource-monitor recordings and to list information from a specified resource-monitor recording. To obtain a list of recordings, simply enter the command without any parameters:
To list the records from a specific recording, use the following command:
With the -V parameter specified, the command will display the recorded values for the recording, which will result in output similar to the following:
Attribute:[Agent][CPU Monitors][CPU Utilization]
Start time:Mon Oct 08 18:53:02 CDT 2012
Stop time:Mon Oct 08 19:08:00 CDT 2012
Date Time Data
October 8, 2012 6:56:00 PM CDT 21.878030735932466
October 8, 2012 6:54:00 PM CDT 19.73976621073892
October 8, 2012 7:07:30 PM CDT 18.91938044786146
To set the format of the output, use the -F option followed by a format specifier such as csv, txt, html, or xml.
Keep in mind that the output will still be displayed to the screen, so you’ll need to redirect the output of the recording to a file for further processing.
Managing the web interface. The CLI includes some commands that are useful for managing the web interface, such as chgloginmsg, which lets you change the message displayed with the login prompt for all users, and the endSession command, which terminates the web interface session for a specified user. Let's look at terminating a web session:
To display a list of currently active users, use this command:
Creating Custom Events
Even though Systems Director provides a wealth of monitoring capabilities, at times you might want to be notified of a particular event that the existing monitors don't support. In such cases, you can define a customized event in Systems Director that will be generated from the endpoint and create event filters and event action plans against the customized event. Let's look at the process of creating a custom event.
Generating the event. The Common Agent on the managed endpoints includes a command called genevent that you can use to send a user-definable event to the Systems Director server. On AIX and Linux systems, you can find the genevent command in the /opt/ibm/director/agent/runtime/agent/subagents/director directory; on IBM i, you can find the command in the /www/CAS/lwi/runtime/agent/subagents/director directory. Note that genevent is well suited for use in client-side scripts. Here's an example usage:
This command will cause the event shown in Figure 3 to be added to the Systems Director event log.
The format of the parameters for the genevent command is very specific. The parameter begins with a slash (/) followed by the parameter itself, then a colon, and then by the parameter value. Note that there are no spaces between the parameter and parameter value.
The genevent command supports these parameters:
- /compact: specifies the system-component category for the event definition. The component category, type (/comptype), and instance (/compinstance) define the total event type.
- /condtype: used to specify the type of condition that triggered the event
- /text: specifies a text description of the event
- /compinstance: specifies the instance, or index, of the system-component type that generated the event; it's needed when multiple instances of the component type exist on a managed endpoint
- /meid: specifies the unique ID of the managed endpoint; the value is given as a hexadecimal value and is prefixed with 0x
- /mode: specifies whether the event is a problem occurrence (Alert) or a problem resolution (Resolution)
- /comptype: specifies the system component type for the event
- /sev: specifies the severity for the event; a value of 0 indicates a fatal event, 1 indicates a critical event, 2 indicates a minor event, 3 is for warnings, 4 indicates a harmless event—typically informational only—and 5 indicates that the event severity is unknown
- /condvalue: indicates the value that triggered the event
Let's look at another example of a genevent command, this time using most of the parameters:
/sev:0 /condvalue:77 /condtype:RC
Note that this sample command would be entered on a single line, but I've broken it into multiple lines here for readability. The command will generate an event for instance 1 of the User.Game system component on localhost. The severity of the event is 0 (Fatal Error), the value that triggered the event is 77, and the type of condition that triggered the event is RC. When the corresponding event is received by the Systems Director management server, it generates an event in the event log, as shown in Figure 4.
You can use the smcli command lsevttype -l to list the system-component categories, condition types, component instance, and component type. You can use the lssys -o command to list all the system IDs (useful for the /meid parameter.)
Putting it all together. Once the event has been generated, you can use the corresponding event log entry to create an event filter, as shown in Figure 5. The Create Filter function will ask you to provide a filter name and an optional description.
Once you've created the event filter, you can use it in an event automation plan by specifying the event filter in the Events step of the Create Event Automation Plan function. Assuming that the event action plan uses an action of "send an email," when the previously shown genevent command is re-executed, the email shown below will be generated from the Systems Director management server:
Event Text Skyway chili recipe rocks!
Date 10/8/2012 6:32 PM CDT
Event Type User.Game (RC: 77)
System Name etclxaix1.rchland.ibm.com
Sender Name etclxaix1.rchland.ibm.com
A Useful Addition to Your Systems Director Toolset
The Systems Director CLI commands can a useful or even preferable alternative to the web management interface in certain cases. One such case is when the data or parameters for a command or function already exist in an external file—for example, when a list of system names or IP addresses to be discovered already exists. Another case is when the CLI provides a function that simply doesn't exist in the web management interface—such as the monitor-recording solution I described earlier this article. Neither the CLI nor the web management interface should be viewed as an isolated solution; rather, they should be considered parts of an overall systems management solution.
Now that you've seen some examples of how the CLI can be used to work with data obtained by Systems Director and manage the Systems Director interface, I encourage you to further explore the more the 150 commands that the CLI provides.