Pointers to information on establishing a Windows Service

The following links supply information about running programs as a Windows Service. Based on emails read there are at least three programs that help establish a program as a Windows Service: srvany.exe, Java *Service* Launcher (JSL) or Java *Service* Wrapper by Tanuki Software - there are probably others.

The usage of the standard windows programs (instsrv.EXE and srvany.exe) is described in the tutorial below.

JSL and JSW are alternative ways of wrapping Java programs into a windows service.

Example Configuration Using Java Service Wrapper

Setting up Derby to run as a windows service is not terribly difficult using the Java Service Wrapper (JSW) by Tanuki Software. The steps below refer to Derby 10.2 and JSW version 3.2.3 configuring a service on Windows Server 2003.

Create Service User

It is typically a good idea to run services such as this one under a non-SYSTEM account. So first, create the user account that this service will run as.

   C:\> net user derby derbypw /ADD /PASSWORDCHG:NO /EXPIRES:NEVER /FULLNAME:"Derby DB" /COMMENT:"Derby DB service logon account"

The above command creates a local user "derby" with a password "derbypw". This user must now be granted access to log on as a windows service. Launch the "Local Security Settings" from the Control Panel's "Administrative Tools" folder. In this application:

  1. In the left tree pane, navigate to "Security Settings / Local Policies / User Rights Assignment"
  2. Find the "Log on as a service" policy in the right pane
  3. Add the "derby" user (in the local computer domain) to this policy

By default, this user will have read-only access to the files and directories on the disk. Grant this user full control access (or whatever is appropriate for your needs) to the directory where the databases are to be stored. To aid in troubleshooting, also ensure that this user has write access to any locations where log files are stored.

In sites concerned about security there are plenty of other steps to be taken to lock down this account but they go well beyond the scope of this page.

Configure the Wrapper

