SUNScholar/Handle Server

From Libopedia
Jump to navigation Jump to search
Back to After Installation Tasks
Back to Digital Object Identifiers


After an upgrade from DSpace 1.8.2 to 3.2, the following software bug appeared.



The handle service allows us to apply a short URL, which is persistent, for the purposes of citation and discovery on the web.

Click on the image above and then copy and paste the following, to see how the service works:


Step 1 - Register as handle server

Visit the following web sites to register as handle server;

Step 2 - Prepare an initial handle request

After you have logged into to the server, type the following in a terminal on your server and then follow the command line instructions;

$HOME/bin/dspace make-handle-config $HOME/handle-server

When asked to encrypt, say no!

Step 3 - Send handle request email

Mail the file:



They will quickly create your global identifier and email you with the appropriate information.

Tip: Save the file to your USB stick and mail it from your default workstation.

Do not continue until you have received your handle from the handle registrar!


Step 4 - Update handle server config file

Step 1

Once you receive the email, print a copy on your default workstation then login to your DSpace server with Ubuntu as the "dspace" user.

Step 2

Edit the following file:

nano $HOME/handle-server/config.dct

Step 3

Replace all mention of 300:0.NA/123456789 or 300:0.NA/YOUR_NAMING_AUTHORITY with the handle of your server.

For example




For our server.

Step 4

Include the following lines in the server_config clause:

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

Sample "config.dct"


"hdl_http_config" = {
"bind_address" = ""
"num_threads" = "15"
"bind_port" = "8000"
"backlog" = "5"
"log_accesses" = "no"

"server_type" = "server"
"hdl_udp_config" = {
"bind_address" = ""
"num_threads" = "15"
"bind_port" = "2641"
"log_accesses" = "no"

"hdl_tcp_config" = {
"bind_address" = ""
"num_threads" = "15"
"bind_port" = "2641"
"backlog" = "5"
"log_accesses" = "no"

"log_save_config" = {
"log_save_interval" = "Weekly"

"no_udp_resolution" = "n"
"interfaces" = (

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

"replication_admins" = (

"max_session_time" = "86400000"
"this_server_id" = "1"
"max_auth_time" = "60000"
"backup_admins" = (

"case_sensitive" = "no"


Step 5 - Update DSpace config file

Edit the following file:

nano $HOME/source/

For older versions of DSpace, please modify the following file;

nano $HOME/source/dspace/config/dspace.cfg

Update the handle prefix parameter with the handle number assigned to you as follows:

handle.prefix = XXXXXX

Replace the XXXXXX with your handle number. For example in our case, the line reads handle.prefix = 10019.1

Step 6 - Rebuild DSpace

Rebuild the DSpace webapps using the custom rebuild script.

Step 7 - Update old handle prefixes to new registered prefixes

If you need to update the handle prefix on items created before the registration process you can run the $HOME/bin/dspace update-handle-prefix 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:

$HOME/bin/dspace update-handle-prefix 123456789 46664

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

Step 8 - Firewall Ports

This is not optional for a working handle server, it is mandatory.


Open ports 8000 and 2641 for internet access by the handle server on your local server AND on the campus firewall.

Please speak to your campus network administrator about these ports.

Ports 8000 and 2641 must be opened to listen via UDP AND TCP to the handle server:

Check the following links:

  1. Check the handle server firewall notes:
  2. Check the local server firewall page to open the ports on your server.

Please check the following link for an example of local server handle resolution;

Type in the following handle to see what happens.


Step 9 - Java environment

Click on the heading above to prepare a suitable Java environment for the Java handle server.

Step 10 - Start handle server automatically

The handle server is only started during a boot up of the server.
This is to prevent too many instances of the server running at the same time.
On a test server, this service is not needed since handles can only be resolved when the server is properly registered.
See steps above.

Type the following to start your handle server when the server boots up:

sudo nano /etc/rc.local

Copy and paste the following into a blank space in the file before the "exit" statement:


Step 11 - Check for correct operation

Reboot your DSpace server to check that the handle server will start-up when the server is rebooted.

Then peform the following tests and checks.

Listening Ports

First we check to see if the local handle server is actually listening on ports 2641 and 8000.

Type the following:

sudo netstat -tlnp | grep 2641
sudo netstat -tlnp | grep 8000

See example results below.

 tcp6       0      0      :::*                    LISTEN      2055/java
 tcp6       0      0      :::*                    LISTEN      2055/java

If the ports are listening, then check the firewall page to see if the ports are correctly firewalled on the local server.

Check server from off-campus

If you are sure the local server is listening on the corrects ports and that the local server firewall is ok, then check from off-campus, that your handle server can process requests on the following port:


For example:

If the above fails, check the campus firewall ports are open and the local server ports, see step 8 above for more off-campus ports information, then try checking the following.

Handle service

Type the following to see if the local handle service is running:
(Only one instance must be running - check the log file)

sudo ps ax | grep handle

See sample output below.

dspace@ar1:~/handle-server$ sudo ps ax | grep handle
 4953 ?        Sl     0:04 java -Djava.awt.headless=true >>> etc..

Notice that there is a process id assigned (PID). There should only be one PID.

Handle config

After the reboot and after the handle server has registered itself, there should be the following file.

sudo ls -l /root/.handle/root_info

Handle log

If not, check the error logs.

nano $HOME/handle-server/error.log

Rebuild config

Rebuild the config by typing.

$HOME/bin/dspace make-handle-config $HOME/handle-server

Start service manually

Type the following to start the server manually.

sudo $HOME/bin/start-handle-server

Example listing of files in "/home/dspace/handle-server" folder

See below.

dspace@ar1:~/handle-server$ ls -l
total 116
-rw-r--r-- 1 root root  2584 Jul 15 13:07 access.log-20140713
-rwxrwxrwx 1 root root   335 Dec 10  2009 admpriv.bin
-rwxrwxrwx 1 root root   440 Dec 10  2009 admpub.bin
-rw-r--r-- 1 root root 16402 Jul 15 13:18 cache.jdb
-rw-r--r-- 1 root root   894 Jul 15 13:18 config.dct
-rwxrwxrwx 1 root root    81 Jul 15 13:11 contactdata.dct
-rw-r--r-- 1 root root     0 Jul 15 12:28 dbtxns.log
-rw-r--r-- 1 root root   846 Jul 15 13:13 error.log
-rw-r--r-- 1 root root  1353 Jul 15 13:22 error.log-20140713
-rw-r--r-- 1 root root 40018 Jul 15 12:28 handles.jdb
-rw-r--r-- 1 root root  8018 Jul 15 12:28 nas.jdb
-rwxrwxrwx 1 root root   335 Dec 10  2009 privkey.bin
-rwxrwxrwx 1 root root   440 Dec 10  2009 pubkey.bin
-rwxrwxrwx 1 root root  1575 Jul 15 13:11
-rwxrwxrwx 1 root root   548 Jul 15 13:11 siteinfo.bin
drwxrwxrwx 2 root root  4096 Jul 15 13:18 txns

YouTube Video


DSpace Documentation