xcli utility user manual - ibm · 2019-08-29 · xcli utility user manual xcli reference guide...

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 withlocal law.

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUTWARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THEIMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states (orregions) do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statementmay 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 Contractwith IBM Corp.

Contents

Chapter 1. Overview of XCLI utility . . . 1XCLI documentation. . . . . . . . . . . . 2Interactive and basic modes . . . . . . . . . 3

Chapter 2. Getting started with XCLI . . 5Installing the XCLI utility . . . . . . . . . . 5Launching the XCLI utility . . . . . . . . . 5Logging off the XCLI utility . . . . . . . . . 7Interactive mode features . . . . . . . . . . 7Commands syntax . . . . . . . . . . . . 7

Commands syntax quick-reference . . . . . . 8Syntax example . . . . . . . . . . . . 8

Chapter 3. Using XCLI . . . . . . . . 11Identification parameters . . . . . . . . . . 11

User and password parameters . . . . . . . 11Defining XCLI Configurations . . . . . . . 12Running commands in batch mode . . . . . 13

Display options . . . . . . . . . . . . . 14Using display options . . . . . . . . . . 14Table 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 maintainthe IBM XIV Storage System. XCLI commands are entered on an XCLI clientmachine (or XCLI client) supplied by the customer.

Some XCLI commands run directly on the XCLI client. But usually, XCLIcommands are sent by the XCLI client to the IBM XIV Storage System forexecution.

The XCLI relies on code running in two places: the XCLI client machine, and theIBM XIV Storage System. A single XCLI client machine usually supports multipleIBM XIV Storage Systems, and these IBM XIV Storage Systems may be runningdifferent microcode versions. The XCLI client code version is independent of theversion of microcode firmware which is running on the IBM XIV Storage System.When you receive a new version of IBM XIV Storage System microcode whichsupports additional XCLI system commands, you do not need to update the XCLIcode 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 thisdocument.

Definitions

XCLI client machine, XCLI clientThe machine on which the XCLI command is entered.

XCLI utility commandAn XCLI command which is executed on the XCLI client. An XCLI utilitycommand is not sent to an IBM XIV Storage System for processing. XCLIutility commands are used for setting up configurations on the XCLI clientand for queries (for example, of software version) which can be processedon the client.

Figure 1. The XCLI utility runs commands on the IBM XIV Storage System.

© Copyright IBM Corp. 2011 1

XCLI system commandAn XCLI command which is sent to the IBM XIV Storage System forexecution.

Interactive modeA means of entering XCLI commands on the XCLI client. Interactive modeis intended for real time command execution by a human being. When ininteractive mode, the IBM XIV Storage System IP address, user, andpassword information does not need to be specified for each command.

Basic modeA means of entering XCLI commands on the XCLI client. Basic moderequires specifying IP address and login information for each command.Also, additional output formatting options are available in basic mode.

XCLI identification parametersXCLI identification parameters identify the user executing the command,and the IBM XIV Storage System (if any) on which the command will beexecuted. XCLI identification parameters can be specified:v By entering them at the beginning of an interactive mode sessionv In a configuration filev When running a command in basic modev When running a list of commands as a batch

Communication between the XCLI client and the IBM XIV StorageSystem

The XCLI client and the IBM XIV Storage System communicate using SSL overTCP/IP. Each IBM XIV Storage System has three Ethernet ports used asmanagement interfaces, and each IBM XIV Storage System can be assigned up tothree IP addresses – one per management interface. Having three managementinterfaces provides redundancy, allowing management interface communication tocontinue on a different port and IP address should one of the ports, or thecustomer Ethernet network fail. When running a command, the XCLI client isprovided with these three IP addresses and tries each of them until communicationwith one of the IP addresses is successful.

XCLI documentationThe XIV Command Line Interface (XCLI) relies on code running in two places:

The XCLI clientThis is a hardware platform that has TCP/IP connectivity to the IBM XIVStorage 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 SystemThis is where most of the commands are executed. This part of thecommand is described in the XCLI Reference Guide. Commands executed onthe IBM XIV Storage System are also called XCLI system commands.

The XCLI documentation comes in two parts, the XCLI Utility Manual (thisdocument) and the XCLI Reference Guide. The table below describes theinformation contained in each.

2 IBM XIV Storage System: XCLI Utility User Manual

XCLI Utility User Manual XCLI Reference Guide

General Describes the general format ofXCLI command line arguments,how to format output fromXCLI, and other commandswhich are executed on the XCLIclient machine withoutcommunicating to a IBM XIVStorage System.

