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
	

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:

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.