Sunteți pe pagina 1din 51

HP 3PAR Web Services API 1.

1 Developer's Guide

Abstract
This guide provides instructions and reference information for the HP 3PAR Web Services API.

HP Part Number: QL226-96939 Published: March 2013 Edition: Second

Copyright 2013 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.21 1 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Contents
1 Introduction...............................................................................................6
About the WSAPI......................................................................................................................6 Typographic Conventions......................................................................................................6 User Input......................................................................................................................6 System Output................................................................................................................6 Getting Started.........................................................................................................................6 Configuring the Server..............................................................................................................6 About the SDK.........................................................................................................................7 Java SDK............................................................................................................................7 Perl SDK.............................................................................................................................7

2 Overview..................................................................................................8
Protocol and Message Format....................................................................................................9 Client Headers....................................................................................................................9 Examples.....................................................................................................................10 Querying CPGs........................................................................................................10 Creating CPGs.........................................................................................................10 Server Headers.................................................................................................................10 Supported HTTP Methods....................................................................................................10 GET............................................................................................................................10 POST...........................................................................................................................11 DELETE........................................................................................................................11 General URI Format................................................................................................................11

3 System Access..........................................................................................12
Creating Credentials...............................................................................................................12 About Multiple Session Keys................................................................................................12 About Session Key Security.................................................................................................12 Creating a Session Key...........................................................................................................12 Deleting a Session Key............................................................................................................13 Getting Version Information......................................................................................................13 Success............................................................................................................................13

4 Status and Error Codes.............................................................................14


The code Member..................................................................................................................14 Codes Listing.....................................................................................................................14 The desc Member...................................................................................................................18 Examples..........................................................................................................................18 The ref Member......................................................................................................................18 HTTP Error Codes...................................................................................................................18

5 6 7 8

Request Input and Optional Members.........................................................20 Enumerations...........................................................................................21 JSON Types and API Types........................................................................22 Working with Common Provisioning Groups................................................23
CPG Enumeration and Configuration Objects.............................................................................23 LDLayout Object................................................................................................................23 RAIDType Enumeration........................................................................................................23 HA Enumeration................................................................................................................24 chunkletPosPref Enumeration................................................................................................24 diskPatterns Object.............................................................................................................24 diskType Enumeration.........................................................................................................25
Contents 3

Space Usage Objects.........................................................................................................25 Growth Objects.................................................................................................................26 state Enumeration..............................................................................................................26 detailed state Enumeration..................................................................................................26 Create a CPG........................................................................................................................26 Message Body Parameters..................................................................................................27 Responses.........................................................................................................................27 Success........................................................................................................................27 Error Codes..................................................................................................................27 Remove a CPG.......................................................................................................................27 Responses.........................................................................................................................28 Success........................................................................................................................28 Errors..........................................................................................................................28 Query CPG Information...........................................................................................................28 Responses.........................................................................................................................29 Success........................................................................................................................29

9 Working with Storage Volumes..................................................................30


Volume Enumeration and Configuration Objects.........................................................................30 ProvisioningType Enumeration Types.....................................................................................30 CopyType Enumeration Types...............................................................................................30 state Enumeration Types......................................................................................................31 DetailedState Enumeration Types..........................................................................................31 Policies Configuration Object...............................................................................................32 space Objects...................................................................................................................32 Create a Storage Volume.........................................................................................................33 Create Base Volumes..........................................................................................................33 Message Body Parameters..............................................................................................33 Responses....................................................................................................................35 Success...................................................................................................................35 Error Codes.............................................................................................................35 Create Snapshot Volumes........................................................................................................35 Message body parameters..................................................................................................35 Remove a Storage Volume.......................................................................................................36 Responses.........................................................................................................................36 Success Response..........................................................................................................36 Error Codes..................................................................................................................36 Query Volume Information.......................................................................................................36

10 Working with Virtual LUNs.......................................................................39


Configuration and Enumeration Objects....................................................................................39 VLUN portPos Configuration Object......................................................................................39 VLUNtype Enumeration.......................................................................................................39 VLUN multipathing Enumeration...........................................................................................39 VLUN failedPathPol Enumeration..........................................................................................40 Create a VLUN.......................................................................................................................40 URI..................................................................................................................................40 Request Body....................................................................................................................40 Return Status.....................................................................................................................41 Response Body..................................................................................................................41 Example...........................................................................................................................41 HTTP Request................................................................................................................41 HTTP Response.............................................................................................................42 Remove a VLUN.....................................................................................................................42 URI Parameters..................................................................................................................42 Responses.........................................................................................................................43
4 Contents

Success........................................................................................................................43 Error Codes..................................................................................................................43 Example...........................................................................................................................43 HTTP Request................................................................................................................43 HTTP Response.............................................................................................................43 Query VLUN Information.........................................................................................................43 Responses.........................................................................................................................43 Success........................................................................................................................43 JSON Objects in a VLUN Query................................................................................44 Example...........................................................................................................................45 HTTP Request................................................................................................................45 HTTP Response.............................................................................................................45

1 1 Support and Other Resources...................................................................47


Contacting HP........................................................................................................................47 HP 3PAR documentation..........................................................................................................47 Typographic conventions.........................................................................................................50 HP 3PAR branding information.................................................................................................50

12 Documentation feedback.........................................................................51

Contents

1 Introduction
This Developer's Guide describes how to write a client that uses the HP 3PAR Web Services API (HP 3PAR WSAPI) to manage HP 3PAR storage systems. HP 3PAR storage systems include both hardware components that store data, and software applications to manage data. The Application Program Interface (API) provides a more flexible and powerful way to perform storage management tasks than Command Line Interface (CLI) scripting or the HP 3PAR OS Management Console software. This API enables you to automate management of volumes, Common Provisioning Groups (CPGs), and Virtual LUNs (VLUNs).

About the WSAPI


The API consists of a server and a definition of the operations, inputs, and outputs of the API. The Software Development Kit (SDK) of the API includes a sample client that can be referenced for the development of customer-defined clients. Clients of the API interact with the server through HTTPS. For an overview of the supported HTTP methods, see Supported HTTP Methods (page 10) below.

Typographic Conventions
User Input
User-supplied text is marked as boldface and enclosed in angle brackets, as follows: https://<Storage System>:8080/api/v1/credentials/<session key> In this example, the user supplied text is:
Text <Storage System> <session key> Description The name of the server processing requests and sending responses. The session key. For more information on session keys, see Creating Credentials (page 12)

System Output
System-supplied variables are marked in italics and enclosed in angle brackets, as follows: /api/v1/volumes/<volume name> <volume name> in this case is the name of the newly created volume, returned in the HTTP Location header.

Getting Started
This section of the HP 3PAR Web Services API Developer's Guide shows how to configure the server. Included also is an introduction to the WSAPI commands and a summary of the items included in the HP 3PAR Web Services API Server SDK. It contains the following topics: Configuring the server About the SDK

Configuring the Server


The API server is part of the HP 3PAR OS 3.1.2 and will run on the HP 3PAR Storage Server. The server must be started with the startwsapi CLI command. It is possible to configure the server with setwsapi. To start the server, do the following: 1. In the Command Line Interface (CLI), enter the startwsapi command.

Introduction

NOTE: 2.

This command does not run by default.

To configure the server, enter the setwsapi command.

About the SDK


In addition to the WSAPI, HP provides an SDK for Java and Perl, available via download from software.hp.com.

Java SDK
The Java SDK includes: Core "storage-entity" classes representing the attributes of HP 3PAR storage system objects (CPGs, volumes, VLUNs) and input parameters for creating objects. An example client interface which demonstrates the use of JavaScript Object Notation (JSON) processors with the base classes. Example programs to illustrate the creation and query of base entities. These examples rely on the accessor and base packages.

Perl SDK
The Perl SDK includes: A module with methods for accessing the HP 3PAR storage system. Modules with mappings of the error codes and enumerated properties used by WSAPI. An example program that demonstrates creation, querying, and deleting of base entities.

About the SDK

2 Overview
The HP 3PAR Web Services API (WSAPI) makes it possible to manage storage volumes, Common Provisioning Groups (CPGs) and Virtual Logical Unit Numbers (VLUNs) through a series of HTTP or HTTPS requests. NOTE: For security reasons, HTTPS is the preferred choice and is used by default. Throughout this document, HTTP is used to refer to both. The behavior is the same using both protocols. Clients make HTTP requests to the server and receive HTTP replies. When input is provided, such as with the HTTP POST method, or when output is returned, the body of the messages are coded using JSON. The message body will be ignored for GET and DELETE operations. The WSAPI enables programmatic management of HP 3PAR storage servers. The clients access Web services at specified HTTPS locations that control the following volume management tasks: Creating and deleting volumes Creating snapshot volumes Querying all volumes Creating and deleting Common Provisioning Groups (CPGs) Querying all CPGs Creating and deleting VLUNs Querying all VLUNs

