Configuring openNMS as Windows Service

From OpenNMS
Jump to: navigation, search

Windows OS might not be the first choice for the people associated with open source projects. But due to organizational constraints, you might end up with windows machine for running openNMS. This article discusses the steps for configuring openNMS as a windows service.

Wrapper is an open source java application that can wrap around any other java application. We will be using it for invoking Jetty (the default servlet container for openNMS on Windows platform).

Downloading Wrapper

Download the java service wrapper from http://wrapper.tanukisoftware.org/doc/english/download.jsp
At the time of this writing, I downloaded version 3.3.3 for windows (x86) platform. Unzip the the Wrapper zip file into a directory on the target machine. Lets call that folder as {WRAPPER_HOME}.

Configuration

There are four files which are required to be able to use the Wrapper. We will also copy over three additional batch files which can be used to launch openNMS as well as install and uninstall it as an NT Service.

bin directory

First we will copy the following files into the openNMS bin directory:

{WRAPPER_HOME}\bin\wrapper.exe
{WRAPPER_HOME}\src\bin\App.bat.in
{WRAPPER_HOME}\src\bin\InstallApp-NT.bat.in
{WRAPPER_HOME}\src\bin\UninstallApp-NT.bat.in

Rename the three batch files as follows. Be sure to remove the .in extensions so that the files all end in .bat. Depending on how your file explorer is configured, you may not be able to see the extensions.

{openNMS_HOME}\bin\openNMSWrapper.bat
{openNMS_HOME}\bin\InstallOpenNMS-NT.bat
{openNMS_HOME}\bin\UninstallOpenNMS-NT.bat

The wrapper.exe file is the actual Wrapper executable. The three batch files are used to run openNMS in a console, and to install and remove it as an NT Service. These scripts should not require any modification. They do assume that the wrapper.conf file will be located within a conf directory one level up, ../conf/wrapper.conf. If you wish to locate this file someplace else, then the three batch files will require that small modification.

lib directory

Copy the following two files into the openNMS lib directory:
{WRAPPER_HOME}\lib\wrapper.dll
{WRAPPER_HOME}\lib\wrapper.jar
The wrapper.dll file is a native library required by the portion of the Wrapper which runs within the JVM. The wrapper.jar file contains all of the Wrapper classes.

conf directory

The Wrapper requires a configuration file. The standard location for this file is in a conf directory in the application's home directory. openNMS does not have such a directory by default, so we will need to create one. Please do so and copy the template wrapper.conf file to that location:
{WRAPPER_HOME}\src\conf\wrapper.conf.in
Be sure to remove the .in extension so that the file is named wrapper.conf. Depending on how your file explorer is configured, you may not be able to see the extension. You should now have:
{openNMS_HOME}\conf\wrapper.conf
If you wish to relocate the configuration file, you are free to do so. You will need to modify the batch scripts copied into the bin directory above, to reflect the new location.

logs directory

The default wrapper.conf file will place a wrapper.log file in a logs directory under the application home directory. openNMS does has such a directory by default, so we will need to create one. Please do so. You should now have the following directory:
{openNMS_HOME}\logs
If you wish to place the log file in another location, you will need to edit the wrapper.conf file and modify the wrapper.logfile property to reflect the new location.


Locate the Application's Java Command Line

Before the Wrapper can be configured to launch an Application, you will need to know the full Java command which is normally used. Most applications make use of a batch file to build up the actual command line. These batch files tend to get quite unwieldy and in fact, the ability to avoid having to work with them is one of the benefits of working with the Wrapper. opemNMS is launched by using a batch file called opennms.bat. It is launched by first changing the current directory to the bin directory and then run from there. If you open opennms.bat into an editor, you will notice the following line towards the end of the file:
"C:\Program Files\Java\jdk1.6.0_11\bin\java" -Xmx256m -Dopennms.home="C:/PROGRA~1/OpenNMS" -jar "C:/PROGRA~1/OpenNMS/lib/opennms_bootstrap.jar" %1 %2 %3 %4 %5 %6 %7 %8 %9


Modifying the wrapper.conf File

