IBM XIV User Manual

Version 11.4.x

IBM XIV Storage System User Manual



GC27-3914-05

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 International Business Machines Corporation 2008, 2012.

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

Chapter 1. Introduction ........1

Purpose and Scope ............1

Intended Audience ............1

Related Documentation ...........1

Documentation Conventions .........2

Abbreviations ..............2

Parameter Definitions ...........2

Accessibility features for IBM XIV Storage System . . 2

Chapter 2. Host and Cluster

Management .............5

Adding a Host to a Cluster .........6

Creating a Cluster ............7

Deleting Clusters .............7

Listing Clusters .............8

Removing a Host from a Cluster........9

Renaming Clusters ............10

Adding a Port to a Host ..........10

Defining a New Host ...........11

Deleting a Host .............13

Listing Hosts ..............14

Listing Ports ..............15

Removing a Port from a Host ........16

Renaming a Host ............17

Updating a Host Definition .........18

Mapping a Volume to a Host or Cluster .....19

Listing the Mapping of Volumes to Hosts or

Clusters ...............21

Setting the Special Type of Hosts or Clusters . . . 23
Listing Hosts/Cluster to which a Volume is Mapped 23
Unmapping a Volume from a Host or Cluster . . . 24
Set the Default Idle Time for Unmapping a Volume 26

Creating a Performance Class ........26

Deleting a Performance Class ........27

Renaming a Performance Class ........28

Listing Details on Performance Classes .....29

Adding a Host to a Performance Class .....29

Removing a Host from its Performance Class . . . 30

Setting the Rate for a Performance Class.....31

Listing Host Profiles ...........32

Updates the Host Profile ..........33

Removes the Profile of the Specified Host ....34

Enable Host Profiler Functionality .......34

Disable Host Profiler Functionality ......35

Locking a Volume ............52

Renaming a Volume ...........53

Resizing a Volume ............54

Unlocking a Volume ...........58

Chapter 4. LUN Mapping Management 61

Chapter 5. Volume Snapshot

Management ............63

Changing a Snapshot Deletion Priority .....63

Creating a Snapshot ...........64

Deleting a Snapshot ...........67

Duplicating a Snapshot ..........68

Formatting a Snapshot...........70

Listing Snapshot Information ........71

Restoring a Volume from a Snapshot ......73

Chapter 6. Consistency Group

Management ............77

Adding a Volume to a Consistency Group ....77

Creating Consistency Groups ........81

Deleting a Consistency Group ........82

Listing Consistency Groups .........83

Removing a Volume from a Consistency Group . . 84

Renaming Consistency Groups ........86

Suspend I/O Execution on Consistency Group . . 87

Resume I/O Execution ..........88

List Consistency Groups Pause I/O State ....89

Creates a Cross-System Consistency Group ....90

Associates an Existing Consistency Group to a
Cross-System Consistency Group Definition . . . 91
Removes an Existing Consistency Group from a
Cross-System Consistency Group Definition . . . 93
Adds a Remote System Name to the Cross-System

Consistency Group Definition ........94

Removes a Remote System Name from a
Cross-System Consistency Group Definition . . . 95
Lists Cross-System Consistency Group Definitions

Along With Contained Consistency Groups....96

Retrieve The Names of Remote Systems Part of The

Specified Cross-System Consistency Group ....97

Deletes a Cross-System Consistency Group ....98

Lists Cross-System Consistency Group Definitions 99

Chapter 3. Volume Management ....37

Clearing Reservations of a Volume ......37

Listing Reservation Keys ..........38

Listing Volume Reservations .........39

Finding a Volume Based on a SCSI Serial Number 40

Copying Volumes ............42

Creating a Volume ............44

Deleting a Volume ............46

Formatting a Volume ...........48

Listing Volumes .............49

Chapter 7. Snapshot Set Management 101

Snapshotting a Consistency Group ......101

Changing Snapshot Group Deletion Priority . . . 104

Deleting a Snapshot Group .........105

Disbanding a Snapshot Group ........106

Duplicating a Snapshot Group........107

Formatting a Snapshot Group ........108

Listing Snapshot Groups .........109

Locking a Snapshot Group .........111

Renaming a Snapshot Group ........112

iii

Restoring a Consistency Group from a Snapshot

Group................113

Unlocking a Snapshot Group ........114

Sets a Snapshot Group Descriptor ......115

Returns the Snapshot Group's Descriptor ....116

Chapter 8. Storage Pool Management 119

Moving Consistency Groups between Storage Pools

or or Grouped Pools ...........119

Changing Pool Limitation .........120

Changing Pool Settings for Snapshots .....121

Creating Storage Pools ..........124

Deleting a Storage Pool ..........126

Listing Storage Pools ...........127

Renaming a Storage Pool .........128

Resizing a Storage Pool ..........129

Moving a Volume between Storage Pools ....131

Chapter 9. System Management . . . 135

Displaying Current Consumed Capacity of the

System ...............136

Printing Configuration Parameters ......137

Setting Configuration Parameters .......138

Testing the DNS ............139

Printing Help .............140

Printing the Current Maintenance Urgency . . . 142
Adding a Patch Script that will be Run on System's

Modules ...............143

Deletes a Patch Script ..........145

Listing Patch Scripts ...........145

Updating a Patch Script that will be Run on

Systems Modules ............147

Gets a Patch Script Log ..........148

Trigger Patch Script Execution on One or All

Modules. ...............149

Get Patch Script Execution Inforamtion .....150

Shutting Down .............151

Changing the Operational State .......153

Listing Operational State .........154

