XCLI Utility User Manual

IBM XIV Storage System XCLI Utility User Manual GC27-3915-00

Note: Before using this information and the product it supports, read the general information in Notices on page 17. Third Edition (2011) The following paragraph does not apply to any country (or region) where such provisions are inconsistent with local law. INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states (or regions) do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you. Order publications through your IBM representative or the IBM branch office serving your locality. Copyright IBM Corporation 2011. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Chapter 1. Overview of XCLI utility... 1 XCLI documentation............ 2 Interactive and basic modes......... 3 Chapter 2. Getting started with XCLI.. 5 Installing the XCLI utility.......... 5 Launching the XCLI utility......... 5 Logging off the XCLI utility......... 7 Interactive mode features.......... 7 Commands syntax............ 7 Commands syntax quick-reference...... 8 Syntax example............ 8 Chapter 3. Using XCLI........ 11 Identification parameters.......... 11 User and password parameters....... 11 Defining XCLI Configurations....... 12 Running commands in batch mode..... 13 Display options............. 14 Using display options.......... 14 Table display options.......... 15 Printing XCLI help and version........ 16 Notices.............. 17 Copyright IBM Corp. 2011 iii

iv IBM XIV Storage System: XCLI Utility User Manual

Chapter 1. Overview of XCLI utility The XCLI provides a mechanism for executing commands to manage and maintain the IBM XIV Storage System. XCLI commands are entered on an XCLI client machine (or XCLI client) supplied by the customer. Some XCLI commands run directly on the XCLI client. But usually, XCLI commands are sent by the XCLI client to the IBM XIV Storage System for execution. Figure 1. The XCLI utility runs commands on the IBM XIV Storage System. The XCLI relies on code running in two places: the XCLI client machine, and the IBM XIV Storage System. A single XCLI client machine usually supports multiple IBM XIV Storage Systems, and these IBM XIV Storage Systems may be running different microcode versions. The XCLI client code version is independent of the version of microcode firmware which is running on the IBM XIV Storage System. When you receive a new version of IBM XIV Storage System microcode which supports additional XCLI system commands, you do not need to update the XCLI code running on the XCLI client machine to use the new commands. Note: The IBM XIV Storage System is often referred to as "the machine" in this document. Definitions XCLI client machine, XCLI client The machine on which the XCLI command is entered. XCLI utility command An XCLI command which is executed on the XCLI client. An XCLI utility command is not sent to an IBM XIV Storage System for processing. XCLI utility commands are used for setting up configurations on the XCLI client and for queries (for example, of software version) which can be processed on the client. Copyright IBM Corp. 2011 1

XCLI documentation XCLI system command An XCLI command which is sent to the IBM XIV Storage System for execution. Interactive mode A means of entering XCLI commands on the XCLI client. Interactive mode is intended for real time command execution by a human being. When in interactive mode, the IBM XIV Storage System IP address, user, and password information does not need to be specified for each command. Basic mode A means of entering XCLI commands on the XCLI client. Basic mode requires specifying IP address and login information for each command. Also, additional output formatting options are available in basic mode. XCLI identification parameters XCLI identification parameters identify the user executing the command, and the IBM XIV Storage System (if any) on which the command will be executed. XCLI identification parameters can be specified: v By entering them at the beginning of an interactive mode session v In a configuration file v When running a command in basic mode v When running a list of commands as a batch Communication between the XCLI client and the IBM XIV Storage System The XCLI client and the IBM XIV Storage System communicate using SSL over TCP/IP. Each IBM XIV Storage System has three Ethernet ports used as management interfaces, and each IBM XIV Storage System can be assigned up to three IP addresses one per management interface. Having three management interfaces provides redundancy, allowing management interface communication to continue on a different port and IP address should one of the ports, or the customer Ethernet network fail. When running a command, the XCLI client is provided with these three IP addresses and tries each of them until communication with one of the IP addresses is successful. The XIV Command Line Interface (XCLI) relies on code running in two places: The XCLI client This is a hardware platform that has TCP/IP connectivity to the IBM XIV Storage System. This part of the XCLI is describesd in this document. Note: XCLI utility commands run directly on the XCLI client. The IBM XIV Storage System This is where most of the commands are executed. This part of the command is described in the XCLI Reference Guide. Commands executed on the IBM XIV Storage System are also called XCLI system commands. The XCLI documentation comes in two parts, the XCLI Utility Manual (this document) and the XCLI Reference Guide. The table below describes the information contained in each. 2 IBM XIV Storage System: XCLI Utility User Manual

