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.
- Tutorial on standard Windows service generation: http://www.vogella.de/articles/ApacheDerby/article.html#service
JSL and JSW are alternative ways of wrapping Java programs into a windows service.
- Information on JSL: http://sourceforge.net/projects/jslwin
- Information on JSW: http://wrapper.tanukisoftware.org/doc/english/index.html
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:
- In the left tree pane, navigate to "Security Settings / Local Policies / User Rights Assignment"
- Find the "Log on as a service" policy in the right pane
- 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:
- 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. - 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
- 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
- Next provide properties to set the classpath. You need to specify the three derby JAR's and the wrapper JAR:
be sure to change the paths to their actual location on your system.
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
- Set whatever Derby options are required using the
wrapper.java.additional.N
properties whereN
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 thederby.system.home
property:wrapper.java.additional.1=-Dderby.system.home=E:/Databases
- 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
- 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
- Set some standard Java runtime options (values are in MB - adjust as necessary)
wrapper.java.initmemory=64 wrapper.java.maxmemory=128
- 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
- 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 propertywrapper.logfile
for error messages. - The Derby log file