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
The command fails if the specified host is contained in a cluster. In this case, the unmapping of the host must be performed through the cluster.
The command does not fail when the volume is not mapped to the host/cluster.
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed The volume is a snapshot, where
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.
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
v VOLUME_BAD_NAME
Volume name does not exist
v SNAPSHOT_IS_INTERNAL
Internal snapshots cannot be mapped, modified or deleted.
v VOLUME_IS_NON_PROXY_OLVM_DESTINATION
The volume is in an IBM Hyper-Scale Mobility migration state.
v OLVM_LINK_IS_NOT_UP
IBM Hyper-Scale Mobility link is not up. The mapping list cannot be updated.
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 HOST_PORT_EXISTS
Host with this port ID already defined
v MAPPING_IS_NOT_DEFINED
The requested mapping is not defined
v REMOTE_MAX_VIRTUAL_HOSTS_REACHED
Maximum number of remote virtual hosts already defined
Chapter 2. Host and Cluster Management 25
Set the Default Idle Time for Unmapping a Volume
Sets the default idle time required for a volume before unmapping it
unmap_vol_set_default_idle_time idle_time_seconds=IdleSeconds
Parameters:
Name Type Description Mandatory
Integer How many seconds the
idle_time_ seconds
This command sets the default idle time required for unmapping a volume.
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Disallowed N/A
Application administrator Conditionally Allowed The volume is a snapshot, where
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
volume needs to be idle before unmapping
Y
its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.
Creating a Performance Class
Creates a Performance Class
perf_class_create perf_class=perfClassName
Parameters:
Name Type Description Mandatory
perf_class String Name of a Performance
This command creates a Performance Class. The Performance Class name must be unique. Up to 4 classes can be created.
Example:
perf_class_create perf_class=p1
Class
Y
26 IBM XIV Storage System User Manual
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 PERF_CLASS_EXISTS
Performance Class already exists.
v MAX_PERF_CLASSES_REACHED
Maximum number of Performance Class is already defined.
Deleting a Performance Class
Deletes a Performance Class
perf_class_delete perf_class=perfClassName
Parameters:
Name Type Description Mandatory
perf_class Object name Name of a Performance
Class
Y
This command deletes a Performance Class.
Example:
perf_class_delete perf_class=p1
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_A_PERF_CLASS
Are you sure you want to delete Performance Class Performance Class?
v
Chapter 2. Host and Cluster Management 27
ARE_YOU_SURE_YOU_WANT_TO_DELETE_A_PERF_CLASS_ ASSOCIATED_WITH_ HOSTS
Deleting Performance Class Performance Class will remove the performance limits set for hosts associated with the Performance Class. Are you sure you want to delete Performance Class Performance Class?
Completion Codes:
v PERF_CLASS_BAD_NAME
Performance Class does not exist
Renaming a Performance Class
Renames a Performance Class
perf_class_rename perf_class=perfClassName
new_name=Name
Parameters:
Name Type Description Mandatory
perf_class Object name Existing name of a
Performance Class
new_name String New name for the
Performance Class. Class new name must be unique.
Y
Y
This command renames a Performance Class.
Example:
perf_class_rename perf_class=p1 new_name=perf1
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 PERF_CLASS_EXISTS
Performance Class already exists.
v PERF_CLASS_BAD_NAME
Performance Class does not exist
28 IBM XIV Storage System User Manual
Listing Details on Performance Classes
Lists Performance Classes
perf_class_list [ perf_class=perfClassName ]
Parameters:
Name Type Description Mandatory Default
perf_class String Name of a
Performance Class. If left unspecified ­all performance classes will be listed.
This command lists details of a specified Performance Class, or all Performance Classes.
Id Name Default Position
name Performance class 1
max_iops Max IO rate(IOPOS) 2
max_bw Max BW rate(MB/s) 3
hosts Hosts 4
N All Performance
classes.
Example:
perf_class_list
Access Control:
User Category Permission
Storage administrator Allowed
Storage integration administrator Allowed
Application administrator Disallowed
Security administrator Disallowed
Read-only users Allowed
Technicians Disallowed
Adding a Host to a Performance Class
Adds a host to a Performance Class
perf_class_add_host perf_class=perfClassName host=HostName
Parameters:
Name Type Description Mandatory
perf_class Object name Name of a Performance
Class
Y
Chapter 2. Host and Cluster Management
29
Name Type Description Mandatory
host Object name Name of a host that will
be added to the performance class
Y
This command adds a host to a Performance Class. If the host is already associated to another performance class, it is removed from it.
Example:
perf_class_add_host perf_class=p1 host=h1
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 PERF_CLASS_BAD_NAME
Performance Class does not exist
v HOST_BAD_NAME
Host name does not exist
Removing a Host from its Performance Class
Removes a host from its Performance Class
perf_class_remove_host host=HostName
Parameters:
Name Type Description Mandatory
host Object name Name of a host that will
be removed from its Performance Class
This command removes a host from its Performance Class.
Example:
Y
perf_class_remove_host host=h1
30 IBM XIV Storage System User Manual
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 PERF_CLASS_DOES_NOT_CONTAIN_ANY_HOSTS
Performance Class is already empty
Setting the Rate for a Performance Class
Sets the rate for a Performance Class
perf_class_set_rate perf_class=perfClassName [ max_io_rate=iops ] [ max_bw_rate=bw ]
Parameters:
Name Type Description Mandatory Default
perf_class Object name Name of a
Positive integer Specifies the
max_io_ rate
Positive integer Specifies the
max_bw_ rate
Performance Class
Performance Class maximum rate in IOPS per interface (IOPS). The max setting allowed is 100,000. If zero is specified, the IOPS rate will not be limited.
Performance Class maximum rate in bandwidth per interface (Mbps). The max setting allowed is 10,000. If zero is specified, the bandwidth rate will not be limited.
This command sets the rate for a Performance Class. The specified rate is applied for each interface module. Either max_io_rate, max_bw_rate or both attributes must be set.
Y N/A
N Keep unchanged.
N Keep unchanged.
Example:
Chapter 2. Host and Cluster Management 31
perf_class_set_rate perf_class=p1 max_io_rate=1000
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 PERF_CLASS_BAD_NAME
Performance Class does not exist
v PERF_CLASS_INVALID_RATE
The rate set for the Performance Class is invalid
Listing Host Profiles
lists all host profiles
host_profile_list [ host=HostName ]
Parameters:
Name Type Description Mandatory Default
host Object name Name of a specific
Host to list its profile
Lists all Host Profiles or a specific one.
Id Name Default Position
host_name Host Name 1
update_time Update Time 2
profile Profile 3
Example:
xcli -u -c XIV1 host_profile_list host
Output:
N >All Host Profiles.
Host Name Update Time Profile
---------------------------- --------------------- ----------------------­host1 2012-05-09 22:54:36 Windows 7
32 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 Allowed
Updates the Host Profile
updates the host profile
host_profile_set profile_value=Profile
Parameters:
Name Type Description Mandatory
profile_ value
String The host profile value
length up to 1024 characters
Y
updates the host profile
Example:
xcli -u -c XIV1 host_profile_set profile_value
Access Control:
User Category Permission
Storage administrator Disallowed
Storage integration administrator Disallowed
Application administrator Disallowed
Security administrator Disallowed
Read-only users Disallowed
Technicians Disallowed
Completion Codes:
v HOST_PROFILE_UPDATE_TOO_FREQUENT
Host Profile has been set too often.
Troubleshooting: Try again after the minimal update interval time
v HOST_BAD_NAME
Host name does not exist
v MAX_HOST_PROFILES_REACHED
Maximum number of host profiles already defined
v HOST_PROFILER_DISABLED
Host profiler disabled
Chapter 2. Host and Cluster Management 33
Removes the Profile of the Specified Host
removes the profile of the specified host
host_profile_clear host=HostName
Parameters:
Name Type Description Mandatory
host Object name The host name. Y
removes the profile of the specified host
Example:
xcli -u -c XIV1 host_profile_clear host
Access Control:
User Category Permission
Storage administrator Allowed
Storage integration administrator Allowed
Application administrator Allowed
Security administrator Disallowed
Read-only users Disallowed
Technicians Allowed
Completion Codes:
v HOST_BAD_NAME
Host name does not exist
v HOST_PROFILE_DOES_NOT_EXIST
No profile defined for the requested host
Enable Host Profiler Functionality
Enable host profiler functionality
host_profiler_enable
Enable host profiler functionality
Example:
xcli -u -c XIV1 host_profiler_enable
Access Control:
User Category Permission
Storage administrator Allowed
Storage integration administrator Allowed
34 IBM XIV Storage System User Manual
User Category Permission
Application administrator Allowed
Security administrator Disallowed
Read-only users Disallowed
Technicians Disallowed
Disable Host Profiler Functionality
Disable host profiler functionality
host_profiler_disable
Disable host profiler functionality
Example:
xcli -u -c XIV1 host_profiler_disable
Access Control:
User Category Permission
Storage administrator Allowed
Storage integration administrator Allowed
Application administrator Allowed
Security administrator Disallowed
Read-only users Disallowed
Technicians Disallowed
Chapter 2. Host and Cluster Management
35
36 IBM XIV Storage System User Manual
Chapter 3. Volume Management
The following sections describe the XIV Command Line Interface (XCLI) for volume management. Other commands that are relevant to this topic are: Listing Volumes, Renaming a Volume, Moving a Volume between Storage Pools .
See also:
v Volume Snapshot Management
v Consistency Group Management
v Storage Pool Management
The sections are listed as follows:
v reservation_clear(Clears reservations of a volume.)
v reservation_key_list(Lists reservation keys.)
v reservation_list(Lists volume reservations.)
v vol_by_id(Prints the volume name according to its specified SCSI serial number.
)
v vol_copy(Copies a source volume onto a target volume.)
v vol_create(Creates a new volume.)
v vol_delete(Deletes a volume.)
v vol_format(Formats a volume.)
v vol_list(Lists all volumes or a specific one.)
v vol_lock(Locks a volume so that it is read-only.)
v vol_rename(Renames a volume.)
v vol_resize(Resizes a volume.)
v vol_unlock(Unlocks a volume, so that it is no longer read-only and can be
written to.)
The following commands are no longer in use:
v vol_clear_keys (Command is no longer in use in this version. Supplanted by
new command reservation_clear.)
Clearing Reservations of a Volume
Clears reservations of a volume.
reservation_clear vol=VolName
Parameters:
Name Type Description Mandatory
vol Object name Name of the volume to
Clear reservations of a volume.
Example:
clear reservations of.
Y
37
reservation_clear vol=Vol1
Access Control:
User Category Permission
Storage administrator Allowed
Storage integration administrator Allowed
Application administrator Allowed
Security administrator Disallowed
Read-only users Disallowed
Technicians Disallowed
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
Listing Reservation Keys
Lists reservation keys.
reservation_key_list [ vol=VolName ]
Parameters:
Name Type Description Mandatory Default
vol Object name Name of the
volume to list reservation keys.
Lists reservation keys.
Example:
reservation_key_list vol=Vol2
Output:
Initiator Port Volume Name Reservation Key
------------------ ------------------ ----------------­100000062B151C3C vol-dmathies-0a7 2 100000062B151C3C vol-dobratz-23a 3
Id Name Default Position
initiator_port Initiator Port 1
Initiator ISID 2
initiator_ port_isid
vol_name Volume Name 3
reg_key Reservation Key 4
N All volumes.
38 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
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
Listing Volume Reservations
Lists volume reservations.
reservation_list [ vol=VolName ]
Parameters:
Name Type Description Mandatory Default
vol Object name Name of the
volume to list reservations of.
N All volumes.
Lists volume reservations.
Example:
reservation_list vol=Vol1
Output:
Volume Name Reserving Port Reservation Type Persistent vol1 none none
Reservation Type Persistent Access Type Initiator UID PR Generation
Id Name Description Default Position
name Volume Name N/A 1
reserved_by_ port
reserved_by_ port_isid
reservation_ type
none -1 0
Reserving Port N/A 2
Reserving ISID N/A 3
Reservation Type N/A 4
Chapter 3. Volume Management
39
Id Name Description Default Position
Persistent Reservation
persistent_ reservation_ type
access_type Persistent Access Type N/A 6
reserving_ initiator_uid
pr_generation PR Generation N/A 8
reservation_ age
Type
Initiator UID uid of reserving host 7
Reservation Age N/A 9
N/A 5
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
Finding a Volume Based on a SCSI Serial Number
Prints the volume name according to its specified SCSI serial number.
vol_by_id id=n
Parameters:
Name Type Description Mandatory
id Positive integer SCSI volume ID. Y
This command prints the volume name according to its specified SCSI serial number.
Id Name Default Position
name Name 1
size Size (GB) 2
size_MiB Size (MiB) N/A
master_name Master Name 3
cg_name Consistency Group 4
pool_name Pool 5
creator Creator 6
40 IBM XIV Storage System User Manual
Id Name Default Position
proxy Proxy N/A
capacity Capacity (blocks) N/A
modified Modified N/A
sg_name Snapshot Group Name N/A
Deletion Priority N/A
delete_ priority
locked Locked N/A
serial Serial Number N/A
snapshot_time Snapshot Creation Time N/A
Master Copy Creation Time N/A
snapshot_time_ on_master
Snapshot Internal Role N/A
snapshot_ internal_role
snapshot_of Snapshot of N/A
sg_snapshot_of Snapshot of Snap Group N/A
wwn WWN N/A
mirrored Mirrored N/A
locked_by_pool Locked by Pool N/A
used_capacity Used Capacity (GB) 7
Used Capacity (MiB) N/A
used_capacity_ MiB
short_lived_io Short Live IO N/A
enable_VAAI VAAI enabled N/A
VAAI disabled by user N/A
user_disabled_ VAAI
Snapshot Format N/A
snapshot_ format
ssd_caching SSD Caching State N/A
Use SSD Caching Default State N/A
use_ssd_ caching_ default
unmap_support Unmap Support N/A
managed Managed N/A
enable_unmap unmap enabled N/A
unmap disabled by user N/A
user_disabled_ unmap
marked Marked N/A
Example:
vol_by_id id=59
Chapter 3. Volume Management
41
Output:
Name Size (GB) Master Name Consistency Group Pool Creator Used Capacity(GB) volume_1 51 0
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_SERIAL
Copying Volumes
Copies a source volume onto a target volume.
Volume with requested SCSI serial number does not exist
vol_copy vol_src=VolName vol_trg=VolName
Parameters:
Name Type Description Mandatory
vol_src Object name Name of the source
volume from which the data is to be taken.
vol_trg Object name Name of the target
volume to which the data is to be copied.
This command copies a source volume onto a target volume.
All data stored on the target volume is lost and cannot be restored.
This command performs the following as a single atomic action:
v Deletes the target volume.
v Creates a new volume with the same name as the target volume and the same
size as the source volume.
v Instantly copies the source volume data onto the target volume.
All volume-to-host mappings of the target volume remain intact during this process. Except for its size, the target volume retains all of its properties, including its name, ID, lock state, creation time and all other attributes.
Y
Y
Immediately after the completion of the command, the volumes are independent of each other and are valid for any further operations (including deletion).
42 IBM XIV Storage System User Manual
If the target volume is larger then the source volume, excess storage space is freed and returned to the target volume's Storage Pool. If the target volume is smaller than the source volume, all storage space that is needed to support the additional volume's capacity is reserved from the Storage Pool.
The command fails in the following cases:
v The target is not formatted.
v The source volume is larger than the target volume, and there is not enough free
space in the Storage Pool that contains the target for target volume resizing.
v The target volume has a snapshot associated with it or if the target volume is a
snapshot.
v The target volume is locked.
v The target volume is part of any mirroring definitions (either master or slave).
v The source volume is a slave of a synchronous mirroring, and it is currently
inconsistent due to either a re-synchronization or an initialization process.
v There is not enough free space in the Storage Pool that contains the target
In the following example, the -y option suppresses the "ARE_YOU_SURE_YOU_WANT_TO_COPY_VOLUME Y/N" prompt.
The volume can't be copied if it is part of an IBM Hyper-Scale Mobility relation and in Proxy phase.
Example:
vol_copy vol_src=DBVolume vol_trg=DBVolumeCopy
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 ARE_YOU_SURE_YOU_WANT_TO_COPY_VOLUME
Are you sure you want to copy the contents of volume source Volume to volume target Volume?
Completion Codes:
v NOT_ENOUGH_HARD_SPACE
No space to allocate for volume's current usage
v NOT_ENOUGH_SPACE
Chapter 3. Volume Management 43
No space to allocate volume
v SOURCE_VOLUME_BAD_NAME
Source volume name does not exist
v SOURCE_VOLUME_DATA_MIGRATION_UNSYNCHRONIZED
Data Migration has not completed to source volume
v TARGET_VOLUME_BAD_NAME
Target volume name does not exist
v TARGET_VOLUME_LOCKED
Target volume is locked
v TARGET_VOLUME_HAS_MIRROR
Mirror is defined for target volume
v TARGET_VOLUME_HAS_DATA_MIGRATION
Data Migration is defined for target volume
v VOLUME_IS_SNAPSHOT
Operation is not permitted on snapshots
v VOLUME_IDENTICAL
Source and target are the same volume
v VOLUME_HAS_SNAPSHOTS
Volume has snapshots
v VOLUME_IS_NOT_CONSISTENT_SLAVE
Operation not allowed on slave volume that is not consistent.
v TARGET_VOLUME_NOT_FORMATTED
Target volume is not formatted
v SNAPSHOT_IS_FORMATTED
Snapshot is formatted
v VOLUME_TOO_BIG_TO_COPY
Volume is too large to be copied
v TARGET_VOLUME_HAS_OLVM
This target volume is part of an IBM Hyper-Scale Mobility relation.
v VOLUME_IS_OLVM_PROXY
The volume is in an IBM Hyper-Scale Mobility Proxy phase.
Creating a Volume
Creates a new volume.
vol_create vol=VolName < size=GB | size_blocks=BLOCKS > pool=PoolName
Parameters:
Name Type Description Mandatory
vol Object name Volume name. Y
size Positive integer Volume size in GB. N
size_ blocks
44 IBM XIV Storage System User Manual
Positive integer Size in number of
blocks.
N
Name Type Description Mandatory
pool Object name The name of the Storage
Pool to which the volume belongs.
Y
This command creates a new volume.
The name of the volume must be unique in the system.
Space for the volume is allocated from the specified Storage Pool and the volume belongs to that Storage Pool. Specifying the Storage Pool is mandatory.
When creating a volume, the storage space that is needed to support the volume's capacity is reserved from the soft capacity of the storage Pool for the volume.
The command fails if the reservation cannot be committed.
The volume is logically formatted at creation time, which means that any read operation results in returning all zeros as a response.
The size is the actual "net" storage space, as seen by the user's applications, not including any mirroring or other data protection overhead.
The free space consumed by the volume will be the smallest multiple of 17GB which is bigger than the specified size.
The size can be specified either in gigabytes or in blocks (where each block is 512 bytes). If the size is specified in blocks, volumes are created in the exact size specified. If the size is specified in gigabytes, the actual volume size is rounded up to the nearest 17GB multiple (making the actual size identical to the free space consumed by the volume, as described above). This rounding up prevents a situation where storage space is not fully utilized because of a gap between the free space used and the space available to the application. The size specified in blocks is exact.
9
The term GB (gigabytes) is defined in this context as 10
(and not as 230as in many
other contexts).
Upon successful completion of the command, its lock state is unlocked, meaning that write, format and resize operations are allowed.
The creation time of the volume is set to the current time and is never changed.
Example:
vol_create vol=DBVolume size=2000 pool=DBPool
Output:
Command executed successfully.
Chapter 3. Volume Management
45
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 VOLUME_CANNOT_HAVE_ZERO_SIZE
Volume size cannot be zero
v POOL_DOES_NOT_EXIST
Storage Pool does not exist
v VOLUME_EXISTS
Volume name already exists
v VOLUME_BAD_PREFIX
Volume name has a reserved prefix
v NOT_ENOUGH_SPACE
No space to allocate volume
v MAX_VOLUMES_REACHED
Maximum number of volumes already defined
v ELECTRONIC_LICENSE_NOT_APPROVED
Operation blocked until Electronic license approval
Troubleshooting: Please retrieve Electronic license version and accept it
v VOLUME_SIZE_ABOVE_LIMIT
Volume size specified is above limit
v INVALID_SLICE_OFFSET
Slice number out of range
v ENCRYPTION_IN_PROGRESS
System is in the process of changing encryption activation state
Deleting a Volume
Deletes a volume.
vol_delete vol=VolName
Parameters:
Name Type Description Mandatory
vol Object name Name of the volume to
This command deletes a volume. All data stored on the volume is lost and cannot be restored.
46 IBM XIV Storage System User Manual
delete.
Y
This command cannot be applied to a snapshot. To delete a snapshot, use Deleting a Snapshot.
All storage space allocated (or reserved) for the volume is freed and returned to the volume's Storage Pool.
The volume is removed from all LUN Maps that contain a mapping of the volume.
This command deletes all snapshots associated with this volume. Even snapshots that are part of a Snapshot Group (this can happen when the volume was in a Consistency Group and was removed from it prior to the deletion).
This command cannot be applied to a volume that is part of a Consistency Group or to a volume that is mapped to a host or cluster.
The command succeeds regardless of the volume's lock state.
Example:
vol_delete vol=DBVolumeCopy
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
Warnings:
v ARE_YOU_SURE_YOU_WANT_TO_DELETE_VOLUME
Are you sure you want to delete volume Volume?
v ARE_YOU_SURE_YOU_WANT_TO_DELETE_VOLUME_WITH_SNAPSHOTS
Volume Volume has snapshots! Are you sure you want to delete this volume AND all its snapshots?
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v VOLUME_HAS_MIRROR
Mirror is defined for this volume
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
v SNAPSHOT_IS_INTERNAL
Chapter 3. Volume Management 47
Internal snapshots cannot be mapped, modified or deleted.
v VOLUME_BELONGS_TO_CG
Volume belongs to a Consistency Group
v VOLUME_IS_MAPPED
Volume that is mapped to a host cannot be deleted
v VOLUME_HAS_MAPPED_SNAPSHOT
Volume which has a snapshot that is mapped to a host cannot be deleted
v SNAPSHOT_HAS_ACTIVE_SYNC_JOB
Snapshot is currently a target of an active sync job
Troubleshooting: Please wait for sync job to complete
v SNAPSHOT_IS_CONSISTENT_ELCS
If a mirrored volume is not consistent then its ELCS is protected and cannot be deleted.
v VOLUME_HAS_OLVM
IBM Hyper-Scale Mobility relation is defined for this volume
v VOLUME_IS_OLVM_PROXY
The volume is in an IBM Hyper-Scale Mobility Proxy phase.
Formatting a Volume
Formats a volume.
vol_format vol=VolName
Parameters:
Name Type Description Mandatory
vol Object name Name of the volume to
be formatted.
This command formats a volume. A formatted volume returns zeros as a response to any read command.
All data stored on the volume is lost and cannot be restored.
The formatting of the volume is done logically and no data is actually written to the physical storage space allocated for the volume. This allows the command to complete instantly.
The volume's lock state must be unlocked when the command is issued.
This command fails if the volume has snapshots associated with it, or if the volume is a snapshot, or if the volume is part of any mirroring or Data Migration definition.
Y
Example:
vol_format vol=DBVolume
Output:
48 IBM XIV Storage System User Manual
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 ARE_YOU_SURE_YOU_WANT_TO_FORMAT_VOLUME
Volume Volume may contain data. Formatting will cause data loss. Are you sure you want to format volume Volume?
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v VOLUME_HAS_SNAPSHOTS
Volume has snapshots
v VOLUME_IS_SNAPSHOT
Operation is not permitted on snapshots
v VOLUME_LOCKED
Volume is locked
v VOLUME_HAS_MIRROR
Mirror is defined for this volume
v VOLUME_HAS_DATA_MIGRATION
Data Migration is defined for this volume
Listing Volumes
Lists all volumes or a specific one.
vol_list [ vol=VolName | pool=PoolName | cg=cgName ] [ show_proxy=<yes|no> ]
Parameters:
Name Type Description Mandatory Default
vol Object name Name of a specific
pool Object name Name of a specific
volume to be listed.
Pool whose volumes are to be listed.
N All volumes.
N Volumes in all
Pools.
Chapter 3. Volume Management
49
Name Type Description Mandatory Default
cg Object name List all the
volumes in this Consistency Group.
show_proxy Boolean Returns data on
proxy volumes (volumes in Proxy State) as well
N All Consistency
Groups.
NNo
This command lists volumes according to:
v Volume name
v Pool
v Consistency Group
If no parameter is indicated, the command lists all available volumes. In addition, the command indicates whether the volume is mirrored.
This command displays the following VAAI fields (available on the XML output format):
v enable_VAAI
v user_disabled_VAAI
This command displays the following snapshot format field (available on the XML output format):
v snapshot_format
Id Name Default Position
name Name 1
size Size (GB) 2
size_MiB Size (MiB) N/A
master_name Master Name 3
cg_name Consistency Group 4
pool_name Pool 5
creator Creator 6
proxy Proxy N/A
capacity Capacity (blocks) N/A
modified Modified N/A
sg_name Snapshot Group Name N/A
Deletion Priority N/A
delete_ priority
locked Locked N/A
serial Serial Number N/A
snapshot_time Snapshot Creation Time N/A
Master Copy Creation Time N/A
snapshot_time_ on_master
Snapshot Internal Role N/A
snapshot_ internal_role
snapshot_of Snapshot of N/A
50 IBM XIV Storage System User Manual
Id Name Default Position
sg_snapshot_of Snapshot of Snap Group N/A
wwn WWN N/A
mirrored Mirrored N/A
locked_by_pool Locked by Pool N/A
used_capacity Used Capacity (GB) 7
Used Capacity (MiB) N/A
used_capacity_ MiB
short_lived_io Short Live IO N/A
enable_VAAI VAAI enabled N/A
VAAI disabled by user N/A
user_disabled_ VAAI
Snapshot Format N/A
snapshot_ format
ssd_caching SSD Caching State N/A
Use SSD Caching Default State N/A
use_ssd_ caching_ default
unmap_support Unmap Support N/A
managed Managed N/A
enable_unmap unmap enabled N/A
unmap disabled by user N/A
user_disabled_ unmap
marked Marked N/A
Example:
vol_list
Output:
Name Size (GB) Master Name Pool Creator Used Capacity (GB) DBLog 3006 MainPool admin 0 Dev 2010 MainPool admin 0 Marketing 1013 MainPool admin 0 Dev.snapshot_00001 2010 Dev MainPool admin Dev.snapshot_00002 2010 Dev MainPool admin Dev.snapshot_00003 2010 Dev MainPool admin
Access Control:
User Category Permission
Storage administrator Allowed
Storage integration administrator Allowed
Application administrator Allowed
Security administrator Allowed
Read-only users Allowed
Chapter 3. Volume Management
51
User Category Permission
Technicians Disallowed
Locking a Volume
Locks a volume so that it is read-only.
vol_lock vol=VolName
Parameters:
Name Type Description Mandatory
vol Object name Name of the volume to
This command locks a volume so that hosts cannot write to it.
A volume that is locked is write-protected, so that hosts can read the data stored on it, but cannot change it. In addition, a locked volume cannot be formatted or resized. In general, locking a volume prevents any operation (other than deletion) that changes the volume's image.
This command succeeds when the volume's lock state is already set to the one the user is trying to apply, while leaving it in the same lock state.
lock.
Y
The lock states of master volumes are set to unlocked when they are created.
The lock states of snapshots are set to locked when they are created.
In addition to the lock state, snapshots also have a modification state. The modification state is a read-only state (which cannot be changed by the user explicitly) and it is initially set to unmodified when the snapshot is created. The first time a snapshot lock state is set to unlocked, the modification state of the snapshot is changed to modified, and it is never changed thereafter.
If applied on a volume that is part of an IBM Hyper-Scale Mobility relation, the command has to be acknowledged by both source and destination volumes. Otherwise, a completion code is returned (see below).
Example:
vol_lock vol=DBVolume
Output:
Command executed successfully.
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
52 IBM XIV Storage System User Manual
User Category Permission Condition
Application administrator Conditionally Allowed The volume is a snapshot, where
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
Completion Codes:
v SNAPSHOT_IS_INTERNAL
Internal snapshots cannot be mapped, modified or deleted.
v VOLUME_BAD_NAME
Volume name does not exist
v VOLUME_IS_SLAVE
Volume is defined as a slave volume
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
Renaming a Volume
its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.
Renames a volume.
vol_rename vol=VolName new_name=Name
Parameters:
Name Type Description Mandatory
vol Object name Name of the volume to
be renamed.
new_name Object name New volume name. Y
This command renames a volume.
The new name of the volume must be unique in the system.
This command succeeds even if the new name is identical to the current name.
This command succeeds regardless of the volume's lock state.
Renaming a snapshot does not change the name of its master volume. Renaming a master volume does not change the names of its associated snapshots.
If applied on a volume that is part of an IBM Hyper-Scale Mobility relation, the command has to be acknowledged by both source and destination volumes. Otherwise, a completion code is returned (see below).
Y
Example:
Chapter 3. Volume Management 53
vol_rename vol=DBVolume new_name=DBVolume1
Output:
Command completed successfully
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed The volume is a snapshot, where
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v VOLUME_EXISTS
Volume name already exists
v SNAPSHOT_IS_INTERNAL
Internal snapshots cannot be mapped, modified or deleted.
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
v VOLUME_BAD_PREFIX
Volume name has a reserved prefix
v SNAPSHOT_IS_CONSISTENT_ELCS
If a mirrored volume is not consistent then its ELCS is protected and cannot be deleted.
v OLVM_ERROR
IBM Hyper-Scale Mobility error.
v COMMAND_NOT_SUPPORTED_FOR_OLVM_VOLUMES
This command is not supported for IBM Hyper-Scale Mobility volumes.
Resizing a Volume
Resizes a volume.
vol_resize vol=VolName < size=GB | size_blocks=BLOCKS > [ shrink_volume=<yes|no> ] [ force_on_inactive_mirror=<yes|no> ]
54 IBM XIV Storage System User Manual
Parameters:
Name Type Description Mandatory Default
vol Object name The name of the
size N/A The new volume
N/A New size of
size_ blocks
Boolean Must be specified
shrink_ volume
Boolean The parameter is
force_on_ inactive_ mirror
volume to be resized.
size.
volumes in number of blocks.
as yes if the new size is smaller than the current size.
required for a successful resize of a volume if (1) the volume is mirrored, (2) the volume is a Master, and (3) the mirror has been deactivated by the system following a previously issued resize command that failed to successfully complete due to a communication error.
Y N/A
N N/A
N N/A
NNo
NNo
This command resizes a volume.
The volume can be resized in either direction. However, whenever the volume is downsized, you have to specify this with shrink_volume="yes".
9
The new size of the volume is specified as an integer multiple of 10 actual new size of the volume is rounded up to the nearest valid size, which is an integer multiple of 16 x 2
30
bytes.
bytes, but the
If the new size equals the current size, the command will succeed without changes to the volume.
The volume's address space is extended at its end to reflect the increased size, and the additional capacity is logically formatted (that is, zeros are returned for all read commands).
When resizing a regular volume (not a writable snapshot), all storage space that is needed to support the additional volume's capacity is reserved (static allocation). This guarantees the functionality and integrity of the volume, regardless of the resource levels of the volume's Storage Pool. The command fails if this reservation cannot be committed.
The volume's lock state must be unlocked when the command is issued, or otherwise the command fails.
v Resizing a master volume does not change the size of its associated snapshots.
Chapter 3. Volume Management 55
v These snapshots can still be used to restore their individual master volumes.
v The same goes for resizing a snapshot: it does not change the size of its master
volume.
If applied on a volume that is part of an IBM Hyper-Scale Mobility relation, the command has to be acknowledged by both source and destination volumes. Otherwise, a completion code is returned (see below).
In the following example, the -y option suppresses the "ARE_YOU_SURE_YOU_WANT_TO_ENLARGE_VOLUME Y/N" prompt.
force_on_inactive_mirror
v This parameter enables to force the resizing of a mirror peer even if mirroring is
inactive (this could happen when the mirroring cannot be activated due to size mismatch).
Example:
vol_resize -y vol=DBVolume size=2500
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 ARE_YOU_SURE_YOU_WANT_TO_ENLARGE_VOLUME
Are you sure you want to increase volume size?
v ARE_YOU_SURE_YOU_WANT_TO_REDUCE_VOLUME
Decreasing volume size may cause data loss. Are you sure you want to proceed?
v VOLUME_WILL_CROSS_1TB_SIZE
Many operating systems do not support a resize operation across the 1TB boundary, are you sure?
Troubleshooting: Snapshot backup before resize is advised
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v ILLEGAL_VOLUME_SIZE
Illegal volume size
v NOT_ENOUGH_SPACE
56 IBM XIV Storage System User Manual
No space to allocate volume
v REMOTE_VOLUME_SIZE_ABOVE_LIMIT
Volume size specified is above limit of remote machine
v VOLUME_LOCKED
Volume is locked
v VOLUME_HAS_DATA_MIGRATION
Data Migration is defined for this volume
v CAN_NOT_SHRINK_MAPPED_VOLUME
Mapped volume's size cannot be decreased
v CAN_NOT_SHRINK_VOLUME_WITH_SNAPSHOTS
Size of volume with snapshots cannot be decreased
v CAN_NOT_SHRINK_REMOTE_VOLUME_WITH_SNAPSHOTS
Remote volume has snapshots
v CAN_NOT_SHRINK_MAPPED_REMOTE_VOLUME
Remote volume is mapped
v REMOTE_VOLUME_HAS_DATA_MIGRATION
Data Migration is defined for slave volume
v VOLUME_CANNOT_HAVE_ZERO_SIZE
Volume size cannot be zero
v CAN_NOT_SHRINK_SNAPSHOTS
Size of snapshots cannot be decreased
v CAN_NOT_RESIZE_ASYNC_INTERVAL_VOLUMES
Size of volumes with asynchronous mirroring cannot be changed
v CAN_NOT_SHRINK_VOLUME
Size of volumes cannot be decreased without explicit request
v MIRROR_SIZE_MISMATCH
Slave volume and Master Volume sizes are different
v MIRROR_POSSIBLE_SIZE_MISMATCH
Slave volume and Master Volume sizes may be different. This problem occurs whenever the Master does not receive an acknowledgment from the Slave until the command timed out, or any other unexpected failure.
v VOLUME_SIZE_ABOVE_LIMIT
Volume size specified is above limit
v COMMAND_NOT_SUPPORTED_FOR_OLVM_VOLUMES
This command is not supported for IBM Hyper-Scale Mobility volumes.
v MIRROR_IS_NON_OPERATIONAL
Mirror is non-operational
v VOLUME_IS_SLAVE
Volume is defined as a slave volume
v MIRROR_RETRY_OPERATION
There is an operation in progress on this mirror , please retry your request in a few seconds
Troubleshooting: Please retry the command in a few seconds
Chapter 3. Volume Management 57
Unlocking a Volume
Unlocks a volume, so that it is no longer read-only and can be written to.
vol_unlock vol=VolName
Parameters:
Name Type Description Mandatory
vol Object name The name of the volume
This command unlocks a volume so that it is no longer read-only and can be written into.
A volume that is unlocked is no longer write-protected.
The lock state of regular volumes is set to unlocked when they are created.
The lock state of snapshots is set to locked when they are created.
In addition to the lock state, snapshots also have a modification state. The modification state is a read-only state (which cannot be changed by the user explicitly) and it is initially set to unmodified when the snapshot is created. The first time a snapshot lock state is set to unlocked, the modification state of the snapshot is changed to modified, and it is never changed thereafter.
to unlock.
Y
Note:
The modification time is the time when the unlock command was executed, regardless of the actual changes performed on the volume via write commands.
If applied on a volume that is part of an IBM Hyper-Scale Mobility relation, the command has to be acknowledged by both source and destination volumes. Otherwise, a completion code is returned (see below).
Example:
vol_unlock vol=DBVolume
Output:
Command executed successfully.
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
58 IBM XIV Storage System User Manual
User Category Permission Condition
Application administrator Conditionally Allowed The volume is a snapshot, where
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.
Warnings:
v ARE_YOU_SURE_YOU_WANT_TO_UNLOCK_SNAPSHOT
Are you sure you want to unlock snapshot Snapshot?
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v VOLUME_IS_SLAVE
Volume is defined as a slave volume
v SNAPSHOT_IS_INTERNAL
Internal snapshots cannot be mapped, modified or deleted.
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
Chapter 3. Volume Management 59
60 IBM XIV Storage System User Manual
Chapter 4. LUN Mapping Management
All the LUN mapping commands are obsolete and were replaced by the clustering commands.
The following commands are no longer in use:
v map_add_vol (The concept of mapping has been replaced by clusters. See
map_volume.)
v map_create (The concept of mapping has been replaced by clusters. See
map_volume and cluster_create.)
v map_delete (The concept of mapping has been replaced by clusters. See
map_volume.)
v map_duplicate (The concept of mapping has been replaced by clusters.)
v map_link_host (The concept of mapping has been replaced by clusters. See
map_volume.)
v map_list (The concept of mapping has been replaced by clusters.)
v map_list_luns (The concept of mapping has been replaced by clusters. See
mapping_list)
v map_remove_vol (The concept of mapping has been replaced by clusters. See
unmap_volume.)
v map_rename (The concept of mapping has been replaced by clusters.)
v map_set_special_type (The concept of mapping has been replaced by clusters.
See special_type_set.)
v map_unlink_host (The concept of mapping has been replaced by clusters.)
61
62 IBM XIV Storage System User Manual
Chapter 5. Volume Snapshot Management
The following sections describe the XIV Command Line Interface (XCLI) for snapshot management. Other commands that are relevant to this topic are: Listing Volumes, Renaming a Volume, Changing Pool Settings for Snapshots.
See also:
v Volume Management
v Consistency Group Management
v Storage Pool Management
The sections are listed as follows:
v snapshot_change_priority(Changes a snapshot's deletion priority.)
v snapshot_create(Creates a snapshot of an existing volume.)
v snapshot_delete(Deletes a snapshot.)
v snapshot_duplicate(Duplicates an existing snapshot.)
v snapshot_format(Formats a snapshot)
v snapshot_list(Lists snapshot information.)
v snapshot_restore(Restores a master volume or a snapshot from one of its
associated snapshots.)
Changing a Snapshot Deletion Priority
Changes a snapshot's deletion priority.
snapshot_change_priority snapshot=SnapshotName delete_priority=del_value
Parameters:
Name Type Description Mandatory
snapshot Object name Name of the snapshot
Integer The priority for deleting
delete_ priority
This command changes the priority of the deletion of an existing snapshot. The deletion priority determines which snapshots are deleted first when the system runs out of snapshot storage.
The Auto Delete Priority can have a value between 1 and 4, as follows:
v 1 = Is the last to be deleted automatically ("1" is the default set by the system)
v ...
v 4 = Is the first to be deleted automatically
whose delete_priority is
Y
to be changed.
Y the volume's snapshot.
Example:
63
snapshot_change_priority snapshot=DBVolume.snapshot1 delete_priority=4
Output:
Command completed successfully
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed The master volume of the
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
snapshot is mapped to a host or cluster associated with the user and the snapshot was created by the application administrator.
Completion Codes:
v VOLUME_IS_NOT_A_SNAPSHOT
Operation is permitted only on snapshots
v SNAPSHOT_ILLEGAL_PRIORITY
Illegal snapshot priority; must be an integer between 1 and 4.
v SNAPSHOT_IS_INTERNAL
Internal snapshots cannot be mapped, modified or deleted.
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
v VOLUME_BAD_NAME
Volume name does not exist
v SNAPSHOT_IS_CONSISTENT_ELCS
If a mirrored volume is not consistent then its ELCS is protected and cannot be deleted.
Creating a Snapshot
Creates a snapshot of an existing volume.
snapshot_create vol=VolName < [ name=Name ] [ delete_priority=del_value]>|<overwrite=Name >
Parameters:
Name Type Description Mandatory Default
vol Object name Name of the
64 IBM XIV Storage System User Manual
volumes to
Y N/A
snapshot.
Name Type Description Mandatory Default
name Object name Names of the new
Integer The deletion
delete_ priority
overwrite Object name Name of an
snapshots.
priority of the volume's snapshot.
existing snapshots to be overwritten with the current volumes content.
N Auto-generated
names.
N1
N N/A
This command creates a new snapshot for an existing volume, which is referred to as the snapshot's master volume. The snapshot's content is the same as the master volume at the exact point in time that the snapshot was created. The snapshot remains unchanged, although the master volume keeps changing after the snapshot is created. Upon a successful completion of this command, the snapshot is created and assigned a name that can later be used by other commands. The name doesn't have to be new. It could be of an already existing snapshot (in such a case, the already existing snapshot is overridden).
A write operation can be processed at the exact time of the snapshot creation, meaning that the write operation request was sent to the system before the command was executed, while the write was acknowledged after the command was executed. In this case, the content of the snapshot is not deterministic and may either contain the original value before the write operation or the new value after the write operation. In fact, the snapshot's data may even contain a mixture of the two, where some blocks are equal to the volume before the write operation and other blocks are equal to the value after the write operation.
The new snapshot is initially locked for changes.
The snapshot that is created acts like a regular volume, except for the differences described below:
v The snapshot's name is either automatically generated from its master volume's
name or given as a parameter to the command. It can later be changed without altering the snapshot's modification state.
v Upon successful completion of the command, the system assigns a unique SCSI
ID to the snapshot. The creation time of the snapshot is set to the current time and is never changed until the snapshot is deleted.
v The size of the snapshot is the same as its master volume's size, but no storage
space is reserved for the snapshot. This means that the functionality of the snapshot is not guaranteed. When the snapshot's Storage Pool is exhausted, the snapshot may be deleted.
v The snapshot's lock state is initially set to "locked", and as long as it is not
"unlocked", the snapshot remains an exact image of the master volume at creation time and can be the source for a restore operation. The modification state of the snapshot is initially set to "unmodified".
During creation, the snapshot's deletion priority can be set explicitly, or it is automatically set to the default value. The deletion priority determines which snapshots will be deleted first when the Storage Pool runs out of snapshot storage.
Chapter 5. Volume Snapshot Management 65
This may happen due to the redirect-on-write mechanisms which share unchanged data between volumes and their snapshots, as well as between snapshots of the same volume.
The Auto Delete Priority is from the list (1-4), as follows:
v 1 = Is last to be deleted automatically ("1" is the default set by the system)
v ...
v 4 = Is first to be deleted automatically
The snapshot is associated with its master volume and this association cannot be broken or changed as long as the snapshot exists.
The overwrite option copies the current content of the volume into one of its existing snapshots (set as an input argument). The overwritten snapshot keeps the same SCSI serial number and same mapping, so hosts maintain a continuous mapping to the snapshot, without any need for a rescan or similar operation. The overwritten snapshot must be an existing snapshot of the given volume. The overwritten snapshot can't be part of a Snapshot Group.
This command fails when no snapshot space is defined in the Storage Pool the master volume belongs to.
Mirroring limitations:
v This command fails if the volume is a slave of an asynchronous mirroring
coupling (either synchronous or asynchronous).
v This command fails if the volume is a slave of an inconsistent synchronous
coupling.
Example:
snapshot_create vol=DBVolume name=DBVolume.snapshot1 delete_priority=2
Output:
Command executed successfully.
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed The volume is mapped to a host
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
or a cluster associated with the user. If a snapshot overwrite is used, the target snapshot must be one created by a server administrator.
66 IBM XIV Storage System User Manual
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v MAX_VOLUMES_REACHED
Maximum number of volumes already defined
v SNAPSHOT_ILLEGAL_PRIORITY
Illegal snapshot priority; must be an integer between 1 and 4.
v VOLUME_IS_SNAPSHOT
Operation is not permitted on snapshots
v VOLUME_EXISTS
Volume name already exists
v VOLUME_BAD_PREFIX
Volume name has a reserved prefix
v VOLUME_DATA_MIGRATION_UNSYNCHRONIZED
Data Migration has not completed to this volume
v OVERWRITE_SNAPSHOT_BAD_NAME
Snapshot name does not exist
v OVERWRITE_SNAPSHOT_IS_MASTER_VOL
Cannot overwrite Master Volume
This snapshot cannot be overwritten as it is a master volume.
v SNAPSHOT_OVERWRITE_MISMATCH
Specified snapshot is not a snapshot of the specified volume
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
v SNAPSHOT_IS_INTERNAL
Internal snapshots cannot be mapped, modified or deleted.
v POOL_SNAPSHOT_LIMIT_REACHED
There is not enough space to create a snapshot.
v VOLUME_IS_NOT_CONSISTENT_SLAVE
Operation not allowed on slave volume that is not consistent.
v SNAPSHOT_HAS_ACTIVE_SYNC_JOB
Snapshot is currently a target of an active sync job
Troubleshooting: Please wait for sync job to complete
v TOO_MANY_FAST_SNAPSHOTS_IN_VOLUME
Max number of fast snapshots for this volume already exist
Deleting a Snapshot
Deletes a snapshot.
snapshot_delete snapshot=SnapshotName
Parameters:
Name Type Description Mandatory
snapshot Object name Snapshot to be deleted. Y
Chapter 5. Volume Snapshot Management
67
This command deletes a snapshot. It cannot be used to delete a master volume, to delete a snapshot which is mapped to a host or cluster, or to delete an internal snapshot of a mirroring.
Example:
snapshot_delete snapshot=DBVolume.snapshot1
Output:
Command completed successfully
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed The master volume of the
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
snapshot is mapped to a host or cluster associated with the user and the snapshot was created by the application administrator.
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v VOLUME_IS_NOT_A_SNAPSHOT
Operation is permitted only on snapshots
v SNAPSHOT_IS_INTERNAL
Internal snapshots cannot be mapped, modified or deleted.
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
v SNAPSHOT_IS_MAPPED
Snapshot that is mapped to a host cannot be deleted
v SNAPSHOT_HAS_ACTIVE_SYNC_JOB
Snapshot is currently a target of an active sync job
Troubleshooting: Please wait for sync job to complete
v SNAPSHOT_IS_CONSISTENT_ELCS
If a mirrored volume is not consistent then its ELCS is protected and cannot be deleted.
Duplicating a Snapshot
Duplicates an existing snapshot.
snapshot_duplicate snapshot=SnapshotName [ name=Name ]
68 IBM XIV Storage System User Manual
Parameters:
Name Type Description Mandatory Default
snapshot Object name The name of the
snapshot to duplicate.
name Object name Name of the new
snapshot to be generated.
This command duplicates an existing snapshot. The newly created snapshot is initially locked for changes and is associated with the master volume of the existing snapshot. The content of the newly created snapshot is identical to the content of the source snapshot.
It is useful to duplicate a snapshot before unlocking it for write operations. The duplicate snapshot can be used as a logical backup of the data in case the write operation caused logical data corruption.
Upon successful completion of the command, a new duplicate snapshot is created.
The duplicated snapshot is identical to the source snapshot. It has the same creation time and behaves as if it was created at the exact same moment that the source snapshot was created from the same master volume.
Y N/A
N Automatically
generated name.
The duplicate snapshot's name is either automatically generated from its master volume's name or provided as a parameter. It can later be changed without altering its modification state.
A snapshot can be duplicated multiple times. A duplicated snapshot can be the source for further duplications.
Example:
snapshot_duplicate snapshot=DBVolume.snapshot1 name=DBVolume.snapshot1.copy
Output:
Command executed successfully.
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed The master volume of the
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
snapshot is mapped to a host or cluster associated with the user and the snapshot was created by the application administrator.
Chapter 5. Volume Snapshot Management
69
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v MAX_VOLUMES_REACHED
Maximum number of volumes already defined
v VOLUME_IS_NOT_A_SNAPSHOT
Operation is permitted only on snapshots
v VOLUME_EXISTS
Volume name already exists
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
v VOLUME_BAD_PREFIX
Volume name has a reserved prefix
Formatting a Snapshot
Formats a snapshot
snapshot_format snapshot=SnapshotName
Parameters:
Name Type Description Mandatory
snapshot Object name The snapshot to be
formatted.
Y
This command deletes the content of a snapshot while maintaining its mapping to the host. The format operation results with the following:
v The formatted snapshot is read-only
v The format operation has no impact on performance
v The formatted snapshot does not consume space
v Reading from the formatted snapshot always returns zeroes
v It can be overridden
v It can be deleted
v Its deletion priority can be changed
Example:
snapshot_format snapshot
Output:
Command executed successfully.
Access Control:
User Category Permission
Storage administrator Allowed
70 IBM XIV Storage System User Manual
User Category Permission
Storage integration administrator Allowed
Application administrator Allowed
Security administrator Disallowed
Read-only users Disallowed
Technicians Disallowed
Completion Codes:
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
v SNAPSHOT_HAS_ACTIVE_SYNC_JOB
Snapshot is currently a target of an active sync job
Troubleshooting: Please wait for sync job to complete
v VOLUME_BAD_NAME
Volume name does not exist
v SNAPSHOT_IS_INTERNAL
Internal snapshots cannot be mapped, modified or deleted.
v MAX_VOLUMES_REACHED
Maximum number of volumes already defined
v SNAPSHOT_IS_FORMATTED
Snapshot is formatted
v ELCS_CANNOT_BE_FORMATTED
The snapshot is an ELCS and cannot be formatted.
v VOLUME_IS_NOT_A_SNAPSHOT
Operation is permitted only on snapshots
Listing Snapshot Information
Lists snapshot information.
snapshot_list vol=VolName
Parameters:
Name Type Description Mandatory
vol Object name List of all the snapshots
This command lists snapshot information for all the snapshots of a specified volume.
This command displays the following VAAI fields (available on the XML output format):
v enable_VAAI
v user_disabled_VAAI
This command displays the following snapshot format field (available on the XML output format):
of this volume.
Y
Chapter 5. Volume Snapshot Management 71
v snapshot_format
Id Name Default Position
name Name 1
size Size (GB) 2
size_MiB Size (MiB) N/A
master_name Master Name 3
cg_name Consistency Group 4
pool_name Pool 5
creator Creator 6
proxy Proxy N/A
capacity Capacity (blocks) N/A
modified Modified N/A
sg_name Snapshot Group Name N/A
Deletion Priority N/A
delete_ priority
locked Locked N/A
serial Serial Number N/A
snapshot_time Snapshot Creation Time N/A
Master Copy Creation Time N/A
snapshot_time_ on_master
Snapshot Internal Role N/A
snapshot_ internal_role
snapshot_of Snapshot of N/A
sg_snapshot_of Snapshot of Snap Group N/A
wwn WWN N/A
mirrored Mirrored N/A
locked_by_pool Locked by Pool N/A
used_capacity Used Capacity (GB) 7
Used Capacity (MiB) N/A
used_capacity_ MiB
short_lived_io Short Live IO N/A
enable_VAAI VAAI enabled N/A
VAAI disabled by user N/A
user_disabled_ VAAI
Snapshot Format N/A
snapshot_ format
ssd_caching SSD Caching State N/A
Use SSD Caching Default State N/A
use_ssd_ caching_ default
unmap_support Unmap Support N/A
managed Managed N/A
enable_unmap unmap enabled N/A
72 IBM XIV Storage System User Manual
Id Name Default Position
unmap disabled by user N/A
user_disabled_ unmap
marked Marked N/A
Example:
snapshot_list vol=DBVolume
Output:
Name Size (GB) Master Name Consistency Group Pool DBVolume.sp1 2508 DBVolume default DBVolume.sp1.copy 2508 DBVolume default
Access Control:
User Category Permission
Storage administrator Allowed
Storage integration administrator Allowed
Application administrator Allowed
Security administrator Disallowed
Read-only users Allowed
Technicians Disallowed
Restoring a Volume from a Snapshot
Restores a master volume or a snapshot from one of its associated snapshots.
snapshot_restore snapshot=SnapshotName [ target_snapshot=SnapshotName ]
Parameters:
Name Type Description Mandatory Default
snapshot Object name Name of the
Object name Snapshot to be
target_ snapshot
This command restores the data of a master volume from one of its associated snapshots.
Issuing a restore command logically copies the data of the source snapshot onto its volume. The volume's data is therefore restored to the state that it was at the time that the snapshot was created. If the volume was resized after the snapshot was created, the restore operation resizes the volume back to its original size.
snapshot with which to restore its master volume, or snapshot.
restored.
Y N/A
N Restore the master
volume.
Chapter 5. Volume Snapshot Management 73
All the snapshots associated with the volume are left unchanged during a restore operation.
It is possible to snapshot the volume before restoring it, so that the generated snapshot can be used and the data is not lost.
It is possible to restore another snapshot (the target snapshot) from the source snapshot. The target snapshot must be a snapshot of the same volume as the source snapshot. The target snapshot's content and size will be identical to the source snapshot's content and size. The target snapshot's lock/unlock status will remain as it was.
Restoring a mirrored volume:
v Delete the mirror
v Restore the volume
v Re-establish the mirror
Note:
It is impossible to restore a volume while it is mirrored.
Example:
snapshot_restore snapshot=DBVolume.snapshot1
Output:
Command completed successfully.
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed Both target and source are
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
snapshots of the same master volume. This master volume is mapped to a host or cluster associated with the user, and the target snapshot was created by an application administrator.
Warnings:
v ARE_YOU_SURE_YOU_WANT_TO_RESTORE_SNAPSHOT
Are you sure you want to restore the volume from snapshot Snapshot?
Completion Codes:
v VOLUME_HAS_DATA_MIGRATION
Data Migration is defined for this volume
74 IBM XIV Storage System User Manual
v VOLUME_BAD_NAME
Volume name does not exist
v VOLUME_IS_NOT_A_SNAPSHOT
Operation is permitted only on snapshots
v NOT_ENOUGH_SPACE
No space to allocate volume
v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Snapshot is part of a Snapshot Group
v VOLUME_HAS_MIRROR
Mirror is defined for this volume
v VOLUME_LOCKED
Volume is locked
v SNAPSHOTS_BELONG_TO_DIFFERENT_MASTERS
Target snapshot and source snapshot should be snapshots of the same volume
v TARGET_SNAPSHOT_BAD_NAME
Target snapshot name does not exist
v TARGET_SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP
Target snapshot is part of a Snapshot Group
v TARGET_SNAPSHOT_IS_MASTER
Target snapshot is a master volume
v TARGET_SNAPSHOT_SAME_AS_SNAPSHOT
Source snapshot cannot be the target snapshot
v TARGET_SNAPSHOT_HAS_ACTIVE_SYNC_JOB
Traget snapshot is currently a target of an active sync job
Troubleshooting: Please wait for sync job to complete
Chapter 5. Volume Snapshot Management 75
76 IBM XIV Storage System User Manual
Chapter 6. Consistency Group Management
The following sections describe the XIV Command Line Interface (XCLI) for Consistency Group management. Other commands that are relevant to this topic are: Snapshotting a Consistency Group, Moving a Volume between Storage Pools , Moving Consistency Groups between Storage Pools or or Grouped Pools.
v Volume Management
v Volume Snapshot Management
v Storage Pool Management
The sections are listed as follows:
v cg_add_vol(Adds a volume to a Consistency Group.)
v cg_create(Creates a Consistency Group.)
v cg_delete(Deletes a Consistency Group.)
v cg_list(Lists Consistency Groups.)
v cg_remove_vol(Removes a volume from a Consistency Group. )
v cg_rename(Renames Consistency Groups.)
v io_pause(Suspend IO execution on CG)
v io_resume(Resume IO execution on CG previously suspended with resume_io)
v io_pause_list(List CGs io_pause state)
v xcg_create(Creates a Cross-system Consistency Group (XCG) definition.)
v xcg_add_cg(Associates an existing Consistency Group to a Cross-system
Consistency Group definition.)
v xcg_remove_cg(Removes an existing Consistency Group from a Cross-system
Consistency Group definition.)
v xcg_add_remote_system(Adds a remote system name to the Cross-system
Consistency Group definition.)
v xcg_remove_remote_system(Removes a remote system name from a
Cross-system Consistency Group definition.)
v xcg_get_local_cgs(Lists Cross-system Consistency Group definitions along with
contained Consistency Groups.)
v xcg_get_remote_systems(Retrieve the names of remote systems part of the
specified Cross-system Consistency Group.)
v xcg_delete(Deletes a Cross-system Consistency Group (XCG) definition.)
v xcg_list(Lists Cross-system Consistency Group definitions along with contained
Consistency Groups.)
The following commands are no longer in use:
v cg_restore (The command has been replaced by the snap_group_restore
command)
Adding a Volume to a Consistency Group
Adds a volume to a Consistency Group.
cg_add_vol cg=cgName vol=VolName
77
Parameters:
Name Type Description Mandatory
cg Object name Name of a Consistency
Group.
vol Object name Name of the volume to
add.
This command adds a volume to a Consistency Group. The Consistency Group is capable of containing up to 128 volumes.
Requirements for successful command completion:
v The volume and Consistency Group have to be associated with the same pool.
v The volume is not already part of a Consistency Group.
v The volume can not be a snapshot.
v The Consistency Group has less than the max number of volumes (see above).
Adding a mirrored volume to a non-mirrored Consistency Group:
v Such an addition always succeeds and the volume will retain its mirroring
settings.
Requirements for successful command completion for a mirrored Consistency Group:
v The command must be issued only on the master Consistency Group.
v The command can not be run during an initialization of the volume or the
Consistency Group.
v The volume does not have any outstanding ad-hoc sync jobs.
v The volume has to be mirrored, and its following mirroring settings must be
identical to those of the Consistency Group: mirroring type (e.g., synchronous), mirroring status, mirroring target, target pool, designation.
v In addition, for a mirrored Consistency Group that is defined as sync_best_effort
(synchronous):
– The synchronization status of both volume and Consistency Group has to be
Synchronized.
v For a mirrored Consistency Group that is defined as async_interval
(asynchronous):
– The volume and Consistency Group must have the following identical
settings and values: schedule, remote schedule, timestamp of the last_replicated snapshot.
– Their both synchronization status is RPO_OK
v The link has to be up.
Y
Y
Adding a mirrored volume to a mirrored Consistency Group will also add the volume's peer to the Consistency Group's peer. Once added, the mirrored volume will be set the RPO of the mirrored Consistency Group.
The mirrored Consistency Group has one sync job for all pertinent mirrored volumes within the Consistency Group.
In case of acknowledgment time out:
78 IBM XIV Storage System User Manual
v Whenever the command is issued on a mirrored CG Master - and the Master
does not receive an acknowledgment from the Slave (until the command timed out or due to any unexpected failure), a completion code is returned (MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH).
If the command CG_ADD_VOLUME is issued on a mirrored CG Master - and the Master does not receive an acknowledgment from the Slave (until the command timed out or due to any unexpected failure), a new completion code will be returned (MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH ­meaning that the member lists of the mirror Consistency Group peers might not be the same).
If applied on a volume that is part of an IBM Hyper-Scale Mobility relation:
v The command is applicable only to a destination volume
v This destination volume has to be in Proxy state
Otherwise, a completion code is returned (see below).
Example:
cg_add_vol cg=DBGroup vol=DBLog
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
Warnings:
v CONS_GROUP_MIRROR_DESIGNATION_MISMATCH
Volume Mirror has different designation than Consistency Group Mirror. Are you sure you want to add that Volume to that CG?
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v CONS_GROUP_BAD_NAME
Consistency Group name does not exist.
v CONS_GROUP_IS_SLAVE
Consistency Group is mirroring slave.
v MAX_VOLUMES_IN_CONS_GROUP_REACHED
The maximum permitted number of volumes per Consistency Group is reached.
Chapter 6. Consistency Group Management 79
Consistency Group contains maximum number of volumes.
v MAX_VOLUMES_IN_REMOTE_CONS_GROUP_REACHED
The maximum permitted number of volumes per the remote Consistency Group is reached.
Remote Consistency Group contains maximum number of volumes.
v MIRROR_HAS_SYNC_JOB
Operation is not permitted on a mirror with active sync jobs
v MIRROR_IS_NOT_SYNCHRONIZED
Mirror is not synchronized
v MIRROR_LAST_SYNC_TIMES_DIFFER
All mirrors should have the same last sync time.
v MIRROR_RETRY_OPERATION
There is an operation in progress on this mirror , please retry your request in a few seconds
Troubleshooting: Please retry the command in a few seconds
v REMOTE_VOLUME_BAD_POOL
Remote volume and remote Consistency Group belong to different Storage Pools
v REMOTE_VOLUME_BELONGS_TO_CONS_GROUP
The remote volume belongs to a Consistency Group.
Remote Volume belongs to a Consistency Group
v TARGET_NOT_CONNECTED
There is currently no connection to the target system
v VOLUME_BAD_POOL
Volume belongs to a different Storage Pool
v VOLUME_BELONGS_TO_CG
Volume belongs to a Consistency Group
v VOLUME_DATA_MIGRATION_UNSYNCHRONIZED
Data Migration has not completed to this volume
v VOLUME_IS_SNAPSHOT
Operation is not permitted on snapshots
v CONS_GROUP_MIRROR_SCHEDULE_MISMATCH
Volumes under Consistency Group Mirror should have the same mirroring schedule.
v CONS_GROUP_MIRROR_TARGET_MISMATCH
Volumes under Consistency Group Mirror should have the same mirroring Target.
v CONS_GROUP_MIRROR_ROLE_MISMATCH
Volumes under Consistency Group Mirror should have the same mirroring role.
v CONS_GROUP_MIRROR_ACTIVATION_MISMATCH
Volumes under Consistency Group Mirror should have the same mirroring activation state.
v REMOTE_CONS_GROUP_MIRROR_SCHEDULE_MISMATCH
Volumes under Consistency Group Mirror in remote machine should have identical mirroring schedule.
v CONS_GROUP_MIRROR_TYPE_MISMATCH
Volumes under Consistency Group Mirror should have the same mirroring type.
80 IBM XIV Storage System User Manual
v MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH
Mirrored CG may contain different volumes on Master and Slave. This problem occurs whenever the cg_add_vol command results with the Master not receiving an acknowledgment from the Slave until the command timed out, or any other unexpected failure.
v REMOTE_CONS_GROUP_APPLICATION_CONSISTENCY_MISMATCH
Application consistency of the volume doesn't match the state of other volumes in the group on the remote machine.
v CONS_GROUP_APPLICATION_CONSISTENCY_MISMATCH
Application consistency of the volume doesn't match the state of other volumes in the group.
v VOLUME_HAS_OLVM
IBM Hyper-Scale Mobility relation is defined for this volume
Creating Consistency Groups
Creates a Consistency Group.
cg_create cg=cgName <pool=PoolName | gp=gpName>
Parameters:
Name Type Description Mandatory
cg Object name Name of the
pool Object name Storage Pool of the
gp Object name Grouped Pool of the
Consistency Group.
Y
N Consistency Group.
N Consistency Group.
This command creates a Consistency Group. A Consistency Group is a group of volumes that can all be snapshotted at the same point in time. This is essential for snapshotting several volumes that are used by the same application or by applications that interact with each other in order to generate a consistent set of snapshots.
The name of the Consistency Group must be unique in the system. The system is capable of containing up to 256 Consistency Groups.
The Storage Pool of the Consistency Group must be specified.
The Consistency Group is initially empty, containing no volumes.
A Consistency Group always belongs to a specific Storage Pool. All the volumes in the Consistency Group belong to the same Storage Pool as the Consistency Group.
The Consistency Group can be mirrored as a whole (see Creating a Mirroring Definition).
Example:
cg_create pool=p_1 cg=DBgroup
Chapter 6. Consistency Group Management
81
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 CONS_GROUP_NAME_EXISTS
Consistency Group name already exists.
v MAX_CONS_GROUPS_REACHED
Maximum number of Consistency Groups already defined.
v POOL_DOES_NOT_EXIST
Storage Pool does not exist
Deleting a Consistency Group
Deletes a Consistency Group.
cg_delete cg=cgName
Parameters:
Name Type Description Mandatory
cg Object name Name of the
This command deletes a Consistency Group.
This command fails if:
v The Consistency Group is not empty (meaning that it still contains volumes).
v The Consistency Group is mirrored (even if empty).
All snapshot groups associated with the Consistency Group are disbanded, meaning that the snapshots contained in these snapshot groups become independent snapshots.
Example:
Consistency Group to
Y
delete.
cg_delete cg=DBvolumes
Output:
82 IBM XIV Storage System User Manual
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
Completion Codes:
v CONS_GROUP_BAD_NAME
Consistency Group name does not exist.
v CONS_GROUP_NOT_EMPTY
This operation is only allowed on an empty Consistency Group.
v CONS_GROUP_HAS_MIRROR
Consistency Group has mirroring defined for it.
The mirror definition has to be removed.
v CONS_GROUP_BELONGS_TO_XCG
Consistency Group belongs to another Cross Consistency Group.
Listing Consistency Groups
Lists Consistency Groups.
cg_list [ cg=cgName ]
Parameters:
Name Type Description Mandatory Default
cg Object name Name of a
This command lists select details for all Consistency Groups; if a Consistency Group name is specified, it is the only one to be listed.
Listed details include the following:
v Name
v Mirrored CG - indicates whether the Consistency Group is mirrored
– Available values - Yes|No
v GP Based (indicates whether the Consistency Group is based on a Grouped
Pool)
– Values - Yes|No
v Mirror sync status - indicates the status of the mirroring
– Available values - RPO_OK|RPO_Lagging
Consistency
N All
Group.
Chapter 6. Consistency Group Management 83
v CG role - the role of the peer
– Available values - master|slave
Id Name Default Position
name Name 1
pool Pool Name 2
gp_based GP Based N/A
mirrored Mirrored N/A
managed Managed N/A
Example:
cg_list cg=DBgroup
Output:
Name Pool Name Mirrored GP Based DBgroup default Yes No
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 Volume from a Consistency Group
Removes a volume from a Consistency Group.
cg_remove_vol vol=VolName
Parameters:
Name Type Description Mandatory
vol Object name Name of the volume to
be removed.
This command removes a volume from a Consistency Group.
A Consistency Group's name is deduced from the volume name. A unique name is ensured because each volume belongs to only a single Consistency Group. Future snapshot groups that are created from this Consistency Group will not include a snapshot that is associated with the removed volume.
Following the volume removal:
v Corresponding peer volume is removed from the peer Consistency Group
84 IBM XIV Storage System User Manual
Y
– If the Consistency Group is mirrored, the mirroring definition of the removed
volume is retained. The mirroring definition is based on the same settings as the Consistency Group.
v The peer volume is also removed from the peer Consistency Group
v The removed mirrored volume is set the RPO of the mirrored Consistency
Group from which it was removed
v Event is generated
This command succeeds even if the volume is not included in any Consistency Group.
Requirements for a successful command completion:
v The command can be issued only on the master
v The link must be up
v The Consistency Group cannot have ongoing sync jobs
In case of acknowledgment time-out:
v Whenever the command is issued on a mirrored CG Master - and the Master
does not receive an acknowledgment from the Slave (until the command timed out or due to any unexpected failure), a completion code is returned (MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH).
If applied on a volume that is part of an IBM Hyper-Scale Mobility relation:
v The command is applicable only to a destination volume
v This destination volume must be in Proxy state
Otherwise, a completion code is returned.
Example:
cg_remove_vol vol=DBLog
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
Warnings:
v ARE_YOU_SURE_YOU_WANT_TO_REMOVE_VOLUME_FROM_
CONS_GROUP
Are you sure you want to remove volume 'Volume' from its Consistency Group?
Chapter 6. Consistency Group Management 85
Completion Codes:
v VOLUME_BAD_NAME
Volume name does not exist
v VOLUME_NOT_IN_CONS_GROUP
Volume does not belong to a Consistency Group
v TARGET_NOT_CONNECTED
There is no connection to the target system
v VOLUME_IS_SNAPSHOT
Operation is not permitted on snapshots
v CONS_GROUP_IS_SLAVE
Consistency Group is mirroring slave.
v MIRROR_RETRY_OPERATION
There is an operation in progress on this mirror , please retry your request in a few seconds
Troubleshooting: Please retry the command in a few seconds
v MIRROR_HAS_SYNC_JOB
Operation is not permitted on a mirror with active sync jobs
v MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH
Mirrored CG may contain different volumes on Master and Slave. This problem occurs whenever the cg_add_vol command results with the Master not receiving an acknowledgment from the Slave until the command timed out, or any other unexpected failure.
v VOLUME_IS_NOT_CONSISTENT_SLAVE
Operation not allowed on slave volume that is not consistent.
v SNAPSHOT_HAS_ACTIVE_SYNC_JOB
Snapshot is currently a target of an active sync job
Troubleshooting: Please wait for sync job to complete
v VOLUME_HAS_OLVM
IBM Hyper-Scale Mobility relation is defined for this volume
Renaming Consistency Groups
Renames Consistency Groups.
cg_rename cg=cgName new_name=Name
Parameters:
Name Type Description Mandatory
cg Object name The name of the
new_name Object name The new name of the
This command renames a Consistency Group.
The new name of the Consistency Group must be unique in the system.
86 IBM XIV Storage System User Manual
Consistency Group to
Y
be renamed.
Y
Consistency Group.
This command succeeds even if the new name is identical to the current name.
Example:
cg_rename cg=DBgroup new_name=DBvolumes
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
Completion Codes:
v CONS_GROUP_BAD_NAME
Consistency Group name does not exist.
v CONS_GROUP_NAME_EXISTS
Consistency Group name already exists.
Suspend I/O Execution on Consistency Group
Suspend IO execution on CG
io_pause cg=cgName [ milli_seconds_to_resume=MilliSecondsTimeout ] [ allow_read=AllowRead ]
Parameters:
Name Type Description Mandatory Default
Positive integer Timeout for auto
milli_ seconds_ to_resume
allow_read Boolean Flag controls
cg Object name CG name Y N/A
Suspend I/O execution on Consistency Group with auto-resume timeout
resume, measurement starts when current IOs execution on CG completes
whether to enable read IOs during the io_pause period
N 10000
N yes
It is possible to suspend execution of all I/Os or just writes
Chapter 6. Consistency Group Management 87
Example:
io_pause cg=test_cg milli_seconds_to_resume=10000
Output:
command:
code = "SUCCESS" status = "0" status_str = "Command completed successfully" return:
token_id = "6343971831808"
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed At least one of the volumes in
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.
Completion Codes:
v COMMAND_IS_NOT_VALID_IN_CURRENT_SYSTEM_STATE
The requested command cannot be invoked in the current system state
v PAUSE_IO_TIMEOUT_OUT_OF_RANGE
Timeout parameter is out of range
v TOO_MANY_IO_PAUSE_ISSUED
Too many Pause IOs are in progress
v CONS_GROUP_BAD_NAME
Consistency Group name does not exist.
v CONS_GROUP_IS_SLAVE
Consistency Group is mirroring slave.
v IO_PAUSE_ALREADY_ISSUED_FOR_CONS_GROUP
Volume(s) belonging to the Consistency Group are already paused
Resume I/O Execution
Resume IO execution on CG previously suspended with resume_io
io_resume token_id=Token
88 IBM XIV Storage System User Manual
Parameters:
Name Type Description Mandatory
token_id Positive integer token returned by
resume_io command
Y
Resume IO execution on CG previously suspended with resume_io
Example:
io_resume token_id=6343971831808
Output:
command:
code = "SUCCESS" status = "0" status_str = "Command completed successfully"
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed At least one of the volumes in
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.
Completion Codes:
v CONS_GROUP_IS_NOT_PAUSED
Consistency Group is not paused or auto-resume timeout expired
v CONS_GROUP_DEFINITION_MODIFIED_DURING_IO_PAUSE
Consistency Group definitions changed during pause io period
List Consistency Groups Pause I/O State
List CGs io_pause state
io_pause_list [ token_id=Token ]
Chapter 6. Consistency Group Management
89
Parameters:
Name Description Mandatory Default
token_id Optional filter value to
show status for specific token, 0 means unfiltered
Gives detailed status of pause_io_state of CGs suspended with io_pause
Example:
io_pause_list
Output:
command:
code = "SUCCESS" status = "0" status_str = "Command completed successfully" return:
stop_io 0:
allow_read = "yes" cg_name = "cg_test" config_changed = "no" inode_list_changed = "no" num_volumes = "1" resume_pending = "no" stop_io_elapsed_time = "4062" timeout = "10000" token = "6343971831808"
N0
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed At least one of the volumes in
Security administrator Disallowed N/A
Read-only users Allowed N/A
Technicians Disallowed N/A
Creates a Cross-System Consistency Group
Creates a Cross-system Consistency Group (XCG) definition.
xcg_create xcg=XcgName
the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.
90 IBM XIV Storage System User Manual
Parameters:
Name Type Description Mandatory
xcg Object name Name of a Cross-system
Consistency Group.
Y
Creates a Cross-system Consistency Group (XCG) definition to which Consistency Groups on different XIV systems may be associated.
Example:
xcg_create xcg=DBbackup
Output:
Command completed successfully
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed At least one of the volumes in
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.
Completion Codes:
v XCG_NAME_EXISTS
Cross Consistency Group name already exists.
v MAX_XCGS_REACHED
Maximum number of Cross Consistency Groups already defined.
Associates an Existing Consistency Group to a Cross-System Consistency Group Definition
Associates an existing Consistency Group to a Cross-system Consistency Group definition.
xcg_add_cg xcg=XcgName cg=cgName
Parameters:
Name Type Description Mandatory
xcg Object name Name of a Cross-system
Consistency Group.
Chapter 6. Consistency Group Management
Y
91
Name Type Description Mandatory
cg Object name Name of a Consistency
Group.
Y
Associates an existing Consistency Group to a Cross-system Consistency Group definition.
Example:
xcg_add_cg xcg=DBbackup cg=CGbackup
Output:
Command completed successfully
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed At least one of the volumes in
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.
Completion Codes:
v XCG_BAD_NAME
Cross Consistency Group name does not exist.
v MAX_CONS_GROUPS_IN_XCG_REACHED
Cross Consistency Group contains maximum number of cgs.
v CONS_GROUP_IS_SLAVE
Consistency Group is mirroring slave.
v CONS_GROUP_BAD_NAME
Consistency Group name does not exist.
v CONS_GROUP_ALREADY_IN_XCG
Consistency Group already belongs to Cross Consistency Group.
v CONS_GROUP_BELONGS_TO_XCG
Consistency Group belongs to another Cross Consistency Group.
92 IBM XIV Storage System User Manual
Removes an Existing Consistency Group from a Cross-System Consistency Group Definition
Removes an existing Consistency Group from a Cross-system Consistency Group definition.
xcg_remove_cg xcg=XcgName cg=cgName
Parameters:
Name Type Description Mandatory
xcg Object name Name of a Cross-system
Consistency Group.
cg Object name Name of a Consistency
Group.
Removes an existing Consistency Group from a Cross-system Consistency Group definition.
Example:
xcg_remove_cg xcg=DBbackup cg=CGBackup
Y
Y
Output:
Command completed successfully
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed At least one of the volumes in
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.
Warnings:
v ARE_YOU_SURE_YOU_WANT_TO_REMOVE_CONS_GROUP_FROM_XCG
Are you sure you want to remove cons group 'CG' from its cross Consistency Group?
Completion Codes:
v XCG_BAD_NAME
Cross Consistency Group name does not exist.
Chapter 6. Consistency Group Management 93
v CONS_GROUP_BAD_NAME
Consistency Group name does not exist.
v XCG_IS_EMPTY
Consistency Group is empty.
v CONS_GROUP_NOT_IN_XCG
Consistency Group doesnt belong to Cross Consistency Group.
Adds a Remote System Name to the Cross-System Consistency Group Definition
Adds a remote system name to the Cross-system Consistency Group definition.
xcg_add_remote_system xcg=XcgName remote_system=RemoteSystem
Parameters:
Name Type Description Mandatory
xcg Object name Name of a Cross-system
String Name of a remote
remote_ system
Consistency Group.
system.
Y
Y
Adds a remote system name to the Cross-system Consistency Group definition.
Example:
xcg_add_remote_system xcg=DBbackup remote_system=CGbackup
Output:
Command completed successfully
Access Control:
User Category Permission Condition
Storage administrator Allowed N/A
Storage integration administrator Allowed N/A
Application administrator Conditionally Allowed At least one of the volumes in
Security administrator Disallowed N/A
Read-only users Disallowed N/A
Technicians Disallowed N/A
the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.
94 IBM XIV Storage System User Manual
Loading...