This document describes the procedures necessary to run JOnAS as a system service on Microsoft Windows platforms. This applies starting from JOnAS 3.3.2.
This procedure uses ANT targets that are introduced in JOnAS 3.3.2. The procedure also uses the Java Service Wrapper open source project which must be downloaded and installed separately.
WRAPPER_HOME environment variable to the root
directory for Java Service Wrapper.
For example, if the package for Wrapper version 3.0.5 is unzipped into c:\jsw, then SET WRAPPER_HOME=c:\jsw\wrapper_win32_3.0.5
Before JOnAS can be run as a WIN32 service, it is necessary to create a Java Service Wrapper configuration file. Prior to executing the steps in this section, it is necessary to create a JONAS_BASE directory as described in the JOnAS Configuration Guide.
The -Djonas.name=<server_name> parameter is optional. If not specified, the default server name is 'jonas'.
Prior to executing create_win32service it is necessary to set environment variables as required for JOnAS execution. The values of the environment variables are saved in the wrapper_ext.conf file as wrapper properties.
* The config_env.bat file is used to configure JDBC drivers in the CLASSPATH. Any changes to config_env.bat will affect the CLASSPATH environment variable, and therefore requires that the wrapper configuration be updated by running create_win32service.
After the %JONAS_BASE% directory has been updated for use with Java Service Wrapper, JOnAS can be installed as a WIN32 service using the install_win32service ant target. Prior to installing the configuration as a WIN32 service, the configuration can be tested as a standard console application. Refer to the Testing configuration section for more information. The following steps will install the service.
By default, the service is configured to start automatically each time Windows starts. If the administrator would prefer to start the service manually, modify the wrapper.ntservice.starttype parameter in the %JONAS_BASE%\conf\wrapper.conf file. Set the value as described in the comments found in the wrapper.conf file.
When it is no longer desirable to run JOnAS as a Windows service, the service can be uninstalled using the uninstall_win32service ant target.
To start the JOnAS service, open the Service Control Manager (Control Panel Services) window, select the JOnAS service and start the service. As an alternative, the service may be started from a DOS command window using the jonas ntservice start command.
By default, JOnAS will be started automatically each time Windows is started. After installing the service, it can be started manually to avoid the need to reboot Windows.
NOTE: Any environment variables referenced within either of the wrapper.conf and wrapper_ext.conf files must be defined as system environment variables.
To stop the JOnAS service, open the Service Control Manager window, select the JOnAS service and stop the service. As an alternative, the service may be stopped from a DOS command window using the jonas ntservice stop command.
The status of the JOnAS service may be obtained from a DOS command window using the jonas ntservice status command.
The create_win32service ant target copies files from the Java Service Wrapper installation directory and generates a configuration file in the %JONAS_BASE% directory. The following files are managed by the create_win32service ant target.
* wrapper.conf contains Java Service Wrapper configuration properties. This file is copied to the conf directory by the CREATE_JONASBASE command. Changes made to this file are not affected by subsequent execution of the create_win32service target.
** wrapper_ext.conf contains Java Service Wrapper configuration properties specific to the JOnAS service. This file is generated by the create_win32service ant target. Any changes made to this file will be lost when the create_win32service target is executed.
In addition to the files located in the conf directory, JOnAS configuration is affected by the contents of %JONAS_ROOT%\bin\nt\config_env.bat, and by the following environment variables, CLASSPATH, JAVA_OPTS, JONAS_OPTS, TOMCAT_OPTS, JETTY_OPTS. If changes are made to config_env.bat, or any of these environment variables, it is necessary to update the Java Service Wrapper configuration files.
JOnAS memory usage is controlled by the -Xms and -Xms JVM arguments. Prior to running create_win32service, set the JAVA_OPTS environment variable with the desired values for -Xms and -Xmx. The create_win32service target will generate these values as wrapper.java.additional parameters in the wrapper_ext.conf file.
jonas ntservice stop command line.config_env.bat, and the
CLASSPATH, JAVA_OPTS, JONAS_OPTS, TOMCAT_OPTS, JETTY_OPTS
environment variables as needed.
Note: Changes to the JOnAS configuration files located in the %JONAS_BASE%\conf directory do not affect the contents of the wrapper_ext.conf file. When making changes to the files located in the conf directroy, it is only necessary to stop the service and restart the service for the changes to take effect.
After the Java Service Wrapper configuration files have been generated, it is possible to test the configuration in a console window before installing the configuration as a WIN32 service.
The Java Service Wrapper will start as a console application and load JOnAS using the configuration generated by the create_win32service ant target.
Note that this test procedure is using environment variables that are set for the current user. Verify that any environment variables used in the wrapper.conf and/or wrapper_ext.conf files are also set as system environment variables.
Enter CTRL-C to terminate JOnAS. After pressing Ctrl-C, the Java Service Wrapper displays the following messages to the execution report, and/or log file.
wrapper | CTRL-C trapped. Shutting down.
jvm 1 | 2003-12-02 15:25:20,578 : AbsJWebContainerServiceImpl.unRegisterWar
: War /G:/w32svc/webapps/autoload/ctxroot.war no longer available
jvm 1 | Stopping service Tomcat-JOnAS.
wrapper | JVM exited unexpectedly while stopping the application.
wrapper | <-- Wrapper Stopped.