Running JBoss7 in service mode using Java Service Wrapper

Introduction

Have you ever needed to run your JBoss application server unattended on a Windows machine? There are various ways to accomplish this task. By far, the best alternative is to run the JBoss instance as a Windows service. One of the easiest tools I’ve found for running  java-based applications as services is the Java Service Wrapper project from Tanukisoftware.org. According to their website, the Java Service Wrapper is an application which has evolved out of a desire to solve a number of problems common to many Java applications:

  • Run as a Windows Service or Unix Daemon
  • Application Reliability
  • Standard, Out of the Box Scripting
  • On Demand Restarts
  • Flexible Configuration
  • Ease Application Installations
  • Logging

Because it is Java-based and written completely in Java, the Java service wrapper is the perfect candidate for service/daemon enablement of the JBoss server runtime.

Getting Ready

This post specifically deals with the process of confguring JBoss 7 application server as a windows service. You will need to download the following pieces of software before proceeding:

  • JBoss Application Server 7 (download here ) or if you are on the bleeding edge, download the nightly development build from here
  • Java Platform 32-bit standard edition 6+  ( download here )
  • Tanuki Java Service Wrapper 32-bit community edition 3.5.6+ ( download here )
We need the community edition of the java service wrapper (JSW) because the standard and professional editions require purchase of a license. Furthermore, the 64-bit JSW is not available in the community edition. In addition, the 32-bit JSW native library only works with a 32-bit Java Virtual Machine (JVM). So this is why the requirements above are as they are.

Folder Structure

First, you need to create a parent folder which will contain jboss7, the jre and a folder containing the wrapper service files, as depicted in the diagram below:

Folder structure within the Jboss7jvm32 folder

As you can see, in there, I’ve got 2 different jboss7 distributions, versions 6 and 7 of the jre in case I would like to switch between either of them and a folder called service. With this structure, things are kept clean and separated. If we choose to upgrade the java service wrapper version, we only need to update files in the service folder. If a new version of jboss gets released, we just edit the service configuration to point to the new distribution.

Service Configuration

Now its time to integrate the java service wrapper into our setup. There are four directories that need to be present inside the service folder:

  • bin
  • lib
  • conf
  • logs

Let us call this service folder {SERVICE_HOME}

Unzip the Java service wrapper distribution you downloaded earlier somewhere on your computer. Let us call the directory containing the unzipped distribution {WRAPPER_HOME}.

Copy the following files into service’s bin folder.

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

Rename the three batch files, substituting App with your applications name, for example. Be sure to remove the .in extensions so that the files all end in .bat.
(Depending on how your file explorer is configured on your computer, you may not be able to see file extensions.)
You should now have:

1 {SERVICE_HOME}\bin\wrapper.exe
2 {SERVICE_HOME}\bin\JBoss7_standalone_ha_start.bat
3 {SERVICE_HOME}\bin\JBoss7_standalone_ha_install-NT.bat
4 {SERVICE_HOME}\bin\JBoss7_standalone_ha_remove-NT.bat

The wrapper.exe is the actual wrapper executable. JBoss7_standalone_ha_start.bat is used to run jboss7 in the console, and it’s Install and Uninstall counterparts are used to install and uninstall the windows service for jboss7  respectively. Notice that these three bat files are named to reflect the mode we choose to run jboss in. To remind ourserlves, the default jboss7 distribution can be run in 4 different modes.

  • standalone
  • standalone-ha (standalone mode with clustering)
  • domain
  • domain-ha (domain mode with clustering)

Create a new set of the 3 bat files for each mode you choose to support. One to start jboss7, one to install jboss7 as a service and another to stop the service in the respective mode as listed above.

Then copy the following files into service’s lib folder.

1 {WRAPPER_HOME}\lib\wrapper.jar
2 {WRAPPER_HOME}\lib\wrapper.dll

The wrapper.dll file is a native library file required by the portion of the Wrapper which runs within the JVM. The wrapper.jar file contains all of the Wrapper classes.
You should now have.

1 {SERVICE_HOME}\lib\wrapper.jar
2 {SERVICE_HOME}\lib\wrapper.dll

