Performing Universal Volume Manager operations
You can perform Universal Volume Manager operations. Universal Volume Manager is a function that virtualizes storage devices and enables different models of storage systems to be used as one storage system.
Overview of Universal Volume Manager
Universal Volume Manager is a function that virtualizes storage devices and enables different models of storage systems to be used as one storage system.
To use volumes on an external storage system as external volumes, use a cable to connect the external connection port of the local storage system and the port of the external storage system, and then allocate (map) the volumes of the external storage system to the local storage system.
External volumes are used in situations such as the following:
- When you want to back up data in the volumes on the local storage system to the external storage system
- When you want to allocate an external volume to a host when the host issues a request for a volume to be used for storing data
- When you want to migrate data from the old storage system (external storage system) when a new storage system is installed
To discontinue the use of an external storage system that has become necessary, unmap the volumes of the unnecessary external storage system.
For details about the functions of Universal Volume Manager and related notes, see the Hitachi Universal Volume Manager User Guide.
The following figure shows the system configuration for using Universal Volume Manager, and the components of that configuration.
Local storage system
The local storage system receives requests from the REST API client.
External storage system
The external storage system is connected to the local storage system via external paths.
External path
An external path is a route by which the external connection port of the local storage system and the port of the external storage system are connected. You can set multiple routes as external paths. A group consisting of multiple external volumes that use the same external path is called an external path group.
External parity group
An external parity group is used to manage external volumes on the local storage system. Although an external parity group does not include parity information, it is managed in the same way as a parity group is managed. By registering external volumes on the external storage system in the external parity group, you can use the external volume from the local storage system.
External volume
You can enable volumes on an external storage system to be used from the host by creating external volumes from the external parity group. You can use the external volumes in the same way as other volumes on the local storage system.
TipThe mapped volumes on the external storage system are also called external volumes. When these mapped volumes need to be distinguished from the external volumes that are used on the local storage system, the mapped volumes will be referred to as "external volumes on the external storage system".
ImportantIf you are using the REST API, Storage Advisor Embedded, or CCI, attempts to perform multiple, concurrent executions of the following operations on external volumes might fail or produce incorrect results.
- Getting a list of ports on an external storage system
- Getting a list of the LUs of ports on an external storage system
- Getting information about the iSCSI targets of ports on an external storage system
- Performing a test to log in to an iSCSI target of an external storage system registered to the port of the local storage system
Workflow for Universal Volume Manager
This section describes the workflow in the REST API for using Universal Volume Manager to virtualize and use external storage system resources.
Create external volumes by mapping volumes of the external storage system that is connected to the port of the local storage system.
The workflow is shown in the following diagram.
Create volumes in the external storage system
Create volumes in the external storage system. If the external storage system supports the REST API, you can use the REST API on the external storage system to create volumes.
Configure the ports of the external storage system
Configure the ports of the external storage system and the system options. For details on how to configure the ports and options, see the manual for the external storage system that you are using.
(for iSCSI) Get information about the iSCSI target of the port on the external storage system
If the external storage system is connected via an iSCSI connection, retrieve information about the iSCSI target of the port on the external storage system.
(for iSCSI) Register the iSCSI name of the port on the external storage system to the port on the local storage system
If the external storage system is connected via an iSCSI connection, register the retrieved iSCSI name of the port on the external storage system to the port on the local storage system.
After registering the iSCSI name, use the API request for performing a login test make sure that you can successfully log in.
(for iSCSI) Get the iSCSI name of the external storage system, that was registered to the port on the local storage system
If the external storage system is connected via an iSCSI connection, get the iSCSI name of the port on the external storage system, that was registered to the port on the local storage system.
(for iSCSI) Perform a login test for the iSCSI target of the external storage system, that was registered to the port of the local storage system
If the external storage system is connected via an iSCSI connection, test whether you can log in to the iSCSI target of the external storage system by using the retrieved iSCSI name.
If you cannot log in, revise the settings so that you can log in, or delete the iSCSI target. If you do not delete iSCSI targets that cannot be used to log in, when you retrieve information about iSCSI targets of the port on the external storage system, there will be an increased load on the network or external storage system and information might not be retrieved successfully.
Get the list of the ports of the external storage systems
Get information about the ports of the external storage systems that are connected. The obtained information will be used to map external volumes.
Get the list of LUs defined for the port on the external storage system
Get information about the LUs that are defined for the ports of the connected external storage system. The obtained information will be used to map external volumes.
Get information about the external path group
To use an existing external path group to perform mapping, get information about the external path group and check the path group ID.
When an iSCSI connection is used, you can perform this operation by using the Platform REST API (Simple). For detailed information about this operation, see the Hitachi Vantara Knowledge.
Map the external volumes
Create external parity groups, and register information about the external volumes of the external storage system that you want to map. Check the registered mapping information with the API function for getting information about the external path group to which the parity groups that you created belong.
When an iSCSI connection is used, you can perform this operation by using the Platform REST API (Simple). For detailed information about this operation, see the Hitachi Vantara Knowledge.
Create volumes
Create external volumes from the external parity groups that have been created in the local storage system. The created external volumes can be allocated to the host or used as pool volumes (this is the same as other volumes in the local storage system).
You can make the access routes to the external volumes redundant by setting multiple external paths between the local storage system and the external storage system. To set multiple external paths, add the paths to the external path group. The external path group is created automatically when external volumes are mapped.
The workflow is shown in the following diagram.
Get information about the external path group
Get information about the target external path group to check the path group ID.
When an iSCSI connection is used, you can perform this operation by using the Platform REST API (Simple). For detailed information about this operation, see the Hitachi Vantara Knowledge.
Add external paths to the external path group
Add external paths by specifying the external path group.
The priorities of external paths depend on the order that the paths are registered to the external path group. To change the priority of a path in the REST API, delete the paths that are registered before the path for which you want to increase the priority, and then re-register the paths.
The workflow for external paths is shown in the following diagram.
Get information about the external path group
Get information about the target external path group, and check the priorities of the external paths and the path group ID.
When an iSCSI connection is used, you can perform this operation by using the Platform REST API (Simple). For detailed information about this operation, see the Hitachi Vantara Knowledge.
Delete the external path from the external path group
From the external path group, delete the external path whose priority you want to reduce.
Re-register the external path to the external path group
Re-register the deleted external path in the external path group. To add more than one path, re-register the paths starting from the path with a higher priority.
To dispose of an external storage system, disconnect the external volumes to release the mappings, and abolish the use of the external volumes.
The workflow is shown in the following diagram.
Disconnect the external volumes
Disconnect the external volumes. Input operations to and output operations from the mapped external volumes are stopped, and the data stored in the cache memory is written (destaged) to the external volumes.
Release the mappings with the external volumes
Delete the external parity groups to release the mappings with the external volumes. Data that has been written to the volumes on the external storage system site is not deleted after mappings are released. When the last external parity group in the external path group is deleted, the path group is automatically deleted.
(for iSCSI) Delete the iSCSI name of the external storage system, that was registered to the port on the local storage system
If the connection to the iSCSI target is no longer necessary, delete the iSCSI name of the external storage system, that was registered to the port on the local storage system.
Getting information about an iSCSI target of a port on an external storage system
This request gets information by searching for an iSCSI target (on an external storage system) that is connected to the local storage system.
-
0 is assumed for the virtual port ID if virtual port mode is enabled for the local storage system.
Storage Administrator (View Only)
POST base-URL/v1/objects/iscsi-ports/object-ID/actions/discover/invoke
Object ID
Specify the value of
portId
that was obtained by the processing to get information about ports.Attributes
Type
Description
portId
string
(Required) Port number of the local storage system
Query parameters
None.
Body
{ "parameters": { "iscsiIpAddress": "192.168.0.100", "tcpPort": 3260 } }
Attribute
Type
Description
iscsiIpAddress
string
(Required) IP address of the iSCSI target on the external storage system
Specify an IPv4 or IPv6 IP address.
tcpPort
int
(Optional) TCP port number of the iSCSI target on the external storage system
If this attribute is omitted, the TCP port number of the port on the local storage system is assumed.
Body
{ "portId": "CL1-A", "externalIscsiTargets": [ { "iscsiIpAddress": "192.168.0.100", "tcpPort": 3260, "iscsiName": "iqn.rest.example.of.iscsi1", "virtualPortId": 0, "isRegistered": true }, { "iscsiIpAddress": "192.168.0.101", "tcpPort": 3260, "iscsiName": "iqn.rest.example.of.iscsi2", "virtualPortId": 0, "isRegistered": false } ] }
Attribute
Type
Description
portId
string
Port number of the local storage system
externalIscsiTargets
object[]
The following attributes related to the iSCSI target of the external storage system are output:
-
tcpPort (int)
TCP port number
-
iscsiIpAddress (string)
IP address of the iSCSI target
-
iscsiName (string)
iSCSI name of the iSCSI target
-
virtualPortId (int)
ID of the virtual port by which the local storage system is connected to the external storage system
This attribute is output if the virtual port mode is enabled.
-
isRegistered (boolean)
Indicates whether this iSCSI target is registered to the iSCSI port of the local storage system
- true: The iSCSI target is registered to the iSCSI port of the local storage system.
- false: The iSCSI target is not registered to the iSCSI port of the local storage system.
-
None.
For details about the status codes of the request for this operation, see the description of HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session f76884c29fff4dfaa664aa6981087b71" -X POST "https://192.0.2.100/ConfigurationManager/v1/objects/iscsi-ports/CL1-A/actions/discover/invoke"
Registering an iSCSI name of an external storage system to a port on the local storage system
This request registers an iSCSI name of an external storage system to a port on the local storage system.
After registering the iSCSI name, run the API request that performs a login test to verify that you can log in. If the attempt to log in fails, revise the settings so that you can log in, or delete that iSCSI target. If iSCSI targets remain to which you cannot log in, attempts to obtain information might fail because a heavy load might be placed on the network or external storage system when you search for an iSCSI target of a port on the external storage system.
-
0 is assumed for the virtual port ID if virtual port mode is enabled for the local storage system.
Storage Administrator (Provisioning)
POST base-URL/v1/objects/iscsi-ports/object-ID/actions/register/invoke
Object ID
Specify the value of
portId
that was obtained by the processing to get information about ports.Attribute
Type
Description
portId
string
(Required) Port number of the local storage system
Query parameters
None.
Body
{ "parameters": { "iscsiIpAddress": "192.168.0.100", "iscsiName": "iqn.rest.example.of.iscsi1", "tcpPort" : 3260 } }
Attribute
Type
Description
iscsiIpAddress
string
(Required) IP address of the iSCSI target on the external storage system
Specify an IPv4 or IPv6 IP address.
iscsiName
string
(Required) iSCSI name of the iSCSI target on the external storage system
Specify the name in iqn or eui format.
This attribute is case sensitive.
tcpPort
int
(Optional) TCP port number of the iSCSI target on the external storage system
If this attribute is omitted, the TCP port number of the port on the local storage system is assumed.
If the iSCSI name and IP address to be specified are already registered to a port of the local storage system, set the same value as that port or omit this attribute. If you omit this attribute in this situation, the following settings are applied:
- If the iSCSI name and IP address are already registered to the same port
as the port specified for object-ID, the
registered
tcpPort
value is not changed. - If the iSCSI name and IP address are registered to a port different from
the port specified for object-ID, the same value
as the value that was set for
tcpPort
when the iSCSI name and IP address were registered to that port is set for the port specified for object-ID.
- If the iSCSI name and IP address are already registered to the same port
as the port specified for object-ID, the
registered
A job object is returned. For details
about attributes other than affectedResources
, see the description
of job objects.
Attribute |
Description |
affectedResources |
URL of the port (on the local storage system) to which information about the iSCSI name of the external storage system is registered |
None.
For details about the status codes of the request for this operation, see the description of HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session f76884c29fff4dfaa664aa6981087b71" -X POST "https://192.0.2.100/ConfigurationManager/v1/objects/iscsi-ports/CL1-A/actions/register/invoke"
Getting the iSCSI name of an external storage system that is registered to a port on the local storage system
The following request gets information about the iSCSI name of an iSCSI target of a port on an external storage system that is registered to a port on the specified local storage system.
Storage Administrator (View Only)
GET base-URL/v1/objects/iscsi-ports/object-ID
Object ID
Specify the value of
portId
that was obtained by the processing to get information about ports.Attribute
Type
Description
portId
string
(Required) Port number of the local storage system
Query parameters
None.
Body
None.
Body
{ "portId": "CL1-A", "externalIscsiTargets": [ { "iscsiIpAddress": "192.168.0.100", "tcpPort": 3260, "iscsiName": "iqn.rest.example.of.iscsi1", "authenticationMode": "CHAP", "iscsiTargetDirection" "D", "chapUserName": "Win_SQL_EX", "isSecretSet": true, "virtualPortId": 0 }, { "iscsiIpAddress": "192.168.0.101", "tcpPort": 3260, "iscsiName": "iqn.rest.example.of.iscsi2", "authenticationMode": "NONE", "iscsiTargetDirection" "S", "chapUserName": "-", "isSecretSet": false, "virtualPortId": 0 } ] }
Attribute
Type
Description
portId
string
Port number of the local storage system
externalIscsiTargets
object[]
The attributes related to the iSCSI target on the external storage system are output.
An empty array is output if the port on the external storage system is a Fibre Channel port.
-
iscsiIpAddress (string)
IP address of the iSCSI target
-
tcpPort (int)
TCP port number
-
iscsiName (string)
iSCSI name
-
authenticationMode (string)
CHAP-authentication mode
- CHAP: CHAP-authentication mode
- NONE: No authentication mode
-
iscsiTargetDirection (string)
Direction of the iSCSI target CHAP-authentication
- D: Bidirectional authentication (The iSCSI target and the iSCSI initiator authenticate each other.)
- S: Unidirectional authentication (The iSCSI target authenticates the iSCSI initiator.)
-
chapUserName (string)
CHAP user name
The following user name is output: the user name used when the direction of CHAP-authentication is bidirectional.
This also appears if CHAP-authentication mode is NONE.
A hyphen (-) appears if the CHAP user name is omitted.#
-
isSecretSet (boolean)
Indicates whether a secret password is set for the CHAP authentication
- true: A password is set.
- false: A password is not set.
-
virtualPortId (int)
ID of the virtual port by which the local storage system is connected to the external storage system
This attribute is output if virtual port mode is enabled.
#: A hyphen (-) is output if - is specified for the CHAP user name.
-
For details about the status codes of the request for this operation, see the description of HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session f76884c29fff4dfaa664aa6981087b71" -X GET "https://192.0.2.100/ConfigurationManager/v1/objects/iscsi-ports/CL1-A"
Performing a login test on an iSCSI target of an external storage system that is registered to a port on the local storage system
The following request gets a login result by logging in to an iSCSI target on an external storage system that is registered to a port on the local storage system.
If an attempt to log in fails, revise the settings so that you can log in to the iSCSI target, or delete that iSCSI target. If iSCSI targets remain to which you cannot log in, attempts to obtain information might fail because a heavy load might be placed on the network or external storage system when you search for an iSCSI target of a port on the external storage system.
-
0 is assumed for the virtual port ID if virtual port mode is enabled for the local storage system.
Storage Administrator (View Only)
POST base-URL/v1/objects/iscsi-ports/object-ID/actions/check/invoke
Object ID
Specify the value of
portId
that was obtained by the processing to get information about ports.Attribute
Type
Description
portId
string
(Required) Port number of the local storage system
Query parameters
None.
Body
{ "parameters": { "iscsiIpAddress": "192.168.0.100", "iscsiName": "iqn.rest.example.of.iscsi1" } }
Attribute
Type
Description
iscsiIpAddress
string
(Required) IP address of the iSCSI target of the external storage system
Specify an IPv4 or IPv6 IP address.
iscsiName
string
(Required) iSCSI name of the iSCSI target of the external storage system
Specify the name in iqn or eui format.
This attribute is case sensitive.
Body
{ "portId": "CL1-A", "externalIscsiTargets": [ { "iscsiIpAddress": "192.168.0.100", "iscsiName": "iqn.rest.example.of.iscsi1", "isLoginSucceeded": true } ] }
Attribute
Type
Description
portId
string
Port number of the local storage system
externalIscsiTargets
object[]
The following attributes related to the iSCSI target of the external storage system are output:
-
iscsiIpAddress (string)
IP address of the iSCSI target
-
iscsiName (string)
iSCSI name of the iSCSI target
-
isLoginSucceeded (boolean)
Result of logging in to the iSCSI target
- true: The login attempt succeeded.
- false: The login attempt failed.
-
None.
For details about the status codes of the request for this operation, see the description of HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session f76884c29fff4dfaa664aa6981087b71" -X POST "https://192.0.2.100/ConfigurationManager/v1/objects/iscsi-ports/CL1-A/actions/check/invoke"
Getting a list of ports on an external storage system
The following request acquires a list of ports for an external storage system that is connected to the local storage system.
In the case of an iSCSI port, if an iSCSI target that cannot connect to the target iSCSI port is registered, attempts to obtain information might fail because a heavy load might be placed on the network or external storage system. After registering the iSCSI name, perform a login test to verify that you can log in.
Storage Administrator (View Only)
GET base-URL/v1/objects/external-storage-ports
Object ID
None.
Query parameters
Parameter
Type
Filter condition
portId
string
(Required) Number of the port on the local storage system
Body
None.
Body
The following is a coding example when a Fibre Channel port is used:
{ "data" : [ { "externalWwn" : "50060e80222fd141", "portId" : "CL7-A", "externalSerialNumber" : "477777", "externalStorageInfo" : "HITACHI VSP Gx00", "externalPathMode" : "Multi", "externalIsUsed" : false } ] }
The following is a coding example when an iSCSI port is used:
{ "data" : [ { "portId" : "CL2-D", "externalSerialNumber" : "477777", "externalStorageInfo" : "HITACHI VSP Gx00", "externalPathMode" : "Multi", "externalIsUsed" : true, "iscsiIpAddress" : "192.0.1.100", "iscsiName" : "iqn.rest.example.of.iscsi1", "virtualPortId" : 0 } ] }
Attribute
Type
Description
portId
string
Number of the port on the local storage system
externalWwn
string
WWN of the port on the external storage system
This attribute is displayed when a Fibre Channel port is used.
iscsiIpAddress
string
IP address of the iSCSI target on the external storage system
This attribute is displayed when an iSCSI port is used.
iscsiName
string
Name of the iSCSI target on the external storage system
This attribute is displayed when an iSCSI port is used.
virtualPortId
int
Virtual port ID
This attribute is displayed when an iSCSI port is used and virtual port mode is enabled.
externalSerialNumber
string
Serial number of the external storage system
externalStorageInfo
string
The vendor information and product ID of the external storage system
This information is obtained in a format in which the vendor information and product ID are concatenated by a space.
externalPathMode
string
Path mode for the external path of the port on the external storage system
- Multi: Multi mode
- Single: Single mode
- APLB: APLB mode
externalIsUsed
boolean
Whether the port of the external storage system that is externally connected to the local storage system is being used to map external volumes
- true: Used
- false: Not used
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/external-storage-ports?portId=CL7-A
Getting a list of LUs defined for a port on an external storage system
The following request acquires a list of the LUs that are defined for the port on an external storage system that is externally connected to the local storage system.
Storage Administrator (View Only)
GET base-URL/v1/objects/external-storage-luns
Object ID
None.
Query parameters
When a Fibre Channel port is used:
Parameter
Type
Filter Condition
portId
string
(Required) Number of the port on the local storage system
externalWwn
string
(Required) WWN of the port on the external storage system
When an iSCSI port is used:
Parameter
Type
Filter Condition
portId
string
(Required) Port number on the local storage system
iscsiIpAddress
string
(Required) IP address of the iSCSI target on the external storage system
iscsiName
string
(Required) iSCSI name of the iSCSI target on the external storage system
Specify this parameter in iqn or eui format.
Body
None.
Body
The following is a coding example when a Fibre Channel port is used:
{ "data" : [ { "externalLun" : 0, "portId" : "CL7-A", "externalWwn" : "50060e80222fd141", "externalVolumeCapacity" : 62914560, "externalVolumeInfo" : "OPEN-V HITACHI 50412FD100CC" } ] }
The following is a coding example when an iSCSI port is used:
{ "data" : [ { "externalLun" : 0, "portId" : "CL7-A", "externalVolumeCapacity" : 62914560, "externalVolumeInfo" : "OPEN-V HITACHI 50412FD100CC", "iscsiIpAddress" : "192.168.0.100", "iscsiName" : "iqn.rest.example.of.iscsi1", "virtualPortId" : 0 } ] }
Attribute
Type
Description
portId
string
Number of the port on the local storage system
externalWwn
string
WWN of the port on the external storage system
This attribute is displayed when a Fibre Channel port is used.
iscsiIpAddress
string
IP address of the iSCSI target on the external storage system
This attribute is displayed when an iSCSI port is used.
iscsiName
string
Name of the iSCSI target on the external storage system
This attribute is displayed when an iSCSI port is used.
virtualPortId
int
Virtual port ID
This attribute is displayed when an iSCSI port is used and virtual port mode is enabled.
externalLun
int
LUN that can be referenced from the port on the external storage system
externalVolumeCapacity
long
Capacity of the external volume on the external storage system (1 block = 512 bytes)
externalVolumeInfo
string
The product ID and the device identification (output in ASCII format) in the SCSI information for the external volume on the external storage system
This information is obtained in a format in which the product ID and the device identification are concatenated by a space.
If the LU cannot be used as an external volume group, OTHER is output for the product ID.
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET "https://192.0.2.100/ConfigurationManager/v1/objects/external-storage-luns?portId=CL7-A&externalWwn=50060e80222fd141"
Mapping an external volume
The following request creates an external parity group on the local storage system, and then registers (maps) volumes on an external storage system to the created external parity group. When a volume is mapped, the external path group and the external path are also created.
The API request for mapping an external volume can be used only when Fibre Channel ports are used. The request cannot be used when iSCSI ports are used.
If you are using an iSCSI port, use storage management software such as CCI. You can perform this operation by using the Platform REST API (Simple). For detailed information about this operation, see the Hitachi Vantara Knowledge website.
Storage Administrator (Provisioning)
POST base-URL/v1/objects/external-parity-groups
Object ID
None.
Query parameters
None.
Body
{ "externalParityGroupId":"1-1", "externalPathGroupId":1, "portId":"CL7-A", "externalWwn":"50060e80222fd141", "lunId":0, "emulationType":"OPEN-V", "clprId":0 }
Attribute
Type
Description
externalParityGroupId
string
(Required) External parity group number
Specify the number in gno-sgno format.
externalPathGroupId
int
(Required) External path group ID
If the specified path group ID does not exist, a new path group ID will be created.
portId
string
(Required) Number of the port on the local storage system
externalWwn
string
(Required) WWN of the external storage system
lunId
int
(Required) LUN of the port on the external storage system
emulationType
string
(Optional) Emulation type
Specifiable values are as follows:
OPEN-3 , OPEN-8 , OPEN-9 , OPEN-E , OPEN-K , OPEN-L , OPEN-V , 3380-3 , 3380-3A , 3380-3B , 3380-3C , 3390-1 , 3390-2 , 3390-3 , 3390-A , 3390-3A , 3390-3B , 3390-3C , 3390-3R , 3390-9 , 3390-9A , 3390-9B , 3390-9C , 3390-L , 3390-LA , 3390-LB , 3390-LC , 3390-M , 3390-MA , 3390-MB , 3390-MC , 3390-V , 6586-G , 6586-J , 6586-K , 6586-KA , 6586-KB , 6586-KC , 6588-1 , 6588-3 , 6588-9 , 6588-A , 6588-3A , 6588-3B , 6588-3C , 6588-9A , 6588-9B , 6588-9C , 6588-L , 6588-LA , 6588-LB , 6588-LC
If this attribute is omitted, OPEN-V is set.
clprId
int
(Optional) CLPR number to be used by the external parity group
Specify a decimal (base 10) number in the range from 0 to 31.
If this attribute is omitted, 0 is set.
isExternalAttributeMigration
boolean
(Optional) Whether to set the nondisruptive migration attribute for the external parity group
- true: Set the attribute.
- false: Do not set the attribute
If this attribute is omitted, false is set.
commandDeviceLdevId
int
(Optional) LDEV number of the remote command device
Specify this attribute if you want to map the command device of the external storage system.
The specified LDEV number is assigned to the remote command device.
Body
A job object is returned. For details on attributes other than
affectedResources
, see the section explaining job objects. To check whether the execution results of this API request have been correctly applied, execute the API request for getting information about the external paths.Attribute
Description
affectedResources
URL of the mapped external parity group
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/external-parity-groups
Getting a list of external path groups
The following request obtains a list of information about external path groups. It also obtains information about the related external parity groups and external paths.
Depending on the number of resources for which information is to
be obtained, you might have to run this API request more than once to obtain
information about all of those resources. In such cases, each time you run the
request, if information was not obtained for one or more external path groups, the
attribute nextPageHeadPathGroupId
in the response body indicates
the ID of the first external path group for which information was not obtained. To
obtain information about the remaining external path groups, run the API request
with the path group ID indicated by nextPageHeadPathGroupId
specified for the parameter headPathGroupId
in the query. If
information was obtained for all target resources, the attribute
nextPageHeadPathGroupId
returns the value
-1.
-
The API request for getting a list of external path groups can be used only when Fibre Channel ports are used. The request cannot be used when iSCSI ports are used.
If you are using an iSCSI port, use storage management software such as CCI. You can perform this operation by using the Platform REST API (Simple). For detailed information about this operation, see the Hitachi Vantara Knowledge website.
- the number of concurrent executions of this API request might be limited depending on the number of paths in the external path groups for which information is to be obtained or depending on the other processing being executed at the same time. For details on this limitation and the conditions under which the limitation applies, see the note on the number of concurrent executions.
Storage Administrator (View Only)
GET base-URL/v1/objects/external-path-groups
Object ID
None.
Query parameters
Parameter
Type
Filter Condition
externalParityGroupId
string
(Optional) External parity group number
Specify the number in gno-sgno format.
You cannot specify this parameter and the
ldevId
parameter at the same time.ldevId
string
(Optional) LDEV number
You cannot specify this parameter and the
externalParityGroupId
parameter at the same time.headPathGroupId
int
(Optional) ID of the first external path group of the external path groups for which information is to be obtained
If you want to specify a range of external path groups for which to information is to be obtained, specify the ID of the first external path group in the target range.
Body
None.
Body
{ "data": [ { "externalPathGroupId": 0, "externalSerialNumber": "91110309", "externalProductId": "HUS", "externalParityGroups": [ { "externalParityGroupId": "1-1", "externalParityGroupStatus": "BLK", "cacheMode": "D", "isInflowControlEnabled": false, "mpBladeId": 0, "loadBalanceMode": "N", "pathMode": "M", "isDataDirectMapping": false, "externalLuns": [ { "portId": "CL5-B", "externalWwn": "50060e8010539b51", "priority": 1, "externalLun": 0, "pathStatus": "BLK" } ] }, { "externalParityGroupId": "1-12", "externalParityGroupStatus": "BLK", "cacheMode": "E", "isInflowControlEnabled": false, "mpBladeId": 2, "loadBalanceMode": "N", "pathMode": "M", "isDataDirectMapping": false, "externalLuns": [ { "portId": "CL5-B", "externalWwn": "50060e8010539b51", "priority": 1, "externalLun": 19, "pathStatus": "BLK" } ] } ], "externalPaths": [ { "portId": "CL5-B", "externalWwn": "50060e8010539b51" } ], "nextPageHeadPathGroupId": -1 }, { "externalPathGroupId": 1, "externalSerialNumber": "210945", "externalProductId": "HUS VM", "externalParityGroups": [ { "externalParityGroupId": "1-2", "externalParityGroupStatus": "NML", "cacheMode": "D", "isInflowControlEnabled": false, "mpBladeId": 1, "loadBalanceMode": "N", "pathMode": "M", "isDataDirectMapping": false, "externalLuns": [ { "portId": "CL5-B", "externalWwn": "50060e80132ac120", "priority": 1, "externalLun": 21, "pathStatus": "NML" } ] }, { "externalParityGroupId": "1-23", "externalParityGroupStatus": "NML", "cacheMode": "E", "isInflowControlEnabled": false, "mpBladeId": 2, "loadBalanceMode": "N", "pathMode": "M", "isDataDirectMapping": false, "externalLuns": [ { "portId": "CL5-B", "externalWwn": "50060e80132ac120", "priority": 1, "externalLun": 32, "pathStatus": "NML" } ] } ], "externalPaths": [ { "portId": "CL5-B", "externalWwn": "50060e80132ac120" } ], "nextPageHeadPathGroupId": -1 } ] }
Attribute
Type
Description
externalPathGroupId
int
External path group number
externalSerialNumber
string
Serial number of the external storage system
externalProductId
string
Product ID of the external storage system
externalParityGroups
object[]
The following attributes are output for each external parity group:
- externalParityGroupId (string)
External parity group number
- externalParityGroupStatus (string)
Status of the external parity group
-
NML: Normal
-
CHK: The mapping path status is being checked
-
SYN: Data in the cache is being written to the volume
-
DSC: The parity group is disconnected from the external storage system or the external volumes
-
BLK: The mapping path is blocked
-
WAR: The status of the mapping path is not normal
-
Unknown: Unknown
-
- cacheMode (string)
Cache mode
-
E: Enabled
-
D: Disabled
-
EM: Enabled
-
DM: Disabled
-
TM: Through
-
SM: Synchronized writing
-
- isInflowControlEnabled (boolean)
Inflow cache control
-
true: Enabled
-
false: Disabled
-
- mpBladeId (int)
MP blade ID
- loadBalanceMode (string)
The load balancing method for I/O operations for the external storage system
-
N: Standard round-robin method
-
E: Expanded round-robin method
-
D: I/O is performed over a single path, and load balancing is not used
-
- pathMode (string)
Path mode of the external storage system
-
M: Multi mode
-
S: Single mode
-
A: APLB mode
-
AL: ALUA mode
-
MA: Multi mode (in a state in which the mode can be changed to the ALUA mode)
-
SA: Single mode (in a state in which the mode can be changed to the ALUA mode)
-
- isDataDirectMapping (boolean)
Whether the data direct mapping attribute is enabled
-
true: Enabled
-
false: Disabled
-
- externalLuns (object[])
The following attributes are output for each LU on the external storage system:
- portId (string)
Port number
- externalWwn (string)
WWN of the external storage system
- priority (int)
Priority within the external path group
- externalLun (int)
LUN within the ports of the external storage system
- pathStatus (string)
Status of the external path
NML: Normal
CHK: Temporarily blocked (The status of the external path is being checked.)
BLK: Blocked
DSC: Disconnected
Unknown: Unknown
- portId (string)
externalPaths
object[]
The following attributes are output for each external path:
- portId (string)
Port number
- externalWwn (string)
WWN of the external storage system
- qDepth (int)
Number of Read/Write commands that can be queued to the external parity group
This information is obtained only when the
qDepth
attribute is set. - ioTimeOut (int)
The value (in seconds) set for the I/O time over for the external parity group
This information is obtained only when the
ioTimeOut
attribute is set. - blockedPathMonitoring (int)
The time (in seconds) until the external parity group is blocked after all paths to the external parity group are disconnected
This information is obtained only when the
blockedPathMonitoring
attribute is set.
nextPageHeadPathGroupId
int
ID of the first external path group for which information was not obtained
If you were not able to obtain information about all target external path groups by a single execution of the request, you can obtain information about the remaining external path groups by running the request again, with this value specified for the parameter
headPathGroupId
in the query.If information was obtained about all target external path groups, the value -1 is output.
- externalParityGroupId (string)
For details on the status codes of the API, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/external-path-groups
The number of concurrent executions of this API request might be limited depending on the number of paths in the external path groups for which information is to be obtained or depending on the other processing being executed at the same time.
The number of concurrent executions can be affected by the following:
- Processing to get a list of resource groups
- Processing to get information about multiple LDEVs
- Processing to get port information (when executed with
detailInfoType=logins
specified in the query) - Processing to get information about host groups or iSCSI targets
- Processing to get information about global-active device pairs
- Processing to get information about a specific external path group
Refer to the information below to estimate the maximum number of concurrent requests for getting a list of external path groups if one or more of the above processing is in progress.
Processing being executed |
Maximum number of requests that can be executed concurrently (expected number of resources for which information can be obtained) |
None |
13 (Number of paths in the external path groups: less than 10,240) |
None |
4 (Number of paths in the external path groups: 10,240 or more) |
Processing to get LDEV information (Number of LDEVs: 16,384) × 1 |
9 (Number of paths in the external path groups: less than 10,240) |
Processing to get LDEV information (Number of LDEVs: 16,384) × 1 |
1 (Number of paths in the external path groups: 10,240 or more) |
Getting information about a specific external path group
The following request acquires information about a specified external path group and the external parity groups and external paths that are related to the specified external path group.
-
The API request for getting information about a specific external path group can be used only when Fibre Channel ports are used. The request cannot be used when iSCSI ports are used.
If you are using an iSCSI port, use storage management software such as CCI. You can perform this operation by using the Platform REST API (Simple). For detailed information about this operation, see the Hitachi Vantara Knowledge website.
- the number of concurrent executions of this API request might be limited depending on the number of paths in the external path groups for which information is to be obtained or depending on the other processing being executed at the same time. For details on this limitation and the conditions under which the limitation applies, see the note on the number of concurrent executions for the API for getting a list of external path groups.
Storage Administrator (View Only)
GET base-URL/v1/objects/external-path-groups/object-ID
Object ID
Specify the value of
externalPathGroupId
that was obtained by the request to get information about the external path group.Attribute
Type
Description
externalPathGroupId
int
(Required) External path group number
Query parameters
None.
Body
None.
Body
{ "externalPathGroupId": 1, "externalSerialNumber": "210945", "externalProductId": "HUS VM", "externalParityGroups": [ { "externalParityGroupId": "1-2", "externalParityGroupStatus": "NML", "cacheMode": "D", "mpBladeId": 1, "loadBalanceMode": "N", "pathMode": "M", "externalLuns": [ { "portId": "CL5-B", "externalWwn": "50060e80132ac120", "priority": 1, "externalLun": 21, "pathStatus": "NML" } ], "isInflowControlEnabled": false, "isDataDirectMapping": false }, { "externalParityGroupId": "1-23", "externalParityGroupStatus": "NML", "cacheMode": "E", "mpBladeId": 2, "loadBalanceMode": "N", "pathMode": "M", "externalLuns": [ { "portId": "CL5-B", "externalWwn": "50060e80132ac120", "priority": 1, "externalLun": 32, "pathStatus": "NML" } ], "isInflowControlEnabled": false, "isDataDirectMapping": false } ], "externalPaths": [ { "portId": "CL5-B", "externalWwn": "50060e80132ac120" } ] }
Attribute
Type
Description
externalPathGroupId
int
External path group number externalSerialNumber
string
Serial number of the external storage system externalProductId
string
Product ID of the external storage system
externalParityGroups
object[]
The following attributes are output for each external parity group:
- externalParityGroupId (string)
External parity group number
- externalParityGroupStatus (string)
Status of the external parity group
-
NML: Normal
-
CHK: The mapping path status is being checked
-
SYN: Data in the cache is being written to the volume
-
DSC: The external parity group is disconnected from the external storage system or the external volume
-
BLK: The mapping path is blocked
-
WAR: The status of the mapping path is not normal
-
Unknown: Unknown
-
- cacheMode (string)
Cache mode
-
E: Enabled
-
D: Disabled
For an external parity group that has the nondisruptive migration attribute, the following values are output:
-
EM: Enabled
-
DM: Disabled
-
TM: Through
-
SM: Synchronized writing
-
- isInflowControlEnabled (boolean)
Inflow cache control
-
true: Enabled
-
false: Disabled
-
- mpBladeId (int)
MP blade ID
- loadBalanceMode (string)
The load balancing method for I/O operations for the external storage system
-
N: Standard round-robin method
-
E: Expanded round-robin method
-
D: I/O is performed over a single path, and load balancing is not used
-
- pathMode (string)
Path mode of the external storage system
-
M: Multi mode
-
S: Single mode
-
A: APLB mode
-
AL: ALUA mode
-
MA: Multi mode (E)
-
SA: Single mode (in a state in which the mode can be changed to the ALUA mode)
-
- isDataDirectMapping (boolean)
Whether the data direct mapping attribute is enabled
-
true: Enabled
-
false: Disabled
-
- externalLuns (object[])
The following attributes are output for each LU on the external storage system:
- portId (string)
Port number
- externalWwn (string)
WWN of the external storage system
- priority (int)
Priority within the external path group
- externalLun (int)
LUN within the ports of the external storage system
- pathStatus (string)
Status of the external path
NML: Normal
CHK: Temporarily blocked (The status of the external path is being checked.)
BLK: Blocked
DSC: Disconnected
Unknown: Unknown
- portId (string)
externalPaths
object[]
The following attributes are displayed for each external path: - portId (string)
Port number
- externalWwn (string)
WWN of the external storage system
- qDepth (int)
Number of Read/Write commands that can be queued to the external parity group
This information is obtained only when the
qDepth
attribute is set. - ioTimeOut (int)
The value (in seconds) set for the I/O time over for the external parity group
This information is obtained only when the
ioTimeOut
attribute is set. - blockedPathMonitoring (int)
The time (in seconds) until the external parity group is blocked after all paths to the external parity group are disconnected
This information is obtained only when the
blockedPathMonitoring
attribute is set.
- externalParityGroupId (string)
For details on the status codes of the API, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/external-path-groups/1
Adding an external path to an external path group
The following request adds external path information to an existing external path group. The priority of the path is set in ascending order, according to the order in which the path was added.
Storage Administrator (Provisioning)
POST base-URL/v1/objects/external-path-groups/object-ID/actions/add-path/invoke
Object ID
Specify the value of
externalPathGroupId
that was obtained by the request to get information about the external path group.Attribute
Type
Description
externalPathGroupId
int
(Required) External path group number
Query parameters
None.
Body
The following is a coding example when a Fibre Channel port is used:
{ "parameters": { "portId":"CL7-A", "externalWwn":"50060E801033C2F0" } }
When a Fibre Channel port is used:
Attribute
Type
Description
portId
string
(Required) Number of the port on the local storage system
externalWwn
string
(Required) WWN of the external storage system
The following is a coding example when an iSCSI port is used:
{ "parameters": { "portId":"CL1-C", "iscsiIpAddress": "192.168.0.100", "iscsiName": "iqn.rest.example.of.iscsi1" } }
When an iSCSI port is used:
Attribute
Type
Description
portId
string
(Required) Port number on the local storage system
iscsiIpAddress
string
(Required) IP address of the iSCSI target on the external storage system
Specify an IPv4 or IPv6 address.
iscsiName
string
(Required) iSCSI name of the iSCSI target on the external storage system
Specify this attribute in iqn or eui format.
Body
A job object is returned. For details on attributes other than
affectedResources
, see the section explaining job objects.Attribute
Description
affectedResources
-
When a Fibre Channel port is used:
The URL of the external path group to which the external path was added is returned.
-
When an iSCSI port is used:
affectedResources
is not displayed for this API.To check whether the external path was added to the external path group, use storage management software such as CCI. You can perform this operation by using the Platform REST API (Simple). For detailed information about this operation, see the Hitachi Vantara Knowledge website.
-
None.
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/external-path-groups/1/actions/add-path/invoke
Removing an external path from an external path group
The following request removes external path information from an external path group.
Storage Administrator (Provisioning)
POST base-URL/v1/objects/external-path-groups/object-ID/actions/remove-path/invoke
Object ID
Specify the value of
externalPathGroupId
that was obtained by the request to get information about the external path group.Attribute
Type
Description
externalPathGroupId
int
(Required) External path group number
Query parameters
None.
Body
The following is a coding example when a Fibre Channel port is used:
{ "parameters": { "portId":"CL7-A", "externalWwn":"50060E801033C2F0" } }
When a Fibre Channel port is used:
Attribute
Type
Description
portId
string
(Required) Number of the port on the local storage system
externalWwn
string
(Required) WWN of the external storage system
The following is a coding example when an iSCSI port is used:
{ "parameters": { "portId":"CL1-C", "iscsiIpAddress": "192.168.0.100", "iscsiName": "iqn.rest.example.of.iscsi1" } }
When an iSCSI port is used:
Attribute
Type
Description
portId
string
(Required) Port number on the local storage system
iscsiIpAddress
string
(Required) IP address of the iSCSI target on the external storage system
Specify an IPv4 or IPv6 address.
iscsiName
string
(Required) iSCSI name of the iSCSI target on the external storage system
Specify this attribute in iqn or eui format.
Body
A job object is returned. For details on attributes other than
affectedResources
, see the section explaining job objects.Attribute
Description
affectedResources
-
When a Fibre Channel port is used:
The URL of the external path group from which the external path was removed is returned.
-
When an iSCSI port is used:
affectedResources
is not displayed for this API.To check whether the external path was removed from the external path group, use storage management software such as CCI. You can perform this operation by using the Platform REST API (Simple). For detailed information about this operation, see the Hitachi Vantara Knowledge website.
-
None.
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/external-path-groups/1/actions/remove-path/invoke
Unmapping an external volume
The following request unmaps an external volume by deleting the external parity group. If the last external parity group is deleted, the external path group itself is also deleted.
Storage Administrator (Provisioning)
DELETE base-URL/v1/objects/external-parity-groups/object-ID
Object ID
Specify the value of
externalParityGroupId
that was obtained by the processing to get information about the external path group.Attribute
Type
Description
externalParityGroupId
string
(Required) External parity group number
Query parameters
None.
Body
{ "force": true }
Attribute
Type
Description
force
boolean
(Optional) Specify whether to forcibly unmap the external volume without destaging it.
Specify true to unmap the external volume without destaging it.
-
true: Forcibly unmap the external volume.
- false: Unmap the external volume only if the external volume has been destaged.
If this attribute is omitted, false is set.
If you specify false, first execute the API function to disconnect the external volume.
-
Body
A job object is returned. See the description for the job object.
affectedResources
is not displayed for this API. To check whether the unmapping was successful, execute the API request for getting information about an external path group.
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X DELETE https://192.0.2.100/ConfigurationManager/v1/objects/external-parity-groups/1-1
Disconnecting from an external volume
The following request disconnects an external volume on an external storage system from the local storage system. The external volume is not unmapped.
Storage Administrator (Provisioning)
POST base-URL/v1/objects/external-parity-groups/object-ID/actions/disconnect/invoke
Object ID
Specify the value of
externalParityGroupId
that was obtained by the processing to get information about the external path group.Attribute
Type
Description
externalParityGroupId
string
(Required) External parity group number
Query parameters
None.
Body
None.
Body
A job object is returned. See the description for the job object.
affectedResources
is not displayed for this API function. To check whether the disconnection was successful, check the status of the external path by executing the API function for getting information about an external path group.
None.
For details on the status codes of the request for this operation, see the description of HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST https://192.0.2.100/ConfigurationManager/v1/objects/external-parity-groups/1-1/actions/disconnect/invoke -d ""
Deleting an iSCSI name of an external storage system that is registered to a port on the local storage system
This request deletes information about an iSCSI name (on the external storage system) that is registered to the local storage system.
-
0 is assumed for the virtual port ID if virtual port mode is enabled for the local storage system.
Storage Administrator (Provisioning)
POST base-URL/v1/objects/iscsi-ports/object-ID/actions/remove/invoke
Object ID
Specify the value of
portId
that was obtained by the processing to get information about ports.Attribute
Type
Description
portId
string
(Required) Port number of the local storage system
Query parameters
None.
Body
{ "parameters": { "iscsiIpAddress": "192.168.0.100", "iscsiName": "iqn.rest.example.of.iscsi1" } }
Attribute
Type
Description
iscsiIpAddress
string
(Required) IP address of the iSCSI target on the external storage system
Specify an IPv4 or IPv6 IP address.
iscsiName
string
(Required) iSCSI name of the iSCSI target on the external storage system
Specify the name in iqn or eui format.
This attribute is case sensitive.
A job object is returned. For details
about attributes other than affectedResources
, see the description
of job objects.
Attribute |
Description |
affectedResources |
URL of the port (on the local storage system) whose iSCSI name information about the external storage system has been deleted |
None.
For details about the status codes of the request for this operation, see the description of HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session f76884c29fff4dfaa664aa6981087b71" -X POST "https://192.0.2.100/ConfigurationManager/v1/objects/iscsi-ports/CL1-A/actions/remove/invoke"