Local Storage Free Space .........154

Showing System Runtime, Power Consumption,
System Alert, Numbet Of Psus With No Power In . 155
Showing System Capacity, Free Space and Spares 156

Showing the Current Time .........157

Setting the System's Time .........157

Listing Optional Time Zones ........158

Setting the Time Zone ..........159

Aborting the Upgrade to a New Software Version 159
Initiating Download of a New Software Version 160

Canceling an Upgrade Download Process ....161

Forcing a Continuation of the Upgrade Process . . 161

Displaying Status of Upgrade Process .....162

Upgrading a System ...........164

Validating the Prerequisites of an Upgrade to a

New Software Version ..........165

Printing the Current System Version......166

Showing Values of VPD Parameters.......166

Setting VPD Parameters ..........167

Showing Values of Maintenance Module

Parameters. ..............169

Displaying the System's MIB File .......170

Retrieves the Electronic License Acceptance Status. 171
Retrieving a Fragment of the Electronic License File 171

Accept the Electronic License Agreement ....172

Chapter 10. Remote Target

Connectivity ............175

Setting a Threshold for Link Disruption Duration

that Triggers an Event ..........176

Updating the Target Mirroring Configuration. . . 177
Activating Connectivity to a Remote Target . . . 178
Deactivating Connectivity to a Remote Target . . 179

Defining Connectivity to a Remote Target ....180

Deleting Connectivity to a Remote Target ....182

Listing Target Connectivity Definitions .....183

Defining a Remote Target .........184

Deleting a Remote Target .........186

Listing Remote Targets ..........187

Allowing Remote Mirroring Access ......188

Activating a Port ............189

Adding a New Port to a Remote Target ....190

Deactivating a Port ...........191

Deleting a Port from a Remote System .....192

Listing the Ports of a Remote Target ......193

Renaming a Remote Target .........194

Updating the Target Configuration ......194

Chapter 11. Remote Mirroring ....197

Canceling a Snapshot Mirror (Ad Hoc Sync Job) 198
Creating a Snapshot Mirror (Ad Hoc Sync Job) . . 199

Activating Mirroring ...........203

Changing the RPO for Local/Remote System . . . 205
Changing a the Mirroring Peers' Designation . . . 206
Changing a Mirroring Schedule for Remote Slave

Peers ................208

Changing the Roles of a Mirrored Volume....210

Changing a Mirroring Schedule for Local Peers . . 212

Creating a Mirroring Definition .......214

Deactivating Mirroring ..........219

Deleting a Remote Mirroring Definition ....221

Viewing Mirroring Status .........223

Obtaining Statistics On Past Sync Jobs .....226

Switching Roles between Master and Slave . . . 227

Retrieving RPO Threshold .........229

Setting RPO Threshold ..........229

Changes the Interval For a Schedule......230

Creating a Schedule Object .........232

Triggering a Schedule ..........233

Deletes a Schedule Object .........234

Listing a Schedule Object .........235

Renaming a Schedule Object ........236

Viewing Sync Job Status ..........237

Chapter 12. Data Migration .....239

Activating Data Migration .........239

Deactivating Data Migration ........240

Defining Data Migration Configuration .....241

Deleting the Data Migration Process ......243

Listing Data Migration Statuses .......244

Testing the Data Migration Definition .....245

iv IBM XIV Storage System User Manual

Chapter 13. IBM Hyper-Scale Mobility 247

Creating an IBM Hyper-Scale Mobility Relation 247

Activates the Volume Migration .......250

Deactivates IBM Hyper-Scale Mobility Migration 251
Aborts a Defined or Activated IBM Hyper-Scale

Mobility Process ............252

Moves the IBM Hyper-Scale Mobility Source

Volume to a Proxy State ..........254

Deletes an IBM Hyper-Scale Mobility Relationship 255

Listing IBM Hyper-Scale Mobility Status ....256

Chapter 14. Event Handling .....259

Generating a Custom Event ........260

Defining a New Event Notification Destination . . 261

Deleting a Destination ..........263

Listing Event Notification Destinations .....265

Renaming a Destination ..........266

Testing a Destination ...........267

Updating an Event Notification Destination . . . 268
Adding a Destination to a Destination Group . . 271

Creating a Destination Group ........272

Deleting a Destination Group ........273

Listing Destination Groups .........274

Removing a Destination from Destination Group 274

Renaming a Destination Group .......275

Clearing Alerting Events .........276

Listing Events .............278

Listing Uncleared Alerting Events ......280

Setting the Threshold for Events Notification . . . 281

Listing Thresholds............282

Generating a Custom Event ........284

Receiving a MM Heartbeat .........284

Activating a Rule ............286

Creating Event Notification Rules ......286

Deactivating a Rule ...........289

Deleting Event Notification Rules ......290

Listing Event Notification Rules .......291

Renaming Event Notification Rules ......292

Updating an Event Notification Rule .....293

Defining an SMS Gateway .........296

Deleting an SMS Gateway .........298

Listing SMS Gateways ..........299

Prioritizing SMS Gateways .........299

Renaming an SMS Gateway ........301

Updating an SMS Gateway .........302

Defining a New SMTP Gateway .......303

Deleting an SMTP Gateway ........305

Listing SMTP Gateways ..........306

Prioritizing SMTP Gateways ........307

Renaming an SMTP Gateway ........308

Updating an SMTP Gateway ........309

Chapter 15. IP Configuration .....311

Adding Ethernet Ports to IP Interfaces .....311

Creating a New IP Interface ........313

Deleting IP Interfaces ...........315

