Handle.Net Registry Support

DSpace comes with support for CNRI's Handle.Net Registry (HNR).  This feature is completely optional, as DSpace functions the same with or without using a Handle Server/Registry. 

A few things to keep in mind:

• You'll notice that while you've been playing around with a test server, DSpace has apparently been creating (fake) handles for you looking like hdl:123456789/24 and so forth. These aren't really Handles, since the global Handle system doesn't actually know about them, and lots of other DSpace test installs will have created the same IDs. They're only really Handles once you've registered a prefix with CNRI (see below) and have correctly set up the Handle server included in the DSpace distribution. This Handle server communicates with the rest of the global Handle infrastructure so that anyone that understands Handles can find the Handles your DSpace has created.
• If you want to use the Handle system, you'll need to set up a Handle server. One is included with DSpace.
• If you want to use the Handle system, you'll need to obtain a Handle prefix from the central CNRI Handle site. This requires a small yearly fee to CNRI
• Again, all of this is completely optional. But, the key benefit is that it provides you with persistent, permanent URLs (of the form https://hdl.handle.net/[prefix]/[suffix]) for every object within your DSpace site.  Those persistent URLs may be useful for citations or even during upgrades/migrations, as DSpace + Handle.Net ensures that these URLs always go to the right object, even if your site's main URL changes.

A Handle server runs as a separate process that receives TCP requests from other Handle servers, and issues resolution requests to a global server or servers if a Handle entered locally does not correspond to some local content. The Handle protocol is based on TCP, so it will need to be installed on a server that can send and receive TCP on port 2641.

You can either use a Handle server running on the same machine as DSpace, or you can install it on a separate machine. Installing it on the same machine is a little bit easier.  If you install it on a separate machine, you can use one Handle server for more than one DSpace installation.

To install your Handle resolver on the host where DSpace runs

1. To configure your DSpace installation to run the handle server, run the following command:

   [dspace]/bin/make-handle-config

   1. If you are using Windows, the proper command is:

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

      Ensure that [dspace]/handle-server matches whatever you have in dspace.cfg for the handle.dir property. You will need to answer a series of qestions to configure the server. For the most part, you can use the default options, except you should choose to not  encrypt your certificates when prompted.

2. Edit the resulting [dspace]/handle-server/config.dct file to include the following lines in the "server_config"clause:

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

   This tells the Handle server to get information about individual Handles from the DSpace code and to disable transaction replication. If you used the make-handle-config script, these should already be set in your config.dct file.

3. Once the configuration file has been generated, you will need to go to https://hdl.handle.net/4263537/5014 to upload the generated sitebndl.zip file. The upload page will ask you for your contact information. An administrator will then create the naming authority/prefix on the root service (known as the Global Handle Registry), and notify you when this has been completed. You will not be able to continue the handle server installation until you receive further information concerning your naming authority.
4. When CNRI has sent you your naming authority prefix, you will need to edit the config.dct file. The file will be found in /[dspace]/handle-server. Look for "300:0.NA/123456789". Replace 123456789 with the assigned naming authority prefix sent to you.  Also change the value of handle.prefix in [dspace]/config/local.cfg from "123456789" to your assigned naming authority prefix, so that DSpace will use that prefix in assigning new Handles.

5. Now start your handle server (as the dspace user):

   [dspace]/bin/start-handle-server

   1. If you are using Windows, there is a corresponding 'start-handle-server.bat' script:

      [dspace]/bin/start-handle-server.bat
      

Note that since the DSpace code manages individual Handles, administrative operations such as Handle creation and modification aren't supported by DSpace's Handle server.

To install a Handle resolver on a separate machine

The Handle server you use must be dedicated to resolve Handles from DSpace. You cannot use a Handle server that is in use with other software already. You can use CNRI's Handle Software -- all you have to do is to add to it a plugin that is provided by DSpace. The following instructions were tested with CNRI's Handle software version 9.1.0. You can do the following steps on another machine than the machine DSpace runs on, but you have to copy some files from the machine on which DSpace is installed.

1. Set the following two configuration properties for every DSpace backend that your are running:

   DSpace backend configuration to activate the endpoints used by the remote handle resolver

   handle.remote-resolver.enabled = true
   handle.hide.listhandles = false

2. Download the CNRI Handle Software: http:s//www.handle.net/download.html. In the tarball you'll find an README.txt with installation instructions -- follow it.
3. After installing the CNRI Handle Software you should have two directories: once that contains the CNRI software and one that contains the configuration of you local Handle Server. For the rest of this instruction we assume that the directory containing the CNRI Software is /hs/handle-9.1.0 and the directory containing the configuration of your local server is /hs/srv_1.  (We use the same paths here as CNRIs README.txt.)
4. Download the plugin from https://github.com/DSpace/Remote-Handle-Resolver/releases.  Select a release.  You can get the source and build it yourself, or just use the JAR file included in the release.  In either case, once you have a dspace-remote-handle-resolver-VERSION.jar, copy it to the directory containing the CNRI software (/hs/handle-9.1.0/lib). 
5. Create the directory /hs/srv_1/logs.

6. Create the following two files in /hs/srv_1.

   log4j-handle-plugin.properties

   log4j.rootCategory=INFO, A1
   log4j.appender.A1=org.apache.log4j.DailyRollingFileAppender
   log4j.appender.A1.File=/hs/srv_1/logs/handle-plugin.log
   log4j.appender.A1.DatePattern= '.' yyyy-MM-dd
   log4j.appender.A1.layout=org.apache.log4j.PatternLayout
   log4j.appender.A1.layout.ConversionPattern=%d %-5p %c @ %m%n
   log4j.logger.org.apache.axis.handlers.http.HTTPAuthHandler=INFO

   Change the path in the third line, if necessary. It must point to the DSpace 7 Rest API (as configured in $dspace.server.url).

   handle-dspace-plugin.cfg

   dspace.handle.endpoint1 = http: //dspace.example.org/server

   If you run more than one DSpace Installation, you may add more DSpace Endpoints.  Just increase the number at the end of the key for each:  endpoint2, endpoint3....

7. Edit the file /hs/srv_1/config.dct to include the following lines in the " server_config" clause:

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

8. Edit /hs/handle-9.1.0/bin/hdl:
   1. Find a line that contains exec java ... net.handle.server.Main ...
   2. Add "-Dlog4j.configuration=file:///hs/srv_1/log4j-handle-plugin.properties -Ddspace.handle.plugin.configuration=/hs/srv_1/handle-dspace-plugin.cfg" right in front of net.handle.server.Main.
9. If your handle server is running, restart it.

Please note: The Handle Server will only start if it is able to connect to at least one running DSpace Installation. It only resolves the handles of the DSpace Installations that were running when it was started.

To install a Handle resolver on a separate machine using template handles

Instead of using the described plugin above, you can configure a Handle server (version 8+) to resolve handles based on a template. Template handle require less configuration than the plugin, and do not require an additional download. However, there are two things to keep in mind when using template handles:

1. Handles that don't exist will still generate a Handle record with a URL, even though resolving that URL will show an error page.
2. Handle records can only be generated based on the handle and the template. If you need to look up information in DSpace in or to geneate the correct url for a given handle, you will need to use a storage plugin instead.

The Handle server you use must be dedicated to resolve Handles from DSpace. You cannot use a Handle server that is in use with other software already. The following instructions were tested with CNRI's Handle software version 9.1.0.

1. Download the CNRI Handle Software: https://www.handle.net/download.html.
2. In the tarball you'll find an README.txt with installation instructions. Follow the directions to install and configure your Handle server. Importantly, make sure your prefixes are set correctly in the "auto_homed_prefixes" setting.

3. Edit the server's config.dct file to include the following line in the " server_config" clause:

   "namespace" = "<namespace><template delimiter'/'><value type='URL' index='1' data='https://demo.dspace.org/handle/${handle}'/></template></namespace>"

   
   

   In the "namespace" section, replace "https://demo.dspace.org/handle/" with the url endpoint for your DSpace server. The "${handle}" part of the template will be replaced with the full handle to be resolved.

4. If your handle server is running, restart it.

This configuration is a minimal example of how to configure template handles for DSpace. For more details about configuring template handles, see the Handle Technical Manual, Chapter 11 (PDF download).

Updating Existing Handle Prefixes

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

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

This script 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.