Universal Messaging 10.7 | Administration Guide | Configuring the Java Service Wrapper
 
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 following 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 of the Java sample applications, located under <InstallDir>/UniversalMessaging/java/<InstanceName>/bin.
*The certificate generator, 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, properties in configuration files determine the configuration of the Java Service Wrapper and the behavior of the logging and monitoring features. There is typically one configuration file per wrapper that determines a default set of properties, and a second configuration file per wrapper that 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 settings in the wrapper.conf file.
Note:
The filenames wrapper.conf and custom_wrapper.conf shown here are just examples, and can be different for any given wrapper. See the following table for details.
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 is 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.
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.
Additionally, each sample application has its own *.conf file in <InstallDir>/UniversalMessaging/java/<InstanceName>/bin/
Administration Tools ( Enterprise Manager / 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.
Additionally, <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.
Additionally each application has its own configuration file:
<InstallDir>/UniversalMessaging/server/<InstanceName>/bin/CertificateGenerator.conf provides settings for the certificate generator application.
<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. However, you can modify the properties if the installed settings do not suit your needs. 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 contains the output sent to the console by the wrapper itself and by the Universal Messaging component running in the wrapper. 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. However, you can modify the following properties if the installed settings do not suit your needs. 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 the 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 details 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
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
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 execute 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 port used for this communication is determined by the configuration of the Wrapper itself.
When the Wrapper launches 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 additional connections. The way this is done 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 of the ports will be in use when the Wrapper attempts to start.