Listing IP Interface Configuration ......315

Listing IP Interface Addresses ........317

Showing the Status and Configuration of Ethernet

Ports ................318

Removing Ethernet Ports from IP Interfaces . . . 319

Renaming an IP Interface .........320

Printing the ARP Database of an IP Interface . . . 320

Testing the Traceroute to a Remote IP .....321

Testing the Traceroute to a Remote IP .....322

Updating an IP Interface .........323

Defines a New IPSec Connection .......325

Updates an Existing IPSec Connection .....327

Removes an Existing IPSec Connection .....328

Listing IPSec Connections .........328

Listing IPSec Tunnels...........329

Connecting to a Support Center .......330

Defining a Support Center .........332

Deleting a Support Center .........333

Disconnecting from a Support Center .....333

Listing Support Centers ..........334

Presenting Status of a Support Center .....335

Enabling TCP SACK ...........335

Disabling TCP SACK ...........336

Chapter 16. PKI configuration ....337

Listing PKI Items ............337

Generate Certificate Signing Request .....338

Generate a Private Key and CSR .......339

Delete a PKI Content ...........340

Change PKI Symbolic Name ........341

Import Signed Certificate .........342

Import PKCS#12 Certificate.........343

Show Signed Certificate Details .......344

Update PKI Certificate or Services ......344

Chapter 17. Infiniband........347

Moves Existing Infiniband Port .......347

Lists Configured IB Ports .........348

Resumes a Port That Was Shutdown Due to

Performance Problems ..........349

Resumes a Module Infiniband Port That Was

Shutdown Due to Performance Problems ....350

Collecting IB Switch Logs .........351

List Configured IB Switches. ........352

List SM Port Service Statuses ........355

Chapter 18. Access Control .....357

Adding an Access Control Definition .....357

Deleting an Access Control Definition .....358

Listing Access Control Definitions ......360

Determining Whether Challenge-Response
Authentication is Enabled on System Consoles. . . 361
Enabling/Disabling Challenge-Response

Authentication on System Consoles. ......361

Adding an LDAP Server Definition ......362

Testing an LDAP Configuration .......363

Listing LDAP Configuration Parameters ....365

Configuring LDAP in the System .......366

Listing LDAP Servers Defined in the System . . . 370

List LDAP Server Users ..........371

Listing LDAP-Based Authentication Mode....372

Enabling or Disabling LDAP-Based Authentication

Mode ................373

Updating an LDAP Server Definition .....374

Contents v

Removing an LDAP Server Definition .....375

Running ldapsearch Utility .........376

Defining a New User ...........377

Deleting a User .............379

Adding Users to a User Groups .......380

Creating User Groups ..........381

Deleting a User Group ..........383

Listing User Groups ...........384

Removing a User from a User Group .....385

Renaming User Groups ..........386

Updating a User Group ..........387

Listing Users .............388

Renaming Users ............389

Updating a User Definition .........390

Chapter 19. Fibre Channel and iSCSI

Configuration and Status ......393

Discovering FC Hosts ..........393

Changing FC Port Configuration .......394

Listing FC Ports ............395

Resetting FC Ports ............397

Listing Connectivity to Hosts ........397

Chapter 20. Hardware Maintenance 401

Listing ATS Configuration .........402

Listing CFs in the System .........405

Listing System Components ........406

Phasing Out a Component .........407

Phasing In a Component .........409

Testing a Component ...........411

Setting a Component as Equipped ......412

Listing System Components Requiring Service . . 414
Forces the Service Required of a Component to OK 415

Online Upgrading Firmware ........415

Aborting a Firmware Upgrade .......417

Status of a Firmware Upgrade Process .....418

Per-Component Progress of a Firmware Upgrade

Process ...............419

Listing InfiniBand HCA Adapters in the System 420

Listing CNA Adapters in the System .....422

Listing DIMMs in the System ........423

Listing CPUs in the System.........425

Listing MaintenanceModules in the System . . . 427

Listing NICs in the System .........429

Listing Modules Internal Temperatures .....431

Monitoring Rebuild or Redistribution Processes 434

Listing Disk Status ...........435

Listing Module Configuration ........437

Reset Ethernet Interface ..........439

Check Modules Serial Connections ......440

Lists Serial Consoles Statuses ........440

Listing UPS Component Statuses .......441

Listing Service Status ...........444

Listing PSUs in the System .........445

Resetting a Failed Command Service. .....447

Stopping System Traces ..........448

Resuming System Traces .........448

Listing Status of System Traces .......449

Create traces snapshot ..........450

Lists Traces Snapshots on a Module.......451

Notifying the System of a Technician at Work . . 452

Enables XIV Support Access ........453

Disables XIV Support Access ........455

Shows XIV Support Window ........455

Cancel UPS Calibration ..........456

Check UPS Monitor Cables .........457

Set the UPS Battery Date .........457

Start UPS Calibration ...........458

Start UPS Self Test............459

TurnUPSOff.............460

Listing Fans in the System .........461

Listing SSDs that are Used as Flash Cache in the

System ...............462

Disabling the SSD Caching Feature ......464

Enabling the SSD Cache Feature .......465

Getting the Default State of the SSD Caching . . . 466

Setting a Default State for SSD Caching ....467

Overriding the SSD Caching State ......467

Shows System Average Power Consumption . . . 468

Shows System Average Temperature......469

Chapter 21. Statistics ........471

Getting Performance Statistics ........471

Retrieving History Usage .........478

Chapter 22. Meta-data ........481

Setting Meta Data ............481

Deleting Meta Data ...........482

Listing Meta Data ............483

Chapter 23. Encryption enablement

and support commands .......485

Disable Encryption ...........485

Enabling Encryption ...........487

Define A Keyserver ...........488

Remove Keyserver ...........490

Display Keyserver Status .........491

Obtain New Master Key ..........492

Rename Keyserver ...........494

Change Keyserver Properties ........495

Recovery Key Enter ...........496

Recovery Key Generation .........497

Retrieve the Security Admin Recovery Key . . . 499

Rekey the Security Admins .........501

Recovery Key Status ...........502

Recovery Key Verification .........504

Recovery Key Share Information .......505

Chapter 24. Events .........507

Chapter 25. Return Codes ......635

Notices ..............637

Glossary .............639

vi

IBM XIV Storage System User Manual

Chapter 1. Introduction

Reliable high-end storage systems are critical for the successful operation of
businesses. The XIV Grid Storage Platform is designed to guarantee secure,
dependable, enterprise-grade data storage and access, straightforward and
non-intrusive installation and upgrade and full scalability.

At the heart of the system are proprietary and innovative algorithms to offset any
imaginable hardware malfunction and to minimize maintenance requirements. The
flexibility and robustness of the system is further enhanced by virtue of the
off-the-shelf hardware components (such as the SATA disk drives) that are easily
integrated and supported.

Purpose and Scope

This document presents the XIV Command Line Interface (XCLI) functions.
Relevant tables, charts, sample outputs and appropriate examples are also
provided, as applicable.

This document contains the following chapters:

Introduction Introduces the document, intended audience,

CLI Commands Provides detailed information about each

Event Descriptions Provides detailed information about the events

Return Codes Lists all UNIX return codes returned by the XCLI

Glossary Provides an alphabetically ordered list of the

Index Provides an index of this document.

Intended Audience

This document serves as a reference for System Administrators and all IT staff that
interface with the system via the CLI.

Related Documentation

v IBM XIV Product Overview

v IBM XIV XCLI Utility

v IBM XIV Storage System Release Notes

related documentation and document conventions.

command in the XIV Command Line Interface
(XCLI).

generated by the system.

command.

definitions of the key terms and abbreviations
used in this document.

1

Documentation Conventions

v Notes are embedded in the text, as shown in the example below.

Note:

This is an example of a Note.

v Code samples or output samples are documented in monospaced font. The text

box for examples and output is framed around it. For example:

–

Example:

vol_rename vol=DBVolume new_name=DBVolume1

–

Output:

Command completed successfully

Abbreviations

OLVM Online Volume Mobility - denotes an IBM

Hyper-Scale Mobility relationship.

Parameter Definitions

Definition Description Syntax

IP Address An address of the form

Existing <object> The name of an object. The

Format string with runtime
tokens.

iSCSI initiator name. A legal name of iSCSI initiator. Up to 253 characters with no

N.N.N.N, where each N is a
number between 0 and 255

object must already exist

A format string, where
pre-defined tokens are replaced
with run time information.

Accessibility features for IBM XIV Storage System

Accessibility features help users who have a disability, such as restricted mobility
or limited vision, to use information technology products successfully.

n.n.n.n for n between 0 and 255.

Letters, digits, ~, \, ., _, -, with a
maximum of 63, no spaces at the
beginning and the end, no ALL
or NONE (regardless of case).

Letters, digits, ., - with a
maximum of 64, with {} to define
tokens.

spaces.

Accessibility features

These are the major accessibility features associated with the IBM®XIV®Storage
System:

v You can use screen-reader software and a digital speech synthesizer to hear what

is displayed on the screen. PDF documents have been tested using Adobe
Reader version 7.0. HTML documents have been tested using JAWS version 13.0.

v This product uses standard Windows navigation keys.

2 IBM XIV Storage System User Manual

Keyboard navigation

You can use keys or key combinations to perform operations and initiate menu
actions that can also be done through mouse actions. You can navigate this
publication and the Information Center from the keyboard by using the shortcut
keys for your browser or screen-reader software. See your browser or screen-reader
software Help for a list of shortcut keys that it supports.

IBM XIV and accessibility

See the IBM Human Ability and Accessibility Center http://www-03.ibm.com/
able/ for more information about the commitment that IBM has to accessibility.

Chapter 1. Introduction 3

4 IBM XIV Storage System User Manual

Chapter 2. Host and Cluster Management

The following sections describe the XIV Command Line Interface (XCLI) for host
and cluster management.

The sections are listed as follows:

v cluster_add_host(Adds a host to a cluster.)

v cluster_create(Creates a new cluster.)

v cluster_delete(Deletes a cluster.)

v cluster_list(Lists a specific cluster or all of them.)

v cluster_remove_host(Removes a host from a cluster.)

v cluster_rename(Renames a cluster.)

v host_add_port(Adds a port address to a host.)

v host_define(Defines a new host to connect to the XIV system.)

v host_delete(Deletes a host. )

v host_list(Lists a specific host or all hosts.)

v host_list_ports(Lists all the ports of a host)

v host_remove_port(Removes a port from a host.)

v host_rename(Renames a host. )

v host_update(Updates a host definition.)

v map_vol(Maps a volume to a host or a cluster.)

v mapping_list(Lists the mapping of volumes to a specified host or cluster.)

v special_type_set(Sets the special type of a host or a cluster.)

v vol_mapping_list(Lists all hosts and clusters to which a volume is mapped. )

v unmap_vol(Unmaps a volume from a host or a cluster.)

v unmap_vol_set_default_idle_time(Sets the default idle time required for a

volume before unmapping it)

