NCSTRL Documentation.

Steps to Install Dienst with Autoconfig

NOTE: Autoconfig should not be used if you are updating a pre-4.0 version of Dienst. Contact help@nctrl.org for more information.

The automatic configuration (auto_config.pl) tool simplifies the configuration of Dienst and the initial creation of a document database. It allows you to install a Dienst server with only basic Unix and text editing skills. (If you wish, you may customize Dienst to use an existing document directory structure).

To ensure a successful installation, please perform the following steps in order. In these instructions, all directory names, except when noted otherwise, are relative to the dienst root directory, which is created when you download the Dienst software..

If you have problems with any of these instructions, there is an FAQ for those who are installing Dienst.

If you need to report a bug, contact us at bugs@ncstrl.org.

Up to the main installation menu


Consider copyright issues

Before you make your documents available on the Internet, we strongly urge you to think about the copyright issues. You may wish to look at the copyright statements used by the individual institutional members of NSCTRL (the summary page for each document in the NCSTRL collection includes a copyright statement). You may also wish to consult your institution's intellectual property lawyer.


Register and obtain a naming authority for your site

This section describes the system Dienst uses to identify documents, and tells how to register naming authority(s) for your site.

Dienst requires that each document in the entire (distributed) collection has a unique location-independent name, known as a handle. A handle consists of a naming authority followed by a slash (/) and string. A naming authority is an entity that is authorized to create new handles and store them in the handle system. Naming authorities are hierarchially organized with periods used as the separator. For example, the naming authority ncstrl.cornell, has ncstrl as the top level naming authority, and cornell as the sub-naming authority within it. By convention, the top level naming authority for NCSTRL documents is ncstrl. The remainder of a handle is a unique string assigned to each document within a specific naming authority. The naming authority is free to use its own conventions within the string, as long as each document in the naming authority has a unique string. An example of a complete handle is ncstrl.cornellcs/TR95-1918.

Before you include a set of documents in the NCSTRL collection (by running Dienst), you must assign a handle to each document. The first task is requesting the administrators of the ncstrl naming authority to create one or more sub-naming authorities for your collection. You may wish to specify a single naming authority for all of your documents. We assume most sites will do this. Or you may wish to specify multiple naming authorities. For example, the site Nebraska Coastal University, which has a computer science department and a separate research lab, could choose to have two naming authorities: "ncstrl.ncu.cs" and "ncstrl.ncu.researchlab". To propose naming authorities within the ncstrl domain, you must fill out a registration form for each request. We will respond with your assign authority(s), and additional information such as the administrative password for your naming authority(s).

After securing one or more naming authorities, you can create handles by prepending the naming authority to your site specific document identifier. We assume that most sites already have a naming scheme for their documents. There is no reason that these sites can't use this existing naming scheme as the component of the handle following the assigned naming authority.

To the top of this document


Download the Dienst server

This section gives directions for downloading. At the end of following these directions you will have the Dienst software.

The server and associated software is available in a Unix compressed tar file at ftp.cs.cornell.edu/pub/Dienst/Dienst.tar.Z . The tar file is approximately 2.5MB in compressed form and 3.5MB when uncompressed. A large portion of this space is consumed by the examples/db directory, which contains a sample document database and which may be deleted at any time. Uncompress and unpack the tar file using the command line:

    uncompress -c Dienst.tar.Z | tar xpvf -

All files in this tar file are rooted under a single directory, dienst. This directory contains the following subdirectories. Directories with capitalized names contain code.

The permissions on the various components of the dienst subtree are set as follows: You should recursively set the user ownership and group ownership of the Dienst sub-tree to identifiers that correspond to the user and group that your Dienst server will run as. For example, if your Dienst server will run as user dienst_user and group dienst_group then execute the following commands from the directory that contains the Dienst sub-tree:
    chown -R dienst_user dienst
    chgrp -R dienst_group dienst
You may remove the Dienst.tar.Z file after unpacking it


Create a master database file of bibliographic entries for your documents

Create an ASCII file (in the Config directory) that is a set of RFC 1807-formatted bibliography entries for each of your documents. The name of this file is up to you. The auto config script uses this file to create your document database and its resident bibliographic files. RFC 1807 is a tagged bibliography format. Tags always appear at the beginning of lines and are delimitted from the values by two colons and a space, like this ":: ". The tags that are mandatory for use in Dienst are shown below in the order they should appear. An example of a bibliographic entry is as follows. Individual bibliographic entries in the master bib file must begin with the BIB-VERSION tag and end with the END tag. The release comes with a sample master bib file, Config/examples.bib, containing two document bibliographies. .


