Command Line Interface and Script Commands Programming Guide

(1)

IBM System Storage DS3000, DS4000, and DS5000

Command Line Interface and Script Commands Programming Guide

(2)

(3)

IBM System Storage DS3000, DS4000, and DS5000

Command Line Interface and Script Commands Programming Guide

(4)

Note

Before using this information and the product it supports, read the information in “Notices” on page 359.

Seventh Edition (December 2010)

This edition applies to DS5000 Storage Manager Version 10.60, DS4000 Storage Manager Version 10.50, and DS3000 Storage Manager Version 10.35 software release levels and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2010.

(5)

Figures

1. Host and Storage Relationship . . . 184

2. DS3200 Host Ports . . . 186

3. DS3400 Host Ports . . . 186

4. DS3500 Series Host Ports . . . 186

5. DS4200 and DS4700 Host Ports . . . 187

6. DS4800 Host Ports . . . 187

7. DS3950 and DS5020 Host Ports . . . 188

8. DS5300 / DS5100 Host Ports . . . 189

(10)

(11)

Tables

1. Command Name Syntax Conventions . . . . 2 2. Command Line Terminals . . . 3 3. Exit Status . . . 8 4. Configuration and Management Operations 11 5. Object Types and Identifiers . . . 12 6. General Form of the Script Commands 13 7. Recurring Syntax Elements . . . 14 8. Valid Characters for a CHAP Secret . . . . 116 9. Host Ports and the Type of Host Interfaces on

Controller Modules . . . 185 10. Maximum Number of Disk Drives . . . . 189 11. Maximum Number of Disk Drives in an

Array Based on Capacity. . . 191 12. Logical Drive Specifications by Supported

Controller Model . . . 192 13. RAID Level Configurations . . . 193

14. Maximum Number of HBA Host Ports per Controller. . . 196 15. Default Values for Segment Size and Cache

Read Prefetch . . . 214 16. Values for the cacheFlushModifier Parameter 222 17. Components of a FlashCopy Logical Drive 227 18. FlashCopy Logical Drive Commands 228 19. FlashCopy Logical Drive Parameters 231 20. Maximum Number of Defined Mirrors 237 21. VolumeCopy Commands. . . 258 22. Information About Storage Subsystem

Performance . . . 272 23. Support Data for the Storage Subsystem 274 24. RLS Baseline Data for the Storage Subsystem 277 25. Deprecated Commands . . . 349 26. Deprecated Parameters . . . 353

(12)

(13)

About this document

This document is a programming guide that describes the command line interface and the script commands for DS3000, DS4000^®, and DS5000 Storage Manager software to configure, operate, and maintain a storage subsystem. This document describes all of the script commands, explains the purpose of the commands, shows the complete syntax of the commands, and defines the parameters for the commands. The command line interface code is automatically installed as part of the IBM DS Storage Manager client installation.

For information about using the Storage Manager graphical user interface (GUI) or configuring your host operating systems, see the IBM System Storage DS Storage Manager Version 10 Installation and Host Support Guide.

This document does not cover hardware installation or integration. For information about these topics, see the Installation and Support Guide that is appropriate for your storage subsystem. See “Additional Documentation,” on page 355 for a list of these documents.

Check the DS3000, DS4000, or DS5000 readme files for the most up-to-date

information regarding hardware, software, or firmware products that might not be described in this document.

DS3000, DS4000, and DS5000 software and firmware support

The command line interface and the script commands described in this document are supported with the following software and firmware levels:

v DS3000:DS3000 Storage Manager Version 10.xx software in conjunction with firmware 07.xx.xx.xx and later.

v DS4000:DS4000 Storage Manager Version 10.xx software in conjunction with the DS4000 controller firmware version 07.xx.xx.xx and later.

Note: Some of the script commands are also supported in earlier versions of DS4000 controller firmware. Please see “DS3000, DS4000, and DS5000 commands with minimum firmware levels” on page 24 for the minimum controller

firmware that is required to support each script command. This table also shows which commands are supported with the DS3000, DS4000, or DS5000 products only, two of the three, or all three.

v DS5000:DS5000 Storage Manager Version 10.50 and later software in conjunction with the DS5000 controller firmware version 07.50 and later.

Who should read this document

This document assumes that the user has a knowledge of basic storage area network (SAN) hardware and installation skills.

This document is intended for system operators, system administrators, and service personnel who are responsible for operating, maintaining, troubleshooting, and servicing a DS3000, DS4000, or DS5000 storage subsystem. Users must be familiar with computer system operation, maintenance, and repair. In addition, they should understand disk storage technology, Redundant Array of Independent

(14)

Disks (RAID) concepts, networking, and Fibre Channel and iSCSI technologies. The reader must have a basic knowledge of SAN hardware functionality (controllers, drives, and hosts) and SAN cabling.

Notices used in this document

This document contains the following notices that are designed to highlight key information:

Note: These notices provide tips, guidance, or advice.

Important:

These notices provide information or advice that might help you avoid inconvenient or problem situations.