General Types of commands described Types of parameters described Updated when XCLI Utility User Manual Describes the general format of XCLI command line arguments, how to format output from XCLI, and other commands which are executed on the XCLI client machine without communicating to a IBM XIV Storage System. Help, general formatting, defining configurations for CLI. Destination IBM-XIV Storage System, user name, user password, display options. A new version of this manual would be used after loading a new version of the XCLI onto the XCLI client machine. XCLI Reference Guide Describes the XCLI commands which are executed on the IBM XIV Storage System. Only the commands themselves are described in this guide. Commands for management of IBM XIV Storage System. For example, commands for creation and management of volumes, management of host pathing, etc. Parameters related to the function itself. For example, name, size, and pool of a volume being created with a vol_create command. After loading microcode which supports new CLI commands on the IBM XIV Storage System. Interactive and basic modes XCLI can be used in two modes: interactive and basic. The differences between these two modes are: v v v The basic mode requires you to login to a machine each time you issue a command, but the interactive mode requires you to login only once. Basic mode requires entering the command's syntax as a whole. Interactive mode allows for a shorter syntax. The interactive mode offers several command and argument completion features (hence its interactivity). Issuing commands in these two modes looks like this: Basic xcli -u user -p password -m 10.18.54.4 vol_list Interactive vol_list Note: Each of the batch mode parameters mentioned above is explained later in this manual. Chapter 1. Overview of XCLI utility 3

4 IBM XIV Storage System: XCLI Utility User Manual

Chapter 2. Getting started with XCLI Installing the XCLI utility Launching the XCLI utility This chapter gets you started with the XCLI Utility, covering the following topics: Installation and set-up v Installing the XCLI utility v Launching the XCLI utility v Logging off from XCLI utility v Interactive mode's features Command syntax An overview of the structure of the XCLI command and a quick-reference to its parameters. The XCLI utility is available on Windows, Linux and other platforms. Note: For the installation requirements and a list of available packages, see the Release Notes on our web site. Windows installation The installation package is wizard-driven. 1. Download the installation file. 2. Double-click it and follow the instructions on the screen. 3. See launching instructions on the next section. Linux installation 1. Download the installation file. 2. Extract using tar xzf into an appropriate directory on your system. Optional: add the installation directory to your PATH variable. 3. See launching instructions on the next section. Other platforms See the Release Notes for the availability of XCLI utility for other platforms, and for relevant installation instructions. The ways the XCLI utility is launched differ according to the hosting OS and operation mode. The following section describes the way the XCLI utility is launched on the following hosts and modes: v Windows host, interactive mode v Windows host, basic mode v Linux host, interactive mode v Linux host, basic mode Copyright IBM Corp. 2011 5

Windows host, interactive mode 1. Upon installing the IBM XIV GUI, the XCLI utility is available from the Programs menu: Start > Programs > XIV> XCLI The XCLI Session window is launched. 2. Follow the instructions on the screen and type: a. User name b. Password c. Machine IP/DNS 3. You are now connected to the machine specified above. The XCLI utility prompt appears on screen. Figure 2. The XCLI utility prompt on Windows From this prompt you can run XCLI commands, for example: vol_list Windows host, basic mode 1. Open Windows' command line interface. 2. Type c:\program files\xiv. 3. Run the XCLI command, including the XCLI identification parameters, for example: xcli -u user -p ******** -m 10.18.54.4 vol_list Linux host, interactive mode 1. Type xcli -w. A new session opens. 2. Follow the instructions on the screen and type: a. User name b. Password c. Machine IP/DNS 3. From the session's prompt you can run XCLI commands, for example: vol_list Linux host, basic mode 1. Run the XCLI command, for example: xcli -u user -p ******** -m 10.18.54.4 vol_list 6 IBM XIV Storage System: XCLI Utility User Manual

Logging off the XCLI utility Interactive mode features Exit the XCLI utility by either closing the window, or typing exit. Running XCLI commands in interactive mode offers command and argument completion, along with possible values to these arguments. Executing a command in interactive mode Simply type the command, for example: pool_list Command name completion Typing a character, or several characters, and pressing TAB offers all possible valid completions. For example: v cg version_get vol_by_id... vol_unlock cg_add_vol... cg_snapshot_create Commands syntax Command argument completion Typing a command that requires arguments and pressing TAB results in a list of optional values for these arguments. For example: vol_create The result is a list of arguments for this command. vol= size= size_block= pool= pool_create pool= The pool_create command requires several arguments, among them a name for the new pool. Typing the command with this argument but without its value results in a list of the possible values for this argument. >> pool_create pool= 8058 2nd Pool 8059 pool1 vol_list vol=v The result is a list of values that match the typed character. For example, a list of matching values of volumes which begin with "v". >> vol_list vol=v vol1 vol2 The XCLI utility has the following general syntax: xcli < <[ --file=file ] -c CONFIG -m IP1 [-m IP2 [-m IP3]] > -L -a <config> -m IP1 [-m IP2 [ -m IP3]] -d IP1 [-m IP2 [ -m IP3]] > Chapter 2. Getting started with XCLI 7

