Initial settings for a storage system

Last updated
Save as PDF

Initial setup tasks of a storage system include setting date and time, registering licenses, and specifying the target destination of the audit log files.

Child Topics

Overview of the initial settings of a storage system
This section describes the operations that can be performed by using the REST API, related to the initial settings of a storage system.
Getting the system date and time of a storage system
The following request gets the system date and time of a storage system.
Getting a list of time zones that can be used in a storage system
The following request checks the time zones that can be used when you set the system date and time of a storage system or other information.
Setting the system date and time of a storage system
The following request sets the system date and time of a storage system.
Uploading the files required for initial configuration
The following request uploads the files required for the initial configuration of storage systems. The files are uploaded from a REST API client to the storage system. In the request header of this API function, specify multipart/form-data for Content-Type. For details about the initial configuration of storage systems, see the System Administrator Guide.
Getting information about the transfer destinations of audit log files
The following request gets information, specified for a storage system, about the settings related to the transfer of audit log files to the syslog servers.
Specifying the transfer destinations of audit log files
The following request specifies settings related to the transfer of audit log files from a storage system to the syslog servers. Run this API function with https specified as the protocol to be used.
Sending test messages to the transfer destinations of audit log files
The following request sends test messages to the syslog servers to verify that the settings related to the transfer destinations of audit log files are correctly specified.
Getting SNMP settings
The following request explains how to obtain the SNMP settings for a storage system.
Specifying the SNMP error notification destinations
The following request specifies settings related to reporting error information (SIM) of a storage system by using SNMP. Run this API function with https specified as the protocol to be used.
Sending a test SNMP trap
The following request sends a test SNMP trap to make sure that the settings for reporting error information (SIM) to the SNMP manager are correctly specified.
Getting a list of license information
The following request obtains a list of software license information. You can also obtain the list by specifying the software name or installation status of the software.
Getting information about a specific license
The following request obtains license information by specifying a software license ID.
Installing software
The following request installs software by registering a license key code.
Enabling or disabling a license
You can enable or disable a software license by specifying the software license ID.
Removing software
The following request shows how to remove software by specifying the license ID.

Overview of the initial settings of a storage system

This section describes the operations that can be performed by using the REST API, related to the initial settings of a storage system.

Initial setup operations that can be performed in the REST API

Setting the system date and time for a storage system
Set the system date and time for a storage system.
Setting the transfer destinations for audit log files
Specify settings related to the transfer of audit log files from a storage system to the syslog servers. You can also upload to the storage system the certificate files that are required when SSL communication is used to transfer audit log files between a storage system and the syslog servers.
Setting the SNMP notification destinations
Specify settings related to reporting error information (SIM) of a storage system by using SNMP. For details on SNMP, see the Hitachi SNMP Agent User Guide.
License management
Set software licenses.

For details on initial settings of storage systems, see the System Administrator Guide.

Getting the system date and time of a storage system

The following request gets the system date and time of a storage system.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/v1/objects/date-times/instance

Request message

Object ID

Specify instance.

If an object has only one instance, the instance is the fixed value that specifies the object ID.

Query parameters

None.

Body

None.

Response message

Body

{
  "isNtpEnabled": true,
  "ntpServerNames": [
    "192.0.2.200"
  ],
  "timeZoneId": "America/Los_Angeles",
  "systemTime": "2016-07-20T17:02:12Z",
  "synchronizingLocalTime": "22:00",
  "adjustsDaylightSavingTime": true
}

Attribute	Type	Description
isNtpEnabled	boolean	Whether to synchronize the time with the NTP server `true`: Synchronize the time with the NTP server `false`: Do not synchronize the time with the NTP server
ntpServerNames	string[]	The IP address or host name of the NTP server This attribute is displayed if the time is synchronized with the NTP server.
timeZoneId	string	Time zone ID
systemTime	ISO8601string	System date and time (UTC)
synchronizingLocalTime	string	Synchronization time with the NTP server (local time) This attribute is displayed if the time is synchronized with the NTP server.
adjustsDaylightSavingTime	boolean	Whether to automatically adjust for daylight saving time This attribute is displayed if the time zone supports daylight saving time. `true`: Adjust for daylight saving time `false`: Do not adjust for daylight saving time

Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description of HTTP status codes.

Status code	Message	Description
412	Precondition Failed	The microcode version of the storage system does not support this operation.

Coding example

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/date-times/instance

Getting a list of time zones that can be used in a storage system

The following request checks the time zones that can be used when you set the system date and time of a storage system or other information.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/v1/objects/time-zones

Request message

Object ID

None.

Query parameters

None.

Body

None.

Response message

Body

{
  "data": [
    {
      "timeZoneId": "Etc/GMT+12",
      "timeZone": "(UTC-12:00)",
      "displayName": "International Date Line West",
      "observesDaylightSavingTime": false
    },
    {
      "timeZoneId": "Etc/GMT+11",
      "timeZone": "(UTC-11:00)",
      "displayName": "Coordinated Universal Time-11",
      "observesDaylightSavingTime": false
    },
    {
      "timeZoneId": "Pacific/Honolulu",
      "timeZone": "(UTC-10:00)",
      "displayName": "Hawaii",
      "observesDaylightSavingTime": false
    }
  ]
}

Attribute	Type	Description
timeZoneId	string	Time zone ID
timeZone	string	Time zone
displayName	string	Displays the name of the time zone
observesDaylightSavingTime	boolean	Whether daylight saving time is supported `true`: Daylight saving time is supported. `false`: Daylight saving time is not supported.

Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description of HTTP status codes.

Status code	Message	Description
412	Precondition Failed	The microcode version of the storage system does not support this operation.

Coding example

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/time-zones

Setting the system date and time of a storage system

The following request sets the system date and time of a storage system.

