Starting, restarting and stopping the IBM IoT MessageSight server by using REST Administration APIs

System administrators can restart and stop the IBM® IoT MessageSight server by using REST Administration APIs.

About this task

You can restart and stop the server by using REST Administration APIs or by using the IBM IoT MessageSight Web UI. For more information about using the IBM IoT MessageSight Web UI to restart and stop the server, see Restarting, stopping, and viewing the status of the IBM IoT MessageSight server by using the IBM IoT MessageSight Web UI. You can start the server by using docker or systemctl commands.

Procedure

Check the status of the IBM IoT MessageSight server, by using the IBM IoT MessageSight REST API GET method with the following IBM IoT MessageSight service URI:

http://<admin-endpoint-IP:port>/ima/v1/service/status
- If the server status is Running, the server is running. You can restart or stop the server by using REST Administration APIs.
- If the server status is Maintenance, the server is in maintenance mode. For more information about maintenance mode, see Maintenance mode.
Note: If the server is not running, a failure to connect error is received in response to the REST call. You can start the server by using docker or systemctl commands.
Choose an appropriate action:
- To start the server in a Docker environment, use the following command:
  docker start <container name>
- To start the server on a Host OS, use the following command:
  systemctl start IBMIoTMessageSightServer
- To restart the server use the IBM IoT MessageSight REST API POST method with the following IBM IoT MessageSight service URI:
  http://<admin-endpoint-IP:port>/ima/v1/service/restart
  - To restart the server in maintenance mode, provide configuration data in the payload of the POST method by using the following schema:
```
{    
  "Service": "Server", 
      "Maintenance": "start"|"stop"
}
```
    Where:
    
    Maintenance: "start"|"stop"
    
    Optional.
    
    If this option is set to start, the server comes up in maintenance mode on restart. If set to stop, the server comes up in production mode on restart.
  - To restart the server and to specify whether the store is cleaned as part of the shutdown process, provide configuration data in the payload of the POST method by using the following schema:
```
{    
  "Service": "Server", 
      "CleanStore": true|false
}
```
    Where:
    
    CleanStore: true|false
    
    Optional.
    
    If this option is set to true, then the store is cleaned as part of the shutdown process. The server does not need to be in maintenance mode for the store to be cleaned.
    Note: You cannot clean the store of an IBM IoT MessageSight server that is a member of a cluster.
- To stop the server, use the IBM IoT MessageSight REST API POST method with the following IBM IoT MessageSight service URI:
  http://<admin-endpoint-IP:port>/ima/v1/service/stop

Example

The following example uses cURL to show how a GET method is used to view the status of the server:

curl -X GET http://127.0.0.1:9089/ima/v1/service/status

The following example shows a successful example response to the GET method used to view the status of the server:


{
  "Version":"v1",
  "Server": {
    "Name": "TestSystem:9089",
    "UID": "aFWxYf32",
    "Status": "Running",
    "State": 1,
    "StateDescription": "Running (production)",
    "ServerTime": "2016-03-04T14:46:53.081Z",
    "UpTimeSeconds": 4134,
    "UpTimeDescription": "0 days 1 hours 8 minutes 54 seconds",
    "Version": "2.0 20160304-0400",
    "ErrorCode": 0,
    "ErrorMessage": ""
  },
  "Container": {
    "UUID":"034c91ce828a4f5c2c21d7cd7f04628368b63bd308825ec2d9dab5096ff04ca0"
  },
  "HighAvailability": {
    "Status": "Inactive",
    "Enabled": false
  },
  "Cluster": {
    "Status": "Inactive",
    "Enabled": false
  },
  "Plugin": {
    "Status": "Inactive",
    "Enabled": false
  },
  "MQConnectivity": {
    "Status": "Active",
    "Enabled": true
  },
  "SNMP": {
    "Status": "Active",
    "Enabled": true
  }
}

The following example uses cURL to show how a POST method is used to restart the server in production mode without cleaning the store:


curl -X POST \
   -H  'Content-Type: application/json'  \
   -d  '{                       
         "Service": "Server",       
           "CleanStore": false
        }
  '   \
http://127.0.0.1:9089/ima/v1/service/restart

An example response to the POST method:

{           
          "Version": "v1",   
            "Code": "CWLNA6011",   
            "Message": "The requested configuration change has completed successfully ."
          }

The following example uses cURL to show how a POST method is used to stop the server:


curl -X POST \
   -H  'Content-Type: application/json'  \
   -d  '{                       
         "Service": "Server" 
        }
  '   \
http://127.0.0.1:9089/ima/v1/service/stop

An example response to the POST method:

{           
          "Version": "v1",   
            "Code": "CWLNA6011",   
            "Message": "The requested configuration change has completed successfully ."
          }