addvdiskcopy

Edit online

Use the addvdiskcopy command to add a copy to an existing volume. In this way, you change a non-mirrored volume into a mirrored volume.On a system with a hyperswap topology, use the addvolumecopy command to convert an existing volume to a HyperSwap® volume by adding a copy at a second site.

Note: The first syntax diagram depicts the addition of a sequential or striped mode volume. The second syntax diagram depicts the addition of an image mode volume.

Syntax

Parameters

-mdiskgrp mdisk_group_id_list | mdisk_group_name_list

(Required) Specifies the storage pools to use to create copies for the volume. You must specify a group for each copy that is being added.

Important: If the MDisk group is from a child pool, the -vtype parameter must be set to striped.

-mirrorwritepriority latency | redundancy

(Optional) Specifies how to configure the mirror write algorithm priority.

Choosing latency means that a copy that is slow to respond to a write input/output (I/O) becomes unsynchronized, and the write I/O completes processing if the other copy successfully writes the data.
Choosing redundancy means that a copy that is slow to respond to a write I/O synchronizes completion of the write I/O with the completion of the slower I/O to maintain synchronization.

-vtype seq | striped | image

(Optional) Specifies the virtualization type for the copy: sequential, striped, or image. The type can be different from the virtualization types for other copies on the volume. The default virtualization type is striped. If you specify the -rsize auto option or the -import option, you must also specify the -vtype image option.

Important: You cannot create an image or sequential mode copy from a child pool or data reduction pools.

-mdisk mdisk_id_list | mdisk_name_list

(Optional) Specifies one or more managed disks (MDisks). For sequential and image mode copies, you must specify a single MDisk that has sufficient free extents. For image mode copies, the MDisk must be in unmanaged mode. For sequential mode copies, the MDisk must be in managed mode.

-syncrate syncrate

(Optional) Specifies the copy synchronization rate. A value of 0 prevents synchronization. For the supported -syncrate values and their corresponding rates, see the table in the command description section. If not specified, the current value is unchanged.

-createsync

(Optional) Suppresses the synchronization of the new volume copy with the primary copy.

Attention: Using this parameter can cause data corruption if the primary copy fails and leaves an unsynchronized secondary copy to provide data. Using this parameter can cause loss of read stability in unwritten areas if the primary copy fails, data is read from the primary copy, and then different data is read from the secondary copy.

Remember: You cannot specify -createsync for a volume that is fast formatting and for a volume with policy-based replication.

-rsize disk_size | disk_size_percentage% | auto

(Optional) Makes the copy thin-provisioned and specifies the real size of the copy. Specify the disk_size | disk_size_percentage value by using an integer, or an integer immediately followed by the percent character (%). The default units for disk_size are megabytes (MB). To specify different units, use the -unit parameter. The auto option creates a volume copy that uses the entire size of the MDisk; if you specify the -rsize auto option, you must also specify the -vtype image option.

-deduplicated

(Optional) Adds a deduplicated volume. If you specify -deduplicated, you must also specify -rsize because it applies only to thin-provisioned or compressed volumes.

Restriction: Data deduplication works only with data reduction storage pools. You can create deduplicated volumes and volume copies in an I/O group only if no compressed volumes or volume copies exist in regular storage pools.

-compressed

(Optional) Add exactly one copy to an existing volume that already has one copy a volume, and enables compression. If you specify the -compressed parameter, you must also specify the -rsize parameter.

Important:

You cannot specify this parameter with the grain_size parameter.
When you specify this parameter with the -import parameter, you must specify the -rsize auto parameter.

-warning disk_size | disk_size_percentage%

(Optional) Generates a warning when the used disk capacity on the thin-provisioned copy first exceeds the specified threshold. You can specify a disk_size integer, which defaults to megabytes (MB) unless the -unit parameter is specified, or you can specify a disk_size%, which is a percentage of the volume size. If -autoexpand is enabled, the default value for -warning parameter is 80% of the volume capacity. If -autoexpand is not enabled, the default value for warning is 80% of the real capacity. To disable warnings, specify 0.