Note

If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.

Execution permission

Storage Administrator (Initial Configuration)

Request line

PATCH base-URL/v1/objects/date-times/instance

Request message

Object ID

Specify instance.

If an object has only one instance, the instance is the fixed value that specifies the object ID.

Query parameters

None.

Body

{
  "isNtpEnabled": true,
  "ntpServerNames": [
    "192.0.2.200",
    "192.0.2.300"
  ],
  "timeZoneId": "America/Los_Angeles",
  "systemTime": "2016-07-20T17:02:12Z",
  "synchronizingLocalTime": "22:00",
  "adjustsDaylightSavingTime": true,
  "synchronizesNow": true
}

Attribute	Type	Description
isNtpEnabled	boolean	(Required) Whether to synchronize the time with the NTP server `true`: Synchronize the time with the NTP server `false`: Do not synchronize the time with the NTP server
ntpServerNames	string[]	(Optional) The IP address or host name of the NTP server You can specify this attribute only if `true` is specified for the `isNtpEnabled` attribute. If `true` is specified for the `isNtpEnabled` attribute, you must specify this attribute. If you specify multiple NTP servers, use commas to delimit the names. You can set a maximum of 5 NTP servers.
timeZoneId	string	(Required) Time zone ID Specify a time zone ID that you obtained by using the API function that obtains a list of available time zones for the storage system.
systemTime	ISO8601string	(Required) System date and time (UTC) Specify a date between January 1, 2000 and December 31, 2037 in YYYY-MM-DDThh:mm:ssZ format. If the time zone specified for the `timeZoneId` attribute uses daylight saving time and the `adjustsDaylightSavingTime` attribute is set to `true`, you cannot set a time that is within the transition period of standard time to daylight saving time or the transition period of daylight saving time to standard time. The specified system date and time might be different from the date and time actually set on the storage system by several seconds. To set an accurate date and time, we recommend that you synchronize the date and time with the NTP server.
synchronizingLocalTime	string	(Optional) Synchronization time with the NTP server (local time) You can specify this attribute only if `true` is specified for the `isNtpEnabled` attribute. Specify a time between `00:00` and `23:59` in "hh:mm" format. If this attribute is omitted, `00:00` is assumed to be set.
adjustsDaylightSavingTime	boolean	(Optional) Whether to automatically switch to daylight saving time You can specify this attribute only if the time zone specified for the `timeZoneId` attribute supports daylight saving time. You cannot specify this attribute if the specified time zone does not support daylight saving time. To check whether the time zone supports daylight saving time, you can use the API function that obtains a list of available time zones for the storage system. `true`: Switch to daylight saving time `false`: Do not switch to daylight saving time If this attribute is omitted, `true` is assumed to be set.
synchronizesNow	boolean	(Optional) Whether to immediately synchronize with the NTP server You can specify this attribute only when `true` is specified for the `isNtpEnabled` attribute. `true`: Immediately synchronize with the NTP server `false`: Do not synchronize with the NTP server until the synchronization time If you specify `false` for this attribute, the time will be set as the time specified for the `systemTime` attribute until the time specified for the synchronization time of the `synchronizingLocalTime` attribute. If this attribute is omitted, `true` is assumed to be set.

Response message

Body

{
  "isNtpEnabled": true,
  "ntpServerNames": [
    "192.0.2.200",
    "192.0.2.300"
  ],
  "timeZoneId": "America/Los_Angeles",
  "systemTime": "2016-07-20T17:02:12Z",
  "synchronizingLocalTime": "22:00",
  "adjustsDaylightSavingTime": true
}

Attribute	Type	Description
isNtpEnabled	boolean	Whether to synchronize the time with the NTP server `true`: Synchronize the time with the NTP server `false`: Do not synchronize the time with the NTP server
ntpServerNames	string[]	The IP address or host name of the NTP server
timeZoneId	string	Time zone ID
systemTime	ISO8601string	System date and time (UTC)
synchronizingLocalTime	string	Synchronization time with the NTP server (local time)
adjustsDaylightSavingTime	boolean	Whether to automatically switch to daylight saving time `true`: Switch to daylight saving time `false`: Do not switch to daylight saving time

Action template

None.

Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description of HTTP status codes.

Status code	Message	Description
412	Precondition Failed	The microcode version of the storage system does not support this operation.

Coding example

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X PATCH --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/date-times/instance

Uploading the files required for initial configuration

The following request uploads the files required for the initial configuration of storage systems. The files are uploaded from a REST API client to the storage system. In the request header of this API function, specify multipart/form-data for Content-Type. For details about the initial configuration of storage systems, see the System Administrator Guide.

If SSL communication is used between the storage system and the syslog server, run this API function to upload the required certificate file to the storage system in advance. After that, run the API function for setting the transfer destinations of the audit log. When you do so, the storage system will be set to use the uploaded certificate file for communication.

Important

Only one file can be uploaded in one request.
If files with the same fileType attribute are already uploaded, the currently uploaded file will be overwritten by the file to be uploaded.

Execution permission

Audit Log Administrator (View & Modify)

Request header

In this API, the request body is sent in the format of multipart/form-data. Specify multipart/form-data for the Content-Type of the request header.

Request line

POST base-URL/v1/objects/actions/file-upload/invoke

Request message

Object ID

None.

Query parameters

None.

Body

Attribute	Type	Description
fileType	string	(Required) File type of the file to be uploaded The specifiable values are as follows: `AuditSyslogPrimaryClientCertFile`: Client certificate file of the syslog server to which audit log files are to be transferred (for the primary server) `AuditSyslogPrimaryRootCertFile`: Root certificate file of the syslog server to which audit log files are to be transferred (for the primary server) `AuditSyslogSecondaryClientCertFile`: Client certificate file of the syslog server to which audit log files are to be transferred (for the secondary server) `AuditSyslogSecondaryRootCertFile`: Root certificate file of the syslog server to which audit log files are to be transferred (for the secondary server)
file	file	(Required) File to be uploaded You can use the following characters: Spaces Alphanumeric characters The following symbols: ! " # $ % & ' ( ) * + , - . : ; < = > ? @ [ \ ] ^ _ ` { \| } ~

Attribute

Type

Description

fileType

string

(Required) File type of the file to be uploaded

The specifiable values are as follows:

AuditSyslogPrimaryClientCertFile: Client certificate file of the syslog server to which audit log files are to be transferred (for the primary server)
AuditSyslogPrimaryRootCertFile: Root certificate file of the syslog server to which audit log files are to be transferred (for the primary server)
AuditSyslogSecondaryClientCertFile: Client certificate file of the syslog server to which audit log files are to be transferred (for the secondary server)
AuditSyslogSecondaryRootCertFile: Root certificate file of the syslog server to which audit log files are to be transferred (for the secondary server)

file

(Required) File to be uploaded

You can use the following characters:

Spaces
Alphanumeric characters
The following symbols:
! " # $ % & ' ( ) * + , - . : ; < = > ? @ [ \ ] ^ _ ` { | } ~

Response message

Body

None.

Status codes

For details on the status codes of the request for this operation, see the description of HTTP status codes.

If HTTP status code 502 is returned, make sure the file is correctly specified, and then run the API request again.

Coding example

curl -v -H "Accept:application/json" -H "Content-Type: multipart/form-data" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -H "Expect:" -X POST -F "file=@C:\certfile.crt" -F "fileType=AuditSyslogPrimaryClientCertFile" https://192.0.2.100/ConfigurationManager/v1/objects/actions/file-upload/invoke

If you run a request in which multipart/form-data is specified for Content-Type, Expect: 100-continue might be automatically assigned to the header, depending on the specifications of the client software. Depending on the specifications of the web server, this header might not be accepted. If the header is not accepted, a 417 error occurs, and the request fails. In this coding example, the Except header is specified to overwrite the automatically assigned header, thereby preventing this error.

Getting information about the transfer destinations of audit log files

The following request gets information, specified for a storage system, about the settings related to the transfer of audit log files to the syslog servers.

Execution permission

Audit Log Administrator (View Only)

Request line

GET base-URL/v1/objects/auditlog-syslog-servers/instance

Request message

Object ID

Specify instance.

If an object has only one instance, the instance is the fixed value that specifies the object ID.

Query parameters

None.

Body

None.

Response message

Body

{
  "transferProtocol": "TLS",
  "locationName": "886000123456",
  "retries": true,
  "retryInterval": 30,
  "isDetailed": true,
  "primarySyslogServer": {
    "isEnabled": true,
    "ipAddress": "192.0.1.100",
    "port": 12345
  },
  "secondarySyslogServer": {
    "isEnabled": true,
    "ipAddress": "192.0.1.200",
    "port": 12345
  }
}

Attribute	Type	Description
transferProtocol	string	Protocol to be used when transferring audit log files to the syslog servers `TLS`: TLS1.2/RFC5424 `UDP`: UDP/RFC3164
locationName	string	Name of the storage system from which audit log files are to be transferred
retries	boolean	Specifies whether to try again if communication with a syslog server fails This attribute is displayed if the `transferProtocol` attribute is `TLS`. `true`: Tries again `false`: Does not try again
retryInterval	int	Retry interval (in seconds) when communication with a syslog server fails This attribute is displayed if the `retries` attribute is `true`.
isDetailed	boolean	Specifies whether to transfer detailed information about audit log files to the syslog servers `true`: Transfers detailed information `false`: Does not transfer detailed information
primarySyslogServer	object	Settings of the primary-site syslog server The following information about the primary-site syslog server is displayed: isEnabled (boolean) Whether audit log files are transferred to the syslog server `true`: Audit log files are transferred to the syslog server `false`: Audit log files are not transferred to the syslog server ipAddress (string) IP address This is displayed when the value of the `isEnabled` attribute is `true`. port (int) Port number This is displayed when the value of the `isEnabled` attribute is `true`.
secondarySyslogServer	object	Settings of the secondary-site syslog server The following information about the secondary-site syslog server is displayed: isEnabled (boolean) Whether audit log files are transferred to the syslog server `true`: Audit log files are transferred to the syslog server `false`: Audit log files are not transferred to the syslog server ipAddress (string) IP address This is displayed when the value of the `isEnabled` attribute is `true`. port (int) Port number This is displayed when the value of the `isEnabled` attribute is `true`.

Status codes

For details on the status codes of the request for this operation, see the description of HTTP status codes.

Coding example

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/auditlog-syslog-servers/instance

Specifying the transfer destinations of audit log files

The following request specifies settings related to the transfer of audit log files from a storage system to the syslog servers. Run this API function with https specified as the protocol to be used.

Note

If SSL communication is to be used to transfer audit log files between syslog servers, upload the necessary certificate files to the storage system before specifying the transfer destinations of audit log files.
If you locked the resources of the target storage system by using the REST API, you will not be able to use the API function for specifying the transfer destinations of audit log files. In such cases, unlock the resources before running the API function.

Execution permission

Audit Log Administrator (View & Modify)

Request line

PATCH base-URL/v1/objects/auditlog-syslog-servers/instance

Request message

Object ID

Specify instance.

If an object has only one instance, the instance is the fixed value that specifies the object ID.

Query parameters

None.

Body

{
  "transferProtocol": "TLS",
  "locationName": "886000123456",
  "retries": true,
  "retryInterval": 30,
  "isDetailed": true,
  "primarySyslogServer": {
    "isEnabled": true,
    "ipAddress": "192.0.1.100",
    "port": 12345,
    "clientCertFileName": "primaryClientCert.crt",
    "clientCertFilePassword": "123456",
    "rootCertFileName": "primaryRootCert.crt"
  },
  "secondarySyslogServer": {
    "isEnabled": true,
    "ipAddress": "192.0.1.200",
    "port": 12345,
    "clientCertFileName": "secondaryClientCert.crt",
    "clientCertFilePassword": "123456",
    "rootCertFileName": "secondaryRootCert.crt"
  }
}

Attribute	Type	Description
transferProtocol	string	(Required) Protocol used when transferring audit log files to syslog servers Specify one of the following values: `TLS`: TLS1.2/RFC5424 `UDP`: UDP/RFC3164
locationName	string	(Required) Name of the storage system from which audit log files are to be transferred Specify a character string consisting of 1 to 32 characters. You can use the following characters: Alphanumeric characters The following symbols: ! " # $ % & ' ( ) * + - . / : ; < = > ? @ [ \ ] ^ _ ` { \| } ~
retries	boolean	(Optional) Specify whether to try again if communication with a syslog server fails. If the `transferProtocol` attribute is `TLS`, specify either of the following values: `true`: Try again. `false`: Do not try again. If you omit this item, `true` is assumed.
retryInterval	int	(Optional) Retry interval (in seconds) if communication with a syslog server fails If the `retries` attribute is `true`, specify a value in the range from `1` to `60`. If you omit this item, `1` will be set.
isDetailed	boolean	(Optional) Specify whether to transfer detailed information about audit log files to the syslog servers. Specify one of the following values: `true`: Transfer detailed information. `false`: Do not transfer detailed information. If you omit this item, `true` is assumed.
primarySyslogServer	object	(Required) Settings of the primary-site syslog server Specify values for the following attributes of the primary-site syslog server: isEnabled (boolean) (Required) Specify whether audit log files are to be transferred to the syslog server. `true`: Transfer audit log files. `false`: Do not transfer audit log files. ipAddress (string) (Optional) IP address You must specify this attribute if `true` is specified for `isEnabled`. You can specify the address in either the IPv4 format or the IPv6 format. port (int) (Optional) Port number You must specify this attribute if `true` is specified for `isEnabled`. clientCertFileName (string) (Optional) Name of the client certificate file You must specify this attribute if `true` is specified for `isEnabled` and `TLS` is specified for `transferProtocol`. If you specify this attribute, the certificate file that was uploaded to the storage system will be set to be used. (The system will not check whether the file name of the certificate matches the file name specified for this attribute.) If a null character string is specified for this attribute, the certificate file that is already set for the storage system will be used. clientCertFilePassword (string) (Optional) Password for client certificate You must specify this attribute if `true` is specified for `isEnabled` and `TLS` is specified for `transferProtocol`. rootCertFileName (string) (Optional) File name for root certificate You must specify this attribute if `true` is specified for `isEnabled` and `TLS` is specified for `transferProtocol`. If you specify this attribute, the certificate file that was uploaded to the storage system will be set to be used. (The system will not check whether the file name of the certificate matches the file name specified for this attribute.) If a null character string is specified for this attribute, the certificate file that is already set for the storage system will be used.
secondarySyslogServer	object	(Required) Settings of the secondary-site syslog server Specify values for the following attributes of the secondary-site syslog server: isEnabled (boolean) (Required) Specify whether audit log files are to be transferred to the syslog server. `true`: Transfer audit log files. `false`: Do not transfer audit log files. ipAddress (string) (Optional) IP address You must specify this attribute if `true` is specified for `isEnabled`. You can specify the address in either the IPv4 format or the IPv6 format. port (int) (Optional) Port number You must specify this attribute if `true` is specified for `isEnabled`. clientCertFileName (string) (Optional) Name of the client certificate file You must specify this attribute if `true` is specified for `isEnabled` and `TLS` is specified for `transferProtocol`. If you specify this attribute, the certificate file that was uploaded to the storage system will be set to be used. (The system will not check whether the file name of the certificate matches the file name specified for this attribute.) If a null character string is specified for this attribute, the certificate file that is already set for the storage system will be used. clientCertFilePassword (string) (Optional) Password for client certificate You must specify this attribute if `true` is specified for `isEnabled` and `TLS` is specified for `transferProtocol`. rootCertFileName (string) (Optional) File name for root certificate You must specify this attribute if `true` is specified for `isEnabled` and `TLS` is specified for `transferProtocol`. If you specify this attribute, the certificate file that was uploaded to the storage system will be set to be used. (The system will not check whether the file name of the certificate matches the file name specified for this attribute.) If a null character string is specified for this attribute, the certificate file that is already set for the storage system will be used.

Response message

Body

A job object is returned. For details on attributes other than affectedResources, see the description of job objects.

Attribute	Description
affectedResources	URL of the transfer destinations set for the audit log files of the storage system

Status codes

For details on the status codes of the request for this operation, see the description of HTTP status codes.

Coding example

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X PATCH --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/auditlog-syslog-servers/instance

Sending test messages to the transfer destinations of audit log files

The following request sends test messages to the syslog servers to verify that the settings related to the transfer destinations of audit log files are correctly specified.

Note

If you locked the resources of the target storage system by using the REST API, you will not be able to use the API function for sending test messages. In such cases, unlock the resources before running the API function.

Execution permission

Audit Log Administrator (View & Modify)

Request line

POST base-URL/v1/objects/auditlog-syslog-servers/instance/actions/send-test/invoke

Request message

Object ID

Specify instance.

If an object has only one instance, the instance is the fixed value that specifies the object ID.

Query parameters

None.

Body

None.

Response message

Body

A job object is returned. For details on the schema of job objects, see the description of job objects.

Action template

None.

Status codes

For details on the status codes of the request for this operation, see the description of HTTP status codes.

Coding example

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/auditlog-syslog-servers/instance/actions/send-test/invoke -d ""

Getting SNMP settings

The following request explains how to obtain the SNMP settings for a storage system.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/v1/objects/snmp-settings/instance

Request message

Object ID

Specify instance.

If an object has only one instance, the instance is the fixed value that specifies the object ID.

Query parameters
None.

Body

None.

Response message

Body

The following is an example of output when the SNMP version is SNMP v1:

{
  "isSNMPAgentEnabled": true,
  "snmpVersion": "v1",
  "sendingTrapSetting": {
    "snmpv1v2cSettings": [
      {
        "community": "MyRestSNMPCommunity1",
        "sendTrapTo": [
          "192.0.2.100",
          "192.0.2.200"
        ]
      }
    ]
  },
  "requestAuthenticationSetting": {
    "snmpv1v2cSettings": [
      {
        "community": "MyRestSNMPCommunity2",
        "requestsPermitted": [
          "192.0.3.100"
        ]
      }
    ]
  },
  "systemGroupInformation": {
    "storageSystemName": "VSP_G700",
    "contact": "confmanager.@example.com",
    "location": "Data Center 1F"
  },
  "snmpEngineID": "0x80000074046361336663353061"
}

The following is an example of output when the SNMP version is SNMP v3:

{
  "isSNMPAgentEnabled": true,
  "snmpVersion": "v3",
  "sendingTrapSetting": {
    "snmpv3Settings": [
      {
        "userName": "MyRestSNMPUser1",
        "sendTrapTo": "192.0.2.100",
        "authentication": {
          "protocol": "SHA",
          "password": "",
          "encryption": {
            "protocol": "AES",
            "key": ""
          }
        }
      },
      {
        "userName": "MyRestSNMPUser2",
        "sendTrapTo": "192.0.2.200"
      }
    ]
  },
  "requestAuthenticationSetting": {
    "snmpv3Settings": [
      {
        "userName": "MyRestSNMPUser3",
        "authentication": {
          "protocol": "MD5",
          "password": "",
          "encryption": {
            "protocol": "DES",
            "key": ""
          }
        }
      }
    ]
  },
  "systemGroupInformation": {
    "storageSystemName": "VSP_G700",
    "contact": "confmanager.@example.com",
    "location": "Data Center 1F"
  },
  "snmpEngineID": "0x80000074046361336663353061"
}

Attribute	Type	Description
isSNMPAgentEnabled	boolean	Whether the SNMP Agent is enabled `true`: Enabled `false`: Disabled If this attribute is `true`, error information (SIM) is reported by SNMP traps. Also, SNMP operation requests (GET REQUEST, GETNEXT REQUEST, and GETBULK REQUEST) are received.
snmpVersion	string	SNMP version Outputs the SNMP version that is being used. `v1` : SNMP v1 `v2c` : SNMP v2c `v3` : SNMP v3 If this attribute is not set, `Unestablished` is output.
sendingTrapSetting	object	SNMP trap destinations snmpv1v2cSettings (object[]) Array of settings for SNMP trap destinations This is output when there is a setting for which the SNMP version is SNMPv1 or SNMPv2c. community (string) Community name used for SNMP trap reports sendTrapTo (string[]) Array of IP addresses to which SNMP traps are sent The addresses are output in IPv4 or IPv6 IP. snmpv3Settings (object[]) Array of the settings for SNMP trap destinations This is output when there is a setting for which the SNMP protocol version is SNMP v3. userName (string) User name that is used for SNMP trap reports sendTrapTo (string) The IP address to which an SNMP trap is sent This is output in IPv4 or IPv6 format. authentication (object) Authentication information This is output when password-based authentication is enabled. For details on the output attributes, see the table of the attributes output to the `authentication` attribute.
requestAuthenticationSetting	object	Settings for permitted requests. Settings for the permitted requests (GET REQUEST, GETNEXT REQUEST, and GETBULK REQUEST) of SNMP operations are output. snmpv1v2cSettings (object[]) Array of the settings for permitted requests This is output when there is a setting for which the SNMP protocol version is SNMPv1 or SNMPv2c. community (string) Name of the community that receives requests requestsPermitted (string[]) Array of the IP addresses of the SNMP Managers that receive requests This is output in IPv4 or IPv6 format. If the array is empty, requests of all SNMP Managers are received. snmpv3Settings (object[]) Array of the settings for permitted requests This is output when there is a setting for which the SNMP version is SNMP v3. userName (string) Name of the user who receives requests authentication (object) Authentication information This is output when password-based authentication is enabled. For details on the output attributes, see the table of the attributes output to the `authentication` attribute.
systemGroupInformation	object	Information of the system group storageSystemName (string) Name of the storage system contact (string) Contact information or name of the administrator location (string) Location of the storage system
snmpEngineID	string	ID identifying the SNMP engine

The following table shows the attributes output to the authentication attribute.

Attribute	Type	Description
protocol	string	Authentication method The following values are output: `SHA` `MD5`
password	string	Password An empty character string is output even if a password has been set.
encryption	object	Encryption information This is output when encryption is enabled. protocol (string) Encryption method The following values are output: `AES` `DES` key (string) Encryption key An empty character string is output even if an encryption key has been set.

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example

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/snmp-settings/instance

Specifying the SNMP error notification destinations

The following request specifies settings related to reporting error information (SIM) of a storage system by using SNMP. Run this API function with https specified as the protocol to be used.

For details on SNMP, see the Hitachi SNMP Agent User Guide.

Notes on creating the request body

Before running this API function, obtain the current settings by using the API function that obtains SNMP information. The response body you have obtained is to be used as the request body for this API function. Change only the values of the attributes that you want to change. This API function overwrites all the specified values.

If you delete the information in the response body you have obtained, the setting is deleted.

Note

Null character values are output to the acquired response body for the password attribute and key attribute. Change the values only when you want to change the setting.
You cannot change the setting for the snmpEngineID attribute. The value is ignored even if it is specified.
If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.

Execution permission

Storage Administrator (Initial Configuration)

Request line

PATCH base-URL/v1/objects/snmp-settings/instance

Request message

Object ID

Specify instance.

If an object has only one instance, the instance is the fixed value that specifies the object ID.

Query parameters
None.

Body

The following is a coding example when the SNMP version is SNMP v1:

{
  "isSNMPAgentEnabled": true,
  "snmpVersion": "v1",
  "sendingTrapSetting": {
    "snmpv1v2cSettings": [
      {
        "community": "MyRestSNMPCommunity1",
        "sendTrapTo": [
          "192.0.2.100",
          "192.0.2.200"
        ]
      }
    ]
  },
  "requestAuthenticationSetting": {
    "snmpv1v2cSettings": [
      {
        "community": "MyRestSNMPCommunity2",
        "requestsPermitted": [
          "192.0.3.100"
        ]
      }
    ]
  },
  "systemGroupInformation": {
    "storageSystemName": "VSP_G700",
    "contact": "confmanager.@example.com",
    "location": "Data Center 1F"
  }
}

The following is a coding example when the SNMP version is SNMP v3:

{
  "isSNMPAgentEnabled": true,
  "snmpVersion": "v3",
  "sendingTrapSetting": {
    "snmpv3Settings": [
      {
        "userName": "MyRestSNMPUser1",
        "sendTrapTo": "192.0.2.100",
        "authentication": {
          "protocol": "SHA",
          "password": "TopSecretForMySNMP1",
          "encryption": {
            "protocol": "AES",
            "key": "KeyForMySNMP1"
          }
        }
      },
      {
        "userName": "MyRestSNMPUser2",
        "sendTrapTo": "192.0.2.200"
      }
    ]
  },
  "requestAuthenticationSetting": {
    "snmpv3Settings": [
      {
        "userName": "MyRestSNMPUser3",
        "authentication": {
          "protocol": "MD5",
          "password": "",
          "encryption": {
            "protocol": "DES",
            "key": ""
          }
        }
      }
    ]
  },
  "systemGroupInformation": {
    "storageSystemName": "VSP_G700",
    "contact": "confmanager.@example.com",
    "location": "Data Center 1F"
  }
}

Attribute	Type	Description
isSNMPAgentEnabled	boolean	(Required) Whether SNMP Agent is enabled `true`: Enabled `false`: Disabled If this attribute is `true`, error information (SIM) is sent by using SNMP traps. Also, SNMP operation requests (GET REQUEST, GET NEXT REQUEST, and GET BULK REQUEST) are received.
snmpVersion	string	(Required) SNMP version Specify the SNMP version that is used. The specifiable values are as follows: `v1`: SNMP v1 `v2c`: SNMP v2c `v3`: SNMP v3
sendingTrapSetting	object	(Optional) SNMP trap destinations Specifiable attributes vary depending on the SNMP version. snmpv1v2cSettings (object[]) (Optional) Array of the settings for SNMP trap destinations (for SNMP v1 or SNMP v2c) You can specify up to 32 destinations. If you specify more than one destination, you must specify a unique `community` attribute. If you specify `snmpv1v2cSettings` attribute, you must also specify both the `community` attribute and the `sendTrapTo` attribute. community (string) Community name used to report an SNMP trap^# Specify a character string that consists of 1 to 180 characters. sendTrapTo (string[]) Array of the IP addresses to which SNMP traps are sent. Specify these in IPv4 or IPv6 format. You can specify up to 32 IP addresses. snmpv3Settings (object[]) (Optional) Array of the settings for SNMP trap destinations (for SNMP v3) You can specify up to 8 destinations. If you specify more than one destination, you must specify a unique `sendTrapTo` attribute. If you specify `snmpv3Settings` attribute, you must also specify both the `userName` attribute and the `sendTrapTo` attribute. userName (string) User name that is used for SNMP trap reports^# Specify a character string that consists of 1 to 32 characters. sendTrapTo (string) Specify the IP address to which SNMP traps are sent. Specify these in IPv4 or IPv6 format. authentication (object) (Optional) Authentication information Specify this attribute when password-based authentication is enabled. For details on the specifiable attributes, see the table of the attributes that can be specified for the `authentication` attribute.
requestAuthenticationSetting	object	(Optional) Settings for the permitted requests Specify the settings for the permitted requests (GET REQUEST, GETNEXT REQUEST, and GETBULK REQUEST) of SNMP operations. Specifiable attributes vary depending on the SNMP version. snmpv1v2cSettings (object[]) (Optional) Array of the settings for permitted requests (for SNMP v1 or SNMP v2c) You can specify up to 32 requests. If you specify more than one request, you must specify a unique `community` attribute. If you specify `snmpv1v2cSettings` attribute, you must also specify both the `community` attribute and the `requestsPermitted` attribute. community (string) Name of the community that receives requests^# Specify a character string that consists of 1 to 180 characters. requestsPermitted (string[]) Array of the IP addresses of the SNMP Managers that receive requests Specify this in IPv4 or IPv6 format. You can specify up to 32 IP addresses. If you specify an empty array, requests of all SNMP Managers are received. snmpv3Settings (object[]) (Optional) Array of the settings for permitted requests (for SNMP v3) You can specify up to 8 requests. If you specify more than one request, you must specify a unique `userName` attribute. If you specify `snmpv3Settings` attribute, you must also specify the `userName` attribute. userName (string) Name of the user who receives requests^# Specify a character string that consists of 1 to 32 characters. This attribute is case sensitive. authentication (object) (Optional) Authentication information Specify this attribute when password-based authentication is enabled. For details on the specifiable attributes, see the table of the attributes that can be specified for the `authentication` attribute.
systemGroupInformation	object	(Required) Information of the system group storageSystemName (string) (Required) Name of the storage system^# This is output as the sysName of the MIB of SNMP Agent. Specify a character string that consists of 1 to 180 characters. contact (string) (Required) Contact information or name of the administrator^# This is output as the sysContact of the MIB of SNMP Agent. Specify a character string that consists of 0 to 180 characters. location (string) (Required) Location of the storage system^# This is output as the sysLocation of the MIB of SNMP Agent. Specify a character string that consists of 0 to 180 characters.

The following table shows the attributes that can be specified for the authentication attribute. If you specify authentication attribute, you must also specify both the protocol attribute and the password attribute.

Attribute	Type	Description
protocol	string	Authentication method You can specify the following values: `SHA` `MD5`
password	string	Password^# Specify a character string that consists of 8 to 64 characters. If you do not want to change the password, specify an empty character string.
encryption	object	(Optional) Encryption information Specify this item to enable encryption. If you specify this attribute, you must also specify both the `protocol` attribute and the `key` attribute. protocol (string) Encryption method You can specify the following values: `AES` `DES` key (string) Encryption key^# Specify a character string that consists of 8 to 64 characters. If you do not want to change the encryption key, specify an empty character string.

#: You can use the following characters:

Alphanumeric characters
The following symbols:
! # $ ' ( ) + - . = @ [ ] _ ` { } ~
Spaces (except at the beginning or end of a character string)

Response message

Body

A job object is returned. For details on attributes other than affectedResources, see the section explaining job objects.

Attribute	Description
affectedResources	URL of the SNMP settings

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X PATCH --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/snmp-settings/instance

Sending a test SNMP trap

The following request sends a test SNMP trap to make sure that the settings for reporting error information (SIM) to the SNMP manager are correctly specified.

For details on SNMP, see the Hitachi SNMP Agent User Guide.

Note

If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.

Execution permission

Storage Administrator (Initial Configuration)

Request line

POST base-URL/v1/objects/snmp-settings/instance/actions/send-trap-test/invoke

Request message

Object ID

Specify instance.

If an object has only one instance, the instance is the fixed value that specifies the object ID.

Query parameters
None.

Body
None.

Response message

Body

A job object is returned. For details on the schema of job objects, see the description of job objects.

Action template

None.

Status codes

For details on the status codes of the request for this operation, see the description of HTTP status codes.

Coding example

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/snmp-settings/instance/actions/send-trap-test/invoke -d ""

Getting a list of license information

The following request obtains a list of software license information. You can also obtain the list by specifying the software name or installation status of the software.

Note

If you execute this API request immediately after updating the license, the request might not be processed correctly if the system does not recognize the updated license. If this happens, wait a while, and then execute the request again.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/v1/objects/licenses

Request message

Object ID
None.

Query parameters

Parameter	Type	Filter condition
programProductName	string	(Optional) Software name You cannot specify this parameter and the `status` parameter at the same time.
status	string	(Optional) Installation status of the software You can specify the following values: `Installed` `Installed (Disabled)` `Not Installed` `Not Enough License` `Grace Period` `Expired` You cannot specify this parameter and the `programProductName` parameter at the same time.

Parameter

Type

Filter condition

programProductName

string

(Optional) Software name

You cannot specify this parameter and the status parameter at the same time.

status

string

(Optional) Installation status of the software

You can specify the following values:

Installed
Installed (Disabled)
Not Installed
Not Enough License
Grace Period
Expired

You cannot specify this parameter and the programProductName parameter at the same time.

Body

None.

Response message

Body

{
  "data": [
    {
      "licenseId": 32775,
      "programProductName": "Dynamic Provisioning",
      "status": "Installed",
      "keyType": "Permanent",
      "capacityLimitStatus": "Unlimited",
      "usedCapacityInGB": 24379
    },
    {
      "licenseId": 32835,
      "programProductName": "Dynamic Tiering",
      "status": "Installed",
      "keyType": "Permanent",
      "capacityLimitStatus": "Unlimited",
      "usedCapacityInGB": 14682
    },
    {
      "licenseId": 32880,
      "programProductName": "Thin Image",
      "status": "Installed",
      "keyType": "Permanent",
      "capacityLimitStatus": "Unlimited",
      "usedCapacityInGB": 940
    },
    {
      "licenseId": 32884,
      "programProductName": "global-active device",
      "status": "Installed",
      "keyType": "Permanent",
      "capacityLimitStatus": "Unlimited",
      "usedCapacityInGB": 161
    }
  ]
}

The following is an example of output generated when the query parameters are specified:

{
  "data": [
    {
      "licenseId": 32775,
      "programProductName": "Dynamic Provisioning",
      "status": "Installed",
      "keyType": "Permanent",
      "capacityLimitStatus": "Unlimited",
      "usedCapacityInGB": 24379
    }
  ]
}

The following table lists the license information that you can obtain. For details about license information, see the System Administrator Guide.

