This section explains how to control refdbd from the command line. The easiest and strongly recommended way is to use the provided control script that will be explained in the first subsection. If you need further control, you can use the command line of refdbd directly as explained in the second subsection.
The refdb package includes the refdbctl script which is installed in /usr/local/bin. This is a simple shell script to start, stop, restart, and reconfigure refdbd from the command line. The very same script is also used if you have instructed init(8) to start and stop refdbd.
refdbctl accepts the following arguments:
refdbctl start will try to start the daemon. refdbd will be called without any command-line parameters so all configuration parameters should be set in refdbdrc. The script prints a diagnostic message whether or not the daemon was successfully started. If the daemon is already running when you issue this command, the script will not try to start another process.
refdbctl stop will try to stop the daemon. This is done by sending the process the TERM signal. The script prints a diagnostic message whether or not the daemon was successfully stopped. If the daemon is not running when you issue this command, the script will print a diagnostic message.
refdbctl reload will cause the daemon to reload its configuration file by sending the process the HUP signal. The script prints a diagnostic message whether or not the daemon configuration was successfully reloaded. If the daemon is not already running when you issue this command, the script will not try to start it.
refdbctl restart will terminate the daemon and start it again. If the daemon is not yet running, this command will not attempt to start it.
Calling refdbd directly allows you to pass configuration parameters on the command line. Start refdbd with the command:
refdbd [-b dbs-port] [-d default-database] [-D dbserver] [-e log-destination] [-E encoding] [-h] [-i IP-address] [-I] [-k] [-K] [-l log-level] [-L log-file] [-p port] [-P PID-file] [-q] [-r] [-s] [-T time] [-U] [-v] [-V] [-y confdir] [-Y libdbidir]
The command-line switches are:
Set the port on which the database server listens for incoming connections. The default is 3306 for MySQL and 5432 for PostgreSQL.
Set a default database to be used for all client queries that do not specify a database.
Select the database server. Currently the values mysql, pgsql, and sqlite are supported to select MySQL, PostgreSQL, and SQLite, respectively.
This specifies the destination of the log information. If destination is 0 or "stderr", the log output is sent to stderr. This should only be used for debugging purposes when refdbd is not run as a daemon.
If destination is 1 or "syslog", the syslog facility of the system is used. syslog has to be configured properly to accept refdb's log output. Consult the syslogd(8) man page how to achieve this.
If destination is 2 or "file", a custom log file as defined by the -L switch is used instead. If this log file cannot be written to, refdbd falls back to using syslog.
Select the default character encoding for new databases. This feature is currently supported only by PostgreSQL (and only if PostgreSQL was built with the --enable-multibyte option). See the PostgreSQL manual for a full list of supported encodings. As of this writing, SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE, MULE_INTERNAL, LATIN1 through LATIN5, KOI8, WIN and ALT are available. You can override this default by using the -E option of the createdb command.
Displays help and usage screen, then exits.
For external database servers, set the IP address of the box which is running the database server. Instead of the IP address you can also specify the hostname as long as it can be properly resolved by your system. If the database server runs on the same box as refdbd, use "localhost".
Note: If "localhost" does not seem to work, try specifying the real IP address of the box instead - some database client libraries refuse to use TCP/IP for local connections which may cause mayhem on particular systems.
For embedded database engines, set the directory which contains the database files.
Set this switch to allow remote connections to refdbd. Otherwise only connections from localhost (127.0.0.1) will be answered.
refdb stores up to four names (full name, official abbreviation, and two user-defined abbreviations) of each periodical. These synonyms are shared by all references that use one of these periodical names. As it sometimes requires some effort to get at the synonyms (public reference data often contains only the official abbreviation), it is desirable to keep these synonyms even if you remove the last reference that uses a particular periodical name. If you use the -k option, the synonyms will not be removed from the database and will be available immediately if you add a new reference using that particular periodical name.
If this option is used, refdbd will run an automatic keyword scan each time you add or update references. refdbd will scan the title fields and the abstract field of the modified references for any keywords already present in the database but not in the particular reference. This increases the usability of keywords in queries. There is no speed decrease for the user interaction as the keyword scan is performed in the background. See also the related refdba command scankw which performs a more thorough manual keyword scan.
Set the log level to a value between 0 and 7 or to a string value as described in log level definitions. 0 means that only critical log messages will be logged, while a value of 7 means that every log message will be logged. Set level to -1 to disable logging.
| Caution |
|
Use log level 7 with caution and only for debugging purposes. Every SQL command and a plethora of other messages will be logged. This slows down the application server considerably and has the potential to grind your server to a halt by completely clogging the hard drive :-). |
This switch specifies a custom log file (full path please). This will only be used if the -e switch is set accordingly.
| Warning |
|
If you start refdbd as a regular user, you may not have write access to the default log file. In this case, use this option to specify a file that you can write to, e.g. /home/username/refdbd.log. |
Set the port on which refdbd listens for incoming connections. The default is 9734.
Specify the full path of the file that refdbd writes its process ID to. This PID simplifies stopping and reconfiguring the application server from the command line. The default value is /var/log/refdbd.pid.
| Warning |
|
If you start refdbd as a user, you may not have write access to the default PID file. In this case, use this option to specify a file that you can write to, e.g. /home/username/refdbd.pid. |
Start without reading the configuration file.
Enables remote administration via refdba.
Starts as a standalone application, not as daemon.
Set the timeout for client/application server dialogue in seconds.
This switch causes refdbd to automatically uppercase all citation keys of newly added references. This makes it more convenient to work with SGML bibliographies.
Prints version and copyright information, then exits.
Switches to verbose mode. To be honest, currently this doesn't make much of a difference.
Specify the directory where the global configuration files are
Note: By default, all refdb applications look for their configuration files in a directory that is specified during the configure step when building the package. That is, you don't need the -y option unless you use precompiled binaries in unusual locations, e.g. by relocating a rpm package.
Specify the directory where the libdbi drivers are
Note: By default, libdbi (the database abstraction library used by refdb) looks for its driver files in a directory that is specified during the configure step when building the package. That is, you don't need the -Y option unless you use precompiled libdbi binaries in unusual locations, e.g. by relocating a rpm package.