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
200 OK
The request was successful. The response body contains the requested representation.
400 Bad Request
The authentication information was not provided in the correct format.
401 Unauthorized
The authentication credentials were missing or incorrect.
404 Not Found Error
The processing of the request fails.
500 Internal Server Error
The processing of the request fails because of an unexpected condition on the server.
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"
 }
]
Example for configuring DB2 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" : "14",
  "inputParams":
   [
	{"name":"PRIMARY_IP_HOSTNAME","value":"9.199.138.195"},
      {"name":"PRIMARY_DB_PORT","value":"50090"},
      {"name":"PRIMARY_HADR_PORT","value":"60030"},
      {"name":"PRIMARY_DB_NAME","value":"KLMDB42"},
      {"name":"PRIMARY_DB_USERNAME","value":"dbuser"},
      {"name":"PRIMARY_AGENT_PORT","value":"60015"},
      {"name":"STANDBY_COUNT","value":"1"},
      {"name":"STANDBY_0_IP_HOSTNAME","value":"9.199.138.208"},
      {"name":"STANDBY_0_HADR_PORT","value":"60030"},
      {"name":"STANDBY_0_DB_NAME","value":"KLMDB42"},
      {"name":"STANDBY_0_AGENT_PORT","value":"60015"},
      {"name":"STANDBY_0_IS_NEW","value":"True"},
      {"name":"STANDBY_0_DB_USERNAME","value":"dbusername"},
      {"name":"STANDBY_0_DB_PORT","value":"50090"} 
  ]
}
Success response
Status Code : 200 OK
Content-Language: en
{
"status":"0",
"message":"Setup HADR service successful.",
"requestType":"14",
"outputParams":[]
}
Error response
Status Code : 400 Bad Request
Content-Language: en
{"code":"CTGKM6002E","message":"CTGKM6002E Bad Request: Invalid user 
authentication ID or invalid request format."}