Difference between revisions of "SUNScholar/Handle Server"

From Libopedia
Jump to navigation Jump to search
m (1 revision)
(No difference)

Revision as of 21:16, 14 August 2010

Step 1 - Register as handle server

Visit: http://www.handle.net and http://www.handle.net/service_agreement.html to register to become a handle server.

Step 2 - Prepare initial handle request

Type the following in a terminal on your server as the "dspace" user:


See below for an example of the questions answered where all defaults were selected:

Will this be a caching server or a regular handle server?

  1 - regular Handle Server (Recommended)
  2 - caching Handle Server

Please choose 1 or 2 and press Enter [1]: 
Will this be a "primary" server (ie, not a mirror of another server)?(y/n) [y]: y

Through what IP address will this server be accessible? (Domain names are OK) []: 

Enter the (TCP/UDP) port number this server will listen to [2641]: 

What port number will the HTTP interface be listening to? [8000]: 

Would you like to log all accesses to this server?(y/n) [n]: y

Please indicate whether log files should be automatically
rotated, and if so, how often.

("N" (Never), "M" (Monthly), "W" (Weekly), or "D" (Daily))? [Never] : W

Please select a weekday for auto-saves and restarts
("Sun", "Mon", "Tue", "Wed", "Thu", "Fri", or "Sat") [Sun]: 

Select a time of day for the saving and restarting (HH:MM:SS)

Enter the full pathname of the directory where saved logs should be stored

Each handle site has a version/serial number assigned
to it.  This is so that a client can tell if a particular
site's configuration has changed since the last time it
accessed a server in the site.  Every time you modify a site
(by changing an IP address, port, or adding a server, etc), 
you should increment the version/serial number for that site.

Enter the version/serial number of this site [1]: 

Please enter a short description of this server/site: ETD for Stellenbosch University

Please enter the name of your organization: Stellenbosch University

Please enter the name of a contact person
for Stellenbosch University (optional) [(none)]: Hilton Gibson

Please enter the telephone number of Hilton Gibson or of Stellenbosch University (optional) [(none)]: +27 21 808 4100

Telephone number contains illegal character '+', please try again.

Please enter the telephone number of Hilton Gibson or of Stellenbosch University (optional) [(none)]: 27 21 808 4100

Please enter the email address of Hilton Gibson or of Stellenbosch University: hgibson@sun.ac.za

The Handle System can communicate via UDP and/or TCP sockets.
Since UDP messages are blocked by many network firewalls, you may
want to disable UDP services if you are behind such a firewall.

  Would you like to disable UDP services?(y/n) [n]:
Server keys already exist, do you want to create new ones? (y/n) [n]: 

Administrator keys already exist, do you want to create new ones? (y/n) [n]: 
Generating site info record...

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.

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

Open the handle config file.

nano /home/dspace/handle-server/config.dct

Replace all mention of:


with the handle number as sent to you in the email from the Handle admin people.

Step 3

Find the following lines:

"server_config" = {
"server_admins" = (

Then add the following:

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

So it looks like this afterwards:

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

Save the file.

Step 5 - Update DSpace config file

Step 1

Open the Dspace config file as follows:

nano /home/dspace/dspace-1.5.2-src-release/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

Step 2

Update the handle server location folder parameter:

handle.dir = /home/dspace/handle-server

Then rebuild your Dspace to use the new handle system.

Step 6 - Update handle prefixes

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

Step 7 - Firewall Ports

Open ports 8000 and 2641 for internet access by the handle server. Check the firewall and security page.

Step 8 - Start handle server

Type the following to start your server during reboots:

sudo nano /etc/rc.local

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


Save the file and reboot your Dspace server.