v perf_class_create(Creates a Performance Class)

v perf_class_delete(Deletes a Performance Class)

v perf_class_rename(Renames a Performance Class)

v perf_class_list(Lists Performance Classes)

v perf_class_add_host(Adds a host to a Performance Class)

v perf_class_remove_host(Removes a host from its Performance Class)

v perf_class_set_rate(Sets the rate for a Performance Class)

v host_profile_list(lists all host profiles)

v host_profile_set(updates the host profile)

v host_profile_clear(removes the profile of the specified host)

v host_profiler_enable(Enable host profiler functionality)

v host_profiler_disable(Disable host profiler functionality)

The following commands are no longer in use:

v host_define_fc (This command has been replaced by the host_define command)

v host_define_iscsi (This command has been replaced by the host_define

command)

5

v host_luns_list (This command has been replaced by map_list_luns)

Adding a Host to a Cluster

Adds a host to a cluster.

cluster_add_host cluster=ClusterName host=HostName map=MapName

Parameters:

Name Type Description Mandatory

cluster Object name Name of the cluster to

host Object name Host to be added to the

map Enumeration Override the mapping

This command adds a host to a cluster.

This command fails if the host already belongs to another cluster.

contain the host.

Y

Y

cluster.

Y
of the host, cluster or
keep the host mapping
and add above it the
cluster mapping

This operation succeeds if the host already belongs to the specified cluster and has
no effect.

Using the map parameter:

v If the map parameter is cluster, the mapping of the host and host type is

changed to be the cluster's mapping and type.

v If the map parameter is host, the mapping of the cluster and its host type is

changed to be the host's mapping and type.

v If the map parameter is clusterWithHostExceptions the host is keeping his

mapping and apply on it the cluster mapping as well

v Use map=host to add a host to an empty cluster. This way to cluster will receive

the host’s mapping.

The host or cluster is getting a single SCSI unit attention message, even if the
change affects multiple volumes.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

6 IBM XIV Storage System User Manual

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v CLUSTER_BAD_NAME

Cluster name does not exist

v HOST_BELONGS_TO_ANOTHER_CLUSTER

Host already belongs to another cluster

v HOST_AND_CLUSTER_HAVE_CONFLICTING_MAPPINGS

Host mapping conflicts with cluster mapping

v HOST_AND_CLUSTER_HAVE_DIFFERENT_MAPPING_TYPE

Host mapping type is not the same as the cluster mapping type

Creating a Cluster

Creates a new cluster.

cluster_create cluster=ClusterName

Parameters:

Name Type Description Mandatory

cluster Object name Name of the cluster to

be created.

Y

This command creates a new cluster. The newly created cluster does not contain
hosts, has the default type and has no mapping.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v CLUSTER_NAME_EXISTS

v MAX_CLUSTERS_REACHED

Deleting Clusters

Deletes a cluster.

Cluster name already exists

Maximum number of clusters already defined

cluster_delete cluster=ClusterName

Chapter 2. Host and Cluster Management

7

Parameters:

Name Type Description Mandatory

cluster Object name Cluster to be deleted. Y

This command deletes a cluster. All hosts contained in the cluster remain active
and are not deleted. The special type of each host is set to the cluster's special
type. The mapping of each host is set to the cluster's mapping. No I/O
interruption is caused by this command.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_DELETE_ASSIGNED_CLUSTER

Cluster Cluster' has hosts in it. Are you sure you want to delete it?

Listing Clusters

Completion Codes:

v CLUSTER_BAD_NAME

Cluster name does not exist

Lists a specific cluster or all of them.

cluster_list [ cluster=ClusterName ]

Parameters:

Name Type Description Mandatory Default

cluster Object name Cluster to be

listed.

This command lists a specific cluster or all of them. For each cluster, a special type
and a comma separated list of hosts is listed.

Id Name Default Position

name Name 1

hosts Hosts 2

type Type 3

creator Creator 4

user_group User Group 5

N All clusters.

8 IBM XIV Storage System User Manual

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Removing a Host from a Cluster

Removes a host from a cluster.

cluster_remove_host cluster=ClusterName host=HostName

Parameters:

Name Type Description Mandatory

cluster Object name Cluster name. Y

host Object name Host to be removed

from cluster.

Y

This command removes the specified host from a cluster. The host then no longer
belongs to any cluster. The host's special type and mapping remain identical to the
cluster's special type and mapping, and therefore, I/O is not interrupted. The
association of the host with user or user groups remains the same as the cluster's
association.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v CLUSTER_BAD_NAME

Cluster name does not exist

v HOST_NOT_IN_CLUSTER

Host is not part of specified cluster

Chapter 2. Host and Cluster Management 9

Renaming Clusters

Renames a cluster.

cluster_rename cluster=ClusterName new_name=Name

Parameters:

Name Type Description Mandatory

cluster Object name Cluster to be renamed. Y

new_name Object name New name of cluster. Y

This command renames the specified cluster.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v CLUSTER_BAD_NAME

Cluster name does not exist

v CLUSTER_NAME_EXISTS

Cluster name already exists

Adding a Port to a Host

Adds a port address to a host.

host_add_port host=HostName < fcaddress=wwpn | iscsi_name=iSCSIName >

Parameters:

Name Type Description Mandatory

host Object name The host name. Y

fcaddress N/A FC address of the

iscsi_name iSCSI initiator name iSCSI initiator name of

The FC port address or iSCSI initiator (port) name assigned to the host must be
unique per XIV system. The FC port name must be exactly 16 characters long, in
hexadecimal form.

