IBM XIV User Manual

Version 11.4.x

IBM XIV Storage System User Manual



GC27-3914-05

The following paragraph does not apply to any country (or region) where such provisions are inconsistent with local law.

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states (or regions) do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you.

Order publications through your IBM representative or the IBM branch office serving your locality.

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

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.

Documentation Conventions

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

Note:

This is an example of a Note.

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

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

–

Example:

vol_rename vol=DBVolume new_name=DBVolume1

–

Output:

Command completed successfully

Abbreviations

OLVM Online Volume Mobility - denotes an IBM

Hyper-Scale Mobility relationship.

Parameter Definitions

Definition Description Syntax

IP Address An address of the form

Existing <object> The name of an object. The

Format string with runtime tokens.

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

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

object must already exist

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

Accessibility features for IBM XIV Storage System

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

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

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

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

spaces.

Accessibility features

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

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

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

v This product uses standard Windows navigation keys.

2 IBM XIV Storage System User Manual

Keyboard navigation

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

IBM XIV and accessibility

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

Chapter 1. Introduction 3

4 IBM XIV Storage System User Manual

Chapter 2. Host and Cluster Management

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

The sections are listed as follows:

v cluster_add_host(Adds a host to a cluster.)

v cluster_create(Creates a new cluster.)

v cluster_delete(Deletes a cluster.)

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

v cluster_remove_host(Removes a host from a cluster.)

v cluster_rename(Renames a cluster.)

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

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

v host_delete(Deletes a host. )

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

v host_list_ports(Lists all the ports of a host)

v host_remove_port(Removes a port from a host.)

v host_rename(Renames a host. )

v host_update(Updates a host definition.)

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

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

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

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

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

v unmap_vol_set_default_idle_time(Sets the default idle time required for a

volume before unmapping it)

v perf_class_create(Creates a Performance Class)

v perf_class_delete(Deletes a Performance Class)

v perf_class_rename(Renames a Performance Class)

v perf_class_list(Lists Performance Classes)

v perf_class_add_host(Adds a host to a Performance Class)

v perf_class_remove_host(Removes a host from its Performance Class)

v perf_class_set_rate(Sets the rate for a Performance Class)

v host_profile_list(lists all host profiles)

v host_profile_set(updates the host profile)

v host_profile_clear(removes the profile of the specified host)

v host_profiler_enable(Enable host profiler functionality)

v host_profiler_disable(Disable host profiler functionality)

The following commands are no longer in use:

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

v host_define_iscsi (This command has been replaced by the host_define

command)

v host_luns_list (This command has been replaced by map_list_luns)

Adding a Host to a Cluster

Adds a host to a cluster.

cluster_add_host cluster=ClusterName host=HostName map=MapName

Parameters:

Name Type Description Mandatory

cluster Object name Name of the cluster to

host Object name Host to be added to the

map Enumeration Override the mapping

This command adds a host to a cluster.

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

contain the host.

cluster.

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

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

Using the map parameter:

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

changed to be the cluster's mapping and type.

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

changed to be the host's mapping and type.

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

mapping and apply on it the cluster mapping as well

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

the host’s mapping.

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

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

6 IBM XIV Storage System User Manual

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v CLUSTER_BAD_NAME

Cluster name does not exist

v HOST_BELONGS_TO_ANOTHER_CLUSTER

Host already belongs to another cluster

v HOST_AND_CLUSTER_HAVE_CONFLICTING_MAPPINGS

Host mapping conflicts with cluster mapping

v HOST_AND_CLUSTER_HAVE_DIFFERENT_MAPPING_TYPE

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

Creating a Cluster

Creates a new cluster.

cluster_create cluster=ClusterName

Parameters:

Name Type Description Mandatory

cluster Object name Name of the cluster to

be created.

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

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v CLUSTER_NAME_EXISTS

v MAX_CLUSTERS_REACHED

Deleting Clusters

Deletes a cluster.

Cluster name already exists

Maximum number of clusters already defined

cluster_delete cluster=ClusterName

Chapter 2. Host and Cluster Management

Parameters:

Name Type Description Mandatory

cluster Object name Cluster to be deleted. Y

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

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_DELETE_ASSIGNED_CLUSTER

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

Listing Clusters

Completion Codes:

v CLUSTER_BAD_NAME

Cluster name does not exist

Lists a specific cluster or all of them.

cluster_list [ cluster=ClusterName ]

Parameters:

Name Type Description Mandatory Default

cluster Object name Cluster to be

listed.

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

Id Name Default Position

name Name 1

hosts Hosts 2

type Type 3

creator Creator 4

user_group User Group 5

N All clusters.

8 IBM XIV Storage System User Manual

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Removing a Host from a Cluster

Removes a host from a cluster.

cluster_remove_host cluster=ClusterName host=HostName

Parameters:

Name Type Description Mandatory

cluster Object name Cluster name. Y

host Object name Host to be removed

from cluster.

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

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v CLUSTER_BAD_NAME

Cluster name does not exist

v HOST_NOT_IN_CLUSTER

Host is not part of specified cluster

Chapter 2. Host and Cluster Management 9

Renaming Clusters

Renames a cluster.

cluster_rename cluster=ClusterName new_name=Name

Parameters:

Name Type Description Mandatory

cluster Object name Cluster to be renamed. Y

new_name Object name New name of cluster. Y

This command renames the specified cluster.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v CLUSTER_BAD_NAME

Cluster name does not exist

v CLUSTER_NAME_EXISTS

Cluster name already exists

Adding a Port to a Host

Adds a port address to a host.

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

Parameters:

Name Type Description Mandatory

host Object name The host name. Y

fcaddress N/A FC address of the

iscsi_name iSCSI initiator name iSCSI initiator name of

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

added port.

N the newly added port.

10 IBM XIV Storage System User Manual

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

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v HOST_PORT_EXISTS

Host with this port ID already defined

v ISCSI_HOST_ILLEGAL_PORT_NAME

Port name for iSCSI Host is illegal

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

v MAX_PORTS_REACHED

Maximum number of ports already defined in the system

v TARGET_PORT_BAD_ADDRESS

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

v PORT_EXISTS

Port is already defined

v OLVM_LINK_IS_NOT_UP

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

v REMOTE_MAX_VIRTUAL_HOSTS_REACHED

Maximum number of remote virtual hosts already defined

Defining a New Host

Defines a new host to connect to the XIV system.

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

Parameters:

Name Type Description Mandatory Default

host Object name Name of host to be

cluster Object name Name of cluster to

created.

contain host.

Y N/A

N No cluster.

Chapter 2. Host and Cluster Management

Name Type Description Mandatory Default

iscsi_ chap_name

iscsi_ chap_ secret

String The host's CHAP

name identifier

String Password of

initiator used to authenticate to XIV when CHAP is enabled

N [None]

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

Note:

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

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

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

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

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

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

treated as a 6 bit equivalent length

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

treated as a 4 bit equivalent length

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

entered is treated as a 8 bit equivalent length

Example:

host_define host=server1

Output:

Command executed successfully.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

12 IBM XIV Storage System User Manual

Deleting a Host

User Category Permission

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ISCSI_CHAP_NAME_AND_SECRET_NOT_UNIQUE

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

Completion Codes:

v HOST_NAME_EXISTS

Host name already exists

v MAX_HOSTS_REACHED

Maximum number of hosts already defined

v CLUSTER_BAD_NAME

Cluster name does not exist

Deletes a host.

host_delete host=HostName

Parameters:

Name Type Description Mandatory

host Object name The host name. Y

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

Example:

host_delete host=mailserver

Output:

Command completed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Chapter 2. Host and Cluster Management

Listing Hosts

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_DELETE_HOST

Are you sure you want to delete host Host?

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

Lists a specific host or all hosts.

host_list [ host=HostName ] [ perf_class=perfClassName ]

Parameters:

Name Type Description Mandatory Default

host Object name The host name. N All hosts.

perf_class Object name Name of a

Performance Class

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

N no filter.

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

The list contains the following comma separated information:

v Port addresses

v Containing cluster, if one exists

v Associated users and user groups

Example:

host_list host=mailserver

Output:

Name Type FC Ports iSCSI Ports User Group Cluster

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

Id Name Default Position

name Name 1

type Type 2

fc_ports FC Ports 3

iscsi_ports iSCSI Ports 4

creator Creator N/A

user_group User Group 5

14 IBM XIV Storage System User Manual

Listing Ports

Id Name Default Position

cluster Cluster 6

perf_class Performance Class 7

iSCSI CHAP Name N/A

iscsi_chap_ name

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Lists all the ports of a host

host_list_ports host=HostName

Parameters:

Name Type Description Mandatory

host Object name The host name. Y

This command lists all the ports on a specified host.

Example:

host_list_ports host=tlib_host_pro125_fc0

Output:

Host Type Port name

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

Id Name Default Position

host Host 1

type Type 2

port_name Port Name 3

Access Control:

User Category Permission

Storage administrator Allowed

Chapter 2. Host and Cluster Management

User Category Permission

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Removing a Port from a Host

Removes a port from a host.

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

Parameters:

Name Type Description Mandatory

host Object name The host name. Y

fcaddress N/A FC address of the port

iscsi_name iSCSI initiator name iSCSI initiator name of

to be removed.

N the port to be removed.

This command removes a port from a host.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v PORT_DOES_NOT_BELONG_TO_HOST

Port ID belongs to another host

v HOST_PORT_DOES_NOT_EXIST

Port ID is not defined

v ISCSI_HOST_ILLEGAL_PORT_NAME

Port name for iSCSI Host is illegal

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

v OLVM_LINK_IS_NOT_UP

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

v TARGET_PORT_BAD_ADDRESS

16 IBM XIV Storage System User Manual

v HOST_PORT_EXISTS

v MAX_PORTS_REACHED

v PORT_EXISTS

v REMOTE_MAX_VIRTUAL_HOSTS_REACHED

Renaming a Host

Renames a host.

Parameters:

Name Type Description Mandatory

host Object name The original host name. Y

new_name Object name The new host name.

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

Host with this port ID already defined

Maximum number of ports already defined in the system

Port is already defined

Maximum number of remote virtual hosts already defined

host_rename host=HostName new_name=Name

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

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

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

Example:

host_rename host=server2 new_name=mailserver

Output:

Command completed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Chapter 2. Host and Cluster Management

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v HOST_NAME_EXISTS

Host name already exists

Updating a Host Definition

Updates a host definition.

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

Parameters:

Name Type Description Mandatory Default

host Object name Name that

iscsi_ chap_name

iscsi_ chap_ secret

represents the host to XIV

String The host's CHAP

name identifier

String Password of

initiator used to authenticate to XIV when CHAP is enabled

Y N/A

N [unchanged]

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

v The parameters iscsi_chap_name and iscsi_chap_secret must either be both

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

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

the secret:

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

entered is treated as a 6 bit equivalent length

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

treated as a 4 bit equivalent length

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

entered is treated as a 8 bit equivalent length

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

bits)- the command will fail.

Changing the chap_name and/or chap_secret:

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

the next time the host is connected.

Example:

host_update host iscsi_chap_name iscsi_chap_secret

