Configuring Apps as a Linux Service

< Previous		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 shut down. StreamBase supports the Linux service management subsystem using systemd.

This page assumes familiarity with systemd concepts and general architecture; sudo access is required to install new services.

The TIBCO-provided systemd unit file is shipped as:

INSTALLROOT/tibco/str/11.1/distrib/tibco/dtm/services/linux/tibco-ep.service

The standard and recommended INSTALLROOT is /opt, which is shown on the rest of this page.

This file defines a service named tibco-ep that can manage 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.

Installation

Install the systemd file as follows. These instructions install the service with the default name and configure a service to manage a single node.

Install into the required systemd directory using the default service name. Run this command in one line, substituting your installation location. The example below wraps to the next line for clarity:
```
sudo cp -p /opt/tibco/str/11.1/distrib/tibco/dtm/services/linux/tibco-ep.service \
   /usr/lib/systemd/system
```
Do not use a symbolic link to install the file; systemd does not fully support symbolic links.
Reload the systemd manager configuration to detect the newly installed service.
```
sudo systemctl daemon-reload
```
Enable the service so that Linux can automatically manage it.
```
sudo systemctl enable tibco-ep
```
Manually start the service.
```
sudo systemctl start tibco-ep
```

Multiple nodes can be installed on the same machine by installing multiple copies of the unit file with different names. Run the following to install another service named my-application on the same machine:

sudo cp /opt/tibco/str/11.1/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 systemd file supports configuration using systemd environment configuration variables. You can change these configuration values directly in the systemd file after it is installed.

Variable	Description	Required?
`JAVA_HOME`	Java installation.	Yes. Default value is `/usr/lib/jvm/java`.
`TIBCO_EP_APPLICATION`	Absolute path to the application archive to install on the node.	No. If not used, the node is installed without an application.
`TIBCO_EP_HOME`	Absolute path to the TIBCO Streaming 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 a node deploy configuration file to configure node during installation.	No. If not used, the node is installed using default configuration.
`TIBCO_EP_RUN_DIRECTORY`	Absolute path to the run directory where nodes are to be installed.	Yes. Default value is `%t/tibco-ep`. See the `systemd` configuration documentation for details regarding `%t`.
`TIBCO_EP_SUBSTITUTION_FILE`	Absolute path to a substitution variable file.	No. If not used, no substitution variables are specified during node install.

In addition to these supported configuration variables, you can specify standard systemd configuration values 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 the node if not installed, then 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:

Creating a snapshot of the failed node.
Removing the node.
Re-installing the node.

Note

For a restart on failure, all user data stored in the failed node is lost. It is the best practice to replicate your data to another node as needed.

Removal

Use these steps to completely remove an installed service. These steps use the default shipped service name, tibco-ep.

Stop the service.
```
sudo systemctl stop tibco-ep
```
Remove the service from management by the operating system.
```
sudo systemctl disable tibco-ep
```

Remove installed systemd file.

sudo rm /usr/lib/systemd/system/tibco-ep.service

Remove any configuration overrides.

sudo rm -rf /etc/systemd/system/tibco-ep.service.d

Reload systemd manager to update its configuration.
```
sudo systemctl daemon-reload
```
Reset all failed messages.
```
sudo systemctl reset-failed 
```