Execute JOnAS as a WIN32 Service

1.1. Instructions
1.1.1. Download and Install Java Service Wrapper
1.1.2. create_win32service
1.1.3. install_win32service
1.1.4. uninstall_win32service
1.1.5. Start JOnAS Service
1.1.6. Stop JOnAS Service
1.1.7. Status of JOnAS Service
1.2. Files Managed by create_win32service
1.3. Modify JOnAS Configuration
1.3.1. Update Wrapper Configuration
1.4. Testing Configuration

This document describes the procedures necessary to run JOnAS as a system service on Microsoft Windows platforms.

1.1. Instructions

The procedure uses the Java Service Wrapper open source project which must be downloaded and installed separately.

1.1.1. Download and Install Java Service Wrapper

  1. Download Java Service Wrapper version 3.3.6 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.3.6 is unzipped into C:\Programs, then set WRAPPER_HOME=C:\Programs\wrapper-windows-x86-32-3.3.6

1.1.2. 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_ROOT, JONAS_BASE and WRAPPER_HOME environment variables are set.

  3. Set %JONAS_ROOT%\templates\win32 as the current directory.

  4. Set environment variables required for JOnAS execution (see list below).

  5. Execute


                  ant [-Djonas.name=<server_name>] create_win32service
              

    .

[Note] Note

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

1.1.3. 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 Section 1.4, “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%\templates\win32service 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.

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

1.1.5. 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] Note

Any environment variables referenced within either of the wrapper.conf and wrapper_ext.conf files must be defined as system environment variables.

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

1.1.7. Status of JOnAS Service

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

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

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

1.3. Modify JOnAS Configuration

In addition to the files located in the conf directory, JOnAS configuration is affected by the following environment variables, CLASSPATH, JAVA_OPTS, JONAS_OPTS. If changes are made to 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.

1.3.1. 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 environment variables as needed.

  3. Update the Java Service Wrapper configuration. Refer to the Section 1.1.2, “create_win32service” section for details.

  4. Test the updated configuration. Refer to the Section 1.4, “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] 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.

1.4. 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] 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.