Restriction: Requires that the -rsize parameter also be specified.

-autoexpand

(Optional) Specifies that thin-provisioned copies automatically expand their real capacities by allocating new extents from their storage pool. If the -autoexpand parameter is specified, the -rsize parameter specifies a capacity that is reserved by the copy. It protects the copy from going offline when its storage pool runs out of space by allowing it to consume this reserved space first.

Restriction: Requires that the -rsize parameter also be specified.

-grainsize 32 | 64 | 128 | 256

(Optional) Sets the grain size (KB) for a thin-provisioned volume copy. The grain size value must be 32, 64, 128, or 256 KB. The default is 256 KB.

Restriction: Requires that the -rsize parameter also be specified.

-unit b | kb | mb | gb | tb | pb

(Optional) Specifies the data units for the -rsize and -warning parameters.

-import

(Optional) Imports an image mode disk that contains a thin-provisioned volume into the system. Requires that the -rsize and -vtype image parameters also be specified.

-tier tier0_flash | tier1_flash | tier_enterprise | tier_nearline | tier_scm

(Optional) Specifies the MDisk tier when an image mode copy is added.

tier0_flash: Specifies a tier0_flash hard disk drive or an external MDisk for the newly discovered or external volume.
tier1_flash: Specifies a tier1_flash (or flash drive) hard disk drive or an external MDisk for the newly discovered or external volume.
tier_enterprise: Specifies a tier_enterprise hard disk drive or an external MDisk for the newly discovered or external volume.
tier_nearline: Specifies a tier_nearline hard disk drive or an external MDisk for the newly discovered or external volume.
tier_scm: Specifies a tier_scm hard disk drive or an external MDisk for the newly discovered or external volume.

-easytier on | off

(Optional) Determines whether the IBM® Easy Tier® function can move extents for this volume. If a volume copy is striped and not being migrated, see the settings in the following table:

Table 1. Storage pool Easy Tier settings
Storage pool Easy Tier setting	Number of tiers in the storage pool	Volume copy Easy Tier setting	Volume copy Easy Tier status
Off	One	Off	inactive (see note 1)
Off	One	On	inactive (see note 1)
Off	Two	Off	inactive (see note 1)
Off	Two	On	inactive (see note 1)
Measure	One	Off	measured (see note 2)
Measure	One	On	measured (see note 2)
Measure	Two	Off	measured (see note 2)
Measure	Two	On	measured (see note 2)
Auto	One	Off	measured (see note 2)
Auto	One	On	measured (see note 2)
Auto	Two	Off	balanced (see note 3)
Auto	Two	On	active (see note 4)
On	One	Off	measured (see note 2)
On	One	On	balanced (see note 3)
On	Two	Off	measured (see note 2)
On	Two	On	active (see note 4)
Note When the volume copy status is `inactive`, no IBM Easy Tier functions are enabled for that volume copy. When the volume copy status is `measured`, the IBM Easy Tier function collects usage statistics for volume, but automatic data placement is not active. When the volume copy status is `balanced`, the IBM Easy Tier function enables performance-based pool balancing for that volume copy. When the volume copy status is `active`, the IBM Easy Tier function operates in automatic data placement mode for that volume.

If the volume copy is in image or sequential mode or is being migrated, the volume copy IBM Easy Tier status is measured instead of active.

The default Easy Tier setting for a storage pool is auto, and the default Easy Tier setting for a volume copy is on. If the setting is on, it means that Easy Tier functions except for pool performance balancing are disabled for storage pools with a single tier, and that automatic data placement mode is enabled for all striped volume copies in a storage pool with two or more tiers.

-autodelete

(Optional) Specifies that the primary copy is deleted after the secondary copy is synchronized.

-inconsistentownershipgroup

(Optional) Specifies that inconsistent ownership is permitted for this object.

jvdisk_name | vdisk_id

(Required) Specifies the volume to add the volume copy to, either by ID or by name.

Description

The addvdiskcopy command adds a copy to an existing volume. In this way, a non-mirrored volume is changed into a mirrored volume. Use the mkdiskgrp parameter to specify the storage pools that provide storage for the copy; the lsmdiskgrp command lists the available storage pools and the amount of available storage in each group.

