Reference
This section contains information about system limits, known issues, license and copyright information, and information on using the command-line interface and REST API.
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 - 2019 Hitachi Vantara Corporation. All rights reserved.
Troubleshooting
For information on viewing system events, see System events.
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 check on the specified service. You can ignore this event. The additional health check is not required and does not affect the other health checks used to display the service status on the Monitoring > Services page in the System Management application. |
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 - 2019 Hitachi Vantara Corporation. All rights reserved.
CLI reference
The system includes an administrative CLI for system management. This interface allows you to perform all tasks relating to system setup and configuration. Any administrative activity that you can perform in the System Management application or REST API can be performed through the CLI.
Your system may also include additional, product-specific CLI tools.
You can access the CLI tools from any instance. To do this:
1.Log in or SSH into a system instance.
2.Navigate to the CLI tool directory:
cd <installation-directory>/cli/
3.Navigate to the directory for the CLI tool you want. For example:
cd admin
You can install your system's CLI tools on your Linux computer. To do this, 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.
To install a CLI tool:
1.Store the .tgz file in a directory on your computer.
2.Unpack the file on Linux:
tar zxvf filename
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. See Viewing request models.
--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 -c option, displays information about commands in the specified category.
-k, --check-ssl-cert <true|false>
Whether to enable SSL security checking. When false, insecure connections are allowed.
-m, --model-schema <ModelName>
Returns the JSON-formatted schema for the specified request model. See Viewing request models.
-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. For information, see Adding identity providers.
-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.
•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
Some commands require that you include 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 requires.
For example, this help command output indicates that a command to update a service requires 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
Viewing request model formattingTo view the JSON format for the request model, run:
<cli-tool-name> -m <ModelName>
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
•Check 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 directory.
The options you specify explicitly in a CLI command override the options specified in the .conf file.
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 codesThis table describes the typical reasons why these HTTP status codes are returned.
Status code | Description |
---|---|
400 (Bad Request) |
The request body contains one or more of these: •An invalid entry •An invalid value for an entry •Invalidly formatted JSON If the request includes a UUID, the UUID may be invalidly formatted. |
401 (Unauthorized) |
The provided credentials are invalid. |
403 (Forbidden) |
You do not have permission to perform the request. |
404 (File 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 (Server Error) |
The system experienced an error. |
599 (Network Connection Timeout Error) |
The CLI request timed out while attempting 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.
Error 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> } ] }
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 - 2019 Hitachi Vantara Corporation. All rights reserved.
REST API reference
Your system provides a RESTful API that you can use for writing applications that manage the system. Anything you can do in the System Management application can also be performed using the REST API.
Information is available about the APIs in two places:
- For information about system management APIs, see the topics in this Help document.
- For information about Object Storage Management and S3 APIs, see the Help for the Object Storage Management application.
The REST API accepts and returns JSON.
To use the REST API, you need a user account that has permission to perform the actions you want. For information on assigning permissions to users, see Roles.
Requesting an access tokenOnce you have a user account, you need to request an authentication token from the system. To do this, you send an HTTP POST request to the /auth/oauth endpoint.
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:
-d grant_type=password \
-d username=user1 \
-d password=password1 \
-d scope=* \
-d client_secret=my-client \
-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 your token. For example:
{"access_token" : "eyJr287bjle..."
Notes: •To get a list of security realms for the system, send an HTTP GET request to the /setup endpoint. For example, to do this with cURL: curl -k -X GET --header 'Accept: application/json' 'https://mysystem.example.com:<System-Management-application-port>/api/admin/setup' For information on configuring security realms, see Adding identity providers. •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 need to specify your access token as part of all REST API requests that you make. You do this by submitting an Authorization header along with your request. Here's an example that uses cURL:
curl -X GET --header "Accept:application/json" https://mysystem.example.com:<System-Management-application-port>/api/admin/instances --header "Authorization: Bearer eyJr287bjle..."
Changing a password
You can use the REST API to change your system's password using the following cURL command.
$1=<server-name>
$2=<current-password>
$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=hci-client -d client_id=hci-client -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"'"}'
Your system provides web-based documentation pages where you can view all supported REST API methods, including the request bodies, request URLs, response bodies, and return codes for each. You can also use these pages to run each REST API method.
Viewing the API documentationTo view the REST API documentation, in the System Management application, click on the help icon (). Then click on REST API - Admin.
To view the HCP for cloud scale API documentation, click REST API in the Object Storage Management app.
Making requestsYou can use the REST API documentation pages to experiment with the REST API.
Note: Any requests you submit on the REST API page take effect on the system. |
To use the REST API page to run a method:
1.Click on the row for the method you want.
2.If the method you want requires that you specify a UUID:
a.Click on the row for the GET method for the resource type that you want.
b.Click on the Try it Out! button.
c.In the JSON response body, copy the value for the uuid field for the resource that you want.
Note: If you specify UUIDs when creating resources, the UUIDs are ignored. |
3.If the method you want requires that you specify a request body:
a.In the Parameters section, under Model Schema, click inside the JSON text box.
The JSON text is added to the Value field.
b.Edit the JSON in the Value field.
Note: Some methods may require other information in addition to or instead of UUIDs or JSON-formatted text. Some require particular string values or require that you browse for and select a file to upload. |
4.Click on the Try it out! button.
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 codesThis 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 (see Viewing and using REST API methods).
Status code | Description |
---|---|
400 (Bad Request) |
The request body contains one or more of these: •An invalid entry •An invalid value for an entry •Invalidly formatted JSON If the request includes a UUID, the UUID may be invalidly formatted. |
403 (Forbidden) |
You do not have permission to perform the request. |
404 (File 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 (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.
Error 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>
}
]
}
Trademarks, Legal disclaimer, Third-party software in this documentation
© 2017 - 2019 Hitachi Vantara Corporation. All rights reserved.