Now copy the following template for a wrapper.conf file into service’s conf folder

1 {WRAPPER_HOME}\src\conf\wrapper.conf.in

now you should have

1 {SERVICE_HOME}\conf\wrapper_standalone_ha.conf

The wrapper_standalone_ha.conf naming easily helps us identify that this configuration file will be used to enable jboss7 as a service in standalone clustering mode. Create corresponding wrapper.conf files for the various jboss7 startup modes that you wish to support e.g. wrapper_domain_ha.conf. Since we are creating various conf files to correspond with the jboss7 startup modes we wish to support, we also need to edit the corresponding bat files created above, to point to the respective wrapper conf file.

Open the corresponding bat files and edit the set_WRAPPER_CONF_DEFAULT default property to point to the required wrapper config file. So for JBoss7_standalone_ha_start.bat, JBoss7_standalone_ha_install-NT.bat and JBoss7_standalone_ha_remove-NT.bat I have changed that property to:

set _WRAPPER_CONF_DEFAULT=../conf/wrapper_standalone_ha.conf

Create a logs directory inside the service directory so you now have

1 {SERVICE_HOME}\logs

Now it is time to modify your wrapper.conf to tell the java service wrapper how it is supposed to run jboss7  as a service.  I have mine below (wrapper_standalone_ha.conf). Notice how the JAVA_HOME, JBOSS_HOME AND SERVICE_HOME variables are set to the locations of the desired java, jboss and service folders, allowing easy switching or upgrading of the corresponding component binaries. We only need to edit the wrapper configuration file and set a new JAVA_HOME if we choose to change the JVM, set a new JBOSS_HOME if we wish to upgrade our server to a new version and set a new SERVICE_HOME if we choose to upgrade the java service wrapper version or even just if we decide to change the name of the service folder (default is called service) or its location.

Putting it all together

encoding=UTF-8
# Configuration files must begin with a line specifying the encoding
# of the the file.

#********************************************************************
# Wrapper License Properties (Ignored by Community Edition)
#********************************************************************
# Professional and Standard Editions of the Wrapper require a valid
# License Key to start. Licenses can be purchased or a trial license
# requested on the following pages:
# http://wrapper.tanukisoftware.com/purchase
# http://wrapper.tanukisoftware.com/trial

# Include file problems can be debugged by removing the first '#'
# from the following line:
##include.debug

# The Wrapper will look for either of the following optional files for a
# valid License Key. License Key properties can optionally be included
# directly in this configuration file.
#include ../conf/wrapper-license.conf
#include ../conf/wrapper-license-%WRAPPER_HOST_NAME%.conf

# The following property will output information about which License Key(s)
# are being found, and can aid in resolving any licensing problems.
#wrapper.license.debug=TRUE

#********************************************************************
# Wrapper Localization
#********************************************************************
# Specify the locale which the Wrapper should use. By default the system
# locale is used.
#wrapper.lang=en_US # en_US or ja_JP

# Specify the location of the Wrapper's language resources. If these are
# missing, the Wrapper will default to the en_US locale.
wrapper.lang.folder=../lang

#********************************************************************
# Wrapper Java Properties
#********************************************************************
# Java Application
# Locate the java binary on the system PATH:
wrapper.java.command=java
# Specify a specific java binary:
set.JBOSS_HOME=..\..\jboss-as-7.2.0.Alpha1-SNAPSHOT
set.JAVA_HOME=..\..\jre7
set.SERVICE_HOME=..\..\service
wrapper.java.command=%JAVA_HOME%\bin\java

# Tell the Wrapper to log the full generated Java command line.
wrapper.java.command.loglevel=ERROR

# Java Main class. This class must implement the WrapperListener interface
# or guarantee that the WrapperManager class is initialized. Helper
# classes are provided to do this for you. See the Integration section
# of the documentation for details.
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperJarApp

# Java Classpath (include wrapper.jar) Add class path elements as
# needed starting from 1
wrapper.java.classpath.1=%SERVICE_HOME%\lib\wrapper.jar
wrapper.java.classpath.2=%JBOSS_HOME%\jboss-modules.jar

