Page tree
Skip to end of metadata
Go to start of metadata


Implementing the Handle Server on Windows using the Tanuki Service Wrapper


This guide is based on the Tanuiki WrapperSimpleApp Integration modified to allow the DSpace handle server to be run as a Microsoft Windows service. Many thanks to Tanuki for allowing this guide to be posted.

More information on the Tanuki project along with the software required can be found at:

This installation guide will refer to the path of the DSpace installation as dspace, the path of the DSpace source as dspace-src and the path of where the Tanuki software is extracted to as wrapper.

Registering for a Handle

1) The Handle server code is included with the DSpace code in


. Note: The latest version of the handle.jar file is not included in the release due to licensing conditions changing between the provided version and later versions. It is recommended you read the new license conditions and decide whether you wish to update your installation's handle.jar. If you decide to update, you should replace the existing handle.jar in dspace/lib with the new version and rebuild your war files.
2) Firstly generate the

by running the following command and completing the questions:

[dspace]/bin/dsrun net.handle.server.SimpleSetup [dspace]/handle-server

3) Register for your handle at (CNRI You will be required to fill in details about your organisation, pay a small annual fee and upload the which was generated in the previous step and can be located in


4) The registration process should take about one week. Once completed you should receive a handle which can be used to update DSpace.

Updating DSpace

1) Once you receive your handle, it will need to be updated in the dspace\dspace.cfg. Update the following line to your own handle code:

##### Handle settings ######
# CNRI Handle prefix
handle.prefix = 123456789

2) Once updated you will need to save the dspace.cfg file and restart Tomcat.
3) If you need to update the handle prefix on items created before the CNRI registration process you can run the


script. You may need to do this if you loaded items prior to CNRI registration (e.g. setting up a demonstration system prior to migrating it to production). The script takes the current and new prefix as parameters. For example:

[dspace]/bin/update-handle-prefix 123456789 1303

will change any handles currently assigned prefix 123456789 to prefix 1303, so for example handle 123456789/23 will be updated to 1303/23 in the database.

Updating the Handle-Server

1) Edit the resulting file config.dct found at


to include the following clause in the "server_config" clause:

"server_config" = {
"storage_type" = "CUSTOM"
"storage_class" = "org.dspace.handle.HandlePlugin"

2) Update all references to YOUR_NAMING_AUTHORITY to your handle prefix. i.e.:


Installing the Tanuki Service Wrapper

1) Download the Tanuki Java service wrapper and extract to wrapper

2) Copy the following file from


into the




3) Copy the following files from


into the




4) Rename the three batch files as below and ensure the .in extension is removed. Depending on how your file explorer is configured, you may not be able to see the extensions.

[dspace]\bin\ -> [dspace]\bin\dspace-handle.bat
[dspace]\bin\ -> [dspace]\bin\install-dspace-handle.bat
[dspace]\bin\ -> [dspace]\bin\uninstall-dspace-handle.bat

The Wrapper.exe file is the actual Wrapper executable. The three batch files are used to run DSpace in a console, and to install and remove it as an NT Service. These scripts should not require any modification. They do assume that the wrapper.conf file will be located within a conf directory one level up,


. If you wish to locate this file someplace else, then the three batch files will require that small modification.

5) Copy the following files from wrapper\lib to the dspace\config directory. NOTE: Do NOT place the following files the dspace\lib directory as they will be overwritten upon a DSpace rebuild.


The Wrapper.DLL file is a native library required by the portion of the Wrapper which runs within the JVM. The wrapper.jar file contains all of the Wrapper classes

6) The Wrapper requires a configuration file which needs to be copied from


to the


directory. Ensure that the .in extension is removed from the wrapper.conf file.


7) The following batch files will then need to be updated to tell the wrapper the location of the config file:


Locate the line:

set _WRAPPER_CONF="%_REALPATH%..\conf\wrapper.conf" and modify to
set _WRAPPER_CONF="%_REALPATH%..\config\wrapper.conf"

Save and close each of the batch files. If you wish to relocate the configuration file, you are free to do so. You will need to modify the batch scripts copied into the bin directory above, to reflect the new location.

8) To ensure that the wrapper files are not over written, they will need to be copied into the follwing



[dspace]\bin\wrapper.exe -> [dspace-src]\dspace\bin\wrapper.exe

[dspace]\bin\dspace-handle.bat -> [dspace-src]\dspace\bin\dspace-handle.bat
[dspace]\bin\install-dspace-handle.bat -> [dspace-src]\dspace\bin\install-dspace-handle.bat
[dspace]\bin\uninstall-dspace-handle.bat -> [dspace-src]\dspace\bin\uninstall-dspace-handle.bat

Editing the config file

When editing the configuration file


is the absolute path i.e.



# Java Application Path
# i.e. Files/Java/jdk1.6.0_04/bin/java[PATH TO JDK]/bin/java

# Java Classpath (include wrapper.jar)  Add class path elements as needed starting from 1[dspace]/config/wrapper.jar[dspace]/lib/handle.jar[dspace]/lib/*.jar[dspace]/config/templates/*[dspace]/config/dspace.cfg

# Java Library Path (location of Wrapper.DLL or[dspace]/config

# Java Additional Parameters[dspace]/config/dspace.cfg

# Application parameters required to start handle server.  Add parameters as needed starting from 1[dspace]/handle-server

# Log file to use for wrapper output logging. This needs to be modified from logs to log to write to the DSpace logging directory.

# Name of the service

# Display name of the service
wrapper.ntservice.displayname=DSpace Handle Service

# Description of the service
wrapper.ntservice.description=DSpace Handle Service

Testing the Wrapper Installation

1) The Handle Server can be run by executing the


script. A terminal window should open as the server loads (see below)

2) Shutdown the handle server by executing CTRL^C in the command window and select Y.

Installing the Handle Server as a Windows Service

1) Once the handle server has been tested and is functioning correctly, it can be installed as a windows service.

2) Execute the following batch script to install the Handle Server as a Windows service:


Checking the Windows Services GUI will show the installed service

3) To uninstall the service, execute the following script:



If a similar error message to below is displayed:

WrapperManager Error: Unexpected exception opening backend socket: Network is unreachable: connect

1) Ensure ports 2641 and 8000 (TCP/UDP) are open in both your server firewall and institutions firewall.

2) Ensure your server's correct IP is specified in the dspace/handle-server/config.dct