Platform specific details

Platform specific details
Prev	Chapter 8. Reference	Next

Operating system service management

Operating systems have service management subsystems that support starting and stopping services when the host operating system is booted and shutdown. These subsystems are operating system family specific, i.e. Linux, macOS, Windows. Currently system service management is only supported on Linux and Windows.

Linux systemd support

The systemd service management subsystem is used on Linux. This section assumes familiarity with systemd concepts and general architecture. sudo access is also required to install new services.

A systemd unit file is shipped in <product-installation-location>/distrib/tibco/dtm/services/linux/tibco-ep.service. This unit file defines a service named tibco-ep that manages a single node. Multiple nodes can be started on a single machine by installing multiple copies of the shipped unit file, each with a different name (see the section called “Installation”).

Installation

These steps are required to install the shipped unit file.

sudo cp <product-installation-location>/distrib/tibco/dtm/services/linux/tibco-ep.service /usr/lib/systemd/system - install the unit file into the required systemd directory using the default service name.
Do not use a symbolic link to install the unit file - symbolic links are not fully supported by systemd.
sudo systemctl daemon-reload - reload systemd manager configuration to detect newly installed service.
sudo systemctl enable tibco-ep - enable the service to be automatically managed by operating system.
sudo systemctl start tibco-ep - manually start the service.

These instructions install the service with the default name. This will configure a service to manage a single node. Multiple nodes can be installed on the same machine by installing multiple copies of the unit file with different names. For example, this will install another service named my-application on the same machine:

sudo cp <product-installation-location>/distrib/tibco/dtm/services/linux/tibco-ep.service /usr/lib/systemd/system/my-application.service
sudo systemctl daemon-reload
sudo systemctl enable my-application
sudo systemctl start my-application

Configuration

The shipped unit file supports configuration using the systemd Environment configuration variable. See Table 8.131, “Unit file configuration variables” for the supported configuration variables. These configuration values can be changed directly in the unit file after it has been installed.

Table 8.131. Unit file configuration variables

Variable	Description	Required?
`JAVA_HOME`	Java installation.	Yes. Default value is `/usr/lib/jvm/java`.
`TIBCO_EP_APPLICATION`	Absolute path to application archive to install on node.	No. Node will be installed without an application.
`TIBCO_EP_HOME`	Absolute path to product installation.	Yes. Default value is `/opt/tibco-ep`.
`TIBCO_EP_NODE`	Node name.	Yes. Default value is `A.tibco-ep`.
`TIBCO_EP_NODE_DEPLOY`	Absolute path to node deploy configuration to configure node during installation.	No. Node will be installed using default configuration.
`TIBCO_EP_RUN_DIRECTORY`	Absolute path to the run directory where nodes will be installed.	Yes. Default value is `%t/tibco-ep`. See the systemd unit configuration documentation for details on `%t`.
`TIBCO_EP_SUBSTITUTION_FILE`	Absolute path to substitution variable file.	No. No substitution variables will be specified during node install.

In addition to these supported configuration variables, standard systemd configuration values can be specified in unit file overrides using systemctl edit. See the systemd documentation for complete details on the unit file supported configuration variables.

Operational Behavior

The shipped unit file has these behaviors for managing services using systemctl:

start - install node, if not installed, and start the node.
stop - stop and quiesce the node.
reload - not supported. Use standard node configuration mechanisms to change node configuration.

The Restart=on-failure configuration is enabled. When a node fails, it is automatically restarted after taking these actions:

Create a snapshot of the failed node.
Remove the node.
Re-install the node.


	All user data stored in a failed node is lost. Any precious user data must be replicated to another node to avoid loss.

Removal

These steps are required to completely remove an installed service. These steps are using the default shipped service name of tibco-ep.

sudo systemctl stop tibco-ep - stop the service.
sudo systemctl disable tibco-ep - remove the service from management by the operating system.
sudo rm /usr/lib/systemd/system/tibco-ep.service - remove installed unit file.
sudo rm -rf /etc/systemd/system/tibco-ep.service.d - remove any configuration overrides.
sudo systemctl daemon-reload - reload systemd manager to update its configuration.
sudo systemctl reset-failed - reset all failed messages.

Windows service support

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 are installed as Windows services are installed using the epadmin install systemservice command. See the section called “systemservice target” for details. The account in which the service should run is specified when installing the service. This account must have the JAVA_HOME environment variable set.

Service start-up parameters

The start-up parameters for a service are stored in the Windows registry using this key when the service is installed:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\TIBCO Software Inc.\Settings\sb-cep\<service-name>\<service-name>Startup
- service-name is service name specified when the application was installed as a service.

These parameters can be changed directly in the registry before a service is started.

Table 8.132. Registry start-up parameter variables

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. See the section called “systemservice target” for details.


	All user data stored in a node is lost when a service is removed. Any precious user data must be replicated to another node to avoid data loss before removing a service.

Windows event logging appender

A LogBack appender for Windows is provided. This appender is configured using the standard Logback configuration mechanisms. The supported appender configuration values are in Table 8.133, “Event logging appender configuration”.

Table 8.133. Event logging appender configuration

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.windowseventlogger.WindowsEventLoggerAppender`.	Yes.
`layout`	LogBack appender layout. See LogBack layout documentation.	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 is an example 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 in Table 8.134, “Windows event logger event type mapping”.

Table 8.134. Windows event logger event type mapping

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 in Table 8.135, “Windows event logger category mapping”.

Table 8.135. Windows event logger category mapping

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

Shared memory allocation on macOS

The starting virtual address of allocated shared memory on macOS is managed by a global file located in /var/tmp/osx.memory. This file is created as needed, and accessed, whenever a node is installed. Modifying this file could result in corrupting data stored in shared memory.

Shared memory on Windows

Only memory mapped file shared memory is supported on Windows. There is no support for System V shared memory.

Prev	Up	Next
Default logging configuration	Home	Diagnosing service discovery networking problems


	Do not use a symbolic link to install the unit file - symbolic links are not fully supported by `systemd`.