Encryption/servers: GET

Displays information about RKM servers.

Availability

Available on all IBM Storage Scale editions.

Description

The GET scalemgmt/v2/encryption/servers request displays information about tenants and remote key manager (RKM) servers that they are associated with. For more information about the fields in the data structures that are returned, see the mmkeyserv command in the IBM Storage Scale documentation.

Request URL

https://IP address of API server:<port>/scalemgmt/v2/encryption/servers
where
servers
Specifies the resource of this GET call.

Request headers

Content-Type: application/json
Accept: application/json

Parameters

Table 1. List of parameters
Parameter name Description and applicable keywords Required/Optional
keyServer The hostname or IP address of the RKM server for which the details are displayed. Required

Request data

No request data.

Response data

{ 
    "jobs": [
        {
            "jobId": Job ID,
            "status": "RUNNING | COMPLETED | FAILED",
            "submitted": "Time and date",
            "completed": "Time and date",
            "runtime": Time,
            "request": {
                "type": "GET | POST | PUT | DELETE",
                "url": "Request URL"
            },
            "result": {
                "progress": [],
                "commands": [
                    "Command name "
                ],
                "stdout": [
                "type": Server type"
                "backupKeyServers": Server type
                "distribute": "Keystore file"
                "fips140mode" : "Password" 
                "interval": Certification file label"
                "ipa": Tenant name
                "keyServer": "Tenant name"
                "kmipCertificateExpiration" : "Tenant name" 
                "label": Tenant name"
                "nistCompliance": Tenant name
                "restCertificateExpiration": "Tenant name"
                "restPort" : "Port number" 
                "retry": Number of attempts"
                "timeout": Number of attempts
                "userID": "Number of attempts"

                "tenantName" : "Tenant name" 
                "keyServer": Key server name"
                "registeredClient": Client details
                "rkmId": "Server ID"
                "tenantName" : "Tenant name" 
                "keyServer": Key server name"
                "registeredClient": Client details
                "rkmId": "Server ID"
                "tenantName" : "Tenant name" 
                ],
                "stderr": [],
                "exitCode": Code            },
            "pids": []
        }
    ],
    "status": {
        "code": Status code,
        "message": "Status message"
    }
}
    }
For more information about the fields in the following data structures, see the links at the end of the topic.
"jobId": "Job ID"
The unique ID of the job.
"status": "RUNNING | COMPLETED | FAILED"
The status of the job.
"submitted": "Time and date"
The time and date when the job was submitted.
"completed": "Time and date"
The time at which the job was completed.
"runtime": "Time and date"
The time that the job took to run.
"request"
"type": "GET | POST | PUT | DELETE"
The request type.
"URL": "Request URL"
The URL through which the job is submitted.
"result"
"progress": Job progress
Progress information for the request.
"commands": "Command name
Array of commands that are run in this job.
"stdout": "message
Request Information.
"backupKeyServers": Back up servers"
The comma-separated list of server names that is added to the list of backup RKM servers in the RKM.conf file
"distribute": yes | no"
Specifies whether the list of RKM server names (main RKM server and backup RKM servers) in the RKM.conf file are arranged in a different order on each node so that each node connects with the servers in a different order.
"fips140mode": on | off"
Specifies whether the FIPS 140 certified encryption model is enabled for communications between the nodes..
"interval": Time"
The number of microseconds to wait between connection retries. The valid range is 1 - 1000000000. The default value is 10000 (0.1 seconds)..
"ipa": IP address"
The server IP address.
"keyServer": Server name"
The RKM server name.
"kmipCertificateExpiration": Date and time"
The expiration date and time of the non-self-signed certificate files in a certificate chain that is used by the specified key server to establish communication on the KMIP port.
"label": Server label"
The label to identify the RKM server.
"nistCompliance": off | SP800-131A"
Specifies whether GPFS operates in the NIST 800-131A mode.
"restCertificateExpiration": Time and date"
The expiration date and time of the non-self-signed certificate files in a certificate chain that is used by the specified key server to establish communication on the REST port.
"restPort": REST Port number"
The port number for the Representational State Transfer (REST) interface.
"retry": Number of attempts"
The number of attempts to retry a connection to an RKM server. The valid range is 1 - 10 retries. The default value is three retries.
"timeout": Time"
The connection timeout, in seconds, for retrieving an MEK from an RKM server. The valid range is 1 - 120 seconds. The default value is 60 seconds.
"type": Server type"
The type of server.
"userID": REST user ID"
The user ID for the RKM server. The default value is SKLMAdmin.
"exitCode":"Exit code"
Exit code of command. Zero indicates success and any other value denotes failure.
"stderr":"Error"
CLI messages from stderr.
"pids": "Process IDs
The process IDs for the job.
"status":
Return status.
"message": "ReturnMessage"
The return message.
"code": ReturnCode
The return code.

Examples

The following example gets information on the RKM server.

Request data:
curl -X GET --header 'Content-Type: application/json' --header 'Accept: text/html' 'https://198.51.100.1:443/scalemgmt/v2/encryption/servers?keyServer=lodestar1.fyre.ibm.com'
Response data:
Note: In the JSON data that is returned, the return code indicates whether the command is successful. The response code 200 indicates that the command successfully retrieved the information. Error code 400 represents an invalid request and 500 represents internal server error. 
{
    "jobs": [
        {
            "jobId": 3000000000011,
            "status": "COMPLETED",
            "submitted": "2021-06-21 05:22:28,005",
            "completed": "2021-06-21 05:22:28,309",
            "runtime": 304,
            "request": {
                "type": "GET",
                "url": "/scalemgmt/v2/encryption/servers"
            },
            "result": {
                "progress": [],
                "commands": [
                    "mmkeyserv rkm show "
                ],
                "stdout": [
                {
                "serverList": [
                {
                "backupKeyServers": "",
                "distribute": "yes",
                "fips140mode": "off",
                "interval": 10000,
                "ipa": "9.30.252.171",
                "keyServer": "lodestar1.fyre.ibm.com",
                "kmipCertificateExpiration": "2024-05-23 11:53:14 (+0000)",
                "label": "1_lodestar1",
                "nistCompliance": "on",
                "restCertificateExpiration": "2022-05-23 11:01:35 (+0000)",
                "restPort": "9443",
                "retry": 3,
                "timeout": 60,
                "type": "ISKLM",
               "userID": "SKLMAdmin"
               }
               ],
               "stderr": [],
                "exitCode": 0
            },
            "pids": []
        }
    ],
    "status": {
        "code": 200,
        "message": "The request finished successfully."
    }
}

Related information

mmkeyserv command in the IBM Storage Scale documentation.