Daemon

Introduction

Actually only the UNIX like platforms are supported. The sources are located in the src/native/unix subdirectory of the project sources. For win32 platforms the cygwin emulation layer is used. See cygwin for more information.

In the future APR may be used to provide more convenient 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:

support/buildconf.sh
support/buildconf.sh: configure script generated successfully

Once the configure script is generated, follow the next section.

Building from a release tarball

To build the binary under a UNIX operating system you will need:

An ANSI-C compliant compiler (GCC is good)
GNU Make
A Java Platform 2 compliant SDK

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

export JAVA_HOME
./configure

If your operating system is supported, configure will go thru 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:

    -jvm <JVM name>
        use a specific Java Virtual Machine. Available JVMs:
            'client' 'server'
    -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)
    -help / -?
        show this help page (implies -nodetach)
    -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
    -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
    -wait <waittime>
        wait waittime seconds for the service to start
        waittime should multiple of 10 (min=10)
    -stop
        stop the service using the file given in the -pidfile option

Using jsvc

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

Via Daemon interface

You have to do the following.

Write a Class that implements the Daemon interface (MyClass).
Put it in the jarfile (my.jar).

Call jsvc like:

./jsvc -cp commons-daemon.jar:my.jar MyClass

Directly

You have to write a Class (MyClass) that implements the following methods:

void load(String[] arguments): Here open the configuration files, create the trace file, create the ServerSockets, the Threads
void start(): Start the Thread, accept incoming connections
void stop(): Inform the Thread to live the run(), close the ServerSockets
void destroy(): Destroy any object created in init()

Store it in a jarfile and use as above:

./jsvc -cp commons-daemon.jar: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.

Forks in commons-daemon

Launcher process:

main()
{
  fork()
  parent: wait_child(), wait until JAVA service started when the child says "I am ready".
  child: controller process.
}

Controller process:

  while (fork()) {
    parent: wait_for_child.
      if exited and restart needed continue
      else exit.
    child: exit(child()). controlled process.
  }

Controlled process:

In child(): controlled process.
  init_JVM().
  load_service().
  start_service().
  say "I am ready"
  wait for signal or pool for stop
  stop_service().
  destroy_service().
  destroy_JVM().
  exit (with different codes so that parent knows if it has to restart us).

Note: The controller process uses signals to stop the controlled process.

Downgrading user

On linux setuid()/setgid() + capabilities are used. On other unix setgid/initgroups are used. We have something like:

/* as root */
init_JVM().
load_service. /*  java_load() calls the load method */
downgrade user (set_caps() or set_user_group())
/* as the user $USER (from -user $USER parameter) */
umask()
start_service. /* java_start() calls the start method */

Development

Project Documentation

Commons

ASF