# Java Library Path (location of Wrapper.DLL or libwrapper.so)
wrapper.java.library.path.1=%SERVICE_HOME%\lib

# Java Bits. On applicable platforms, tells the JVM to run in 32 or 64-bit mode.
wrapper.java.additional.auto_bits=TRUE

# Java Additional Parameters
wrapper.java.additional.1=-XX:+TieredCompilation
wrapper.java.additional.2=-XX:MaxPermSize=512m
wrapper.java.additional.3=-Dprogram.name=standalone.bat
wrapper.java.additional.4=-Dorg.jboss.resolver.warning=true
wrapper.java.additional.5=-Dsun.rmi.dgc.client.gcInterval=3600000
wrapper.java.additional.6=-Dsun.rmi.dgc.server.gcInterval=3600000
wrapper.java.additional.7=-Djboss.modules.system.pkgs=org.jboss.byteman
wrapper.java.additional.8=-Djava.net.preferIPv4Stack=true
wrapper.java.additional.9=-Dorg.tanukisoftware.wrapper.WrapperManager.mbean=false
wrapper.java.additional.10=-Djboss.server.default.config=standalone-ha.xml
wrapper.java.additional.11=-Dlogging.configuration=file:%JBOSS_HOME%/standalone/configuration/logging.properties
wrapper.java.additional.12=-Dorg.jboss.boot.log.file=%JBOSS_HOME%/standalone/log/boot.log
wrapper.java.additional.13=-Djava.util.logging.manager=org.jboss.logmanager.LogManager
wrapper.java.additional.14=-Dorg.jboss.logging.Logger.pluginClass=org.jboss.logging.logmanager.LoggerPluginImpl

# Initial Java Heap Size (in MB)
#wrapper.java.initmemory=512

# Maximum Java Heap Size (in MB)
#wrapper.java.maxmemory=2048

# Application parameters. Add parameters as needed starting from 1
wrapper.app.parameter.1=%JBOSS_HOME%/jboss-modules.jar
wrapper.app.parameter.2=-mp
wrapper.app.parameter.3=%JBOSS_HOME%/modules
wrapper.app.parameter.4=-jaxpmodule
wrapper.app.parameter.5=javax.xml.jaxp-provider
wrapper.app.parameter.6=org.jboss.as.standalone
wrapper.app.parameter.7=-Djboss.home.dir=%JBOSS_HOME%

#********************************************************************
# Wrapper Logging Properties
#********************************************************************
# Enables Debug output from the Wrapper.
# wrapper.debug=TRUE

# Format of output for the console. (See docs for formats)
wrapper.console.format=PM

# Log Level for console output. (See docs for log levels)
wrapper.console.loglevel=INFO

# Log file to use for wrapper output logging.
wrapper.logfile=%SERVICE_HOME%\logs\wrapper_standalone_ha.log

# Format of output for the log file. (See docs for formats)
wrapper.logfile.format=LPTM

# Log Level for log file output. (See docs for log levels)
wrapper.logfile.loglevel=ERROR

# Maximum size that the log file will be allowed to grow to before
# the log is rolled. Size is specified in bytes. The default value
# of 0, disables log rolling. May abbreviate with the 'k' (kb) or
# 'm' (mb) suffix. For example: 10m = 10 megabytes.
wrapper.logfile.maxsize=0

# Maximum number of rolled log files which will be allowed before old
# files are deleted. The default value of 0 implies no limit.
wrapper.logfile.maxfiles=0

# Log Level for sys/event log output. (See docs for log levels)
wrapper.syslog.loglevel=NONE

#********************************************************************
# Wrapper General Properties
#********************************************************************
# Allow for the use of non-contiguous numbered properties
wrapper.ignore_sequence_gaps=TRUE

# Do not start if the pid file already exists.
wrapper.pidfile.strict=TRUE

# Title to use when running as a console
wrapper.console.title=JBoss Application Server 7.2.0.Alpha1 (standalone config, clustered mode)

#********************************************************************
# Wrapper JVM Checks
#********************************************************************
# Detect DeadLocked Threads in the JVM. (Requires Standard Edition)
wrapper.check.deadlock=TRUE
wrapper.check.deadlock.interval=10
wrapper.check.deadlock.action=RESTART
wrapper.check.deadlock.output=FULL

# Out Of Memory detection.
# (Ignore output from dumping the configuration to the console. This is only needed by the TestWrapper sample application.)
wrapper.filter.trigger.999=wrapper.filter.trigger.*java.lang.OutOfMemoryError
wrapper.filter.allow_wildcards.999=TRUE
wrapper.filter.action.999=NONE
# (Simple match)
wrapper.filter.trigger.1000=java.lang.OutOfMemoryError
# (Only match text in stack traces if -XX:+PrintClassHistogram is being used.)
#wrapper.filter.trigger.1000=Exception in thread "*" java.lang.OutOfMemoryError
#wrapper.filter.allow_wildcards.1000=TRUE
wrapper.filter.action.1000=RESTART
wrapper.filter.message.1000=The JVM has run out of memory.

#********************************************************************
# Wrapper Email Notifications. (Requires Professional Edition)
#********************************************************************
# Common Event Email settings.
#wrapper.event.default.email.debug=TRUE
#wrapper.event.default.email.smtp.host=<SMTP_Host>
#wrapper.event.default.email.smtp.port=25
#wrapper.event.default.email.subject=[%WRAPPER_HOSTNAME%:%WRAPPER_NAME%:%WRAPPER_EVENT_NAME%] Event Notification
#wrapper.event.default.email.sender=
#wrapper.event.default.email.recipient=

# Configure the log attached to event emails.
#wrapper.event.default.email.attach_log=TRUE
#wrapper.event.default.email.maillog.lines=50
#wrapper.event.default.email.maillog.format=LPTM
#wrapper.event.default.email.maillog.loglevel=INFO

# Enable specific event emails.
#wrapper.event.wrapper_start.email=TRUE
#wrapper.event.jvm_prelaunch.email=TRUE
#wrapper.event.jvm_start.email=TRUE
#wrapper.event.jvm_started.email=TRUE
#wrapper.event.jvm_deadlock.email=TRUE
#wrapper.event.jvm_stop.email=TRUE
#wrapper.event.jvm_stopped.email=TRUE
#wrapper.event.jvm_restart.email=TRUE
#wrapper.event.jvm_failed_invocation.email=TRUE
#wrapper.event.jvm_max_failed_invocations.email=TRUE
#wrapper.event.jvm_kill.email=TRUE
#wrapper.event.jvm_killed.email=TRUE
#wrapper.event.jvm_unexpected_exit.email=TRUE
#wrapper.event.wrapper_stop.email=TRUE

# Specify custom mail content
wrapper.event.jvm_restart.email.body=The JVM was restarted.\n\nPlease check on its status.\n

#********************************************************************
# Wrapper Windows NT/2000/XP Service Properties
#********************************************************************
# WARNING - Do not modify any of these properties when an application
# using this configuration file has been installed as a service.
# Please uninstall the service before modifying this section. The
# service can then be reinstalled.

# Name of the service
wrapper.name=JBoss 7.2.0.Alpha1 (clustered mode)

# Display name of the service
wrapper.displayname=JBoss Application Server 7.2.0.Alpha1 (standalone config, clustered mode)

# Description of the service
wrapper.description=JBoss Application Server 7.2.0.Alpha1 (standalone config, clustered mode)

# Service dependencies. Add dependencies as needed starting from 1
wrapper.ntservice.dependency.1=

# Mode in which the service is installed. AUTO_START, DELAY_START or DEMAND_START
wrapper.ntservice.starttype=AUTO_START

# Allow the service to interact with the desktop.
wrapper.ntservice.interactive=false

JBoss7 can now be run by simply executing the corresponding batch file from {SERVICE_HOME}/bin. Please try running the application once as a console application to verify the configuration before attempting to run it as a service.

Congratulations. Your JBoss7 should now be up and running as a service. 🙂

References: http://wrapper.tanukisoftware.com/doc/english/integrate.html

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s