18 IBM XIV Storage System User Manual

Output:

Command executed successfully.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ISCSI_CHAP_NAME_AND_SECRET_NOT_UNIQUE

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

v ISCSI_CHAP_SECRET_NOT_UNIQUE

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

v ISCSI_CHAP_NAME_NOT_UNIQUE

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

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v ISCSI_CHAP_NAME_EMPTY

CHAP name should be a non-empty string

v ISCSI_CHAP_NAME_TOO_LONG

CHAP name is too long

v ISCSI_CHAP_SECRET_EMPTY

CHAP secret should be a non-empty string

v ISCSI_CHAP_SECRET_BAD_SIZE

CHAP secret should be 12 to 16 bytes long

v ISCSI_CHAP_SECRET_BAD_HEX_FORMAT

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

Mapping a Volume to a Host or Cluster

Maps a volume to a host or a cluster.

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

Chapter 2. Host and Cluster Management

Parameters:

Name Type Description Mandatory Default

host Object name Host name. N N/A

cluster Object name Cluster name. N N/A

vol Object name Volume name. Y N/A

lun Integer LUN identifier. Y N/A

override Boolean Override existing

mapping.

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

The command fails if:

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

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

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

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

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

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

the host.

Nno

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed This volume is a snapshot. The

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

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

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_PERFORM_HOST_SPECIFIC_MAPPING

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

v ARE_YOU_SURE_YOU_WANT_TO_MAP_VOLUME

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

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

20 IBM XIV Storage System User Manual

v HOST_BELONGS_TO_CLUSTER

Host is part of a cluster

v CLUSTER_BAD_NAME

Cluster name does not exist

v VOLUME_BAD_NAME

Volume name does not exist

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v VOLUME_ALREADY_ASSIGNED

Mapping conflict: volume is already assigned

v LUN_ALREADY_IN_USE

Mapping conflict: LUN is already in use

v EXT_LUN_ILLEGAL

LUN is out of range or does not exist

v VOLUME_HAS_HOST_SPECIFIC_MAPPING

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

v LUN_HAS_HOST_SPECIFIC_MAPPING

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

v VOLUME_IS_NON_PROXY_OLVM_DESTINATION

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

v ISCSI_HOST_ILLEGAL_PORT_NAME

Port name for iSCSI Host is illegal

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

v MAX_PORTS_REACHED

Maximum number of ports already defined in the system

v OLVM_LINK_IS_NOT_UP

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

v HOST_PORT_EXISTS

Host with this port ID already defined

v REMOTE_MAX_VIRTUAL_HOSTS_REACHED

Maximum number of remote virtual hosts already defined

Listing the Mapping of Volumes to Hosts or Clusters

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

mapping_list [ host=HostName | cluster=ClusterName ]

Parameters:

Name Type Description Mandatory

host Object name Host name. N

cluster Object name Cluster name. N

Chapter 2. Host and Cluster Management

Id Name Default Position

lun LUN 1

volume Volume 2

proxy Proxy 3

size Size 4

master Master 5

serial Serial Number 6

locked Locked 7

host Host 8

Example:

e mapping_list host=tlib_host_lsihost034_fc10000006072d0190

Output:

LUN Volume Size Master Serial Locked

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

Number

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v CLUSTER_BAD_NAME

Cluster name does not exist

v TOO_MANY_MAPPINGS

There are too many mappings to display

22 IBM XIV Storage System User Manual

Setting the Special Type of Hosts or Clusters

Sets the special type of a host or a cluster.

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

Parameters:

Name Type Description Mandatory

host Object name Host name. N

cluster Object name Cluster name. N

type Enumeration Special map type. Y

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

Example:

special_type_set host=tlib_host_pro26_fc0 type=zvm

Output:

Command executed successfully.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v HOST_BELONGS_TO_CLUSTER

Host is part of a cluster

v CLUSTER_BAD_NAME

Cluster name does not exist

Listing Hosts/Cluster to which a Volume is Mapped

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

vol_mapping_list vol=VolName

Chapter 2. Host and Cluster Management

Parameters:

Name Type Description Mandatory

vol Object name Volume name. Y

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

Id Name Default Position

host Host/Cluster 1

type Type 2

lun LUN 3

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

Unmapping a Volume from a Host or Cluster

Unmaps a volume from a host or a cluster.

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

Parameters:

Name Type Description Mandatory Default

host Object name Host name. N N/A

cluster Object name Cluster name. N N/A

vol Object name Volume name. Y N/A

Integer How many

idle_ seconds

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

seconds the volume needs to be idle before unmapping

N-1

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

24 IBM XIV Storage System User Manual

The command fails if the specified host is contained in a cluster. In this case, the unmapping of the host must be performed through the cluster.

The command does not fail when the volume is not mapped to the host/cluster.

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed The volume is a snapshot, where

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v HOST_BELONGS_TO_CLUSTER

Host is part of a cluster

v CLUSTER_BAD_NAME

Cluster name does not exist

v VOLUME_BAD_NAME

Volume name does not exist

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v VOLUME_IS_NON_PROXY_OLVM_DESTINATION

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

v OLVM_LINK_IS_NOT_UP

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

v ISCSI_HOST_ILLEGAL_PORT_NAME

Port name for iSCSI Host is illegal

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

v MAX_PORTS_REACHED

Maximum number of ports already defined in the system

v HOST_PORT_EXISTS

Host with this port ID already defined

v MAPPING_IS_NOT_DEFINED

The requested mapping is not defined

v REMOTE_MAX_VIRTUAL_HOSTS_REACHED

Maximum number of remote virtual hosts already defined

Chapter 2. Host and Cluster Management 25

Set the Default Idle Time for Unmapping a Volume

Sets the default idle time required for a volume before unmapping it

unmap_vol_set_default_idle_time idle_time_seconds=IdleSeconds

Parameters:

Name Type Description Mandatory

Integer How many seconds the

idle_time_ seconds

This command sets the default idle time required for unmapping a volume.

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Disallowed N/A

Application administrator Conditionally Allowed The volume is a snapshot, where

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

volume needs to be idle before unmapping

its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.

Creating a Performance Class

Creates a Performance Class

perf_class_create perf_class=perfClassName

Parameters:

Name Type Description Mandatory

perf_class String Name of a Performance

This command creates a Performance Class. The Performance Class name must be unique. Up to 4 classes can be created.

Example:

perf_class_create perf_class=p1

Class

26 IBM XIV Storage System User Manual

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v PERF_CLASS_EXISTS

Performance Class already exists.

v MAX_PERF_CLASSES_REACHED

Maximum number of Performance Class is already defined.

Deleting a Performance Class

Deletes a Performance Class

perf_class_delete perf_class=perfClassName

Parameters:

Name Type Description Mandatory

perf_class Object name Name of a Performance

Class

This command deletes a Performance Class.

Example:

perf_class_delete perf_class=p1

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_DELETE_A_PERF_CLASS

Are you sure you want to delete Performance Class Performance Class?

Chapter 2. Host and Cluster Management 27

ARE_YOU_SURE_YOU_WANT_TO_DELETE_A_PERF_CLASS_ ASSOCIATED_WITH_ HOSTS

Deleting Performance Class Performance Class will remove the performance limits set for hosts associated with the Performance Class. Are you sure you want to delete Performance Class Performance Class?

Completion Codes:

v PERF_CLASS_BAD_NAME

Performance Class does not exist

Renaming a Performance Class

Renames a Performance Class

perf_class_rename perf_class=perfClassName

new_name=Name

Parameters:

Name Type Description Mandatory

perf_class Object name Existing name of a

Performance Class

new_name String New name for the

Performance Class. Class new name must be unique.

This command renames a Performance Class.

Example:

perf_class_rename perf_class=p1 new_name=perf1

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v PERF_CLASS_EXISTS

Performance Class already exists.

v PERF_CLASS_BAD_NAME

Performance Class does not exist

28 IBM XIV Storage System User Manual

Listing Details on Performance Classes

Lists Performance Classes

perf_class_list [ perf_class=perfClassName ]

Parameters:

Name Type Description Mandatory Default

perf_class String Name of a

Performance Class. If left unspecified all performance classes will be listed.

This command lists details of a specified Performance Class, or all Performance Classes.

Id Name Default Position

name Performance class 1

max_iops Max IO rate(IOPOS) 2

max_bw Max BW rate(MB/s) 3

hosts Hosts 4

N All Performance

classes.

Example:

perf_class_list

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Adding a Host to a Performance Class

Adds a host to a Performance Class

perf_class_add_host perf_class=perfClassName host=HostName

Parameters:

Name Type Description Mandatory

perf_class Object name Name of a Performance

Class

Chapter 2. Host and Cluster Management

Name Type Description Mandatory

host Object name Name of a host that will

be added to the performance class

This command adds a host to a Performance Class. If the host is already associated to another performance class, it is removed from it.

Example:

perf_class_add_host perf_class=p1 host=h1

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v PERF_CLASS_BAD_NAME

Performance Class does not exist

v HOST_BAD_NAME

Host name does not exist

Removing a Host from its Performance Class

Removes a host from its Performance Class

perf_class_remove_host host=HostName

Parameters:

Name Type Description Mandatory

host Object name Name of a host that will

be removed from its Performance Class

This command removes a host from its Performance Class.

Example:

perf_class_remove_host host=h1

30 IBM XIV Storage System User Manual

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v PERF_CLASS_DOES_NOT_CONTAIN_ANY_HOSTS

Performance Class is already empty

Setting the Rate for a Performance Class

Sets the rate for a Performance Class

perf_class_set_rate perf_class=perfClassName [ max_io_rate=iops ] [ max_bw_rate=bw ]

Parameters:

Name Type Description Mandatory Default

perf_class Object name Name of a

Positive integer Specifies the

max_io_ rate

Positive integer Specifies the

max_bw_ rate

Performance Class

Performance Class maximum rate in IOPS per interface (IOPS). The max setting allowed is 100,000. If zero is specified, the IOPS rate will not be limited.

Performance Class maximum rate in bandwidth per interface (Mbps). The max setting allowed is 10,000. If zero is specified, the bandwidth rate will not be limited.

This command sets the rate for a Performance Class. The specified rate is applied for each interface module. Either max_io_rate, max_bw_rate or both attributes must be set.

Y N/A

N Keep unchanged.

Example:

Chapter 2. Host and Cluster Management 31

perf_class_set_rate perf_class=p1 max_io_rate=1000

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v PERF_CLASS_BAD_NAME

Performance Class does not exist

v PERF_CLASS_INVALID_RATE

The rate set for the Performance Class is invalid

Listing Host Profiles

lists all host profiles

host_profile_list [ host=HostName ]

Parameters:

Name Type Description Mandatory Default

host Object name Name of a specific

Host to list its profile

Lists all Host Profiles or a specific one.

Id Name Default Position

host_name Host Name 1

update_time Update Time 2

profile Profile 3

Example:

xcli -u -c XIV1 host_profile_list host

Output:

N >All Host Profiles.

Host Name Update Time Profile

---------------------------- --------------------- ----------------------host1 2012-05-09 22:54:36 Windows 7

32 IBM XIV Storage System User Manual

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Allowed

