# Installation

This chapter tries to explain the process of the installation. There are some things you should consider before you actually install the software. These will be discussed in the second section. The technical details of the installation on various platforms can be found in the following sections of this chapter. The final sections deal with the setup of optional web-based frontends. But first we start with a brief overview of installing and running RefDB for those who never read manuals.

## Quickstart guide

These are the essential steps to get your reference database up and running:

- Follow the installation instructions for either Unix/Linux or Windows.

- Finish the installation by creating and filling the internal database.

- Start the application server refdbd, either manually or as a daemon, as explained in the OS-specific installation sections.

- Create one or more reference databases.

- Add one or more users that are permitted to work with this database (not required if you use the SQLite database engine as it lacks access control).

- Add bibliography styles.

Some of the above steps are simplified by the shell script refdb-init which you should have a thorough look at. Then it is up to the users to populate the database with references, run their queries, create bibliographies, and whatever they may desire.

## Upgrading from an older version

If you already run an older version of RefDB and want to upgrade to the latest version, you may have to change a few things in your local setup in order to reuse existing databases and existing configuration files. This section lists all backwards-incompatible changes of the past few versions (the complete list since the days of yore can be found in the file `README`).

The file `UPGRADING` contains instructions how to avoid losing your data in the case of non-trivial changes in the new version.

### 0.9.9

- Major changes in both the reference databases and the main database require to upgrade both.

- Before re-importing your reference data, you may have to migrate the contents of some AV fields to L1

- Before re-importing custom citation styles, you may have to fix a few elements. The styles shipped with RefDB do not require these fixes, you can just add them again.

### 0.9.8

- The implementation of personal reference lists has changed, most notably in that each user can have more than one of these lists. Although there was no need to alter the database schema, one of the tables is now used to record the ownership of a reference instead of the membership of a reference in a personal list. The results may be a bit unexpected if you upgrade to 0.9.8 without migrating the data.

### 0.9.7

- The main database needs to be re-created if you use MySQL as a database engine.

## Things to know before you start

### Which database server?

RefDB currently supports MySQL and PostgreSQL as external database servers as well as SQLite as an embedded database engine. This section tries to help you decide which one to pick.

The first issue is whether you want to run an external database server or not. External database servers scale better if many users share databases and they provide access control. The external database servers also use more fine-grained locking mechanisms which allow concurrent read and write accesses, whereas the SQLite engine will lock the entire database for write accesses. However, the latter does not provide access control and thus doesn't require any sort of user administration.

Rule #1

If you don't intend to share databases, or if running a database server scares you in any way, then you may better off with SQLite.

Another issue is the way how the database engines store their data. SQLite is unique in that it uses a single architecture-independent file per database which makes transferring the data to a different box a breeze. The external database engines use more sophisticated ways to organize their data, but you need some basic administrative skills in order to replicate the data.

Rule #2

If you cannot rely on remote access to your databases (something which RefDB is well suited for) but have to take your data physically with you while travelling, SQLite is a better choice.

Now some words about the external database servers. As with many other fundamental schisms in the Unix world (vi vs. Emacs, KDE vs. Gnome, to name a few), both database servers supported by RefDB have followers who are semi-religious about their choice. Both MySQL and PostgreSQL are robust and well-proven. This leads us to:

Rule #3

If you already use one of the servers, then by all means use it also for RefDB. Being familiar with the server and having it happily running usually outweighs any advantages that the other server might have.

But what if you do not yet run a suitable database server? You can browse the web and read for hours about the differences between MySQL and PostgreSQL, but for the purpose of managing RefDB reference databases it boils down to one essential difference: MySQL is faster.

This leads us to:

Rule #4

If you cherish speed over anything else, use MySQL.

There's a few more differences that you should be aware of: PostgreSQL has transaction support by default. MySQL supports transactions only if you use InnoDB tables. If you want this additional peace of mind from MySQL, make sure InnoDB is the default table type. SQLite does not support Unix-style regular expressions. If you'd like to use these more versatile expressions instead of the simpler SQL regular expressions supported by SQLite, choose MySQL or PostgreSQL.

### Where do the components go?

As RefDB is a three-tiered client-server application, you have considerable freedom to distribute the components among your computers. Although RefDB shines in a network environment, there is absolutely no problem to run all components on a single standalone workstation.

Please keep in mind that there's one tier less if you choose the SQLite embedded database engine. The databases will always be on the filesystem of the machine that runs refdbd (this doesn't exclude putting the files on an NFS share if you have a good reason to do so).

The basic idea of the client-server model has several implications:

- Many workstations can access a single server running the database server. Thus many people can access the same databases without the pain of duplicating the data and the database engine on every single machine.

- A considerable part of the computing effort is done outside of the workstations. Therefore even rather lame workstations may be sufficient to access and manipulate the data. The database server should run on a decent machine, though (better not that dusty 486 that has doubled as a paperweight since 1990).

- Updates of the software will mainly affect the database server and the application server. This considerably reduces your workload, as the workstations need to be updated less frequently.

The most common scenarios for using RefDB will be on a department or institute network and on a standalone workstation. Let's see how these scenarios differ:

#### Installation on a standalone workstation

This is obviously the simplest case. The clients, the application server, the database server, and the databases reside on the same physical machine (see ). The only requirement for the workstation is that a TCP/IP network is installed. This is necessary as the three layers of RefDB always communicate via TCP/IP sockets. The IP address 127.0.0.1 has to be specified in the configuration files of the clients and of the application server.

RefDB on a standalone workstation

#### Installation in a network

In a network you can take advantage of the client-server model and distribute the workload between your computers. Although the three layers can well be distributed between three physical machines, it may be more useful to install the application server on the same machine as the database server and the databases (see ). A dedicated or general-purpose server may be most suitable to hold these components, as a workstation may get sluggish if it has to answer a lot of database requests.

The clients as well as scripts and support files have to be installed on all workstations that will be used to access the databases. The client for administrative tasks, refdba, can be restricted to the workstations of system administrators or otherwise experienced staff.

RefDB on a network

### The mystery of the configuration files

Like with most Unix-style software packages, the behaviour of the RefDB applications can be tweaked by configuration files. Wherever it makes sense, there is one global config file with useful admin-picked defaults, and another user config file for the individual user to play with. The purpose of the configuration files is to set some reasonable default values for the command-line switches of the RefDB programs. Once you have set these, you will never have to specify these values on the command line again, unless you want to temporarily override them.

#### Types of configuration files

All RefDB applications and scripts that use configuration files (these are the server refdbd, the clients refdbc, refdbib, refdba, the script refdbxml, as well as the conversion filters bib2ris, db2ris, med2ris.pl, marc2ris, and en2ris) can use two configuration files each. One global configuration file is supplied by the system administrator and can be used to set values that are common for all users on that box, like the IP address of the application server. Another file can be used by every user to supply the values that were not set in the global file or to override settings in this file. The users' copies can have a leading dot to hide the files (the refdb programs will first try to read a hidden configuration file, and only if that cannot be found they try to read a non-hidden file).

bib2ris, marc2ris, and med2ris use a second global configuration file if they are run as a CGI applications. A local configuration file does not make sense in this case.

The default location for the global configuration files is `/usr/local/etc/refdb`. There are two ways to change this. If you compile RefDB from the sources you can specify a different directory with the `--prefix` or `--sysconfdir` options of `./configure`. E.g. if you specify `--sysconfdir=/etc`, then the configuration files will be installed in `/etc/refdb` (the `refdb` part is automatically appended by the RefDB install routines). If you use precompiled binaries, use the `-y` command line option to specify the directory. In this case you have to specify the full path, i.e. `/etc/refdb` to read the configuration files installed by the previous example.

