- Index

< Previous |  | Next >

# 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>\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