Describes the XCLI commandswhich are executed on the IBMXIV Storage System. Only thecommands themselves aredescribed in this guide.

Types of commands described Help, general formatting,defining configurations for CLI.

Commands for management ofIBM XIV Storage System.

For example, commands forcreation and management ofvolumes, management of hostpathing, etc.

Types of parameters described Destination IBM-XIV StorageSystem, user name, userpassword, display options.

Parameters related to thefunction itself. For example,name, size, and pool of avolume being created with a“vol_create” command.

Updated when A new version of this manualwould be used after loading anew version of the XCLI ontothe XCLI client machine.

After loading microcode whichsupports new CLI commands onthe IBM XIV Storage System.

Interactive and basic modesXCLI can be used in two modes: interactive and basic. The differences betweenthese two modes are: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.v Basic mode requires entering the command's syntax as a whole. Interactive

mode allows for a shorter syntax.v 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

Interactivevol_list

Note: Each of the batch mode parameters mentioned above is explained later inthis manual.

Chapter 1. Overview of XCLI utility 3

Chapter 2. Getting started with XCLI

This chapter gets you started with the XCLI Utility, covering the following topics:

Installation and set-up

v Installing the XCLI utilityv Launching the XCLI utilityv Logging off from XCLI utilityv Interactive mode's features

Command syntaxAn overview of the structure of the XCLI command and a quick-referenceto its parameters.

Installing the XCLI utilityThe XCLI utility is available on Windows, Linux and other platforms.

Note: For the installation requirements and a list of available packages, see theRelease Notes on our web site.

Windows installationThe 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 platformsSee the Release Notes for the availability of XCLI utility for otherplatforms, and for relevant installation instructions.

Launching the XCLI utilityThe ways the XCLI utility is launched differ according to the hosting OS andoperation mode. The following section describes the way the XCLI utility islaunched on the following hosts and modes:v Windows host, interactive modev Windows host, basic modev Linux host, interactive modev Linux host, basic mode


http://www.ibm.com/systems/support/storage/XIV

Windows host, interactive mode1. Upon installing the IBM XIV GUI, the XCLI utility is available from the

Programs menu:Start > Programs > XIV> XCLIThe XCLI Session window is launched.

2. Follow the instructions on the screen and type:a. User nameb. Passwordc. Machine IP/DNS

3. You are now connected to the machine specified above.The XCLI utility prompt appears on screen.

From this prompt you can run XCLI commands, for example:vol_list

Windows host, basic mode1. 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 mode1. Type xcli -w.

A new session opens.2. Follow the instructions on the screen and type:

a. User nameb. Passwordc. Machine IP/DNS

3. From the session's prompt you can run XCLI commands, for example:vol_list

Linux host, basic mode1. Run the XCLI command, for example:

xcli -u user -p ******** -m 10.18.54.4 vol_list

Figure 2. The XCLI utility prompt on Windows


Logging off the XCLI utilityExit the XCLI utility by either closing the window, or typing exit.

Interactive mode featuresRunning XCLI commands in interactive mode offers command and argumentcompletion, 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 validcompletions. For example:

v version_getvol_by_id...vol_unlock

cg cg_add_vol...cg_snapshot_create

Command argument completion

Typing a command that requires arguments and pressing TAB results in a list ofoptional values for these arguments. For example:

vol_createThe 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 aname for the new pool.

Typing the command with this argument but without its value results in alist of the possible values for this argument.>> pool_create pool=8058 2nd Pool 8059 pool1

vol_list vol=vThe result is a list of values that match the typed character. For example, alist of matching values of volumes which begin with "v".>> vol_list vol=vvol1 vol2

Commands syntaxThe 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-referenceThis guide describes command parameters and options for the XCLI utility. Thefollowing 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.

commandThe actual command to be run.

Syntax exampleThe XCLI command syntax specifies the command to be run, along with itsapplicable parameters and their values. In the following example, the parametersto the left of the vol_list command specify the IBM XIV Storage System to whichthe command is being directed, and also specify the required user and passwordfor this machine:xcli -u admin -p ********** -m 10.18.54.4 vol_list

Identification parameters

-u User.

-p Password.

MachineThe machine is specified by either its IP address of the machine's name aslisted on the configuration file. See “Configuration parameters” on page 12.

-m The IP address of the machine this command is directed to.


or

-c The machine on which to execute the command.

Command

vol_listThe command itself.

