World Map
Java Service Wrapper is the easiest way to make your product more reliable.
  • Free Trial
  • Buy Now
Launching Your Application (Linux / UNIX)

Launching Your Application (Linux / Unix)

On UNIX, it is possible to run an application either as a desktop application, or as a daemon process in the background. In the case of a daemon, the Wrapper needs to be able to be installed, removed, started, stopped, have its status queried, etc. Depending on whether the application has a GUI or is meant to be run in a command window also determines how it will be run.

Command Based Batch File

Setup The Scripts

The Wrapper is shipped with a shell script (sh) which can be used to reliably start and stop any Java application controlled by the Java Service Wrapper.

First, please copy the following shell script from the Wrapper directory into the bin directory of your application.

Script file:
{WRAPPER_HOME}\src\bin\sh.script.in

Rename the script file to reflect your application name. (Replace "MyApp" with the name of your application throughout this document.)

Example of Replacing file name:
/usr/lib/myapp/bin/myapp

Now open the script into an editor. We need to set the long and short names to reflect that the script is being used to launch your application. You will see two variables immediately after the header of the script. APP_NAME and APP_LONG_NAME. Suggested values for these variables are shown below.

Example of Setting in the script:
APP_NAME="myapp"
APP_LONG_NAME="My Application"

The script should not require any additional modification. However it does assume that the wrapper executable is placed in the same directory, and also assume that the wrapper.conf file is placed within a conf directory (one level up, ../conf/wrapper.conf). If you wish to place either of these files someplace else, the WRAPPER_CONF variable in the script will require appropriate modification.

WARNING

Important! Before proceeding, please make sure that both the script and the wrapper executable have their executable bit set.

NOTE

The shell script (sh) will attempt to create a PID file in the /var/run directory. If the user used to launch the Wrapper does not have permission to write to this directory then this will result in an error. An alternative that will work in most cases is to write the PID file to the same directory where the Wrapper executable is located. To make this change, edit the sh script and change the following line:

PIDDIR="/var/run"

to:

PIDDIR="./"

Running in a Console

Start the application:

The application can now be run by simply executing bin/myapp console. Because of the way the Wrapper script sets its current directory, it is not necessary to run this script from within the bin directory.

Command and Output Example:
/usr/lib/myapp/bin/myapp console
Running My Application...
wrapper  | --> Wrapper Started as Console
wrapper  | Launching a JVM...
jvm 1    | Wrapper (Version 3.x.x)
jvm 1    |

When running using the console command, output from the JVM will be visible in the console.

Stop the application:

The application can be terminated by pressing CTRL-C in the console (command window). This will cause the Wrapper to shut down the application cleanly.

Standard Daemon scripts:

As you will see if you omit a command, the scripts shipped with the Wrapper are fairly standard daemon scripts. They accept console, start, stop, restart, status, and dump commands. The start, stop, and restart commands are common to most daemon scripts and are used to control the Wrapper and its application as a daemon process. The status command can be used to find out whether or not the Wrapper is currently running. The console command will launch the Wrapper in the current shell, making it possible to kill the application with CTRL-C. The final command, dump, will send a "kill -3" signal to the Wrapper causing the its JVM to do a full thread dump.

Running as a Daemon Process

The application can be run as a detached daemon process by executing the script using the start command.

Command and Output Example:
/usr/lib/myapp/bin/myapp start
Running My Application...

When running using the start command, output from the JVM will only be visible by viewing the wrapper.log file using tail -f wrapper.log

Because the application is running as a detached process, it can not be terminated using CTRL-C and will continue to run even if the console is closed.

To stop the application, rerun the script using the stop command.

Command and Output Example:
/usr/lib/myapp/bin/myapp stop
Stopping TestWrapper Example Application...
Stopped TestWrapper Example Application.

Installing The Application To Start on Reboot

Introduced in the Wrapper version 3.4.0, the script provides a way to embed the Wrapper (and finally your application). The script will automatically detect your OS - on Linux platforms also some distributions - and perform the steps necessary to install the Wrapper script into the initialization process of your OS.