The addvdiskcopy command can be specified with a file system volume, but must be used with the same storage pool for that volume.

Remember: Only compressed copies can be added to file system volumes.

The addvdiskcopy command adds a different volume copy, such as a copy created from an uncompressed to compressed conversion or a compressed to uncompressed conversion.

Restriction: A volume cannot have volume copies in different storage pools if cloud snapshot feature is enabled on the volume.

A thin-provisioned or compressed volume copy in a data reduction storage pool must not be a sequential or image mode volume. On some node types, you can create a compressed volume copy in a data reduction storage pool for an I/O group. A compressed volume copy in a data reduction pool can be created only in an I/O group with V5030, V7000, or SVC node types. You can create thin-provisioned volume copies on any node type. Use the -autoexpand parameter to create thin-provisioned or compressed volume copies from a data reduction storage pool. Volumes can also have standard-provisioned volume copies in data reduction storage pools.

You cannot create a volume copy that is a thin-provisioned or compressed volume in a data reduction storage pool, and the volume caching mode is none or readonly. You must specify chvdisk to change the volume caching mode to readwrite.

You cannot specify -warning for a thin-provisioned or compressed volume copy in a data reduction storage pool.

For thin-provisioned and compressed volume copies in data reduction storage pools, the Easy Tier mode for the volume is taken from the data reduction storage pool. The Easy Tier mode cannot be configured on these volume types.

You cannot specify grain_size for thin-provisioned and compressed volume copies in data reduction storage pools. This type of volume copy is created with a size of 8 KB.

Thin-provisioned or compressed volume copies in data reduction pools cannot be created if the data reduction storage pool is offline and requires recovery. If the recovery is still in progress, you must wait until the recovery is complete and the pool is in online state.

An encryption key cannot be used when you add an image mode MDisk. To use encryption (when the MDisk has an encryption key), the MDisk must be self-encrypting.

Remember: You cannot add a volume copy if the volume to be copied is being formatted.

The virtualization types are defined as follows:

sequential (seq): This policy requires the -mdisk parameter with a single managed disk as its argument. This MDisk must be in managed mode.
It creates the volume by using extents from the given managed disk (assuming that enough free extents exist on the managed disk).
striped: The striped policy is the default policy. If the -vtype parameter is not specified, this policy is used in its default form. That is, all managed disks in the storage pool are used to create the volume. The striping is at an extent level; one extent from each managed disk in the group is used. For example, a storage pool with 10 managed disks uses one extent from each managed disk, and then the storage pool uses the 11th extent from the first managed disk, and so on.
If the -mdisk parameter is also specified, you can supply a list of managed disks to use as the stripe set. This list can include two or more managed disks from the same storage pool. The same circular algorithm is used across the striped set. However, a single managed disk can be specified more than once in the list. For example, if you enter -m 0:1:2:1, the extents are from the following managed disks: 0, 1, 2, 1, 0, 1, 2, and so on. All MDisks that are specified in the -mdisk parameter must be in managed mode.
image: This policy allows image mode volumes to be created when a managed disk already has data on it, perhaps from a previrtualized subsystem. When an image mode volume is created, it directly corresponds to the (previously unmanaged) managed disk that it was created from; therefore, volume logical block address (LBA) x equals managed disk LBA i. You can use this command to bring a nonvirtualized disk under the control of the system. After it is under the control of the system, you can migrate the volume from the single managed disk. When it is migrated, the volume is no longer an image mode volume.
You can add image mode volumes to an already populated storage pool with other types of volumes, such as a striped or sequential.

Important: An image mode copy must be at least as large as the volume that it is being added to, but any capacity beyond the size of the volume is not accessible.

The command returns the ID of the newly created volume copy.

Create the first compressed volume copy for an I/O group to activate compression. You cannot create or move a compressed volume copy to an I/O group that contains one or more nodes that do not support compressed volumes. You must use another I/O group, but note that it does not affect moving to the recovery I/O group.

Important:

