Introduction

Jsvc is a set of libraries and applications for making Java
applications run on UNIX more easily.
Jsvc allows the application (e.g. Tomcat) to perform some privileged operations as root
(e.g. bind to a port < 1024), and then switch identity to a non-privileged user.
It can run on Win32 via the Cygwin emulation layer (see
Cygwin for more information),
however Win32 users may prefer to use procrun
instead, which allows the application to run as a Windows Service.

The sources are located in the src/native/unix subdirectory.

In the future APR may be used
to provide more portable platform support.

Building from source

To build under a UNIX operating system you will need:

GNU AutoConf (at least version 2.53)

An ANSI-C compliant compiler (GCC is good)

GNU Make

A Java Platform 2 compliant SDK

You need to build the "configure" program with:

sh support/buildconf.sh

(Note it is possible to replace sh by any compatible shell like bash, ksh).
The result should be something like:

Building from a release tarball

You have to specify the JAVA_HOME of the SDK
either with the --with-java=<dir> parameter or set the JAVA_HOME environment
to point to your SDK installation. For example:

./configure --with-java=/usr/java

or

export JAVA_HOME
./configure

If your operating system is supported, configure will go through cleanly,
otherwise it will report an error (please send us the details of your
OS/JDK, or a patch against the sources). To build the binaries and
libraries simply do:

make

This will generate the executable file jsvc.

Starting jsvc

To check the allowed parameters for the jsvc binary simply do:

./jsvc -help
Usage: jsvc [-options] class [args...]
Where options include:
-help | --help | -?
show this help page (implies -nodetach)
-jvm <JVM name>
use a specific Java Virtual Machine. Available JVMs:
'client' 'server'
-client
use a client Java Virtual Machine.
-server
use a server Java Virtual Machine.
-cp / -classpath <directories and zip/jar files>
set search path for service classes and resouces
-home <directory>
set the path of your JDK or JRE installation (or set
the JAVA_HOME environment variable)
-version
show the current Java environment version (to check
correctness of -home and -jvm. Implies -nodetach)
-showversion
show the current Java environment version (to check
correctness of -home and -jvm) and continue execution.
-nodetach
don't detach from parent process and become a daemon
-debug
verbosely print debugging information
-check
only check service (implies -nodetach)
-user <user>
user used to run the daemon (defaults to current user)
-verbose[:class|gc|jni]
enable verbose output
-cwd </full/path>
set working directory to given location (defaults to /)
-outfile </full/path/to/file>
Location for output from stdout (defaults to /dev/null)
Use the value '&2' to simulate '1>&2'
-errfile </full/path/to/file>
Location for output from stderr (defaults to /dev/null)
Use the value '&1' to simulate '2>&1'
-pidfile </full/path/to/file>
Location for output from the file containing the pid of jsvc
(defaults to /var/run/jsvc.pid)
-D<name>=<value>
set a Java system property
-X<option>
set Virtual Machine specific option
-ea[:<packagename>...|:<classname>]
-enableassertions[:<packagename>...|:<classname>]
enable assertions
-da[:<packagename>...|:<classname>]
-disableassertions[:<packagename>...|:<classname>]
disable assertions
-esa | -enablesystemassertions
enable system assertions
-dsa | -disablesystemassertions
disable system assertions
-agentlib:<libname>[=<options>]
load native agent library <libname>, e.g. -agentlib:hprof
-agentpath:<pathname>[=<options>]
load native agent library by full pathname
-javaagent:<jarpath>[=<options>]
load Java programming language agent, see java.lang.instrument
-procname <procname>
use the specified process name (works only for Linux)
-wait <waittime>
wait waittime seconds for the service to start
waittime should multiple of 10 (min=10)
-restarts <maxrestarts>
maximum automatic restarts (integer)
-1=infinite (default), 0=none, 1..(INT_MAX-1)=fixed restart count
-stop
stop the service using the file given in the -pidfile option
-keepstdin
does not redirect stdin to /dev/null
--add-modules=<module name>
Java 9 --add-modules option. Passed as it is to JVM
--module-path=<module path>
Java 9 --module-path option. Passed as it is to JVM
--upgrade-module-path=<module path>
Java 9 --upgrade-module-path option. Passed as it is to JVM
--add-reads=<module name>
Java 9 --add-reads option. Passed as it is to JVM
--add-exports=<module name>
Java 9 --add-exports option. Passed as it is to JVM
--add-opens=<module name>
Java 9 --add-opens option. Passed as it is to JVM
--limit-modules=<module name>
Java 9 --limit-modules option. Passed as it is to JVM
--patch-module=<module name>
Java 9 --patch-module option. Passed as it is to JVM
--illegal-access=<value>
Java 9 --illegal-access option. Passed as it is to JVM. Refer java help for possible values.

Mac OS X universal binaries

If jsvc was build with universal binary support the proper way of
starting jsvc is by using Mac OS X arch command:

Use -jvm server because default client JVM is
not present for all architectures.

Using jsvc

There two ways to use jsvc: via a Class that implements the Daemon interface or
via calling a Class that has the required methods.
For example Tomcat-4.1.x uses the Daemon interface
whereas Tomcat-5.0.x provides a Class whose methods are called by jsvc directly.

void stop(): Inform the Thread to terminate the run(), close the ServerSockets

void destroy(): Destroy any object created in init()

Store it in a jarfile and use as above:

./jsvc -cp my.jar MyClass

How jsvc works

Jsvc uses 3 processes: a launcher process, a controller process and a controlled process.
The controlled process is also the main java thread, if the JVM crashes
the controller will restart it in the next minute.
Jsvc is a daemon process so it should be started as root and the -user parameter
allows to downgrade to an unprivilegded user.
When the -wait parameter is used, the launcher process waits until the controller says
"I am ready", otherwise it returns after creating the controller process.

Apache Commons, Apache Commons Daemon, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation.
All other marks mentioned may be trademarks or registered trademarks of their respective owners.