Attention:

These notices indicate possible damage to programs, devices or data. An attention notice is placed just before the instruction or situation in which damage could occur.

Getting information, help, and service

If you need help, service, or technical assistance or just want more information about IBM^®products, you will find a wide variety of sources available from IBM to assist you. This section contains information about where to go for additional information about IBM and IBM products, what to do if you experience a problem with your system, and whom to call for service, if it is necessary.

Before you call

Before you call, take these steps to try to solve the problem yourself:

v Check all cables to make sure that they are connected.

v Check the power switches to make sure that the system is turned on.

v Use the troubleshooting information in your system documentation, and use the diagnostic tools that come with your system.

v Check for technical information, hints, tips, and new device drivers at the IBM support Web site pages that are listed in this section.

v Use an IBM discussion forum on the IBM Web site to ask questions.

You can solve many problems without outside assistance by following the

troubleshooting procedures that IBM provides in the Storage Manager online help or in the documents that are provided with your system and software. The information that comes with your system also describes the diagnostic tests that you can perform. Most subsystems, operating systems, and programs come with information that contains troubleshooting procedures and explanations of error messages and error codes. If you suspect a software problem, see the information for the operating system or program.

Using the documentation

Information about your IBM system and preinstalled software, if any, is available in the documents that come with your system. This includes printed books, online documents, readme files, and help files. See the troubleshooting information in your system documentation for instructions for using the diagnostic programs. The troubleshooting information or the diagnostic programs might tell you that you need additional or updated device drivers or other software.

(15)

Finding Storage Manager software, controller firmware, and readme files

Storage Manager software and controller firmware are available on the product CD and can also be downloaded from the Web. Storage Manager readme files are also found on the Web.

Important: Before you install Storage Manager software, consult the readme file for your host operating system. Updated readme files contain the latest device driver versions, firmware levels, limitations, and other information not found in this document.

1. Go to the following Web site:

www.ibm.com/servers/storage/support/disk/

2. Click the link for your storage subsystem (for example, DS3400 or DS4800).

3. When the support page for your storage subsystem opens, click the Download link in the Support & Downloads box. The Software and device drivers page opens.

4. In the Storage Manager section of the table, locate your operating system and version level, and click on the version link in the right hand column. The specific page for your storage subsystem and operating system version opens.

5. In the table under File details, click on the *.txt file link, and the README will open in your Web browser.

Essential Web sites for DS3000, DS4000, and DS5000 support information

The most up-to-date information about DS3000, DS4000, DS5000, and DS5020 storage subsystems and Storage Manager, including documentation and the most recent software, firmware, and NVSRAM downloads, can be found at the

following Web sites.

IBM System Storage^®Disk Storage Systems

Find links to software and firmware downloads, readmes, and support pages for all IBM System Storage disk storage systems, including DS3000, DS4000, DS5000, and DS5020:

www.ibm.com/systems/support/storage/disk IBM System Storage Interoperation Center (SSIC)

Find technical support information for your specific DS3000, DS4000, DS5000, or DS5020 storage subsystem/host configuration, including the latest recommended firmware versions for your system, by using this interactive Web-based utility:

www.ibm.com/systems/support/storage/config/ssic/index.jsp IBM DS3000, DS4000, and DS5000 Premium Feature Activation

Activate a DS3000, DS4000, or DS5000 premium feature by using this Web-based utility:

https://www-912.ibm.com/PremiumFeatures/jsp/keyPrereq.jsp IBM System Storage DS3000, DS4000, and DS5000 Interoperability Support

Find the latest information about operating system and HBA support, clustering support, storage area network (SAN) fabric support, and Storage Manager feature support:

v DS3000: www.ibm.com/systems/storage/disk/ds3000/pdf/interop.pdf

(16)

v DS4000 / DS5000: www.ibm.com/systems/support/storage/config/

ssic/index.jsp

Storage Area Network (SAN) Support

Find information about using SAN switches, including links to SAN user guides and other documents:

www.ibm.com/systems/support/storage/san Support for IBM System p^®, AIX 5L^™, and Linux servers

Find the latest support information for System p, AIX^®, Linux, BladeCenter^®, and i5/OS^®servers:

www.ibm.com/systems/support/supportsite.wss/

brandmain?brandind=5000025 Support for IBM System x^®servers

Find the latest support information for System x Intel- and AMD-based servers:

www.ibm.com/systems/support/supportsite.wss/

brandmain?brandind=5000008

eServer^™System p and AIX Information Center

Find everything you need to know about using AIX with System p and POWER^® servers:

publib.boulder.ibm.com/infocenter/pseries/index.jsp?

Fix Central

Find fixes and updates for your system's software, hardware, and host operating system:

www.ibm.com/eserver/support/fixes IBM System Storage products

Find information about all IBM System Storage products:

www.storage.ibm.com IBM Publications Center

Find IBM publications:

www.ibm.com/shop/publications/order/

Software service and support