Attribute	Type	Description
licenseId	int	License ID
programProductName	string	Software name
status	string	Installation status of the software `Installed`: Installed `Installed (Disabled)`: Installed (License is disabled) `Not Installed`: Not installed `Not Enough License`: Installed (Not enough license capacity) `Grace Period`: Not enough license capacity because of additional LDEVs or pool volumes, or creation of pairs `Expired`: Expired Output when the `keyType` attribute is `Temporary`.
keyType	string	License key type `Permanent`: For purchase (no limit on effective term) `Term`: For purchase (effective term specified) `Temporary`: For trial use before purchase `Emergency`: For emergency use
capacityLimitStatus	string	Specified if the permitted license capacity has a limit `Limited`: Limited `Unlimited`: Unlimited
permittedCapacityInTB	long	Permitted license capacity (TB)
usedCapacityInGB	long	Volume capacity used by the software (GB)
remainingDays	int	Remaining days before expiration If the `keyType` attribute is `Term`, `Temporary`, or `Emergency`: Remaining days before expiration If a license for which the `keyType` attribute is `Temporary` is expired: Remaining days after the expiration date until re-installation of the software becomes available

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example

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/licenses

Getting information about a specific license

The following request obtains license information by specifying a software license ID.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/v1/objects/licenses/object-ID

Request message

Object ID

Specify the licenseId value obtained by getting information about the licenses.

Attribute	Type	Description
licenseId	int	(Required) License ID

Query parameters
None.

Body

None.

Response message

Body

{
  "licenseId": 32775,
  "programProductName": "Dynamic Provisioning",
  "status": "Installed",
  "keyType": "Permanent",
  "capacityLimitStatus": "Unlimited",
  "usedCapacityInGB": 24379
}

The following table lists the license information that you can obtain. For details about license information, see the System Administrator Guide.

Attribute	Type	Description
licenseId	int	License ID
programProductName	string	Software name
status	string	Installation status of the software `Installed`: Installed `Installed (Disabled)`: Installed (License is disabled) `Not Installed`: Not installed `Not Enough License`: Installed (Not enough license capacity) `Grace Period`: Not enough license capacity because of additional LDEVs or pool volumes, or creation of pairs `Expired`: Expired Output when the `keyType` attribute is `Temporary`.
keyType	string	License key type `Permanent`: For purchase (no limit on effective term) `Term`: For purchase (effective term specified) `Temporary`: For trial use before purchase `Emergency`: For emergency use
capacityLimitStatus	string	Specified if the permitted license capacity has a limit `Limited`: Limited `Unlimited`: Unlimited
permittedCapacityInTB	long	Permitted license capacity (TB)
usedCapacityInGB	long	Volume capacity used by the software (GB)
remainingDays	int	Remaining days before expiration If the `keyType` attribute is `Term`, `Temporary`, or `Emergency`: Remaining days before expiration If a license for which the `keyType` attribute is `Temporary` is expired: Remaining days after the expiration date until re-installation of the software becomes available

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example

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/licenses/34055

Installing software

The following request installs software by registering a license key code.

Execution permission

Storage Administrator (Initial Configuration)

Request line

POST base-URL/v1/objects/licenses

Request message

Object ID
None.

Query parameters
None.

Body

{
  "keyCode": "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789012345678901234567890ABCDEFGHIJKLMNOPQRS"
}

Attribute	Type	Description
keyCode	string	(Required) License key code

Response message

Body

A job object is returned. For details on attributes other than affectedResources, see the section explaining job objects.

Attribute	Description
affectedResources	URL of the list of software license information

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example

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/licenses

Enabling or disabling a license

You can enable or disable a software license by specifying the software license ID.

Execution permission

Storage Administrator (Initial Configuration)

Request line

PATCH base-URL/v1/objects/licenses/object-ID

Request message

Object ID

Specify the licenseId value obtained by getting information about the licenses.

Attribute	Type	Description
licenseId	int	(Required) License ID

Query parameters

None.

Body

{
  "isEnabled": true
}

Attribute	Type	Description
isEnabled	boolean	(Required) Whether to enable a license or not `true`: Enables a license `false`: Disables a license

Attribute

Type

Description

isEnabled

boolean

(Required) Whether to enable a license or not

true: Enables a license
false: Disables a license

Response message

Body

A job object is returned. For details on attributes other than affectedResources, see the section explaining job objects.

Attribute	Description
affectedResources	URL of information about the license for which the setting was changed

Action template

None.

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X PATCH --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/licenses/34055

Removing software

The following request shows how to remove software by specifying the license ID.

Execution permission

Storage Administrator (Initial Configuration)

Request line

DELETE base-URL/v1/objects/licenses/object-ID

Request message

Object ID

Specify the licenseId value obtained by getting information about the licenses.

Attribute	Type	Description
licenseId	int	(Required) License ID

Query parameters
None.

Body
None.

Response message

Body

A job object is returned. For details on attributes other than affectedResources, see the section explaining job objects.

Attribute	Description
affectedResources	URL of the license information of the removed program product

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example

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/licenses/34055

We've Moved!

Product Documentation has moved to docs.hitachivantara.com

Overview of the initial settings of a storage system

Getting the system date and time of a storage system

Getting a list of time zones that can be used in a storage system

Setting the system date and time of a storage system

Uploading the files required for initial configuration

Getting information about the transfer destinations of audit log files

Specifying the transfer destinations of audit log files

Sending test messages to the transfer destinations of audit log files

Getting SNMP settings

Specifying the SNMP error notification destinations

Sending a test SNMP trap

Getting a list of license information

Getting information about a specific license

Installing software

Enabling or disabling a license

Removing software

Still Looking?

Quick Links

Overview of the initial settings of a storage system

Getting the system date and time of a storage system

Getting a list of time zones that can be used in a storage system

Setting the system date and time of a storage system

Uploading the files required for initial configuration

Getting information about the transfer destinations of audit log files

Specifying the transfer destinations of audit log files

Sending test messages to the transfer destinations of audit log files

Getting SNMP settings

Specifying the SNMP error notification destinations

Sending a test SNMP trap

Getting a list of license information

Getting information about a specific license

Installing software

Enabling or disabling a license

Removing software