USERACC(1) Contributed Software Manual USERACC(1)NAMEuseracc — special purpose database application
SYNOPSISuseracc-s [-d] [-f data_file] [-g] -h host_list [-l log_file] [-p port]
[-t timeout] -u user_list
useracc-S [-d] [-g] -h host [-p port] [-P port] [-t timeout]
useracc [-b | -i] [-c comment] [-P port] [-r | -w] [-t timeout] [-u user]
[value]
useracc-e [-f data_file]
useracc-x | -X [-f data_file]
DESCRIPTION
The useracc utility is a special purpose database application to store
and retrieve data about users in a distributed environment. It is usable
in situations where a single numerical and/or a single non-numerical
field for each index (possibly a user name) are adequate.
To use useracc, a single useracc master server needs to be run on a
selected host; the master server is responsible for managing the database
which is stored in single file. This file is locked by the server process
to gain exclusive access. On each host on which access to the data is
desired a useracc slave server has to be run. The useracc clients send
their requests to the local slave server which on its part completes the
requests and transfers them to the master server. Any response is first
sent back to the slave server and then returned to the client.
Connections to the master server are restricted to hosts specified in a
host list. Slave servers listen on the internal loopback address only. To
bind sockets to the default ports, master and slave servers must run in
privileged mode.
Access is granted to requests by master servers if following conditions
are met:
· The request was sent from a trusted host found in the host list.
· Access to the requested database record is permitted for this host.
· The request was sent from a privileged port (if the master server is
run by root and listening on a privileged port).
· The encrypted secret key transmitted by the slave server matches.
· The request was caused by a trusted user found in the user list.
· The request arrived in time.
Secret keys are created on invocation by master and slave servers using
the random(3) function. Slave servers running on trusted hosts are
allowed to query the master server for a seed to recalculate the key if
necessary; such events are logged with ALERT priority.
There is no need for useracc clients to know the secret key since their
requests are completed by slave servers.
Slave servers do only accept local connections and permit all requests
sent by clients.
OPTIONS
Available options:
-b Inquire or set the balance of a user's account which
generally spoken is a user specific floating point
value stored in the data base. When setting the bal‐
ance, value must either be a floating point number
to which the balance is set, or a floating point
number preceded by one of the operators +, -, * or
/. The given floating point number will then be
added to or subtracted from the balance stored in
the database, or both will be multiplied, or the
stored balance will be divided by the given number.
Please don't forget to terminate command line option
processing by preceding value with -- if the opera‐
tor - will be used.
-c comment Comment that shall be recorded in the log file of
the master server to label the current client
request.
-d Daemon mode; useracc master and slave servers will
run in the background.
-e Edit mode; a special mode available on the master
server host when the master server is not running.
useracc will backup the binary database file and
convert it to a plain text file. useracc will then
call the user's preferred text editor to let him or
her edit the file, and finally will regenerate the
binary database.
-f data_file Name of the file containing the database; by
default, the name will be useracc.dat and the file
will be located in the current working directory.
-g If specified, a master server will grant access to
all records to all slave servers; a slave server
will grant access to all other slave servers to all
new records added by the master on demand of the
current slave server itself, independent of the
behavior of the master server.
-h host_list | host In case of invoking a master server, a host name or
a comma separated list of host names denominating
hosts on which slave servers are run; this list
should include localhost if a slave server will be
run on the local machine, too. When invoking a
slave server, the name of the host where the master
server runs on has to be given here.
-i Inquire or set additional user information which
generally spoken is a user specific string value
stored in the database.
-l log_file Name of the file where the master server will log
all requests; if not given, logging information will
be written to stdout.
-p port Port number the master server will listen on,
defaults to 911. If useracc master or slaver
servers are invoked by unprivileged users, a port
number available for unprivileged access should be
used (typically these are numbers greater than
1023).
-P port Port number the slave server will listen on,
defaults to 912. If useracc master or slaver
servers are invoked by unprivileged users, a port
number available for unprivileged access should be
used (typically these are numbers greater than
1023).
-r Read request by the client, inquire data; if neither
-r nor -w are given, -r is assumed. If neither -b
nor -i are specified additionally, both values will
be reported.
-suseracc will start in master server mode.
-Suseracc will start in slave server mode.
-t timeout Number of seconds useracc will try to transmit data
over the network before giving up, defaults to 12
seconds. Additionally, a master server will consider
requests to be illegal if the clocks on master and
slaves differ more than this amount of time.
-u user_list | user Name of a user or comma separated list of user
names; when invoking a master server, client
requests originated by users not mentioned here will
not be granted access. When invoking a client, name
of the user whose data are to be inquired, added or
modified, if different from the name of the user
issuing the request.
-w Write request by the client, modify or add data; one
of the flags -b or -i must be given additionally as
well as the argument value.
-x Extract mode; a special mode available on the master
server host to extract all data form the binary
database in human readable form.
-X Similar to -x, but the output generated by useracc
will consist of useracc client calls which could be
used to regenerate the current status of a database
by feeding them into a shell.
DATABASE FORMAT
The databases useracc uses have a simple and fixed format and are built
of records of equal length. The record length equals 512 bytes; records
consist of the following fields:
· User identification or user name which should not be longer than 15
characters and frequently is equal to the FreeBSD user name.
· Additional user information, like full name or email address, should
not be longer than 255 characters and should not contain colons.
· Balance of user's account, double precision floating point value.
· Name of the host (not exceeding a length of 231 characters) the slave
server of which requested to add the record; normally, later access
to the record is limited to this host.
User names are used as an index to database records. Host names in the
last field can only be changed by using the edit mode of useracc.
Read requests referring to non-existing records will result in error mes‐
sages; write requests referring to non-existing records will silently add
corresponding records.
LOG FILE
Requests and events are logged by the master server; the log file is
readable by the process owner only. Each entry starts with a time stamp
followed by a column indicating the type of event:
E Transmission error
R Normal request
S Start of master server
T Termination of master server
In case of a normal request, the next columns show the name of the host
the request comes from and the port number used by the slave server, the
name of the user who caused the request, the code number of the requested
operation, an error code, the elapsed number of seconds needed to process
the request, an optional request comment, the user name the request
refers to and possibly a transmitted or received value for that user.
Operation codes are as follows:
0
Key assignment, transfer seed to slave server.
1
Read all, both user data fields are returned to caller.
2
Read balance, balance of the user's account is returned to caller.
3
Read info, user information is returned to caller.
4
Write balance, new balance of user's account is written to database.
5
Write info, new user information is written to database.
Error codes are as follows:
0
No error occurred.
1
Data transmission has been incomplete.
2
Invalid data have been supplied.
3
An invalid key has been sent.
6
Permission for this request is denied.
8
There is no record for the user in the database.
RETURN VALUES
Return values of useracc clients are zero in case of success and non-zero
otherwise; in the latter case, a descriptive error message is printed on
stderr.
EXAMPLE
An unprivileged user dave might start a useracc master server granting
himself access by the following command:
useracc-s -d -h localhost -l useracc.log -p 9808 -u dave
Then, he will have to invoke a slave server:
useracc-S -d -h localhost -p 9808 -P 9809
Next, it is possible to require the creation of a new record:
useracc-b -P 9809 -w -u dave +3.36
Now it is possible to send a query
useracc-P 9809 -u dave
which will print
dave 3.36
on stdout.
ENVIRONMENT
In edit mode, useracc will use the environment variable EDITOR if set to
invoke the user's preferred editor instead of vi.
FILES
/usr/local/etc/rc.d/useracc.sh
HISTORY
Development of useracc started in the times of FreeBSD 2.2.8-RELEASE.
BUGS
There are no known bugs; useracc has been proven to be reliable. Never‐
theless, there are some shortcomings:
· The database format is inflexible.
· The simple search algorithm (linear search) may be to slow for very
large databases.
· The protection of possibly sensible data transferred over the network
is still and despite of all improvements not optimal.
AUTHOR
Konrad Heuer ⟨kheuer@gwdg.de⟩
BSD December 20th, 2002 BSD
