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 Script File - Provides a single shell script file which takes a command as a parameter to perform various actions on the Wrapper. Scripts like this are very common on UNIX systems.
  • Standalone Binary - It is also possible to run the Wrapper binary directly. In most cases, this is done from a command line by providing additional parameters, but it is also possible to use a default configuration file to avoid this requirement.

Command Based Batch File

Set up 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 into the bin directory of your application (on older Wrapper versions, this file was named 'sh.script.in').

Script file: 
{WRAPPER_HOME}/src/bin/App.sh.in

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

Example of replacing the file name: 
/usr/lib/myapp/bin/myapp

Now open the script into an editor:

There are several variables at the top of the script that can be used to configure how the Wrapper should be launched. Each of them is preceded with a description explaining the usage and possible values. In most cases you can start using the default values, and then think about changing some variables when the need arises.

Since version 3.5.37, the shell script will look for a file with the same basename as the script, located in the same directory, and suffixed with a '.shconf' extension. If such file exists it will be executed, making it possible to override any variable of the shell script. Should you need to customize a variable, it is a good practice to do it in the .shconf file and leave the script file to its original state. By doing so, any upgrade of the Wrapper will be easier as you would only need to replace the script without having to merge your modifications.

Example of script and shconf file names: 
/usr/lib/myapp/bin/myapp
/usr/lib/myapp/bin/myapp.shconf

Note that you will still need to replace the token in the 'INIT INFO' section at the top of the main script: 

### BEGIN INIT INFO
# Provides: @app.name@
# Required-Start: $local_fs $network $syslog
# Should-Start: 
# Required-Stop:
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: @app.long.name@
# Description: @app.description@
### END INIT INFO

Among the variables of the shell script, you will most likely want to at least edit APP_NAME and APP_LONG_NAME to reflect that the script is being used to launch your application. If APP_NAME is not set it will default to the basename of the shell script, and if APP_LONG_NAME is not set it will default to the value of APP_NAME.

Example: 
APP_NAME="myapp"
APP_LONG_NAME="My Application"

The script assumes that the wrapper executable is placed in the same directory, and 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 somewhere else, the WRAPPER_CMD and WRAPPER_CONF variables will require appropriate modifications.

WARNING

Important! Before proceeding, please make sure that the script, the '.shconf' file 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 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, the 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 cannot 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 shell script provides an unified way to install the Wrapper as a Daemon through different platforms (Linux distributions or other Unix systems), allowing your application to automatically start on a system boot or reboot.

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

During the installation step, the script will automatically detect the OS (Linux distributions or other Unix platforms), then figure out which service management tools (such as Systemd, Upstart, Initd) are present. Whenever several service managements are available, the most advanced one will be chosen. For example, on Linux, systemd is preferred to upstart, which itself is preferred to initd. This default behavior has been introduced in version 3.5.31 and can be changed by editing the following line located near the top of the script: 

SERVICE_MANAGEMENT_TOOL=auto

For example, if you want to force using initd over Systemd or Upstart, you may use the following: 

SERVICE_MANAGEMENT_TOOL=initd

NOTE

Note that the daemon needs to be reinstalled for the change on SERVICE_MANAGEMENT_TOOL to take effect.

NOTE

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

For FreeBSD and MacOSX users, or when using Systemd or Upstart on Linux, the install command will create a default configuration file that describes how the operating system service management will handle the script during the boot process.

It is possible to customize this step just by placing the configuration file into the bin directory:

  • On MacOSX, the file name of this file has to be {filename of your script}.plist.
  • On FreeBSD or for Upstart on Linux: {filename of your script}.install.
  • For Systemd: {filename of your script}.service.

For example, if the script is called "testwrapper" it would look for "testwrapper.plist" on MacOSX, "testwrapper.install" on FreeBSD or Upstart, and "testwrapper.service" on Systemd.

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 we will be more than happy to include them in the next release.

Standalone Binary

As an alternative to using the scripts shipped with the Java Service Wrapper, you may choose to launch the Wrapper directly.

Wrapper Usage

If the wrapper executable is launched without any parameters or with a "-?", the following usage output will be displayed.

Output Example: 
Java Service Wrapper Professional Edition 64-bit {version}
  Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
    https://wrapper.tanukisoftware.com

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
  -h  --hostid  print a list of HostIds which can be used to license this host.
  -v  --version print the Wrapper's Version information
  -?  --help    print this help message
  -- <args>     mark the end of Wrapper arguments.  All arguments after the
                '--' will be passed through unmodified to the java application.

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

[configuration properties] are configuration name-value pairs which override values
  in the Wrapper configuration file.  For example:
  wrapper.debug=true

  --cipher Obfuscate a password and generate a token along with wrapper.cipher.*
    properties that can then be used in the configuration file for added safety.
    The value to be encoded can be piped to Stdin of the Wrapper.  Otherwise, it
    will be prompted.
    The following arguments are available:
      --method <method name> One of the following methods:
          base64   : to encode in Base64
          base64url: to encode in the modified Base64 for URLs
          obf      : to generate a fixed obfuscated string
          robf     : to generate a random obfuscated string
      --name <cipher name> Optional cipher name. This argument is required when
        '--private_keyfile' is specified.
      --private_keyfile <file path> Optional path to a private key file
        (available for method 'obf' and 'robf').
      --encoding <utf8 or utf-8> Encoding to use when reading Stdin.
      --echo Echo the input to debug encoding issues (do not use with real
        passwords).
      --simple If specified, the output will only contain the obfuscated string.

  --keygen Generate a private key file to be used when obfuscating passwords.
    The following arguments are available:
      --method <method name> Obfuscation method for which the private key is
        intended to be used:
          obf : to generate a key for fixed obfuscation
          robf: to generate a key for random obfuscation
      --private_keyfile <file path> Specifies the filename of the key file.

  Please note that any file references must be absolute or relative to the location
  of the Wrapper executable.

Run the Wrapper in a Shell

To run the Wrapper in a shell, please use the -c command, followed by the path to the wrapper.conf file. The location of the wrapper.conf file can be absolute or relative. 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

Starting the Application as a Daemon Process

To launch the application as a daemon process using the command line, please add wrapper.daemonize=TRUE after the path to the wrapper.conf file. However, using the Shell Script is recommended.

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

Reference: Launching your application with the Wrapper

[Windows]

[Linux / Unix]

[Common]