Build windows service from java application with procrun

Recently, I needed to adjust a Java application to be able to run as a Windows service which is the Windows equivalent to a Unix daemon. There are several libraries available for this kind of task and after some reading, I chose Apache procrun which turned out to be a good choice. The configuration was less painful than expected and the tool seems quite powerful, due to a large set of configuration options. Also, building a Windows service or a Unix daemon should not make much of a difference. I used a 64bit Windows 7 and 32bit Java 7 JVM for this tutorial.

Everything you need to know about procrun really is on the page that is linked above. There even is a basic tutorial. However, the documentation is not overly verbose and it took me some time to get everything up and running, so I think a more verbose basic tutorial will not hurt.

To begin with, you need a Java application. You can built a service from more or less any application and here is a simple class, SomeService with some artifical behaviour:

package com.wordpress.joerglenhard.procrun.demo;

public class SomeService {

    private static boolean stop = false;

    public static void start(String[] args) {
        System.out.println("start");
        while (!stop) {
            try {
                Thread.sleep(1000);
            } catch (InterruptedException e) {
            }
            System.out.println("running");
        }
    }

    public static void stop(String[] args) {
        System.out.println("stop");
        stop = true;
    }

    public static void main(String[] args) {
        if ("start".equals(args[0])) {
            start(args);
        } else if ("stop".equals(args[0])) {
            stop(args);
        }
    }

}

The application acknowledges the call of the start method and then keeps on printing the String “running” every second until it is stopped through the stop method.
Actually, the normal main method and the other two static methods are alternatives for starting and stopping the service. I found both ways useful and will get to that later.

Next, you need to build an executable from this class. For Windows that would be the usual .exe, but an executable jar file is just as fine. I used a jar file and though the contents are very basic, for completeness, here is the MANIFEST.MF:

Manifest-Version: 1.0
Class-Path: .
Main-Class: com.wordpress.joerglenhard.procrun.demo.SomeService

Now, you need procrun to turn that into a Windows service. Download it from the procrun download page and unpack whatever you chose to download. In my case, this was version 1.0.10 of the Windows binaries and the essential part in the archive is prunsrv.exe, the procrun service application which is responsible for installing and removing the service. prunmgr.exe is also an extremly useful application that provides a GUI to set everything you can configure via batch scripts.

The difficult part now is to install the service. This can be done by a call of prunsrv.exe with appropriate options. There are quite some options you can / have to use, so this is best packaged as a batch script which I called installService.bat:

set SERVICE_NAME=TestService
set PR_INSTALL=C:\workspaces\blog\procrun-demo\prunsrv.exe

REM Service log configuration
set PR_LOGPREFIX=%SERVICE_NAME%
set PR_LOGPATH=c:\logs
set PR_STDOUTPUT=c:\logs\stdout.txt
set PR_STDERROR=c:\logs\stderr.txt
set PR_LOGLEVEL=Error

REM Path to java installation
set PR_JVM=C:\Program Files (x86)\Java\jre7\bin\client\jvm.dll
set PR_CLASSPATH=someservice.jar

REM Startup configuration
set PR_STARTUP=auto
set PR_STARTMODE=jvm
set PR_STARTCLASS=com.wordpress.joerglenhard.procrun.demo.SomeService
set PR_STARTMETHOD=start

REM Shutdown configuration
set PR_STOPMODE=jvm
set PR_STOPCLASS=com.wordpress.joerglenhard.procrun.demo.SomeService
set PR_STOPMETHOD=stop

REM JVM configuration
set PR_JVMMS=256
set PR_JVMMX=1024
set PR_JVMSS=4000
set PR_JVMOPTIONS=-Duser.language=DE;-Duser.region=de
REM Install servic prunsrv.exe //IS//%SERVICE_NAME%

Open the command prompt and move to the directory where the script is located. The script modifies the registry, so it needs to have administrator privileges to execute successfully. The first line sets the service name which determines its registry key. Next, you need to set the path to prunsrv.exe. On that note, here is a lesson that took me some time to learn: If you use (correct) relative paths to files in the installation script, the service will install correctly and it will run fine in debugging mode. It will however fail when run normally with any administrative tooling you have. Be it the usual Windows management console (Computer -> Manage -> Services and Applications -> TestService) or prunmgr.exe. Generally, you should use absolute paths with procrun. Interestingly, there is one exception to this rule: the jar file you use as classpath. Here, the relative path worked out fine for me. Another lesson, I found on stackoverflow, is that you must not use white spaces in the service name.

But back to the script: Lines 5 – 9 set the logging behaviour This needs to be adjusted to proper paths of the system. The same applies to line 12 which needs to point to a jvm, on my system this is a client jvm. This is required, because the service here is set to run in jvm mode (line 17). In java mode, the JAVA_HOME environment variable is used to resolve the jvm location. The difference between the modes essentially is that the jvm mode starts the service in-process while the other modes (java or exe) use a separate one.

Lines 16 – 19 and 22 – 24 reference the class that allows to start and stop the service which is of course the only class we have here. Furthermore, the methods to be invoked on startup and shutdown are set. You can set the method arguments as well using PR_STARTPARAM or PR_STOPPARAM, but this is required for the methods used here. Had I used the normal main method, the setting of the program arguments would have been required. Lines 27 – 30 set the memory settings of the jvm and last but not least, Line 33 installs the service.

Now, you can use prunsrv.exe to run the service in debugging mode (you can do that without administrator privileges) which uses the current command prompt as output:

> start prunsrv.exe //TS//TestService

This fires up a new window and if you hit CTRL+C to stop the service, you should see something like the following before the window closes:

You might wonder why the service outputs one more “running” after the stop method was invoked. Start and stop are called from different threads, so there can be race conditions. I wanted to keep the service code simple and did not use any synchronization. That’s fine for a trivial example, but not for production code, of course.

Finally, in case you don’t want to keep that service on your system, uninstallation is pretty easy. Simply call (with administrator privileges):

> prunsrv.exe //DS//TestService

So actually procrun is a fine tool that is not difficult to use. You just have to invest some time to dig into it. I hope some people will have that easier with this tutorial.

Update 2013-09-02

Due to continuing interest in the tutorial, I decided to provide a sample version on github, available here. The settings in the repository differ a little from the settings below in the paths, as my installation is a little bit different now from when I wrote this post. To use the code simply run:

git clone git@github.com:lenhard/procrun-sample.git