added port.

N

N
the newly added port.

10 IBM XIV Storage System User Manual

Only the following alphanumeric characters are valid: 0-9, A-F, a-f. In addition to
the 16 characters, colons (:) may be used as separators in the 16 character port
name. The iSCSI initiator name may not exceed 253 characters and may not
contain any blank spaces.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v HOST_PORT_EXISTS

Host with this port ID already defined

v ISCSI_HOST_ILLEGAL_PORT_NAME

Port name for iSCSI Host is illegal

Troubleshooting: Port names for iSCSI Hosts must contain only printable
characters.

v MAX_PORTS_REACHED

Maximum number of ports already defined in the system

v TARGET_PORT_BAD_ADDRESS

Remote port address is illegal or does not belong to the remote target

v PORT_EXISTS

Port is already defined

v OLVM_LINK_IS_NOT_UP

IBM Hyper-Scale Mobility link is not up. The mapping list cannot be updated.

v REMOTE_MAX_VIRTUAL_HOSTS_REACHED

Maximum number of remote virtual hosts already defined

Defining a New Host

Defines a new host to connect to the XIV system.

host_define host=HostName [ cluster=ClusterName ]
[ iscsi_chap_name=iscsiChapName iscsi_chap_secret=iscaiPass ]

Parameters:

Name Type Description Mandatory Default

host Object name Name of host to be

cluster Object name Name of cluster to

created.

contain host.

Y N/A

N No cluster.

Chapter 2. Host and Cluster Management

11

Name Type Description Mandatory Default

iscsi_
chap_name

iscsi_
chap_
secret

String The host's CHAP

name identifier

String Password of

initiator used to
authenticate to XIV
when CHAP is
enabled

N [None]

N [None]

This command defines a host that will attach to the IBM XIV Storage System. The
name of the host must be unique in the system.

Note:

Use the Adding a Port to a Hostcommand to add port addresses to this host.
Specifying the cluster is optional.

The parameters iscsi_chap_name and iscsi_chap_secret must either be both
specified - or both left unspecified.

If the iscsi_chap_secret does not conform to the required secret length (96-128 bits)­the command will fail.

The command checks whether the iscsi_chap_name and iscsi_chap secret are
unique. In case they are not, it displays an error message (but will not fail the
command).

The secret has to be between 96 bits and 128 bits. There are 3 ways to enter the
secret:

v Base64: requires to prefix the entry with 0b. each subsequent character entered is

treated as a 6 bit equivalent length

v Hex: requires to prefix the entry with 0x. each subsequent character entered is

treated as a 4 bit equivalent length

v String: requires no prefix (cannot be prefixed with 0b or 0x). Each character

entered is treated as a 8 bit equivalent length

Example:

host_define host=server1

Output:

Command executed successfully.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

12 IBM XIV Storage System User Manual

Deleting a Host

User Category Permission

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ISCSI_CHAP_NAME_AND_SECRET_NOT_UNIQUE

Both iSCSI CHAP name and secret are already used by another host. Are you
sure you want to reuse those values?

Completion Codes:

v HOST_NAME_EXISTS

Host name already exists

v MAX_HOSTS_REACHED

Maximum number of hosts already defined

v CLUSTER_BAD_NAME

Cluster name does not exist

Deletes a host.

host_delete host=HostName

Parameters:

Name Type Description Mandatory

host Object name The host name. Y

This command deletes a host. After this command is executed, the deleted host can
no longer connect to the system, and I/O requests from this host are not handled.

Example:

host_delete host=mailserver

Output:

Command completed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Chapter 2. Host and Cluster Management

13

Listing Hosts

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_DELETE_HOST

Are you sure you want to delete host Host?

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

Lists a specific host or all hosts.

host_list [ host=HostName ] [ perf_class=perfClassName ]

Parameters:

Name Type Description Mandatory Default

host Object name The host name. N All hosts.

perf_class Object name Name of a

Performance Class

This command lists all the hosts that have been defined in the XIV system.

N no filter.

A host name can be specified to list only a specific host or all the hosts.

The list contains the following comma separated information:

v Port addresses

v Containing cluster, if one exists

v Associated users and user groups

Example:

host_list host=mailserver

Output:

Name Type FC Ports iSCSI Ports User Group Cluster

-------- --------- ---------- ------------- ------------ --------­host_4 default iscsi_4
host_5 default iscsi_5
host_6 default iscsi_6
host_7 default iscsi_7
host_8 default iscsi_8
host_9 default iscsi_9

Id Name Default Position

name Name 1

type Type 2

fc_ports FC Ports 3

iscsi_ports iSCSI Ports 4

creator Creator N/A

user_group User Group 5

14 IBM XIV Storage System User Manual

Listing Ports

Id Name Default Position

cluster Cluster 6

perf_class Performance Class 7

iSCSI CHAP Name N/A

iscsi_chap_
name

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Lists all the ports of a host

host_list_ports host=HostName

Parameters:

Name Type Description Mandatory

host Object name The host name. Y

This command lists all the ports on a specified host.

Example:

host_list_ports host=tlib_host_pro125_fc0

Output:

Host Type Port name

-------- --------- --------­tlib_host_pro125_fc0 FC 100000062B125CD0

Id Name Default Position

host Host 1

type Type 2

port_name Port Name 3

Access Control:

User Category Permission

Storage administrator Allowed

Chapter 2. Host and Cluster Management

15

User Category Permission

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Removing a Port from a Host

Removes a port from a host.

host_remove_port host=HostName < fcaddress=wwpn | iscsi_name=iSCSIName >

