This document describes the procedures necessary to run JOnAS as a system service on Microsoft Windows platforms.
The procedure uses the Java Service Wrapper open source project which must be downloaded and installed separately.
Download Java Service Wrapper version 3.0.5 or later, and unzip the package to a directory in the local filesystem.
Set
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 .
Verify that JAVA_HOME is set as a system environment variable.
Verify that JONAS_BASE and WRAPPER_HOME environment variables are set.
Set %JONAS_ROOT% as the current directory.
Set environment variables required for JOnAS execution (see list below).
Execute
ant [-Djonas.name=<server_name>] create_win32service
.
Note | |
---|---|
The
|
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.
CLASSPATH (*)
JAVA_OPTS
JONAS_OPTS
TOMCAT_OPTS
JETTY_OPTS
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
.
The wrapper configuration must be updated whenever any of these environment variables are modified. Refer to the Section 1.2, “Files Managed by create_win32service” section for more information.
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 Section 1.4, “Testing Configuration” section for more information. The following steps will install the service.
Verify that JONAS_BASE and WRAPPER_HOME environment variables are set.
Set %JONAS_ROOT% as the current directory.
Execute
ant install_win32service
. As an alternative, the service may be installed from a DOS command window using the
jonas ntservice install
command.
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.
Verify that JONAS_BASE and WRAPPER_HOME environment variables are set.
Set %JONAS_ROOT% as the current directory.
Verify that the service has been stopped.
Execute
ant uninstall_win32service
. As an alternative, the service may be uninstalled from a DOS command window using the
jonas ntservice uninstall
command.
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
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.
lib\wrapper.jar
lib\wrapper.dll
conf\wrapper.conf
conf\wrapper_ext.conf
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.
Stop the JOnAS service using the Windows Service Control Manager, or the
jonas ntservice stop
command line.
Make changes to
config_env.bat
, and the
CLASSPATH, JAVA_OPTS, JONAS_OPTS, TOMCAT_OPTS, JETTY_OPTS
environment variables as needed.
Update the Java Service Wrapper configuration. Refer to the Section 1.1.2, “create_win32service” section for details.
Test the updated configuration. Refer to the Section 1.4, “Testing Configuration” section for more information.
Restart the JOnAS service using the Windows Service Control Manager, or the
jonas ntservice start
command line.
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.
Verify that JONAS_BASE environment variable is set.
Execute
jonas ntservice console
.
The Java Service Wrapper will start as a console application and load JOnAS using the configuration generated by the
create_win32service
ant target.
Note | |
---|---|
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.