SUNScholar/Handle Server

Back to After Installation Tasks

Back to Digital Object Identifiers

PLEASE NOTE:
After an upgrade from DSpace 1.8.2 to 3.2, the following software bug appeared. https://jira.duraspace.org/browse/DS-1536

Introduction


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: 10019.1/86160

Step 1 - Register as handle server
Visit the following web sites to register as handle server;
 * http://www.handle.net
 * http://www.handle.net/prefix.html

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: $HOME/handle-server/sitebndl.zip

to

hdladmin@cnri.reston.va.us

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 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 300:0.NA/123456789 Became 300:0.NA/10019.1 For our http://scholar.sun.ac.za 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" = "146.232.66.15" "num_threads" = "15" "bind_port" = "8000" "backlog" = "5" "log_accesses" = "no" }

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

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

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

"no_udp_resolution" = "n" "interfaces" = ( "hdl_udp" "hdl_tcp" "hdl_http" )

"server_config" = { "storage_type" = "CUSTOM" "storage_class" = "org.dspace.handle.HandlePlugin" "server_admins" = ( "300:0.NA/10019.1" )

"replication_admins" = ( "300:0.NA/10019.1" )

"max_session_time" = "86400000" "this_server_id" = "1" "max_auth_time" = "60000" "backup_admins" = ( "300:0.NA/10019.1" )

"case_sensitive" = "no" }

}

Step 5 - Update DSpace config file
Edit the following file:

nano $HOME//build.properties For older versions of DSpace, please modify the following file; nano $HOME//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 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.

PLEASE NOTE:
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: http://hdl.handle.net.

Check the following links:
 * 1) Check the handle server firewall notes: http://www.handle.net/support.html#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; http://scholar.sun.ac.za:8000 Type in the following handle to see what happens. 10019.1/79321

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: /home/dspace/bin/start-handle-server

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 146.232.66.15:2641      :::*                    LISTEN      2055/java tcp6      0      0 146.232.66.15:8000      :::*                    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: 8000

For example: http://scholar.sun.ac.za:8000

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 sitebndl.zip -rwxrwxrwx 1 root root  548 Jul 15 13:11 siteinfo.bin drwxrwxrwx 2 root root 4096 Jul 15 13:18 txns

YouTube Video
https://www.youtube.com/watch?v=xB82F4vz03Y

DSpace Documentation

 * https://wiki.duraspace.org/display/DSDOC5x/Installing+DSpace#InstallingDSpace-TheHandleServer
 * https://wiki.duraspace.org/display/DSDOC4x/Installing+DSpace#InstallingDSpace-TheHandleServer
 * https://wiki.duraspace.org/display/DSDOC3x/Installation#Installation-TheHandleServer
 * http://wiki.datadryad.org/Handle_Server_Technology

Handle.Net

 * http://www.handle.net/documentation.html
 * http://handle.net/tech_manual/Handle_Technical_Manual.pdf
 * http://www.handle.net/tech_manual.html
 * http://www.cnri.reston.va.us/mailman/listinfo/handle-info