Through IBM Support Line, for a fee you can get telephone assistance with usage, configuration, and software problems. For information about which products are supported by Support Line in your country or region, go to the following Web site:

www.ibm.com/services/sl/products

For more information about the IBM Support Line and other IBM services, go to the following Web sites:

v www.ibm.com/services v www.ibm.com/planetwide

Hardware service and support

You can receive hardware service through IBM Integrated Technology Services or through your IBM reseller, if your reseller is authorized by IBM to provide warranty service. Go to the following Web site for support telephone numbers:

(17)

www.ibm.com/planetwide

In the U.S. and Canada, hardware service and support is available 24 hours a day, 7 days a week. In the U.K., these services are available Monday through Friday, from 9 a.m. to 6 p.m.

IBM Taiwan product service

IBM Taiwan product service contact information:

v IBM Taiwan Corporation v 3F, No 7, Song Ren Rd.

v Taipei, Taiwan

v Telephone: 0800-016-888

Fire suppression systems

A fire suppression system is the responsibility of the customer. The customer's own insurance underwriter, local fire marshal, or a local building inspector, or both, should be consulted in selecting a fire suppression system that provides the correct level of coverage and protection. IBM designs and manufactures equipment to internal and external standards that require certain environments for reliable operation. Because IBM does not test any equipment for compatibility with fire suppression systems, IBM does not make compatibility claims of any kind nor does IBM provide recommendations on fire suppression systems.

(18)

(19)

Chapter 1. About the Command Line Interface

Attention: IBM recommends using the Storage Manager client GUI to manage your storage subsystems. – The command-line interface does not have any mechanisms to prevent you from inadvertently making unwanted changes to the storage subsystem. Because the script commands are capable of damaging a configuration and causing loss of data access if not used correctly, IBM recommends using the Storage Manager client GUI to manage your storage subsystem configurations.

The command-line interface (CLI) is a software tool that lets storage subsystem installers, developers, and engineers configure and monitor storage subsystems using script commands. Using the CLI, you can run commands from an operating system prompt, such as the Windows command prompt, a Linux operating system console, or a Solaris operating system console. You have to install the IBM DS Storage Manager client in order to run the script commands either through the script window, which is invoked from the IBM DS Storage Manager client Enterprise window, or through the command line interface using the SMcli program. The script command engine is automatically installed as part of the IBM DS Storage Manager client installation.

Each command performs a specific action for managing a storage subsystem or returning information about the status of a storage subsystem. You can enter individual commands, or you can run script files when you need to perform operations more than once. For example, you can run script files when you want to install the same configuration on several storage subsystems. The CLI lets you load a script file from a disk and run the script file. The CLI provides a way to run storage management commands on more than one network storage subsystem. You can use the CLI both in installation sites and in development environments.

How to Use the Command Line Interface

The commands that you run on the CLI provide access to the script engine, specify the storage subsystem to receive the script commands, and set operation

environment parameters.

A CLI command consists of these elements:

v The term SMcli

v The storage subsystem identifier v Parameters

v Script commands

A CLI command takes this form:

SMcli storageSubsystem parameters script-commands;

v SMcli invokes the command line interface.

Note: If you issue the command from the directory or folder that does not contain the SMcli.exe program, you need to include the appropriate path:

directoryName/SMcli.

v storageSubsystem is the name or the IP address of the storage subsystem.

(20)

v parameters are CLI parameters that define the environment and the purpose for the command.

v script-commands are one or more script commands or the name of a script file that contains script commands. (The script commands are the storage subsystem configuration commands.)

Usage Notes

If you enter SMcli and a storage subsystem name but do not specify CLI

parameters, script commands, or a script file, the command line interface runs in interactive mode. Interactive mode lets you 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.

To end an interactive mode session, type the operating system-specific command for terminating a program (such as Control-C on the UNIX operating system or the Windows operating system). Typing the termination command (Control-C) while in interactive mode turns off interactive mode and returns operation of the command prompt to an input mode that requires you to type the complete SMcli string.

If you enter an incomplete or inaccurate SMcli string that does not have the correct syntax, parameter names, options, or terminals, the script engine returns usage information.

CLI Commands

The following table lists the conventions used in the command statement syntax to manage the storage subsystem.

Table 1. Command Name Syntax Conventions

Convention Definition

(a | b | c) Alternative (“a” or “b” or “c”)

italicized-words A terminal that needs user input to fulfill a parameter (a response to a variable)

[ ... ](square brackets) Zero or one occurrence (square brackets are also used as a delimiter for some command parameters) { ... }(curly braces) Zero or more occurrences

bold A terminal that needs a command parameter entered

to start an action

General forms of the CLI commands follow, which show the terminals and the parameters that are used in each command.

SMcli DNS-network-name-or-IP-address [DNS-network-name-or-IP-address]

[-c “command; {command2};”]

[-n storage-system-name | -w wwID]

[-o outputfile] [-p password] [-e] [-S] [-quick]

SMcli DNS-network-name-or-IP-address[DNS-network-name-or-IP-address]