The user copies of the client configuration files are expected to be in the users' home directories as specified by the environment variable `HOME`.

#### Configuration file syntax

All configuration files share a common syntax. There are just three essential things to know:

- All information is stored as pairs of whitespace-separated items, one pair on each line. The first item on the line specifies the variable name, the second item specifies the variable value. Whitespace means one or more spaces or tabs in any combination.

- Everything to the right of a hash sign (#) is a comment. The rest of the line is ignored.

- The line endings are Unix-style (0x10, not DOS-style 0x13 0x10), regardless of the operating system.

#### A configuration example

The whole configuration stuff may sound a bit confusing, so let us now look at a simple configuration example that illustrates the principles laid out above.

The following is a listing of `/usr/local/etc/refdb/refdbcrc`, our global refdbc configuration file in this example:

    # This is the global configuration file for refdbc
    serverip	127.0.0.1
    port	9734
    pager	more
    timeout	180
    # end of refdbcrc

This is the corresponding copy that one of the users of the system created as `/home/joe/.refdbcrc`:

    # This is the user configuration file for refdbc
    pager	less
    username	joesixpack
    passwd  *
    timeout	30
    # end of .refdbcrc

As you can see our hypothetical system administrator configured the IP address (`serverip`) and the `port` where refdbd listens to the client requests. This value is most likely the same for all users on the system, so this is nothing to worry about for the users. `more` is defined as the default `pager`, and the `timeout` is set to 3 minutes.

Joe Sixpack, our reckless user, does not like `more` as a pager and prefers to use `less` instead. He also thinks that half a minute as a timeout should be enough. Both of these settings override the corresponding values in the global file. `serverip` and `port` are not redefined in the user's copy, so the values of the global file take effect. Joe also defined `username` (which happens to be different from his login name "joe") and `passwd` so the correct values will be used for the database access (the asterisk in the `passwd` field will cause refdbc to ask for the password interactively for security reasons).

#### Configuration file variables

For a listing of available configuration file variables please see the tables for refdba, refdbc, refdbib, refdbd, refdbxml, bib2ris, db2ris, med2ris, marc2ris, and en2ris.

### Environment variables

refdb uses the following environment variables to locate the files and directories it needs to run properly.

HOME

  This variable should be set for all users anyway. It is used to locate the personal configuration files for the RefDB clients.

SGML_CATALOG_FILES

  If you process SGML files, this variable will be consulted to locate the catalog files required for resolving public identifiers to their local filename equivalents.

  On some systems, the package system maintains a master catalog whose path is hard-coded into the SGML applications. In this case, the variable is not required.

XML_CATALOG_FILES

  If you process XML files, this variable may be consulted to locate XML catalogs. If this variable is not set, many tools look into the default location `/etc/xml/catalog` instead. Remember that some XSLT processors need access to additional Java classes to provide XML catalog support at all.

### Some notes on the filesystem

The default installation procedure will install the RefDB files in locations compatible with the filesystem hierarchy standard. You will learn in the following sections how to change where the RefDB files will be installed if you want to adapt the installation to specific needs of your system. To get a better idea of what you have to take care of if you don't like the defaults, here is a list of the directories used by RefDB:

`/usr/local/bin`

  This directory will receive all binary files and shell scripts.

`/usr/local/etc/refdb`

  All global RefDB configuration files end up in this directory.

`/usr/local/share/refdb`

  This directory contains shareable, operating system independent files. The files are organized in a couple of subdirectories:

  - `css` contains a cascading stylesheet suitable for the HTML output of the `getref` command.

  - `declarations` contains the default SGML declarations.

  - `dsssl` contains DSSSL stylesheets.

  - `dtd` contains the document type definitions used by RefDB.

  - `examples` contains a few example reference data files as well as SGML and XML test documents using RefDB citations.

  - `sql` contains SQL scripts used to initialize databases.

  - `sru` contains the XSLT and CSS stylesheets required to set up the SRU service

  - `styles` contains some XML files containing bibliography styles.

  - `xsl` contains XSLT stylesheets.

`/usr/local/var/lib/refdb/db`

  holds the database files of embedded database engines and a version file for use by package installation scripts

## Installation on Linux and other Unix variants

RefDB was designed with portability in mind. Thanks to the GNU autotools installation on many Unix variants is straightforward, others need only a little tweaking. The following instructions provide a guideline for all Unix-like systems. Please see also the hints for specific operating systems at the end of this section.

### Generic instructions

#### Prerequisites

These instructions assume that the following software is installed and functional on your computer or on your network before you start:

- A SQL database engine. For an external database server, choose between MySQL (version 3.23 or later) or PostgreSQL (version 7.1 or later). The database server does not have to physically run on the box(es) where you plan to install RefDB, it is sufficient if it is accessible through the network.

  If you prefer an embedded database engine, please use SQLite instead.

- As far as non-standard libraries and header files are concerned, you'll need the readline library and headers (available at the GNU FTP site). Database access requires the libdbi library and headers as well as the libdbi-drivers package. Furthermore, you`ll need the expat library. If you need the BibTeX import filter, you'll also want to have the btparse library.

  Some operating systems/distributions use separate packages for the run-time libraries (ususally `.so` files) and for the development libraries (usually `.a` files). In order to build and run RefDB, you need both packages for each library.

- If you want to import Pubmed or MARC datasets, please get the refdb-perlmod package. This collection of Perl modules is required to run the Pubmed and MARC import filters shipped with RefDB. These Perl modules in turn depend on MARC::Record, MARC::Charset, XML::Parser, and Text::Iconv, available at CPAN.

#### Installation from the sources

The installation steps proper (as opposed to the build steps) should be run with root privileges.

- Unpack the archive in a convenient directory: `tar -xzf refdb-x.y.z.tar.gz` (the actual filename depends on the version).

- If you do not want to build in the source directory, create an empty build directory.

- cd into the new `refdb-x.y.z` source directory or into your separate build directory

- Use `./configure --help` to see a list of things you can customize. If you use a separate build directory, use the relative path to `configure` in the source directory. Some important options are:

  All paths and URLs in the following options should be entered without a trailing slash.

  --prefix=PREFIX

    By default, all files will be installed in the `/usr/local` tree. Use this option to use a different install root, e.g. `/usr` or `/opt`.

  --datadir=DIR

    The data files will be installed in `/usr/local/share/refdb` unless you use this option. The data will be installed in the directory `DIR/refdb`. That is, specifying "--datadir=/usr/local/share" is equivalent to the default behaviour. The configuration variable `refdblib` (which will be automatically generated in the example configuration files) must point to the RefDB data directory.

  --sysconfdir=DIR

    The global configuration files will be installed in `/usr/local/etc/refdb` unless you specify a different directory here.

  --with-libdbi-lib=DIR

    Use this option to specify the directory that contains the libdbi library if it is not in the default library path.

  --with-expat-lib=DIR

    Use this option to specify the directory that contains the expat library if it is not in the default library path.

  --with-btparse-lib=DIR

    Use this option to specify the directory that contains the btparse library if it is not in the default library path.

  --with-sgml-declaration=PATH

    Specify the full path to a suitable SGML declaration for your SGML files. If this option is not used, RefDB will use its own copy of `docbook.dcl` stolen from the DocBook DTD distribution. This SGML declaration also works for a variety of other DTDs.

  --with-xml-declaration=PATH

    Specify the full path to `xml.dcl` which is the SGML declaration for XML files. If this option is not used, RefDB will use its own copy of `xml.dcl` which should work just fine.

  --with-docbook-xsl=PATH

    Specify the full path to the root directory of the DocBook XSL stylesheets.

    This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. `configure` checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.

  --with-docbook-xsl-ns=PATH

    Specify the full path to the root directory of the DocBook XSL-NS (for DocBook V5.0 and later) stylesheets.

    This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. `configure` checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.

  --with-tei-xsl=PATH

    Specify the full path to the root directory of the TEI XSL stylesheets for P4.

    As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The TEI Consortium ships tei-xsl-5.2.9.zip which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. `/usr/local/share/xsl/tei-xsl-5.2.9`.

  --with-tei-xsl-ns=PATH

    Specify the full path to the root directory of the TEI XSL stylesheets for P5.

    As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The TEI Consortium ships tei-xsl-5.2.9.zip which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. `/usr/local/share/xsl/tei-xsl-5.2.9`.

  --with-classpath-root=PATH

    The refdbxml script assumes that all Java classes for the Java parsers and xslt engines are stored in a class repository, i.e. all in the same directory. Specify this directory with this option. If you keep the relevant Java classes in different directories, either create symlinks or customize refdbxml manually.

  --with-var-dir=PATH

    Use this option to specify a directory where refdbd can write its PID file (a file containing the process ID). By default, `/var/run` will be used.

  --with-log-dir=PATH

    Use this option to specify a directory where RefDB programs can write log files to, if logging is directed to a custom file. By default, `/var/log` will be used.

  --with-main-db=dbname

    RefDB uses one main database to store citation styles and other stuff. There is exactly one such database per installation with the default name `refdb`. You may have to change this name if you want to run two different versions of RefDB in parallel, or if you're not free to choose your database name. Although the main database name is configurable at runtime, you should use this option to initialize your `refdbdrc` configuration file, as it allows the refdb-init script to use the proper database name.

  --with-db-dir

    Selects the directory which holds SQLite/SQLite3 databases.

  --with-trang-jar

    Specifies the full path to the jar file of the trang tool. You need this tool if you build RefDB from SVN sources, but not if you build from a tarball.

  --disable-docs

    RefDB ships with prebuilt docs. However, if you build a SVN version, or if the documentation is otherwise screwed up, you may have to build them. Building the docs from the sources requires a couple of extra tools. You can use this configure switch to build the rest of RefDB without having to install these tools.

  --disable-clients

    Use this switch if you want to build and install only the application server `refdbd`. This is mainly targeted at package builders.

  --disable-server

    Use this switch if you want to build and install only the clients but not the application server. This is mainly targeted at package builders.

  Some of these options are used to customize the shell scripts, XSL stylesheets, example configuration files, and HTML files which are part of RefDB. If you do not specify these options now, you can still build and install the package, but you will have to customize the scripts and stylesheets manually in order to make them work. Doing it now is much easier. You've been warned.

  Start the configuration with the command `./configure`, specifying any additional options as you may need. Use the relative path to `configure` in the source directory if you build in a separate directory.

  If your system keeps non-system header files in odd places, it may be necessary to set the `CFLAGS` environment variable before you run `configure`. E.g. if headers like `expat.h` are stored in `/usr/local/include`, you should run `CFLAGS="-I/usr/local/include" ./configure` instead, specifying additional options as necessary.

- `make`

  The autotools-generated Makefiles apparently prefer (or require?) GNU make. If `make` results in spurious error messages about the Makefile syntax, try to run `gmake` instead as your regular `make` is apparently not the GNU version.

- `make install`

  This will install the binaries and scripts in `/usr/local/bin` and the data in `/usr/local/share/refdb` unless you chose different directories in the configure step. Again, run `gmake install` instead if your regular `make` is not the GNU version.

- To finish the installation, please follow the instructions in the section Finishing the RefDB installation below.

If this procedure results in strange error messages, you probably use a platform that is not supported yet. The author appreciates a porting effort or a description of the problem (in this particular order).

#### Living on the bleeding edge: installing a SVN version

While the official release versions of RefDB are your best bet to get a stable installation, you may be interested to test the latest developments "in statu nascendi". The SVN version is guaranteed to compile on the author's development platform (currently FreeBSD 6.1), but may fail on other platforms. Known bugs may have been fixed, but new ones may have crept in as well. New features may be implemented, but might not be without problems. You've been warned. If you still want to go ahead, this is what you need to do:

- Change into a suitable directory. SVN will create a subdirectory called `refdb` during the following steps

- Run the following command (adapt this accordingly if you use some graphical CVS frontend instead of the command line tool):

      	      $~/build
      	      svn co https://svn.sourceforge.net/svnroot/refdb/refdb/trunk refdb

  Other interesting modules to check out are `perlmod` (the Perl modules and the Perl client library) and `elisp` (the Emacs support files).

  If you are interested in a particular repository version, release, or branch, use commands along these lines:

      	      $~/build
      	      svn co --revision 324 https://svn.sourceforge.net/svnroot/refdb/refdb/trunk refdb-324
      	      svn co https://svn.sourceforge.net/svnroot/refdb/refdb/tags/Release-0.9.7 refdb-0.9.7
      	      svn co https://svn.sourceforge.net/svnroot/refdb/refdb/branches/back-to-a-1-branch refdb-a1-branch

- If you want to keep track of the latest developments, you'll have to update your SVN working copy once in a while. Run this command from within the top-level source directory:

      	      $~/build/refdb
      	      svn update

  Consider subscribing to the refdb-cvs mailing list as you'll be notified about each SVN checkin.

- The SVN version lacks all autotool-generated files. You'll have to create them with your local autotools. RefDB contains a small script called `autogen.sh` in its top-level directory which performs all necessary steps.

      	      $~/build/refdb
      	      ./autogen.sh

  The autotools can cause severe headaches at times. If the above command causes errors, read `autogen.sh` and run the commands manually, substituting different versions as appropriate. E.g. substitute `automake` with `automake-1.8` if this gives better results. The native autotools shipped with FreeBSD 5.4 and later are unusable for our purposes, you have to install the gnu-autotools package instead. You have to modify your `PATH` to pick up the latter, and fiddle with the m4 macro paths in order to see the light.

- The SVN version also lacks a few other things which are included in the source tarballs. In order to create the missing stuff, you'll need the following additional tools:

  - Batik SVG Rasterizer: an image converter used to create the images from the SVG sources. The Makefile calls a script in your path called `batik-rasterizer` which is supposed to run this Java application appropriately.

  - dtdparse: a Perl script (which in turn depends on a few Perl modules, see the installation instuctions) which generates the DTD documentation.

  - trang: a tool required to turn the RefDB DTDs into RelaxNG schemas.

  To work around problems, you may want to use the following `./configure` switches:

  - --with-trang-jar=PATH

  - --disable-docs

- Finally you're ready to build RefDB like you would with a released version.

There is also a neat shell script available on the RefDB download page which helps you to keep a SVN version up to date with a minimum number of keystrokes.

#### Installation of refdbd as a daemon

This is all it takes to run RefDB from the command line. If you want to start refdbd as a daemon at system startup, a few more steps are necessary. The exact procedure varies greatly between operating systems and distributions. First we'll look at SysV-style systems (most Linux distributions), then at BSD-style systems (BSD-derived Unices and the Slackware Linux distribution).

##### SysV-style

The following procedure describes the setup on a Debian GNU/Linux system. With a little help of your system handbook you should be able to adapt this to your system. On many systems `/etc/init.d/README` contains just what you need to know or at least it points you to the correct resources.

- Review the parameters in the script `refdb` in the `scripts` directory of the source distribution (this file is not automatically installed). If necessary, change the paths and names to your needs and adapt the following steps. Make sure the `BSDSTYLE` variable is set to "NO" (this is the default value).

- Copy the script `refdb` to `/etc/init.d/` and make sure it is executable: `chmod 755 /etc/init.d/refdb`.

- Create symbolic links from every runlevel directory that should start refdbd to `/etc/init.d/refdb`, e.g. `ln -s /etc/init.d/refdb /etc/rc2.d/S93refdb`. The numbers in the link names are a convenient and simple way to determine the sequence of daemon starts. As most likely no other daemons rely on RefDB, you can choose as high a number as you want (the daemons are started in lexicographical order).

- In analogy to the previous step, generate symbolic links in every runlevel directory that should stop the daemon. Usually these are the runlevels 0 (system halt) and 6 (reboot):

  `ln -s /etc/init.d/refdb /etc/rc0.d/K20refdb`

  `ln -s /etc/init.d/refdb /etc/rc6.d/K20refdb`

- Review the settings in the script `refdbctl` which by default is installed in `/usr/local/bin/`. Most likely the script was properly customized for your system in the build step so you don't have to change anything.

When you boot, halt, or reboot the system you should see messages on the screen telling you that the daemon has been started or stopped successfully. If you don't, please check again all paths in the scripts, the file permissions, and the runlevels you're looking at. Try to run the control script from the command line, e.g. `refdbctl start`, to distinguish between general setup problems and init-related setup problems.

##### BSD-style

The following procedure describes the installation on a FreeBSD system. Other systems might differ somewhat, but you should get the idea.

- Review the parameters in the script `refdb` in the `scripts` directory of the source distribution (this file is not automatically installed). Set the value of the script variable `BSDSTYLE` to "YES" (the sole purpose of this variable is to make the boot message blend in seamlessly, if you happen to care for aesthetics). If necessary, change the paths and names to your needs and adapt the following steps.

- Copy the script `refdb` to `/usr/local/etc/rc.d/refdb.sh` and make sure it is executable: `chmod 755 /usr/local/etc/rc.d/refdb.sh`.

  The suffix `.sh` is mandatory on BSD-style systems.

- Review the settings in the script `refdbctl` which by default is installed in `/usr/local/bin/`. Most likely the script was properly customized for your system in the build step so you don't have to change anything.

When you boot, halt, or reboot the system you should see messages on the screen telling you that the daemon has been started or stopped. If you don't, please check again all paths in the scripts and the file permissions. Try to run the control script from the command line, e.g. `refdbctl start`, to distinguish between general setup problems and system-related setup problems.

### OS-specific hints

This section contains a few hints about the installation on some popular Unix-like operating systems.

#### Linux

The generic instructions should work out of the box for most if not all Linux distributions.

##### Debian GNU/Linux

Debian keeps all configuration files in `/etc` and subdirectories thereof which makes backing up the configuration of the whole box a breeze. To support this nice feature, you want to add `--sysconfdir=/etc` to your configure options. The configuration files will then be in `/etc/refdb`. The following is an example of a complete configure call that works on Debian 3.0 (the line was split into several lines for the sake of clarity; type everything on one line and skip the backslashes):

    	    #~
    	    ./configure --sysconfdir=/etc \
    	    --with-docbook-xsl=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh \
    	    --with-tei-xsl=/usr/local/lib/sgml/stylesheet/xsl

#### FreeBSD

The BSD version of `make` cannot handle the autotools-generated Makefiles correctly. Use gmake instead, and set CFLAGS=-I/usr/local/include during the configuration step. The full configure command, using the default installation paths for the accessory files and programs, looks like this:

    	  #~
    	  CFLAGS=-I/usr/local/include ./configure --with-expat-lib=/usr/local/lib \
    	  --with-classpath-root=/usr/local/share/java/classes

The shared data end up in `/usr/local/share/refdb`, the configuration files will be in `/usr/local/etc/refdb`.

#### NetBSD

The BSD version of `make` cannot handle the autotools-generated Makefiles correctly. Use gmake instead, and set the following environment variables before running `./configure`:

    	  #~
    	  setenv CFLAGS "-I/usr/pkg/include -I/usr/local/include -L/usr/pkg/lib"

    	  #~
    	  setenv LDFLAGS "-L/usr/pkg/lib  -R/usr/pkg/lib -R/usr/pkg/lib/mysql"

    	  #~
    	  ./configure --with-mysqlclient-lib=/usr/pkg/lib/mysql --with-btparse-lib=/usr/local/lib --prefix=/usr/pkg

Use additional options as needed. The shared data will end up in `/usr/pkg/share/refdb`, the configuration files go to `/usr/pkg/etc/refdb`.

#### Solaris

Both the standard C compiler and the standard make program will not give the desired results when building RefDB. Use gcc and gmake instead.

#### OSX

Use fink to conveniently install all the additional software needed. Then help `configure` find the fink-installed packages in `/sw` by setting the following environment variables: `CFLAGS="-I/sw/include" LDFLAGS="-L/sw/lib" ./configure [your_options]`.

## Installation on Windows NT/2000/XP

### Prerequisites

In order to run RefDB you'll need a few external apps. The most important thing are the Cygwin tools which provide a Unix-like environment on the otherwise incompatible Windows platform. Additionally you'll have to build or obtain prebuilt versions of a few libraries which are not part of the standard Cygwin distribution (unless you use prebuilt binaries that contain all non-standard libraries).

#### External applications

- Cygwin toolkit, DLL version 1.5.0 or later (the current version as of this writing, 1.5.12, has serious problems with PostgreSQL, though). The Cygwin distribution uses individual packages for the various parts. In addition to what is installed automatically (the base distribution), please make sure to select the following packages: libxml2, libxslt, expat, Perl, and a full TeX installation if you wish to create Postscript or PDF files.

- A SQL database engine. Currently you can choose between MySQL (version 3.23 or later), PostgreSQL (version 7.1 or later), and SQLite/SQLite3 (versions 2.8.x or later; 3.0.x or later). The database server does not have to physically run on the box(es) where you plan to install RefDB, it is sufficient if it is accessible through the network.

  Cygwin offers a prepackaged version of PostgreSQL (7.3.3 as of this writing) which used to be the most convenient way to run a database server on your Cygwin box, but as stated above it may be broke when you try. Please follow the instructions in the readme shipped with the package to install and initialize the database server. It is crucial that you install and run the separately available cygipc package, available only here.

  SQLite does build on Cygwin, but all filename/path handling code uses the Windows conventions. You will have to use the Windows-style path when setting the database directory.

- If you want to import Pubmed or MARC datasets, please make sure to install the Perl interpreter available for Cygwin and get the refdb-perlmod package. This collection of Perl modules is required to run the Pubmed and MARC import filters shipped with RefDB. These Perl modules in turn depend on MARC::Record, MARC::Charset, XML::Parser, available at CPAN.

The mentioned websites offer plenty of support as web documents or with mailing lists, so it should be possible to figure out how to do a basic install for these suites.

#### Libraries

- The libdbi library and headers, along with the libdbi-drivers package. Please follow the Cygwin-specific instructions that accompany both packages to build and install the software. Prebuilt binaries for both libdbi and libdbi-drivers are available here.

- If you need the BibTeX import filter, you'll also want to have the btparse library. This builds out of the tarball on Cygwin.

### Installation from the sources

Depending on the permission settings, you may have to run the installation steps proper (as opposed to the build steps) as an administrator.

- Unpack the sources in a convenient directory: `tar -xzf refdb-x.y.z.tar.gz` (the exact filename depends on the version).

- If you do not want to build in the source directory, create an empty build directory.

- Change into the new `refdb-x.y.z` source directory or into your separate build directory.

- `./configure --help`

  This command will display a list of things you can customize. If you build in a separate directory, use the relative path to `configure` in the source directory. Some important options are:

  All paths and URLs in the following options should be entered without a trailing slash.

  --prefix=PREFIX

    By default, all files will be installed in the `/usr/local` tree. Use this option to use a different install root, e.g. `/usr` or `/opt`.

  --datadir=DIR

    The data files will be installed in `/usr/local/share/refdb` unless you use this option. The data will be installed in the directory `DIR/refdb`. That is, specifying "--datadir=/usr/local/share" is equivalent to the default behaviour. The configuration variable `refdblib` (which will be automatically generated in the example configuration files) must point to the RefDB data directory.

  --sysconfdir=DIR

    The global configuration files will be installed in `/usr/local/etc/refdb` unless you specify a different directory here.

  --with-libdbi-lib=DIR

    Use this option to specify the directory that contains the libdbi library if it is not in the default library path.

  --with-expat-lib=DIR

    Use this option to specify the directory that contains the expat library if it is not in the default library path.

  --with-btparse-lib=DIR

    Use this option to specify the directory that contains the btparse library if it is not in the default library path.

  --with-sgml-declaration=PATH

    Specify the full path to a suitable SGML declaration for your SGML files. If this option is not used, RefDB will use its own copy of `docbook.dcl` stolen from the DocBook DTD distribution. This SGML declaration also works for a variety of other DTDs.

  --with-xml-declaration=PATH

    Specify the full path to `xml.dcl` which is the SGML declaration for XML files. If this option is not used, RefDB will use its own copy of `xml.dcl` which should work just fine.

  --with-docbook-xsl=PATH

    Specify the full path to the root directory of the DocBook XSL stylesheets.

    This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. `configure` checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.

  --with-docbook-xsl-ns=PATH

    Specify the full path to the root directory of the DocBook XSL-NS (for DocBook V5.0 and later) stylesheets.

    This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. `configure` checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.

  --with-tei-xsl=PATH

    Specify the full path to the root directory of the TEI XSL stylesheets for P4.

    As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The TEI Consortium ships tei-xsl-5.2.9.zip which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. `/usr/local/share/xsl/tei-xsl-5.2.9`.

  --with-tei-xsl-ns=PATH

    Specify the full path to the root directory of the TEI XSL stylesheets for P5.

    As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The TEI Consortium ships tei-xsl-5.2.9.zip which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. `/usr/local/share/xsl/tei-xsl-5.2.9`.

  --with-classpath-root=PATH

    The refdbxml script assumes that all Java classes for the Java parsers and xslt engines are stored in a class repository, i.e. all in the same directory. Specify this directory with this option. If you keep the relevant Java classes in different directories, either create symlinks or customize refdbxml manually.

  --with-var-dir=PATH

    Use this option to specify a directory where refdbd can write its PID file (a file containing the process ID). By default, `/var/run` will be used.

  --with-log-dir=PATH

    Use this option to specify a directory where RefDB programs can write log files to, if logging is directed to a custom file. By default, `/var/log` will be used.

  --with-main-db=dbname

    RefDB uses one main database to store citation styles and other stuff. There is exactly one such database per installation with the default name `refdb`. You may have to change this name if you want to run two different versions of RefDB in parallel, or if you're not free to choose your database name. Although the main database name is configurable at runtime, you should use this option to initialize your `refdbdrc` configuration file, as it allows the refdb-init script to use the proper database name.

  --with-db-dir

    Selects the directory which holds SQLite/SQLite3 databases

  --with-trang-jar

    Specifies the full path to the jar file of the trang tool. You need this tool if you build RefDB from SVN sources, but not if you build from a tarball.

  --disable-docs

    RefDB ships with prebuilt docs. However, if you build a SVN version, or if the documentation is otherwise screwed up, you may have to build them. Building the docs from the sources requires a couple of extra tools. You can use this configure switch to build the rest of RefDB without having to install these tools.

  --disable-clients

    Use this switch if you want to build and install only the application server `refdbd`. This is mainly targeted at package builders.

  --disable-server

    Use this switch if you want to build and install only the clients but not the application server. This is mainly targeted at package builders.

  Finally, run `./configure` with any options that you need. If you build in a separate directory, use the relative path to `configure` in the source directory. A complete set of options might look like this if you use PostgreSQL:

      	    $~
      	    ./configure --with-refdb-url=http://yourbox.com/refdb --with-db-server=pgsql --with-var-dir=/var/run \
      	    --with-log-dir=/var/log --with-libdbi-dir=/uar/local/lib --with-docbook-xsl=/usr/local/share/sgml/stylesheets/docbook \
      	    --with-tei-xsl=/usr/local/share/xsl/tei

- Run `make`. This will create the executables and adapt scripts and other files to your local installation.

- `make install` will copy the application server and the clients to `/usr/local/bin` and the data files to `/usr/local/share/refdb` unless you chose different directories in the configure step.

- To finish the installation, please follow the instructions in the section Finishing the RefDB installation below.

Now you have everything in place to use the RefDB clients and the application server from the command line. To install the application server as a service, the following additional steps are necessary:

- Install the service with the command `cygrunsrv -I refdbd -p /usr/local/bin/refdbd -a '-s'` (adapt the paths to your local installation if necessary).

- Start the service with the command `cygrunsrv -S refdbd`. To stop the service, use the command `cygrunsrv -E refdbd`. If you prefer, you can also start and stop the service with Windows' own tools: Either use the system control panel or use the commands `net start refdbd` and `net stop refdbd`.

With this setup, the service will be automatically started at system startup. See `cygrunsrv --help` for additional options.

### Installation of prebuilt binaries

If you decide to grab the prebuilt binaries, the installation will be a little bit faster. The binaries are accompanied by a copy of libexpat. Please make sure to read the aptly named `Readme` files as they may have newer or additional information.

- Unpack the archive in the root directory (`/`) with the command `tar -xzf refdb-cygwin-bin-x.y.z.tar.gz` (the exact archive name depends on the version you use). This will extract the files into the `/usr/local` hierarchy. The binaries and scripts go to `/usr/local/bin`, the Document Type Definitions, stylesheets, styles and example configuration files go to `/usr/local/share/refdb` and its subdirectories.

- Unpack the prebuilt binaries for both libdbi and libdbi-drivers, available here, in the very same way.

- Add `/usr/local/share/refdb/refdb.cat` to your `SGML_CATALOG_FILES` environment variable.

- Create the configuration files in `/usr/local/etc`. Sample configuration files with a `.example` extension are created in the same directory during the installation. Provide personalized copies for the user's home directories as needed.

- To install refdbd as a service, follow the instructions above.

## Installation on Windows 95/98/ME

Most of the things said for Windows NT/2000/XP are applicable as well for Windows 95/98/ME. The main difference is that the latter operating systems do not support the idea of a daemon or service. The closest thing you can do to running a service is to put a shortcut to refdbd into the startup folder. This is not much of a problem if you run the RefDB clients on the same computer as refdbd. However, Windows 95/98/ME are not suitable to handle RefDB requests from other computers because refdbd will not run if nobody is logged in.

## Other operating systems

RefDB has not been ported to other operating systems yet. As no esoteric features of the C language are used, you may just try to run `./configure [options] && make` and see what happens. Chances are that it either works or can be convinced to work with just a few modifications. If you manage to run RefDB on a platform not described here, a short notice with the porting instructions would be greatly appreciated.

## Finishing the RefDB installation

This step is necessary for all platforms. You have to create some databases for RefDB to start with and you should make the RefDB SGML/XML support files known to your system. In most cases you will prefer to use a script provided with RefDB which performs all things required for a first-time installation. If you need more precise control, you'll also find instructions below how to set up RefDB manually.

### Using the interactive setup script

The interactive script `refdb-init` must be run with root permission as it tries to fiddle with a couple of files that a regular user should not have write permission for. After starting the script, it will collect a few answers from you about your intended setup. It will also perform a couple of sanity checks. After this stage is completed, you will be asked to positively confirm whether or not your system should be modified. Therefore it is safe to dry-run this script in order to decide whether you prefer the script over the manual installation.

The script creates the main database, the refdbd and refdba configuration files, loads the available styles, creates a reference database and a database user account. All that is left to do manually is to take care of the SGML catalog file.

### Manual setup

#### Configuration files

Now is the time to create the global configuration files described in the configuration file section. Create these files in `/usr/local/etc/refdb` (or whatever you chose during configuration). It is recommended to copy and modify the commented example configuration files in the same directory. These files are installed with the suffix ".example" to avoid overwriting existing configuration files. All required paths are automatically configured during the installation, so these files are a good starting point for your local modifications.

The `refdbdrc` configuration file can be copied from one of the templates `refdbdrc.mysql.example`, `refdbdrc.pgsql.example`, `refdbdrc.sqlite.example`, or `refdbdrc.sqlite3.example` according to your choice of the database engine.

#### Configuring your database server

The default installation of all supported database engines should be just fine for running RefDB. However, in some cases a little extra work is needed.

##### MySQL

The MySQL engine earlier than version 4.1 supports only one character encoding per server instance. The default encoding is ISO-8859-1, aka Latin-1. If you prefer a different encoding, you have to configure the server at startup. Either use the `mysqld` command-line option `--default-character-set=charset`, or add a "default-character-set=charset" entry to a suitable MySQL configuration file. A list of available encodings is usually installed as `/usr/local/share/mysql/charsets/Index`. In MySQL versions 4.1 and later each database (in fact, each table) may have one of various character encodings.

For security reasons many default installation allow only local connections. If refdbd has to connect to the database server from a different box, make sure to remove the `--skip_networking` option from the MySQL start script or from the appropriate MySQL configuration file.

##### PostgreSQL

Most default installations of this database server allow only local Unix sockets connections due to security concerns. However, the refdbd application server will always talk to the database server via a TCP/IP connection. Please make sure to start `postmaster` with the `-i` command line option to switch on TCP/IP support.

##### SQLite

The embedded database engine SQLite (versions 2.x) supports two character encodings as a compile-time option: ISO-8859-1 (Latin-1) and UTF-8. The former is the default if you don't use any configure options and if you use prebuilt binaries. If you need Unicode support, you'll have to recompile SQLite using the proper configure switch.

SQLite version 3.0 and higher uses UTF-8 as the default encoding which is just fine for the purposes of RefDB.

#### Creating the databases

The RefDB database contains common information that is shared by all reference databases. The following sections explain the database engine-specific steps. In all cases you have two options: The recommended way is to let `refdbd` handle the installation, but for special needs there is also a description how to set up the databases using the database engine clients.

##### MySQL

As mentioned above, the recommended way to create or update the main database is to run the following command from your root account:

    	    ~$
    	    refdbd -a -u username -w password

Specify the username and password of your database administrator account.

If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.

If `mysqld` (the MySQL database server) is installed on a remote box or if the security settings require it, you may have to use the `-h hostname` and/or the `-u username`/`-p password` options to run the `mysql` client as shown below (most fresh MySQL installations use "root" with no password as the default database administrator). `mysqld` needs to be up and running and you need the appropriate permissions, of course. See the MySQL documentation for further details.

Instead of using `refdbd`, you can also use the hard way and create the main database using your database engine client:

- In a command line window, run the following command to create the database "refdb":

      		~$
      		mysql -u root -e "CREATE DATABASE refdb"

- Then create the tables and fill in the data. For MySQL older than 4.1, run:

      		~$
      		mysql -u root refdb < /usr/local/share/refdb/sql/refdb.dump.mysql

  For MySQL 4.1 and later, run this instead:

      		~$
      		mysql -u root refdb < /usr/local/share/refdb/sql/refdb.dump.mysql41

  Adapt the path to the script accordingly if you configured RefDB to put the data directory somewhere else.

  The above command will create the tables using the MyISAM engine. This is the fastest of the supported engines, but it does not support transactions. If you prefer to use the InnoDB engine instead, use this command:

      		~$
      		sed 's/MyISAM/InnoDB/' < /usr/local/share/refdb/sql/refdb.X.dump.mysql41|mysql -u root refdb

  Use the highest dump file number 'X' shipped with your current RefDB version. See the MySQL documentation for further information about the table engines available with MySQL.

##### PostgreSQL

You must run the following command either from your root account, or from a special database administrator account (depending on your local PostgreSQL installation). Run this command to let `refdbd` create the main database:

    	    ~$
    	    refdbd -a -u username -w password

Specify the username and password of your database administrator account.

If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.

Your PostgreSQL administrator accound may not have the privileges to write to the PID file. In that case, add something like `-P /var/tmp/refdbd.pid` to the command line mentioned above. If `postmaster` (the PostgreSQL database server) is installed on a remote box or if the security settings require it, you may have to use the `-h hostname` and/or the `-U username` options to run the `psql` client as shown below (most fresh PostgreSQL installations on Unix-style systems use "pgsql" with no password as the default database administrator. The Cygwin port of PostgreSQL uses the name of whoever installed the package, usually "Administrator". On Debian you need to be logged in as user "postgres": first `su root`, then `su postgres`). `postmaster` needs to be up and running and you need the appropriate permissions, of course. See the PostgreSQL documentation for further details.

Instead of using `refdbd`, you can also create the main database using your database engine client:

- In a command line window, run the command:

      		~$
      		createdb -U pgsql -E UNICODE refdb

  The data that you will import in the following steps are UTF-8 data. If you wish to use a different encoding, convert the dump file and adapt the above command accordingly.

- Then run this command:

      		~$
      		psql -U pgsql refdb < /usr/local/share/refdb/sql/refdb.X.dump.pgsql

  Use the highest dump file number 'X' shipped with your current RefDB version. Adapt the path to the script accordingly if you configured RefDB to put the data directory somewhere else. This SQL script will generate the necessary table definitions and fill in a few values. PostgreSQL will notice you that it is going to truncate a few identifier names. It is safe to ignore these messages.

- Access control works through user groups. To be able to access the main database, create a RefDB user group like this:

      		~$ psql -U pgsql refdb -c "CREATE GROUP refdbuser"
      		~$ psql -U pgsql refdb -c "GRANT SELECT ON CITSTYLE, POSITIONS, REFSTYLE, SEPARATORS, t_journal_words, t_meta TO GROUP refdbuser"

##### SQLite

Run the following command from your root account to let `refdbd` create the main database:

    	    ~$
    	    refdbd -a

If the default setup described above does not suit your needs, please use the following procedure instead to set up the main database.

- The default database directory is `/usr/local/var/lib/refdb/db`. RefDB will look here unless you selected a different data directory when configuring the application. If you want to keep your databases somewhere else, use the `dbpath` variable in `refdbdrc` and modify the following instructions accordingly.

      		~$
      		cd /usr/local/var/lib/refdb/db

- Run the following command to create the database and load the data:

      		~$
      		sqlite refdb < /usr/local/share/refdb/sql/refdb.X.dump.sqlite

  Use the highest dump file number 'X' shipped with your current RefDB version.

#### The SGML/XML support files

The RefDB package comes with a few additional scripts and stylesheets for the creation of bibliographies. These files are installed in the package data directory (usually `/usr/local/share/refdb`) and its subdirectories, but you should spend a little time to integrate them into your SGML system.

To this end, add the catalog file `/usr/local/share/refdb/refdb.cat` to your `SGML_CATALOG_FILES` environment variable. This is a master catalog with CATALOG directives for all catalog files supplied by RefDB.

#### The shell scripts

The RefDB shell scripts and Perl scripts were installed in `/usr/local/bin` unless you chose a different install root during configure. As RefDB attempts to insert the correct settings during the build process, it should not be necessary to manually customize these scripts. If you still want to fiddle with the settings, the variables are clearly marked within a user-customizable section at the top of each script.

If you want to use a Java XSL processor with the `refdbxml` script, you'll have to check the value of `CLASSPATH` in the script. The value must match the actual location of your `.jar` files and the current versions you've installed.

## Testing your installation

Now that you got this far, you surely want to see whether your setup actually works. To this end, you may want to run the following tests and see what happens. For your convenience you should perform this test in a graphical environment running at least two console windows.

- For our first tests it is desirable to have debug information directly available. Therefore you should start refdbd from the root account with some special parameters. Before going ahead you should make sure that you do not have a refdbd process already running, e.g. because you've setup your system to start that daemon at system startup. The following command will kill any refdbd processes. It will do no harm if no such process is running.

      	  #~
      	  refdbctl stop

  If you see an error message saying refdbctl: command not found then your installation failed or your `PATH` environment variable is not set properly.

- Now that we know that there is no other refdbd process around, we'll start a fresh one with special properties: We'll run it in a separate xterm as a standalone application and have it write debug information to stderr. This way, RefDB will be slow, but we directly see what's going on.

      	  #~
      	  refdbd -s -e 0 -l 7

  If you try to access refdbd from a different box, you should also use the `-I` switch to allow remote connections.

  refdbd should print some diagnostic information about its startup process and then wait for clients to connect. You may experience problems at this point if the access rights do not allow refdbd to create its PID file. This is why we run the test process as root, but if you plan to set up RefDB for use with a different account, this is a good time to check and try out these access rights. You may use the `-P` option to provide the path to a PID file that you have write access to in order to run refdbd from an unprivileged account.

  refdbd checks the availability of libdbi database drivers during the startup procedure. The following messages indicate a problem with libdbi:

  error while loading shared libraries: libdbi.so.0: cannot open shared object file: no such file or directory

    This is a common problem if you build your system from packages, but have to build some libraries (like libdbi, as shown here) from the sources. libdbi and most other autotools-based programs are installed into `/usr/local` by default. On some systems (like Debian, Ubuntu) the linker does not peek into `/usr/local/lib` for shared objects. To fix this, please add `/usr/local/lib` to `/etc/ld.so.conf` and run `ldconfig`(8), or configure the libraries to install into `/usr/lib` instead. See `./configure --help` for further instructions.

  Unable to initialize libdbi! Make sure you specified a valid driver directory

    You should see a few lines before this message which libdbi driver directory refdbd attempted to use. Either the default directory is not where the drivers are, or you specified an incorrect driver directory.

  Initialized libdbi, but no drivers were found!

    The libdbi library was not able to locate or properly load at least one database driver. Please check the libdbi installation and make sure you've installed at least one database driver. Remember that on most systems the libdbi-drivers package is distributed separately from the libdbi package which contains only the framework, but no drivers. This error also occurs if you install driver versions which are too old for the libdbi framework.

  If refdbd successfully loads libdbi, it will list the available database drivers. Make sure the driver for the database engine you use is listed.

- Now switch to a different xterm and start the refdba client. The client can basically run from any user account, but the username and password settings have to be those of a database administrator. We're talking about that username and password that you would provide to the command line client of your database server (`mysql` or `psql` for MySQL and PostgeSQL, respectively) for administrative tasks. The username and password settings are either provided by the corresponding configuration file `~/.refdbarc`, or by using the command line options `-u <dbadmin>` `-p <dbadmin-password>`. In the first case, that is if you set up your configuration file properly, you can just say:

      	  #~
      	  refdba

  In the second case you have to use this instead:

      	  #~
      	  refdba -u <dbadmin> -w <dbadmin-passwd>

  In both cases the client should start up and wait for your commands with a friendly prompt.

- At first you might try and see whether the RefDB programs read their configuration files properly. To this end, first run the following refdba command:

      	  refdba:
      	  set

  This will list the current settings of all configuration variables. Make sure these values are what you want. The most important variables are: username and passwd (you won't see the value of the latter for security reasons, though), as well as the host name or IP address of the box that runs refdbd. As we currently run both the server and the client on the same box, please make sure that the value of serverip is "127.0.0.1".

- Now try to send a command to the server. We use a command that does not require database access, but it will tell us whether we can connect to the server properly:

      	  refdba:
      	  viewstat

  Several things can happen. If you get several lines of output, telling you about the database server used and about a few refdbd variables, you're fine. This output may look like the following:

      You are served by: RefDB 0.9.4
      Client IP: 127.0.0.1
      Connected via pgsql driver (dbd_pgsql v0.7.1)
      to: PostgreSQL 7.2.1 on i386-portbld-freebsd4.3, compiled by GCC 2.95.3
      serverip: localhost
      timeout: 180
      dbs_port: 5432
      logfile: /home/markus/prog/refdb/pseudotest/log/refdbd.log
      logdest: 0
      loglevel: 7
      remoteadmin: off
      pidfile: /home/markus/refdbd.pid

  If you get the following message instead: could not establish server connection, check that refdbd is still running and that the serverip setting in refdba is correct. If you try to access refdbd from a remote box, make sure the server was started with the `-I` option. The error may also result from the fact that you failed to create the common database `refdb` or that you did not use the appropriate database server administrator username and password when starting refdba. Finally, your system may lack the runtime client library of the database server.

  The error message failed to connect to database server shows that your client can talk to refdbd, but that in turn can't talk to the database server. This may be due to incorrect username/password settings or incorrect permissions with the database servers that support user authentication. If you use SQLite as the database engine, you may have specified an incorrect database directory.

  A third possible outcome of this test is the message "main database too old or corrupt". Sometimes this is just what it says, e.g. if you upgraded to a newer version without re-creating the main database although the `UPGRADING` file told you to do so. However, the most likely reason is an incorrect setting in the `refdbdrc` config file. Please check that the `dbserver` variable matches the database engine that you created the main database for. The default is sqlite.

This is all it takes to test the basic functionality of your setup. Everything beyond this is either site-specific setup or mere usage of the tools. Please peruse the manual, especially the hints about getting your database access rights correct.

## SRU support

In addition to its native clients, RefDB also supports optional read access through a web-based search protocol called SRU (Search and Retrieve via URL). There are two options to enable SRU access. We'll first describe a CGI script which is the preferred way but requires a running web server on your system. The subsequent section describes a simpler standalone server for testing purposes and for single-user access.

### Setting up SRU support as a CGI program

In order to provide SRU services at your site, you need to add a CGI script to your web server. The following instructions assume that you use Apache as your web server. However, the CGI script will work just fine with any other web server that provides CGI support.

#### Configure your web server

If your web server is already set up to run CGI scripts, you might be all set to run the SRU CGI script as well. If you're not sure, follow the instructions below and check whether the your configuration file already has the relevant entries.

The Apache web server uses a configuration file called `httpd.conf`. On many systems this file is located in `/usr/local/etc/apache`. Locate the section starting with "<IfModule mod_alias.c>" and make sure it declares a CGI directory:

        ScriptAlias /cgi-bin/ "/usr/local/www/cgi-bin/"

You can choose a different directory, but the directory listed here must exist and be accessible from the account the web server runs in (often "www" or "nobody").

Now you have to allow the execution of CGI scripts in that directory:

        <Directory "/usr/local/www/cgi-bin">
            AllowOverride None
            Options ExecCGI
            Order allow,deny
            Allow from all
        </Directory>

Finally, you have to restart your web browser to let these changes take effect:

    ~# apachectl restart

#### Install the SRU CGI script

First you need to make sure the `/cgi-bin/` directory configured above exists and has the proper permissions. Local habits may vary, but you should see something like this:

    ~# ls -ld /usr/local/www/cgi-bin
    drwxr-xr-x  2 root  wheel  512 Mar 13 14:56 cgi-bin

In the Apache default installation `/usr/local/www/cgi-bin` is a symbolic link to an example CGI directory. Remove the symlink and create a real directory with the appropriate ownership and permissions instead.

Now copy the `scripts/refdbsru` CGI script into that directory and make it executable for all:

    ~# cp refdbsru /usr/local/www/cgi-bin
    ~# chmod a+x /usr/local/www/cgi-bin/refdbsru

All SRU replies are XML files. This is just fine if the requesting agent is a program that intends to further process the data, or to store them somewhere. If the requesting agent is a web browser with a human being in front of it, the plain XML output is a bit hard on the eyes though. It is recommended to provide XSLT stylesheets which can render the XML output in a human-readable HTML format (most current web browsers support XSLT these days). These stylesheets are used by default, unless a user provides the URL of a stylesheet of his own.

Unless you already have a designated folder for system-wide stylesheets, just create one, and make sure it is readable:

    ~# mkdir -p /usr/local/www/data/styles
    ~# chmod a+r /usr/local/www/data/styles

Now copy the example stylesheets shipped with RefDB (installed in `/usr/local/share/refdb/sru`) into that directory:

    ~# cp refdbsru.xsl mods.xsl risx.xsl refdbsru.css /usr/local/www/data/styles

Needless to say, you can tweak all these stylesheets to your heart's content.

Finally you should provide a configuration file called `refdbsrurc` which usually goes into `/usr/local/etc/refdb/`. You'll find a preconfigured example file in the same directory which you can copy and edit. Make sure the `xslurl` variable points to the `refdbsru.xsl` file that you've just installed. The value of this variable is an absolute or relative URL in the filesystem of the web server. If your setup is as described above, /styles/refdbsru.xsl will work just fine. It is recommended to set the variables starting with `zeerex_` to meaningful values. These values determine part of the output of the `explain` SRU command and are supposed to provide the users of your site with useful information about your SRU service.

#### Tune the SRU CGI script

From refdbd's point of view, the refdbsru CGI script is just another client. The script therefore requires a similar configuration file like the other clients, and it needs a database account to work with. For the configuration of the script, see the refdbsru reference.

As SRU provides only read access to your databases, it is recommended to create a separate database account for SRU accesses which all SRU users share. If you specify these values in the configuration files, the SRU users will not have to provide any login information. You may want to restrict that account to read access only using the appropriate switch of the adduser command.

#### Test the SRU CGI script

Open your favourite web browser and enter the following URL:

    localhost/cgi-bin/refdbsru

You should now receive an XML document that describes the RefDB SRU service. If you receive a web server error instead, retrace your steps above and make sure you have restarted the web server before testing. If nothing else helps, please peruse the documentation of your web server. The appropriate document for Apache is the CGI HowTo.

Finally, you should advertize the new service on your web site. Provide a link to "<hostname>/cgi-bin/refdbsru" along with some instructions how to use SRU, as explained in the user manual.

### Setting up SRU support using a standalone web server

RefDB also provides a standalone web server to run the SRU service. All you need to do in terms of "installation" is to create or edit the SRU configuration file that the standalone server shares with the CGI application. See also the refdb-sruserver reference. Then start the SRU server like this:

    ~# [perl] refdb-sruserver

The server will run in the foreground until you kill it with Ctrl c. Now point your web browser to:

    localhost:8080

As you can see, the SRU server uses the non-standard port 8080 so it does not interfere with any regular web server. This also means that the standalone SRU server is usually not accessible from a remote computer unless you configure your firewall appropriately. However, as long as you connect locally you should receive the output of the SRU explain command.

## Install the PHP interface

If you want to provide interactive access to your RefDB databases through the web, consider installing the PHP web interface. This web frontend provides a convenient way to perform the most common user tasks, like running queries or adding datasets.

### Prerequisites

Please check the following prerequisites on your computer before attempting to install the PHP interface

Web server

  Any web server that is capable of running PHP scripts. If you don't run a web server anyway, Apache is always a good choice to start with. Both versions 1.3.x and 2.x will work just fine.

PHP interpreter

  You need PHP5, the older PHP4 won't do. When building PHP, make sure to configure the software appropriately so the php5 Apache module gets built. If you install a prebuilt package, you may have to select an extra package that contains the appropriate module for your web server.

  With the exception of session support, the RefDB PHP interface relies solely on core features of PHP5. You may therefore have to install PHP5 session support separately. However, on some systems like FreeBSD, "core" does not mean "it's there". If the PHP5 core is split into several packages, you may also have to install DOM, XML, and XSL support separately.

### Web server configuration

The following instructions assume that you use Apache as your web server. The configuration file is usually `/etc/apache/httpd.conf` or `/usr/local/etc/apache/httpd.conf`.

- Locate the section "Dynamic Shared Object (DSO) Support". Check if the php5 module is loaded anyway. If not, add a line like the following:

      LoadModule php5_module    libexec/apache/libphp5.so

- The subsequent section in the config file needs to be updated too if you had to add the php5 module:

      AddModule mod_php5.c

- Further down there should be a section containing Aliases. Create a new one within this section like this:

          Alias /refdb/ "/usr/local/share/refdb/www/"

          <Directory "/usr/local/share/refdb/www">
              AllowOverride None
              Order allow,deny
              Allow from all
              AddType application/x-httpd-php .php .phtml
          </Directory>

  The paths point to the files that RefDB installs with all other shared files. If you intend to customize or modify the interface, you can copy the files to a directory in your home folder and change the directories in the config file accordingly.

- Finally you'll have to let the Apache server re-read it's configuration file:

      ~# apachectl restart

### Test your PHP interface

To see the PHP interface in action, first make sure that the RefDB application server is running:

    ~# refdbctl start

Now start your web browser and point it to:

    localhost/refdb/

Please note the trailing slash! Now you should be greeted by the login screen.