Updates the Host Profile

updates the host profile

host_profile_set profile_value=Profile

Parameters:

Name Type Description Mandatory

profile_ value

String The host profile value

length up to 1024 characters

updates the host profile

Example:

xcli -u -c XIV1 host_profile_set profile_value

Access Control:

User Category Permission

Storage administrator Disallowed

Storage integration administrator Disallowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v HOST_PROFILE_UPDATE_TOO_FREQUENT

Host Profile has been set too often.

Troubleshooting: Try again after the minimal update interval time

v HOST_BAD_NAME

Host name does not exist

v MAX_HOST_PROFILES_REACHED

Maximum number of host profiles already defined

v HOST_PROFILER_DISABLED

Host profiler disabled

Chapter 2. Host and Cluster Management 33

Removes the Profile of the Specified Host

removes the profile of the specified host

host_profile_clear host=HostName

Parameters:

Name Type Description Mandatory

host Object name The host name. Y

removes the profile of the specified host

Example:

xcli -u -c XIV1 host_profile_clear host

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Allowed

Completion Codes:

v HOST_BAD_NAME

Host name does not exist

v HOST_PROFILE_DOES_NOT_EXIST

No profile defined for the requested host

Enable Host Profiler Functionality

Enable host profiler functionality

host_profiler_enable

Enable host profiler functionality

Example:

xcli -u -c XIV1 host_profiler_enable

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

34 IBM XIV Storage System User Manual

User Category Permission

Application administrator Allowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Disable Host Profiler Functionality

Disable host profiler functionality

host_profiler_disable

Disable host profiler functionality

Example:

xcli -u -c XIV1 host_profiler_disable

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Chapter 2. Host and Cluster Management

36 IBM XIV Storage System User Manual

Chapter 3. Volume Management

The following sections describe the XIV Command Line Interface (XCLI) for volume management. Other commands that are relevant to this topic are: Listing Volumes, Renaming a Volume, Moving a Volume between Storage Pools .

See also:

v Volume Snapshot Management

v Consistency Group Management

v Storage Pool Management

The sections are listed as follows:

v reservation_clear(Clears reservations of a volume.)

v reservation_key_list(Lists reservation keys.)

v reservation_list(Lists volume reservations.)

v vol_by_id(Prints the volume name according to its specified SCSI serial number.

)

v vol_copy(Copies a source volume onto a target volume.)

v vol_create(Creates a new volume.)

v vol_delete(Deletes a volume.)

v vol_format(Formats a volume.)

v vol_list(Lists all volumes or a specific one.)

v vol_lock(Locks a volume so that it is read-only.)

v vol_rename(Renames a volume.)

v vol_resize(Resizes a volume.)

v vol_unlock(Unlocks a volume, so that it is no longer read-only and can be

written to.)

The following commands are no longer in use:

v vol_clear_keys (Command is no longer in use in this version. Supplanted by

new command reservation_clear.)

Clearing Reservations of a Volume

Clears reservations of a volume.

reservation_clear vol=VolName

Parameters:

Name Type Description Mandatory

vol Object name Name of the volume to

Clear reservations of a volume.

Example:

clear reservations of.

reservation_clear vol=Vol1

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

Listing Reservation Keys

Lists reservation keys.

reservation_key_list [ vol=VolName ]

Parameters:

Name Type Description Mandatory Default

vol Object name Name of the

volume to list reservation keys.

Lists reservation keys.

Example:

reservation_key_list vol=Vol2

Output:

Initiator Port Volume Name Reservation Key

------------------ ------------------ ----------------100000062B151C3C vol-dmathies-0a7 2 100000062B151C3C vol-dobratz-23a 3

Id Name Default Position

initiator_port Initiator Port 1

Initiator ISID 2

initiator_ port_isid

vol_name Volume Name 3

reg_key Reservation Key 4

N All volumes.

38 IBM XIV Storage System User Manual

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

Listing Volume Reservations

Lists volume reservations.

reservation_list [ vol=VolName ]

Parameters:

Name Type Description Mandatory Default

vol Object name Name of the

volume to list reservations of.

N All volumes.

Lists volume reservations.

Example:

reservation_list vol=Vol1

Output:

Volume Name Reserving Port Reservation Type Persistent vol1 none none

Reservation Type Persistent Access Type Initiator UID PR Generation

Id Name Description Default Position

name Volume Name N/A 1

reserved_by_ port

reserved_by_ port_isid

reservation_ type

none -1 0

Reserving Port N/A 2

Reserving ISID N/A 3

Reservation Type N/A 4

Chapter 3. Volume Management

Id Name Description Default Position

Persistent Reservation

persistent_ reservation_ type

access_type Persistent Access Type N/A 6

reserving_ initiator_uid

pr_generation PR Generation N/A 8

reservation_ age

Type

Initiator UID uid of reserving host 7

Reservation Age N/A 9

N/A 5

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

Finding a Volume Based on a SCSI Serial Number

Prints the volume name according to its specified SCSI serial number.

vol_by_id id=n

Parameters:

Name Type Description Mandatory

id Positive integer SCSI volume ID. Y

This command prints the volume name according to its specified SCSI serial number.

Id Name Default Position

name Name 1

size Size (GB) 2

size_MiB Size (MiB) N/A

master_name Master Name 3

cg_name Consistency Group 4

pool_name Pool 5

creator Creator 6

40 IBM XIV Storage System User Manual

Id Name Default Position

proxy Proxy N/A

capacity Capacity (blocks) N/A

modified Modified N/A

sg_name Snapshot Group Name N/A

Deletion Priority N/A

delete_ priority

locked Locked N/A

serial Serial Number N/A

snapshot_time Snapshot Creation Time N/A

Master Copy Creation Time N/A

snapshot_time_ on_master

Snapshot Internal Role N/A

snapshot_ internal_role

snapshot_of Snapshot of N/A

sg_snapshot_of Snapshot of Snap Group N/A

wwn WWN N/A

mirrored Mirrored N/A

locked_by_pool Locked by Pool N/A

used_capacity Used Capacity (GB) 7

Used Capacity (MiB) N/A

used_capacity_ MiB

short_lived_io Short Live IO N/A

enable_VAAI VAAI enabled N/A

VAAI disabled by user N/A

user_disabled_ VAAI

Snapshot Format N/A

snapshot_ format

ssd_caching SSD Caching State N/A

Use SSD Caching Default State N/A

use_ssd_ caching_ default

unmap_support Unmap Support N/A

managed Managed N/A

enable_unmap unmap enabled N/A

unmap disabled by user N/A

user_disabled_ unmap

marked Marked N/A

Example:

vol_by_id id=59

Chapter 3. Volume Management

Output:

Name Size (GB) Master Name Consistency Group Pool Creator Used Capacity(GB) volume_1 51 0

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Completion Codes:

v VOLUME_BAD_SERIAL

Copying Volumes

Copies a source volume onto a target volume.

Volume with requested SCSI serial number does not exist

vol_copy vol_src=VolName vol_trg=VolName

Parameters:

Name Type Description Mandatory

vol_src Object name Name of the source

volume from which the data is to be taken.

vol_trg Object name Name of the target

volume to which the data is to be copied.

This command copies a source volume onto a target volume.

All data stored on the target volume is lost and cannot be restored.

This command performs the following as a single atomic action:

v Deletes the target volume.

v Creates a new volume with the same name as the target volume and the same

size as the source volume.

v Instantly copies the source volume data onto the target volume.

All volume-to-host mappings of the target volume remain intact during this process. Except for its size, the target volume retains all of its properties, including its name, ID, lock state, creation time and all other attributes.

Immediately after the completion of the command, the volumes are independent of each other and are valid for any further operations (including deletion).

42 IBM XIV Storage System User Manual

If the target volume is larger then the source volume, excess storage space is freed and returned to the target volume's Storage Pool. If the target volume is smaller than the source volume, all storage space that is needed to support the additional volume's capacity is reserved from the Storage Pool.

The command fails in the following cases:

v The target is not formatted.

v The source volume is larger than the target volume, and there is not enough free

space in the Storage Pool that contains the target for target volume resizing.

v The target volume has a snapshot associated with it or if the target volume is a

snapshot.

v The target volume is locked.

v The target volume is part of any mirroring definitions (either master or slave).

v The source volume is a slave of a synchronous mirroring, and it is currently

inconsistent due to either a re-synchronization or an initialization process.

v There is not enough free space in the Storage Pool that contains the target

In the following example, the -y option suppresses the "ARE_YOU_SURE_YOU_WANT_TO_COPY_VOLUME Y/N" prompt.

The volume can't be copied if it is part of an IBM Hyper-Scale Mobility relation and in Proxy phase.

Example:

vol_copy vol_src=DBVolume vol_trg=DBVolumeCopy

Output:

Command executed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_COPY_VOLUME

Are you sure you want to copy the contents of volume source Volume to volume target Volume?

Completion Codes:

v NOT_ENOUGH_HARD_SPACE

No space to allocate for volume's current usage

v NOT_ENOUGH_SPACE

Chapter 3. Volume Management 43

No space to allocate volume

v SOURCE_VOLUME_BAD_NAME

Source volume name does not exist

v SOURCE_VOLUME_DATA_MIGRATION_UNSYNCHRONIZED

Data Migration has not completed to source volume

v TARGET_VOLUME_BAD_NAME

Target volume name does not exist

v TARGET_VOLUME_LOCKED

Target volume is locked

v TARGET_VOLUME_HAS_MIRROR

Mirror is defined for target volume

v TARGET_VOLUME_HAS_DATA_MIGRATION

Data Migration is defined for target volume

v VOLUME_IS_SNAPSHOT

Operation is not permitted on snapshots

v VOLUME_IDENTICAL

Source and target are the same volume

v VOLUME_HAS_SNAPSHOTS

Volume has snapshots

v VOLUME_IS_NOT_CONSISTENT_SLAVE

Operation not allowed on slave volume that is not consistent.

v TARGET_VOLUME_NOT_FORMATTED

Target volume is not formatted

v SNAPSHOT_IS_FORMATTED

Snapshot is formatted

v VOLUME_TOO_BIG_TO_COPY

Volume is too large to be copied

v TARGET_VOLUME_HAS_OLVM

This target volume is part of an IBM Hyper-Scale Mobility relation.

v VOLUME_IS_OLVM_PROXY

The volume is in an IBM Hyper-Scale Mobility Proxy phase.

Creating a Volume

Creates a new volume.

vol_create vol=VolName < size=GB | size_blocks=BLOCKS > pool=PoolName

Parameters:

Name Type Description Mandatory

vol Object name Volume name. Y

size Positive integer Volume size in GB. N

size_ blocks

44 IBM XIV Storage System User Manual

Positive integer Size in number of

blocks.

Name Type Description Mandatory

pool Object name The name of the Storage

Pool to which the volume belongs.

This command creates a new volume.

The name of the volume must be unique in the system.

Space for the volume is allocated from the specified Storage Pool and the volume belongs to that Storage Pool. Specifying the Storage Pool is mandatory.

When creating a volume, the storage space that is needed to support the volume's capacity is reserved from the soft capacity of the storage Pool for the volume.

The command fails if the reservation cannot be committed.