Output Example:
$ sudo bin/testwrapper install
[sudo] password for tanuki: 
Detected Ubuntu:
 Installing service testwrapper from current directory /home/tanuki/wrapper/bin
 Adding system startup for /etc/init.d/testwrapper ...
   /etc/rc0.d/K20testwrapper -> ../init.d/testwrapper
   /etc/rc1.d/K20testwrapper -> ../init.d/testwrapper
   /etc/rc6.d/K20testwrapper -> ../init.d/testwrapper
   /etc/rc2.d/S20testwrapper -> ../init.d/testwrapper
   /etc/rc3.d/S20testwrapper -> ../init.d/testwrapper
   /etc/rc4.d/S20testwrapper -> ../init.d/testwrapper
   /etc/rc5.d/S20testwrapper -> ../init.d/testwrapper

As the script installs itself into your OS, it is necessary to run the install (and uninstall) option as a root user!

For freebsd and MacOSX users, the script provides a default configuration file how launchd or initd will handle the script during the boot process. However it is possible to customize this step just by placing the configuration file into the bin directory. For MacOSX, the file name of this file has to be {filename of your script}.plist. For freebsd, {filename of your script}.install. For example if the script is called "testwrapper" it would look for respectively "testwrapper.plist" on MacOSX, and "testwrapper.install" on freebsd.

Ubuntu and RedHat flavoured Linux Distributions also support the usage of Upstart. By default, init.d/rc.d scripts are still used. So in order to switch to upstart, please open the Wrapper script and set the variable USE_UPSTART to a value.

Example of Setting up the script:
# flag for using upstart when installing (rather than init.d rc.d)
USE_UPSTART=true

When calling the script passing over the parameter "install", it will install itself as upstart service. By default, the script generates an Upstart config file in /etc/init/. However, quite alike FreeBSD and MacOS, you can also create your own upstart config file. If the script finds a file called {filename of your script}.install in the same directory the script is located, it will rather use this file as upstart conf file.

Output Example:
$ sudo bin/testwrapper install
[sudo] password for tanuki: 
Detected Ubuntu:
Installing the TestWrapper Example Application daemon using upstart..
creating default upstart conf file..

If you wish to uninstall/remove the Wrapper from the system initialization, run the script (as a root user!) with passing the action parameter "remove". This will first stop the running Wrapper application and finally clean itself from initialization.

Output Example:
$ sudo bin/testwrapper remove
[sudo] password for tanuki: 
Stopping TestWrapper Example Application...
Stopped TestWrapper Example Application.
Detected Ubuntu:
 Removing service testwrapper from current directory /home/tanuki/wrapper/bin
 Removing any system startup links for /etc/init.d/testwrapper ...
   /etc/rc0.d/K20testwrapper
   /etc/rc1.d/K20testwrapper
   /etc/rc2.d/S20testwrapper
   /etc/rc3.d/S20testwrapper
   /etc/rc4.d/S20testwrapper
   /etc/rc5.d/S20testwrapper
   /etc/rc6.d/K20testwrapper

Installing older versions of the Wrapper prior to 3.4.0 has to be done manually. If your platform is not included, please read over those that have been included and adapt as necessary. Please post what you come up with to the wrapper-user@lists.sourceforge.net mailing list and I will be more than happy to include them in the next release.

Using Wrapper Directly

As an alternative to using the scripts shipped with the Java Service Wrapper, you may choose to launch the Wrapper directly. If the wrapper executable is launched without any parameters, the following usage output will be displayed.

Output Example:
/usr/lib/myapp/bin/wrapper
Wrapper (Version 3.n.n) http://wrapper.tanukisoftware.org

Usage:
  wrapper <command> <configuration file> [configuration properties] [...]
  wrapper <configuration file> [configuration properties] [...]
     (<command> implicitly '-c')
  wrapper <command>
     (<configuration file> implicitly 'wrapper.conf')
  wrapper
     (<command> implicitly '-c' and <configuration file> 'wrapper.conf')

where <command> can be one of:
  -c  --console run as a Console application
  -?  --help    print this help message

<configuration file> is the wrapper.conf to use.  Name must be absolute or relative
  to the location of wrapper

[configuration properties] are configuration name-value pairs which override values
  in wrapper.conf.  For example:
  wrapper.debug=TRUE

To run the Wrapper in a shell, you would specify the -c command, followed by the wrapper.conf file. The location of the wrapper.conf file can be an absolute or relative location. If a relative path is used, the path is always relative to the location of the wrapper file, not the current directory.

Command Example:
/usr/lib/myapp/bin/wrapper -c ..\conf\wrapper.conf

To launch the application as a daemon process (Using the shell script is recommended):

Command Example:
/usr/lib/myapp/bin/wrapper -c ..\conf\wrapper.conf wrapper.daemonize=TRUE

Standalone Binary

TODO