Using the Command Line Interface

Using the Command Line Interface

The command line interface (CLI) is a software tool that enables installers, developers, and engineers to configure and monitor storage arrays. Using the command line interface, you can issue commands from an operating system prompt, such as the Microsoft DOS C:\ prompt, a Linux operating system path, or a Solaris operating system path. Each command performs a specific action for managing a storage array or returning information about the of a storage array. You can enter individual commands, or you can run script files when you need to perform operations more than once (such as installing the same configuration on several storage arrays). The command line interface enables you to load a script file from a disk and run the script file. The command line interface provides a way to run storage management commands on more than one network storage array. You can use the command line interface in both installation sites and development environments.

The command line interface provides you with direct access to a script engine that is a utility in the storage management software. The script engine runs commands that enable you to configure and manage storage arrays. The script engine reads the commands, or runs a script file, from the command line and performs the operations instructed by the commands.

Note: You can also access the script engine using the ; however, if you access the script engine using the Enterprise Management Window, you can edit or run script commands on only one storage array in the script window. You can open a script window for each storage array in your configuration and run commands in each window. Using the command line interface, you can run commands on more than one storage array from a single command line.

You can use the command line interface to:

Directly access the script engine and run script commands
Create script command batch files to be run on multiple storage arrays when you need to install the same configuration on different arrays
Run script commands on an , managed storage array, or a combination of both
Display configuration information about the network storage arrays
Add storage arrays to and remove storage arrays from the management domain
Perform automatic discovery of all storage arrays attached to the local subnet
Add or delete destinations and email alert notifications
Specify the mail server and sender email address or SNMP server for alert notifications
Display the alert notification settings for storage arrays currently configured in the Enterprise Management Window
Direct the output to a standard command line display or to a named file

How to Use the Command Line Interface

The commands you run on the command line interface (CLI commands) provide access to the script engine, specify the storage array to receive the script commands, and set operation environment parameters.

A CLI command consists of the following elements:

The term SMcli
Storage array identifier
Parameters
Script commands

The general form of a CLI command is:

SMcli storageArray parameters script-commands;

SMcli invokes the command line interface, storageArray is the name or IP address of the storage array, parameters are CLI parameters that define the environment and purpose for the command, and script-commands is one or more script commands or the name of a script file containing script commands. (The script commands are the storage array configuration commands.)

Usage Notes

If you enter SMcli and a storage array name, but do not specify CLI parameters, script commands, or a script file, the command line interface runs in interactive mode. Interactive mode enables you to run individual commands without prefixing the commands with SMcli. In interactive mode you can enter a single command, view the results, and enter the next command without typing the complete SMcli string. Interactive mode is useful for determining configuration errors and quickly testing configuration changes.

If you enter SMcli without any parameters or an incorrect parameter, the script engine returns usage information.

CLI Commands

This section lists the CLI commands you can use to identify storage arrays, specify passwords, add storage arrays to configuration files, specify communications parameters, enter individual script configuration commands, or specify a file containing script configuration commands. The following table lists the conventions used in the general form of the CLI command.

Table 1-1 Command Name Conventions

Convention Definition

a | b Alternative ("a" or "b")

italicized-words
Terminals

[...] (square brackets) Zero or one occurrence

{...} (curly braces) Zero or more occurrences

(a | b | c) Choose only one of the alternatives

bold
Terminals

The general forms of the CLI commands, showing the parameters and terminals used in each command, are listed below. The table, "Command Line Parameters", lists definitions for the parameters shown in the general form of the CLI commands.

SMcli host-name-or-IP-address [host-name-or-IP-address][-c "command; {command2;}"][-n storage-array-name | -w WWN][-o outputfile][-p password][-e][-S]

SMcli host-name-or-IP-address [host-name-or-IP-address][-f scriptfile][-n storage-array-name | -w WWN][-o outputfile][-p password][-e][-S]

SMcli -n storage-array-name | -w WWN [-c "command; {command2;}"][-o outputfile][-p password][-e][-S]