The volume is logically formatted at creation time, which means that any read operation results in returning all zeros as a response.

The size is the actual "net" storage space, as seen by the user's applications, not including any mirroring or other data protection overhead.

The free space consumed by the volume will be the smallest multiple of 17GB which is bigger than the specified size.

The size can be specified either in gigabytes or in blocks (where each block is 512 bytes). If the size is specified in blocks, volumes are created in the exact size specified. If the size is specified in gigabytes, the actual volume size is rounded up to the nearest 17GB multiple (making the actual size identical to the free space consumed by the volume, as described above). This rounding up prevents a situation where storage space is not fully utilized because of a gap between the free space used and the space available to the application. The size specified in blocks is exact.

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

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v VOLUME_CANNOT_HAVE_ZERO_SIZE

Volume size cannot be zero

v POOL_DOES_NOT_EXIST

Storage Pool does not exist

v VOLUME_EXISTS

Volume name already exists

v VOLUME_BAD_PREFIX

Volume name has a reserved prefix

v NOT_ENOUGH_SPACE

No space to allocate volume

v MAX_VOLUMES_REACHED

Maximum number of volumes already defined

v ELECTRONIC_LICENSE_NOT_APPROVED

Operation blocked until Electronic license approval

Troubleshooting: Please retrieve Electronic license version and accept it

v VOLUME_SIZE_ABOVE_LIMIT

Volume size specified is above limit

v INVALID_SLICE_OFFSET

Slice number out of range

v ENCRYPTION_IN_PROGRESS

System is in the process of changing encryption activation state

Deleting a Volume

Deletes a volume.

vol_delete vol=VolName

Parameters:

Name Type Description Mandatory

vol Object name Name of the volume to

This command deletes a volume. All data stored on the volume is lost and cannot be restored.

46 IBM XIV Storage System User Manual

delete.

This command cannot be applied to a snapshot. To delete a snapshot, use Deleting a Snapshot.

All storage space allocated (or reserved) for the volume is freed and returned to the volume's Storage Pool.

The volume is removed from all LUN Maps that contain a mapping of the volume.

This command deletes all snapshots associated with this volume. Even snapshots that are part of a Snapshot Group (this can happen when the volume was in a Consistency Group and was removed from it prior to the deletion).

This command cannot be applied to a volume that is part of a Consistency Group or to a volume that is mapped to a host or cluster.

The command succeeds regardless of the volume's lock state.

Example:

vol_delete vol=DBVolumeCopy

Output:

Command completed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_DELETE_VOLUME

Are you sure you want to delete volume Volume?

v ARE_YOU_SURE_YOU_WANT_TO_DELETE_VOLUME_WITH_SNAPSHOTS

Volume Volume has snapshots! Are you sure you want to delete this volume AND all its snapshots?

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v VOLUME_HAS_MIRROR

Mirror is defined for this volume

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

v SNAPSHOT_IS_INTERNAL

Chapter 3. Volume Management 47

Internal snapshots cannot be mapped, modified or deleted.

v VOLUME_BELONGS_TO_CG

Volume belongs to a Consistency Group

v VOLUME_IS_MAPPED

Volume that is mapped to a host cannot be deleted

v VOLUME_HAS_MAPPED_SNAPSHOT

Volume which has a snapshot that is mapped to a host cannot be deleted

v SNAPSHOT_HAS_ACTIVE_SYNC_JOB

Snapshot is currently a target of an active sync job

Troubleshooting: Please wait for sync job to complete

v SNAPSHOT_IS_CONSISTENT_ELCS

If a mirrored volume is not consistent then its ELCS is protected and cannot be deleted.

v VOLUME_HAS_OLVM

IBM Hyper-Scale Mobility relation is defined for this volume

v VOLUME_IS_OLVM_PROXY

The volume is in an IBM Hyper-Scale Mobility Proxy phase.

Formatting a Volume

Formats a volume.

vol_format vol=VolName

Parameters:

Name Type Description Mandatory

vol Object name Name of the volume to

be formatted.

This command formats a volume. A formatted volume returns zeros as a response to any read command.

All data stored on the volume is lost and cannot be restored.

The formatting of the volume is done logically and no data is actually written to the physical storage space allocated for the volume. This allows the command to complete instantly.

The volume's lock state must be unlocked when the command is issued.

This command fails if the volume has snapshots associated with it, or if the volume is a snapshot, or if the volume is part of any mirroring or Data Migration definition.

Example:

vol_format vol=DBVolume

Output:

48 IBM XIV Storage System User Manual

Command executed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_FORMAT_VOLUME

Volume Volume may contain data. Formatting will cause data loss. Are you sure you want to format volume Volume?

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v VOLUME_HAS_SNAPSHOTS

Volume has snapshots

v VOLUME_IS_SNAPSHOT

Operation is not permitted on snapshots

v VOLUME_LOCKED

Volume is locked

v VOLUME_HAS_MIRROR

Mirror is defined for this volume

v VOLUME_HAS_DATA_MIGRATION

Data Migration is defined for this volume

Listing Volumes

Lists all volumes or a specific one.

vol_list [ vol=VolName | pool=PoolName | cg=cgName ] [ show_proxy=<yes|no> ]

Parameters:

Name Type Description Mandatory Default

vol Object name Name of a specific

pool Object name Name of a specific

volume to be listed.

Pool whose volumes are to be listed.

N All volumes.

N Volumes in all

Pools.

Chapter 3. Volume Management

Name Type Description Mandatory Default

cg Object name List all the

volumes in this Consistency Group.

show_proxy Boolean Returns data on

proxy volumes (volumes in Proxy State) as well

N All Consistency

Groups.

NNo

This command lists volumes according to:

v Volume name

v Pool

v Consistency Group

If no parameter is indicated, the command lists all available volumes. In addition, the command indicates whether the volume is mirrored.

This command displays the following VAAI fields (available on the XML output format):

v enable_VAAI

v user_disabled_VAAI

This command displays the following snapshot format field (available on the XML output format):

v snapshot_format

Id Name Default Position

name Name 1

size Size (GB) 2

size_MiB Size (MiB) N/A

master_name Master Name 3

cg_name Consistency Group 4

pool_name Pool 5

creator Creator 6

proxy Proxy N/A

capacity Capacity (blocks) N/A

modified Modified N/A

sg_name Snapshot Group Name N/A

Deletion Priority N/A

delete_ priority

locked Locked N/A

serial Serial Number N/A

snapshot_time Snapshot Creation Time N/A

Master Copy Creation Time N/A

snapshot_time_ on_master

Snapshot Internal Role N/A

snapshot_ internal_role

snapshot_of Snapshot of N/A

50 IBM XIV Storage System User Manual

Id Name Default Position

sg_snapshot_of Snapshot of Snap Group N/A

wwn WWN N/A

mirrored Mirrored N/A

locked_by_pool Locked by Pool N/A

used_capacity Used Capacity (GB) 7

Used Capacity (MiB) N/A

used_capacity_ MiB

short_lived_io Short Live IO N/A

enable_VAAI VAAI enabled N/A

VAAI disabled by user N/A

user_disabled_ VAAI

Snapshot Format N/A

snapshot_ format

ssd_caching SSD Caching State N/A

Use SSD Caching Default State N/A

use_ssd_ caching_ default

unmap_support Unmap Support N/A

managed Managed N/A

enable_unmap unmap enabled N/A

unmap disabled by user N/A

user_disabled_ unmap

marked Marked N/A

Example:

vol_list

Output:

Name Size (GB) Master Name Pool Creator Used Capacity (GB) DBLog 3006 MainPool admin 0 Dev 2010 MainPool admin 0 Marketing 1013 MainPool admin 0 Dev.snapshot_00001 2010 Dev MainPool admin Dev.snapshot_00002 2010 Dev MainPool admin Dev.snapshot_00003 2010 Dev MainPool admin

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Allowed

Read-only users Allowed

Chapter 3. Volume Management

User Category Permission

Technicians Disallowed

Locking a Volume

Locks a volume so that it is read-only.

vol_lock vol=VolName

Parameters:

Name Type Description Mandatory

vol Object name Name of the volume to

This command locks a volume so that hosts cannot write to it.

A volume that is locked is write-protected, so that hosts can read the data stored on it, but cannot change it. In addition, a locked volume cannot be formatted or resized. In general, locking a volume prevents any operation (other than deletion) that changes the volume's image.

This command succeeds when the volume's lock state is already set to the one the user is trying to apply, while leaving it in the same lock state.

lock.

The lock states of master volumes are set to unlocked when they are created.

The lock states of snapshots are set to locked when they are created.

In addition to the lock state, snapshots also have a modification state. The modification state is a read-only state (which cannot be changed by the user explicitly) and it is initially set to unmodified when the snapshot is created. The first time a snapshot lock state is set to unlocked, the modification state of the snapshot is changed to modified, and it is never changed thereafter.

If applied on a volume that is part of an IBM Hyper-Scale Mobility relation, the command has to be acknowledged by both source and destination volumes. Otherwise, a completion code is returned (see below).

Example:

vol_lock vol=DBVolume

Output:

Command executed successfully.

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

52 IBM XIV Storage System User Manual

User Category Permission Condition

Application administrator Conditionally Allowed The volume is a snapshot, where

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

Completion Codes:

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v VOLUME_BAD_NAME

Volume name does not exist

v VOLUME_IS_SLAVE

Volume is defined as a slave volume

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

Renaming a Volume

its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.

Renames a volume.

vol_rename vol=VolName new_name=Name

Parameters:

Name Type Description Mandatory

vol Object name Name of the volume to

be renamed.

new_name Object name New volume name. Y

This command renames a volume.

The new name of the volume must be unique in the system.

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

This command succeeds regardless of the volume's lock state.

Renaming a snapshot does not change the name of its master volume. Renaming a master volume does not change the names of its associated snapshots.

Example:

Chapter 3. Volume Management 53

vol_rename vol=DBVolume new_name=DBVolume1

Output:

Command completed successfully

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed The volume is a snapshot, where

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v VOLUME_EXISTS

Volume name already exists

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

v VOLUME_BAD_PREFIX

Volume name has a reserved prefix

v SNAPSHOT_IS_CONSISTENT_ELCS

If a mirrored volume is not consistent then its ELCS is protected and cannot be deleted.

v OLVM_ERROR

IBM Hyper-Scale Mobility error.

v COMMAND_NOT_SUPPORTED_FOR_OLVM_VOLUMES

This command is not supported for IBM Hyper-Scale Mobility volumes.

Resizing a Volume

Resizes a volume.

vol_resize vol=VolName < size=GB | size_blocks=BLOCKS > [ shrink_volume=<yes|no> ] [ force_on_inactive_mirror=<yes|no> ]

54 IBM XIV Storage System User Manual

Parameters:

Name Type Description Mandatory Default

vol Object name The name of the

size N/A The new volume

N/A New size of

size_ blocks

Boolean Must be specified

shrink_ volume

Boolean The parameter is

force_on_ inactive_ mirror

volume to be resized.

size.

volumes in number of blocks.

as yes if the new size is smaller than the current size.

