Configuring Windows as a Service

Overview

Applications can be installed as Windows services. This section assumes familiarity with Windows services concepts and general architecture. Native Windows tools are used to manage these services once they are installed.

Installation

Applications that are installed as Windows services are installed using the epadmin install systemservice command. The user in which the service should run is specified when installing the service. This user must have the JAVA_HOME environment variable set. By default this user is the SYSTEM user (use the username parameter to run install systemservice to use a different user).

The install systemservice command takes several parameters that can be grouped into the following categories:

  • event processing application (application archive, node deploy configuration, substitution file).

  • node (node directory and node name).

  • Windows service information (service name, service startup type, and so on).

install systemservice command example:

install systemservice --name="my-service" --nodedirectory=my-nodes --nodename=A.X
install systemservice --name="my-service" --nodedirectory=my-nodes --nodename=A.X \
 --application=my-app.zip --displayname=my-app --startup=automatic \
 --nodedeploy=node.conf --substitutionfile=my-app.properties
install systemservice --name="my-service" --nodedirectory=my-nodes --nodename=A.X \
 --username=.\my-service-user --password=super-secret

install systemservice command parameters:

Name Description Required?
application Path to application archive. No. No default value. If not specified node is started without an application.
displayname Service display name. No. Default value is name parameter value.
name Service name. Yes.
nodedeploy Path to node deploy configuration file. Can only be specified if application parameter is also specified. No. No default value.
nodedirectory Path of the parent directory that will contain the node installation directory. The node installation directory is <nodedirectory>\<nodename>. Yes.
nodename Fully qualified node service name. Yes.
password User account password. If not specified with a non-built in Windows account (LocalService, NetworkService, or LocalSystem) username, a password prompt is displayed. No. No default value.
startup An enumeration specifying the service startup behavior. Valid values are automatic, delayed, and manual. No. Default value is manual.
substitutionfile Path to substitution variable. Can only be specified if application parameter is also specified. No. No default value.
username User account to use for service. This parameter must be specified as <domain-name>\<user-name>. The local domain must be specified using a period (.). The NT AUTHORITY domain name must be used for the built-in LocalService and NetworkService accounts No. Default value is the LocalSystem account.

Service Startup Parameters

The startup parameters for a service are stored in the Windows registry using this key when the service is installed (the following long line wraps to the next for clarity):

HKEY_LOCAL_MACHINE\SOFTWARE\<node-name>\TIBCO Software Inc.\Settings\sb-cep\
  <service-name>\<service-name>Startup
  • Where node-name is the fully qualified service name of the node running the application.

  • Where service-name is the service name specified when the application was installed as a service.

You can change these parameters directly in the registry before a service is started:

Variable Description
application Absolute path to application archive.
nodedeploy Absolute path to node deploy configuration file.
nodedirectory Absolute path to node directory.
nodename Fully scoped node service name.
substitutionfile Absolute path to substitution file.

Operational Behavior

The installed service has these behaviors when starting and stopping services using the native Windows tools:

  • start — install node, if not installed, and start the node.

  • stop — stop and quiesce the node.

Application warning and error messages are logged to the Windows event logger.

Removal

Windows services are removed using the epadmin remove systemservice command.

All user data stored in a node is lost when a service is removed. TIBCO recommends replicating any important data to another node to avoid data loss before removing a service.

For example:

remove systemservice --name="my-service"
Configuration Value Description Required?
name Service name. Yes.

Windows Event Logging Appender

Application warning and error messages are logged to the Windows Event Log. To accomplish this, a LogBack appender for Windows is provided, which is configured using the standard Logback configuration mechanisms. See the supported appender configuration values, below:

Configuration Value Description Required?
application Application name for logged events. No. Default value is Application.
class Log appender class name. Must be set to: com.tibco.ep.dtm.logappenders.windowclass seventlogger.WindowsEventLoggerAppender. Yes.
layout LogBack appender layout. See the LogBack layout documentation for more information. Yes.
server Windows Universal Naming Convention (UNC) name of the remote log server. No. Default is local machine's log server
source Event source name. Yes.

This following is an example of a Windows Event Logger appender Logback configuration.

<appender
  name="MY-APPENDER"
  class="com.tibco.ep.dtm.logappenders.windowseventlogger.
    WindowsEventLoggerAppender">
  <source>sample.event.source</source>
  <layout class="ch.qos.logback.classic.PatternLayout">
    <pattern>d{HH:mm:ss.SSS} %thread %-5level %logger: %msg%n</pattern>
  </layout>
</appender>

The LogBack log levels are mapped to the Windows Event Logger event types as shown below:

LogBack Log Level Windows Event Logger Event Type
ERROR 0x1
WARN 0x2
All others 0x4

The Logback log levels are also mapped to the Windows Event Logger category identifiers as shown below:

LogBack Log Level Windows Event Logger Event Type
ERROR 1
WARN 2
INFO 3
DEBUG 4
TRACE 5