[-f scriptfile]

[-n storage-system-name | -w wwID]

(21)

SMcli (-n storage-system-name | -w wwID) [-c “command; {command2};”]

SMcli (-n storage-system-name -w wwID) [-f scriptfile]

SMcli -a email: email-address [host-name-or-IP-address1 [host-name-or-IP-address2]]

[-n storage-system-name | -w wwID | -h host-name | -r (host_sa | direct_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-system-name | -w wwID | -h host-name | -r (host_sa | direct_sa)] [-S]

SMcli (-a | -x) trap: community, host-name-or-IP-address [host-name-or-IP-address1 [host-name-or-IP-address2]]

[-n storage-system-name | -w wwID | -h host-name | -r (host_sa | direct_sa)] [-S]

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

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

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

SMcli -X (-n storage-system-name | -w wwID | -h host-name) SMcli -?

Command Line Terminals

Table 2. Command Line Terminals

Terminal Definition

host-name-or-IP-address Specifies either the host name or the Internet Protocol (IP) address (xxx.xxx.xxx.xxx) of an in-band managed storage subsystem or an out-of-band managed storage subsystem.

v If you are managing a storage subsystem by using a host through in-band storage management, you must use the -n terminal or the -w terminal if more than one storage subsystem is connected to the host.

v If you are managing a storage subsystem by using out-of-band storage management through the Ethernet connection on each controller, you must specify the host-name-or-IP-address of the controllers.

v If you have previously configured a storage subsystem in the Enterprise Management Window, you can specify the storage subsystem by its user-supplied name by using the -n terminal.

v If you have previously configured a storage subsystem in the Enterprise Management Window, you can specify the storage subsystem by its World-Wide Identifier (WWID) by using the -w terminal.

-A Adds a storage subsystem to the configuration file. If you do not follow the -A terminal with a host-name-or-IP-address, auto-discovery scans the local subnet for storage subsystems.

(22)

Table 2. Command Line Terminals (continued)

-a Adds a Simple Network Management Protocol (SNMP) trap destination or an email address alert destination.

v When you add an SNMP trap destination, the SNMP community is automatically defined as the community name for the trap, and the host is the IP address or Domain Name Server (DNS) host name of the system to which the trap should be sent.

v When you add an email address for an alert destination, the email-addressis the email address to which you want the alert message to be sent.

-c Indicates that you are entering one or more script commands to run on the specified storage subsystem. End each command with a semicolon (;). You cannot place more than one -c terminal on the same command line. You can include more than one script command after the -c terminal.

-d

Shows the contents of the script configuration file. The file content takes this format:

storage-system-name host-name1 host-name2

-e Runs the commands without performing a syntax check first.

-F (uppercase) Specifies the email address from which all alerts will be sent.

-f (lowercase)

Specifies a file name that contains script commands that you want to run on the specified storage subsystem. (This terminal is similar to the -c terminal in that both terminals are intended for running script commands. The -c terminal runs individual script commands. The -f terminal runs a file of script

commands.)

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

-g Specifies an ASCII file that contains email sender contact information that will be included in all email alert

notifications. The CLI assumes that the ASCII file is text only, without delimiters or any expected format. Do not use this terminal if a userdata.txt file exists.

-h Specifies the host name that is running the SNMP agent to which the storage subsystem is connected. Use this terminal with the -a terminal and the -x terminal.

-I Specifies the type of information to be included in the email alert notifications. You can select these values:

v eventOnly v profile

v supportBundle -i

Shows the IP address of the known storage subsystems. Use this terminal with the -d terminal. The file contents takes this format: storage-system-name IP-address1 IPaddress2

(23)

-m Specifies the host name or the IP address of the email server from which email alert notifications are sent.

-n Specifies the name of the storage subsystem on which you want to run the script commands. This name is optional when you use a host-name-or-IP-address. If you are using the in-band method for managing the storage subsystem, you must use the -n terminal if more than one storage subsystem is connected to the host at the specified address. The storage subsystem name is required when the host-name-or-IP-address is not used. The name of the storage subsystem that is configured for use in the Enterprise Management Window (that is, the name is listed in the configuration file) must not be a duplicate name of any other configured storage subsystem.

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

-p Specifies the password for the storage subsystem on which you want to run commands. A password is not necessary under these conditions:

v A password has not been set on the storage subsystem.

v The password is specified in a script file that you are running.

v You specify the password by using the -c terminal and the set session password= password command.

-q Specifies the frequency that 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 terminal to eventOnly, the only valid value for the -q terminal is everyEvent. If you set the -I terminal to either the profile value or the supportBundle value, this information is included with the emails with the frequency specified by the -q terminal. These values are valid frequency values:

v everyEvent – Information is returned with every email alert notification.

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

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

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

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

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

(24)

-quick

Reduces the amount of time that is required to run a

single-line operation. An example of a single-line operation is the recreate flashCopy LogicalDrive command. This terminal reduces time by not running background processes for the duration of the command.

Do not use this terminal for operations that involve more than one single-line operation. Extensive use of this command can overrun the controller with more commands than the controller can process, which causes operational failure. Also, status updates and configuration updates that are collected usually from background processes will not be available to the CLI. This terminal causes operations that depend on

background information to fail.

-r Sets or changes the alert notifications for all of the storage subsystems that are managed by a specific storage

management station. Use the -r terminal with the -a terminal or the -x terminal. For storage subsystems that are managed out-of-band, use the direct_sa value. For storage subsystems that are managed in-band, use the host_sa value.

-S (uppercase) Suppresses informational messages describing the command progress that appear when you run script commands.

(Suppressing informational messages is also called silent mode.) This terminal suppresses these messages:

v Performance syntax check v Syntax check complete v Executing script

v Script execution complete v SMcli completed successfully

-s (lowercase) Shows the alert settings in the configuration file when used with the -d terminal.

-v Show the current global status of the known devices in a configuration file when used with the -d terminal.

-w

Specifies the WWID of the storage subsystem. This terminal is an alternate to the -n terminal. Use the -w terminal with the -d terminal to show the WWIDs of the known storage subsystems. The file content take this format:

storage-system-name world-wide-ID IPaddress1 IP-address2.

-X (uppercase) Deletes a storage subsystem from a configuration.

-x (lowercase) Removes an SNMP trap destination or an 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.

-? Shows usage information about the CLI commands.

Formatting Considerations

Double quotation marks (“ ”) that are used as part of a name or label require special consideration when you run the CLI commands and the script commands on a Microsoft Windows operating system. This section describes how to use

(25)

double quotation marks in names while running CLI commands and script commands on a Windows operating system.

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

-c set storageSubsystem userLabel=\“Engineering\”;”

where “Engineering” is the storage subsystem name. A second example is:

-n \“My\”_StorageSubsystem

where “My”_StorageSubsystem is the name of the storage subsystem.

You cannot use double quotation marks (“ ”) 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 subsystem name to “Finance Subsystem":

-c “set storageSubsystem userLabel=\”\”Finance\”Subsystem\”;”

In the Linux operating system and the Solaris operating system, the delimiters around names or labels are single quotation marks (‘ ’). The UNIX versions of the previous examples are as follows:

-c 'set storageSubsystem userLabel=“Engineering”;' -n “My”_StorageSubsystem

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 terminals -n, -o, -f, and -p. For example, to specify storage subsystem CLI>CLIENT, enter this string:

-n CLI^>CLIENT

Insert one caret (^) before each special script character when used within a string literal in a script command. For example, to change the name of a storage

subsystem to FINANCE_|_PAYROLL, enter the following string:

-c set storageSubsystem 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:

v If the CLI must abnormally end running CLI commands and script commands, error data is collected and saved before the CLI finishes.

v The CLI saves the error data by writing the data to a standard file name.

v The CLI automatically saves the data to a file. Special command line options are not required to save the error data.

v You are not required to perform any action to save the error data to a file.

v The CLI does not have any provision to avoid over-writing an existing version of the file that contains error data.

For error processing, errors appear as two types:

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

(26)

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

When an exception occurs while a command is running, the CLI captures the error.

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 tries to place the excprpt.txt file in the directory that is specified by the system property devmgr.datadir. If for any reason the CLI cannot place the file in the directory specified by devmgr.datadir, the CLI saves the excprpt.txt file in the same directory from which the CLI is running. You cannot change the file name or the location. The excprpt.txt file is overwritten every time that 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 a new directory.

Note: In Windows, this is specified by the registry key:

HKLM\SOFTWARE\storage\SMclient\SunJVMOption1

In a typical installation with no changes in the default installation directory, the location is:

v Windows operating systems:c:\Program Files\IBM_DS....\client\data v UNIX-based operating systems:/var/opt/SM

Exit Status

The following table lists the exit statuses that might be returned and the meaning of each status.

Table 3. Exit Status

Status Value Meaning

0 The command terminated without an error.

1 The command terminated with an error. Information about the error also appears.

2 The script file does not exist.

3 An error occurred while opening an output file.

4 A storage subsystem was not at the specified address.

5 Addresses specify different storage subsystems.

6 A storage subsystem name does not exist for the host agent that is connected.

7 The storage subsystem name was not at the specified address.

8 The storage subsystem name was not in the configuration file.

10 A management class does not exist for the storage subsystem.

11 A storage subsystem was not found in the configuration file.

12 An internal error occurred.

(27)

Table 3. Exit Status (continued) Status Value Meaning

13 Invalid script syntax was found.

14 The controller was unable to communicate with the storage subsystem.

15 A duplicate argument was entered.

16 An execution error occurred.

17 A host was not at the specified address.

18 The WWID was not in the configuration file.

19 The WWID was not at the address.

20 An unknown IP address was specified.

21 The Event Monitor configuration file was corrupted.

22 The storage subsystem was unable to communicate with Event Monitor.

23 The controller was unable to write alert settings.

24 The wrong organizer node was specified.

25 The command was not available.

26 The device was not in the configuration file.

27 An error occurred while updating the configuration file.

28 An unknown host error occurred.

29 The sender contact information file was not found.

30 The sender contact information file could not be read.

31

The userdata.txt file exists.

32 An invalid -I value in the email alert notification was specified.

33 An invalid -f value in the email alert notification was specified.

Usage Examples

The following examples show how to enter CLI commands on a command line.

The examples show the syntax, the form, and, in some examples, script commands.

Examples are shown for both the Windows operating system and the UNIX

operating system. Note that the usage for the -c terminal varies depending on your operating system. On Windows operating systems, enclose the script command following the -c terminal in double quotation marks (" "). On UNIX operating systems, enclose the script command following the -c terminal in single quotation marks (' '). (For descriptions of the script commands used in these examples, see Chapter 3, “Script Commands,” on page 21.

This example shows how to change the name of a storage subsystem. The original name of the storage subsystem is Payroll_Subsystem. The new name is

Finance_Subsystem. The storage subsystem is managed in-band through the host name ICTSANT.

v Windows operating system:

SMcli ICTSANT -n "Payroll_Subsystem"

-c "set storageSubsystem userLabel=\"Finance_Subsystem\";"

v UNIX operating system:

(28)

SMcli ICTSANT -n ’Payroll_Subsystem’

-c ’set storageSubsystem userLabel="Finance_Subsystem";’

This example shows how to delete an existing logical drive and create a new logical drive on a storage subsystem. The existing logical drive name is

Stocks_<_Bonds. The new logical drive name is Finance. The controller host names are finance1 and finance2. The storage subsystem is protected, requiring the password TestSubsystem.

SMcli finance1 finance2

-c ’set session password=\"TestSubsystem\"; delete logicalDrive [\"Stocks_<Bonds\"];

create logicalDrive driveCount[3] RAIDLEVEL=3 capacity=10GB userLabel=\

"Finance\";

show storageSubsystem healthStatus;"

v UNIX operating system:

SMcli finance1 finance2 -c ’set session password="TestSubsystem";

delete logicalDrive ["Stocks_<Bonds"];

create logicalDrive driveCount[3] RAIDLEVEL=3 capacity=10GB userLabel=

"Finance";

show storageSubsystem healthStatus;’

This example shows how to run commands in a script file named scriptfile.scr on a storage subsystem named Example. The -e terminal causes the file to run without checking the syntax. Running a script file without checking the syntax lets the file run more quickly; however, the file might not run correctly because the 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 subsystem named Example. In this example, the storage subsystem is protected by the password MySubsystem. Output, as a result of commands in the script file, goes to file output.txt.

SMcli -n Example -f scriptfile.scr -p "My_Subsystem" -o output.txt v UNIX operating system:

SMcli -n Example -f scriptfile.scr -p ’My_Subsystem’ -o output.txt

This example shows how to show all of the storage subsystems in the current configuration. The command in this example returns the host name of each storage subsystem.

SMcli -d

If you want to know the IP address of each storage subsystem in the configuration, add the -i terminal to the command.

SMcli -d -i

(29)

Chapter 2. About the Script Commands

You can use the script commands to configure and manage a storage subsystem.

You can enter individual script commands, or you can run a file of script commands.

To invoke the Storage Manager Command-Line Interface (SMcli), use the SMcli command.

Note: When you enter an individual script command, you include it as part of a SMcli command. When you run a file of script commands, you include the file name as part of a SMcli command.

The script commands are processed by a script engine that performs the following functions:

v Verifies the command syntax v Interprets the commands

v Converts the commands to the appropriate protocol-compliant commands v Passes the commands to the storage subsystem

At the storage subsystem level, the storage subsystem controllers run script commands.

The script engine and the script commands support the storage subsystem configuration and management operations that are listed in the following table:

Table 4. Configuration and Management Operations

Operation Activities

Cache configuration Controlling all cache parameters, both at the storage subsystem level and the individual logical drive level Logical drive

configuration and array configuration

Creating, deleting, and setting the reconstruction priority control; labeling; setting drive composition when creating logical drives; setting the segment size; and setting the media scan control

Disk drive configuration Assigning hot spares

Controller configuration Defining logical drive ownership, changing mode settings, defining network settings, and setting host channel IDs

General storage subsystem configuration

Resetting a configuration to defaults, labeling, checking the health status, setting the time of day, clearing the Event Log, and setting the media scan rate

NVSRAM configuration Downloading and modifying the user configuration region at the bit level and the byte level, showing nonvolatile static random access memory (NVSRAM) values

Product identification Retrieving the enclosure profile display data Battery management Setting the battery installation date

Firmware management Downloading controller firmware, the environmental services monitor (ESM) firmware, and the disk drive firmware

(30)

Script Command Structure

All script commands have the following structure:

command operand-data (statement-data)

where command identifies the action to be performed, operand-data represents the objects associated with a storage subsystem that you want to configure or manage, and statement-data provides the information needed to perform the command.

The syntax for operand-data is as follows:

(object-type | allobject-types | [qualifier] (object-type [identifier]

{object-type [identifier]} | object-types [identifier-list]))

An object can be identified four ways: object type, all parameter prefix, square brackets, or a list of identifiers. Use an object type when the command is not referencing a specific object. The all parameter prefix means all objects of the specified type in the storage subsystem (for example, allLogicalDrives). To perform a command on a specific object, use square brackets to identify the object (for example, logicalDrive [engineering]). Specify a subset of objects with a list of identifiers in square brackets (for example, logicalDrives [sales engineering marketing]). A qualifier is required if you want to include additional information to describe the objects.

The following table lists the object type and the identifiers that are associated with each object type.

Table 5. Object Types and Identifiers

Object Type Identifier

controller a or b

drive Enclosure ID and slot ID only, or enclosure ID, drawer ID, and slot ID, depending on the type of storage enclosure

drivechannel Drive channel identifier

host User label

hostchannel Host channel identifier

hostgroup User label

hostport User label

remote mirror Primary logical drive user label flashcopy Logical drive user label storagesubsystem Not applicable

enclosure Enclosure ID

logicalDrive Logical drive user label or logical drive World-Wide Identifier (WWID) (set command only)

volumecopy Target logical drive user label and, optionally, the source logical drive user label

array Array number

Statement data is in the form of:

(31)

v Parameter=value (such as raidLevel=5) v Parameter-name (such as batteryInstallDate) v Operation-name (such as redundancyCheck)

Script Command Synopsis

Because you can use the script commands to define and manage the different aspects of a storage subsystem (such as host topology, disk drive configuration, controller configuration, logical drive definitions, and array definitions), the actual number of commands is extensive. The commands, however, fall into general categories that are reused when you apply the commands to the different aspects of a storage subsystem. The following table lists the general form of the script commands and provides a definition of each command.

Table 6. General Form of the Script Commands

Syntax Description

activate object {statement-data} Sets up the environment so that an operation can take place or performs the operation if the environment is already set up correctly.

autoConfigure storageSubsystem {statement-data}

Automatically creates a configuration that is based on the parameters that are specified in the command.

check object {statement-data} Starts an operation to report on errors in the object, which is a synchronous operation.

clear object {statement-data} Discards the contents of some attribute of an object. This operation is destructive and cannot be reversed.

create object {statement-data} Creates an object of the specified type.

deactivate object {statement-data}

Removes the environment for an operation.

delete object Deletes a previously created object.

diagnose object {statement-data} Runs a test and shows the results.

disable object {statement-data} Prevents a feature from operating.

download object {statement-data} Transfers data to the storage subsystem or to the hardware that is associated with the storage subsystem.

enable object {statement-data} Sets a feature operate.

recopy object {statement-data} Restarts a VolumeCopy operation by using an existing VolumeCopy pair. You can change the parameters before the operation is restarted.

recover object {statement-data} Re-creates an object from saved configuration data and the statement parameters. (This command is similar to the create command.)

recreate object {statement-data} Restarts a flashcopy operation by using an existing flashcopy logical drive. You can change the parameters before the operation is restarted.

(32)

Table 6. General Form of the Script Commands (continued)

Syntax Description

remove object {statement-data} Removes a relationship from between objects.

repair object {statement-data} Repairs errors found by the check command.

reset object {statement-data} Returns the hardware or an object to an initial state.

resume object Starts a suspended operation. The

operation starts where it left off when it was suspended.

revive object Forces the object from the Failed state to the Optimal state. Use this command only as part of an error recovery procedure.

save object {statement-data} Writes information about the object to a file.

set object {statement-data} Changes object attributes. All changes are completed when the command returns.

show object {statement-data} Shows information about the object.

start object {statement-data} Starts an asynchronous operation. You can stop some operations after they have started. You can query the progress of some operations.

stop object {statement-data} Stops an asynchronous operation.

suspend object {statement-data} Stops an operation. You can then restart the suspended operation, and it continues from the point where it was suspended.

Recurring Syntax Elements

Recurring syntax elements are a general category of variables and options that you can use in one or more script commands. The recurring syntax is used in the general definitions of the script commands that are listed in Chapter 3, “Script Commands,” on page 21

The following table lists the recurring syntax and the syntax values that you can use with the syntax.

Note: A command statement appears in a monospace font. The statement variables are in a monospace italic font. Options are described separately, and usually the choices are shown as TRUE or FALSE, as a letter (a), a number (42), or a number-range (0-99) selection.

Table 7. Recurring Syntax Elements

Recurring Syntax Syntax Value

raid-level (0 | 1 | 3 | 5 | 6)

repository-raid-level (1 | 3 | 5 | 6)

(33)

Table 7. Recurring Syntax Elements (continued) Recurring Syntax Syntax Value

capacity-spec integer-literal[KB | MB | GB | TB | Bytes]

segment-size-spec integer-literal

boolean (TRUE | FALSE)

user-label string-literal

user-label-list user-label {user-label}

create-raid-logicalDrive-attr-value- list

create-raid-logicalDrive-attribute-value- pair {create-raid-logicalDrive-attribute- value-pair}

create-raid-logicalDrive-attribute- value-pair

slotID (1-32)

portID (0-127)

drive-spec

enclosureID,slotID or enclosureID, drawerID,slotID, depending on the type of storage enclosure

drive-spec-list drive-spec {drive-spec}

enclosureID-list enclosureID {enclosureID}

hex-literal 0xhexadecimal-literal

array-number integer-literal

filename string-literal

error-action (stop | continue)

drive-channel-identifier

(1 | 2 | 3 | 4 | 5 | 6 |7 | 8)

Note: You might not be able to use all the supported values, depending on your storage subsystem model.

drive-channel-identifier-list drive-channel-identifier {drive-channel-identifier}

(34)

host-channel-identifier

(a1 | a2 | a3 | a4 | a5

| a6 | a7 | a8) (b1 | b2

| b3 | b4 | b5 | b6 | b7

|b8)

Note: You might not be able to use all the supported values, depending on your storage subsystem model.

drive-type (fibre | SATA | SAS)

feature-identifier

remoteMirror | volumeCopy | SSDSupport | safeStoreSecurity | safeStoreExternalKeyMgr)

repository-spec instance-based-repository-spec | count-based-repository-spec

instance-based-repository-spec

repositoryRAIDLevel=repository-raid-level repositoryDrives=(drive-spec-list) [enclosureLossProtect=boolean¹] repositoryArray=array-number freeCapacityArea=integer-literal² Specify repositoryRAIDLevel with

repositoryDrives. Do not specify the RAID level or the disk drives with the array. Do not set enclosureLossProtectwhen you specify a array.

count-based-repository-spec

repositoryRAIDLevel=repository-raid-level repositoryDriveCount=integer-literal [driveType=drive-type³]

[enclosureLossProtect=boolean⁴]

wwID string-literal

nvsram-offset hex-literal

host-type string-literal | integer-literal

nvsram-byte-setting nvsram-value-> 0xhexadecimal | integer-literal

nvsram-bit-setting nvsram-mask, nvsram-value-> 0xhexadecimal, 0xhexadecimal | integer-literal

ip-address for IPv4

Four groups of four numeric characters (0-9) separated by period "."

(0255).(0255).(0255).(0255)

(35)

ip-address for IPv6

Eight groups of four hexadecimal characters (0-9 and A-F) separated by semicolon ":"

(02AF):(02AF):(02AF):(02AF):

(02AF):(02AF):(02AF):(02AF) autoconfigure-logicaldrive-attr-

value-list

autoconfigure-logicaldrive-attr-value-pair {autoconfigure-logicaldrive-attr-value-pair}

autoconfigure-logicaldrive-attr- value-pair

driveType=drive-type ⁵ | raidLevel=raid- level | arrayWidth=integer-literal | arrayCount=integer-literal |

logicalDrivesPerArrayCount=integer-literal ⁶

| hotSpareCount=integer-literal | segmentSize=segment-size-spec | cacheReadPrefetch=(TRUE | FALSE)

create-volume-copy-attr-value-list create-volume-copy-attr-value-pair {create-volume-copy-attr-value-pair}

create-volume-copy-attr-value-pair copyPriority=(highest | high | medium | low

| lowest) | targetReadOnlyEnabled=boolean recover-raid-logicalDrive-attr-

value-list

recover-raid-logicalDrive-attr-value-pair {recover-raid-logicalDrive-attr-value-pair}

recover-raid-logicalDrive-attr- value-pair

owner=(a | b) | cacheReadPrefetch=(TRUE | FALSE)

cache-flush-modifier-setting immediate, 0, .25, .5, .75, 1, 1.5, 2, 5, 10, 20, 60, 120, 300, 1200, 3600, infinite

Command Line Interface and Script Commands Programming Guide

IBM System Storage DS3000, DS4000, and DS5000

Command Line Interface and Script Commands Programming Guide

IBM System Storage DS3000, DS4000, and DS5000

Command Line Interface and Script Commands Programming Guide

Contents

Figures

Tables

About this document

DS3000, DS4000, and DS5000 software and firmware support

Who should read this document

Notices used in this document

Getting information, help, and service

Before you call

Using the documentation

Finding Storage Manager software, controller firmware, and readme files

Essential Web sites for DS3000, DS4000, and DS5000 support information

Software service and support

Hardware service and support

IBM Taiwan product service

Fire suppression systems

Chapter 1. About the Command Line Interface

How to Use the Command Line Interface

Usage Notes

CLI Commands

Command Line Terminals

Formatting Considerations

Detailed Error Reporting

Exit Status

Usage Examples

Chapter 2. About the Script Commands

Script Command Structure

Script Command Synopsis

Recurring Syntax Elements