Configuring Windows as a Service

< Previous		Next >

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>\Cloud Software Group, 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