If the volume (or volume copy) is a target of a FlashCopy® mapping with a source volume in an active-active relationship, the new storage pool must be in the same site as the source volume.
If this command is used for a volume that is a master volume, an auxiliary volume, or a change volume of an active-active relationship, the new copy must be created in a storage pool of the same site as the existing volume copy.
When you add an image mode copy, the site information for the MDisk that is being added must be well-defined and match the site information for any other MDisks in the storage pool.

The rate at which the volume copies resynchronize after loss of synchronization can be specified by using the -syncrate parameter. This following table provides the relationship of the syncrate value to the amount of data copied per second.

Remember: These settings also affect the initial rate of formatting.

Table 2. Relationship between the `syncrate` value and the amount of data copied per second
User-specified `syncrate` attribute value	Data copied per second
1 - 10	128 KB
11 - 20	256 KB
21 - 30	512 KB
31 - 40	1 MB
41 - 50	2 MB
51 - 60	4 MB
61 - 70	8 MB
71 - 80	16 MB
81 - 90	32 MB
91 - 100	64 MB
101 - 110	128 MB
111 - 120	256 MB
121 - 130	512 MB
131 - 140	1 GB
141 - 150	2 GB

The addvdiskcopy command can run on a Safeguarded backup volume with the following limitations:

The specified pool must be a Safeguarded backup location.
The volume will be thin-provisioned if the Safeguarded backup location is a standard pool no matter what parameters the user specifies.
The volume will be compressed and deduplicated if the Safeguarded backup location is a Data Reduction Pool no matter what parameters the user specifies.
The volume will have autoexpand set to yes whether specified or not. The user may specify -autoexpand parameter if they so choose but doing so will not make any difference.
The user can specify -rsize and the specified value honored otherwise a default -rsize value will be chosen.
- The default rsize value is 2% of the volume size with a minimum rsize of 1 GiB and maximum rsize 100 GiB.
- The user cannot specify a -rsize of 0.
The user may optionally specify the following parameters:
- -grain_size
  Important: If you specify the grain_size parameter, you must also specify the -rsize parameter.
- -syncrate
- -mirrorwritepriority
- -autodelete
- -unit
Other than the previously listed parameters, all other parameters are not permitted. The default value of the -warning parameter is 0, which specifies that warnings are disabled.

Failure Scenarios

The following failure scenarios can occur when the command fails:

Scenario 1:

The command fails because of insufficient resources if the I/O group contains any of the following elements:

At least one 8 GiB node.
At least one thin-provisioned or compressed volume in a data reduction pool.
A FlashCopy bitmap size for I/O group exceeds 1.5 GiB.

Scenario 2:

When a thin-provisioned or compressed volume is created within a data reduction pool, the pool must have enough capacity to create more volumes that track SCSI unmap operations from the host. If this capacity is not available, the command fails.

Scenario 3:

Volumes cannot be created in a data reduction pool if offline thin-provisioned or compressed volumes exist in a data reduction pool, either because of thin provisioning (an out-of-space or data corruption issue), or a component that is associated with the thin provisioning keeping a pool volume offline.

An invocation example

addvdiskcopy -mdiskgrp 0 -easytier off vdisk8

The resulting output:

Vdisk [8] copy [1] successfully created

An invocation example for specifying storage pools

addvdiskcopy -mdiskgrp 0 -vtype image -mdisk 13 -tier tier0_flash -easytier off vdisk9

The resulting output:

Vdisk [9] copy [1] successfully created

An invocation example for configuring a mirror write algorithm priority

addvdiskcopy -mdiskgrp 0 -mirrorwritepriority latency vdisk9

The resulting output:

Vdisk [9] copy [1] successfully created

An invocation example for adding a compressed volume copy

addvdiskcopy -mdiskgrp 1 -rsize 10% -compressed vdisk2

The resulting output:

Vdisk [2] copy [1] successfully created

An invocation example for adding a compressed volume copy

addvdiskcopy -mdiskgrp 0 -vtype image -mdisk 13 -tier tier_nearline vdisk9

The resulting output:

Vdisk [9] copy [1] successfully created