SMcli -n storage-array-name | -w WWN [-f scriptfile][-o outputfile][-p password][-e][-S]

SMcli -n storage-array-name | -w WWN [-o outputfile][-p password][-e][-S]

SMcli -a email:email-address [host-name-or-IP-address1 [host-name-or-IP-address2]] [-n storage-array-name | -w WWN | -h host-name | -r (inband_sa | outofband_sa)]

[-I information-to-include][-q frequency][-S]

SMcli -x email:email-address [host-name-or-IP-address1 [host-name-or-IP-address2]] [-n storage-array-name | -w WWN | -h host-name | -r (inband_sa | outofband_sa)] [-S]

SMcli (-a | -x) trap:community,host-name-or-IP-address [host-name-or-IP-address1[host-name-or-IP-address2]][-n storage-array-name | -w WWN | -h host-name | -r (inband_sa | outofband_sa)][-S]

SMcli (-a | -x) trap:community,host-name-or-IP-address host-name-or-IP-address [host-name-or-IP-address][-n storage-array-name | -w WWN | -h host-name | -r (inband_sa | outofband_sa)][-S]

SMcli -d [-w][-i][-s][-v][-S]

SMcli -m host-name-IP-address -F email-address [-g contactInfoFiles][-S]

SMcli -A [host-name-or-IP-address [host-name-or-IP-address]] [-S]

SMcli -X (-n storage-array-name | -w WWN | -h host-name)

SMcli -?

Command Line Parameters

Table 1-2 Command Line Parameters

Parameter Definition

host-name-or-IP-address You can specify either the name or the IP address (xxx.xxx.xxx.xxx) of an in-band managed storage array or an out-of-band managed storage array.

If you are managing a storage array using a host through in-band storage management, you must use the -n or -w parameter if more than one storage array is connected to the host.
If you are managing a storage array using out-of-band storage management through the Ethernet connection on each RAID controller module, you must specify the host-name-or-IP-address of the RAID controller modules.
If you have previously configured a storage array in the EMW, you can specify the storage array by its user-supplied name using the -n parameter.
If you have previously configured a storage array in the EMW, you can specify the storage array by its world wide name using the -w parameter.

-A
Use this parameter to add a storage array to the configuration files. If you do not follow the -A parameter with a host-name-or-IP-address, auto-discovery scans the local subnet for storage arrays.

-a
Use this parameter to add an SNMP trap destination or an email address .

When adding an SNMP trap destination, the SNMP community is automatically defined as the for the trap and the host is the IP address or DNS host name of the system to which the trap should be sent.
When adding an email address for an alert destination the email-address is the email address where you want the alert message to be sent.

-c
Use this parameter to indicate you are entering one or more script commands to run on the specified storage array. Terminate each command with a semicolon (;).

You cannot place more than one -c parameter on the same command line. You can include more than one script command after the -c parameter.

-d
Use this parameter to display the contents of the script configuration file. The format of the file contents is:
storage-Array-name host-name1 host-name-2

-e
Use this parameter to run the commands without performing a syntax check first.

-f
Use this parameter to specify a file name containing script commands you want to run on the specified storage array. (This parameter is similar to the -c parameter in that both are intended for running script commands. The -c parameter runs individual script commands. The -f parameter runs a file of script commands.)

By default, any errors encountered when running the script commands in a file are ignored, and the file continues to run. Use the set session errorAction=stop command in the script file to override this behavior.

-F
Use this parameter to specify the email address from which all alerts are sent.

-g Use this parameter to specify an ASCII file containing email sender contact information that will be included in all email alert notifications. The CLI assumes the ASCII file is text only, without delimiters or any expected format. Do not use this parameter if a userdata.txt file exists.

-h
Use this parameter to specify the host name that is running the SNMP agent to which the storage array is connected. Use this parameter with the -a and -x parameters.

-I Use this parameter to specify the type of information to be included in the email alert notifications. Valid information arguments are:

eventOnly
profile
supportBundle

-i
Use this parameter to display the IP address of the known storage arrays. Use this parameter with the -d parameter. The format of the file content is:
storage-Array-name IP-address-1 IP-address-2