To configure the Java Service Wrapper (JSW), create a configuration file that describes the Derby launch and shutdown parameters. But before getting into the details of this file, it is important to know that the file will contain a lot of paths to various files. Java Service Wrapper sets the current working directory to the location of the wrapper executable. So any relative paths are relative to the location of "Wrapper.exe". Now, to configure JSW:

  1. Create a file (it doesn't really matter where) called derby.conf. This file has a ".properties"-style format (key = value) to specify the configuration parameters.
  2. Add a property wrapper.java.command to specify the java runtime to launch:
    wrapper.java.command = C:/Program Files/Java/jdk1.6.0_02/bin/java.exe
  3. Derby works well with the Wrapper Start/Stop mechanism (option 2 of the JSW configuration reference). To enable this option add the property:
    wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperStartStopApp
  4. Next provide properties to set the classpath. You need to specify the three derby JAR's and the wrapper JAR:
    wrapper.java.classpath.1=C:/Program Files/Derby/lib/derby.jar
    wrapper.java.classpath.2=C:/Program Files/Derby/lib/derbynet.jar
    wrapper.java.classpath.3=C:/Program Files/Derby/lib/derbytools.jar
    wrapper.java.classpath.4=C:/Program Files/JavaServiceWrapper/Wrapper.jar
    be sure to change the paths to their actual location on your system.
  5. Set whatever Derby options are required using the wrapper.java.additional.N properties where N is a sequential index (starting with 1) for each option. Since JSW sets the current working directory to the location of its executable, you will at least want to set the derby.system.home property:
    wrapper.java.additional.1=-Dderby.system.home=E:/Databases
  6. Set the application parameters that will configure the wrapper to start and stop the application using the appropriate Derby class and options:
    wrapper.app.parameter.1=org.apache.derby.drda.NetworkServerControl
    # number of arguments is 3
    wrapper.app.parameter.2=3
    wrapper.app.parameter.3=start
    # Option -h 0.0.0.0 means: listening on all interfaces, not only on localhost.
    # This is needed to make the derby server accept connections from other hosts
    # than the localhost.
    wrapper.app.parameter.4=-h
    wrapper.app.parameter.5=0.0.0.0
    wrapper.app.parameter.6=org.apache.derby.drda.NetworkServerControl
    wrapper.app.parameter.7=true
    # number of arguments is 1
    wrapper.app.parameter.8=1
    wrapper.app.parameter.9=shutdown
  7. Set the library search path so that JSW can find its Wrapper.dll. Set this parameter to the location of that DLL
    wrapper.java.library.path.1=C:/Program Files/JavaServiceWrapper/lib
  8. Set some standard Java runtime options (values are in MB - adjust as necessary)
    wrapper.java.initmemory=64
    wrapper.java.maxmemory=128
    

  9. Set some general logging options:
    wrapper.console.format=PM
    wrapper.console.loglevel=INFO
    wrapper.logfile=C:/logs/wrapper.log
    wrapper.logfile.format=LPTM
    wrapper.logfile.loglevel=INFO
    wrapper.logfile.maxsize=5m
    wrapper.logfile.maxfiles=10
    wrapper.syslog.loglevel=ERROR
  10. Finally, set the service options:
    wrapper.console.title=Derby DB Server
    wrapper.ntservice.name=derby
    wrapper.ntservice.displayname=Apache Derby Database
    wrapper.ntservice.description=Apache Derby Relational Database Engine (Network Server)
    wrapper.ntservice.starttype=AUTO_START
    wrapper.ntservice.interactive=false
    wrapper.ntservice.account=.\derby
    wrapper.ntservice.password=derbypw

There are alternative options if you do not want to put the account password into a file. See the JSW docs for more information.

Set Java policy

To enable the derby network server and the wrapper to open connections the polycies for the wrapper and derby jar files have to be added in the policy-files of the execution JVM.

Add the following lines to C:/Program Files/Java/jdk1.6.0_02/lib/security/java.policy

   // Give Wrapper classes full permissions
grant codeBase "file:C:/Program Files/Derby/lib/wrapper.jar" {
    permission java.security.AllPermission;
};

// Give Derby net classes full permissions
grant codeBase "file:C:/Program Files/Derby/lib/derbynet.jar" {
    permission java.security.AllPermission;
};
Start It Up

Before installing the service, run it from the console to ensure things are working properly.

  C:\> Wrapper.exe -c derby.conf

You will have to supply the full path to the "derby.conf" file unless both Wrapper.exe and derby.conf are in the same directory. If things are configured correctly, this will start up in the current command window and await connections:

C:\> "C:\Program Files\JavaServiceWrapper\bin\Wrapper.exe" -c C:\src\conf\derby.conf
wrapper  | --> Wrapper Started as Console
wrapper  | Launching a JVM...
jvm 1    | Wrapper (Version 3.2.3) http://wrapper.tanukisoftware.org
jvm 1    |   Copyright 1999-2006 Tanuki Software, Inc.  All Rights Reserved.
jvm 1    |
jvm 1    | Apache Derby Network Server - 10.2.2.0 - (485682) started and ready to accept connections on port 1527 at 2007-08-03 16:43:04.028 GMT

Use <CTRL-C> to stop the server. The JSW intercepts this and issues the proper shutdown sequence for Derby.

Once it works from the console, install the service. Just replace the "-c" option to Wrapper with "-i"

C:\> "C:\Program Files\JavaServiceWrapper\bin\Wrapper.exe" -i C:\src\conf\derby.conf
wrapper  | Apache Derby Database Server installed.

And that should be all. Start the service either by rebooting or through the service control manager:

C:\> net start derby
The Apache Derby Database service is starting..
The Apache Derby Database service was started successfully.

At this point if you have trouble connecting to the database (and you had no problems when running in the console) it is typically a permissions problem with the "derby" user account. Error messages are logged in a variety of places:

  • Windows Event Viewer
  • The wrapper log file (configured in the derby.conf file as the property wrapper.logfile for error messages.
  • The Derby log file
  • No labels