Handle FAQs - 2


 17. My IT department wants to limit TCP and UDP handle resolution requests through our firewall to specific outside machines by IP address. Can we do that?

Handles resolve via a public resolution system meant to be available without restrictions. We recommend you not limit requests by IP because the addresses for the required services and the hdl.handle.net Proxy will change over time. Future plans call for placing proxy servers in many more locations around the world. Also, if you restrict, then someone running a native handle client can't resolve your handles.

18. I opened both ports (2641 and 8000) for my handle server, and handles resolve from outside of our firewall, but users inside the firewall cannot resolve them. What can I do?

For inside users, you need to map the external IP address of the server to the internal IP address through which the users should access the server. This can be done by putting the file "local_addresses" in the .handle folder. This local_addresses file should contain the IP address mapping like this:

outsideaddr1    insideaddr1

outsideaddr2    insideaddr2

The outside (public) address goes first, then a tab, then the inside address. In version 8.1 a whitespace can be used instead of a tab.

19. When I sent my initial request for a prefix I used port 8380, which is my Tomcat server port for DSpace. Does the handle server use its own port, 8000?

Yes, the handle server uses its own ports. You will need to re-run the hdl-setup script again to make the change. This not only creates the sitebndl.zip file that the HNR Administrator uses, but also the config.dct file and the siteinfo.bin file in your server directory. These all have to match, so running the hdl-setup script again ensures that everything that needs to be updated gets updated.

20. How do I create handles? And is there a way for me to administer my handles using a web browser?

You can use the Handle Tool that comes with the server software to create handles and the associated handle records. There are graphical utilities for performing handle operations such as creation, deletion and editing, and other important administrative functions. Batch operations are described in the documentation, and the distribution includes a Browser Admin Client. Included in the handle server distribution are servlets (located in the "net.handle.apps.admin_servlets" package) that will enable you to administer over the web handles that you have authorization to administer. Using the administration servlet you can create, edit, and delete handles one at a time or in batches, and also list handles under a given prefix. More information on the web interface for handle administration is available in the Technical Manual.


21. How do I administer (create/delete/edit) handles on a machine other than the machine my handle server is running on?

You will need administrative privileges on such other machines. Copy the hdl-admintool file (from your server download package) to the new machine, then start the Handle Tool. The command to start the tool is provided in the README.txt file.

22. Is it possible to append parameters to a proxy handle resolution request, and if so, what is the syntax and what parameters are accepted?

There are several parameters recognized by the proxy server, both the server that CNRI is currently running at http://hdl.handle.net, and the server bundled with the reference implementation. The proxy currently supports index, type, auth, noredirect, ignore_aliases, and urlappend.

The syntax for one parameter is:


The syntax for multiple parameters is:


There are no quotes around parameter values. Note that appended URL fragments don't have anything to do with the server.



returns the value found at index 300 in the handle record for as34/56.




assumes the value to be returned is a URL redirect. The server appends the data following urlappend= to the end of the redirect string. If there is no redirect, the urlappend parameter is ignored. Note that there are no assumptions made by urlappend, so, for example, if you want a / to separate the url and your append string, the append string has to start with a /.


forces the proxy to bypass the cache and go directly to the responsible server, and then refresh the cache with the data for that handle.


prevents the web browser from being redirected, even if a URL is found.


means that if the handle has an HS_ALIAS value, normally the proxy would resolve the alias and return it instead of the specified handle, but appending ignore_aliases will let you see what is in the handle (i.e. the HS_ALIAS value).


23. What do I do if I get a Java™ out-of-memory error?

If you get an out-of-memory error (or would like to increase the amount of memory that the server can use), add the "-mx128m" argument when running java/jre. In fact, we recommend increasing the amount of memory available to Java to allow Java and the server to use up to 128 megabytes of virtual memory, if necessary. Alternatively, the config.dct file can be edited to cut down on the amount of memory used by changing the number of threads allocated for each listener.

24. When I resolve my handles I get a 'cannot connect' error. What does this mean?

This means that your handle server is not responding to client requests. Make sure your handle server is running. If it is running, then check that ports 2641 and 8000 in your firewall are open to ALL incoming or outgoing requests, and make sure that the IP address in the prefix record is correct.

25. What does the error "GOT_EXPIRED_MESSAGE" mean and what should I do?

That error message means that the time setting is incorrect, by at least 12 hours, on the computer on which the client or server is running. You should check and reset the system clock.

26. What does the error message "MISSING_OR_INVALID_SIGNATURE, unable to verify signature, Verification failed" mean?

The server's private key does not match the public key that the client has for it. You should generate a new public/private key pair.

27. What does the error message "Message_Format_Error: Invalid message length: 143048265" mean?

This error means that an invalid message was either sent to, or received by, a handle client or a handle server. For example, it would occur if a UDP or TCP request was sent to a handle server's HTTP interface.

28. How do I change my key passphrase?

If you want to change your passphrase you can use the hdl-keyutil found in your server bin directory. You will need to know the current passphrase to run the command successfully.