Howto: Execute JOnAS as a WIN32 Service

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.

Instructions

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.

Download and Install Java Service Wrapper

  1. Download Java Service Wrapper version 3.0.5 or later, and unzip the package to a directory in the local filesystem.
  2. 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

create_win32service

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.

  1. Verify that JAVA_HOME is set as a system environment variable.
  2. Verify that JONAS_BASE and WRAPPER_HOME environment variables are set.
  3. Set %JONAS_ROOT% as the current directory.
  4. Set environment variables required for JOnAS execution (see list below).
  5. Execute ant [-Djonas.name=<server_name>] create_win32service.

The -Djonas.name=<server_name> parameter is optional. If not specified, the default server name is 'jonas'.

Environment Variables

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.

The wrapper configuration must be updated whenever any of these environment variables are modified. Refer to the Modify JOnAS Configuration section for more information.

install_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.

  1. Verify that JONAS_BASE and WRAPPER_HOME environment variables are set.
  2. Set %JONAS_ROOT% as the current directory.
  3. 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.

uninstall_win32service

When it is no longer desirable to run JOnAS as a Windows service, the service can be uninstalled using the uninstall_win32service ant target.

  1. Verify that JONAS_BASE and WRAPPER_HOME environment variables are set.
  2. Set %JONAS_ROOT% as the current directory.
  3. Verify that the service has been stopped.
  4. Execute ant uninstall_win32service. As an alternative, the service may be uninstalled from a DOS command window using the jonas ntservice uninstall command.

Start JOnAS Service

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.

Stop JOnAS Service

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.

Status of JOnAS Service

The status of the JOnAS service may be obtained from a DOS command window using the jonas ntservice status command.

Files Managed by create_win32service

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.

Modify JOnAS Configuration

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.

Update Wrapper Configuration

  1. Stop the JOnAS service using the Windows Service Control Manager, or the jonas ntservice stop command line.
  2. Make changes to config_env.bat, and the CLASSPATH, JAVA_OPTS, JONAS_OPTS, TOMCAT_OPTS, JETTY_OPTS environment variables as needed.
  3. Update the Java Service Wrapper configuration. Refer to the create_win32service section for details.
  4. Test the updated configuration. Refer to the Testing configuration section for more information.
  5. 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.

Testing Configuration

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.

  1. Verify that JONAS_BASE environment variable is set.
  2. 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 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.