In order to be able to use this command with the Wrapper, we need to break up its components. Open the wrapper.conf file into an editor and make the changes below.

Java Executable
First is to extract the java executable and assign it to the wrapper.java.command property:
wrapper.java.command= C:\Program Files\Java\jdk1.6.0_11\bin\java

Java Arguments
Most applications provide a number of parameters to the Java executable when it is launched. The Wrapper provides special properties for configuring things like memory, as well as class and library paths. These will be covered below, however any other settings are configured using the wrapper.java.additional.<n> series of properties. The openNMS command line only has one such property. In this case, we have changed the name of the script used to launch JBoss from run.bat, but for consistency we will leave it as is.:
wrapper.java.additional.1=-Xmx512m
wrapper.java.additional.2=-Dopennms.home="C:/PROGRA~1/OpenNMS"
Notice that the full property was copied directly from the command line without any modifications except for the increase in memory size.

Classpath
Next, comes the classpath, which is configured using the wrapper.java.classpath.<n> properties. The Wrapper requires that the classpath be broken up into its individual elements. Then, because we will also be making use of the Wrapper, it is necessary to include the wrapper.jar file as well:

wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=../lib/opennms_bootstrap.jar

Main Class
The final component of the command used to launch openNMS is the main class, org.jboss.Main. The main class executed by Java when launched is specified by using the wrapper.java.mainclass property. As mentioned above however. Because the JBoss main class does not know how to communicate with the Wrapper, we will set the main class to be the full class name of WrapperSimpleApp. The opennms main class is then specified as the first application parameter below.

wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp


Application Parameters
Application parameters are set using the wrapper.app-parameter.<n> properties. Application parameters appear in the Java command line directly after the main class. While JBoss does not have any such parameters, it is still necessary to set one of these properties. This is because we are using the WrapperSimpleApp helper class and as described above, its first parameter is the main class name of the application being run. in this case, org.jboss.Main:

wrapper.app.parameter.1= org.opennms.bootstrap.Bootstrap
wrapper.app.parameter.2= start


Library Path
In order to use the Wrapper, there is one more property which much be set. The Wrapper makes use of a native library to control interactions with the system. This file wrapper.dll needs to be specified on the library path supplied to the JVM. JBoss does not have any native libraries of its own, but if it did, the directories where they were located would also need to be specified. The library path is set using the wrapper.java-library-path.<n> properties.

wrapper.java.library.path.1=../lib


Putting It All Together

Please Note the directory structure dependency and modify it accordingly fo your platform. By taking advantage of the fact that the Wrapper always sets the working directory to the location of the wrapper.exe file and by making use of a single environment variable, we are able to modify the above properties so that they are completely platform and machine independent:

wrapper.java.command=%JAVA_HOME%/bin/java
wrapper.java.additional.1=-Dprogram.name=run.bat
wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=%JAVA_HOME%/lib/tools.jar
wrapper.java.classpath.3=./run.jar
wrapper.java.library.path.1=../lib
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp
wrapper.app.parameter.1= org.opennms.bootstrap.Bootstrap
wrapper.app.parameter.2= start

Wrapper NT/2000/XP Service Properties
The final step is to set the Windows specific NT/2000/XP Service Properties properties. We will just set the properties which should be changed. But there are several others available. See the documentation for details on their usage. Note that the default values of both of these variables are Ant friendly tokens which can easily be replaced as part of a build.

wrapper.ntservice.name=openNMS
wrapper.ntservice.displayname=openNMS Server
wrapper.ntservice.description= openNMS-The opensource NMS

Trying It Out

openNMS can now be run by simply executing the bin\openNMSWrapper.bat script. Because of the way the Wrapper sets its current directory, it is not necessary to run this script from within the bin directory. Please try running the application once as a console application to verify the configuration before attempting to run it as a service.

Service Installation

Upon performing a satisfactory sanity test that openNMS is working properly in the command prompt. Run the following command.
{openNMS_HOME}\bin\InstallOpenNMS-NT.bat
If you navigate to control panel->Administrative Tools -> Services, you will see a new service with the name 'openNMS' is available now. The openNMS can be controlled now automatically or manually like any other windows service.