Parameters:

Name Type Description Mandatory

host Object name The host name. Y

fcaddress N/A FC address of the port

iscsi_name iSCSI initiator name iSCSI initiator name of

to be removed.

N

N
the port to be removed.

This command removes a port from a host.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v PORT_DOES_NOT_BELONG_TO_HOST

Port ID belongs to another host

v HOST_PORT_DOES_NOT_EXIST

Port ID is not defined

v ISCSI_HOST_ILLEGAL_PORT_NAME

Port name for iSCSI Host is illegal

Troubleshooting: Port names for iSCSI Hosts must contain only printable
characters.

v OLVM_LINK_IS_NOT_UP

IBM Hyper-Scale Mobility link is not up. The mapping list cannot be updated.

v TARGET_PORT_BAD_ADDRESS

16 IBM XIV Storage System User Manual

v HOST_PORT_EXISTS

v MAX_PORTS_REACHED

v PORT_EXISTS

v REMOTE_MAX_VIRTUAL_HOSTS_REACHED

Renaming a Host

Renames a host.

Parameters:

Name Type Description Mandatory

host Object name The original host name. Y

new_name Object name The new host name.

Remote port address is illegal or does not belong to the remote target

Host with this port ID already defined

Maximum number of ports already defined in the system

Port is already defined

Maximum number of remote virtual hosts already defined

host_rename host=HostName new_name=Name

Y
The new host name
must be unique in the
system.

This command renames a host. The new name of the host must be unique in the
system.

The command still succeeds even if the new name is identical to the current name.

Example:

host_rename host=server2 new_name=mailserver

Output:

Command completed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Chapter 2. Host and Cluster Management

17

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v HOST_NAME_EXISTS

Host name already exists

Updating a Host Definition

Updates a host definition.

host_update host=HostName [ iscsi_chap_name=iscsiChapName ] [ iscsi_chap_secret=iscaiPass ]

Parameters:

Name Type Description Mandatory Default

host Object name Name that

iscsi_
chap_name

iscsi_
chap_
secret

represents the host
to XIV

String The host's CHAP

name identifier

String Password of

initiator used to
authenticate to XIV
when CHAP is
enabled

Y N/A

N [unchanged]

N [unchanged]

This command updates the host definition. The command carries out the following
CHAP-related checks:

v The parameters iscsi_chap_name and iscsi_chap_secret must either be both

specified - or both left unspecified.These parameters have to be unique. In case
they are not, an error message is presented to the user, but the command won't
fail.

v The Secret needs to be between 96 bits and 128 bits. There are 3 ways to enter

the secret:

– Base64: requires to prefix the entry with 0b. each subsequent character

entered is treated as a 6 bit equivalent length

– Hex: requires to prefix the entry with 0x. each subsequent character entered is

treated as a 4 bit equivalent length

– String: requires no prefix (cannot be prefixed with 0b or 0x). Each character

entered is treated as a 8 bit equivalent length

v If the iscsi_chap_secret does not conform to the required secret length (96-128

bits)- the command will fail.

Changing the chap_name and/or chap_secret:

v A warning message will be presented stating that the changes will apply only on

the next time the host is connected.

Example:

host_update host iscsi_chap_name iscsi_chap_secret

18 IBM XIV Storage System User Manual

Output:

Command executed successfully.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ISCSI_CHAP_NAME_AND_SECRET_NOT_UNIQUE

Both iSCSI CHAP name and secret are already used by another host. Are you
sure you want to reuse those values?

v ISCSI_CHAP_SECRET_NOT_UNIQUE

iSCSI CHAP secret is already used by another host. Are you sure you want to
reuse this value?

v ISCSI_CHAP_NAME_NOT_UNIQUE

iSCSI CHAP name is already used by another host. Are you sure you want to
reuse this value?

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v ISCSI_CHAP_NAME_EMPTY

CHAP name should be a non-empty string

v ISCSI_CHAP_NAME_TOO_LONG

CHAP name is too long

v ISCSI_CHAP_SECRET_EMPTY

CHAP secret should be a non-empty string

v ISCSI_CHAP_SECRET_BAD_SIZE

CHAP secret should be 12 to 16 bytes long

v ISCSI_CHAP_SECRET_BAD_HEX_FORMAT

CHAP secret is an illegal hexadecimal number or wrong size - should be 24 to
32 hexadecimal digits

Mapping a Volume to a Host or Cluster

Maps a volume to a host or a cluster.

map_vol <host=HostName | cluster=ClusterName> vol=VolName
lun=LUN [ override=<no|yes> ]

Chapter 2. Host and Cluster Management

19

Parameters:

Name Type Description Mandatory Default

host Object name Host name. N N/A

cluster Object name Cluster name. N N/A

vol Object name Volume name. Y N/A

lun Integer LUN identifier. Y N/A

override Boolean Override existing

mapping.

This command maps a volume to a host or to a cluster. It maps the volume to all
the hosts that are contained in the cluster.

The command fails if:

v The host specified is contained in a cluster (must be done through the cluster)

v Another volume is mapped to the same LUN for this cluster/host, and the

override parameter is not specified.
– If the override parameter is specified, the mapping is replaced, so the host

(or all hosts in the cluster) see continuous mapping of volume to this LUN,
only that the content is changing (and maybe size).

v Mapping to a cluster, if the LUN was defined as an exception.

– Whenever the LUN is defined as an exception, you have to map it directly to

the host.

Nno

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed This volume is a snapshot. The

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