Configuration File Editing

This section gives instructions about editing Config/install.config, which contains the input for the Dienst auto configuration script.

Config/install.config is a set of configuration settings, which you will modify. This file uses a markup syntax, where each markup consists of a markup start (e.g., <markup>) and a markup end (e.g., </markup> (the makeup start and markup end MUST be the same, except for the / character in the markup end). Each markup corresponds to a setting name or a tag for a Tagged List. There are three types of settings supported: singletons, lists, tagged lists.

Commented sections in install.config begin with a <!-- and end with a -->.

Now, do it.

With the text editor of your choice, edit Config/install.config. Just follow the directions in the file.


Run Config/auto_config.pl

The auto configuration script auto_config.pldoes several things in the following order: To run the auto configuration script, in the Config directory enter the command:
auto_config.pl
A run of auto_config.pl with comments is available.

Rerun this as many times as you need to get all the variables set correctly. Remember it creates a new version of config_constants.pl and custom.pl each time, as well as a new additions file for your Web server configuration file.

Some notes:

Unless you are specifically instructed to do so, don't delete settings when you edit Config/install.config.

After Config/auto_config.pl is run, and your document database has been created, you may wish to run the utility Utilities/bin/check-bib-file.pl (from the dienst root directory). This makes some checks on the consistency of your database.


Start and test your Dienst server

This section describes the process of starting and testing your Dienst server software. When completed, you should have a functional Dienst server on your system.

Start the server.

You can start your server by executing the command
    dienst.pl &
in the Kernel directory. You may wish to place this command in your system's /etc/rc.local so that it automatically started when your system is booted.

Test the server.

Immediately after starting up, the Dienst server will load in the database index files, write a startup message to the log, and wait for connections over its assigned port. If all is working correctly you should see no messages on the terminal window from which you issued the command to start Dienst. You can examine the today's log file logs/dienst.log.<date> to verify that a startup message was recorded in the log.

To test the Dienst server, execute the script Dienst_server_test.pl in Config. Test 1 returns a header and the Dienst version of your server; Test 2 returns a header, and an html formated listing of the server status (this is pretty long); Test 3 returns a header, and a text/plain listing of the contents of your document database. If no error messages occur, your server is running fine.

To the top of this document


Download a Web server

We recommend you run a separate http server for Dienst. However, if you wish you can use an existing Web server as the gateway to Dienst.

Choose a Web server to download. You should install the Web server on the same machine that you installed your Dienst server. Dienst has been fully tested with two well-known http servers, You should choose the server that you are most familiar with.


Configure your Web server to work with Dienst

This section give instruction to configure the Web server to work with Dienst. At the end of these instructions, you should have a new version of your Web server configuration file to allow your Web server to talk with your Dienst server.

Modify the home page

The file htdocs/Welcome.html is the recommended NCSTRL home page. You may, of course, customize it for your site. Note that the final text on the page (the footer) must be modified for your site.

Modify the Web server configuration file

auto_config.pl created files to help you configure your Web server to interface to Dienst.

If you are using NCSA http server as the gateway to Dienst, insert the contents of the file Config/srm_conf.additions at the end of the ScriptAlias directives in the srm.conf file.

If you are using CERN http server as a gateway to Dienst, replace all Pass directives in the httpd.conf with the contents of the file Config/httpd_conf.additions.

You can now start your Web server (please refer to the specific instructions for your Web server).


Test your Web server with Dienst

This section is the final test of the functional interaction of the three peices - the Dienst server, the document database, and the Web server.

The Final Test

You have now completed the basic installation. To verify that everything works correctly, start up a Web browser (e.g. Netscape) and connect to the server's home page. (If this is successful, the Web browser communication is ok.) Next, follow the link to the Dienst fielded search form. At this point you are running a standalone system; you will see only the name of your local collections (a local_authority listing). Now perform a fielded search request, on your local document collection.

Congratulations. Let us know you are up.

When you have tested your server and are happy with its function, send us a note at help@ncstrl.org so that we can add you to our list of repositories. After you recieve our response that we have added you, you need to change your server from a standalone server, to a networked server. Using any editor, edit the file Config/config_constants.pl. Locate the line
$standalone = "1";
and change it to
$standalone = "0";
Now run the command
Utilities/bin/reload-code
to register this new setting with your Dienst server.

To the top of this document

Up to Main Information Menu


NCSTRL Documentation
Any comments or questions?
Contact us at help@ncstrl.org.