Tasks can be automated by developing a WSAPI client. Because the API is more formally defined, using it is preferable to scripts that use the HP 3PAR CLI, since those scripts will need to process CLI-generated text.

Overview

Protocol and Message Format


Clients communicate with the WSAPI server using HTTPS and data structures represented with JavaScript Object Notation (JSON). The supported JSON character encodings include the following formats: ASCII ISO-8859-1 US-ASCII UTF-8 UTF-16 UTF-32 UTF-16BE UTF-32BE UTF-16LE UTF-32LE

Client Headers
Client header information is required only when the client request has a message body. In these instances, the client must provide the HTTP Content-Type specifying application/json and the optional charset parameter. For example: application/json; charset=UTF-8 The HTTP requests that clients make to the API server include HTTP headers. The following table shows the required and optional HTTP headers. Optional headers, when present, must be one of the values listed in the Values column: Table 1 Headers Supported by the HP 3PAR Web Services API for Requests
Header Accept Description The response format the client can accept. Values One of the following: application/* application/json application/json* Accept-Language The response language the client can accept. One of the following: * en en* Content-Length The length of the content in bytes. The format of the body. Number of bytes Yes, for requests with a message body. Yes, for requests with a message body. Yes, except for a request to create credentials. No Required No

Content-Type

application/json

X-HP3PAR-WSAPI-SessionKey A key associated with the user that created credentials.

The result of a credentials creation request.

Protocol and Message Format

Examples
Querying CPGs When querying the CPGs, the client sends the following: GET /api/v1/cpgs HTTP/1.1 Accept: application/json Accept-Language: en X-HP3PAR-WSAPI-SessionKey: 1-c86aedb2e7e98b4119cd74b624b8576b-b06d2d50 Creating CPGs When creating a CPG, the client sends the following: POST /api/v1/cpgs HTTP/1.1 X-HP3PAR-WSAPI-SessionKey: 1-c86aedb2e7e98b4119cd74b624b8576b-b06d2d50 Accept: application/json Content-Type: application/json Content-Length: 27 { "name" : "t887-cpg" }

Server Headers
Table 2 HTTP headers Included by the Web Services API in Responses
HTTP Header Server Cache-Control Value HP3PAR-WSAPI no-cache Description The HP 3PAR Web Services API Server. Disables caching by mechanisms between the Web Services API server software and client (HTTP RFC 2616), for HTTP/1.0 and 1.1. Disables caching by mechanisms between the Web Services API server software and client (HTTP RFC 2616), for HTTP/1.0 and 1.1 Included when the message body, which will be in JSON format, is nonempty. The path portion of the URI of a newly created object, such as: /api/v1/volumes/foo Encoding is UTF-8 and percent encoded per RFC 3986. The date and time at which the message was originated, per RFC 2616.

Pragma

no-cache

Content-Type Location

application/json Varies. See the example in the Description column.

Date

Varies according to the date.

Supported HTTP Methods


This section summarizes the HTTP methods currently supported by the HP 3PAR WSAPI. These include:

GET
The GET method retrieves information identified by the Request-URI.

10

Overview

POST
The POST method requests an object described by the body of the request be created in the collection identified by the URI.

DELETE
The DELETE method requests that the server deletes the resource identified by the Request-URI.

General URI Format


All operations of the API are performed using an HTTP method (GET, POST, or DELETE) and a Uniform Resource Identifier (URI). In this example, the URI corresponds to the volume named projectXvol residing on the HP 3PAR storage system with the hostname storsys1.example.com: https://storsys1.example.com:8080/api/v1/volumes/projectXvol

General URI Format

1 1

3 System Access
This chapter discusses the use of session keys with the WSAPI. Session keys enable access to the HTTP methods for a single session.

Creating Credentials
In order to use the Web Services, you must create a session key by providing a username and password. The username and password are the same that you would use to access the HP 3PAR storage server through the Command Line Interface (CLI) or the Management Console (MC). The authorization carries the same user permissions for the WSAPI as for the CLI/MC, in that you have permission to perform the same operations through the API (where available) as you would with the CLI or MC. 1. Create a session key using the HTTP POST method with a URL of the following format: https://<Storage System>:8080/api/v1/credentials 2. The message body of the request is a JavaScript Object Notation (JSON) object with the following members:
Member user password JSON type string string Value Username User's password

NOTE:

For error output for this and other conditions, see Status and Error Codes (page 14).

About Multiple Session Keys


A multi-threaded client application can use one session key in multiple threads concurrently. However, the requested operations will be serialized by the server. When true concurrency is needed, a client can create a session key for each concurrent thread. NOTE: This increases server resource usage and should be kept to a small number to avoid affecting server performance.

About Session Key Security


Because session keys allow access to the storage server, client applications should not display session keys or otherwise make them visible to end users. Revealing a session key is similar to revealing a password in that an unauthorized person who obtains a session key can use it to access the storage server until the key is deleted.

Creating a Session Key


Except for creating and deleting a session key, the session key is required for all operations and is passed in an HTTP header with the name X-HP3PAR-WSAPI-SessionKey. Each session key is associated with the IP address of the client that originally requested it, and subsequent use is restricted to requests from that same IP address. An example of creating a session key using cURL (a command-line utility available for most Linux distributions) is as follows: 1. Enter the following: curl -k -H "Accept:application/json" -H "Content-Type:application/json" --data-binary '{"user":"example","password":"example"}'

12

System Access

https://storsys1.example.com:8080/api/v1/credentials 2. The system returns the key in the JSON content of the response: {"key":"1-c86aedb2e7e98b4119cd74b624b8576b-b06d2d50"}

Deleting a Session Key


When a client is finished making requests to the server it should delete the session keys it created. This frees up server resources and allows for better server performance. NOTE: 1. Unused session keys expire automatically after fifteen minutes.

To delete a session key, send a request with the HTTP DELETE method and the URI: https://<Storage System>:8080/api/v1/credentials/<session key> NOTE: The <session key> is the key that is returned in the process of creating a session key. For more information, see Creating Credentials (page 12).

2.

A successful session key deletion returns status code 200 OK. There is no message body. NOTE: An error condition returns an error object as a message body.

Example
An example of deleting credentials using cURL is: curl -X DELETE -H "Accept: application/json" https://storsys1.example.com:8080 /api/v1/credentials/1-c86aedb2e7e98b41-b06d2d50

Getting Version Information


A client of the WSAPI can query the API server for version information by using a GET request on a URI in the following form: https://<Storage System>:8080/api NOTE: A session key is not needed to make the request.

Success
On success, a JSON object is returned that describes the interface version provided by the API server, as described in the following table:
member major minor build JSON type number number number description The version major number. The version minor number. A build number not meant to be interpreted by clients, but useful for identifying specific builds of versions for defect reports or support requests.

Deleting a Session Key

13

4 Status and Error Codes


When an operation is successful, the system returns one of the following HTTP status codes: 200 OK 201 Created

When an operation fails, one of several HTTP status codes is returned. Also, the message body contains a JSON object with information specific to the HP 3PAR WSAPI. The JSON object contains the members code, desc, and, when relevant, ref. The code member is a number and the rest are strings. The JSON object contains the following members:

The code Member


Just as is the case with CLI text, the text in the desc member (see below) is subject to change and cannot be relied upon. To avoid that problem, the WSAPI provides a reliable code for an error. HP recommends avoiding parsing the desc member and using it only for display purposes. For example, the desc member for an error may change from No snap CPG specified to Error: The volume must have a snap CPG in one storage system version to another. The associated WSAPI error code will not change. The Error code member is a JSON numeric type. Only codes that are defined in the table below will be returned.

Codes Listing
For applications that change behavior based on errors, only the code member should be relied on. For ease of reading documentation, a symbol is defined for each numeric code, but the symbol is not part of the API. The numeric value is the contract between client and server. The codes are described in the following table: Table 3 API General Error Codes Provided by the code Member
API error code 1 2 3 4 5 6 7 8 9 API error symbol INT_SERV_ERR Description HTTP code

An internal error has occurred in 500 Internal the server. Server Error An SSL protocol violation has occurred. 400 Bad Request

INV_SSL INPUT_EOF INPUT_TOO_LONG

The client has not sent a complete 400 Bad Request request. The client has sent a request that 413 Request is too long. Entity Too Large The username or password is invalid. The client request has an invalid session key. 403 Forbidden 403 Forbidden

INV_USER_PASS INV_SESS_KEY TIMEOUT

The client did not send or receive 408 Request in time. Timeout The client request has an unsupported HTTP method. 505 HTTP Version Not Supported

UNSUP_HTTP

UNSUP_OP

The resource does not support the 501 Not method. Implemented

14

Status and Error Codes

Table 3 API General Error Codes Provided by the code Member (continued)
API error code 1 1 12 13 14 15 16 17 18 19 21 22 23 24 API error symbol URI_RES_NOT_FOUND INV_INPUT PERM_DENIED EXISTENT_CPG NON_EXISTENT_CPG EXISTENT_HOST NON_EXISTENT_HOST EXISTENT_LUN NON_EXISTENT_VLUN BAD_PORT_TYPE EXISTENT_VOL NON_EXISTENT_VOL NO_SPACE Description The resource of the request does not exist. The client request contains an invalid value. Permission denied, insufficient privileges. The CPG already exists. The CPG does not exist. The host already exists. The host does not exist. The VLUN already exists. The VLUN does not exist. Attempt to create VLUN with invalid port type. The storage volume already exists. The storage volume does not exist. Not enough space is available for the operation. This varies based on the following circumstances: In volume creation, when the CPG contains insufficient space for the specified volume size. In CPG creation, when the storage system's hardware configuration does not support the requested LD layout. In CPG creation, when the chunklets that are required for the requested LD layout are in the process of being cleaned. 25 27 28 29 31 32 33 HAS_RO_CHILD RETAINED TOO_LARGE OTHER SVC_UNAVAIL The volume has a read-only child. 409 Conflict Volume retention time has not expired. The client request contains a value that is too large. A more specific error could not be determined. 409 Conflict 400 Bad Request 400 Bad Request HTTP code 404 Not Found 400 Bad Request 403 Forbidden 409 Conflict 404 Not Found 409 Conflict 404 Not Found 409 Conflict 404 Not Found 400 Bad Request 409 Conflict 404 Not Found 400 Bad Request

The server has reached its 503 Service maximum number of connections. Unavailable The Virtual Volume (VV) has a child VV2. The VV has no snapshot CPG configured. 409 Conflict 409 Conflict

HAS_CHILD NO_SNAP_CPG

The code Member

15

Table 3 API General Error Codes Provided by the code Member (continued)
API error code 34 35 API error symbol IN_USE UNSUP_REPRESENTATION Description The resource is in use. The representation specified in client's Accept header is not supported. HTTP code 409 Conflict 406 Not Acceptable

36

UNSUP_LANGUAGE

The language specified in client's 406 Not Accept-Language header is not Acceptable supported. Invalid RAID set size. The domain does not exist. 400 Bad Request 404 Not Found

37 38 39

INV_SET_SIZE NON_EXISTENT_DOMAIN INV_INPUT_WRONG_TYPE

A JSON input object contains a 400 Bad Request name-value pair where the type of the value differs from what is expected (e.g. a number is found where a string is expected). Ref contains the name of the name-value pair. A JSON input object is missing a 400 Bad Request required name-value pair. Ref contains the expected name. A JSON input object contains 400 Bad Request more than one name-value pair with the same name. Ref contains the name. A JSON input object contains a 400 Bad Request name-value pair with a name that is unrecognized. Ref contains the name. A JSON input object contains a name-value pair with a numeric value that exceeds the expected range. Ref contains the name 400 Bad Request

40

INV_INPUT_MISSING_REQUIRED

41

INV_INPUT_DUP_NAME

42

INV_INPUT_UNREC_NAME

43

INV_INPUT_EXCEEDS_RANGE

44

INV_INPUT_PARAM_CONFLICT

A JSON input object contains a 400 Bad Request name-value pair that cannot be present with another name-value parameter that is present. Ref contains the name A JSON input object contains a name-value pair with an empty string (distinct from a null string) where a string of length greater than zero is required. 400 Bad Request

45

INV_INPUT_EMPTY_STR

46

INV_INPUT_BAD_ENUM_VALUE

A JSON input object contains an 400 Bad Request enum property with a value thats not in the valid range. The allocation warning level is higher than the allocation limit. 400 Bad Request

47 48 49

INV_INPUT_WARN_GT_LIMIT INV_INPUT_USR_ALRT_NON_TPVV INV_INPUT_RETAIN_GT_EXPIRE

User space allocation alerts only 400 Bad Request valid with TPVV. The VV retain time is greater than 400 Bad Request the expiration time.

16

Status and Error Codes

Table 3 API General Error Codes Provided by the code Member (continued)
API error code 50 51 API error symbol INV_INPUT_VV_POLICY UNSUP_CONTENT Description HTTP code

An invalid policy (e.g., system or 400 Bad Request caching) is specified for VV. Unsupported content (e.g., as specified in Content-Type HTTP header). 415 Unsupported Media Type

52 53 54 55 56 57 58 59 60

INV_INPUT_NOT_JSON_OBJ BAD_CPG_PATTERN MISSING_VLUN_EXPORT_INFO INV_INPUT_PORT_SPECIFICATION INV_URL_PERCENT_ENCODING INV_INPUT_EXCEEDS_LENGTH INV_INPUT_TIME EXISTENT_ID JSON_SYNTAX_ERR

A JSON object was expected but 400 Bad Request another JSON type was found. A pattern in a CPG specifies illegal values. 400 Bad Request

Missing both hostname and port 400 Bad Request position. Incorrect port specification. Invalid URL percent encoding. Invalid input: string length exceeds limit. Invalid time specified. An ID exists. 400 Bad Request 400 Bad Request 400 Bad Request 400 Bad Request 409 Conflict

JSON syntax error. When the 400 Bad Request error is associated with an object member, ref contains the name of the member. Too many levels of nesting in JSON; numbers too large to be represented; length restrictions exceeded. When the error is associated with an object member, ref contains the name of the member. Invalid HTTP header syntax. A request body contains a sequence of characters that is invalid for the supported UTF encodings. A POST request is missing a JSON request body. The request line (first line) of an HTTP request does not meet the form specified for Request-Line in RFC 2616. 400 Bad Request

61

JSON_NOT_SUPPORTED

62 63

INV_HTTP_HEADER INV_UTF

400 Bad Request 400 Bad Request

64 65

INV_INPUT_NO_REQ INV_HTTP_REQ

400 Bad Request 400 Bad Request

66

INV_URI

The URI is not absolute, contains 400 Bad Request characters not allowed in a URI, contains invalid percent encoding, or, after percent decoding, contains an invalid UTF-8 character sequence. A POST request contains an action member with an invalid value. 400 Bad Request

67

INV_POST_ACTION

The code Member

17

Table 3 API General Error Codes Provided by the code Member (continued)
API error code 68 API error symbol SYS_SVC_NOT_READY Description HTTP code

Services that the system depends 503 Service on in order to process the Unavailable requested operation are not ready. Input contains one or more illegal 400 Bad Request characters. System is not licensed for this feature or functionality. 403 Forbidden

69 70

INV_INPUT_ILLEGAL_CHAR UNLICENSED_FEATURE

The desc Member


The desc member provides supplementary information that helps explain the reason for the error code. NOTE: The text in this member is subject to change between releases.

Examples
Examples of desc are: {"code":28,"desc":"client request contains values that are too large} {"code":24,"desc":"insufficient space for requested operation"}

The ref Member


In the event of an error that may occur for several reasons, the ref member may specify the reason for the error. For example, if the client were to send an incorrect value for a JSON member then the server may be able to identify which member had the incorrect value. NOTE: There are errors in which a ref member is not necessary or useful. So, it may not appear for all errors.

Example
curl -k -H "Accept:application/bogus" -H "X-HP3PAR-WSAPI-SessionKey:9-1786eb905dabf39a4d564e799ea4360c-8053d24f" https://storsys1.example.com:8080 '{"code":35,"desc":"unsupported representation scheme","ref":"Accept"}'

HTTP Error Codes


In addition to the API-specific error information, the response to a client request that has failed will include an HTTP error code. Each API error code is associated with an HTTP status code as shown in API General Error Codes Provided by the code Member (page 14). The following is an example of a bad client request, followed by the server response showing how the API error code 5 is associated with HTTP status code 403:

Request
POST /api/v1/credentials HTTP/1.1 Content-Type: application/json Host: storsys1:8080 Content-Length: 44
18 Status and Error Codes

Expect: 100-continue Accept: application/json {"password":"not bobs password","user":"bob"}

Response
HTTP/1.1 403 Forbidden Date: Tue, Wed, 31 Oct 2012 22:15:52 GMT Server: hp3par-wsapi Content-Type: application/json Connection: close {"code":5,"desc":"invalid user or password"}

HTTP Error Codes

19

5 Request Input and Optional Members


For some API operations, such as POST, the client passes a JSON object as the message body. The JSON object includes required parameters for the operation and may include optional parameters. Most operations have optional parameters. For example, to create a volume, only the name of the volume, the name of the CPG that provides disk space for the volume, and the size of the volume are required. Optional parameters include the ID of the volume and a comment. When constructing a JSON object, optional members may be omitted or set to values that indicate the server should ignore them. The client sets only the fields of interest. The JSON object need not include all members. A client can perform one of two possible operations when creating the JSON object: Include only the optional members required for the operation, or Include a member that is not required, but with a value that means it should be ignored. When writing a client in a language that provides services for serializing a class into a JSON object, it is convenient to only have a single class that represents all required or optional parameters. The following chapters will specify the special values to use to ignore a member.

20

Request Input and Optional Members

6 Enumerations
Some properties have values from a fixed set of limited values. For example, the state property of a Storage Volume can be one of Normal, Degraded or Failed. When properties like these are present in a JSON object, they are represented numerically. In addition to the values shown in the definition of an enumeration, each enumeration can also have the value of -1, meaning that the API server has encountered a value that it does not recognize and therefore cannot assign a value from the valid set. This usually means a defect in the API server. The values defined for an enumeration start with 1; the value 0 is unused. When using tools that deserialize JSON into a class, this allows an omitted property of enumeration type to be detected, since the member will not be assigned a non-zero value of a property and will retain its default or pre-set value of 0. For enumerations, the symbols used in this document are for convenience in referring to values of enumerations, but are not part of the WSAPI. Integer values representing the symbols appear in JSON objects. Clients can use any symbols with the integers.

21

7 JSON Types and API Types


JSON uses primitive types defined by IETF RFC 4627, including: String Number Boolean null

The properties returned in JSON output objects and the parameters provided in JSON input objects use JSON primitive types with additional restrictions on valid values. Restrictions on values or format are given names that appear in the Type column in the table below. These API types are referenced in the sections below describing JSON input and output. Table 4 API Types
Type 8601 Description JSON string with time in ISO 8601 format: YYYY-MM-DDThh:mm:ssTZD , where TZD is Z or +hh:mm or -hh:mm NOTE: igint32 epoch For more information, see http://www.w3.org/TR/NOTE-datetime

JSON number restricted to a 32-bit signed integer where negative values are ignored by the server, and treated as if not present. The number of seconds since 01/01/1970 GMT. Also known as Unix epoch.

int32 name31

JSON number restricted to a 32-bit signed integer JSON string of 31 or fewer characters, in which the following characters are allowed: a-z A-Z 0-9 . (dot) - (dash) NOTE: Dash (-) is disallowed as the first character. A name of 0 characters is represented in JSON as the empty string . An unset name is represented in JSON as null.

print511 uint32 WWN

JSON string of 51 1 or fewer characters. JSON number restricted to a 32-bit unsigned number. JSON string of 16 or 32 characters. For port and FC Host it is always 16 characters. Possible characters are: 09 af AF

JSON members suffixed with MiB represent size or space in mebibtyes where 1 MiB = 1,048,576 bytes (2^20 bytes). Members suffixed with MB represent size or space in megabytes where 1MB = 1,000,000 bytes (10^6 bytes). JSON members suffixed with Pct mean percent.

22

JSON Types and API Types

8 Working with Common Provisioning Groups


You can use a Common Provisioning Group (CPG) to create a virtual pool of logical disks that allows virtual volumes to share the resources of the CPG and allocates space on demand. You can create fully-provisioned virtual volumes and Thinly-Provisioned Virtual Volumes (TPVVs) that draw space from the logical disk pool. You can use this chapter to: Create a CPG Remove a CPG Query a CPG

CPG Enumeration and Configuration Objects


Many of the CPG operation objects have enumerations or contain sub-objects as detailed in the following sections.

LDLayout Object
Table 5 LDLayout object
Member RAIDType setSize HA JSON type number number number API type RAIDType enum igint32 HA enum Description Ignored Values

Specifies the RAID type for the Negative values logical disk. Specifies the set size in the number of chunklets. Negative values

Specifies that the layout must Negative values support the failure of one port pair, one cage, or one magazine. Specifies the chunklet location Negative values preference characteristics. Specifies patterns for candidate disks. None

chunkletPosPref number diskPatterns array of objects

chunkletPosPref enum array of diskPatterns objects

RAIDType Enumeration
Table 6 RAIDType enumeration
Symbol R0 R1 R5 R6 Value 1 2 3 4 Description RAID level 0 RAID level 1 RAID level 5 RAID level 6

CPG Enumeration and Configuration Objects

23

HA Enumeration
Table 7 HA Enumeration
Symbol Port cage mag Value 1 2 3 Description Support failure of a port. Support failure of a drive cage. Support failure of a drive magazine.

chunkletPosPref Enumeration
Table 8 chunkletPosPref enumeration
Symbol first last Value 1 2 Description Lowest numbered available chunklets, where transfer rate is the fastest. Highest numbered available chunklets, where transfer rate is the slowest.

diskPatterns Object
Table 9 diskPatterns Object
Symbol nodeList Value string Description Specifies one or more nodes. Nodes are identified by one or more integers. Multiple nodes are separated with a single comma (1,2,3). A range of nodes is separated with a hyphen (07). The primary path of the disks must be on the specified node number. Ignored values Null

slotList

string

Specifies one or more PCI slots. Slots are Null identified by one or more integers. Multiple slots are separated with a single comma (1,2,3). A range of slots is separated with a hyphen (07). The primary path of the disks must be on the specified PCI slot number(s). Specifies one or more ports. Ports are identified Null by one or more integers. Multiple ports are separated with a single comma (1,2,3). A range of ports is separated with a hyphen (04). The primary path of the disks must be on the specified port number(s). Specifies one or more drive cages. Drive cages Null are identified by one or more integers. Multiple drive cages are separated with a single comma (1,2,3). A range of drive cages is separated with a hyphen (03). The specified drive cage(s) must contain disks. Specifies one or more drive magazines. Drive Null magazines are identified by one or more integers. Multiple drive magazines are separated with a single comma (1,2,3). A range of drive magazines is separated with a hyphen (07). The specified magazine(s) must contain disks. Specifies one or more disk positions within a Null drive magazine. Disk positions are identified by one or more integers. Multiple disk positions

portList

string

cageList

string

magList

string

diskPosList

string

24

Working with Common Provisioning Groups

Table 9 diskPatterns Object (continued)


Symbol Value Description are separated with a single comma (1,2,3). A range of disk positions is separated with a hyphen (03). The specified portion(s) must contain disks. diskList string Specifies one or more physical disks. Disks are Null identified by one or more integers. Multiple disks are separated with a single comma (1,2,3). A range of disks is separated with a hyphen (03). Disks must match the specified ID(s). Specifies that physical disks with total chunklets Negative greater than the number specified be selected. values Specifies that physical disks with total chunklets Negative less than the number specified be selected. values Specifies that physical disks with free chunklets Negative less than the number specified be selected. values Specifies that physical disks with free chunklets Negative greater than the number specified be selected. values Specifies that PDs identified by their models are Null array selected. elements Specifies that physical disks must have the specified device type. See diskType enumeration. Disks must be of the specified speed. Negative values Negative values Ignored values

totalChunkletsGreaterThan totalChunkletsLessThan freeChunkletsGreaterThan freeChunkletsLessThan diskModels diskType

number number number number array of string number

RPM

number

diskType Enumeration
Table 10 diskType Enumeration
Symbol FC NL SSD Value 1 2 3 Description Fibre Channel Near Line SSD

Space Usage Objects


Table 1 1 SDUsage, SAUsage, and UsrUsage Objects
Member totalMiB rawTotalMiB usedMiB rawUsedMiB JSON type number number number number API type uint32 uint32 uint32 uint32 Description Total logical disk space in MiB. Total physical (raw) logical disk space in MiB. Amount of logical disk used, in MiB. Amount of physical (raw) logical disk used, in MiB.

CPG Enumeration and Configuration Objects

25

Growth Objects
Table 12 SAGrowth and SDGrowth Objects
Member warningMiB limitMiB incrementMiB LDLayout JSON type number number number object API type uint32 uint32 uint32 LDLayout object Description Threshold of used logical disk space, when exceeded, results in a warning alert. The auto-grow operation is limited to the specified storage amount that sets the growth limit. The growth increment, the amount of logical disk storage created on each auto-grow operation. Logical disk types to be used for this CPG. See LDLayout object for member details.

state Enumeration
Table 13 state Enumeration
Symbol normal degraded failed Value 1 2 3 Description The CPG is operating normally. The CPG is in a degraded state. The CPG is operating abnormally.

detailed state Enumeration


DetailedState enumeration values are used in multiple arrays including failedStates, degradedStates, and additionalStates. Details of the CPG's state are enumerated in the following table: Table 14 detailedState Enumeration
Symbol SALimitReached SDLimitReached SAGrowFailed SDGrowFailed SAWarnReached SDWarnReached Invalid Value 1 2 3 4 5 6 7 Description Admin space at limit. Copy space at limit. Admin space grow failed. Copy space grow failed. Admin space at warning level. Copy space at warning level. Invalid

Create a CPG
This topic describes how to create a CPG. You create a CPG with the HTTP POST method to the following URI: https://<Storage System>:8080/api/v1/cpgs NOTE: Any user with Super or Edit role, or any role granted with the cpg_create right can perform this operation.

26

Working with Common Provisioning Groups

Message Body Parameters


Table 15 CPG creation Members
Member name growthIncrementMiB JSON type string number API Type name31 igint32 Description Specifies the name of the CPG. Ignored values None (Required)

Specifies the growth Negative values increment, the amount of logical disk storage created on each auto-grow operation. Specifies that the auto-grow Negative values operation is limited to the specified storage amount that sets the growth limit. Specifies that the threshold of used logical disk space, in MiB, when exceeded results in a warning alert. Specifies the name of the domain in which the object will reside. Specifies Logical Disk types to be used for this CPG. Negative values

growthLimitMiB

number

igint32

usedLDWarningAlertMiB number

igint32

domain

string

name31

Null

LDLayout

object

LDLayout object

None

Responses
Success
A successful operation returns status code 201 Created. There is no message body. On successful creation of the CPG, the Location response header contains the URI for the newly created CPG in the following format: /api/v1/cpgs/<cpg name>

Error Codes
If there is an error condition, the system returns one of the following error codes, or a general error code listed in API General Error Codes Provided by the code Member (page 14):
API error NON_EXISTENT_DOMAIN EXISTENT_CPG BAD_CPG_PATTERN INV_SET_SIZE HTTP code 404 Not Found 409 Conflict 400 Bad Request 400 Bad Request Description Domain doesnt exist CPG already exists A pattern in a CPG specifies illegal values Invalid RAID set size

Remove a CPG
A CPG is removed with the HTTP DELETE method to the URI: https://<Storage System>:8080/api/v1/<cpg name>

Remove a CPG

27

Responses
Success
Status code 200 OK is returned with no message body.

Errors
API error NON_EXISTENT_CPG IN_USE HTTP code 404 Not Found 408 Conflict Description CPG not found The CPG cannot be removed because it is in use by a volume

Query CPG Information


Querying for CPG information is done with the HTTP GET method on the URI with no message body: https://<Storage System>:8080/api/v1/cpgs The body is an object with total and members as described below. As is the case with all collection queries, the total object is the number of objects in the collection. The members object is a JSON array of zero or more JSON objects as listed in the following table: Table 16 JSON objects for CPG Queries
Member id uuid name domain warningPct JSON type number string string string number API Type uint32 uuid string name31 name31 uint32 Description CPG ID UUID that was automatically assigned to the CPG at creation. CPG name Domain that the CPG belongs to Percentage usage at which to issue an alert. This is set with the CLI createcpg aw parameter which is deprecated and not exposed by this API Number of Thinly Provisioned Virtual Volumes allocated in the CPG. Number of Fully Provisioned Virtual Volumes allocated in the CPG. User data space usage Snapshot administration usage Snapshot data space usage Snapshot administration space auto-growth parameters Snapshot data space auto-growth parameters Overall state of the CPG Detailed state of CPG

numTPVVs numFPVVs UsrUsage SAUsage SDUsage SAGrowth SDGrowth state failedStates

number number object object object object object number array of numbers

uint32 uint32 UsrUsage object SAUsage object SDUsage object SAGrowth object SDGrowth object state enum array of DetailedState enum

28

Working with Common Provisioning Groups

Table 16 JSON objects for CPG Queries (continued)


Member JSON type API Type array of DetailedState enum array of DetailedState enum Description Detailed state of CPG

degradedStates array of numbers additionalStates array of numbers

Detailed state of CPG

Responses
Success
On success, status code 200: OK is returned.

Query CPG Information

29

9 Working with Storage Volumes


This chapter describes how to manage storage volumes. The sections apply to creation, modification, and query operations on storage volumes. You can perform the following operations on storage volumes: Query storage volume Create a storage volume Remove a storage volume

Queries for storage volume information are created with the HTTP GET method on a URI, with no message body. The syntax is as follows: https://<Storage System>:8080/api/v1/volumes Unless an error occurs, the response includes a message body with JSON objects total and members. The object members will contain an array of zero or more JSON objects, shown below as the Output object. The total is the number of objects in the members array.

Volume Enumeration and Configuration Objects


Several enumerations and configuration objects are used for the various volume API operations. These are described in the following sections:

ProvisioningType Enumeration Types


Table 17 Enumeration for the provisioningType JSON Object
Symbol full Value 1 Description Fully provisioned VV, either with no snapshot space or with statically allocated snapshot space. Also, a commonly-provisioned VV where the user space is fully provisioned and the snapshot space is associated with the snapCPG property. Thin provisioned VV, with space for the base volume allocated from the Usr space that is associated with the userCPG property. Also includes old-style thin provisioned VV (created on a 2.2.4 release or earlier) where both the base VV and snapshot data are allocated from the Snap space associated with userCPG. The VV is a snapshot (Type vcopy) and its space is provisioned from the base volume's snapshot space. Remote volume admitted into the local storage system. Unknown

tpvv

snp peer unknown

3 4 5

CopyType Enumeration Types


Table 18 Enumeration for theCopyType JSON Object
Symbol base physicalCopy virtualCopy Value 1 2 3 Description Base volume (not a copy) Physical copy (full copy) Snapshot copy (virtual copy)

30

Working with Storage Volumes

state Enumeration Types


Table 19 Volume state Enumeration
Symbol normal degraded failed Value 1 2 3 Description The virtual volume (VV) is operating normally VV is in degraded state VV is operating abnormally

DetailedState Enumeration Types


Details of the volume's state are enumerated in the following table. DetailedState is not a JSON object itself, but rather an enumeration that applies to multiple JSON objects, including failedStates, degradedStates, and additionalStates. Table 20 Volume DetailedState Enumeration
Symbol LDsNotStarted NotStarted NeedsCheck NeedsMaintCheck InternalConsistencyError SnapdataIinvalid Preserved Stale CopyFailed DegradedAvail DegradedPerf Promoting CopyTarget ResyncTarget Tuning Closing Removing RemovingRetry Creating CopySource Importing Converting Invalid Value 1 2 3 4 5 6 7 8 9 10 1 1 12 13 14 15 16 17 18 19 20 21 22 23 Description LDs Not Started. VV Not Started. Needs to be checked for consistency Maintenance Check Required. Internal Consistency Error. Snapshot data Invalid. One or more sets of an LD is unavailable due to missing chunklets and the remaining VV data is preserved. Parts of the VV contain old data because of a copy-on-write operation. A promote or copy to this volume failed. Degraded due to availability Degraded due to performance Volume is currently the target of a promote. Volume is currently the target of a physical copy. Volume is currently the target of a resync copy. Volume is tuning. Volume is closing. Volume is removing. Volume is retrying a remove. Volume is creating. Copy source. Volume is importing. Volume is converting. Invalid

Volume Enumeration and Configuration Objects

31

Policies Configuration Object


Table 21 Policies Object
Symbol staleSS Value Boolean Description true: Stale snapshots. If there is no space for a copy-on-write operation, the snapshot is allowed to go stale but the host write can proceed without an error. false: No stale snapshots. If there is no space for a copy-on-write operation, the host write will fail. oneHost Boolean true: This indicates a volume is constrained to export to one host or one host cluster. false: This indicates a volume exported to multiple hosts for use by a cluster-aware application, or when "port presents" VLUNs are used zeroDetect Boolean true: This indicates that the storage system will scan for zeros in the incoming write data. false: This indicates that the storage system will not scan for zeros in the incoming write data. system Boolean true: Special volume used by the system. false: Normal user volume caching Boolean This is a read-only policy and cannot be set. true: This indicates that the storage system is enabled for write caching, read caching, and read ahead for the volume false: This indicates that the storage system is disabled for write caching, read caching, and read ahead for the volume.

space Objects
The volume space is specified by the following three sub-objects, each of which uses the same members: adminSpace snapshotSpace userSpace

The members are listed in the following table: Table 22 Members of the JSON Volume Space Objects adminSpace
Member reservedMiB rawReservedMiB usedMiB freeMiB JSON type number number number number API Type uint32 uint32 uint32 uint32 Description Reserved space in MiB Raw reserved space in MiB Used space in MiB Free space in MiB

32

Working with Storage Volumes

Create a Storage Volume


This section contains information on creating volumes, and includes the following topics: Create base volumes Create snapshot volumes

When creating a snapshot volume, the message body is a JSON object with two members, action and parameters. The action member is a string with the value "createSnapshot". The parameters member is a JSON object with members described in Create Snapshot Volumes (page 35). NOTE: Any user with Super or Edit role, or any role granted with the volumes_create right can perform this operation.

Create Base Volumes


A Storage Volume is created with the HTTP POST method to the URI: https://<Storage System>:8080/api/v1/volumes NOTE: The <Storage System> will be replaced with the actual storage systems hostname or IP address.

Message Body Parameters


The message body is a JSON object with the members shown in the following tables. Most of the members are optional. When creating a snapshot volume, isCopy is set to true and name and copyOfName are required. The definition of members can be found in the CLI Reference Manual or in the column help for the CLI command createvv
Member name JSON Type API Type string name31 Description Ignored values

Specifies a VV name up None (Required) to 31 characters in length. Specifies the name of the None (Required) CPG from which the volume user space will be allocated. Specifies the size for the None (Required) volume in MiB. The volume size is rounded up to the next multiple of 256 MiB. Specifies the ID of the volume. If not specified, the next available ID is chosen. Negative values

cpg

string

name31

sizeMiB

number

uint32

id

number

igint32

comment

string

print51 1

Specifies any additional None information up to 51 1 characters for the volume. Specifies virtual volume policies. None except caching and system which are ignored if false.

policies

object

Policies object

snapCPG

string

name31

Specifies the name of the None CPG from which the snapshot space will be allocated.

Create a Storage Volume

33

Member ssSpcAllocWarningPct

JSON Type API Type number igint32

Description

Ignored values

Enables a snapshot Negative values. space allocation warning. A warning alert is generated when the reserved snapshot space of the virtual volume exceeds the indicated percentage of the virtual volume size. Sets a snapshot space Negative values allocation limit. The snapshot space of the virtual volume is prevented from growing beyond the indicated percentage of the virtual volume size. true: Create TPVV false: (default) Create FPVV None

ssSpcAllocLimitPct

number

igint32

tpvv

Boolean

Boolean

usrSpcAllocWarningPct

number

igint32

This option enables user Negative values space allocation warning. It specifies that a warning alert is generated when the reserved user space of the TPVV exceeds the specified percentage of the virtual volume size. this option sets the user Negative values space allocation limit. The user space of the TPVV is prevented from growing beyond the indicated percentage of the virtual volume size. After this size is reached, any new writes to the virtual volume will fail. Specifies the relative Negative values time from the current time that the value will expire. Value is a positive integer with a range of 1 - 43,800 hours (1825 days). Specifies the amount of Negative values time relative to the current time that the volume will be retained. Value is a positive integer with a range of 1 - 43,800 hours (1825 days).

usrSpcAllocLimitPct

number

igint32

expirationHours

number

igint32

retentionHours

number

igint32

34

Working with Storage Volumes

Responses
Success A successful operation returns status code 200 OK. There is no message body. On successful creation of the volume, the Location response header, contains the URI for the newly created volume in the following format: /api/v1/volumes/<volume name> Error Codes An error condition returns one of the following:
API error code EXISTENT_SV TOO_LARGE status code 409 Conflict 400 Bad Request Description The volume already exists Volume size above architectural limit

Create Snapshot Volumes


A snapshot is created with the HTTP POST method to the URI: https://<Storage System>:8080/api/v1/volumes/<volume name> <volume name> is the name of the volume being copied.

Message body parameters


The message body is a JSON object with two members, action and parameters. The action member is a string with the value "createSnapshot" and the parameters member is a JSON object with members described below.
Member name id JSON Type string number API Type name31 igint32 Description Specifies a snapshot VV name up to 31 characters in length. Specifies the ID of the volume. If not specified, the next available ID is chosen. Specifies any additional information up to 51 1 characters for the volume. true: Specifies that the copied volume is read-only. false: (default) The volume is read-write. expirationHours number igint32 Specifies the relative time from the current time that the volume will expire. Value is a positive integer and in the range of 143,800 hours, or 1825 days. Specifies the relative time from the current time that the volume will expire. Value is a positive integer and in the range of 143,800 hours, or 1825 days. Negative values Ignored values None (Required) Negative values

comment readOnly

string Boolean

print51 1 Boolean

None None

retentionHours number

igint32

Negative values

Create Snapshot Volumes

35

Remove a Storage Volume


A volume is removed with the HTTP DELETE method to the URI with no message body: https://<server>/api/v1/volumes/<volume>

Responses
Success Response
A successful removal returns the following code: status code 200: OK

Error Codes
An error returns one of the following:
API error code status code Description The volume does not exist Volume retention time has not expired Volume has read-only child

NON_EXISTENT_VOL 404 Not Found RETAINED HAS_RO_CHILD 403 Forbidden 403 Forbidden

Query Volume Information


Querying for Storage Volume information is done with the HTTP GET method on the URI, with no message body: https://<Storage System>:8080/api/v1/volumes Unless an internal server error occurs, the response includes a message body that returns an object that has a total member and a members member with members being the array of objects. one for each volume on the system. These objects are described in the following table: Table 23 JSON objects for Volume Queries
Member id uuid name domain provisioningType copyType copyOf JSON type number string string string number number string API type int32 uuid string name31 name31 provisioningType enum copyType enum name31 Description VV identifier UUID that was automatically assigned to the volume at creation. VV name VV domain The provisioning for the VV. Indicates the copy type of the VV. If the VV is a physical copy or virtual copy of another VV, this field indicates the VV that this VV is a copy of. The ID of the VV that is the base VV (at the root of the snapshot tree) for the VV. true: Read only false: Read and write allowed. state number state enum State of the VV.

baseId

number

uint32

readOnly

Boolean

Boolean

36

Working with Storage Volumes

Table 23 JSON objects for Volume Queries (continued)


Member failedStates degradedStates additionalStates adminSpace snapshotSpace userSpace sizeMiB parentId JSON type Array of numbers Array of numbers Array of numbers Object Object Object number number API type Array of DetailedState enum Array of State enum Array of DetailedState enum Space Space Space uint32 int32 Description Detailed state of VV. Detailed state of VV. Detailed state of VV. Admin space in MiB. Snapshot space in MiB. User space in MiB . Virtual size of volume in MiB (1024^2 bytes). ID of the parent in the snapshot tree (not necessarily same as the CopyOf VV). ID of the read-only child VV in the snapshot tree. Id of the read-write child VV in the snapshot tree. ID of the Physical Parent. Valid only for a physical copy. Volume World Wide Name. The time when the VV was created, measured in seconds since 12 AM on 01/01/1970. The time when the VV was created. The time when the VV will expire. The time when the VV will expire. The time at which the volume retention time expires. The time at which the volume retention time expires. Enables a snapshot space allocation warning. A warning alert is generated when the reserved snapshot space of the virtual volume exceeds the indicated percentage of the virtual volume size. Sets a snapshot space allocation limit. The snapshot space of the virtual volume is prevented from growing beyond the indicated percentage of the virtual volume size. This option enables a user space allocation warning. It specifies that a warning alert is generated when the reserved user space of the TPVV exceeds the specified percentage of the virtual volume size. Query Volume Information 37

roChildId rwChildId physParentId wwn creationTimeSec

number number number string number

int32 int32 int32 WWN epoch

creationTime8601 expirationTimeSec expirationTime8601 retentionTimeSec retentionTime8601 ssSpcAllocWarningPct

String number number number string number

8601 epoch 8601 epoch 8601 igint32

ssSpcAllocLimitPct

number

igint32

usrSpcAllocWarningPct

number

igint32

Table 23 JSON objects for Volume Queries (continued)


Member usrSpcAllocLimitPct JSON type number API type igint32 Description This option sets the user space allocation limit. The user space of the TPVV is prevented from growing beyond the specified percentage of the virtual volume size. After the size is reached, any new writes to the virtual volume will fail. Policies used for the VV. CPG name from which the user space is allocated. CPG name from which the snapshot (Snap and Admin) space is allocated. Comment associated with the volume.

policies userCPG snapCPG comment

object string string string

policies obj name31 uint32 print51 1

38

Working with Storage Volumes

10 Working with Virtual LUNs


This chapter describes the API operations you can perform on Virtual LUNs (VLUNs). A VLUN is a pairing between a virtual volume and a logical unit number (LUN), expressed as either a VLUN template or an active VLUN. A VLUN template sets up an association between a virtual volume and one of the following combinations by establishing the export rule, or the manner in which the Volume is exported. When you create a VLUN template, if the current system state meets the conditions established by the template, active VLUNs, e.g. exports that are seen as LUNs by the host, are the result. Depending on the conditions of the VLUN template, a single template can produce more than one active VLUN. The sections that follow describe the APIs to perform VLUN operations.

Configuration and Enumeration Objects


Several enumerations and configuration objects are used for managing VLUNs. These configuration objects are defined in this section.

VLUN portPos Configuration Object


The SPI server communicates port position as a portPos object as defined below: Table 24 JSON Components of the portPos Object.
Members node slot cardPort JSON type Number Number Number API type igint32 igint32 igint32 Description System node (0-7) PCI bus slot in the node (0-5) Port number on the FC card (0-4)

VLUNtype Enumeration
This component enumerates the types of VLUNs assigned in the system. Table 25 Enumeration of VLUN Types.
Value 1 2 3 4 5 Description Empty Port Host. Matched set Host set

VLUN multipathing Enumeration


The API server will communicate the multipathing configuration enumerated as follows: Table 26 Enumeration of multipathing Configurations for VLUNs
Value 1 2 3 Description Unknown RoundRobin Failover

Configuration and Enumeration Objects

39

VLUN failedPathPol Enumeration


The API server will communicate the failed path monitoring method (failedPathPol) enumerated as follows: Table 27 Enumeration of failedPathPol Configurations for VLUNs
Value 1 2 3 4 Description Unknown scsiTestUnitReady inquiry readSector0

Create a VLUN
The following section describes the HTTP request and response parameters for creating a VLUN template. No URI parameters are supported for this operation. NOTE: Any user with Super, Edit role or any role granted with the vlun_create right can perform this operation.

URI
A VLUN is created with the HTTP POST method to the URI: https://<Storage System>:8080/api/v1/vluns

Request Body
The following JSON members are sent in the request body, for specifying the parameters for creating a VLUN template.
Member volumeName lun hostname portPos JSON type String Number String Object API Type name31 igint32 name31 portPos Description Name of the volume to be exported LUN id Ignored Values None (required) None (required)

Name of the host which the None* (optional) volume is to be exported. System port of VLUN None* (optional) exported to. It includes node number, slot number, and card port number A VLUN change None* (optional) notification (VCN) not be issued after export (-novcn). Default: False. Existing lower priority VLUNs will be overridden (-ovrd). Use only if hostname member exists. Default: False. None* (optional)

noVcn

Boolean

Boolean

overrideLowerPriority Boolean

Boolean

When creating a VLUN, the volumeName and lun members are required. Either hostname or portPos (or both in the case of matched sets) is also required. The noVcn and overrideLowerPriority members are optional.

40

Working with Virtual LUNs

Return Status
With a successful VLUN creation, status code 201 Created is returned and there is no message body. On successful creation of the VLUN, the Location response header contains the URI for the newly created VLUN in the following format: /api/v1/vluns/<volumeName>,<lun>,<hostname>,[<port>] The volumeName is the volume that the newly created VLUN exports. The hostname or port information or both (depending on the VLUN type) for the newly created VLUN. The port information will not be displayed for host type VLUN.

An error condition returns one of the following:


API status code INV_INPUT_MISSING_REQUIRED HTTP code 400 Bad Request 404 Not found 404 Not found 400 Bad Request 404 Not found 409 Conflict Description Missing volumeName or incomplete port info, , specifying override option without hostname. Specified volume does not exist. Specified hostname not found. Missing both hostname and portPos for VLUN creation. Specified port is of invalid link type. LUN already exists. Incorrect portPos specification or the node or slot or cardPort in portPos object maybe out of range. OverrideLowerPriority is being specified without hostname. LUN is greater than 16384.

NON_EXISTENT_VOL NON_EXISTENT_HOST MISSING_VLUN_EXPORT_INFO

BAD_PORT_TYPE EXISTENT_LUN

INV_INPUT_PORT_SPECIFICATION 400 Bad Request INV_INPUT_PARAM_CONFLICT 400 Bad Request 400 Bad Request

TOO_LARGE

Response Body
On success, there is no content in the response body for this operation. On failure, the error code and API-specific error information is sent.

Example
The following example creates a matched VLUN type template for test_vv02 volume.

HTTP Request
POST /api/v1/vluns HTTP/1.1 Host: storsys1.example.com:8080 Accept: application/json Content-Type: application/json X-HP3PAR-WSAPI-SessionKey: 2-33fe8891e288b34b3f914410e7cc7907-a93d1c50 { "volumeName":"test_vv02", "lun":252, "hostname":"mysystem", "portPos":{
Create a VLUN 41

"node": 2, "slot": 2, "cardPort": 4 }, "noVcn":false, "overrideLowerPriority":false }

HTTP Response
HTTP/1.1 201 Created Date: Mon, 16 Apr 2012 06:44:26 GMT Server: hp3par-wsapi Cache-Control: no-cache Pragma: no-cache Location: /api/v1/vluns/test_vv02,252,mysystem,2:2:4

Remove a VLUN
The following section describes the HTTP request and response for removing a virtual volumes SCSI LUN export definition from the system. The VLUN definition is removed with the HTTP Delete method to the URI: https://<Storage System>:8080/api/v1/vluns/<volumeName>,<lun>, <hostname>[,<port>][?<query>] NOTE: Any user with Super, Edit role or any role granted with the vlun_remove right can perform this operation.

URI Parameters
The following parameters are sent in the URI for the delete operation:
URI Parameter* volumeName lun hostname port Description Name of the volume to be exported LUN Ignored values None (required) None (required)

Name of the host which the volume is exported. None (required if volume is exported to host, or For VLUN of port type, the value is empty. both host and port) Specifies the system port of the VLUN export. It None (required if volume is exported to port, or includes the system node number, PCI bus slot both host and port) number, and card port number on the FC card in the format: <node>:<slot>:<port>

Must be percent encoded as in RFC 3968 for reserved characters.

Table 28 Options Parameter (query)


Query noVcn=<true|false> Description A VLUN change notification (VCN) not be issued after export (-novcn).

42

Working with Virtual LUNs

Responses
Success
A successful removal returns status code 200: OK with no message body.

Error Codes
An error state returns one of the following:
API error Status code Description Incomplete VLUN info. Missing volumeName or lun, or both hostname and port. NON_EXISTENT_HOST NON_EXISTENT_VLUN NON_EXISTENT_VOLUME 404 Not Found 404 Not Found 404 Not Found Specified hostname not found Incorrect LUN or volumeName Specified volume name not found Specified port is invalid. The LUN specified exceeds expected range.

INV_INPUT_MISSING_REQUIRED 400 Bad Request

INV_INPUT_PORT_SPECIFICATION 400 Bad Request INV_INPUT_EXCEEDS_RANGE 400 Bad Request

Example
In the following example VLUNs with LUN 252, exported to storsys1 is deleted. The optional port information is also sent because the VLUN is of matched type.

HTTP Request
DELETE /api/v1/vluns/test_vv02,252,mysystem,2:2:4 HTTP/1.1 Host: storsys1.example.com:8080 Accept: application/json Content-Type: application/json X-HP3PAR-WSAPI-SessionKey: 2-33fe8891e288b34b3f914410e7cc7907-a93d1c50

HTTP Response
HTTP/1.1 200 OK Date: Mon, 16 Apr 2012 07:16:39 GMT Server: hp3par-wsapi Cache-Control: no-cache Pragma: no-cache Connection: close

Query VLUN Information


The VLUN query fetches all the VLUN templates and active-VLUNs on the system. Querying for VLUN information is done with the HTTP GET method on the URI. The syntax is as follows: https://<Storage System>:8080/api/v1/vluns

Responses
Success
A successful query returns status code 200 OK and a response body with the following members:
Query VLUN Information 43

JSON Objects in a VLUN Query


Member total members JSON type number array of objects API type int32 Array of VLUN Property objects Description Number of VLUN objects returned VLUN properties

The members object is a JSON array of zero or more JSON objects one for each VLUN on the system. These objects are described in the following table.
Member lun volumeName hostname remoteName JSON type number string string string API type uint32 name31 name31 name31 Description Exported LUN Value Name of exported Virtual Volume name Hostname the VLUN is exported to host WWN, or iSCSI name, or SAS addr; depends on port type System port of VLUN exported to. It includes node number, slot number, and cardPort number VLUN type

portPos

object

portPos object For more information, see JSON Components of the portPos Object. (page 39) VLUNtype enum For more information, see Enumeration of VLUN Types. (page 39) WWN multipathing enum For more information see Enumeration of multipathing Configurations for VLUNs (page 39) failedPathPol enum For more information, see Enumeration of failedPathPol Configurations for VLUNs (page 40) uint32

type

number

volumeWWN multipathing

string number

WWN of exported volume Multipathing method in use

failedPathPol

number

Failed path monitoring method

failedPathInterval

number

Monitoring interval in seconds after which the host checks for failed paths The device name for this VLUN on the host Specified if the VLUN is an active VLUN or a VLUN template. , . true for active VLUN false for VLUN template

hostDeviceName active

string Boolean

name31 Boolean

44

Working with Virtual LUNs

Example
The example lists all the VLUN templates or active VLUNs, including all active and template VLUNs on the storage system:

HTTP Request
GET /api/v1/vluns HTTP/1.1 Host: storsys1.example.com:8080 Accept: application/json Content-Type: application/json X-HP3PAR-WSAPI-SessionKey: 2-33fe8891e288b34b3f914410e7cc7907-a93d1c50

HTTP Response
{"total": 2, "members": [ { "lun": 1, "volumeName": "vol1.0", "hostname": "host", "remoteName": "10000000C978500E", "portPos": { "node": 0, "slot": 4, "cardPort": 1 }, "type": 4, "volumeWWN": "60002AC0000000000000020D0000017D", "multipathing": 1, "failedPathPol": 1, "failedPathInterval": 0, "active": true }, { "lun": 10, "volumeName": "vol1.0", "portPos": { "node": 0, "slot": 4, "cardPort": 1 }, "type": 4, "volumeWWN": "60002AC0000000000000020D0000017D", "multipathing": 1, "failedPathPol": 1,
Query VLUN Information 45

"failedPathInterval": 0, "active": false } ] }

46

Working with Virtual LUNs

1 1 Support and Other Resources


Contacting HP
For worldwide technical support information, see the HP support website: http://www.hp.com/support Before contacting HP, collect the following information: Product model names and numbers Technical support registration number (if applicable) Product serial numbers Error messages Operating system type and revision level Detailed questions

Specify the type of support you are requesting:


HP 3PAR storage system HP 3PAR StoreServ 7200 and 7400 Storage systems HP 3PAR StoreServ10000 Storage systems HP 3PAR T-Class storage systems HP 3PAR F-Class storage systems Support request StoreServ 7000 Storage 3PAR or 3PAR Storage

HP 3PAR documentation
For information about: Supported hardware and software platforms See: The Single Point of Connectivity Knowledge for HP Storage Products (SPOCK) website: http://www.hp.com/storage/spock Locating HP 3PAR documents The HP 3PAR StoreServ Storage site: http://www.hp.com/go/3par To access HP 3PAR documents, click the Support link for your product. HP 3PAR storage system software Storage concepts and terminology HP 3PAR StoreServ Storage Concepts Guide

Using the HP 3PAR Management Console (GUI) to configure HP 3PAR Management Console User's Guide and administer HP 3PAR storage systems Using the HP 3PAR CLI to configure and administer storage systems CLI commands Analyzing system performance Installing and maintaining the Host Explorer agent in order to manage host configuration and connectivity information HP 3PAR Command Line Interface Administrators Manual HP 3PAR Command Line Interface Reference HP 3PAR System Reporter Software User's Guide HP 3PAR Host Explorer Users Guide

Creating applications compliant with the Common Information HP 3PAR CIM API Programming Reference Model (CIM) to manage HP 3PAR storage systems

Contacting HP

47

For information about:

See:

Migrating data from one HP 3PAR storage system to another HP 3PAR-to-3PAR Storage Peer Motion Guide Configuring the Secure Service Custodian server in order to monitor and control HP 3PAR storage systems Using the CLI to configure and manage HP 3PAR Remote Copy Updating HP 3PAR operating systems Identifying storage system components, troubleshooting information, and detailed alert information Installing, configuring, and maintaining the HP 3PAR Policy Server HP 3PAR Secure Service Custodian Configuration Utility Reference HP 3PAR Remote Copy Software Users Guide HP 3PAR Upgrade Pre-Planning Guide HP 3PAR F-Class, T-Class, and StoreServ 10000 Storage Troubleshooting Guide HP 3PAR Policy Server Installation and Setup Guide HP 3PAR Policy Server Administration Guide

48

Support and Other Resources

For information about:

See: Planning for HP 3PAR storage system setup

Hardware specifications, installation considerations, power requirements, networking options, and cabling information for HP 3PAR storage systems HP 3PAR 7200 and 7400 storage systems HP 3PAR 10000 storage systems HP 3PAR StoreServ 7000 Storage Site Planning Manual HP 3PAR StoreServ 10000 Storage Physical Planning Manual HP 3PAR StoreServ 10000 Storage Third-Party Rack Physical Planning Manual Installing and maintaining HP 3PAR 7200 and 7400 storage systems Installing 7200 and 7400 storage systems and initializing the Service Processor HP 3PAR StoreServ 7000 Storage Installation Guide HP 3PAR StoreServ 7000 Storage SmartStart Software Users Guide HP 3PAR StoreServ 7000 Storage Service Guide HP 3PAR StoreServ 7000 Storage Troubleshooting Guide HP 3PAR Service Processor Software User Guide HP 3PAR Service Processor Onsite Customer Care (SPOCC) User's Guide HP 3PAR host application solutions Backing up Oracle databases and using backups for disaster HP 3PAR Recovery Manager Software for Oracle User's recovery Guide Backing up Exchange databases and using backups for disaster recovery Backing up SQL databases and using backups for disaster recovery Backing up VMware databases and using backups for disaster recovery HP 3PAR Recovery Manager Software for Microsoft Exchange 2007 and 2010 User's Guide HP 3PAR Recovery Manager Software for Microsoft SQL Server Users Guide HP 3PAR Management Plug-in and Recovery Manager Software for VMware vSphere User's Guide

Maintaining, servicing, and upgrading 7200 and 7400 storage systems Troubleshooting 7200 and 7400 storage systems Maintaining the Service Processor

Installing and using the HP 3PAR VSS (Volume Shadow Copy HP 3PAR VSS Provider Software for Microsoft Windows Service) Provider software for Microsoft Windows User's Guide Best practices for setting up the Storage Replication Adapter HP 3PAR Storage Replication Adapter for VMware for VMware vCenter vCenter Site Recovery Manager Implementation Guide Troubleshooting the Storage Replication Adapter for VMware HP 3PAR Storage Replication Adapter for VMware vCenter Site Recovery Manager vCenter Site Recovery Manager Troubleshooting Guide Installing and using vSphere Storage APIs for Array Integration (VAAI) plug-in software for VMware vSphere HP 3PAR VAAI Plug-in Software for VMware vSphere User's Guide

HP 3PAR documentation

49

Typographic conventions
Table 29 Document conventions
Convention Bold text Element Keys that you press Text you typed into a GUI element, such as a text box GUI elements that you click or select, such as menu items, buttons, and so on Monospace text File and directory names System output Code Commands, their arguments, and argument values <Monospace text in angle brackets> Code variables Command variables Bold monospace text Commands you enter into a command line interface System output emphasized for scannability

WARNING! Indicates that failure to follow directions could result in bodily harm or death, or in irreversible damage to data or to the operating system. CAUTION: NOTE: Indicates that failure to follow directions could result in damage to equipment or data.

Provides additional information.

Required
Indicates that a procedure must be followed as directed in order to achieve a functional and supported implementation based on testing at HP.

HP 3PAR branding information


The server previously referred to as the "InServ" is now referred to as the "HP 3PAR StoreServ Storage system." The operating system previously referred to as the "InForm OS" is now referred to as the "HP 3PAR OS." The user interface previously referred to as the "InForm Management Console (IMC)" is now referred to as the "HP 3PAR Management Console." All products previously referred to as 3PAR products are now referred to as "HP 3PAR" products.

50

Support and Other Resources

12 Documentation feedback
HP is committed to providing documentation that meets your needs. To help us improve the documentation, send any errors, suggestions, or comments to Documentation Feedback (docsfeedback@hp.com). Include the document title and part number, version number, or the URL when submitting your feedback.

51

S-ar putea să vă placă și