table of contents
other versions
- jessie 1.0.2-3
REFDBA(1) | RefDB Manual | REFDBA(1) |
NAME¶
refdba - the administration client of RefDBSYNOPSIS¶
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:
Batch 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¶
refdba is a command-line client providing the commands to administer RefDB(7) databases, users, and styles. refdba can be started in an interactive mode, providing a command prompt. Type ? or help to see a list of available commands. Alternatively you can start refdba in non-interactive mode. refdba will execute the requested command and return. In this mode refdba will accept input on stdin for a variety of commands, allowing Unix piping.OPTIONS¶
-c pager-commandThe 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.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¶
Synopsisaddstyle [-c command] [-h]
[[-o filename] | [-O filename]]
{style-file...}
Adds one or more bibliography style specifications from the input file(s).
-c command
Specifies a command that will receive the output instead
of the default pager. This may be a different pager, any command that takes
input on stdin, or the string “stdout” to send the data to
stdout without using a pager.
-h
Displays the online help about the addstyle
command.
-o filename
Write the output to filename instead of to
stdout.
-O filename
Append the output to filename instead of writing
it to stdout.
style-file
All other arguments are interpreted as the names of files
containing style specifications.
refdba: addstyle j.biol.chem.xml pharmacol.rev.xml
adduser¶
Synopsisadduser {-d database} [-h]
{-H host-IP} [-R]
[-W password] {[ -f file] |
[username...]}
Grants access rights to a refdb database to the given users. Specify the
database with the -d option.
Note
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
Specifies the reference database for which the access
rights should apply.
-f file
Reads a whitespace-separated list of usernames from
file.
-h
Displays the online help about the adduser
command.
-H hostname
hostname specifies the host the refdb application
server runs on. If it runs on the same machine as the database server, you may
specify “localhost” as hostname. Use “%” as
hostname to allow access from all addresses except localhost. Otherwise, the
hostname argument can be either a hostname, an IP address, or a subnet that
specifies one or more computers to allow access from. You can add the same
user several times with different hostnames.
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.
-R
Use this option to grant read-only access for the user.
By default, users are granted read/write access. Users with read-only access
can basically only retrieve references and notes.
-W password
Set the password for a new user. The password is
encrypted before transferring it to the application server. If the user
already exists, his password will be changed accordingly.
username
All other arguments are interpreted as usernames. If
neither a username argument nor an input file is specified, refdba attempts to
read a whitespace-separated list of names from stdin. To force refdba to read
from stdin in addition to explicitly named users, use the -f
stdin option.
refdba: adduser -d db1 -N newpassjim
refdba: adduser -d db1 -H mono.mycomp.com jim jane
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:
•If you use MySQL as your database server, each
new user needs at least entries in the mysql.user and mysql.db tables. Your
database administrator might have set up his own rules, but in general the
mysql.user table should grant no privileges to the user, whereas the mysql.db
table should grant INSERT, SELECT, UPDATE, DELETE permissions to each user for
the refdb database and SELECT, INSERT, UPDATE, DELETE, CREATE, DROP privileges
for each reference database the user should have access to. Make sure to
mention that the Host field in mysql.user must contain the name or address of
the box that runs refdbd, which is not necessarily identical with the
workstation of the user.
•If you prefer PostgreSQL instead, things are a
little simpler. When you create a refdb database, a new group will be created
to manage access to this database. All your database administrator needs to do
is to add the new user to the groups refdbuser (granting access to the common
refdb database) and <dbname>user, where <dbname> is the name of
the reference database the user should be allowed to access.
addword¶
Synopsisaddword [-h] {[-f file] |
[word...]...}
Most bibliography styles use standardized abbreviations of the journal names.
Most data sources specify these abbreviations without dots, as in "Mol
Cell Biol". If the words are to be abbreviated with dots (as in
"Mol. Cell Biol.") in the bibliography, refdb needs to know which
tokens in the abbreviated name are indeed abbreviated (e.g. "Mol."),
and which are full words (e.g. "Cell"). To this end, refdb keeps a
list of reserved words which are known not to be abbreviations of something
else. refdb ships with a fairly complete list of such words, but if you detect
errors or omissions, the addword command comes in handy.
-f file
Read a whitespace-separated list of journal title words
from file.
-h
Displays the online help about the addword
command.
word
All other arguments are interpreted as reserved words. If
neither a word list nor an input file is specified, refdba attempts to read a
whitespace-separated list of words from stdin. To force refdba to read from
stdin in addition to explicitly listed words, use the -f stdin
option.
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
confserv¶
Synopsisconfserv {command} [value]
Configures the application server while it is running and does some tricks with
the refdb helper databases as well. Some of the commands modify variables that
can be set as command line arguments or with the init file. See Running the
refdbd daemon for more information about these variables.
Note
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
Stops the application server.
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.
ping
Checks whether the application server is still alive and
well. If this is the case, it will report the process IDs of the child that
handles your query and of the parent. If not, the connection will time out
with no response.
serverip value
Sets the database server IP address to
value.
timeout value
Sets the timeout in seconds to value.
logdest value
Sets the destination of log output to value.
Possible values are 0 (stderr), 1 (the system syslog facility), 2 (a private
log file as defined by logfile).
logfile value
Sets the filename of the log file to value.
loglevel value
Sets the maximum level of messages to be logged to
value. 0 means that only critical errors will be logged, 7 means that
all messages including the extremely verbose debug messages will be logged. -1
disables logging completely.
refdba: confserv loglevel 7
createdb¶
Synopsiscreatedb [-E encoding] [-h]
{dbname...}
Creates a new database with the name dbname. Several databases may be
specified in a single call of this command.
-E encoding
Select a character encoding for the new database. This is
currently only supported by MySQL and PostgreSQL. If you use a different
engine, this option is ignored. Please see the documentation of your database
engine installation for available encodings. The value passed with the
-E option should be the IANA[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.
-h
Displays the online help about the createdb
command.
name
The name of the reference database. The name must not
contain a colon (':') or a dash ('-') due to the citation formats in documents
using RefDB. The allowed characters may be further restricted by the database
engine you use. The database name should also be considered case-insensitive,
i.e. don't try to create a database "mybase" if you already have one
called "MYBASE". Also, avoid using names which are SQL reserved
words as this is doomed to fail. Unfortunately, this includes the all too
convenient name "references". Try "refs" or
"biblio" instead.
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
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:
•You do not have database administrator
permissions and have to ask your admin to create the databases for you. Your
admin might prefer to run the script as he can easily find out what it is
going to do.
•You want to integrate refdb with an existing or a
custom database system. In that case you want the refdb-specific tables in an
existing database in addition to non-refdb tables.
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.
•If you're running MySQL, use the following
commands (provide additional options like username and password as required):
#~ 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):
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.#~ sed 's/refdbtest/dbname/g' < empty.pgsql.dump.in > empty.pgsql.dump
#~ psql template1 < empty.pgsql.dump
deletedb¶
Synopsisdeletedb [-h] {dbname...}
Deletes the database with the name dbname. Several databases may be
specified in a single call of this command.
Caution
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
Displays a brief usage message and returns to the
prompt.
dbname
The name of the database to be deleted.
refdba: deletedb db1 db2
deletestyle¶
Synopsisdeletestyle [-h] {unix-regexp}
Deletes the bibliography styles whose names match the Unix regular expression
unix-regexp.
Note
Some database engines, like SQLite, do not support Unix-style regular
expressions. Use SQL regular expressions instead.
-h
Displays a brief usage message and returns to the
prompt.
unix-regexp
The remaining arguments are interpreted as a regular
expression which specifies the style or styles to be deleted.
refdba: deletestyle J\..*
deleteuser¶
Synopsisdeleteuser {-d database} [-h]
{ -H host-IP} {-R} {[-f file]
| [ username...]}
Revokes access rights to a refdb database from the given users.
Note
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
Specify the name of the database.
-f filename
Read the usernames from filename
-h
Displays the online help about the deleteuser
command.
-H hostname
Specify the hostname or IP address for which to modify
the access rights. This must be the same name that you used for a previous
call to adduser.
Note
This option is only supported by MySQL. It is ignored if you useother database
engines.
-R
Revokes read-only access.
username
All other arguments are interpreted as usernames. If
neither a username argument nor an input file is specified, refdba attempts to
read a whitespace-separated list of names from stdin. To force refdba to read
from stdin in addition to explicitly named users, use the -f
stdin option.
refdba: deleteuser -d -H % db1jim
deleteword¶
Synopsisdeleteword [-h] {[-f file] |
[ word...]...}
This command performs the reverse operation of addword. The specified reserved
words will be removed from the list.
-f
Read a whitespace-separated list of words from
file.
-h
Displays the online help about the addword
command.
word
All other arguments are interpreted as reserved words. If
neither a word list nor an input file is specified, refdba attempts to read a
whitespace-separated list of words from stdin. To force refdba to read from
stdin in addition to explicitly listed words, use the -f stdin
option.
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
getstyle¶
Synopsisgetstyle [-c] [-h] [[-o] |
[-O]] { style...}
Retrieves one or more bibliography style specifications from the database and
formats them as an XML file.
-c command
Specify a command that will receive the output instead of
the default pager. This may be a different pager, any command that takes input
on stdin, or the string “stdout” to send the data to stdout
without using a pager.
-h
Displays the online help about the getstyle
command.
-o
Write the output to a file instead of to stdout.
-O
Append the output to a file instead of writing it to
stdout
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.
style
All other arguments are interpreted as the names of
bibliography styles.
refdba: getstyle -o j.biol.chem.xml J.Biol.Chem.
help¶
Synopsishelp
?
Displays a brief summary of the available commands.
refdba: help
listdb¶
Synopsislistdb [-h] [database-regexp]
Lists all available databases if no argument is specified. If
database-regexp is specified, only the databases matching this
expression will be listed.
Note
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
Displays a help message explaining the listdb
command.
database-regexp
A valid SQL regular expression which limits the output to
matching database names.
refdba: listdb db%
liststyle¶
Synopsisliststyle [-h] [style-regexp]
Lists all available bibliography styles that match style-regexp. If no
argument is given, all available styles will be listed. This may or may
not be what you want.
-h
Displays a help message explaining the listdb
command.
style-regexp
A valid Unix regular expression which limits the output
to matching style names.
Note
Some database engines, like SQLite, do not support Unix-style regular
expressions. Use SQL regular expressions instead.
refdba: liststyle ^J.*
listuser¶
Synopsislistuser {-d database} [-h]
[name-regexp]
Lists all available users of the specified database that match
name-regexp. If no argument is given, all available users will
be listed. This may or may not be what you want.
-d database
Specify the database name.
-h
Displays a help message explaining the listdb
command.
name-regexp
A valid Unix regular expression which limits the output
to matching database user names.
Note
Some database engines, like SQLite, do not support Unix-style regular
expressions. Use SQL regular expressions instead.
refdba: listuser -d refs ^mo.*
listword¶
Synopsislistword [-h] {word-regexp}
Lists all available reserved journal words that match unix-regexp. If no
argument is given, all available words will be listed. This may or may
not be what you want.
Note
Keep in mind that the journal words are uppercased internally. You should write
your unix-regexp using all caps accordingly.
-h
Displays a help message explaining the listdb
command.
word-regexp
A valid Unix regular expression which limits the output
to matching journal title words.
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.*
scankw¶
Synopsisscankw {-d database}
[-h]
This command schedules a full keyword scan in the database specified with the
-d option. The abstract field as well as all title fields of all
references found in the database are scanned for the presence of all keywords
available in the database. If a match is found and the keyword is not yet
associated with that reference, the keyword is added to that reference. As the
time required to perform this operation increases with both the number of
references and the number of keywords, the keyword scan is performed in the
background and the command returns immediately on the client side. See the
server log for the results.
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
Specify the database name.
-h
Displays a help message explaining the listdb
command.
set¶
Synopsisset [-h] [varname] [varvalue]
The set command displays or modifies the values of configuration
variables.
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:"".
Note
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
Displays a help message explaining the listdb
command.
varname
The name of the variable whose value should be displayed
or set.
varvalue
The new value of the variable to be set.
refdba: set timeout 90
verbose¶
Synopsisverbose [-h]
Toggles the verbose mode on or off. If the verbose mode is on, the error
messages and warnings may be some more comprehensible.
-h
Displays a help message explaining the listdb
command.
refdba: verbose
viewstat¶
Synopsisviewstat [-h]
Shows the version numbers of the libdbi driver used to connect to your database
server as well as the version information of that server. It also shows the
current values of the variables that can be modified with
confserv.
-h
Displays a help message explaining the listdb
command.
refdba: viewstat
FILES¶
PREFIX/etc/refdb/refdbarcThe global configuration file of refdba.
$HOME/.refdbarc
The user configuration file of refdba.
SEE ALSO¶
RefDB (7), refdbd (1), refdb-backup (1), refdb-restore (1), refdbc (1). RefDB manual (local copy) PREFIX/share/doc/refdb-<version>/refdb-manual/index.html RefDB manual (web) < http://refdb.sourceforge.net/manual/index.html> RefDB on the web < http://refdb.sourceforge.net/>AUTHOR¶
refdba was written by Markus Hoenicka <markus@mhoenicka.de>.NOTES¶
- 1.
- IANA
2005-10-15 | RefDB Manual |