Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  USERACC (1)


useracc - special purpose database application


Database Format
Log File
Return Values


useracc -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]


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.


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 balance, 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 operator - 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.
-s useracc will start in master server mode.
-S useracc 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.


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
    .Fx 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 messages; write requests referring to non-existing records will silently add corresponding records.


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 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.


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.


In edit mode, useracc will use the environment variable EDITOR if set to invoke the user’s preferred editor instead of vi.




Development of useracc started in the times of
.Fx 2.2.8-RELEASE.


There are no known bugs; useracc has been proven to be reliable. Nevertheless, 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.


.An Konrad Heuer Aq
Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.