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.

  1. 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.

  2. 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.

  3. 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:


    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.

  4. 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:


    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 "".

  5. 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:


    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:
    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.