docs/user-manual.html
<html>
<head>
<title>User Manual: RedBrick Registration System</title>
<link rel="stylesheet" href="doc.css" type="text/css">
</head>
<body>
<h1>User Manual:<br>RedBrick Registration System</h1>
<p><i>Cillian Sharkey, CASE3, 50716197</i></p>
<ol>
<li><a href="#useradm">Using useradm</a>
<ol>
<li><a href="#running">Running useradm</a>
<li><a href="#using">Using useradm</a>
<li><a href="#common">Common command line options</a>
</ol>
<li><a href="#rrs">Using rrs web interface</a>
<ol>
<li><a href="#card">card - card reader interface</a>
<li><a href="#add">add - Add new user</a>
<li><a href="#delete">delete - Delete user</a>
<li><a href="#renew">renew - Renew user</a>
<li><a href="#update">update - Update user</a>
<li><a href="#rename">rename - Rename user</a>
<li><a href="#convert">convert - Convert user to new usertype</a>
<li><a href="#show">show - Show user information</a>
<li><a href="#freename">freename - Check if a username is free</a>
<li><a href="#search">search - Search user and DCU databases</a>
<li><a href="#stats">stats - Database statistics</a>
<li><a href="#log">log - Log of all actions</a>
</ol>
</ol>
<a name=useradm></a><h2>Using useradm</h2>
<a name=running></a><h3>Running useradm</h3>
<p>For performing any account operations, <code>useradm</code> must be run as
root (superuser). For accessing only database information, an unprivilged user
account (that has been granted access to the database) can be used. All
examples below assume running as root on the main server where both accounts
and user database live.</p>
<p>The <code>useradm</code> script can be run from anywhere, as long as it is
in the same directory as the rest of the rrs distribution. Say rrs is installed
in <code>/usr/local/rrs</code>. It could be run as follows:</p>
<pre>
main# <b>/usr/local/rrs/useradm</b>
Usage: useradm command [options]
'useradm -h' for more info on available commands
<i>[OR]</i>
main# <b>cd /usr/local/rrs</b>
main# <b>./useradm</b>
Usage: useradm command [options]
'useradm -h' for more info on available commands</pre>
<p>"<code>useradm -h</code>" gives a full listing of all commands available. For
full usage and command line options for a given command, use "<code>useradm
command -h</code>" e.g:</p>
<pre>
main# <b>./useradm -h</b>
Usage: useradm command [options]
Single user commands:
add Add new user
delete Delete user
renew Renew user
update Update user
rename Rename user
convert Change user to a different usertype
Single account commands:
resetpw Set new random password and mail it to user
resetsh Reset user's shell
disuser Disuser a user
reuser Re-user a user
Single user information commands:
show Show user details
freename Check if a username is free
Interactive batch commands:
search Search user and dcu databases
sync Synchronise accounts with userdb (for RRS)
sync_dcu_info Interactive update of userdb using dcu database info
Batch commands:
newyear Prepare database for start of new academic year
unpaid_warn Warn (mail) all non-renewed users
unpaid_disable Disable all normal non-renewed users
unpaid_delete Delete all grace non-renewed users
Batch information commands
newbies_list List all paid newbies
renewals_list List all paid renewals (non-newbie)
freename_list List all usernames that are taken
unpaid_list List all non-renewed users
unpaid_list_normal List all normal non-renewed users
unpaid_list_reset List all normal non-renewed users with reset shells
unpaid_list_grace List all grace non-renewed users
Miscellaneous commands:
checkdb Check database for inconsistencies
stats Show database and account statistics
'useradm command -h' for more info on a command's options & usage.
main# <b>./useradm add -h</b>
Add new user
Usage: useradm add [options] [username]
-h Display this usage
-T Test mode, show what would be done
-d Perform database operations only
-a Perform unix account operations only
-u username Unix username of who updated this user
-f Set newbie (fresher) to true
-F Opposite of -f
-m Send account details to user's alternate email address
-M Opposite of -m
-o Override warning errors
-p Set new random password
-P Opposite of -p
-t usertype Type of account
-n name Real name or account description
-e email Alternative email address
-i id Student/Staff ID
-c course DCU course (abbreviation)
-y year DCU year
-s years paid Number of years paid (subscription)
-b birthday Birthday (format YYYY-MM-DD)</pre>
<p>While useradm is primarily designed for user interaction, all required user
input can be provided on the command line by the use of options and
arguments as shown above.</p>
<a name=using></a><h3>Using useradm</h3>
<p>The basic operation involves the prompting of the user for information. Examples
of the prompt follow:</p>
<pre>
Enter usertype
(hints) [member] >>
Enter new username
[no default] >>
Enter birthday as 'YYYY-MM-DD'
(optional) [1982-06-20] >></pre>
<p>The prompt has the following features:</p>
<ul>
<li>Line editing (provided by readline) - this allows for easy editing
of data at the prompt and provides a history of previously input data
that is accessible by using the up and down arrow keys.
<li>Default answer - if a default answer is provided, it is shown in
square brackets <code>[like this]</code>. To accept the default, simply
hit <code>RETURN</code>. If no default is provided it will be shown as
<code>[no default]</code>. In this case hitting <code>RETURN</code> is
equivalent to giving an empty answer.</p>
<li>Optional questions - indicated by "<code>(optional)</code>" beside
the prompt. Giving an empty answer is taken as not answering the
question. If however, a default answer is provided and you want to give
an empty answer, you must use the End Of File (<code>EOF</code>)
control sequence (instead of <code>RETURN</code> which will give the
default answer). <code>EOF</code> is typically Control-D on UNIX
systems.
<li>Tab completion - if a default answer is provided or a set of hints
(indicated by "<code>(hints)</code>" beside the prompt) then pressing
<code>TAB</code> will cycle through all possible answers when no text
has been entered at the prompt. When some text has been entered and
<code>TAB</code> is pressed, it will only cycle through possible answers
that start with the given text.
<li>Error handling - if an error occurs during the input of user data
it will be displayed and the question will be asked again until correct
or valid input is provided. If however, the error is only a
<code>WARNING</code> and not <code>FATAL</code>, then the option to
override (i.e. essentially "ignore") the error is provided. If you
answer No, you go back to the question prompt again. If you answer Yes,
you advance to the next question or step. Answering yes also sets the
'override' option so any <code>WARNING</code> errors that occur when
action is performed after all user input is complete will also be
ignored (they will be displayed however).
</ul>
<a name=common></a><h3>Common command line options</h3>
<p>A number of command line options are common to all commands:</p>
<ul>
<li><code>-T</code> test mode. This runs through all user input and
questions but it does not perform any actions. Rather, it prints out
exactly what would be done. Any SQL INSERTs, UPDATEs or DELETEs that
would be sent to the database, what local commands (and their
arguments) would be executed (and any input that would be given to
them) the contents of any email messages that would be sent, etc. This
is extremely handy if you are unsure as to what a command will do or if
you just want to be careful before performing any of the batch
operations, like <code>unpaid_delete</code> or <code>sync</code> for
example.
<li><code>-d</code> database only mode. This ensures that only database
actions will be performed. This is especially useful when using useradm
with the web setup where the local accounts don't exist. It is also
useful for making changes to the database so that is up to date with
the corresponding account(s) if they are out of sync.
<li><code>-a</code> account only mode. This ensures that only account
actions will be performed. This is especially useful if for example
a database & account operation failed on the account operation and
needed to be completed later after fixing the source of the problem. An
example of this is a <code>rename</code> or a <code>convert</code> of a
user who was currently logged in at the time. In this case the database
operation would complete succesfully however the account operation which
uses <code>usermod</code> would fail as it would not operate on a
currently logged-in user. Note that this was only apparent with the Solaris
implementation of the command. Other uses would be to operate on an account
that does not exist in the database for whatever reasons.
</ul>
<a name=rrs></a><h2>Using rrs web interface</h2>
<p>The web interface is designed to be rather intuitive and easy to use. The
top of the page contains a menu with the following commands available:</p>
<a name=card></a><h3>card - card reader interface</h3>
<p>This is designed to be the main interface when using rrs. The card ID input
field is automatically focused on page load so it is ready to accept input from
either a magnetic card reader, barcode scanner or plain user input.</p>
<p>If the given DCU ID number is already in the database it will present the
user renewal form with the users' current details along with any updated
details from the DCU databases (e.g. course and year will change for students,
or an invalid email address may have been fixed, etc.). If the user has already
paid however, it will issue a warning message and remain on the card reader
page. This is prevents users accidentally paying again for an already paid
account. The new username input field is automatically focused to allow for
quick entry of the user's preferred choice of new username (if any). Typically
nothing needs to be changed so simply pressing <code>RETURN</code> is enough to
renew the user after checking that their user details are correct.</p>
<p>Otherwise it must be a new user so details are loaded in from the DCU
databases along with reasonable default values (e.g. years paid will be 1). The
username input field will be automatically focused to allow for quick entry of
the user's preferred choice of username.</p>
</p>
<a name=add></a><h3>add - Add new user</h3>
<p>A more 'manual' approach to adding new users. It provides a blank form for
adding a new user. Leaving out details and submitting the form will fill in any
missing information if possible until there is enough information to add the
user succesfully.</p>
<a name=delete></a><h3>delete - Delete user</h3>
<p>Simply deletes user from database. Note that in reality it should be very
rare for anyone to request an account deletion but the feature is provided just
in case.</p>
<a name=renew></a><h3>renew - Renew user</h3>
<p>A more 'manual' approach to renewing users. It provides a blank form for
renewing a new user. Leaving out details and submitting the form will fill in
any missing information if possible until there is enough information to renew
the user succesfully.</p>
<a name=update></a><h3>update - Update user</h3>
<p>Similar to the renewal form except only the users' current database
information is displayed for easy modification. No new information from the DCU
databases or defaults are provided so an update of a user without changing any
of the input fields has no visible change of the users' information other than
the updating of the <code>updated_by</code> and <code>updated_at</code>
attributes.</p>
<a name=rename></a><h3>rename - Rename user</h3>
<p>Simply changes a user's username. Note that currently the old username
becomes available as soon as it is renamed.</p>
<a name=convert></a><h3>convert - Convert user to new usertype</h3>
<p>Note that only conversions for "paying" usertypes are supported.</p>
<a name=show></a><h3>show - Show user information</h3>
<p>Shows database information for given username.</p>
<a name=freename></a><h3>freename - Check if a username is free</h3>
<p>Simply checks for a free new username.</p>
<a name=search></a><h3>search - Search user and DCU databases</h3>
<p>Allows for searching by username, name or ID number. Note that the SQL
wildcard characters '_' for a single character and '%' for any number of
characters can be used. Any student or staff entries that have a RedBrick
account (i.e. a datbase entry with the <i>same</i> DCU ID number) will appear
with a 'show' button so that their database entry can be displayed quickly and
easily.</p>
<a name=stats></a><h3>stats - Database statistics</h3>
<p>Simply displays database statistics.</p>
<a name=log></a><h3>log - Log of all actions</h3>
<p>Shows a detailed log of all user actions that were performed and all user
input that was given including a time stamp.</p>
<hr>
$Id: user-manual.html,v 1.1 2003/03/28 16:39:08 cns Exp $
</body>
</html>