Configuring the Java Service Wrapper
The Java Service Wrapper is an application developed by Tanuki Software, Ltd. It is a utility program that allows an application such as a JVM to run as a Windows service or UNIX daemon.
Several components of Universal Messaging run in a Java Service Wrapper. You can configure your Universal Messaging environment by adding or modifying the Java Service Wrapper properties for each of these components.
In addition, the Java Service Wrapper offers features for monitoring the JVM, logging console output, and generating thread dumps. The following sections describe how Universal Messaging components use the features of the Java Service Wrapper.
For an overview of the Java Service Wrapper, see the cross-product document, Software AG Infrastructure Administrator's Guide .
Product Components that Use the Java Service Wrapper
Each of the Universal Messaging components runs in its own dedicated Java Service Wrapper:
- The Universal Messaging realm server, located under <InstallDir>/UniversalMessaging/server/<InstanceName>/bin, where <InstanceName> is the name of the realm server instance. If there are multiple realm servers, each instance runs in its own Java Service Wrapper.
- The Enterprise Manager and the Enterprise Viewer, located under <InstallDir>/UniversalMessaging/java/<InstanceName>/bin
- All Java sample applications, located under <InstallDir>/UniversalMessaging/java/<InstanceName>/bin.
- The server configurator and interface configurator server applications under <InstallDir>/UniversalMessaging/server/<InstanceName>/bin.
The Java Service Wrapper Configuration Files
When you start a Java Service Wrapper, the properties in the configuration files determine the configuration of the Java Service Wrapper and the behavior of the logging and monitoring features. There are typically two configuration files per wrapper. One of the configuration files determines a default set of properties, and the second determines your customized set of properties. A typical arrangement can be as follows:
| File name | Description |
|---|---|
| wrapper.conf | Contains initial property settings. Do not modify the contents of this file unless asked to do so by Software AG. |
| custom_wrapper.conf | Contains properties that modify the installed settings in
wrapper.conf. If you need to modify the property settings for the Java Service Wrapper, then modify this file. The settings in this file override the settings in the wrapper.conf file. |
| Component | Configuration files |
|---|---|
| Command Central | <InstallDir>/profiles/CCE/configuration/wrapper.conf, custom_wrapper.conf |
| Software AG Platform Manager | <InstallDir>/profiles/SPM/configuration/wrapper.conf, custom_wrapper.conf |
| Realm Server <InstanceName> |
<InstallDir>/UniversalMessaging/server/<InstanceName>/bin/nserverdaemon.conf: this file contains the default Tanuki configuration for the Universal Messaging realm server. <InstallDir>/UniversalMessaging/server/<InstanceName>/bin/Server_Common.conf: this file contains common Tanuki configuration settings for the Universal Messaging realm server. Historically the server could be started in different modes and this file would contain common configuration options. <InstallDir>/UniversalMessaging/server/<InstanceName>/bin/Custom_Server_Common.conf: this file should be used to customize the default Tanuki configuration. For information about how to resolve various server issues by modifying the Wrapper configuration, see Troubleshooting. |
| Java sample applications for <InstanceName> |
There is a generic <InstallDir>/UniversalMessaging/java/<InstanceName>/bin/Samples_Common.conf file that provides the common settings for all sample applications. Also, each sample application has its own *.conf file in <InstallDir>/UniversalMessaging/java/<InstanceName>/bin/ |
| Administration Tools (Enterprise Manager or Enterprise Viewer) |
There is a <InstallDir>/UniversalMessaging/java/<InstanceName>/bin/Admin_Tools_Common.conf file that provides common settings for the Enterprise Manager and the Enterprise Viewer tools. Also, <InstallDir>/UniversalMessaging/java/<InstanceName>/bin/nenterprisemgr.conf provides settings for the Enterprise Manager <InstallDir>/UniversalMessaging/java/<InstanceName>/bin/nenterpriseview.conf provides settings for the Enterprise Viewer |
| Server applications |
There is a generic <InstallDir>/UniversalMessaging/server/<InstanceName>/bin/Server_Tools_Common.conf file that provides common settings for all server applications. Also, each application has its own configuration file: <InstallDir>/UniversalMessaging/server/<InstanceName>/bin/nServerConfiguration.conf provides settings for the server configurator application. <InstallDir>/UniversalMessaging/server/<InstanceName>/bin/inconfig.conf provides settings for the interface configurator application. |
The JVM property settings that Universal Messaging installs are suitable for most environments. If the installed settings do not suit your needs, you can modify the properties. For procedures and additional information, see the cross-product document, Software AG Infrastructure Administrator's Guide .
The Wrapper Log
The Java Service Wrapper records console output in a log file. The log file also contains the output that the Universal Messaging component, which is running in the wrapper, sends to the console. The wrapper log is especially useful when you run the component as a Windows service because console output is normally not available to you in this mode.
| Component | Log file |
|---|---|
| Command Central | <InstallDir>/profiles/CCE/logs/wrapper.log |
| Software AG Platform Manager | <InstallDir>/profiles/SPM/logs/wrapper.log |
| Realm Server <InstanceName> | <InstallDir>/UniversalMessaging/server/<InstanceName>/bin/UMRealmService.log |
Logging Properties
The wrapper.console and wrapper.log properties in the wrapper configuration files determine the content, format, and behavior of the wrapper log.
The default logging settings are suitable for most environments. If the installed settings do not suit your needs, you can modify the properties listed in the table. For procedures and additional information, see the cross-product document, Software AG Infrastructure Administrator's Guide .
| Property | Value |
|---|---|
| wrapper.console.loglevel | Level of messages to display in the console. |
| wrapper.console.format | Format of messages in the console. |
| wrapper.logfile | File in which to log messages. |
| wrapper.logfile.loglevel | Level of messages to write in the log file. |
| wrapper.logfile.format | Format of messages in the log file. |
| wrapper.logfile.maxsize |
Maximum size to which the log can grow. |
| wrapper.logfile.maxfiles |
Number of old logs to maintain. |
| wrapper.syslog.loglevel |
Level of messages to write to the Event Log on Windows systems or the syslog on UNIX. |
Fault Monitoring
The Java Service Wrapper can monitor the JVM for certain conditions and then restart the JVM or perform other actions when it detects these conditions.
The following table gives some examples. To learn more about these features, see the cross-product document, Software AG Infrastructure Administrator's Guide .
| Feature | Enabled? | User configurable? |
|---|---|---|
| JVM timeout | Yes | No. Do not modify the wrapper.ping properties unless asked to do so by Software AG. |
| Deadlock detection | No | Yes. For more details see, Deadlock-Detecting Properties. |
| Console filtering | No | Yes. For more information see, Console Filtering Properties. |
JVM Timeout Properties
The wrapper.ping.interval properties in the wrapper configuration files determine whether the wrapper monitors the JVM for timeout and what action it takes when a timeout occurs. The following table gives some examples.
| Property | Value |
|---|---|
| wrapper.ping.interval | How often, in seconds, the Java Service Wrapper pings JVM to ensure that it is active. The default is 5 seconds. |
| wrapper.ping.timeout | Length of time, in seconds that the Wrapper waits for a
response to a ping. Set this property to 60. If the Wrapper does not receive a response in the
specified time, it initiates the action specified in wrapper.ping.timeout.action. |
| wrapper.ping.timeout.action | An action to take if the Wrapper does not receive a
response to a ping in the allotted time. Set this property to DEBUG,DUMP,RESTART. |
Deadlock-Detection Properties
The wrapper.check.deadlock properties in the wrapper configuration files determine whether the wrapper monitors the JVM for deadlocks and what action it takes when a deadlock occurs. The following table gives some examples.
| Property | Value |
|---|---|
| wrapper.check.deadlock | Flag (TRUE or FALSE) that enables or disables deadlock
detection. The default is FALSE. |
| wrapper.check.deadlock.interval | How often, in seconds, the Java Service Wrapper evaluates the JVM for a deadlock condition. The default is 60 seconds. |
| wrapper.check.deadlock.action | Action that occurs if the Java Service Wrapper detects a deadlock condition. |
| wrapper.check.deadlock.output | Information to log when the Wrapper detects a deadlock
condition. Set this property to DEBUG,DUMP,RESTART.
|
Console Filtering Properties
The wrapper.filter properties in the wrapper configuration files determine whether the wrapper monitors the console for specified messages and what action it takes when a specified message occurs. To use console filtering, you can configure the following properties. However, Software AG recommends that you do not modify these properties unless asked to do so. The following table gives some examples.
| Property | Value |
|---|---|
| wrapper.filter.trigger. n |
A string of text that you want to detect in the console output. |
| wrapper.filter.action. n |
Action that occurs when the Java Service Wrapper detects the string of text. |
| wrapper.filter.allow_wildcards. n |
Flag (TRUE or FALSE) that specifies whether the Java Service Wrapper processes wildcard characters that appear in wrapper.filter.trigger. n. |
| wrapper.filter.message. n |
Message that displays when Java Service Wrapper detects the string of text. |
Generating a Thread Dump
The Java Service Wrapper provides a utility for generating a thread dump of the JVM when running as a Windows service. A thread dump can help you locate thread contention issues that can cause thread blocks or deadlocks.
Go to the bin directory
of the wrapper and run the command service -dump.
The Java Service Wrapper writes the
thread dump to the Wrapper log file.
Default Port Handling
The Java Service Wrapper uses a socket to communicate with its Java component running inside a JVM. The configuration of the Wrapper determines the port that is used for this communication.
When the Wrapper starts a JVM instance, the Wrapper opens a server socket that listens on this port and is bound to the localhost address. The JVM instance is supplied with a key that it must use to connect back to the Wrapper process. After the JVM is connected, the wrapper no longer accepts other connections. This process should not raise any security issues.
The default range for this port is 32000 to 32999. You can
change the range by using the wrapper.port.min and
wrapper.port.max properties in the Server_Common.conf file. If you specify a range,
be sure to provide a large enough range to make it unlikely that all ports are in use when the
Wrapper attempts to start.