-m
Use this parameter to specify the host name or IP address of the email server from which email alert notifications will be sent.

-n
Use this parameter to specify the name of the storage array on which you want to run the script commands. This name is optional when you specify a "host-name" or "IP address"; however, if you are using the in-band method for managing the storage array, you must use the -n parameter if more than one storage array is connected to the host at the specified address.

The storage array name is required when the host-name or IP address is not used; however, the name of the storage array configured for use in the EMW (that is, listed in the configuration file) must not be a duplicate name of any other configured storage array.

-o
Use this parameter with the -c or -f parameters to specify a file name for all output text that is a result of running the script commands. If you do not specify an output file, the output text goes to stdout. All output from commands that are not script commands is sent to stdout, regardless of whether this parameter is set.

-p
Use this parameter to specify the password for the storage array on which you want to run commands. A password is not necessary under the following conditions:

A password has not been set on the storage array.
The password is specified in a script file you are running.
You specify the password using the -c parameter and the set session password=string-literal command.

-q Use this parameter to specify how frequently you want to include additional profile or support bundle information in the email alert notifications. An email alert notification containing at least the basic event information is always generated for every critical event. If you set the -I parameter to eventOnly, the only valid argument for -q is everyEvent. If you set the -I parameter to either profile or supportBundle, this information is included with the emails with the frequency specified by the -q parameter.
Valid frequency arguments are:

everyEvent – Information is returned with every email alert notification

2 – Information is returned no more than once every two hours

4 – Information is returned no more than once every four hours

8 – Information is returned no more than once every eight hours

12 – Information is returned no more than once every 12 hours

24 – Information is returned no more than once every 24 hours

-quick Use this parameter to reduce the amount of time that is required to run a single-line operation. (An example of a single-line operation is the recreate snapshot virtual disk command. This parameter reduces time by not running background processes for the duration of the command.
Do not use this parameter for operations involving more than one single-line operation. Extensive use of this command can overrun the RAID controller module with more commands than the RAID controller module can process, which causes operational failure. Also, status and configuration updates normally collected from background processes will not be available to the CLI. This parameter causes operations that depend on background information to fail.

-r
Use this parameter with the -a or -x parameters to specify the name of an organizer node. The name of an organizer node can be either outofband_sa (out-of-band storage array organizer node) or inband_sa (in-band storage arrays organizer node). The -r parameter enables you to set or change the alert notifications for all storage arrays under each organizer node.

-S
Use this parameter to suppress informational messages describing command progress that appear when running script commands. (Suppressing informational messages is also called "silent mode.") This parameter suppresses the following messages:

Performance syntax check.
Syntax check complete.
Executing script.
Script execution complete.
SMcli completed successfully.

-s
Use this parameter with the -d parameter to display the alert settings in the configuration file.

-v
Use this parameter with the -d parameter to display the current global status of the known storage arrays in a configuration file.

-w
Use this parameter to specify the World Wide Name (WWN) of the storage array. This parameter is an alternative to the -n parameter. Use the -w parameter with the -d parameter of display the WWNs of the known storage arrays. The format of the file content is:
storage-Array-name WWN IP-address-1 IP-address-2

-X (uppercase)
Use this parameter to delete a storage array from a configuration.

-x (lowercase)
Use this parameter to remove an SNMP trap destination or and email address alert destination. The community is the SNMP community name for the trap and the host is the IP address or DNS host name of the system to which you want the trap sent.

-?
Use this parameter to display usage information about the CLI commands.

Formatting Considerations

A double quotation mark (") used as part of a name or label requires special consideration when running CLI and script commands under a Windows operating system. The following bullet items explains how to use double quotation marks in names while running under a Windows operating system.

When double quotation marks are part of a name or argument you must insert a backslash (\) before each double quotation character. For example:

-c "set storageArray userLabel=\"Engineering\";"where "Engineering" is the storage array name. A second example is:

-n \"My"\_Arraywhere "My"_Array is the name of the storage array.

You cannot use the double quotation character (") as part of a character string (also called string literal) within a script command. For example, you cannot enter the following string to set the storage array name to "Finance Array":

-c "set storageArray userLabel=\"\"Finance\"Array\";"In UNIX and Solaris operating systems, the delimiter around names or labels are single quotation marks ('). The UNIX versions of the previous examples are:

-c 'set storageArray userLabel="Engineering";'-n "My" Array
In a Windows operating system, if you do not use double quotation marks around a name, you must insert a caret (^) before each special script character. Special characters are ^, |, <, and >

Insert a caret before each special script character when used with the -n, -o, -f, and -p parameters. For example, to specify storage array CLI>CLIENT, enter the following string:

-n CLI^>CLIENT

Insert one caret (^) before each special script character when used within a script command string literal. For example, to change the name of a storage array to FINANCE_|_PAYROLL, enter the following string:

-c "set storageArray userLabel=\"FINANCE_^|_PAYROLL\";"

Detailed Error Reporting

Error data collected from an error encountered by the CLI is written to a file. Detailed error reporting under the CLI works as follows:

If the CLI must abnormally end running CLI and script commands, then error data is collected and saved before the CLI finishes.
The CLI saves the error data by writing the data to a standard file name.
The CLI automatically saves the data to a file; special command line options are not required to save the error data.
You are not required to perform any actions to save the error data to a file.
The CLI does not have any provisions to avoid overwriting an existing version of the file containing error data.

For error processing, errors appear as two types:

Parameter or syntax errors you might enter
Exceptions that occur as a result of an operational error

When the CLI encounters either type of error, it writes information describing the error directly to the command line and sets a return code. Depending on the return code, the CLI might also write additional information about which parameter caused the error. The CLI also writes information about what it was expecting in the command syntax to help you identify any syntax errors you might have entered.

When an exception occurs while a command is running, the CLI captures the error and, at the end of processing the command (after the command processing information has been written to the command line) the CLI automatically saves the error information to a file.

The name of the file to which error information is saved is excprpt.txt. The CLI attempts to place the excprpt.txt in the directory specified by the system property devmgr.datadir. If for any reason the CLI cannot place the file in the devmgr.datadir specified directory, the CLI saves the excprpt.txt file in the same directory from which the CLI is running. You cannot change the file name or location. The excprpt.txt file is overwritten every time an exception occurs. If you want to save the information in the excprpt.txt file, you must copy the information to a new file or directory.

Exit Status

After you run a CLI command or CLI script command, status indicating the success of the operation defined by the command is displayed. The statuses are:

0 - Terminated without error.

1 - Terminated with error. Information about the error is also displayed.

Usage Examples

The following examples show how to enter CLI commands on a command line. The examples show the syntax, form, and, in some examples, script commands. Examples are shown for both Windows and UNIX systems. Note that the usage for the -c parameter varies depending on your operating system. On Windows operating systems, the script command following the -c must be enclosed in double quotation marks ("). On UNIX systems, the script command following the -c must be enclosed in single quotation marks (').

This example shows how to change the name of a storage array. The original name of the storage array is Payroll_Array. The new name is Finance_Array.

Windows operating system:

SMcli ICTSANT -n "Payroll_Array" -c "set storageArray userLabel=\"Finance_Array\";"

UNIX operating system:

SMcli ICTSANT -n 'Payroll_Array' -c 'set storageArray userLabel="Finance_Array";'

This example shows how to delete an existing virtual disk and create a new virtual disk on a storage array. The existing virtual disk name is Stock_<_Bonds. The new virtual disk name is Finance. The RAID controller module host names are finance1 and finance2. The storage array is protected, requiring the password TestArray.

Windows operating system:

SMcli finance1 finance2 -c "set session password=\"TestArray\"; delete virtual disk[\"Stock_^<_Bonds\"]; create virtual disk driveCount[3] RAIDLEVEL=3 capacity=10GB userLabel=\"Finance\"; show storageArray healthStatus;"

UNIX operating system:

SMcli finance1 finance2 -c 'set session password="TestArray"; delete virtual disk["Stock_<_Bonds"]; create virtual disk driveCount[3] RAIDLEVEL=3 capacity=10GB userLabel="Finance"; show storageArray healthStatus;'

This example shows how to run commands in a script file named scriptfile.scr on a storage array named Example. The -e parameter causes the file to run without checking syntax. Running a script file without checking syntax enables the file to run more quickly; however, the file might not run correctly because syntax for a command might be incorrect.

SMcli -n Example -f scriptfile.scr -e

This example shows how to run commands in a script file named scriptfile.scr on a storage array named Example. In this example, the storage array is protected by the password My_Array. Output, as a result of commands in the script file, goes to file output.txt.

Windows operating system:

SMcli -n Example -f scriptfile.scr -p "My_Array" -o output.txt

UNIX operating system:

SMcli -n Example -f scriptfile.scr -p 'My_Array' -o output.txt

This example shows how to display all arrays in the current configuration. The command in this example returns the host name of each storage array.

SMcli -dIf you want to know the IP address of each storage array in the configuration, add the -i parameter to the command.

SMcli -d -i

This example shows how to run commands in a script file named scriptfile.scr on a storage array named Example. The -e parameter causes the file to run without checking syntax. Running a script file without checking syntax enables the file to run more quickly; however, the file might not run correctly because syntax for a command might be incorrect.

SMcli -n Example -f scriptfile.scr -e

Convention	Definition
a \| b	Alternative ("a" or "b")
`italicized-words`	Terminals
[...] (square brackets)	Zero or one occurrence
{...} (curly braces)	Zero or more occurrences
(a \| b \| c)	Choose only one of the alternatives
bold	Terminals

Parameter	Definition
`host-name-or-IP-address`	You can specify either the name or the IP address (xxx.xxx.xxx.xxx) of an in-band managed storage array or an out-of-band managed storage array. If you are managing a storage array using a host through in-band storage management, you must use the `-n` or `-w` parameter if more than one storage array is connected to the host. If you are managing a storage array using out-of-band storage management through the Ethernet connection on each RAID controller module, you must specify the host-name-or-IP-address of the RAID controller modules. If you have previously configured a storage array in the EMW, you can specify the storage array by its user-supplied name using the `-n` parameter. If you have previously configured a storage array in the EMW, you can specify the storage array by its world wide name using the `-w` parameter.
`-A`	Use this parameter to add a storage array to the configuration files. If you do not follow the `-A` parameter with a host-name-or-IP-address, auto-discovery scans the local subnet for storage arrays.
`-a`	Use this parameter to add an SNMP trap destination or an email address . When adding an SNMP trap destination, the SNMP community is automatically defined as the for the trap and the host is the IP address or DNS host name of the system to which the trap should be sent. When adding an email address for an alert destination the email-address is the email address where you want the alert message to be sent.
`-c`	Use this parameter to indicate you are entering one or more script commands to run on the specified storage array. Terminate each command with a semicolon (;). You cannot place more than one `-c` parameter on the same command line. You can include more than one script command after the `-c` parameter.
`-d`	Use this parameter to display the contents of the script configuration file. The format of the file contents is: `storage-Array-name host-name1 host-name-2`
`-e`	Use this parameter to run the commands without performing a syntax check first.
`-f`	Use this parameter to specify a file name containing script commands you want to run on the specified storage array. (This parameter is similar to the `-c` parameter in that both are intended for running script commands. The `-c` parameter runs individual script commands. The `-f` parameter runs a file of script commands.) By default, any errors encountered when running the script commands in a file are ignored, and the file continues to run. Use the `set session errorAction=stop` command in the script file to override this behavior.
`-F`	Use this parameter to specify the email address from which all alerts are sent.
`-g`	Use this parameter to specify an ASCII file containing email sender contact information that will be included in all email alert notifications. The CLI assumes the ASCII file is text only, without delimiters or any expected format. Do not use this parameter if a `userdata.txt` file exists.
`-h`	Use this parameter to specify the host name that is running the SNMP agent to which the storage array is connected. Use this parameter with the `-a` and `-x` parameters.
`-I`	Use this parameter to specify the type of information to be included in the email alert notifications. Valid information arguments are: `eventOnly` `profile` `supportBundle`
`-i`	Use this parameter to display the IP address of the known storage arrays. Use this parameter with the `-d` parameter. The format of the file content is: `storage-Array-name IP-address-1 IP-address-2`
`-m`	Use this parameter to specify the host name or IP address of the email server from which email alert notifications will be sent.
`-n`	Use this parameter to specify the name of the storage array on which you want to run the script commands. This name is optional when you specify a "host-name" or "IP address"; however, if you are using the in-band method for managing the storage array, you must use the `-n` parameter if more than one storage array is connected to the host at the specified address. The storage array name is required when the host-name or IP address is not used; however, the name of the storage array configured for use in the EMW (that is, listed in the configuration file) must not be a duplicate name of any other configured storage array.
`-o`	Use this parameter with the `-c` or `-f` parameters to specify a file name for all output text that is a result of running the script commands. If you do not specify an output file, the output text goes to stdout. All output from commands that are not script commands is sent to stdout, regardless of whether this parameter is set.
`-p`	Use this parameter to specify the password for the storage array on which you want to run commands. A password is not necessary under the following conditions: A password has not been set on the storage array. The password is specified in a script file you are running. You specify the password using the -c parameter and the set session password=string-literal command.
`-q`	Use this parameter to specify how frequently you want to include additional profile or support bundle information in the email alert notifications. An email alert notification containing at least the basic event information is always generated for every critical event. If you set the `-I` parameter to `eventOnly`, the only valid argument for `-q` is `everyEvent`. If you set the `-I` parameter to either `profile` or `supportBundle`, this information is included with the emails with the frequency specified by the `-q` parameter. Valid frequency arguments are: `everyEvent` – Information is returned with every email alert notification `2` – Information is returned no more than once every two hours `4` – Information is returned no more than once every four hours `8` – Information is returned no more than once every eight hours `12` – Information is returned no more than once every 12 hours `24` – Information is returned no more than once every 24 hours
`-quick`	Use this parameter to reduce the amount of time that is required to run a single-line operation. (An example of a single-line operation is the recreate snapshot virtual disk command. This parameter reduces time by not running background processes for the duration of the command. Do not use this parameter for operations involving more than one single-line operation. Extensive use of this command can overrun the RAID controller module with more commands than the RAID controller module can process, which causes operational failure. Also, status and configuration updates normally collected from background processes will not be available to the CLI. This parameter causes operations that depend on background information to fail.
`-r`	Use this parameter with the `-a` or `-x` parameters to specify the name of an organizer node. The name of an organizer node can be either outofband_sa (out-of-band storage array organizer node) or inband_sa (in-band storage arrays organizer node). The `-r` parameter enables you to set or change the alert notifications for all storage arrays under each organizer node.
`-S`	Use this parameter to suppress informational messages describing command progress that appear when running script commands. (Suppressing informational messages is also called "silent mode.") This parameter suppresses the following messages: Performance syntax check. Syntax check complete. Executing script. Script execution complete. SMcli completed successfully.
`-s`	Use this parameter with the `-d` parameter to display the alert settings in the configuration file.
`-v`	Use this parameter with the `-d` parameter to display the current global status of the known storage arrays in a configuration file.
`-w`	Use this parameter to specify the World Wide Name (WWN) of the storage array. This parameter is an alternative to the `-n` parameter. Use the `-w` parameter with the `-d` parameter of display the WWNs of the known storage arrays. The format of the file content is: `storage-Array-name WWN IP-address-1 IP-address-2`
`-X (uppercase)`	Use this parameter to delete a storage array from a configuration.
`-x (lowercase)`	Use this parameter to remove an SNMP trap destination or and email address alert destination. The community is the SNMP community name for the trap and the host is the IP address or DNS host name of the system to which you want the trap sent.
`-?`	Use this parameter to display usage information about the CLI commands.