CNRI Digital Object Repository

Setup and configuration of a DO Repository server


Server Initialization

  1. Extract the DO software package from the downloaded file.
  2. Put the "bin" directory from the package in your PATH environment variable.
  3. Run the command: "do-server -setup <serverdir>" where <serverdir> is a directory for the server configuration and data storage.
  4. Register any Handle IDs used in the previous step. At the very least, you will need to make sure the server ID exists, and contains a reference to the public key for the server (generated in the previous step). In addition, the server ID will also need to contain a reference to the XML server information that was generated in the previous step. If this server is part of a multi-server repository then you will need to combine the server info with that of any existing servers. Note: You may need to give the identifier a few minutes to propagate through the handle system before continuing to the next step.
  5. Then run the command: "do-server <serverdir>" where <serverdir> is the same as in step 3. This starts the server, and if this server is part of a multi-server repository, will allow the replication process to begin.
  6. Use the do-client application to talk to your new digital object server and configure access control and authorization. Without further configuration, the access/authentication system will only allow access to the client that authenticated using the same Handle ID as the server.

Server Configuration

Server Capabilities:

The capabilities of the digital object server are determined based on the "operators" that are loaded in that server. The default operator for a new server includes the "standardops" operator which performs the most common operations such as:

1037/1 Create Object
1037/5 Get the data element named by parameter <elementid>
1037/6 Store data into the element named by parameter <elementid>
1037/7 Delete the data element named by parameter <elementid>
1037/8 List the data elements
1037/10 List the objects in the repository (repo objects only)
1037/45 Delete Object
1037/49 Set attributes of an object or element
1037/50 Get the attributes of an object or element
1037/51 Remove attributes of an object or element

The operations available on any object can be discovered using the do-invoke command:

do-invoke <objectID> 1037/0 < /dev/null

The above command invokes the 1037/0 operation (aka the "list available operations" operation) on the object <objectID>. If the caller has permission to invoke operation 1037/0 then the list of operations available on the given object will be printed to STDOUT.


Access Control (Authorization)

The determination of who can do what to which objects is determined by a set of rules assigned to each object. The access control rules are contained in a data element named "internal.rights" contained in the object. If an object does not have a data element with that name, then the rules are contained in a data element named "internal.default_rights" in the server object. Finally, if that data element does not exist, access is only granted to the client who has authenticated with the same identifier as the server. For this reason, after setting up a server you will need to run the do-invoke command to put some access control rules into the internal.rights and internal.default_rights elements of the server object.

To set the initial access rights you will need to use the server's identifier/handle and private key when authenticating. To set the initial access rights you can perform the following two commands:

# set the default rights that apply to brand new objects that do not
# yet have their own access rights. Note that there must be single TAB
# characters between the *'s in the line below. Using spaces will result
# in permission-denied errors
echo "accept:* * *" | do-invoke myprefix/myserver 1037/6 elementid=internal.default_rights

# set the access rights for the server object itself. The rights below
# allow anyone to create objects, get data elements, list data elements,
# list operations, list attributes, verify object existence, list changes
# and list objects.
echo "accept:* myprefix/myserver *\
accept:1037/1 * *\
accept:1037/46 * *\
accept:1037/5 * *\
accept:1037/8 * *\
accept:1037/0 * *\
accept:1037/50 * *\
accept:1037/44 * *\
accept:1037/10 * *\
" | do-invoke myprefix/myserver 1037/6 elementid=internal.rights

Once you have created one or more "user handles" you can grant them permissions by adding lines such as the following to the internal.rights element of the server object:

# grant permission for myprefix/myuser1 to perform any operation:
accept:* myprefix/myuser1 *


Included Software

This distribution includes all the software that is necessary to get your own DO server, client and applications up and running:

  • do-server: a digital object server that can be used to create, modify and access stored digital objects
  • multiple clients DO clients:
    • do-client: a simple GUI client for invoking operations on digital objects
    • do-example: a command-line client meant as an example for how to write apps that create, modify and retrieve digital objects
    • do-invoke: a command-line client for invoking low-level operations on digital objects. do-invoke is useful for piping data to or from unix utilities and files
    • do-sync: a more user-friendly GUI application for creating, searching for and retrieving digital objects
  • miscellaneous utilities:
    • do-jython: a jython/python scripting environment for running scripts or interactive terminal sessions using the python language to interact with digital objects
    • do-keygen: generator for public/private key pairs for use with the DO protocol (and handle system)

Documentation for the DO client API is located the 'apidoc' folder. The jar files that implement this API are lib/do.jar and lib/do_api.jar. To write applications such as the do-example program above all you will need are those two jar files and the API documents.



The CNRI Digital Object Repository (ver. 2) ("DO Repository") software is being released subject to the CNRI open source License Agreement that may be found in the license.txt file that accompanies this release, and may also be located at: The DO Repository software consists of three main components: DO Server, client and utility code; and the software makes use of the following third party libraries, for which the relevant licenses and related information are available in the license.txt file:

  • bouncycastle
  • Berkeley DB JE
  • Jython
  • Java Activation
  • Apache Lucene/Commons
  • Java Mail
  • Apache Nutch
  • JOID
  • Jetty

Please note that the Apache Nutch code loads third party code from several open source packages, the licenses for which are listed in the license.txt file.

This software is covered by section 740.13(e) of the Export Administration Regulations and is eligible for export and reexport in compliance with License Exception TSU.

spacer spacer