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.
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 Management61
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 Definitions99
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 Number40
Copying Volumes ............42
Creating a Volume ............44
Deleting a Volume ............46
Formatting a Volume ...........48
Listing Volumes .............49
Chapter 7. Snapshot Set Management101
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 Management119
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 Spares156
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 Version159
Initiating Download of a New Software Version160
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
ivIBM XIV Storage System User Manual
Chapter 13. IBM Hyper-Scale Mobility247
Creating an IBM Hyper-Scale Mobility Relation247
Activates the Volume Migration .......250
Deactivates IBM Hyper-Scale Mobility Migration251
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 Relationship255
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 Group274
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
Contentsv
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 Maintenance401
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 System420
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 Processes434
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:
IntroductionIntroduces the document, intended audience,
CLI CommandsProvides detailed information about each
Event DescriptionsProvides detailed information about the events
Return CodesLists all UNIX return codes returned by the XCLI
GlossaryProvides an alphabetically ordered list of the
IndexProvides 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
vNotes 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
OLVMOnline Volume Mobility - denotes an IBM
Hyper-Scale Mobility relationship.
Parameter Definitions
DefinitionDescriptionSyntax
IP AddressAn 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.
2IBM 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. Introduction3
4IBM 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:
vcluster_add_host(Adds a host to a cluster.)
vcluster_create(Creates a new cluster.)
vcluster_delete(Deletes a cluster.)
vcluster_list(Lists a specific cluster or all of them.)
vcluster_remove_host(Removes a host from a cluster.)
vcluster_rename(Renames a cluster.)
vhost_add_port(Adds a port address to a host.)
vhost_define(Defines a new host to connect to the XIV system.)
vhost_delete(Deletes a host. )
vhost_list(Lists a specific host or all hosts.)
vhost_list_ports(Lists all the ports of a host)
vhost_remove_port(Removes a port from a host.)
vhost_rename(Renames a host. )
vhost_update(Updates a host definition.)
vmap_vol(Maps a volume to a host or a cluster.)
vmapping_list(Lists the mapping of volumes to a specified host or cluster.)
vspecial_type_set(Sets the special type of a host or a cluster.)
vvol_mapping_list(Lists all hosts and clusters to which a volume is mapped. )
vunmap_vol(Unmaps a volume from a host or a cluster.)
vunmap_vol_set_default_idle_time(Sets the default idle time required for a
volume before unmapping it)
vperf_class_create(Creates a Performance Class)
vperf_class_delete(Deletes a Performance Class)
vperf_class_rename(Renames a Performance Class)
vperf_class_list(Lists Performance Classes)
vperf_class_add_host(Adds a host to a Performance Class)
vperf_class_remove_host(Removes a host from its Performance Class)
vperf_class_set_rate(Sets the rate for a Performance Class)
vhost_profile_list(lists all host profiles)
vhost_profile_set(updates the host profile)
vhost_profile_clear(removes the profile of the specified host)
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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
6IBM 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:
NameTypeDescriptionMandatory
clusterObject nameName 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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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:
NameTypeDescriptionMandatory
clusterObject nameCluster 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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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:
NameTypeDescriptionMandatoryDefault
clusterObject nameCluster 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.
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.
iscsi_nameiSCSI initiator nameiSCSI 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.
10IBM 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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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
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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
12IBM XIV Storage System User Manual
Deleting a Host
User CategoryPermission
Read-only usersDisallowed
TechniciansDisallowed
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:
NameTypeDescriptionMandatory
hostObject nameThe 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.
initiator used to
authenticate to XIV
when CHAP is
enabled
YN/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
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 CategoryPermissionCondition
Storage administratorAllowedN/A
Storage integration administrator AllowedN/A
Application administratorConditionally AllowedThis volume is a snapshot. The
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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
20IBM 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.
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.
Lists all hosts and clusters to which a volume is mapped.
vol_mapping_list vol=VolName
Chapter 2. Host and Cluster Management
23
Parameters:
NameTypeDescriptionMandatory
volObject nameVolume 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).
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:
NameTypeDescriptionMandatory
perf_classObject nameExisting name of a
Performance Class
new_nameStringNew 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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
Completion Codes:
v PERF_CLASS_EXISTS
Performance Class already exists.
v PERF_CLASS_BAD_NAME
Performance Class does not exist
28IBM XIV Storage System User Manual
Listing Details on Performance Classes
Lists Performance Classes
perf_class_list [ perf_class=perfClassName ]
Parameters:
NameTypeDescriptionMandatoryDefault
perf_classStringName 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.
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.
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 Management33
Removes the Profile of the Specified Host
removes the profile of the specified host
host_profile_clear host=HostName
Parameters:
NameTypeDescriptionMandatory
hostObject nameThe host name.Y
removes the profile of the specified host
Example:
xcli -u -c XIV1 host_profile_clear host
Access Control:
User CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorAllowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansAllowed
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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
34IBM XIV Storage System User Manual
User CategoryPermission
Application administratorAllowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorAllowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
Chapter 2. Host and Cluster Management
35
36IBM 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:
vVolume Snapshot Management
vConsistency Group Management
vStorage Pool Management
The sections are listed as follows:
vreservation_clear(Clears reservations of a volume.)
vreservation_key_list(Lists reservation keys.)
vreservation_list(Lists volume reservations.)
vvol_by_id(Prints the volume name according to its specified SCSI serial number.
)
vvol_copy(Copies a source volume onto a target volume.)
vvol_create(Creates a new volume.)
vvol_delete(Deletes a volume.)
vvol_format(Formats a volume.)
vvol_list(Lists all volumes or a specific one.)
vvol_lock(Locks a volume so that it is read-only.)
vvol_rename(Renames a volume.)
vvol_resize(Resizes a volume.)
vvol_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
Prints the volume name according to its specified SCSI serial number.
vol_by_id id=n
Parameters:
NameTypeDescriptionMandatory
idPositive integerSCSI volume ID.Y
This command prints the volume name according to its specified SCSI serial
number.
IdNameDefault Position
nameName1
sizeSize (GB)2
size_MiBSize (MiB)N/A
master_nameMaster Name3
cg_nameConsistency Group4
pool_namePool5
creatorCreator6
40IBM XIV Storage System User Manual
IdNameDefault Position
proxyProxyN/A
capacityCapacity (blocks)N/A
modifiedModifiedN/A
sg_nameSnapshot Group NameN/A
Deletion PriorityN/A
delete_
priority
lockedLockedN/A
serialSerial NumberN/A
snapshot_timeSnapshot Creation TimeN/A
Master Copy Creation TimeN/A
snapshot_time_
on_master
Snapshot Internal RoleN/A
snapshot_
internal_role
snapshot_ofSnapshot ofN/A
sg_snapshot_ofSnapshot of Snap GroupN/A
wwnWWNN/A
mirroredMirroredN/A
locked_by_poolLocked by PoolN/A
used_capacityUsed Capacity (GB)7
Used Capacity (MiB)N/A
used_capacity_
MiB
short_lived_ioShort Live ION/A
enable_VAAIVAAI enabledN/A
VAAI disabled by userN/A
user_disabled_
VAAI
Snapshot FormatN/A
snapshot_
format
ssd_cachingSSD Caching StateN/A
Use SSD Caching Default StateN/A
use_ssd_
caching_
default
unmap_supportUnmap SupportN/A
managedManagedN/A
enable_unmapunmap enabledN/A
unmap disabled by userN/A
user_disabled_
unmap
markedMarkedN/A
Example:
vol_by_id id=59
Chapter 3. Volume Management
41
Output:
NameSize (GB) Master Name Consistency Group Pool Creator Used Capacity(GB)
volume_1 510
Access Control:
User CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorAllowed
Security administratorDisallowed
Read-only usersAllowed
TechniciansDisallowed
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:
NameTypeDescriptionMandatory
vol_srcObject nameName of the source
volume from which the
data is to be taken.
vol_trgObject nameName 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).
42IBM 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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
Warnings:
v ARE_YOU_SURE_YOU_WANT_TO_COPY_VOLUME
Are you sure you want to copy the contents of volume source Volume to volumetarget Volume?
Completion Codes:
v NOT_ENOUGH_HARD_SPACE
No space to allocate for volume's current usage
v NOT_ENOUGH_SPACE
Chapter 3. Volume Management43
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.
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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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:
NameTypeDescriptionMandatory
volObject nameName of the volume to
This command deletes a volume. All data stored on the volume is lost and cannot
be restored.
46IBM 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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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 Management47
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:
NameTypeDescriptionMandatory
volObject nameName 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:
48IBM XIV Storage System User Manual
Command executed successfully
Access Control:
User CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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?
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 CategoryPermissionCondition
Storage administratorAllowedN/A
Storage integration administrator AllowedN/A
52IBM XIV Storage System User Manual
User CategoryPermissionCondition
Application administratorConditionally AllowedThe volume is a snapshot, where
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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:
NameTypeDescriptionMandatory
volObject nameName of the volume to
be renamed.
new_nameObject nameNew 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 Management53
vol_rename vol=DBVolume new_name=DBVolume1
Output:
Command completed successfully
Access Control:
User CategoryPermissionCondition
Storage administratorAllowedN/A
Storage integration administrator AllowedN/A
Application administratorConditionally AllowedThe volume is a snapshot, where
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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.
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.
YN/A
NN/A
NN/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 Management55
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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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
56IBM 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 Management57
Unlocking a Volume
Unlocks a volume, so that it is no longer read-only and can be written to.
vol_unlock vol=VolName
Parameters:
NameTypeDescriptionMandatory
volObject nameThe 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 CategoryPermissionCondition
Storage administratorAllowedN/A
Storage integration administrator AllowedN/A
58IBM XIV Storage System User Manual
User CategoryPermissionCondition
Application administratorConditionally AllowedThe volume is a snapshot, where
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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 Management59
60IBM 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
62IBM 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:
vVolume Management
vConsistency Group Management
vStorage Pool Management
The sections are listed as follows:
vsnapshot_change_priority(Changes a snapshot's deletion priority.)
vsnapshot_create(Creates a snapshot of an existing volume.)
vsnapshot_delete(Deletes a snapshot.)
vsnapshot_duplicate(Duplicates an existing snapshot.)
vsnapshot_format(Formats a snapshot)
vsnapshot_list(Lists snapshot information.)
vsnapshot_restore(Restores a master volume or a snapshot from one of its
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)
existing snapshots
to be overwritten
with the current
volumes content.
NAuto-generated
names.
N1
NN/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 Management65
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
Application administratorConditionally AllowedThe volume is mapped to a host
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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.
66IBM 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:
NameTypeDescriptionMandatory
snapshotObject nameSnapshot 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 CategoryPermissionCondition
Storage administratorAllowedN/A
Storage integration administrator AllowedN/A
Application administratorConditionally AllowedThe master volume of the
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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.
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.
YN/A
NAutomatically
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.
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.
YN/A
NRestore the master
volume.
Chapter 5. Volume Snapshot Management73
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 CategoryPermissionCondition
Storage administratorAllowedN/A
Storage integration administrator AllowedN/A
Application administratorConditionally AllowedBoth target and source are
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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
74IBM 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 Management75
76IBM 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.
vVolume Management
vVolume Snapshot Management
vStorage Pool Management
The sections are listed as follows:
vcg_add_vol(Adds a volume to a Consistency Group.)
vcg_create(Creates a Consistency Group.)
vcg_delete(Deletes a Consistency Group.)
vcg_list(Lists Consistency Groups.)
vcg_remove_vol(Removes a volume from a Consistency Group. )
vcg_rename(Renames Consistency Groups.)
vio_pause(Suspend IO execution on CG)
vio_resume(Resume IO execution on CG previously suspended with resume_io)
vio_pause_list(List CGs io_pause state)
vxcg_create(Creates a Cross-system Consistency Group (XCG) definition.)
vxcg_add_cg(Associates an existing Consistency Group to a Cross-system
Consistency Group definition.)
vxcg_remove_cg(Removes an existing Consistency Group from a Cross-system
Consistency Group definition.)
vxcg_add_remote_system(Adds a remote system name to the Cross-system
Consistency Group definition.)
vxcg_remove_remote_system(Removes a remote system name from a
Cross-system Consistency Group definition.)
vxcg_get_local_cgs(Lists Cross-system Consistency Group definitions along with
contained Consistency Groups.)
vxcg_get_remote_systems(Retrieve the names of remote systems part of the
specified Cross-system Consistency Group.)
vxcg_delete(Deletes a Cross-system Consistency Group (XCG) definition.)
vxcg_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:
NameTypeDescriptionMandatory
cgObject nameName of a Consistency
Group.
volObject nameName 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:
78IBM 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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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 Management79
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.
80IBM 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:
NameTypeDescriptionMandatory
cgObject nameName of the
poolObject nameStorage Pool of the
gpObject nameGrouped 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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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:
NameTypeDescriptionMandatory
cgObject nameName 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:
82IBM XIV Storage System User Manual
Command completed successfully
Access Control:
User CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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:
NameTypeDescriptionMandatoryDefault
cgObject nameName 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
vMirror sync status - indicates the status of the mirroring
– Available values - RPO_OK|RPO_Lagging
Consistency
NAll
Group.
Chapter 6. Consistency Group Management83
vCG role - the role of the peer
– Available values - master|slave
IdNameDefault Position
nameName1
poolPool Name2
gp_basedGP BasedN/A
mirroredMirroredN/A
managedManagedN/A
Example:
cg_list cg=DBgroup
Output:
NamePool Name Mirrored GP Based
DBgroup defaultYesNo
Access Control:
User CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorAllowed
Security administratorDisallowed
Read-only usersAllowed
TechniciansDisallowed
Removing a Volume from a Consistency Group
Removes a volume from a Consistency Group.
cg_remove_vol vol=VolName
Parameters:
NameTypeDescriptionMandatory
volObject nameName 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
84IBM 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 CategoryPermission
Storage administratorAllowed
Storage integration administratorAllowed
Application administratorDisallowed
Security administratorDisallowed
Read-only usersDisallowed
TechniciansDisallowed
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 Management85
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:
NameTypeDescriptionMandatory
cgObject nameThe name of the
new_nameObject nameThe new name of the
This command renames a Consistency Group.
The new name of the Consistency Group must be unique in the system.
86IBM 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.
Application administratorConditionally AllowedAt least one of the volumes in
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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
88IBM XIV Storage System User Manual
Parameters:
NameTypeDescriptionMandatory
token_idPositive integertoken returned by
resume_io command
Y
Resume IO execution on CG previously suspended with resume_io
Application administratorConditionally AllowedAt least one of the volumes in
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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:
NameDescriptionMandatoryDefault
token_idOptional filter value to
show status for specific
token, 0 means
unfiltered
Gives detailed status of pause_io_state of CGs suspended with io_pause
Application administratorConditionally AllowedAt least one of the volumes in
Security administratorDisallowedN/A
Read-only usersAllowedN/A
TechniciansDisallowedN/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.
90IBM XIV Storage System User Manual
Parameters:
NameTypeDescriptionMandatory
xcgObject nameName 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 CategoryPermissionCondition
Storage administratorAllowedN/A
Storage integration administrator AllowedN/A
Application administratorConditionally AllowedAt least one of the volumes in
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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:
NameTypeDescriptionMandatory
xcgObject nameName of a Cross-system
Consistency Group.
Chapter 6. Consistency Group Management
Y
91
NameTypeDescriptionMandatory
cgObject nameName 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 CategoryPermissionCondition
Storage administratorAllowedN/A
Storage integration administrator AllowedN/A
Application administratorConditionally AllowedAt least one of the volumes in
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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.
92IBM 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:
NameTypeDescriptionMandatory
xcgObject nameName of a Cross-system
Consistency Group.
cgObject nameName 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 CategoryPermissionCondition
Storage administratorAllowedN/A
Storage integration administrator AllowedN/A
Application administratorConditionally AllowedAt least one of the volumes in
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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 Management93
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.
Application administratorConditionally AllowedAt least one of the volumes in
Security administratorDisallowedN/A
Read-only usersDisallowedN/A
TechniciansDisallowedN/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.
94IBM XIV Storage System User Manual
Loading...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.