Why would I want to use the Handle System?
There are many reasons you might want to use the Handle System, but one simple one is that you have information and other resources represented in digital form, sometimes called digital content, that you want users to access via the Internet and you plan to keep that content available over long periods of time. If the content's location is likely to have to change during that time, then you need a resolution system like the Handle System. You would assign your digital content unique identifiers, not just identify the objects by their locations. A location a given URL, for example is not a persistent identifier if the content moves to another location. The ability to change locations without changing names also applies to ownership. You can move or sell an object from one owner to another and still use the same identifier, which is very difficult to do using domain names that are required in URLs. Other reasons to use the Handle System are more technical, e.g., secure resolution and/or multiple resolution, for which we recommend you read the technical documentation found on this site.
Is the Handle System considered a software application?
The Handle System is implemented in software, but it is not intended to be an "end user" product. Specifically, it is not an off-the-shelf software application for stand-alone use. It is considered an infrastructure component, used to identify digital resources whose metadata, such as location information, needs to be updated from time to time and obtained by rapid resolution on the net.
You describe the Handle System as a "resolution system". What do you mean by "resolution"? And what is the difference between "resolving" a handle and "querying" a search engine, such as Google?
The difference might be best explained by the difference between the results of a resolution vs. a query. For the Handle System we use "resolution" in the networking sense to take an identifier and convert it into a set of current state information known as metadata. This is a capability that goes significantly beyond simple resolution mechanisms such as the Domain Name System (DNS) or the Address Resolution Protocol (ARP). A distinction with the normal use of the term "query" would be that querying is often less deterministic. When querying a search engine, you could get no answer to a query, or you could get multiple answers and have to decide among them. Or you might get the same answer from two different questions. Or you might get different answers depending on who you asked. Two Internet search engines, for example, are unlikely to give you the same set of answers.
How does the Handle System compare to LDAP?
At the infrastructure level, the Handle System allows individual namespaces to be registered and later discovered by any application over the Internet. Namespaces registered under the Handle System are unique, and queries will always be directed to the responsible handle server for resolution. An LDAP server typically runs in isolation, with service referrals from one namespace to another performed at the peer level when available.
At the individual server level, handle servers are more efficient than LDAP servers for name-attribute resolution. Handle servers have better security mechanisms (e.g., service integrity, data confidentiality and authenticity etc.) for name-attribute binding in a distributed environment. LDAP severs, on the other hand, provide attribute-based searching, a capability that handle servers don't provide by themselves. For attribute based searching, One might use a dedicated search engine (e.g., Lucene/Google) running as a separate process against the underlying handle data stores. This off-loads the searching function from the name server, making the name server more efficient. (RFC 3650, Section 6.2 has a brief discussion of the relationship between the Handle System and LDAP and how they can work together in this regard.)
Both the Handle system and LDAP have built-in mechanisms for replication/mirroring, but neither support multiple primaries at this time. The Handle System is more scalable because each mirror site may consist of a cluster of servers (splitting the service load), whereas each LDAP mirror site has a single server. (RFC 3650, section 4, has more information on mirroring.)
In at least one project (see "ADL-R: The First Instance of a CORDRA Registry", D-Lib Magazine, February 2006) an existing LDAP installation has been used as a front end authentication system to a handle-based authorization system.
Why doesn't the Handle System use DNS?
The Handle System doesn't need to use DNS. It is an independent naming system that should not be dependent on another system for performance, or any other reason. However, handle records may contain DNS entries, at the discretion of the owner of the record. See the "Handle System and DNS" chapter of HANDLE.NET System Fundamentals for additional information on this.
What kind of authentication does the Handle System use? What will make my handle service, and also my identifiers, secure?
The Handle System uses a combination of passwords and public/private key pairs to authenticate administrators. Individual administrators are identified by "admin handles" which are used in the process of authenticating the administrator to the Handle System. A set of permissions is associated with each admin handle governing that individual administrator's permission to create and modify handles. You will find more information about Handle System administration and authentication in the Technical Manual.
How does the Handle System Scale?
The system scales over two dimensions: quantity of requests and quantity of data. If there are typically more requests per unit time than a given server can handle, the load on that server can be reduced by spreading it across more servers at that particular site. If a site becomes overloaded, one or more "secondary" sites may be used to replicate the primary site and thus to offload it. If a single namespace becomes too large to be housed on a single server, it can be distributed across multiple servers that make up a site. If a site consists of multiple servers, the handles at that site are evenly distributed among the servers based on a hashing algorithm.
How can the Global Handle Registry cope with different loads?
The system is designed so that clients and local resolvers may cache the referral information provided by the GHS and not interact with the GHS very often.
Can handles map to things other than URLs?
Yes. Every handle is a bundle of type/value pairs (or you can think of it as a distributed database of handle/type/value tuples). A lot of those types are URLs and some systems, like the set of hdl.handle.net proxy servers, are set up to operate on URLs, but you can use any type you like. Some types are administrative in nature (when a handle client talks to the Global Handle Registry it looks for a type of 'service information' that is a piece of structured data telling it all it needs, e.g., IPs, ports, public keys, to talk to the one or more handle servers that know about that prefix) and some are application oriented, such as producing menus associated with each link.
What if I want to use handles but I don't want to run a handle service myself?
You might want to work with another organization already using the Handle System. For example, in the area of intellectual property, the Digital Object Identifier System (DOI) is a widely used implementation of the Handle System with tens of millions of Digital Object Identifiers (DOIs) in use. The DOI system is made available by the International DOI Foundation (IDF), which offers policies and the added value of being a robust, established, and experienced organization. Contact the Handle System Administrator at firstname.lastname@example.org for information about other organizations using the Handle System.
Can I try out the Handle System experimentally before committing to its use?
There are really two questions here. As a user, anyone is free to simply make use of the system to resolve handles. But a user who wishes to install and operate a handle service must enter into a Service Agreement in order to obtain a prefix from the Handle System Administrator. However, upon request, temporary prefixes may be allotted for use in evaluating and testing the technology for an agreed trial period. In such cases, any registration or annual fees normally due would be waived for the trial period.
How is Handle System software licensed?
The HANDLE.NET software has a public license, similar to an open source license, in order to enable broader use of the technology. During the development phase of the software, most use of the software was restricted to education, research and experimental purposes, and for R&D using a given prefix. If you are using handle software made available under the earlier license, are no longer using the Handle System exclusively for such purposes, or if your planned use of the system will change, then you should enter into the new license agreement.
Why is there a Handle System Service Agreement?
While there is no cost associated with the HANDLE.NET software itself, a fee structure for providing resolution services is necessary to cover operational costs for running the Global Handle Registry (GHR). This helps to insure the overall integrity of the Handle System. (See Handle System Registration for more information. ) The agreement is also meant to ensure that prefixes are used in a manner that does not disrupt or interfere with the overall operation of the Handle System.
What's a prefix?
The term "prefix" replaces the older term "naming authority", and both will be found (and can be considered interchangeable) in Handle System documentation and publications. A prefix is a globally unique string, allotted by CNRI, which identifies your handle service (and your identifiers) to the Global Handle Registry, and which will be used as the first part, or "prefix", of each of the identifiers you create under that prefix. The prefix string, combined by a slash with another unique string, locally generated by the user and called the "suffix", make up a handle. For example, "4263537/4000" is a handle for the Handle System web site home page. It is defined under the prefix "4263537", and when combined with "4000" becomes a unique identifier for that particular Internet resource . A prefix may be used to create derived prefixes. For example, once the prefix 4263537 has been created, the derived prefix 4263537.1 can be created. Each prefix thus generated is guaranteed to be globally unique within the Handle System. See the Handle System Fundamentals section on handle syntax for more information.
Can I request a specific prefix? Can I have a prefix that uses my corporate name, like a domain name?
No, you cannot request a specific prefix. We have reserved the one, two and three digit prefixes for specific uses (e.g., for countries) and are reserving the remaining unallocated four digit prefixes for future use. Prefixes issued under this license will be five digits or larger. You will be allotted the next allottable numerical prefix. Semantic prefixes are no longer available, but individual applications can map semantic information to prefixes.
I'm a new DSpace user. Do I have to pay for a prefix if I use the HANDLE.NET software?
Yes. Anyone can be a Resolution Service Provider (RSP) and everyone must agree to the terms and pay the appropriate fees.
I'm in the process of setting up an instance of DSpace at my university and need a handle prefix for the DSpace handle server. What do I need to do to obtain one?
Follow the steps in the DSpace documentation that instruct you to run the Simple Setup program, and upload the file to email@example.com via the web form in order to receive your prefix (naming authority). You will need to complete the entire form. See DSpace Documentation on installation for more information on setting up the handle server.
I want a lot of prefixes. Do I have to pay for each one?
The $50 registration fee is only paid once, no matter how many derived prefixes are also created. Thus, one prefix would cost $50 to register and $50 per year to maintain it in the GHR. One prefix, plus four derived prefixes, would cost $50 to register and $250 per year to maintain them in the GHR. Derived prefixes may be requested at any time, as the need arises. In general, these fees go to defray the cost of running the GHR. The costs for registration of large numbers of prefixes are open to negotiation. Contact firstname.lastname@example.org.
If I want to start a business handing out prefixes, or become a consortium and hand out prefixes to my members, what do I do?
The ability for an organization to do this independently and for others in the future will be subject to agreement with CNRI. The policy is currently under development and will be uniformly applied.
I represent a government agency. Do I have to pay for prefixes?
There are no government wide policies concerning handle prefixes. If you believe you are part of an agency that already has a prefix, but you aren't sure, please contact the Handle Administrator at email@example.com for assistance.
Do you have recommendations for hardware specifications for running a handle server?
Because scalability is designed into the Handle System, the scalability and efficiency of each server is less important than might otherwise be the case. Our most recent benchmarks were made using the new Berkeley DB Java Edition database on a PowerBook G4 laptop with 1.5Ghz G4 CPU, 1 GB DDR RAM, Mac OS X 10.4. In this configuration, the client and server were both on the same machine to eliminate network delay. The best run times with 30 parallel threads, each performing 10,000 queries were:
Who should install my handle server? Is it as simple as installing programs on a PC?
Handle servers should be installed by system administrators. It is very much like installing a Web server.
What version of Java should I use?
The client and server software need Java 5.0 or higher (developer version 1.5.0). 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.
What is the simplest handle service installation configuration I can have?
The simplest service configuration is one site with only one handle server. The installation comes with a "Simple Setup" program which will install your handle service for you. The program creates a handle service configuration with one primary server. The next simplest configuration would consist of either one site and multiple handle servers at that site, or one site with a single handler server and multiple secondary sites for replication and backup.
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 Global Handle Registry 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. There are two likely scenarios of how this might be set up.
For instructions on adding routes under Solaris, *BSD, Linux, and other Unix-like operating systems see the manual pages for
Note that SOCKS and HTTP proxy firewalls are not yet supported by the handle server.
What are the config.dct, siteinfo.bin and the key files?
The config.dct is a file that contains all the configuration settings for your handle server, such as IP address and server administration handles. It is located in your server directory. The siteinfo.bin file is generated when you run the Simple Setup to configure your handle server. It contains your handle server configuration settings in binary format. The public/private key files are also generated when you run the Simple Setup. They are initially used in conjunction with your prefix for authentication. This can be changed later, for instance, you can create an admin handle with a secret key.
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?
The Handle System is a public resolution system meant to be available without restrictions. We recommend you not limit requests by IP because the addresses for the Global Handle Registry and the hdl.handle.net Proxy will change over time. Future plans call for placing proxy servers all over the world. Also, if you restrict, then someone running a native handle client can't resolve your handles.
How do I start/restart and stop my Handle server?
To start the server use the following command from your hs/bin directory:
jre -cp handle.jar net.handle.server.Main your_svr_dir
To stop the server you must use the kill command for unix systems. Find the process id and then 'kill process_id'.
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.
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 System Administrator at firstname.lastname@example.org. 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 setup.
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.
How do I back up my handle database?
Use the backup function available via the Admin Tool. Refer to the Technical Manual.
How do I create handles?
You can use the Handle Tool that comes with the server software. They are graphical utilities for performing handle operations such as creation, deletion and editing, and other important administrative functions. See the Handle Tool User Manual for details.
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 handle.jar file (from your server download package) to the new machine, then run the command to start the Admin Tool (or instead, install and run the Handle Tool included with the distribution that uses Java Web Start). The following example of the command assumes the handle.jar file is in the directory where you are running the command.
jre -cp handle.jar net.handle.apps.gui.hadmin.HandleTool
The command to start the tool is also provided in the install.txt file. If you are a handle administrator and do not intend to run a server, download the server distribution and use the above command to start the Admin Tool. You can ignore the server setup instructions provided in the install.txt file.
What do I do if I want to administer my handles remotely, but I don't want to use the included Handle Tool? Is there any way for me to administer my handles using a web browser?
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.
What are the data types used in handle records? Can I make up my own?
Yes, you can make up your own data types for handle values to define the syntax and semantics of the value data, and the types can be any UTF8 string. The set of types basic to system operation are described in RFC 3651, Section 3.2. If you make up your own data types, there is the potential for conflicts for handle clients that encounter types that are not recognized across the user community. To avoid this, the 0.TYPE prefix has been created as a registry for known types; however, policy for how types should be defined and used is currently under discussion.
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. (If you are running an earlier version of the server software, contact the Handle System Administrator for assistance with upgrading to version 7 before moving to new server hardware.) Run the Simple Setup again, then send the new sitebndl to email@example.com, 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 install.txt file. In your email to firstname.lastname@example.org, include your name, organization name, and the previously allotted prefix that needs to be updated, along with the new sitebndl.zip file.
Does my handle server have to run on ports 2641 and 8000?
No, but 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 (Simple Setup) but remember that no other processes, i.e., a web server, can be running on the same ports as your handle server.
When I sent CNRI 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 Simple Setup again to make the change. This not only creates the sitebndl.zip file that the handle 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 Simple Setup again ensures that everything that needs to be updated gets updated.
I'd like to use a relational database to store my handles instead of the one provided in the distribution. Can I do that?
Yes, you can use a relational database as your store instead of the one provided in the distribution. Instructions are provided in the distribution, and in the Technical Manual, also on web site. The instructions assume you are knowledgeable about the relational database you intend to use.
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 administrators 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.
Besides SQL databases, what other databases have been tried with the handle server?
CNRI uses Berkeley DB for its major handle installations. The current handle server version includes code that helps you connect the Berkeley DB to your handle server instance. See the Technical Manual for information. Support for other databases is possible for anyone who provides a Java class, implementing the net.handle.hdllib.HandleStorage interface, to store and retrieve handles.
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 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.
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.
If I want to permanently shut down my handle server and stop using handles, what do I need to do?
Please notify CNRI via email to email@example.com if you plan to shutdown your server permanently.
Can I download version 6 of the server software?
Yes. See Previous Versions of the HANDLE.NET Software for links to the version 6 downloads, and the Technical Manual.
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?
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:
The outside (public) address goes first, then a tab, then the inside address. The tab is important.
If I expect to have over one million handles in my implementation, will the custom jdb file work?
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. Please see the Technical Manual for instructions for using the Berkeley DB module.
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.
Do you know of any potential security risks that could arise from running a local handle service, and opening ports 8000 and 2641 to all incoming and outgoing requests?
We believe no security risks could be introduced, 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 8 years.
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.
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.
When can I use the HANDLE.NET, HDL.NET and HDL marks?
HANDLE.NET, HDL.NET and HDL are trademarks owned by the Corporation for National Research Initiatives ("CNRI"). You may use the HDL mark when referring to your identifiers and related identifier and/or resolution services using prefixes (or their functional equivalent) that are authorized by CNRI or that are known to the Global Handle Registry, the top level of the Handle System. The marks HANDLE.NET and HDL.NET may only be used when referring to the identifier, registration and/or resolution services offered by CNRI or its authorized trademark licensees. (Note that "Handle System" and "Global Handle Registry" are trademarks owned by the DONA Foundation.)
None of these marks should be used by themselves to refer generically to identifiers for publicly available digital information systems and related identifier, registration and/or resolution services. Rather, they should be used as adjectives to describe the identifier, registration and/or resolution services offered by CNRI or its authorized trademark licensees.
Can I use the HANDLE.NET, HDL.NET or HDL marks for any other purpose?
The marks may only be used as such when referring to services offered by CNRI or its authorized trademark licensees. Using any of these marks to refer to services offered by other parties may result in trademark infringement or other violations of law.
How should the registered marks HANDLE.NET and HDL.NET appear?
These marks should appear in unique stylization, and/or a different color from the other text to highlight their trademark significance. The preferred format is to use all capital letters, or at least initial capital letters.It is federally registered with the United States Patent and Trademark Office. Accordingly, the ® symbol should be used with them, such as "HANDLE.NET® services are available to Internet users around the world".
How should I indicate CNRI's ownership of the registered marks?
At the bottom of the page or the end of the promotional material on which the marks appear you should include the following statement: "HANDLE.NET®is a trademark of the Corporation for National Research Initiatives."
What should I do if I become aware of another's misuse of the HANDLE.NET, HDL.NET or HDL marks?
If you become aware of potential misuse of any of these marks, or if you have any other questions or concerns, please contact the Handle System Administrator at firstname.lastname@example.org.