[-r] [ <-l --list> <-s --csv> <-x --xml> ] [ <-u --user> user ] [ <-p --password> password ] [-t [--fields=field1,field2,...]] [command] The parameters and options are described later in this document. Commands syntax quick-reference This guide describes command parameters and options for the XCLI utility. The following table is a quick-reference to the various parameters and options. -f The name of a configuration file that lists the machines you're working with. -c The machine where the command will be run. -m IP address of the machine on which the command runs. -L Lists the machines you're working with, as read from the configuration file. -a The name of the machine you're adding to the configuration file. -d Removes a machine from the configuration file. -r Name of a batch file that runs XCLI commands. -l Displays the command's output in user-readable format. -s Displays the command's output in CSV format. -x Displays the command's output in XML format. -u User. -p Password. -t Manages the fields of the command's output. -h Help. -y Suppresses the Are you sure? prompt. -v Prints the XCLI utility's version on the screen. command The actual command to be run. Syntax example The XCLI command syntax specifies the command to be run, along with its applicable parameters and their values. In the following example, the parameters to the left of the vol_list command specify the IBM XIV Storage System to which the command is being directed, and also specify the required user and password for this machine: xcli -u admin -p ********** -m 10.18.54.4 vol_list Identification parameters -u User. -p Password. Machine The machine is specified by either its IP address of the machine's name as listed on the configuration file. See Configuration parameters on page 12. -m The IP address of the machine this command is directed to. 8 IBM XIV Storage System: XCLI Utility User Manual

or -c The machine on which to execute the command. Command vol_list The command itself. Chapter 2. Getting started with XCLI 9

10 IBM XIV Storage System: XCLI Utility User Manual

Chapter 3. Using XCLI Identification parameters This chapter provides a detailed discussion on each of the XCLI command's parameters. This section covers the following: v Setting the user and password parameters v Setting the machine parameter(s) User and password parameters The XCLI utility and the IBM XIV Storage System provide a password controlled user id as security mechanism for controlling XCLI operation. Running in basic mode, user name and password are specified as follows: xcli -u admin -p ********** -c my_machine vol_list In this command: Identification parameters -u User. -p Password. Machine -c The machine on which to execute the command. See Configuration parameters on page 12. Command vol_list The command itself. The password handling mechanism is as follows: 1. Checking the user: v The -u or --user parameter on the command line is checked first and its value is used as the user name. v If the -u or --user parameter is not specified, an environment variable is used as a user name:xiv_xcliuser. 2. Checking the password: v The -p or --password parameter on the command line is checked first and its value is used as the password. v If the -p or --password parameter is not specified, an environment variable is used as the password.xiv_xclipassword. Note: If none of these two is specified, the command fails. Copyright IBM Corp. 2011 11

Defining XCLI Configurations Configuration parameters Most XCLI commands are directed to a specific machine by directly specifying the machine IP address (at least one address and up to three addresses per machine), by logging into an interactive session, or by specifying the configuration file that stores the machine's IP address(es). Specifying a machine using its IP address In the following example, the command is directed to a machine whose IP address is 10.18.54.4: xcli -u admin -p ********** -m 10.18.54.4 vol_list In this command: Identification parameters -u User. -p Password. Machine The machine is specified by its IP address. -m The IP address of the machine this command is directed to. Command vol_list The command itself. Specifying a machine by using a configuration file In the following example, the command is directed to a machine which is listed on the my_machine configuration file: xcli -u admin -p ********** -c my_machine vol_list In this command: Identification parameters -u User. -p Password. Machine The machine is specified by its name on the configuration file. -c The name of the machine as it was defined in the configuration file. For example, my_machine. Command vol_list The command itself. Creating a configuration file The configuration file lets you manage a list of the machines you're working with. The following options allow you to add and subtract machines from this file and to list them. 12 IBM XIV Storage System: XCLI Utility User Manual