Chapter 2. Getting started with XCLI 9

Chapter 3. Using XCLI

This chapter provides a detailed discussion on each of the XCLI command'sparameters.

Identification parametersThis section covers the following:v Setting the user and password parametersv Setting the machine parameter(s)

User and password parametersThe XCLI utility and the IBM XIV Storage System provide a password controlleduser id as security mechanism for controlling XCLI operation. Running in basicmode, user name and password are specified as follows:xcli -u admin -p ********** -c my_machine vol_list

In this command:


-u User.

-p Password.

Machine

-c The machine on which to execute the command. See“Configuration parameters” on page 12.

Command


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 itsvalue 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.


Defining XCLI Configurations

Configuration parametersMost XCLI commands are directed to a specific machine by directly specifying themachine 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 thatstores the machine's IP address(es).

Specifying a machine using its IP addressIn the following example, the command is directed to a machine whose IPaddress is 10.18.54.4:xcli -u admin -p ********** -m 10.18.54.4 vol_list

In this command:


-u User.

-p Password.

MachineThe machine is specified by its IP address.

-m The IP address of the machine this command is directed to.

Command


Specifying a machine by using a configuration fileIn the following example, the command is directed to a machine which islisted on the my_machine configuration file:xcli -u admin -p ********** -c my_machine vol_list

In this command:


-u User.

-p Password.

MachineThe machine is specified by its name on the configuration file.

-c The name of the machine as it was defined in theconfiguration file. For example, my_machine.

Command


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 andto list them.


Listing the available machinesxcli [-f FILE] -LThe configurations are read from a default file location, or from the filethat is specified with [-f FILE].

Adding a new machine to the configuration filexcli [-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 [-fFILE].<config> is the configuration name of the machine you are adding to thelist.

Removing a machine from the configuration filexcli [-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'trequest you to point at its location, this location (changed among operationsystems) is hereby provided.

Windows\Application Data\XIV\GUI10\properties

UNIX In the home folder under .xiv

Running commands in batch modeXCLI commands can be grouped together and run in a batch. This mechanismallows, for example, running an identical set of commands on multiple IBM XIVStorage Systems.

Creating a text file for the commands

Create a text file and write the commands without the xcli prefix or XCLI utilityparameters. For example:pool_create pool=pool_00001 hard_size=171 soft_size=171 snapshot_size=65vol_create vol=vol_00010 size=17 pool=pool_00001vol_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

In this command:


-u User.

-p Password.

MachineThe machine is specified by either its IP address of the machine's name aslisted 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 batchwould 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.

Display options

Using display optionsOutput from an XCLI command can displayed in list, CSV and XML formats. Onlyone format can be specified. If you do not specify the format, it is displayed in auser-readable format. The available formats are:

listAlso known as user-readable format

xcli -l

csvxcli -s

xmlxcli -x

Use the display options as follows:

Interactive modevol_list -s


Basic modexcli -u user -p ********** -m 10.18.54.4 -s vol_list

In this command:


-u User.

-p Password.

MachineThe machine is specified by either its IP address of themachine's name as listed on the configuration file. See“Configuration parameters” on page 12.

-m The IP address of the machine to which thiscommand is directed.

or


The display option

-s In this example, CSV output.

Command


Table display optionsWhen running a command with a list option (displaying the command's output ina user-readable format), you may specify which of the table's columns will bedisplayed on the screen.

Determine the way the table is displayed as follows:

Interactive modevol_list -t "size"

Single-command modexcli -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.

MachineThe machine is specified by either its IP address of the machine'sname as listed on the configuration file. See “Configurationparameters” on page 12.

-m The IP address of the machine to which this command isdirected.

or


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


Printing XCLI help and versionThe 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>


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 documentin other countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATIONS “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publications. IBM may make improvementsand/or changes in the product(s) and/or program(s) described in this publicationat any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct 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 itbelieves appropriate without incurring any obligation to you.


Readers’ Comments — We'd Like to Hear from You

IBM XIV Storage SystemXCLI 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 theinformation 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, yourIBM 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 anyway it believes appropriate without incurring any obligation to you. IBM or any other organizations will only usethe 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 YouGC27-3915-00

GC27-3915-00

��Cut or FoldAlong Line

Cut or FoldAlong Line

Fold and Tape Please do not staple Fold and Tape

Fold and Tape Please do not staple Fold and Tape

PLACE

POSTAGE

STAMP

HERE

International Business Machines

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

_

��

U.S.A

GC27-3915-00