Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Reference

This section contains information about troubleshooting, information on using the command-line interface, and information on using the REST API.

Troubleshooting

System event issues
IssueDescription/Resolution

The event log contains instances of event id 6007 with this message:

Service service-name health check against HTTP /health port cannot succeed because it is on a different network than service Cluster-Worker. Health check ignored to prevent service interruption.

Your system uses both internal and external networks, but the service specified by the event is on a different network type from the Cluster-Worker service. Because of this, the system cannot perform an additional health verification on the specified service.

You can ignore this event. The additional health verification is not required and does not affect the other health verifications used to display the service status on the Monitoring > Services page in the System Management application.

The MAPI Gateway service becomes unresponsive.

If you're working with a storage component that is configured with multiple retries and long timeouts, and if the endpoint for the storage component is unreachable, and if as a result you send multiple verification or activation requests to the endpoint, the MAPI Gateway service can become unresponsive.

If the MAPI Gateway service becomes unresponsive, use the System Management application Services function Repair on it.

Users can't write to storage components, objects read from storage components are encrypted, and you receive the critical alert Failed to connect to KMS server.The Key Management System service is down. The service should restart automatically. When it restarts, log in to HCP for Cloud Scale on port 8200 and provide a quorum of unseal keys.

CLI reference

An administrative CLI is provided for system management. This interface lets you perform all tasks relating to system setup and configuration. Any administrative activity that you can perform in the Admin App or REST API can be performed through the CLI. You can avoid using an internet connection or a browser.

Your system can also include additional, product-specific CLI tools.

Accessing the CLI tools on a system instance

You can access the CLI tools from any instance

Procedure

  1. Log in directly to or use SSH to log in to a system instance.

  2. Navigate to the CLI tool:

    cd <installation-folder>/cli/
  3. Navigate to the folder for the CLI tool you want. For example:

    cd admin

Installing CLI tools on your computer

You can install your system's CLI tools on a Linux computer.

To install the CLI tools, you must have version 1.8 of the Java Runtime Environment (JRE) installed.

Your system's CLI tools are distributed in .tgz files along with the software installation package.

Procedure

  1. Store the .tgz file in a folder on your computer.

  2. Unpack the file:

    tar zxvf filename

Syntax

The CLI tools have this syntax:

<tool-name> [options] [command] [command-specific-options]

Options-c, --command <command|category>

Specifies the command you want to run. When used with the --help option, displays information about the specified command.

You can also use this option to specify a category of commands when using the --help option. Doing this displays information about all commands within the specified category.

-d, --model-definition <name>

Returns information about the specified request model.

--debug

Includes verbose debug output for troubleshooting purposes.

-h, --help <all>

Displays help information. If you specify the all argument, displays information an all commands. If you specify the --help option, displays information about commands in the specified category.

-k, --check-ssl-cert <true|false>

Whether to enable SSL security verification. When false, insecure connections are allowed.

-m, --model-schema <ModelName>

Returns the JSON-formatted schema for the specified request model.

-p, --password <password>

Password for the specified user account.

--port

The port for the system application that supports the CLI tool.

-r, --realm <realm>

Security realm where your user account is defined.

-s, --server <server>

The hostname or IP address of a system instance.

-u, --username <username>

Username for an account that has permission to access system.

-V, --version

Displays the CLI version.

Viewing available commands

  • To view all available commands, run:

    <cli-tool-name> --help all

  • To view all command categories, run:

    <cli-tool-name> --help

  • To view all commands within a category, run:

    <cli-tool-name> --help -c <category>

    For example:

    admincli --help -c instances

  • To view all information about a single command, run:

    <cli-tool-name> --help -c <command>

    For example:

    admincli --help -c listInstances

Viewing request models

Some commands need a JSON-formatted request body along with the command. The command's request model determines how you need to format the request body.

The help command for an individual command indicates what request model it needs.

For example, this help command output indicates that a command to update a service needs a ServiceUpdateModel request:

# ./admincli -c updateServiceConfig -h
usage: updateServiceConfig
Name:
  updateServiceConfig
Description:
  Configure service instances
Added:
  1.0
Usage:
  admincli -c updateServiceConfig <options>
Options:
  --service-update-model <ServiceUpdateModel>
File containing JSON text representing a ServiceUpdateModel for the command 
updateServiceConfig. Use the -m and -d options to retrieve information on request and 
response models.
Viewing request model information

To view detailed information about the contents of a request model, run:

<cli-tool-name> -d <ModelName>

For example:

admincli -d ServiceUpdateModel
Viewing request model formatting

To view the JSON format for the request model, run:

<cli-tool-name> -m <ModelName>

Editing configuration preferences

You can use the CLI tool's .conf file to specify settings to use every time you run a CLI command.

The CLI configuration file has this format:

{
  "defaultSettings": {
    "checkSSLCert": "[false|true]",(optional)
    "server": "<hostname>",(optional)
    "realm": "[local|<security-realm-name>]",(optional)
    "username": "<your-username>",(optional)
    "password": "<your-password>" (optional)
  }
}

For example, with the following configuration, all commands:

  • Are run against the system.example.com system
  • Verify the SSL certificate for the system before connecting
  • Uses the exampleUsersEast security realm to authenticate the specified username and password
{
  "defaultSettings": {
  "checkSSLCert": "true",
  "server": "system.example.com",
  "realm": "exampleUsersEast"
  }
}
File location

You can configure CLI preference by editing the existing .conf files in the CLI installation folder.

The options you specify explicitly in a CLI command override the options specified in the .conf file.

System error responses

If a CLI request reaches the system and the system returns an error, the CLI response contains:

  • An HTTP status code
  • Conditionally, a product-specific error code
  • A JSON-formatted error response body
HTTP status codes

This table describes the typical reasons why these HTTP status codes are returned.

Status codeMeaningDescription
400Bad Request

The request body contains one or more of these:

  • An entry that isn't valid
  • A value for an entry that isn't valid
  • Incorrectly formatted JSON

If the request includes a UUID, the UUID might be incorrectly formatted.

401UnauthorizedThe provided credentials are incorrect.
403ForbiddenYou do not have permission to perform the request.
404No FoundThe resource you are trying to retrieve or edit cannot be found.
409ConflictThe resource you are trying to create already exists.
500Internal Server ErrorThe system experienced an error.
599Network Connection Timeout ErrorThe CLI request timed out while trying to connect to the system or one of its instances.
Product-specific error codes

Some CLI requests return product-specific error codes in addition to an HTTP status code. These error codes are listed in the errorCodes field in the JSON response body. This table describes these error codes.

Status codeDescription
4000SSL certificate not trusted.
JSON response body

Error response bodies have this format:

{
    "statusCode": <HTTP-status-code>,
    "errorCode": <product-specific-error-code>,
    "errorMessage": <message>,
    "errorProperties": [
        {
            "name": <error-property>,
            "message": <error-property-message>
        }
    ]
}				

REST API Reference

Your system includes a RESTful API that you can use for writing applications that manage the system. Anything you can do in either the Object Storage Management application or the System Management application can also be performed using their REST APIs.

Getting started with the management APIs

HCP for cloud scale includes RESTful HTTP management application programming interfaces (MAPIs) for the Object Storage Management application and the System Management application. These MAPIs are separate and use separate ports.

System Management

You can execute all functions supported in the System Management application using MAPI methods. The System Management methods are served by the Admin service from any HCP for cloud scale node.

All URLs for the System Management MAPI methods have the following base, or root, uniform resource identifier (URI):

https://hcpcs_cluster:8000/api/admin/

The System Management MAPI is described in Swagger, available from the System Management user interface. Those methods not described in this document.

Object Storage Management

You can execute all functions supported in the Object Storage Management application and the S3 Console application using MAPI methods. The Object Storage Management management API (MAPI) supports management of the following:

  • Storage components and Amazon Simple Storage Service (Amazon S3) settings
  • Encryption of storage components
  • Administrative resources such as serial numbers and system events
  • User resources such as S3 user credentials and OAuth tokens
  • Public information such as available public ports

The Object Storage Management MAPI methods are served by the MAPI Gateway service from any HCP for cloud scale node.

All URLs for the Object Storage Management MAPI methods have the following base, or root, uniform resource identifier (URI):

https://hcpcs_cluster:9099/mapi/v1/

The Object Storage Management MAPI is described in this document. It is also described in Swagger, available from the Object Storage Management user interface.

Input and output formats

The API accepts and returns JSON.

The REST API accepts and returns JavaScript Object Notation (JSON). It does not support HTTPS 1.0 requests; all HTTPS 1.0 requests are denied. When the body of the request has contents, the MAPI accepts and returns JSON; when the body is empty, JSON format is unnecessary.

Access and authentication

To use the Object Storage Management or System Management MAPIs, you need a user account that has permission to perform the actions you want.

Requesting an access token

After you have a user account, you must request an authentication token from the system. To do this, you send an HTTP POST request to the method /auth/oauth.

When you generate a new access token, a refresh token also gets generated automatically.

Here's an example using the cURL command-line tool:

curl -ik -X POST https://mysystem.example.com:8000/auth/oauth/ \
-d grant_type=password \
-d username=user1 \
-d password=password1 \
-d scope=* \
-d client_secret=my-secret \
-d client_id=my-client \
-d realm=marketingUsers

In response to this request, you receive a JSON response body containing an access_token field. The value for this field is the token. For example:

{
"access_token": "eyJr287bjle..."
"expires_in": 7200
}
Note
  • To get a list of security realms for the system, send an HTTP GET request to the method /setup. For example, to do this with cURL:
    curl -k -X GET --header 'Accept: application/json' \ 
    'https://mysystem.example.com:8000/api/admin/setup'
  • To get an access token for the local admin user account, you can omit the realm option for the request, or specify a realm value of Local.
Submitting the access token

You must specify the access token as part of all REST API requests that you make. You do this by submitting an Authorization header along with the request. Here's an example that uses cURL:

curl -X GET --header "Accept:application/json" \
https://mysystem.example.com:8000/api/admin/instances \
--header "Authorization: Bearer eyJr287bjle..."
Changing a password

You can use the MAPI to change the system's password using the following cURL commands, where $1=server_name, $2=current_password, and $3=new_password:

TOKEN=$(curl -ik -X POST https://$1.mysystem.com:8000/auth/oauth/ \
-d grant_type=password -d username=admin -d password=$2 \
-d scope=* -d client_secret=client-secret -d client_id=client-id \
-d realm=local 2>&1  | grep access_token | awk -F: '{print $2}' \ 
| awk -F\" '{print $2}')
curl -v -X POST --header 'Content-Type: application/json' \
--header "Authorization: Bearer $TOKEN" \
https://$1.mysystem.com:8000/api/admin/setup/password \
-d '{"password": "'"$3"'"}'

Requesting and submitting an XSRF token

To protect against cross-site-request forgery, the Object Storage Management MAPI requires an XSRF token in all requests.

The Object Storage Management MAPI requires you to pass the XSRF token both in the request header and as a cookie within the request.

NoteThe XSRF token has a limited lifetime, so it's best to obtain a fresh token before issuing every group of requests.

To obtain the token and pass it as part of a request:

Procedure

  1. Obtain the token.

    The following command string obtains the token, locates it within the response, strips out extraneous text, and stores it as a variable:
    xsrf='curl -skc - https://hcpcs_cluster.com:9099/ \
    -H "user-agent: Mozilla" | grep XSRF-TOKEN | cut -d$'\t' -f 7'
  2. Include the token both in the request header and as a cookie within a MAPI request.

    The following command string uses an OAuth token defined as the variable $token in a MAPI request to list the user maria:
    curl -s -k -H "X-XSRF-TOKEN:${xsrf}" \
    -H "Authorization: Bearer $token" \
    -b "XSRF-TOKEN=${xsrf}" -H "accept: application/json" \
    -H "Content-Type: application/json" 
    -d '{"nameFilter": "maria"}' \
    -X POST https://hcpcs_cluster.com:9099/mapi/v1/user/list

Viewing and using MAPI methods

Your system includes web-based documentation pages where you can view the MAPI methods for both the Object Storage Management and System Management applications, including the request bodies, request URLs, response bodies, and return codes for each. You can also use these pages to run each MAPI method.

You can use the MAPI documentation pages to experiment with the MAPI. Any requests you submit on the page take effect on the system.

NoteIf you specify UUIDs when creating resources, the UUIDs are ignored.

To use the MAPI page to run a method:

Procedure

  1. In either the Object Storage Management App or the System Management App, select the user profile icon, in the upper right portion of the page.

  2. Select:

    • In the Object Storage Management App, select REST API.
    • In the System Management App, select REST API - Admin.
    A Swagger page opens for the selected MAPI.
  3. Expand the category containing the method you want.

  4. Select the row for the method you want.

  5. To use an Object Storage Management method, enter the XSRF token in the field X-XSRF-TOKEN Header.

  6. If the method you want needs a UUID:

    1. Select the row for the GET method for the resource type that you want.

    2. Click Try it out.

    3. In the JSON response body, copy the value in the field uuid for the resource that you want.

  7. If the method you want needs a request body:

    1. In the section Parameters, under Model Schema, click inside the JSON text box.

      The JSON text is added to the field Value.

    2. Edit the JSON in the field Value as needed.

      NoteSome methods might need other information in addition to or instead of UUIDs or JSON-formatted text. Some methods need particular string values or need you to browse for and select a file to upload.
  8. Click Execute.

    The method is executed and the results appear in the section Responses.

Including XSRF tokens in MAPI Swagger requests

Swagger does not automatically populate the X-XSRF-TOKEN header when executing Object Storage Management MAPI requests.

To obtain the token within a browser and include it in a MAPI request through Swagger:

Procedure

  1. From the user profile icon on the top right of an Object Storage Management window, select REST API.

    A Swagger page opens in a new tab.
  2. Locate and copy the value of the cookie XSRF-TOKEN:

    • In Chrome, from the Customize menu (in the upper right corner), select More tools > Developer tools. From the Developer Tools window select Storage > Cookies. Select and copy the value of the cookie XSRF-TOKEN.
    • In Firefox, from the Open menu (in the upper right corner), select Web Developer > Storage Inspector. From the Developer Tools window select Cookies. Select and copy the value of the cookie XSRF-TOKEN.
  3. Select the management API you want to execute and then click Try it out.

  4. In the section X-XSRF-TOKEN, paste the value of the cookie into the field X-XSRF-TOKEN Header.

Results

You can now execute the method.

Error responses

When an API request fails, the API returns:

  • An HTTP status code
  • Conditionally, a system-specific error code
  • A JSON-formatted error response body
HTTP status codes

This table describes the typical reasons why these HTTP status codes are returned. For information on the status codes for a particular method, view the system REST API web interface.

Status codeMeaningDescription
400Bad Request

The request body contains one or more of these:

  • An entry that's not valid
  • A value for an entry that's not valid
  • JSON code that's not validly formatted

If the request includes a UUID, the UUID might not be validly formatted.

403ForbiddenYou do not have permission to perform the request.
404Not FoundThe resource you are trying to retrieve or edit cannot be found.
409ConflictThe resource you are trying to create already exists.
500)Internal Server ErrorThe system experienced an error.
System-specific error codes

Some API requests return system-specific error codes in addition to an HTTP status code. These error codes are listed in the errorCodes field in the JSON response body. This table describes these error codes.

Status codeDescription
4000SSL certificate not trusted.
JSON response body

REST API error responses have this format:

{
    "statusCode": <HTTP-status-code>,
    "errorCode": <system-specific-error-code>,
    "errorMessage": <message>,
    "errorProperties": [
        {
            "name": <error-property>,
            "message": <error-property-message>
        }
    ]
}

 

  • Was this article helpful?