required for a successful resize of a volume if (1) the volume is mirrored, (2) the volume is a Master, and (3) the mirror has been deactivated by the system following a previously issued resize command that failed to successfully complete due to a communication error.

Y N/A

N N/A

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

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

bytes.

bytes, but the

If the new size equals the current size, the command will succeed without changes to the volume.

The volume's address space is extended at its end to reflect the increased size, and the additional capacity is logically formatted (that is, zeros are returned for all read commands).

When resizing a regular volume (not a writable snapshot), all storage space that is needed to support the additional volume's capacity is reserved (static allocation). This guarantees the functionality and integrity of the volume, regardless of the resource levels of the volume's Storage Pool. The command fails if this reservation cannot be committed.

The volume's lock state must be unlocked when the command is issued, or otherwise the command fails.

v Resizing a master volume does not change the size of its associated snapshots.

Chapter 3. Volume Management 55

v These snapshots can still be used to restore their individual master volumes.

v The same goes for resizing a snapshot: it does not change the size of its master

volume.

In the following example, the -y option suppresses the "ARE_YOU_SURE_YOU_WANT_TO_ENLARGE_VOLUME Y/N" prompt.

force_on_inactive_mirror

v This parameter enables to force the resizing of a mirror peer even if mirroring is

inactive (this could happen when the mirroring cannot be activated due to size mismatch).

Example:

vol_resize -y vol=DBVolume size=2500

Output:

Command executed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_ENLARGE_VOLUME

Are you sure you want to increase volume size?

v ARE_YOU_SURE_YOU_WANT_TO_REDUCE_VOLUME

Decreasing volume size may cause data loss. Are you sure you want to proceed?

v VOLUME_WILL_CROSS_1TB_SIZE

Many operating systems do not support a resize operation across the 1TB boundary, are you sure?

Troubleshooting: Snapshot backup before resize is advised

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v ILLEGAL_VOLUME_SIZE

Illegal volume size

v NOT_ENOUGH_SPACE

56 IBM XIV Storage System User Manual

No space to allocate volume

v REMOTE_VOLUME_SIZE_ABOVE_LIMIT

Volume size specified is above limit of remote machine

v VOLUME_LOCKED

Volume is locked

v VOLUME_HAS_DATA_MIGRATION

Data Migration is defined for this volume

v CAN_NOT_SHRINK_MAPPED_VOLUME

Mapped volume's size cannot be decreased

v CAN_NOT_SHRINK_VOLUME_WITH_SNAPSHOTS

Size of volume with snapshots cannot be decreased

v CAN_NOT_SHRINK_REMOTE_VOLUME_WITH_SNAPSHOTS

Remote volume has snapshots

v CAN_NOT_SHRINK_MAPPED_REMOTE_VOLUME

Remote volume is mapped

v REMOTE_VOLUME_HAS_DATA_MIGRATION

Data Migration is defined for slave volume

v VOLUME_CANNOT_HAVE_ZERO_SIZE

Volume size cannot be zero

v CAN_NOT_SHRINK_SNAPSHOTS

Size of snapshots cannot be decreased

v CAN_NOT_RESIZE_ASYNC_INTERVAL_VOLUMES

Size of volumes with asynchronous mirroring cannot be changed

v CAN_NOT_SHRINK_VOLUME

Size of volumes cannot be decreased without explicit request

v MIRROR_SIZE_MISMATCH

Slave volume and Master Volume sizes are different

v MIRROR_POSSIBLE_SIZE_MISMATCH

Slave volume and Master Volume sizes may be different. This problem occurs whenever the Master does not receive an acknowledgment from the Slave until the command timed out, or any other unexpected failure.

v VOLUME_SIZE_ABOVE_LIMIT

Volume size specified is above limit

v COMMAND_NOT_SUPPORTED_FOR_OLVM_VOLUMES

This command is not supported for IBM Hyper-Scale Mobility volumes.

v MIRROR_IS_NON_OPERATIONAL

Mirror is non-operational

v VOLUME_IS_SLAVE

Volume is defined as a slave volume

v MIRROR_RETRY_OPERATION

There is an operation in progress on this mirror , please retry your request in a few seconds

Troubleshooting: Please retry the command in a few seconds

Chapter 3. Volume Management 57

Unlocking a Volume

Unlocks a volume, so that it is no longer read-only and can be written to.

vol_unlock vol=VolName

Parameters:

Name Type Description Mandatory

vol Object name The name of the volume

This command unlocks a volume so that it is no longer read-only and can be written into.

A volume that is unlocked is no longer write-protected.

The lock state of regular volumes is set to unlocked when they are created.

The lock state of snapshots is set to locked when they are created.

to unlock.

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.

Example:

vol_unlock vol=DBVolume

Output:

Command executed successfully.

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

58 IBM XIV Storage System User Manual

User Category Permission Condition

Application administrator Conditionally Allowed The volume is a snapshot, where

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

its master volume is mapped to a host or cluster associated with the user and the snapshot was created by an application administrator.

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_UNLOCK_SNAPSHOT

Are you sure you want to unlock snapshot Snapshot?

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v VOLUME_IS_SLAVE

Volume is defined as a slave volume

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

Chapter 3. Volume Management 59

60 IBM XIV Storage System User Manual

Chapter 4. LUN Mapping Management

All the LUN mapping commands are obsolete and were replaced by the clustering commands.

The following commands are no longer in use:

v map_add_vol (The concept of mapping has been replaced by clusters. See

map_volume.)

v map_create (The concept of mapping has been replaced by clusters. See

map_volume and cluster_create.)

v map_delete (The concept of mapping has been replaced by clusters. See

map_volume.)

v map_duplicate (The concept of mapping has been replaced by clusters.)

v map_link_host (The concept of mapping has been replaced by clusters. See

map_volume.)

v map_list (The concept of mapping has been replaced by clusters.)

v map_list_luns (The concept of mapping has been replaced by clusters. See

mapping_list)

v map_remove_vol (The concept of mapping has been replaced by clusters. See

unmap_volume.)

v map_rename (The concept of mapping has been replaced by clusters.)

v map_set_special_type (The concept of mapping has been replaced by clusters.

See special_type_set.)

v map_unlink_host (The concept of mapping has been replaced by clusters.)

62 IBM XIV Storage System User Manual

Chapter 5. Volume Snapshot Management

The following sections describe the XIV Command Line Interface (XCLI) for snapshot management. Other commands that are relevant to this topic are: Listing Volumes, Renaming a Volume, Changing Pool Settings for Snapshots.

See also:

v Volume Management

v Consistency Group Management

v Storage Pool Management

The sections are listed as follows:

v snapshot_change_priority(Changes a snapshot's deletion priority.)

v snapshot_create(Creates a snapshot of an existing volume.)

v snapshot_delete(Deletes a snapshot.)

v snapshot_duplicate(Duplicates an existing snapshot.)

v snapshot_format(Formats a snapshot)

v snapshot_list(Lists snapshot information.)

v snapshot_restore(Restores a master volume or a snapshot from one of its

associated snapshots.)

Changing a Snapshot Deletion Priority

Changes a snapshot's deletion priority.

snapshot_change_priority snapshot=SnapshotName delete_priority=del_value

Parameters:

Name Type Description Mandatory

snapshot Object name Name of the snapshot

Integer The priority for deleting

delete_ priority

This command changes the priority of the deletion of an existing snapshot. The deletion priority determines which snapshots are deleted first when the system runs out of snapshot storage.

The Auto Delete Priority can have a value between 1 and 4, as follows:

v 1 = Is the last to be deleted automatically ("1" is the default set by the system)

v ...

v 4 = Is the first to be deleted automatically

whose delete_priority is

to be changed.

Y the volume's snapshot.

Example:

snapshot_change_priority snapshot=DBVolume.snapshot1 delete_priority=4

Output:

Command completed successfully

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed The master volume of the

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

snapshot is mapped to a host or cluster associated with the user and the snapshot was created by the application administrator.

Completion Codes:

v VOLUME_IS_NOT_A_SNAPSHOT

Operation is permitted only on snapshots

v SNAPSHOT_ILLEGAL_PRIORITY

Illegal snapshot priority; must be an integer between 1 and 4.

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

v VOLUME_BAD_NAME

Volume name does not exist

v SNAPSHOT_IS_CONSISTENT_ELCS

If a mirrored volume is not consistent then its ELCS is protected and cannot be deleted.

Creating a Snapshot

Creates a snapshot of an existing volume.

snapshot_create vol=VolName < [ name=Name ] [ delete_priority=del_value]>|<overwrite=Name >

Parameters:

Name Type Description Mandatory Default

vol Object name Name of the

64 IBM XIV Storage System User Manual

volumes to

Y N/A

snapshot.

Name Type Description Mandatory Default

name Object name Names of the new

Integer The deletion

delete_ priority

overwrite Object name Name of an

snapshots.

priority of the volume's snapshot.

existing snapshots to be overwritten with the current volumes content.

N Auto-generated

names.

N N/A

This command creates a new snapshot for an existing volume, which is referred to as the snapshot's master volume. The snapshot's content is the same as the master volume at the exact point in time that the snapshot was created. The snapshot remains unchanged, although the master volume keeps changing after the snapshot is created. Upon a successful completion of this command, the snapshot is created and assigned a name that can later be used by other commands. The name doesn't have to be new. It could be of an already existing snapshot (in such a case, the already existing snapshot is overridden).

A write operation can be processed at the exact time of the snapshot creation, meaning that the write operation request was sent to the system before the command was executed, while the write was acknowledged after the command was executed. In this case, the content of the snapshot is not deterministic and may either contain the original value before the write operation or the new value after the write operation. In fact, the snapshot's data may even contain a mixture of the two, where some blocks are equal to the volume before the write operation and other blocks are equal to the value after the write operation.

The new snapshot is initially locked for changes.

The snapshot that is created acts like a regular volume, except for the differences described below:

v The snapshot's name is either automatically generated from its master volume's

name or given as a parameter to the command. It can later be changed without altering the snapshot's modification state.

v Upon successful completion of the command, the system assigns a unique SCSI

ID to the snapshot. The creation time of the snapshot is set to the current time and is never changed until the snapshot is deleted.

v The size of the snapshot is the same as its master volume's size, but no storage

space is reserved for the snapshot. This means that the functionality of the snapshot is not guaranteed. When the snapshot's Storage Pool is exhausted, the snapshot may be deleted.

v The snapshot's lock state is initially set to "locked", and as long as it is not

"unlocked", the snapshot remains an exact image of the master volume at creation time and can be the source for a restore operation. The modification state of the snapshot is initially set to "unmodified".

During creation, the snapshot's deletion priority can be set explicitly, or it is automatically set to the default value. The deletion priority determines which snapshots will be deleted first when the Storage Pool runs out of snapshot storage.

Chapter 5. Volume Snapshot Management 65

This may happen due to the redirect-on-write mechanisms which share unchanged data between volumes and their snapshots, as well as between snapshots of the same volume.

The Auto Delete Priority is from the list (1-4), as follows:

v 1 = Is last to be deleted automatically ("1" is the default set by the system)

v ...

v 4 = Is first to be deleted automatically

The snapshot is associated with its master volume and this association cannot be broken or changed as long as the snapshot exists.

The overwrite option copies the current content of the volume into one of its existing snapshots (set as an input argument). The overwritten snapshot keeps the same SCSI serial number and same mapping, so hosts maintain a continuous mapping to the snapshot, without any need for a rescan or similar operation. The overwritten snapshot must be an existing snapshot of the given volume. The overwritten snapshot can't be part of a Snapshot Group.

This command fails when no snapshot space is defined in the Storage Pool the master volume belongs to.

Mirroring limitations:

v This command fails if the volume is a slave of an asynchronous mirroring

coupling (either synchronous or asynchronous).

v This command fails if the volume is a slave of an inconsistent synchronous

coupling.

Example:

snapshot_create vol=DBVolume name=DBVolume.snapshot1 delete_priority=2

Output:

Command executed successfully.

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed The volume is mapped to a host

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

or a cluster associated with the user. If a snapshot overwrite is used, the target snapshot must be one created by a server administrator.

66 IBM XIV Storage System User Manual

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v MAX_VOLUMES_REACHED

Maximum number of volumes already defined

v SNAPSHOT_ILLEGAL_PRIORITY

Illegal snapshot priority; must be an integer between 1 and 4.

v VOLUME_IS_SNAPSHOT

Operation is not permitted on snapshots

v VOLUME_EXISTS

Volume name already exists

v VOLUME_BAD_PREFIX

Volume name has a reserved prefix

v VOLUME_DATA_MIGRATION_UNSYNCHRONIZED

Data Migration has not completed to this volume

v OVERWRITE_SNAPSHOT_BAD_NAME

Snapshot name does not exist

v OVERWRITE_SNAPSHOT_IS_MASTER_VOL

Cannot overwrite Master Volume

This snapshot cannot be overwritten as it is a master volume.

v SNAPSHOT_OVERWRITE_MISMATCH

Specified snapshot is not a snapshot of the specified volume

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v POOL_SNAPSHOT_LIMIT_REACHED

There is not enough space to create a snapshot.

v VOLUME_IS_NOT_CONSISTENT_SLAVE

Operation not allowed on slave volume that is not consistent.

v SNAPSHOT_HAS_ACTIVE_SYNC_JOB

Snapshot is currently a target of an active sync job

Troubleshooting: Please wait for sync job to complete

v TOO_MANY_FAST_SNAPSHOTS_IN_VOLUME

Max number of fast snapshots for this volume already exist

Deleting a Snapshot

Deletes a snapshot.

snapshot_delete snapshot=SnapshotName

Parameters:

Name Type Description Mandatory

snapshot Object name Snapshot to be deleted. Y

Chapter 5. Volume Snapshot Management

This command deletes a snapshot. It cannot be used to delete a master volume, to delete a snapshot which is mapped to a host or cluster, or to delete an internal snapshot of a mirroring.

Example:

snapshot_delete snapshot=DBVolume.snapshot1

Output:

Command completed successfully

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed The master volume of the

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

snapshot is mapped to a host or cluster associated with the user and the snapshot was created by the application administrator.

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v VOLUME_IS_NOT_A_SNAPSHOT

Operation is permitted only on snapshots

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

v SNAPSHOT_IS_MAPPED

Snapshot that is mapped to a host cannot be deleted

v SNAPSHOT_HAS_ACTIVE_SYNC_JOB

Snapshot is currently a target of an active sync job

Troubleshooting: Please wait for sync job to complete

v SNAPSHOT_IS_CONSISTENT_ELCS

If a mirrored volume is not consistent then its ELCS is protected and cannot be deleted.

Duplicating a Snapshot

Duplicates an existing snapshot.

snapshot_duplicate snapshot=SnapshotName [ name=Name ]

68 IBM XIV Storage System User Manual

Parameters:

Name Type Description Mandatory Default

snapshot Object name The name of the

snapshot to duplicate.

name Object name Name of the new

snapshot to be generated.

This command duplicates an existing snapshot. The newly created snapshot is initially locked for changes and is associated with the master volume of the existing snapshot. The content of the newly created snapshot is identical to the content of the source snapshot.

It is useful to duplicate a snapshot before unlocking it for write operations. The duplicate snapshot can be used as a logical backup of the data in case the write operation caused logical data corruption.

Upon successful completion of the command, a new duplicate snapshot is created.

The duplicated snapshot is identical to the source snapshot. It has the same creation time and behaves as if it was created at the exact same moment that the source snapshot was created from the same master volume.

Y N/A

N Automatically

generated name.

The duplicate snapshot's name is either automatically generated from its master volume's name or provided as a parameter. It can later be changed without altering its modification state.

A snapshot can be duplicated multiple times. A duplicated snapshot can be the source for further duplications.

Example:

snapshot_duplicate snapshot=DBVolume.snapshot1 name=DBVolume.snapshot1.copy

Output:

Command executed successfully.

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed The master volume of the

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

snapshot is mapped to a host or cluster associated with the user and the snapshot was created by the application administrator.

Chapter 5. Volume Snapshot Management

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v MAX_VOLUMES_REACHED

Maximum number of volumes already defined

v VOLUME_IS_NOT_A_SNAPSHOT

Operation is permitted only on snapshots

v VOLUME_EXISTS

Volume name already exists

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

v VOLUME_BAD_PREFIX

Volume name has a reserved prefix

Formatting a Snapshot

Formats a snapshot

snapshot_format snapshot=SnapshotName

Parameters:

Name Type Description Mandatory

snapshot Object name The snapshot to be

formatted.

This command deletes the content of a snapshot while maintaining its mapping to the host. The format operation results with the following:

v The formatted snapshot is read-only

v The format operation has no impact on performance

v The formatted snapshot does not consume space

v Reading from the formatted snapshot always returns zeroes

v It can be overridden

v It can be deleted

v Its deletion priority can be changed

Example:

snapshot_format snapshot

Output:

Command executed successfully.

Access Control:

User Category Permission

Storage administrator Allowed

70 IBM XIV Storage System User Manual

User Category Permission

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

v SNAPSHOT_HAS_ACTIVE_SYNC_JOB

Snapshot is currently a target of an active sync job

Troubleshooting: Please wait for sync job to complete

v VOLUME_BAD_NAME

Volume name does not exist

v SNAPSHOT_IS_INTERNAL

Internal snapshots cannot be mapped, modified or deleted.

v MAX_VOLUMES_REACHED

Maximum number of volumes already defined

v SNAPSHOT_IS_FORMATTED

Snapshot is formatted

v ELCS_CANNOT_BE_FORMATTED

The snapshot is an ELCS and cannot be formatted.

v VOLUME_IS_NOT_A_SNAPSHOT

Operation is permitted only on snapshots

Listing Snapshot Information

Lists snapshot information.

snapshot_list vol=VolName

Parameters:

Name Type Description Mandatory

vol Object name List of all the snapshots

This command lists snapshot information for all the snapshots of a specified volume.

This command displays the following VAAI fields (available on the XML output format):

v enable_VAAI

v user_disabled_VAAI

This command displays the following snapshot format field (available on the XML output format):

of this volume.

Chapter 5. Volume Snapshot Management 71

v snapshot_format

Id Name Default Position

name Name 1

size Size (GB) 2

size_MiB Size (MiB) N/A

master_name Master Name 3

cg_name Consistency Group 4

pool_name Pool 5

creator Creator 6

proxy Proxy N/A

capacity Capacity (blocks) N/A

modified Modified N/A

sg_name Snapshot Group Name N/A

Deletion Priority N/A

delete_ priority

locked Locked N/A

serial Serial Number N/A

snapshot_time Snapshot Creation Time N/A

Master Copy Creation Time N/A

snapshot_time_ on_master

Snapshot Internal Role N/A

snapshot_ internal_role

snapshot_of Snapshot of N/A

sg_snapshot_of Snapshot of Snap Group N/A

wwn WWN N/A

mirrored Mirrored N/A

locked_by_pool Locked by Pool N/A

used_capacity Used Capacity (GB) 7

Used Capacity (MiB) N/A

used_capacity_ MiB

short_lived_io Short Live IO N/A

enable_VAAI VAAI enabled N/A

VAAI disabled by user N/A

user_disabled_ VAAI

Snapshot Format N/A

snapshot_ format

ssd_caching SSD Caching State N/A

Use SSD Caching Default State N/A

use_ssd_ caching_ default

unmap_support Unmap Support N/A

managed Managed N/A

enable_unmap unmap enabled N/A

72 IBM XIV Storage System User Manual

Id Name Default Position

unmap disabled by user N/A

user_disabled_ unmap

marked Marked N/A

Example:

snapshot_list vol=DBVolume

Output:

Name Size (GB) Master Name Consistency Group Pool DBVolume.sp1 2508 DBVolume default DBVolume.sp1.copy 2508 DBVolume default

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Restoring a Volume from a Snapshot

Restores a master volume or a snapshot from one of its associated snapshots.

snapshot_restore snapshot=SnapshotName [ target_snapshot=SnapshotName ]

Parameters:

Name Type Description Mandatory Default

snapshot Object name Name of the

Object name Snapshot to be

target_ snapshot

This command restores the data of a master volume from one of its associated snapshots.

Issuing a restore command logically copies the data of the source snapshot onto its volume. The volume's data is therefore restored to the state that it was at the time that the snapshot was created. If the volume was resized after the snapshot was created, the restore operation resizes the volume back to its original size.

snapshot with which to restore its master volume, or snapshot.

restored.

Y N/A

N Restore the master

volume.

Chapter 5. Volume Snapshot Management 73

All the snapshots associated with the volume are left unchanged during a restore operation.

It is possible to snapshot the volume before restoring it, so that the generated snapshot can be used and the data is not lost.

It is possible to restore another snapshot (the target snapshot) from the source snapshot. The target snapshot must be a snapshot of the same volume as the source snapshot. The target snapshot's content and size will be identical to the source snapshot's content and size. The target snapshot's lock/unlock status will remain as it was.

Restoring a mirrored volume:

v Delete the mirror

v Restore the volume

v Re-establish the mirror

Note:

It is impossible to restore a volume while it is mirrored.

Example:

snapshot_restore snapshot=DBVolume.snapshot1

Output:

Command completed successfully.

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed Both target and source are

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

snapshots of the same master volume. This master volume is mapped to a host or cluster associated with the user, and the target snapshot was created by an application administrator.

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_RESTORE_SNAPSHOT

Are you sure you want to restore the volume from snapshot Snapshot?

Completion Codes:

v VOLUME_HAS_DATA_MIGRATION

Data Migration is defined for this volume

74 IBM XIV Storage System User Manual

v VOLUME_BAD_NAME

Volume name does not exist

v VOLUME_IS_NOT_A_SNAPSHOT

Operation is permitted only on snapshots

v NOT_ENOUGH_SPACE

No space to allocate volume

v SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Snapshot is part of a Snapshot Group

v VOLUME_HAS_MIRROR

Mirror is defined for this volume

v VOLUME_LOCKED

Volume is locked

v SNAPSHOTS_BELONG_TO_DIFFERENT_MASTERS

Target snapshot and source snapshot should be snapshots of the same volume

v TARGET_SNAPSHOT_BAD_NAME

Target snapshot name does not exist

v TARGET_SNAPSHOT_IS_PART_OF_SNAPSHOT_GROUP

Target snapshot is part of a Snapshot Group

v TARGET_SNAPSHOT_IS_MASTER

Target snapshot is a master volume

v TARGET_SNAPSHOT_SAME_AS_SNAPSHOT

Source snapshot cannot be the target snapshot

v TARGET_SNAPSHOT_HAS_ACTIVE_SYNC_JOB

Traget snapshot is currently a target of an active sync job

Troubleshooting: Please wait for sync job to complete

Chapter 5. Volume Snapshot Management 75

76 IBM XIV Storage System User Manual

Chapter 6. Consistency Group Management

The following sections describe the XIV Command Line Interface (XCLI) for Consistency Group management. Other commands that are relevant to this topic are: Snapshotting a Consistency Group, Moving a Volume between Storage Pools , Moving Consistency Groups between Storage Pools or or Grouped Pools.

v Volume Management

v Volume Snapshot Management

v Storage Pool Management

The sections are listed as follows:

v cg_add_vol(Adds a volume to a Consistency Group.)

v cg_create(Creates a Consistency Group.)

v cg_delete(Deletes a Consistency Group.)

v cg_list(Lists Consistency Groups.)

v cg_remove_vol(Removes a volume from a Consistency Group. )

v cg_rename(Renames Consistency Groups.)

v io_pause(Suspend IO execution on CG)

v io_resume(Resume IO execution on CG previously suspended with resume_io)

v io_pause_list(List CGs io_pause state)

v xcg_create(Creates a Cross-system Consistency Group (XCG) definition.)

v xcg_add_cg(Associates an existing Consistency Group to a Cross-system

Consistency Group definition.)

v xcg_remove_cg(Removes an existing Consistency Group from a Cross-system

Consistency Group definition.)

v xcg_add_remote_system(Adds a remote system name to the Cross-system

Consistency Group definition.)

v xcg_remove_remote_system(Removes a remote system name from a

Cross-system Consistency Group definition.)

v xcg_get_local_cgs(Lists Cross-system Consistency Group definitions along with

contained Consistency Groups.)

v xcg_get_remote_systems(Retrieve the names of remote systems part of the

specified Cross-system Consistency Group.)

v xcg_delete(Deletes a Cross-system Consistency Group (XCG) definition.)

v xcg_list(Lists Cross-system Consistency Group definitions along with contained

Consistency Groups.)

The following commands are no longer in use:

v cg_restore (The command has been replaced by the snap_group_restore

command)

Adding a Volume to a Consistency Group

Adds a volume to a Consistency Group.

cg_add_vol cg=cgName vol=VolName

Parameters:

Name Type Description Mandatory

cg Object name Name of a Consistency

Group.

vol Object name Name of the volume to

add.

This command adds a volume to a Consistency Group. The Consistency Group is capable of containing up to 128 volumes.

Requirements for successful command completion:

v The volume and Consistency Group have to be associated with the same pool.

v The volume is not already part of a Consistency Group.

v The volume can not be a snapshot.

v The Consistency Group has less than the max number of volumes (see above).

Adding a mirrored volume to a non-mirrored Consistency Group:

v Such an addition always succeeds and the volume will retain its mirroring

settings.

Requirements for successful command completion for a mirrored Consistency Group:

v The command must be issued only on the master Consistency Group.

v The command can not be run during an initialization of the volume or the

Consistency Group.

v The volume does not have any outstanding ad-hoc sync jobs.

v The volume has to be mirrored, and its following mirroring settings must be

identical to those of the Consistency Group: mirroring type (e.g., synchronous), mirroring status, mirroring target, target pool, designation.

v In addition, for a mirrored Consistency Group that is defined as sync_best_effort

(synchronous):

– The synchronization status of both volume and Consistency Group has to be

Synchronized.

v For a mirrored Consistency Group that is defined as async_interval

(asynchronous):

– The volume and Consistency Group must have the following identical

settings and values: schedule, remote schedule, timestamp of the last_replicated snapshot.

– Their both synchronization status is RPO_OK

v The link has to be up.

Adding a mirrored volume to a mirrored Consistency Group will also add the volume's peer to the Consistency Group's peer. Once added, the mirrored volume will be set the RPO of the mirrored Consistency Group.

The mirrored Consistency Group has one sync job for all pertinent mirrored volumes within the Consistency Group.

In case of acknowledgment time out:

78 IBM XIV Storage System User Manual

v Whenever the command is issued on a mirrored CG Master - and the Master

does not receive an acknowledgment from the Slave (until the command timed out or due to any unexpected failure), a completion code is returned (MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH).

If the command CG_ADD_VOLUME is issued on a mirrored CG Master - and the Master does not receive an acknowledgment from the Slave (until the command timed out or due to any unexpected failure), a new completion code will be returned (MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH meaning that the member lists of the mirror Consistency Group peers might not be the same).

If applied on a volume that is part of an IBM Hyper-Scale Mobility relation:

v The command is applicable only to a destination volume

v This destination volume has to be in Proxy state

Otherwise, a completion code is returned (see below).

Example:

cg_add_vol cg=DBGroup vol=DBLog

Output:

Command completed successfully.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v CONS_GROUP_MIRROR_DESIGNATION_MISMATCH

Volume Mirror has different designation than Consistency Group Mirror. Are you sure you want to add that Volume to that CG?

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v CONS_GROUP_BAD_NAME

Consistency Group name does not exist.

v CONS_GROUP_IS_SLAVE

Consistency Group is mirroring slave.

v MAX_VOLUMES_IN_CONS_GROUP_REACHED

The maximum permitted number of volumes per Consistency Group is reached.

Chapter 6. Consistency Group Management 79

Consistency Group contains maximum number of volumes.

v MAX_VOLUMES_IN_REMOTE_CONS_GROUP_REACHED

The maximum permitted number of volumes per the remote Consistency Group is reached.

Remote Consistency Group contains maximum number of volumes.

v MIRROR_HAS_SYNC_JOB

Operation is not permitted on a mirror with active sync jobs

v MIRROR_IS_NOT_SYNCHRONIZED

Mirror is not synchronized

v MIRROR_LAST_SYNC_TIMES_DIFFER

All mirrors should have the same last sync time.

v MIRROR_RETRY_OPERATION

There is an operation in progress on this mirror , please retry your request in a few seconds

Troubleshooting: Please retry the command in a few seconds

v REMOTE_VOLUME_BAD_POOL

Remote volume and remote Consistency Group belong to different Storage Pools

v REMOTE_VOLUME_BELONGS_TO_CONS_GROUP

The remote volume belongs to a Consistency Group.

Remote Volume belongs to a Consistency Group

v TARGET_NOT_CONNECTED

There is currently no connection to the target system

v VOLUME_BAD_POOL

Volume belongs to a different Storage Pool

v VOLUME_BELONGS_TO_CG

Volume belongs to a Consistency Group

v VOLUME_DATA_MIGRATION_UNSYNCHRONIZED

Data Migration has not completed to this volume

v VOLUME_IS_SNAPSHOT

Operation is not permitted on snapshots

v CONS_GROUP_MIRROR_SCHEDULE_MISMATCH

Volumes under Consistency Group Mirror should have the same mirroring schedule.

v CONS_GROUP_MIRROR_TARGET_MISMATCH

Volumes under Consistency Group Mirror should have the same mirroring Target.

v CONS_GROUP_MIRROR_ROLE_MISMATCH

Volumes under Consistency Group Mirror should have the same mirroring role.

v CONS_GROUP_MIRROR_ACTIVATION_MISMATCH

Volumes under Consistency Group Mirror should have the same mirroring activation state.

v REMOTE_CONS_GROUP_MIRROR_SCHEDULE_MISMATCH

Volumes under Consistency Group Mirror in remote machine should have identical mirroring schedule.

v CONS_GROUP_MIRROR_TYPE_MISMATCH

Volumes under Consistency Group Mirror should have the same mirroring type.

80 IBM XIV Storage System User Manual

v MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH

Mirrored CG may contain different volumes on Master and Slave. This problem occurs whenever the cg_add_vol command results with the Master not receiving an acknowledgment from the Slave until the command timed out, or any other unexpected failure.

v REMOTE_CONS_GROUP_APPLICATION_CONSISTENCY_MISMATCH

Application consistency of the volume doesn't match the state of other volumes in the group on the remote machine.

v CONS_GROUP_APPLICATION_CONSISTENCY_MISMATCH

Application consistency of the volume doesn't match the state of other volumes in the group.

v VOLUME_HAS_OLVM

IBM Hyper-Scale Mobility relation is defined for this volume

Creating Consistency Groups

Creates a Consistency Group.

cg_create cg=cgName <pool=PoolName | gp=gpName>

Parameters:

Name Type Description Mandatory

cg Object name Name of the

pool Object name Storage Pool of the

gp Object name Grouped Pool of the

Consistency Group.

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

Output:

Command executed successfully.

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v CONS_GROUP_NAME_EXISTS

Consistency Group name already exists.

v MAX_CONS_GROUPS_REACHED

Maximum number of Consistency Groups already defined.

v POOL_DOES_NOT_EXIST

Storage Pool does not exist

Deleting a Consistency Group

Deletes a Consistency Group.

cg_delete cg=cgName

Parameters:

Name Type Description Mandatory

cg Object name Name of the

This command deletes a Consistency Group.

This command fails if:

v The Consistency Group is not empty (meaning that it still contains volumes).

v The Consistency Group is mirrored (even if empty).

All snapshot groups associated with the Consistency Group are disbanded, meaning that the snapshots contained in these snapshot groups become independent snapshots.

Example:

Consistency Group to

delete.

cg_delete cg=DBvolumes

Output:

82 IBM XIV Storage System User Manual

Command completed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v CONS_GROUP_BAD_NAME

Consistency Group name does not exist.

v CONS_GROUP_NOT_EMPTY

This operation is only allowed on an empty Consistency Group.

v CONS_GROUP_HAS_MIRROR

Consistency Group has mirroring defined for it.

The mirror definition has to be removed.

v CONS_GROUP_BELONGS_TO_XCG

Consistency Group belongs to another Cross Consistency Group.

Listing Consistency Groups

Lists Consistency Groups.

cg_list [ cg=cgName ]

Parameters:

Name Type Description Mandatory Default

cg Object name Name of a

This command lists select details for all Consistency Groups; if a Consistency Group name is specified, it is the only one to be listed.

Listed details include the following:

v Name

v Mirrored CG - indicates whether the Consistency Group is mirrored

– Available values - Yes|No

v GP Based (indicates whether the Consistency Group is based on a Grouped

Pool)

– Values - Yes|No

v Mirror sync status - indicates the status of the mirroring

– Available values - RPO_OK|RPO_Lagging

Consistency

N All

Group.

Chapter 6. Consistency Group Management 83

v CG role - the role of the peer

– Available values - master|slave

Id Name Default Position

name Name 1

pool Pool Name 2

gp_based GP Based N/A

mirrored Mirrored N/A

managed Managed N/A

Example:

cg_list cg=DBgroup

Output:

Name Pool Name Mirrored GP Based DBgroup default Yes No

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Allowed

Security administrator Disallowed

Read-only users Allowed

Technicians Disallowed

Removing a Volume from a Consistency Group

Removes a volume from a Consistency Group.

cg_remove_vol vol=VolName

Parameters:

Name Type Description Mandatory

vol Object name Name of the volume to

be removed.

This command removes a volume from a Consistency Group.

A Consistency Group's name is deduced from the volume name. A unique name is ensured because each volume belongs to only a single Consistency Group. Future snapshot groups that are created from this Consistency Group will not include a snapshot that is associated with the removed volume.

Following the volume removal:

v Corresponding peer volume is removed from the peer Consistency Group

84 IBM XIV Storage System User Manual

– If the Consistency Group is mirrored, the mirroring definition of the removed

volume is retained. The mirroring definition is based on the same settings as the Consistency Group.

v The peer volume is also removed from the peer Consistency Group

v The removed mirrored volume is set the RPO of the mirrored Consistency

Group from which it was removed

v Event is generated

This command succeeds even if the volume is not included in any Consistency Group.

Requirements for a successful command completion:

v The command can be issued only on the master

v The link must be up

v The Consistency Group cannot have ongoing sync jobs

In case of acknowledgment time-out:

v Whenever the command is issued on a mirrored CG Master - and the Master

does not receive an acknowledgment from the Slave (until the command timed out or due to any unexpected failure), a completion code is returned (MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH).

If applied on a volume that is part of an IBM Hyper-Scale Mobility relation:

v The command is applicable only to a destination volume

v This destination volume must be in Proxy state

Otherwise, a completion code is returned.

Example:

cg_remove_vol vol=DBLog

Output:

Command completed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_REMOVE_VOLUME_FROM_

CONS_GROUP

Are you sure you want to remove volume 'Volume' from its Consistency Group?

Chapter 6. Consistency Group Management 85

Completion Codes:

v VOLUME_BAD_NAME

Volume name does not exist

v VOLUME_NOT_IN_CONS_GROUP

Volume does not belong to a Consistency Group

v TARGET_NOT_CONNECTED

There is no connection to the target system

v VOLUME_IS_SNAPSHOT

Operation is not permitted on snapshots

v CONS_GROUP_IS_SLAVE

Consistency Group is mirroring slave.

v MIRROR_RETRY_OPERATION

There is an operation in progress on this mirror , please retry your request in a few seconds

Troubleshooting: Please retry the command in a few seconds

v MIRROR_HAS_SYNC_JOB

Operation is not permitted on a mirror with active sync jobs

v MIRROR_POSSIBLE_CONS_GROUP_MEMBERSHIP_MISMATCH

v VOLUME_IS_NOT_CONSISTENT_SLAVE

Operation not allowed on slave volume that is not consistent.

v SNAPSHOT_HAS_ACTIVE_SYNC_JOB

Snapshot is currently a target of an active sync job

Troubleshooting: Please wait for sync job to complete

v VOLUME_HAS_OLVM

IBM Hyper-Scale Mobility relation is defined for this volume

Renaming Consistency Groups

Renames Consistency Groups.

cg_rename cg=cgName new_name=Name

Parameters:

Name Type Description Mandatory

cg Object name The name of the

new_name Object name The new name of the

This command renames a Consistency Group.

The new name of the Consistency Group must be unique in the system.

86 IBM XIV Storage System User Manual

Consistency Group to

be renamed.

Consistency Group.

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

Example:

cg_rename cg=DBgroup new_name=DBvolumes

Output:

Command completed successfully

Access Control:

User Category Permission

Storage administrator Allowed

Storage integration administrator Allowed

Application administrator Disallowed

Security administrator Disallowed

Read-only users Disallowed

Technicians Disallowed

Completion Codes:

v CONS_GROUP_BAD_NAME

Consistency Group name does not exist.

v CONS_GROUP_NAME_EXISTS

Consistency Group name already exists.

Suspend I/O Execution on Consistency Group

Suspend IO execution on CG

io_pause cg=cgName [ milli_seconds_to_resume=MilliSecondsTimeout ] [ allow_read=AllowRead ]

Parameters:

Name Type Description Mandatory Default

Positive integer Timeout for auto

milli_ seconds_ to_resume

allow_read Boolean Flag controls

cg Object name CG name Y N/A

Suspend I/O execution on Consistency Group with auto-resume timeout

resume, measurement starts when current IOs execution on CG completes

whether to enable read IOs during the io_pause period

N 10000

N yes

It is possible to suspend execution of all I/Os or just writes

Chapter 6. Consistency Group Management 87

Example:

io_pause cg=test_cg milli_seconds_to_resume=10000

Output:

command:

code = "SUCCESS" status = "0" status_str = "Command completed successfully" return:

token_id = "6343971831808"

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed At least one of the volumes in

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.

Completion Codes:

v COMMAND_IS_NOT_VALID_IN_CURRENT_SYSTEM_STATE

The requested command cannot be invoked in the current system state

v PAUSE_IO_TIMEOUT_OUT_OF_RANGE

Timeout parameter is out of range

v TOO_MANY_IO_PAUSE_ISSUED

Too many Pause IOs are in progress

v CONS_GROUP_BAD_NAME

Consistency Group name does not exist.

v CONS_GROUP_IS_SLAVE

Consistency Group is mirroring slave.

v IO_PAUSE_ALREADY_ISSUED_FOR_CONS_GROUP

Volume(s) belonging to the Consistency Group are already paused

Resume I/O Execution

Resume IO execution on CG previously suspended with resume_io

io_resume token_id=Token

88 IBM XIV Storage System User Manual

Parameters:

Name Type Description Mandatory

token_id Positive integer token returned by

resume_io command

Resume IO execution on CG previously suspended with resume_io

Example:

io_resume token_id=6343971831808

Output:

command:

code = "SUCCESS" status = "0" status_str = "Command completed successfully"

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed At least one of the volumes in

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.

Completion Codes:

v CONS_GROUP_IS_NOT_PAUSED

Consistency Group is not paused or auto-resume timeout expired

v CONS_GROUP_DEFINITION_MODIFIED_DURING_IO_PAUSE

Consistency Group definitions changed during pause io period

List Consistency Groups Pause I/O State

List CGs io_pause state

io_pause_list [ token_id=Token ]

Chapter 6. Consistency Group Management

Parameters:

Name Description Mandatory Default

token_id Optional filter value to

show status for specific token, 0 means unfiltered

Gives detailed status of pause_io_state of CGs suspended with io_pause

Example:

io_pause_list

Output:

command:

code = "SUCCESS" status = "0" status_str = "Command completed successfully" return:

stop_io 0:

allow_read = "yes" cg_name = "cg_test" config_changed = "no" inode_list_changed = "no" num_volumes = "1" resume_pending = "no" stop_io_elapsed_time = "4062" timeout = "10000" token = "6343971831808"

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed At least one of the volumes in

Security administrator Disallowed N/A

Read-only users Allowed N/A

Technicians Disallowed N/A

Creates a Cross-System Consistency Group

Creates a Cross-system Consistency Group (XCG) definition.

xcg_create xcg=XcgName

the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.

90 IBM XIV Storage System User Manual

Parameters:

Name Type Description Mandatory

xcg Object name Name of a Cross-system

Consistency Group.

Creates a Cross-system Consistency Group (XCG) definition to which Consistency Groups on different XIV systems may be associated.

Example:

xcg_create xcg=DBbackup

Output:

Command completed successfully

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed At least one of the volumes in

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.

Completion Codes:

v XCG_NAME_EXISTS

Cross Consistency Group name already exists.

v MAX_XCGS_REACHED

Maximum number of Cross Consistency Groups already defined.

Associates an Existing Consistency Group to a Cross-System Consistency Group Definition

Associates an existing Consistency Group to a Cross-system Consistency Group definition.

xcg_add_cg xcg=XcgName cg=cgName

Parameters:

Name Type Description Mandatory

xcg Object name Name of a Cross-system

Consistency Group.

Chapter 6. Consistency Group Management

Name Type Description Mandatory

cg Object name Name of a Consistency

Group.

Associates an existing Consistency Group to a Cross-system Consistency Group definition.

Example:

xcg_add_cg xcg=DBbackup cg=CGbackup

Output:

Command completed successfully

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed At least one of the volumes in

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.

Completion Codes:

v XCG_BAD_NAME

Cross Consistency Group name does not exist.

v MAX_CONS_GROUPS_IN_XCG_REACHED

Cross Consistency Group contains maximum number of cgs.

v CONS_GROUP_IS_SLAVE

Consistency Group is mirroring slave.

v CONS_GROUP_BAD_NAME

Consistency Group name does not exist.

v CONS_GROUP_ALREADY_IN_XCG

Consistency Group already belongs to Cross Consistency Group.

v CONS_GROUP_BELONGS_TO_XCG

Consistency Group belongs to another Cross Consistency Group.

92 IBM XIV Storage System User Manual

Removes an Existing Consistency Group from a Cross-System Consistency Group Definition

Removes an existing Consistency Group from a Cross-system Consistency Group definition.

xcg_remove_cg xcg=XcgName cg=cgName

Parameters:

Name Type Description Mandatory

xcg Object name Name of a Cross-system

Consistency Group.

cg Object name Name of a Consistency

Group.

Removes an existing Consistency Group from a Cross-system Consistency Group definition.

Example:

xcg_remove_cg xcg=DBbackup cg=CGBackup

Output:

Command completed successfully

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed At least one of the volumes in

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.

Warnings:

v ARE_YOU_SURE_YOU_WANT_TO_REMOVE_CONS_GROUP_FROM_XCG

Are you sure you want to remove cons group 'CG' from its cross Consistency Group?

Completion Codes:

v XCG_BAD_NAME

Cross Consistency Group name does not exist.

Chapter 6. Consistency Group Management 93

v CONS_GROUP_BAD_NAME

Consistency Group name does not exist.

v XCG_IS_EMPTY

Consistency Group is empty.

v CONS_GROUP_NOT_IN_XCG

Consistency Group doesnt belong to Cross Consistency Group.

Adds a Remote System Name to the Cross-System Consistency Group Definition

Adds a remote system name to the Cross-system Consistency Group definition.

xcg_add_remote_system xcg=XcgName remote_system=RemoteSystem

Parameters:

Name Type Description Mandatory

xcg Object name Name of a Cross-system

String Name of a remote

remote_ system

Consistency Group.

system.

Adds a remote system name to the Cross-system Consistency Group definition.

Example:

xcg_add_remote_system xcg=DBbackup remote_system=CGbackup

Output:

Command completed successfully

Access Control:

User Category Permission Condition

Storage administrator Allowed N/A

Storage integration administrator Allowed N/A

Application administrator Conditionally Allowed At least one of the volumes in

Security administrator Disallowed N/A

Read-only users Disallowed N/A

Technicians Disallowed N/A

the group is mapped to a host or cluster associated with the user. If a Snapshot Group overwrite is used, then the target Snapshot Group must be one created by a server administrator.

94 IBM XIV Storage System User Manual

IBM XIV User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual