Reference

The CLI tools have this syntax:

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

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.

Password for the specified user account.

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

-r, --realm <realm>

Security realm where your user account is defined.

The hostname or IP address of a system instance.

-u, --username <username>

Username for an account that has permission to access system.

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 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:

For example:

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

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.

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.

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 response bodies have this format:

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

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.

After 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 method.

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-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..."

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:<admin-app-port>
/api/admin/instances --header "Authorization: Bearer eyJr287bjle..."

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"'"}'

To view the REST API documentation:

• In the Object Storage Management application, click the user icon () and then click REST API.
• In the System Management application, click the user icon () and then click REST API - Admin.

You can use the REST API documentation pages to experiment with the REST API.

To use the REST API page to run a method:

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.

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.

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>
        }
    ]
}