FAQs
1. I'm using version 7.3 of the handle software. Should I upgrade to version 8.1?
Yes. We recommend you upgrade to the latest version.
2. I have a five digit prefix and I have prepaid the annual service fee. Do I have to get a prefix that begins with 20.500 in order to use version 8.1? Is there a new license and service agreement?
Your allotted prefix under the previous Handle System Service Agreement (HSSA) will stay the same. You may continue to request derived prefixes for these older prefixes. New prefix allotments will require agreement to the terms of a new License and a new Service Agreement in order to use the new software, but there are no additional fees required to upgrade.
3. May I request a temporary prefix for experimental purposes?
Upon request, temporary prefixes may be allotted for use in evaluating and testing the technology for an agreed trial period. Any registration or annual fees normally due would be waived for the trial period.
4. I want a lot of prefixes. Do I have to pay for each one?
HNR charges a $50 registration fee per prefix of the form 20.500.xxxxx that is only paid once, no matter how many derived prefixes of the form 20.500.xxxxx.x are created under that allotted prefix. Thus, one prefix would cost $50 to register and $50 per year to maintain. One prefix, plus four derived prefixes (e.g. 20.500.12345.6), would cost $50 to register and $250 per year to maintain. Derived prefixes may be requested at any time, as the need arises. If a large number of derived prefixes are resolvable only at a single local handle service, a special agreement is possible to arrange. The cost of registration of large numbers of prefixes is open to negotiation. Contact hdladmin@cnri.reston.va.us.
5. What is the simplest handle service installation configuration I can have?
The simplest service configuration is one site with one handle server. The installation comes with a hdl-setup script in the /bin which will prompt you to configure your handle service. The next simplest configurations consist of (1) one site with multiple handle servers at that site, or (2) one site with a single handler server and multiple secondary sites for replication and backup.
6. Do you have recommendations for hardware specifications for running a handle server?
Handle.Net software is Java-based and is run on Linux, Mac, and Windows hardware, among others. Handle server requirements are generally very low. CNRI has successfully run large and heavily used production servers on inexpensive commodity hardware such as Mac minis, as well as the smallest offerings on cloud services such as Amazon EC2 t2.micro instances. The CPU is generally never a bottleneck for handle servers; however, increased memory, and also faster disk I/O, can improve performance.
7. What are the config.dct, siteinfo.bin and the key files?
The config.dct is a file that contains all the configuration settings for a handle server, such as its IP address and server administration handles. It is located in your server directory. The siteinfo.bin file is generated when you run the hdl-setup script to configure your handle server. It contains the specific handle server configuration settings in binary format. Public/private key files are also generated when you run the hdl-setup script. They are initially used in conjunction with your allotted prefix for authentication but this can be changed later if desired. For instance, you can create an admin handle with a secret key.
8. What version of Java™ should I use?
Java version 6 is the minimum, Java version 8 is recommended. The servlets require the Java Servlet library which is available from Java.com in the Java Enterprise Edition (J2EE), or via downloading a servlet engine such as Apache Tomcat.
9. Can I install a handle service behind a firewall?
The server should be installed on a machine with an Internet presence, preferably outside an organization's firewall. If that is not possible, then ports 2641 and 8000 on the firewall need to be open to incoming and outgoing traffic. This is necessary because the handle clients, including but not limited to the handle web proxies, must be able to talk to your local server. Many networks are configured so that a server might have a different IP address for internal and external access. These addresses are typically in the ranges 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. If this is the case, the external IP address should be used when running the Setup/install so it will be in the prefix record. The internal IP address should be used in the the server's config.dct file.
If your handle service binds to LOCAL-IP, which a firewall/NAT uses to connect to PUBLIC-IP, and you have clients inside the firewall, then the possible answers are:
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. Note that SOCKS and HTTP proxy firewalls are not yet supported by the handle server.
10. How do I start/restart and stop my handle server?
To start the server use the following command from your hs/bin directory:
./hdl-server your_svr_dir
Handle servers create a file called "delete_this_to_stop_server". Delete that file and the server shuts down. To use the kill command for unix systems, find the process id and then 'kill process_id'. Windows-specific ways to stop processes will also work.
To restart the server you may have to first remove the lock file that is in your svr/txns directory if the server did not shut down cleanly. Then start the server using the command above.
11. How can I automatically start my handle server at machine start up?
You must store your keys unencrypted in order to do this. You are asked whether you want to store your keys encrypted during server installation. Choose "NO". Then create a script to start the handle server, and put that script in the same place as your other startup scripts. If you implement this after your initial installation, be sure to send the new sitebndl.zip file to the Handle.Net Registry Administrator at hdladmin@cnri.reston.va.us. If you wish to retain your keys encrypted within the system, and choose "YES", you will have to manually restart the handle server at machine start up.
12. We're moving our handle service to new server hardware. Can you tell me what I need to do?
For versions 7.x and higher, copy the entire bdbje subdirectory to the new server assuming you don't want to have to recreate your existing handles. Run the hdl-setup script again, then send the new sitebndl to hdladmin@cnri.reston.va.us, and your prefix will be updated with the new service information. The final step will be for you to home your prefix on the new server as described in the README.txt file. In your email to hdladmin@cnri.reston.va.us, include your name, organization name, and the previously allotted prefix that needs to be updated, along with the new sitebndl.zip file.
13. If I want to permanently shut down my handle server and stop using handles, what do I need to do?
Please notify the HNR Administrator via email to hdladmin@cnri.reston.va.us if you plan to shut down your server permanently.
14. Besides SQL databases, what other databases have been tried with the handle server?
CNRI uses Berkeley DB for its major handle installations, and if you plan to have over a million handles it is best to use Berkeley DB instead of the Java jdb file, and to use a multiple server implementation. The current version includes code that helps you connect the Berkeley DB to your handle server instance. Support for other databases is possible by providing a Java class to implement the net.handle.hdllib.HandleStorage interface to store and retrieve handles. You can also use a relational database as your store instead of the one provided in the distribution. Instructions are provided in the distribution, but the instructions assume you are knowledgeable about the relational database you intend to use.
15. If I'm using a custom database (other than the one that comes in the distribution), can I still do replication?
Yes and no. If the custom database is only modified using the handle admin tools included in the distribution, then replication/mirroring can also be done using the handle protocol. However, if an administrator make changes directly to the back-end database (for example, updating handle values using SQL) then replication using the handle protocol will not work, and mirroring, if it is required, will have to be done via a separate mechanism specific to that database.
16. What are the potential security risks that could arise from running a local handle service, and opening ports 8000 and 2641 to all incoming and outgoing requests? Does my handle server have to run on ports 2641 and 8000?
Security risks are not likely, because handle servers provide a limited handle lookup and administration service that is constrained to the handle database. There have been no vulnerabilities found or security-related bugs reported in the software in over 15 years. Port 2641 is the ICANN registered handle port. You may choose which ports you would like your handle server to run on during the installation but remember that no other processes, i.e., a web server, can be running on the same ports as your handle server.
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 https://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:
https://proxyurl/handle?parameter
The syntax for multiple parameters is:
https://proxyurl/handle?parameter¶meter
There are no quotes around parameter values. Note that appended URL fragments don't have anything to do with the server.
Examples:
https://hdl.handle.net/1234/56?index=300
returns the value found at index 300 in the handle record for as34/56.
https://hdl.handle.net/1234/56?urlappend=https://someurl.com
or
https://hdl.handle.net/1234/56?urlappend=/mylocation/file.html
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 /.
https://hdl.handle.net/1234/56?auth
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.
https://hdl.handle.net/1234/56?noredirect
prevents the web browser from being redirected, even if a URL is found.
https://hdl.handle.net/1234/56?ignore_aliases
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), change the amount of memory available to the Java process. In recent versions of the Handle software this is done by editing "bin/hdl"; replace "-Xmx200M" with "-Xmx2G" or some amount comfortably less than the amount of memory on your server.
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.
29. Is Handle.Net software vulnerable to "log4shell" (CVE-2021-44228)?
Handle.Net software has no dependency on log4j so is not vulnerable to "log4shell" (CVE-2021-44228).
September 2, 2015