Listing the available machines xcli [-f FILE] -L The configurations are read from a default file location, or from the file that is specified with [-f FILE]. Adding a new machine to the configuration file xcli [-f FILE] -a <config> -m IP1 [-m IP2 [ -m IP3]] IP1...IP3 are added to the configuration file at the default file location. If applicable, the addresses are added to the file that is specified in [-f FILE]. <config> is the configuration name of the machine you are adding to the list. Removing a machine from the configuration file xcli [-f FILE] -d IP1 [-m IP2 [ -m IP3]] IP1...IP3 are removed from the configuration file. If applicable, the addresses are removed from the file that is specified with [-f FILE]. Location of the configuration file Although adding and removing a machine from the configuration file doesn't request you to point at its location, this location (changed among operation systems) is hereby provided. Windows \Application Data\XIV\GUI10\properties UNIX In the home folder under.xiv Running commands in batch mode XCLI commands can be grouped together and run in a batch. This mechanism allows, for example, running an identical set of commands on multiple IBM XIV Storage Systems. Creating a text file for the commands Create a text file and write the commands without the xcli prefix or XCLI utility parameters. For example: pool_create pool=pool_00001 hard_size=171 soft_size=171 snapshot_size=65 vol_create vol=vol_00010 size=17 pool=pool_00001 vol_list vol=vol_00010 Which reads: v pool_create command, along with its arguments. This command will create a Pool, which is a prerequisite for creating a Volume. v vol_create command, along with its arguments, that creates a volume in the pool that has just been created. v vol_list command that displays the details of the newly created volume. Name the script file and store it. Running these commands in batch To run the batch file, you must specify the XCLI utility parameters: xcli -u admin -p ********** -m 10.18.54.4 -r "C:\Documents and Settings\avia\xcli\xcli_script.txt" Chapter 3. Using XCLI 13

Display options In this command: Identification parameters -u User. -p Password. Machine The machine is specified by either its IP address of the machine's name as listed on the configuration file. See Configuration parameters on page 12. -m The IP address of the machine to which this command is directed. or -c The machine to which the command is directed. The batch parameter -r The name of the batch file to run on the machine. Viewing the output The three commands of the example above create a pool, then create a volume, then display the volume's details. Hence, the result of running all three in batch would be: v Acknowledgement of the first command (where a Pool was created). v Acknowledgement of the second command (where a Volume was created). v A table with the details of the newly created volume is displayed on screen. Upon a failure Whenever one of the commands run in batch fails: 1. The script exits immediately. 2. No commands after the failing command are executed. 3. The error message that appears on the screen is the message of the specific XCLI command that failed. Using display options Output from an XCLI command can displayed in list, CSV and XML formats. Only one format can be specified. If you do not specify the format, it is displayed in a user-readable format. The available formats are: list Also known as user-readable format xcli -l csv xcli -s xml xcli -x Use the display options as follows: Interactive mode vol_list -s 14 IBM XIV Storage System: XCLI Utility User Manual

Basic mode xcli -u user -p ********** -m 10.18.54.4 -s vol_list In this command: Identification parameters -u User. -p Password. Machine The machine is specified by either its IP address of the machine's name as listed on the configuration file. See Configuration parameters on page 12. -m The IP address of the machine to which this command is directed. or -c The machine to which the command is directed. The display option -s In this example, CSV output. Command vol_list The command itself. Table display options When running a command with a list option (displaying the command's output in a user-readable format), you may specify which of the table's columns will be displayed on the screen. Determine the way the table is displayed as follows: Interactive mode vol_list -t "size" Single-command mode xcli -u admin -p ********** -m 10.18.54.4 vol_list -t "size" In this command: Access control xcli The utility we are running. -u User. -p Password. Machine The machine is specified by either its IP address of the machine's name as listed on the configuration file. See Configuration parameters on page 12. -m The IP address of the machine to which this command is directed. or -c The machine to which the command is directed. Chapter 3. Using XCLI 15

The table display option -t "size" The table display option, in this case the table will display only the "size" column. You may list any combination of the table's columns. Command vol_list The command itself. Printing XCLI help and version The following command prints the help text for the XCLI utility (in batch mode): xcli <-h --help> The following command prints the XCLI utility version: xcli <-v --version> 16 IBM XIV Storage System: XCLI Utility User Manual

Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATIONS AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publications. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time without notice. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Copyright IBM Corp. 2011 17

18 IBM XIV Storage System: XCLI Utility User Manual

Readers Comments We'd Like to Hear from You IBM XIV Storage System XCLI Utility User Manual Publication No. GC27-3915-00 We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy, organization, subject matter, or completeness of this book. The comments you send should pertain to only the information in this manual or product and the way in which the information is presented. For technical questions and information about products and prices, please contact your IBM branch office, your IBM business partner, or your authorized remarketer. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use the personal information that you supply to contact you about the issues that you state on this form. Comments: Thank you for your support. Send your comments to the address on the reverse side of this form. If you would like a response from IBM, please fill in the following information: Name Address Company or Organization Phone No. Email address

Readers Comments We'd Like to Hear from You GC27-3915-00 GC27-3915-00 Fold and Tape Please do not staple Fold and Tape International Business Machines PLACE POSTAGE STAMP HERE Fold and Tape Please do not staple Fold and Tape Cut or Fold Along Line Cut or Fold Along Line

U.S.A GC27-3915-00