Disabling TIBCO FTL® clients via the REST API

The Realm Server web-based user interface provides a means of human-accessible way to disable clients from the monitoring pages, but in some cases, you may want to disable a client via a programmatic interface.

TIBCO FTL^® provides this capability via the REST API (which is actually how the web-based UI does it as well). Here are some examples to step you through the process of finding a specific client and then disabling it all via programmatic interfaces.

The REST API can list all of the clients currently known to the Realm Server:  

 curl http://localhost:8080/api/v1/clients

The response to this request will give you a full list of clients including specific information for each of them such as:

• Client ID
• Application Name and Instance
• User Name
• Start time
• Host
• Status

The actual response will look something like this:

 {     "clients": [         {             "app_instance": "default",             "app_name": "app1",             "host": "test_host",             "id": 6031,             "ip": "127.0.1.1",             "last_contact": "Feb 10, 2016 7:43:56 PM",             "last_contact_delta": 55916,             "other_info": "Cores=8, Group=trading, Effective User=messaging, User=bob, Effective Group=messaging_grp, Pid=2871, OS Spec=Linux 3.16.0-38-generic x86_64",             "realm_revision": 1095,             "startup": "Feb 10, 2016 7:35:56 PM",             "status": 1,             "status_label": "Running",             "user": "guest",             "version": "5.0.0  dev V0"         },         {             "app_instance": "default",             "app_name": "app1",             "host": "test_host",             "id": 6033,             "ip": "127.0.1.1",             "last_contact": "Feb 10, 2016 7:43:57 PM",             "last_contact_delta": 55802,             "other_info": "Cores=8, Group=trading, Effective User=messaging, User=bob, Effective Group=messaging_grp, Pid=2893, OS Spec=Linux 3.16.0-38-generic x86_64",             "realm_revision": 1095,             "startup": "Feb 10, 2016 7:35:57 PM",             "status": 1,             "status_label": "Running",             "user": "guest",             "version": "5.0.0  dev V0"         },         {             "app_instance": "london",             "app_name": "app2",             "host": "test_host",             "id": 6035,             "ip": "127.0.1.1",             "last_contact": "Feb 10, 2016 7:43:57 PM",             "last_contact_delta": 55607,             "other_info": "Cores=8, Group=trading, Effective User=messaging, User=bob, Effective Group=messaging_grp, Pid=2915, OS Spec=Linux 3.16.0-38-generic x86_64",             "realm_revision": 1095,             "startup": "Feb 10, 2016 7:35:57 PM",             "status": 1,             "status_label": "Running",             "user": "guest",             "version": "5.0.0  dev V0"         },         {             "app_instance": "nyc",             "app_name": "app2",             "host": "test_host",             "id": 6037,             "ip": "127.0.1.1",             "last_contact": "Feb 10, 2016 7:43:57 PM",             "last_contact_delta": 55360,             "other_info": "Cores=8, Group=trading, Effective User=messaging, User=bob, Effective Group=messaging_grp, Pid=2937, OS Spec=Linux 3.16.0-38-generic x86_64",             "realm_revision": 1095,             "startup": "Feb 10, 2016 7:35:57 PM",             "status": 1,             "status_label": "Running",             "user": "guest",             "version": "5.0.0  dev V0"         },         {             "app_instance": "default",             "app_name": "app2",             "host": "test_host",             "id": 6039,             "ip": "127.0.1.1",             "last_contact": "Feb 10, 2016 7:43:57 PM",             "last_contact_delta": 55061,             "other_info": "Cores=8, Group=trading, Effective User=messaging, User=bob, Effective Group=messaging_grp, Pid=2958, OS Spec=Linux 3.16.0-38-generic x86_64",             "realm_revision": 1095,             "startup": "Feb 10, 2016 7:35:57 PM",             "status": 1,             "status_label": "Running",             "user": "guest",             "version": "5.0.0  dev V0"         }     ] }

Using this information, there are a number of ways you can specify a specific client or group of clients to disable. You can disable a specific client by ID as well as clients with shared characteristics like application name or user name.

 curl http://localhost:8080/api/v1/clients/6033 -d '{"cmd":"disable"}' curl http://localhost:8080/api/v1/clients?app_name=app1 -d '{"cmd":"disable"}' curl http://localhost:8080/api/v1/clients?user=bob -d '{"cmd":"disable"}'

Note that you're providing the selection criteria via the URL itself and the command to disable the clients via the data option which will be sent as part of the POST request.  Most REST requests will operate the same way - selecting what you want to operate on via the URL and what operation you want to perform on that selection via the data sent as part of the POST request.

If you disable a client, it will report an exception in its log something like this:

 com.tibco.ftl.exceptions.FTLClientShutdownException: Cannot dispatch on a shutdown client2017-05-26 13:36:49.319 debu pubs: tibPublisher_Close (0x1c1e2170, 0x2900000025)       at com.tibco.ftl.jni.NativeEventQueue.dispatch(Native Method)      at com.tibco.ftl.jni.NativeEventQueue.dispatch(NativeEventQueue.java:122)      at com.tibco.ftl.jni.NativeEventQueue.dispatch(NativeEventQueue.java:94)      at TibRecvMcast.recv(TibRecvMcast.java:146) at TibRecvMcast.main(TibRecvMcast.java:157)  Caused by: com.tibco.ftl.FTLException: TIBCO Exception:      Error Code = Client shutdown      Description = Cannot dispatch on a shutdown client      Thread Name = java.exe      Stack Trace:           tibEventQueue_Dispatch, 1954           ...

If you disable a client, directly via a REST API call or via the user interface, you'll be able to confirm the reason for the client exiting by checking the log - in the event of a disable (via any means), you'll clearly see the statement "Error Code = Client shutdown" in the client log.

Pre TIBCO FTL Release 5.3, you could not disable TIBCO eFTL^® clients in this manner but starting in that release, you'll be able to disable them just like any TIBCO FTL client by specifying the appropriate selection criteria and using the disable command.