Reference
This section contains information about troubleshooting, information on using the command-line interface, and information on using the REST API.
Troubleshooting
Issue | Description/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
Log in directly to or use SSH to log in to a system instance.
Navigate to the CLI tool:
cd <installation-folder>/cli/
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
Store the .tgz file in a folder on your computer.
Unpack the file:
tar zxvf filename
Syntax
The CLI tools have this syntax:
<tool-name> [options] [command] [command-specific-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.
To view detailed information about the contents of a request model, run:
<cli-tool-name> -d
<ModelName>
For example:
admincli -d
ServiceUpdateModel
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" } }
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
This table describes the typical reasons why these HTTP status codes are returned.
Status code | Meaning | Description |
400 | Bad Request |
The request body contains one or more of these:
If the request includes a UUID, the UUID might be incorrectly formatted. |
401 | Unauthorized | The provided credentials are incorrect. |
403 | Forbidden | You do not have permission to perform the request. |
404 | No Found | The resource you are trying to retrieve or edit cannot be found. |
409 | Conflict | The resource you are trying to create already exists. |
500 | Internal Server Error | The system experienced an error. |
599 | Network Connection Timeout Error | The CLI request timed out while trying to connect to the system or one of its instances. |
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 code | Description |
4000 | SSL certificate not trusted. |
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.
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.
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.
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 }
- 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.
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..."
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.
To obtain the token and pass it as part of a request:
Procedure
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'
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 usermaria
: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.
To use the MAPI page to run a method:
Procedure
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.
Select:
- In the Object Storage Management App, select REST API.
- In the System Management App, select REST API - Admin.
Expand the category containing the method you want.
Select the row for the method you want.
To use an Object Storage Management method, enter the XSRF token in the field X-XSRF-TOKEN Header.
If the method you want needs a UUID:
Select the row for the
GET
method for the resource type that you want.Click Try it out.
In the JSON response body, copy the value in the field
uuid
for the resource that you want.
If the method you want needs a request body:
In the section Parameters, under Model Schema, click inside the JSON text box.
The JSON text is added to the field Value.
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.
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
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.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.
Select the management API you want to execute and then click Try it out.
In the section X-XSRF-TOKEN, paste the value of the cookie into the field X-XSRF-TOKEN Header.
Results
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
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 code | Meaning | Description |
400 | Bad Request |
The request body contains one or more of these:
If the request includes a UUID, the UUID might not be validly formatted. |
403 | Forbidden | You do not have permission to perform the request. |
404 | Not Found | The resource you are trying to retrieve or edit cannot be found. |
409 | Conflict | The resource you are trying to create already exists. |
500) | Internal Server Error | The system experienced an error. |
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 code | Description |
4000 | SSL certificate not trusted. |
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> } ] }