TIBCO Streaming applications run as a Windows Service are managed using the 'epadmin systemservice' command described here in the product documentation:
TIBCO Streaming > EP Commands > epadmin and epdev References > epadmin-systemservice There are natural additional requirements for Streaming applications when run as a service due to the interaction of platform and operating security settings and how services are started. Startup may involve re-installing the node directory. Starting the service immediately starts the application with no time for an administrator to modify the node configuration. When manually installing and starting a Streaming application the node administrator has opportunity to perform additional configuration commands between the 'epadmin install node' step and the 'epadmin start node' step. That is not available when run as a service.
The default security configuration assigns the user that performed the 'epadmin install node' command as the node administrator and assigns a random and unreported password. When run as a service, the default user is the Windows SYSTEM account. To override this one must configure a different account using the Windows Services control panel. There is no way to impersonate the Windows SYSTEM account using "Run as...", so when using the defaults there is no way to manually administrate a node running as a service using the 'epadmin' command.
Specifically the limitations are:
- When configured as a service the application archive and all referenced configuration files must be complete and correct for the service environment without needing any manual administration to run correctly.
- When starting the service its node directory may be re-created and the application immediately started with no opportunity for intervention by an administrator.
- If run using the Windows SYSTEM account, no administrative actions are allowed on the node.
- The node directory may or may not be reinstalled from session to session depending on whether the application was able to shut down cleanly in the prior session.
If the service node crashes, then a snapshot report (using 'epadmin create snapshot') is created in the
C:\Windows\System32 directory for analysis later. It is a judgement call whether to allow the service to immediately restart, since the cause of the crash is likely a persistent issue and will simply crash the service again. Streaming applications have robust queuing to allow the application to recover from bursts of higher than expected data ingestion rates. Streaming adapters have built-in reconnection logic to restore service when a network or temporary system error causes a disconnect. With these facilities, when a well-tuned Streaming application fails it is usually for some serious error and not a transient condition. The node snapshot should be investigated and the cause of the crash understood and corrected before manually restarting the service.
In short, plan that:
- there are no administrative runtime changes allowed or will persist
- when a node is re-installed, no state from the prior session will be remembered
- when a node is not re-installed, configuration or even an updated application archive may not be read or used
- service restarts after a failure without changes will not result in a correctly working service
Best practices are to: 1. Create a local Windows user account and configure the service to run as that user.
- This allows you to configure exactly the PATH and other Environment Variables needed by the service without interference from other user's settings.
- This allows you to use "Run As..." to open a shell to run 'epadmin' commands to inspect the running node.
2. Set service recovery after a failure to "Take No Action" and alert an administrator.
3. Use a substitution file for deployment-specific configuration in a file location the service will reference by absolute path.
- This allows you to change key configuration items to be used at next full startup (when node directory is re-created) without having to re-build and re-register the application archive.
epadmin install systemservice --name="SBChirpSvc" --nodedirectory=/svc/nodes --nodename=A.chpsvc --application=/svc/apps/sbchirp-app.zip --displayname=SBChirp --startup=automatic --nodedeploy=/svc/apps/sbchirp-app_node.conf --substitutionfile=/svc/apps/sbchirp-app.properties
4. Read all other files from known absolute file locations, and not as resource files from project folder "src/main/resources"
- This allows you to make changes without having to re-build and re-register the application archive
- You must still stop the service, remove the old node directory, and start the service to guarantee these files are re-read
- You may provide absolute file paths as module parameters set from the substitution file for improved configurability (e.g. ${datapath}) instead of as a hardcoded path as shown here: