Invoke Agent REST Service
Use the Invoke Agent REST Service to run the various configuration services that are provided by the IBM® Security Guardium® Key Lifecycle Manager agent for configuring IBM Security Guardium Key Lifecycle Manager instances for multi-master data replication.
- Operation
POST
- URL
- https://host:port/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService
By default, Guardium Key Lifecycle Manager server listens to the secure port 9443 (HTTPS) for communication. During IBM Security Guardium Key Lifecycle Manager installation, you can modify this default port.
Request
Request Parameters
Parameter | Description |
---|---|
host | Specify the IP address or hostname of the IBM Security Guardium Key Lifecycle Manager server. |
port | Specify the port number on which the IBM Security Guardium Key Lifecycle Manager server listens for requests. |
Request Headers
Header name | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Authorization | SKLMAuth userAuthId=<authIdValue> |
Accept-Language | Any valid locale that is supported by IBM Security Guardium Key Lifecycle Manager. For example, en or de. |
Request body
- Request body to stop the agent
-
JSON property name Description requestType Specify the value 0 for this property to stop the agent that is installed in the master server of the cluster. - Request body to get agent version
-
JSON property name Description requestType Specify the value 4 for this property to obtain the version number of agent that is installed in the master server. - Request body to take database-level backup
-
JSON property name Description requestType Specify the value 7 for this property to take database-level backup of IBM Security Guardium Key Lifecycle Manager master server in the cluster. - Request body to restore the database backup
-
JSON property name Description requestType Specify the value 8 for this property to restore a valid database backup file to the same or another IBM Security Guardium Key Lifecycle Manager instance in the multi-master cluster. inputParams: - backupFilePath
- backupTimeStamp
- rollforwardStopTime
- restoreComplete
Specify the values for the following input parameters. - backupFilePath
- Location of the backup file to be restored.
- backupTimeStamp
- The time that the backup file was created.
- rollforwardStopTime
- The time that the ROLLFORWARD STOP operation was run.
- restoreComplete
- Optional. Status of the restore operation.
- Request body to start HADR service on DB2®
-
JSON property name Description requestType Specify the value 9 for this property to start the DB2 HADR service in the IBM Security Guardium Key Lifecycle Manager instance that is configured with primary database. - Request body to stop HADR service on DB2
-
JSON property name Description requestType Specify the value 10 for this property to stop the DB2 HADR service in the IBM Security Guardium Key Lifecycle Manager instance that is configured with primary database. - Request body to send database backup file
-
JSON property name Description requestType Specify the value 11 for this property to send the database backup file to another IBM Security Guardium Key Lifecycle Manager instance in the cluster. inputParams: - filePath
- fileName
- destinationIp
- destinationPort
Specify the values for the following input parameters. - filePath
- Specify the location to save the backup file.
- fileName
- Specify the backup file name that you want to send.
- destinationIp
- Specify the IP address of the IBM Security Guardium Key Lifecycle Manager system to which you want to send the backup file.
- destinationPort
- Specify the port number that is associated with the IBM Security Guardium Key Lifecycle Manager instance to which the backup file to be sent.
- Request body to update WebSphere® Application Server Liberty configuration
-
JSON property name Description requestType Specify the value 12 for this property to configure WebSphere Application Server Liberty with primary and standby database server details. inputParams: - dbName
- primaryDbServerName
- primaryDbportNumber
- alternateServerName
- alternatePortNumber
Specify the values for the following input parameters. - dbName
- Specify the name of the database instance.
- primaryDbServerName
- Specify the IP address or host name of the master server where HADR primary database is installed.
- primaryDbportNumber
- Specify the port number that is associated with the primary database server.
- alternateServerName
- Specify the IP address or host name of the master server where HADR standby database is installed. You can specify multiple comma-separated database host names.
- alternatePortNumber
- Specify the port number that is associated with the standby database server.
- Request body to get HADR status
-
JSON property name Description requestType Specify the value 13 for this property to obtain the HADR status in the IBM Security Guardium Key Lifecycle Manager instance, such as the current role of the database, primary, or standby. - Request body to set up HADR
-
JSON property name Description requestType Specify the value 14 for this property to set up the primary and standby database servers for HADR with necessary configuration parameters in an IBM Security Guardium Key Lifecycle Manager instance of the multi-master cluster. inputParams: - PRIMARY_IP_HOSTNAME
- PRIMARY_DB_PORT
- PRIMARY_HADR_PORT
- PRIMARY_DB_NAME
- PRIMARY_AGENT_PORT
- STANDBY_COUNT
- STANDBY_IP_HOSTNAME
- STANDBY_HADR_PORT
- STANDBY_DB_NAME
- STANDBY_AGENT_PORT
- STANDBY_0_IS_NEW
- STANDBY_0_DB_PORT
Specify the values for the following input parameters. - PRIMARY_IP_HOSTNAME
- Specify the IP address or host name of the master server where HADR primary database is installed.
- PRIMARY_DB_PORT
- Specify the port number for primary DB2 server.
- PRIMARY_HADR_PORT
- Specify the port number for the HADR primary database.
- PRIMARY_DB_NAME
- Specify the name of the primary DB2 server.
- PRIMARY_AGENT_PORT
- Specify the port number that is configured for the agent in a master server where primary database is installed.
- STANDBY_COUNT
- Specify the number of standby databases in the multi-master cluster. HADR supports multiple standby databases.
- STANDBY_IP_HOSTNAME
- Specify the IP address or host name of the master server where HADR standby database is installed. You can specify multiple comma-separated database host names.
- STANDBY_HADR_PORT
- Specify the port number for the HADR standby database.
- STANDBY_DB_NAME
- Specify the name of the standby database instance.
- STANDBY_AGENT_PORT
- Specify the port number that is configured for the agent in a master server where standby database is installed.
- STANDBY_0_IS_NEW
- Specify whether the standby master is newly added.
- STANDBY_0_DB_PORT
- Specify the port number for standby DB2 server.
Response
Response Headers
Header name | Value and description |
---|---|
Status Code |
|
Content-Type | application/json |
Content-Language | Locale for the response message. |
Success response body
JSON object with the following specification:
JSON property name | Description |
---|---|
status | Returns the value that is specified by the message property. |
message | Returns the status message that indicates the success or failure of the multi-master configuration service that was run. |
requestType | Returns the request type number, which indicates the type of configuration service that was run. |
outputParams | Returns the output parameters for the configuration service that was run. |
Error Response Body
JSON object with the following specification.
JSON property name | Description |
---|---|
code | Returns the application error code. |
message | Returns a message that describes the error. |
Examples
- Service request to run the various multi master configuration services
- Stop agent service
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en { "requestType" : "0" }
- Success response
Status Code : 200 OK Content-Language: en { "status":"0", "message":"Stop agent request processed successfully.", "requestType":"0", "outputParams":[] }
- Get agent version
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en { "requestType" : "4" }
- Success response
Status Code : 200 OK Content-Language: en { "status":"0", "message":"Agent Version", "requestType":"4", "outputParams":[{"name":"version", "value":"1.0"}] }
- Take database backup
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en { "requestType" : "7" }
- Success response
Status Code : 200 OK Content-Language: en { "status":"0", "message":"Take DB backup services completed successfully.", "requestType":"7", "outputParams":[] }
- Restore a database backup
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en { "requestType" : "8", "inputParams":[ {"name" : "backupFilePath", "value" : "/opt/mysklmbackups/sklm_v3.0.0.0_20170705235417-1200_backup"}, {"name" : "backupTimeStamp", "value" : ""}, {"name" : "rollforwardStopTime", "value" : ""}, {"name" : "restoreComplete", "value" : "true"} ] }
- Success response
Status Code : 200 OK Content-Language: en { "status":"0", "message":"Restore DB backup services successful.", "requestType":"8", "outputParams":[] }
- Start HADR
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en { "requestType" : "9" }
- Success response
Status Code : 200 OK Content-Language: en { "status":"0", "message":"Start HADR on DB successful.", "requestType":"9", "outputParams":[] }
- Stop HADR
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en { "requestType" : "10" }
- Success response
Status Code : 200 OK Content-Language: en { "status":"0", "message":"Stop HADR on DB successful.", "requestType":"10", "outputParams":[] }
- Send database backup file
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en { "requestType" : "11", "inputParams":[ {"name" : "filePath", "value" : "/opt/mysklmbackups"}, {"name" : "fileName", "value" : "sklm_v3.0.0.0_20170705235417-1200_backup"}, {"name" : "destinationIP", "value" : "9.194.243.151"}, {"name" : "destinationPort", "value" : "443"} ] }
- Success response
Status Code : 200 OK Content-Language: en { "status":"0", "message":"Send database backup file services successful.", "requestType":"11", "outputParams":[] }
- Update WebSphere Application Server Liberty configuration
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en { "requestType" : "12", "inputParams":[ {"name" : "dbName", "value" : "
klmdb42
"}, {"name" : "primaryDbServerName", "value" : "9.113.37.83"}, {"name" : "primaryDbportNumber", "value" : "50090"}, {"name" : "alternateServerName", "value" : "9.194.243.151"} {"name" : "alternatePortNumber", "value" : "50090"} ] }- Success response
Status Code : 200 OK Content-Language: en { "status":"0", "message":"Send database backup file services successful.", "requestType":"12", "outputParams":[] }
- Get HADR status
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/agent/invokeAgentService Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en { "requestType" : "13" }
- Success response
Status Code : 200 OK Content-Language: en { "status":"0", "message":"Get HADR status services successful.", "requestType":"13", "outputParams":[{"name":"hadrStatus", "value":"1"}] }
- Set up HADR
- Before you configure IBM Security Guardium Key Lifecycle Manager instances
with DB2 HADR, you must add the standby master by setting the
ignoreSetupHADR=true parameter.
Example for adding a standby master.
POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/addNodes Content-Type: application/json Accept : application/json Authorization: SKLMAuth userAuthId=139aeh34567m Accept-Language : en [ { "clusterName":"multimaster", "primaryHadrPort":"60030", "ignoreSetupHADR":"true" }, { "type":"Standby", "ipHostname":"klmclover.in.ibm.com", "httpPort":"443", "sklmUsername":"sklmadmin", "sklmPassword":"your_sklmadmin_password", "standbyPriorityIndex":"1" } ]
- Error response
Status Code : 400 Bad Request Content-Language: en {"code":"CTGKM6002E","message":"CTGKM6002E Bad Request: Invalid user authentication ID or invalid request format."}