master volume of this snapshot
is mapped to a host or cluster
that is associated with the user
executing this command. This
snapshot was created by an
application administrator.

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_PERFORM_HOST_SPECIFIC_MAPPING

'Host' is part of a cluster. Are you sure you want to map this volume only for
that specific host?

v ARE_YOU_SURE_YOU_WANT_TO_MAP_VOLUME

Are you sure you want to map volume Volume, which is already mapped to
another host/cluster?

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

20 IBM XIV Storage System User Manual

v HOST_BELONGS_TO_CLUSTER

Host is part of a cluster

v CLUSTER_BAD_NAME

Cluster name does not exist

v VOLUME_BAD_NAME

Volume name does not exist

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v VOLUME_ALREADY_ASSIGNED

Mapping conflict: volume is already assigned

v LUN_ALREADY_IN_USE

Mapping conflict: LUN is already in use

v EXT_LUN_ILLEGAL

LUN is out of range or does not exist

v VOLUME_HAS_HOST_SPECIFIC_MAPPING

Specified Volume is currently mapped to another LUN in a host-specific
mapping

v LUN_HAS_HOST_SPECIFIC_MAPPING

Specified LUN currently has another volume mapped in a host-specific mapping

v VOLUME_IS_NON_PROXY_OLVM_DESTINATION

The volume is in an IBM Hyper-Scale Mobility migration state.

v ISCSI_HOST_ILLEGAL_PORT_NAME

Port name for iSCSI Host is illegal

Troubleshooting: Port names for iSCSI Hosts must contain only printable
characters.

v MAX_PORTS_REACHED

Maximum number of ports already defined in the system

v OLVM_LINK_IS_NOT_UP

IBM Hyper-Scale Mobility link is not up. The mapping list cannot be updated.

v HOST_PORT_EXISTS

Host with this port ID already defined

v REMOTE_MAX_VIRTUAL_HOSTS_REACHED

Maximum number of remote virtual hosts already defined

Listing the Mapping of Volumes to Hosts or Clusters

Lists the mapping of volumes to a specified host or cluster.

mapping_list [ host=HostName | cluster=ClusterName ]

Parameters:

Name Type Description Mandatory

host Object name Host name. N

cluster Object name Cluster name. N

Chapter 2. Host and Cluster Management

21

Id Name Default Position

lun LUN 1

volume Volume 2

proxy Proxy 3

size Size 4

master Master 5

serial Serial Number 6

locked Locked 7

host Host 8

Example:

e mapping_list host=tlib_host_lsihost034_fc10000006072d0190

Output:

LUN Volume Size Master Serial Locked

----- -------------------------------- ------ ----------------- ------- -------­0 vol-870834-0003 137 3 no
1 vol-870834-0004 137 4 no
2 vol-870834-0005 137 5 no
3 vol-870834-0006 137 6 no
4 vol-870834-0007 34 7 yes
5 vol-870834-0008 34 8 no
6 vol-870834-0010 34 10 no
7 vol-870834-0009 34 9 no
8 vol-870834-0011 34 11 no
9 vol-870837-0004 17 12 no
10 vol-870837-0006 17 13 no
11 vol-870837-0006.snapshot_00004 17 vol-870837-0006 19 yes
12 vol-870837-0022 17 27 no
13 vol-870837-0024 17 28 no
14 vol-870837-0027 68 31 no
15 vol-870837-0028 86 32 no
16 vol-870834-0007.snapshot_00001 34 vol-870834-0007 33 yes

Number

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v CLUSTER_BAD_NAME

Cluster name does not exist

v TOO_MANY_MAPPINGS

There are too many mappings to display

22 IBM XIV Storage System User Manual

Setting the Special Type of Hosts or Clusters

Sets the special type of a host or a cluster.

special_type_set <host=HostName | cluster=ClusterName> type=<default|hpux|zvm|esx>

Parameters:

Name Type Description Mandatory

host Object name Host name. N

cluster Object name Cluster name. N

type Enumeration Special map type. Y

This command sets a special type for a host or a cluster. The supported special
types are HPUX and ZVM. It should be specified for hosts or clusters that run the
HP/UX operating system. All other operating systems do not require a special
type.

Example:

special_type_set host=tlib_host_pro26_fc0 type=zvm

Output:

Command executed successfully.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v HOST_BELONGS_TO_CLUSTER

Host is part of a cluster

v CLUSTER_BAD_NAME

Cluster name does not exist

Listing Hosts/Cluster to which a Volume is Mapped

Lists all hosts and clusters to which a volume is mapped.

vol_mapping_list vol=VolName

Chapter 2. Host and Cluster Management

23

Parameters:

Name Type Description Mandatory

vol Object name Volume name. Y

This command lists all the hosts and clusters to which a volume is mapped, as
well as hosts that are part of a cluster and have host-specific mapping to the
volume. The output list contains two columns: name of host/cluster and type (host
or cluster).

Id Name Default Position

host Host/Cluster 1

type Type 2

lun LUN 3

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

Unmapping a Volume from a Host or Cluster

Unmaps a volume from a host or a cluster.

unmap_vol <host=HostName | cluster=ClusterName> vol=VolName; [ idle_seconds=IdleSeconds ]

Parameters:

Name Type Description Mandatory Default

host Object name Host name. N N/A

cluster Object name Cluster name. N N/A

vol Object name Volume name. Y N/A

Integer How many

idle_
seconds

This command unmaps a volume from a host or a cluster.

seconds the
volume needs to
be idle before
unmapping

N-1

The command to unmap from a cluster will unmap the volume from all the hosts
that are contained in that cluster.

24 IBM XIV Storage System User Manual