SYNOPSIS
Interactive mode:
- refdba [-c pager-command] [-e log-destination] [-f stdin] [-h] [-i IP-address] [-l log-level] [-L log-file] [-p port] [-q] [-T time] [-u name] [-v] [-V] [-w password] [-x] [-y confdir]
- Non-Interactive mode:
- refdba -C command [-c pager-command] [-e log-destination] [-f stdin] [-i IP-address] [-l log-level] [-L log-file] [-p port] [-q] [-T time] [-u name] [-w password] [-x] [-y confdir]
DESCRIPTION
OPTIONS
-c pager-command
- The command line of the pager that is to be used. Instead of a pager you can of course specify any valid command that accepts data on stdin. Use "stdout" to request data output to stdout. This is the default, but you may want to specify it on the command line if you need to temporarily override a default pager setting in your configuration file.
-C command
- The command to be run in non-interactive mode. You can supply all options and parameters that the command accepts on the refdba command line.
-e log-destination
- log-destination can have the values 0, 1, or 2, or the equivalent strings stderr, syslog, or file, respectively. This value specifies where the log information goes to. 0 (zero) means the messages are sent to stderr. They are immediately available on the screen but they may interfere with command output. 1 will send the output to the syslog facility. Keep in mind that syslog must be configured to accept log messages from user programs, see the syslog(8) man page for further information. Unix-like systems usually save these messages in /var/log/user.log. 2 will send the messages to a custom log file which can be specified with the -L option.
-f stdin
- Read data from stdin. refdbc usually knows when it should read from stdin. However, a few commands use data supplied in the command line but also allow to read from a file. Use this option to force refdbc to read from stdin in addition to values supplied on the command line.
-h
- Displays help and usage screen, then exits.
-i IP-address
- Set the IP address of the box which is running the application server refdbd(1). Instead of the IP address you can also specify the hostname as long as it can be properly resolved by your system.
-l log-level
- Specify the priority up to which events are logged. This is either a number between 0 and 7 or one of the strings emerg, alert, crit, err, warning, notice, info, debug, respectively (see also Log level definitions). -1 disables logging completely. A low log level like 0 means that only the most critical messages are logged. A higher log level means that less critical events are logged as well. 7 will include debug messages. The latter can be verbose and abundant, so you want to avoid this log level unless you need to track down problems.
-L log-file
- Specify the full path to a log file that will receive the log messages. Typically this would be /var/log/refdba.
-p port
- Set the port of the box which is running the application server.
-q
- Start without reading the configuration files. The client will use the compile-time defaults for all values that you do not set with command-line switches. Useful for debugging config files.
-T time
- Set the timeout for client/application server dialogue in seconds. A connection with unsuccessful read or write attempts will be considered as dead and taken down after this amount of time has elapsed.
-u name
- Set the username for the database access. Note: This username need not be identical to the login name of the user. This is the username required to access the database server.
-v
- Prints version and copyright information, then exits.
-V
- Switches to verbose mode.
-w password
- Set the password for the database access. Note: This password need not be identical to the login password of the user. This is the password required to access the database server.
-x
- Send passwords unencrypted.
-y confdir
- 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.
DIAGNOSTICS
The exit code is 0 if all went fine. It will be 1 if the command (when run in batch mode) or the last command (when run in interactive mode) returned an error, or if there was a general error condition during startup like a lack of available memory.
CONFIGURATION
refdba evaluates the refdbarc configuration file at startup to initialize itself.
Table 1. refdbarc
Variable | Default |
Comment
|
logfile | /var/log/refdba.log |
The full path of a custom log file. This is used only if logdest is set appropriately. If you start refdba from the command line as a regular user, you should specify a file that you have write access to (you may not be allowed to create /var/log/refdb.log or write to this file as a regular user).
|
logdest | 2 |
The destination of the log information. 0 = print to stderr (this is mainly intended for debugging, as it may visually interfere with command output); 1 = use the syslog facility; 2 = use a custom logfile. The latter needs a proper setting of logfile.
|
loglevel | 6 |
The log level up to which messages will be logged. A low setting (0) allows only the most important messages, a high setting (7) allows all messages including debug messages. -1 means nothing will be logged.
|
pager | stdout |
The command line of a pager that accepts the output of refdb on stdin to allow scrolling and other nifty things. "stdout" sends the data to stdout.
|
passwd | * |
The password which is used for authentication with the database server. It is potentially evil to store unencrypted passwords in disk files. At least make sure that the configuration file is not readable for anyone else. The default setting causes refdba to ask for your password interactively.
|
port | 9734 |
The port on which refdbd listens. Change this for all clients and the server if this value interferes with another program using this port.
|
serverip | 127.0.0.1 |
The IP address or hostname of the machine where refdbd runs. Use the default (localhost) address if the clients and refdbd run on the same machine.
|
timeout | 180 |
The timeout in seconds. After this time has elapsed, a stalled connection is taken down. Increase this value if you encounter frequent timeout errors due to high network traffic or refdbd overload.
|
username | login name |
The username which is used for authentication with the database server. This may be different from the login name of the user.
|
verbose | f |
Set this to t if you prefer verbose error messages.
|
no_encrypt | f |
If set to 't', passwords are transmitted unencrypted. The default is to encrypt passwords.
|
COMMANDS
All commands consist of a single word which specifies the command. This may be followed by arguments and/or switches. The general syntax rules of the getopts library apply.
addstyle
-c command
-h
-o filename
-O filename
style-file
Synopsis
refdba: addstyle j.biol.chem.xml pharmacol.rev.xml
This will add the style specifications contained in the files j.biol.chem.xml and pharmacol.rev.xml to the bibliography style database.
adduser
If a user is not yet known to the database server, refdb will create an account with the default access rights (=none). If you do not specify a password for the new user with the
-W
option (see below), the user will have access to the database server with the default password "refdb". In most cases this is not a good thing.
A new user will automatically get access to the internal refdb database refdb.
Some database engines like SQLite do not support access control. The
adduser
command is not supported with these engines and will just return an explanatory message.
-d database
-f file
-h
-H hostname
-R
-W password
username
Synopsis
Note
Note
This option is only supported by MySQL. It is ignored if you use PostgreSQL as your database server. Please see the PostgreSQL documentation for help on how to manipulate host-based access control with the
pg_hba.conf
file.
refdba: adduser -d db1 -N newpassjim
This will grant access to the database db1 for the new user jim. refdbd runs on the same computer as the database server (if you leave out the -H option, localhost is assumed). "jim" will have to provide "newpass" as a password when starting one of the refdb clients.
-
refdba: adduser -d db1 -H mono.mycomp.com jim jane
This will grant access to the database db1 for the users jim and jane. refdbd runs on the computer with the name "mono.mycomp.com". If "jim" and "jane" are already known to the database server, they will keep their existing passwords. If not, they will have to use the default password "refdb".
If you as the refdb administrator do not have GRANT permission on your database server, the
adduser
command is bound to fail. As a security-minded person your database administrator might refuse to run refdba regardless of how often you ensure him it doesn't contain malicious code. He'll want to do it the hard way, and this is what he needs to do:
Alternatives on sites with restricted database server access
addword
-f file
-h
word
Synopsis
Note
refdb will convert all reserved words to uppercase internally, so it does not matter which case you provide these words in.
refdba: addword -f wordlist FOO BAR
This will add all reserved words in the file wordlist as well as the words "FOO" and "BAR" to the list of reserved words.
confserv
This command will only reconfigure refdbd transiently. All changes are lost when the application server is restarted. To make permantent changes to the configuration, edit the init-file or change the command-line parameters in the script that starts refdbd. Please note also that
remote administration
must be enabled for this command to work.
The following commands are available:
stop
ping
serverip value
timeout value
logdest value
logfile value
loglevel value
Synopsis
Note
Note
This command affects only the refdbd parent process. Any children that may be currently serving clients will continue to do so until they are done.
refdba: confserv loglevel 7
This will set the log level to 7. This temporary change will only be effective until refdbd is restarted.
createdb
-E encoding
-h
name
Synopsis
[1]
encoding name. If you do not use this option, the new database will use the default encoding of the database server unless your refdbdrc configuration file sets a default with a "db_encoding" entry.
Tip
Prepend a constant string like
"rd"
to all refdb database names. This speeds up retrieving refdb databases with the
listdb
command if your database engine manages additional, non-RefDB databases. Use a simple regular expression like
"rd%"
to restrict your search to RefDB databases.
refdba: createdb db1 -E UTF-8 db2
This will create the databases db1 and db2 with the character encoding UTF-8.
refdb contains two plain-text SQL scripts (installed in
/usr/local/share/refdb/sql) to create database tables just like the
createdb
command does. These scripts are preferable to the command in these cases:
The following procedures are equivalent to running the createdb command. If you want to add the tables to an existing database, please adapt the scripts and/or the procedures accordingly.
Using SQL scripts to create databases
#~ mysql -e "CREATE DATABASE dbname"
-
#~ mysql dbname < empty.mysql.dump
-
•
If you're using PostgreSQL, the following sequence should work (again, provide additional options like username and password as required):
-
#~ sed 's/refdbtest/dbname/g' < empty.pgsql.dump.in > empty.pgsql.dump
-
#~ psql template1 < empty.pgsql.dump
-
The empty.pgsql.dump.in script contains the commands to create a database and to set appropriate access rights for a new group of database users. Therefore it is a good idea to replace the string "refdbtest" with the intended name of your new database. The sed command in the first line does just this. You may also edit a few more things, like the encoding. The second command actually creates the database, a new group, grants privileges to this group, and creates all necessary tables and sequences. template1 is a PostgreSQL system database. The psql command requires the name of an existing database as an argument, but in this case you could use any other existing database just as well.
deletedb
The database structure and the data will be gone, really gone, so be careful with this command. Think twice and, if in doubt, at least make a backup first to avoid extensive hairpulling.
-h
dbname
Synopsis
Caution
refdba: deletedb db1 db2
This will delete the databases db1 and db2.
deletestyle
Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
-h
unix-regexp
Synopsis
Note
refdba: deletestyle J\..*
This will delete all bibliography styles that start with "J.".
deleteuser
Some database engines like SQLite do not support access control. The
adduser
command is not supported with these engines and will just return an explanatory message.
refdb will only revoke the access rights to the specified database. It will revoke neither access rights to the internal database refdb, nor will it revoke database server access. You can revoke access to the internal database by specifying "refdb" with the
-d
option. To revoke access to the database server, please use the command line utilities of your database server.
-d database
-f filename
-h
-H hostname
-R
username
Synopsis
Note
Note
This option is only supported by MySQL. It is ignored if you useother database engines.
refdba: deleteuser -d -H % db1jim
This will revoke the access to the database db1 for the user jim for all but local connections.
deleteword
-f
-h
word
Synopsis
Note
refdb will convert all reserved words to uppercase internally, so it does not matter in which case you provide these words.
refdba: deleteword -f wordlist FOO BAR
This will delete all reserved words in the file wordlist as well as the words "FOO" and "BAR" from the list of reserved words.
getstyle
-c command
-h
-o
-O
style
Synopsis
Warning
Be careful with the append (-O) option. refdb will output the processing instructions, the doctype line, and one
CITESTYLE
element for each individually requested style. If you concatenate the results of several
getstyle
calls, the resulting XML file will not be well-formed without further processing. In order to write several styles into a single XML file, use a single
getstyle
call and list all required styles as arguments. This will output the styles wrapped in a
STYLESET
element, resulting in a valid XML file.
refdba: getstyle -o j.biol.chem.xml J.Biol.Chem.
This will write the style specification stored under the style name "J.Biol.Chem." to the file j.biol.chem.xml.
help
Synopsis
refdba: help
listdb
In order to tell refdb reference databases apart from other databases maintained by your database server, refdbd has to peek into each database returned by the database server. Depending on the number of available databases this may take some time. Therefore it may be a good idea to use a common prefix for all refdb databases as explained in the section about the
createdb
command.
-h
database-regexp
Synopsis
Note
refdba: listdb db%
This will list all databases with names that start with the string "db".
liststyle
-h
style-regexp
Synopsis
Note
Some database engines, like SQLite, do not support
Unix-style regular expressions. Use
SQL regular expressions
instead.
refdba: liststyle ^J.*
This will list all bibliography styles that start with a capital "J".
listuser
-d database
-h
name-regexp
Synopsis
Note
Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
refdba: listuser -d refs ^mo.*
This will list all users of the database "refs" whose names start with "mo".
listword
Keep in mind that the journal words are uppercased internally. You should write your
unix-regexp
using all caps accordingly.
-h
word-regexp
Synopsis
Note
Note
Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
Note
For a brief description of the purpose of reserved words, see the
addword
command.
refdba: listword ^BIO.*
This will list all reserved journal words that start with "BIO".
scankw
As this command will cause a huge number of database accesses it is best scheduled to run automatically as a cron job at a time of low use, either nightly or on weekends.
Please note the difference between the full keyword scan and the automatic keyword scan which can be requested by the
refdbd
command line switch
-K
or the corresponding
configuration variable
keyword_scan. The full keyword scan is "retrospective", i.e. it will add keywords that were added later to previously existing references. The automatic keyword scan will only add existing keywords to newly added references, thus causing less impact on the database performance while users are likely to access the database.
-d database
-h
Synopsis
set
If you call
set
without any arguments, it will display a list of all configuration variables with their current values.
If you call
set
with one argument, it will display the current value of this particular variable.
If you call
set
with two arguments, it will set the variable (first argument) to the new value (second argument) for the current session. To specify an empty value, use two quotation marks like this:"".
For obvious reasons,
set
will never display the current password although you can certainly change the password with this command. To make sure no one else sees the new password that you enter, run the command
set passwd *. You will then be asked to enter a password which will not be echoed on the screen.
This command is not available in batch mode, use the command line switches instead. In the interactive mode, the changes to the configuration variables are limited to the current session. If you want to change the values permanently, you should rather edit one of the configuration files.
-h
varname
varvalue
Synopsis
Note
refdba: set timeout 90
This command will set the timeout to 90 seconds for the current session.
verbose
-h
Synopsis
refdba: verbose
Depending on the previous setting, this will toggle the verbose mode on or off.
viewstat
-h
Synopsis
refdba: viewstat
This will print some connection statistics and informations on the screen.
FILES
PREFIX/etc/refdb/refdbarc
- The global configuration file of refdba.
$HOME/.refdbarc
- The user configuration file of refdba.
AUTHOR
refdba was written by Markus Hoenicka <[email protected]>.
NOTES
- 1.
-
IANA