Browse Source

Remove Deprecation & Convert Docs to Markdown (#65)

* Remove Deprication warning

* Migrated from html to md docs
pull/67/head
Tom Doyle 2 years ago
committed by GitHub
parent
commit
f015c64b2a
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 925 additions and 223 deletions
  1. +2
    -2
      README.md
  2. +218
    -0
      docs/func-spec.md
  3. +14
    -0
      docs/index.md
  4. +218
    -0
      docs/install-manual.md
  5. +167
    -221
      docs/tech-manual.html
  6. +306
    -0
      docs/user-manual.md

+ 2
- 2
README.md View File

@@ -1,5 +1,5 @@
## !DEPRECATION WARNING!
### This tool has become more trouble than it's worth to continually work on. Useradm remains in production in its current state for the time being, but will eventually be superceded by redbrick/rb-ldap. Please contact elected-admins@redbrick.dcu.ie with any questions.
## This tool is under heavy construction
### There is no guarantee it is working but work is commencing on it

# Useradm



+ 218
- 0
docs/func-spec.md View File

@@ -0,0 +1,218 @@
# Functional Specification: RedBrick Registration System

*Cillian Sharkey, CASE3, 50716197*

1. Introduction
- Scope and purpose of this document
2. Overview of project
- Background
- Users
- Objectives
- Constraints
3. Functional and data description
- System architecture
- User data
- Software and Hardware Boundaries
4. Projected schedule
5. References

## Introduction

### Scope and purpose of this document
This document is a functional specification for my 3<sup>rd</sup> year
project: a user registration and administration system for use by the DCU
Networking Society ([Redbrick](http://www.redbrick.dcu.ie)). It
will attempt to describe the functional aspects of the project: its
objectives, constraints, system architecture, and functional data description
so that there is enough information for the actual implementation of the
project.

## Overview of project

### Background

There are just over 1,800 accounts on the RedBrick UNIX system and so the
administration of user accounts forms a large part of the system
administrators' workload. As one of the system administrators for RedBrick
myself, I have first hand experience of the amount of work required in
administrating user accounts and dealing with account requests on an often
daily basis. In addition to this, each year at the clubs &amp; societies day
the registration of new and renewal of existing users takes place. Hundreds
of users are processed on a small isolated network of computers. The goal of
this project is to reduce the workload of system administrators and ease the
administration and registration of users both on a daily basis and for the annual
clubs and societies day.

### Users

The users of the system will be restricted to the system administrators
for day to day user administration as it requires root (superuser) access, however
for registration on clubs &amp; societies day it is usual for other members of the
society committee to help out.

### Objectives

* Provide an automated and consistent (UNIX command line) interface
for performing both common day-to-day and occassional "batch" user
administration operations on the actual accounts (home directories,
mail spools, disk quotas etc.), the UNIX `/etc/passwd`
"database" and the user database ensuring that all are kept in sync.
Single user account operations would include:
* adding new accounts,
* deleting existing accounts,
* renaming existing accounts,
* converting existing accounts "usertype",
* renewing existing accounts,
* reseting accounts with new random password (and emailing password to user)
* retrieving account information for display,
* checking the availability of usernames for new accounts,
* Batch account operations would include:
* emailing renewal reminders to non-renewed accounts
* expiring non-renewed accounts (i.e. disabling login shell)
* deleting non-renewed accounts after a grace period
* checking for inconsistencies between the user database and the UNIX `/etc/passwd` database
* interactive update of the user database from the latest copy of the public DCU student database
* Provide a web interface to offer a similar set of single user administration operations for use on the clubs &amp; societies day. The setup is generally that of a small number of networked computers that are isolated from the RedBrick servers so changes would be made to a local (seperate) copy of the user database and at the end of the day all of these changes (i.e. new, renewed, renamed, converted, etc. accounts) must be detected and synchronised with the actual accounts and UNIX `/etc/passwd` database on the system. This needs to be done in batch as hundreds of accounts are processed on clubs &amp; societies day. This would be implemented as one of the command line interface's batch operations.
* Prevent username conflicts with other namespaces on the system e.g. email aliases, mailing lists.

### Constraints

* All accounts must have a name (or description) and an alternate
email address for contact purposes (and as such all UNIX accounts must
have a corresponding entry in the user database).

* Users may only have one account on the system (i.e. one student ID
per account).
* Member, staff and associate accounts must have a valid DCU
student/staff ID associated with them.

* Usernames will be limited to what the underlying UNIX OS supports
in terms of acceptable characters, length etc.

## Functional and data description

### System architecture

The system will be 3 tier in nature:

**Front end**

There will be two client applications: a CGI web interface (primarily for
use on the annual clubs &amp; societies day to register new members and renew
existing members) and a UNIX command line interface for day-to-day user
administration.

**Middle end**

There will be two modules which the two client applications (and any
potential future applications) will use. One will be for performing database
operations (RBUserDB) and the other for UNIX account operations (RBAccount).
The web interface will not make use of the UNIX account module however, as it
operates on the database only.

**Back end**

Database (likely to be PostgreSQL) which will contain tables for the actual
user database and associated information, e.g. local copy of the public DCU
student database, table of valid usertypes, additional reserved usernames,
etc. Will also contain copies of user database from previous years for
reference/archival purposes.

### User data

The traditional UNIX `/etc/passwd` database doesn't contain
enough information for user accounts for RedBrick's needs (nor does it support
complex queries that a database can) hence the need for a user database. The
following additional information will be kept for all UNIX accounts:

<dt>Username</dt>

<dd>Unique UNIX username.<dd>

<dt>Name/Description</dt>

<dd>User's full name or a description for non-user accounts (e.g.
project/system accounts).</dd>

<dt>Usertype</dt>

<dd>Corresponds to both UNIX group and type of user. The following usertypes
will be used: member, staff, associate, project, club, society, committee,
project, guest, system, reserved.</dd>

<dt>Email</dt>

<dd>Alternate contact address (typically DCU email address).</dd>

<dt>Student ID</dt>

<dd>DCU student (or staff) ID number, compulsory for member, staff and
associates.</dd>

<dt>Years paid</dt>

<dd>Number of years paid. (Non-renewed accounts will be zero).</dd>

<dt>Updated by</dt>

<dd>Username of the administrator who last updated the database entry.</dd>

<dt>Updated at</dt>

<dd>Date &amp; time of when the database entry was last updated.</dd>

<dt>Created by</dt>

<dd>Username of the administrator who first created the account.</dd>

<dt>Created at</dt>

<dd>Date &amp; time of when the database entry was first created.</dd>

### Software and Hardware Boundaries

The project will use the OS native command line tools for performing all
UNIX `/etc/passwd` operations and the majority of account
operations. The 3rd party utility `setquota` will be used for
the modification of disk quotas. DCU student information will be retrieved
from the publically accessible LDAP service on `atlas.dcu.ie`.

## Projected schedule

<dt>Week 1</dt>

<dd>Design database (SQL schema &amp; populating with sample data). Code
middle end database module (addition, retrieval and updation of user
information, user data checking functions).</dd>

<dt>Week 2</dt>

<dd>Code middle end account module (interaction with UNIX account utilities
&amp; filesystem manipulation of user accounts).</dd>

<dt>Week 3</dt>

<dd>Code command line interface (single user operations) in parallel with
'unit testing' of the various database and account module functions.</dd>

<dt>Week 4</dt>

<dd>Code web interface.</dd>

<dt>Week 5</dt>

<dd>Work on batch operations.</dd>

<dt>Week 6</dt>

<dd>Final testing. Write up documentation: Technical manual, User manual,
Installation manual.</dd>

## References

### UNIX (Solaris) user administration tool manpages


$Id: func-spec.html,v 1.1 2003/03/28 16:33:07 cns Exp $

+ 14
- 0
docs/index.md View File

@@ -0,0 +1,14 @@
# RedBrick Registration System

### Web interface

The RRS Web Interface

### Documentation

* Technical Manual
* Installation/Configuration Manual
* User Manual
* Original Functional Specification

$Id: index.html,v 1.1 2003/03/26 10:24:19 cns Exp $

+ 218
- 0
docs/install-manual.md View File

@@ -0,0 +1,218 @@
# Installation Manual: RedBrick Registration System

*Cillian Sharkey, CASE3, 50716197*

1. Introduction
2. Pre-requisites
- Requirements for all setups
- Requirements for main setup
- Requirements for web setup
3. Installation
- Installing software
- Setting up database
4. Configuration

## Introduction

There are essentially two kinds of setups for RRS:
1. Main setup - this is the setup of the machine where the user
database and accounts permanently reside. There is at a minimum, full
use of `useradm` for both database and account
administration.
2. Web setup - this is the machine used for hosting the clubs &amp;
societies day system. Full use of the `rrs` cgi for database
administration and limited use of useradm for database only
administration.


Note that the web setup could also be used on the main setup, so that full use
of `useradm` and the `rrs` cgi would be available.

The installation requirements and steps below will indicate if they only
pertain to one of the given setups ('main' or 'web') above, otherwise it can be
assumed that they are required for both types of setup.

It is also worth noting that much of RRS is very specific to the RedBrick
and DCU environment and so as such is not designed for widespread use on
generic machines. The web setup mentioned above however, is not as specific in
its requirements and is intended to be reasonably 'portable'.

## Pre-requisites

### Requirements for all setups

#### Platform

RRS is designed primarily to run on a Unix platform however, it should be
possible to run the web interface part on a non-Unix platform although this has
not been tested. Note that root (superuser) access is required for performing
any account or filesystem operations with `useradm`, everything else
can be performed using a user / unprivileged account (assuming it has access to
the user database).

#### PostgresSQL

PostgresSQL version 7.2 or higher must be installed. Details on doing this vary
depending on the operating system and is outside the scope of this document
however, full instructions can be found on the
PostgresSQL website.

#### Python

Python version 2.2 or higher must be installed. Details on doing this vary
depending on the operating system and is outside the scope of this document
however, full instructions can be found on the
Python website.

The following Python modules are included in the standard Python release,
but may need to be installed or configured to work:

* readline - provides command line editing and completion functionality for useradm. Requires GNU readline to be installed.

The following additional 3rd party Python modules must be installed:

1. [PyGresSQl](http://www.druid.net/pygresql/) - Python
interface to PostgresSQL database. Note that this is actually included
in the PostgresSQL database release, however ensure that version 3.2 or
later is installed.
2. [Python-LDAP](http://python-ldap.sourceforge.net/)- a
Python interface to LDAP. Requires
[OpenLDAP](http://www.openldap.org) to be installed.
Tested with Python-LDAP version 1.10alpha3 and OpenLDAP 1.2.13. This
module is currently only used by
<a href=rebuild_userdb_students.html>rebuild_userdb_student</a> and the
<a href=rebuild_userdb_staff.html>rebuild_userdb_staff</a> scripts.

### Requirements for main setup

#### Account utilities

The account utilities `useradd`, `usermod` and
`userdel` need to be installed. Typically, these are provided as
part of the native operating system and have been found to have a consistent
interface on Solaris, Linux and NetBSD.

#### Setquota

The 3rd party utility `setquota` must be installed for the
manipulation of disk quotas. There appear to be a number of implementations of
this command each with different command line syntax for different operating
systems. Tested with a setquota utility for Solaris written by David Mitchell
of Dept of Computer Science, Sheffield University.

#### Mailman

RRS automatically subscribes (and unsubscribes) users to a variety of
RedBrick mailing lists, specifically the announce-redbrick,
redbrick-newsletter, comittee, rb-admins and admin-discuss lists. For this
reason the mailing list software [Mailman](http://www.list.org) should be installed with the above mentioned lists created and working. It is
not entirely necessary however as "dummy" scripts can be used in place of the
`add_members` and `remove_members` mailman commands.

#### Mail Transfer Agent

Any MTA that provides the generic `sendmail` command line
interface will suffice, e.g. Exim, Postfix, Sendmail, etc.

### Requirements for web setup

#### Apache

A web server is required for the `rrs` cgi. Web servers other
than Apache should work as the CGI standard is web server independant. Tested
against Apache 1.3.26.

## Installation

### Installing software

The installation of RRS simply involves unpacking the RRS distribution tarball in a filesystem location
of your choosing. Say you have downloaded the tarball to
`/tmp/rrs.tar.gz`. Installation to the directory
`/usr/local/rrs` is as follows:

```
# cd /usr/local
# tar zxf /tmp/rrs.tar.gz
```

### Setting up database

A database `userdb` needs to be created with the postgres command
"`createdb userdb`" run as the postgres user. For the account setup,
the root user will need access to the database. For the web setup, the user the
web server runs as will need access to the database. This is achieved by first
creating the users if they don't already exist with the postgres
`createuser` command and making sure that postgres is setup to grant
access to the `userdb` database for these users by appropriate
editing of the `pg_hba.conf` and possibly `pg_ident.conf`
files.

#### Creating database [main setup]

This step sets up a new database from scratch.

Create the tables for the database:

```bash
main$ cat userdb_reserved.sql userdb_staff.sql userdb_students.sql \
userdb_usertypes.sql userdb_users.sql | psql userdb
```

Make sure that access to these tables is granted to all users who need it.
The above scripts include full access for root and SELECT (read only) access
for users `www` and `webgroup` as this is the default
used on the RedBrick system.

Then populate the student, staff and reserved tables by running each of the
rebuild scripts, e.g:

```
main$ ./rebuild_userdb_reserved
userdb/reserved: Purge. Populate. Done [45]
main$ ./rebuild_userdb_students
userdb/students: Search [19523]. Purge. Populate. Done [19436/19523].
main$ ./rebuild_userdb_staff
userdb/staff: Search [1829]. Purge. Populate. Done [397/1829].
```


#### Creating database [web setup]

If the web setup is on a seperate machine to the main system machine, the
database must be copied across. This can be achieved as follows:

```
main$ pg_dump -f userdb.dump userdb
[copy file userdb.dump to the web machine]
web$ psql userdb &; userdb.dump
```

You will need to grant full access to the users table to the user the web
server runs as. The "`GRANT ALL ON users TO username`" SQL command
achieves this when run as the owner of the userdb.

An empty `rrs.log` file needs to be created before any actions
can be performed with the web interface. This can be achieved by:

```
[create rrs.log in directory that rrs is installed]*
web$ touch rrs.log
[make sure web server user can write to file]
web$ chown www rrs.log
```

## Configuration

Local configuration can be performed by editing the rbconfig.py file. The majority of this configuration
file is for providing local account and filesystem location paths to the rbaccount module. The defaults provided are of
course suited for the RedBrick system.

At this point, all necessary installation and configuration should be
complete for use of RRS.

$Id: install-manual.html,v 1.1 2003/03/28 16:33:07 cns Exp $

+ 167
- 221
docs/tech-manual.html View File

@@ -1,125 +1,98 @@
<html>
<head>
<title>Technical Manual: RedBrick Registration System</title>
<link rel="stylesheet" href="doc.css" type="text/css">
</head>
<body>

<h1>Technical Manual:<br>RedBrick Registration System</h1>

<p><i>Cillian Sharkey, CASE3, 50716197</i></p>

<ol>
<li><a href="#overview">Overview of project</a>
<ol>
<li><a href="#background">Background</a>
<li><a href="#users">Users</a>
<li><a href="#features">Features</a>
<li><a href="#constraints">Constraints</a>
</ol>
<li><a href="#arch">System architecture</a>
<ol>
<li><a href="#clients">Clients</a>
<li><a href="#middle">Middle end</a>
<li><a href="#back">Back end</a>
</ol>
<li><a href="#data">User data</a>
<ol>
<li><a href="#sql-users">users</a>
<li><a href="#usertypes">usertypes</a>
<li><a href="#students">students</a>
<li><a href="#staff">staff</a>
<li><a href="#reserved">reserved</a>
</ol>
<li><a href="#boundary">Software and Hardware Boundaries</a>
<li><a href="#refs">References</a>
</ol>

<a name=overview></a><h2>Overview of project</h2>

<a name=background></a><h3>Background</h3>

<p>There are just over 1,800 accounts on the RedBrick UNIX system and so the
# Technical Manual: RedBrick Registration System

*Cillian Sharkey, CASE3, 50716197*

1. Overview of project
* Background
* Users
* Features
* Constraints
2. System architecture
* Clients
* Middle end
* Back end
3. User data
* users
* usertypes
* students
* staff
* reserved
4. Software and Hardware Boundaries
5. References

## Overview of project

### Background

There are just over 1,800 accounts on the RedBrick UNIX system and so the
administration of user accounts forms a large part of the system
administrators' workload. As one of the system administrators for RedBrick
myself, I have first hand experience of the amount of work required in
administrating user accounts and dealing with account requests on an often
daily basis. In addition to this, each year at the clubs &amp; societies day
daily basis. In addition to this, each year at the clubs & societies day
the registration of new and renewal of existing users takes place. Hundreds
of users are processed on a small isolated network of computers. The goal of
this project is to reduce the workload of system administrators and ease the
administration and registration of users both on a daily basis and for the annual
clubs and societies day.</p>
clubs and societies day.

<a name=users></a><h3>Users</h3>
### Users

<p>The users of the system will be restricted to the system administrators
The users of the system will be restricted to the system administrators
for day to day user administration as it requires root (superuser) access, however
for registration on clubs &amp; societies day it is usual for other members of the
society committee to help out.</p>
for registration on clubs & societies day it is usual for other members of the
society committee to help out.

<a name=features></a><h3>Features</h3>
### Features

<ul>

<li><p>The entire system is written in Python, whose website describes
it as:</p>
* The entire system is written in Python, whose website describes
it as:
<blockquote>
<p>"Python is an interpreted, interactive, object-oriented
programming language. It is often compared to Tcl, Perl, Scheme
or Java. Python combines remarkable power with very clear
syntax. It has modules, classes, exceptions, very high level
dynamic data types, and dynamic typing. The Python
implementation is portable: it runs on many brands of UNIX, on
Windows, DOS, OS/2, Mac, Amiga... "</p>
</blockquote>
> "Python is an interpreted, interactive, object-oriented
> programming language. It is often compared to Tcl, Perl, Scheme
> or Java. Python combines remarkable power with very clear
> syntax. It has modules, classes, exceptions, very high level
> dynamic data types, and dynamic typing. The Python
> implementation is portable: it runs on many brands of UNIX, on
> Windows, DOS, OS/2, Mac, Amiga... "
<li><p>Provides a flexible, automated and consistent (UNIX command
line) interface (<code>useradm</code>) for performing both common
* Provides a flexible, automated and consistent (UNIX command
line) interface (`useradm`) for performing both common
day-to-day and occassional "batch" user administration operations on
the actual accounts (home directories, mail spools, disk quotas etc.),
the UNIX <code>/etc/passwd</code> "database" and the user database
the UNIX `/etc/passwd` "database" and the user database
ensuring that all are kept in sync. The following functions are
provided:</p>

<ul>
<li>adding new accounts,
<li>deleting existing accounts,
<li>renaming existing accounts,
<li>converting existing accounts "usertype",
<li>renewing existing accounts,
<li>reseting accounts with new random password (and emailing password
to user)
<li>reseting accounts with disabled Unix shells,
<li>retrieving account information for display,
<li>checking the availability of usernames for new accounts,
</ul>

<p>Batch account operations include:</p>

<ul>
<li>emailing renewal reminders to non-renewed accounts
<li>expiring non-renewed accounts (i.e. disabling login shell)
<li>deleting non-renewed accounts after a grace period
<li>checking for inconsistencies between the user database and the
UNIX <code>/etc/passwd</code> database
<li>interactive update of the user database from the latest copy of
the public DCU student database
</ul>

<p>Other information available:</p>

<ul>
<li>searching user and DCU databases,
<li>database and account statistics
</ul>
provided:

* adding new accounts,
* deleting existing accounts,
* renaming existing accounts,
* converting existing accounts "usertype",
* renewing existing accounts,
* reseting accounts with new random password (and emailing password to user)
* reseting accounts with disabled Unix shells,
* retrieving account information for display,
* checking the availability of usernames for new accounts,

Batch account operations include:

* emailing renewal reminders to non-renewed accounts
* expiring non-renewed accounts (i.e. disabling login shell)
* deleting non-renewed accounts after a grace period
* checking for inconsistencies between the user database and the UNIX `/etc/passwd` database
* interactive update of the user database from the latest copy of the public DCU student database

Other information available:

* searching user and DCU databases,
* database and account statistics
<p>The following is the output for the command usage help from
<code>useradm</code> when given the '-h' option which lists all
the names of the functions the script performs.</p>
The following is the output for the command usage help from
`useradm` when given the '-h' option which lists all
the names of the functions the script performs.

<pre>Usage: useradm command [options]
```
Usage: useradm command [options]
Single user commands:
add Add new user
delete Delete user
@@ -155,157 +128,141 @@ Batch information commands:
Miscellaneous commands:
checkdb Check database for inconsistencies
stats Show database and account statistics
'useradm command -h' for more info on a command's options &amp; usage.</pre>
'useradm command -h' for more info on a command's options &amp; usage.
```

<li><p>Provides a web interface (<code>rrs</code>) to offer a similar
* Provides a web interface (`rrs`) to offer a similar
set of single user administration operations for use on the clubs &amp;
societies day. While not as fully featured or as flexible as
<code>useradm</code>, the interface is designed primarily for speed and
efficiency.</p>
`useradm`, the interface is designed primarily for speed and
efficiency.
<p>To achieve this, user input fields are automatically focused on page
To achieve this, user input fields are automatically focused on page
load (using Javascript) to save using the keyboard or mouse to select
the input box; input from barcode scanners or magnetic strip
readers (for use with DCU staff and student cards) is accepted which
considerably speeds up the process and eliminates the potential for
human error.</p>
human error.
<p>The setup is generally that of a small number of networked computers
The setup is generally that of a small number of networked computers
that are isolated from the RedBrick servers so changes would be made to
a local (seperate) copy of the user database and at the end of the day
all of these changes (i.e. new, renewed, renamed, converted, etc.
accounts) must be detected and synchronised with the actual accounts
and UNIX <code>/etc/passwd</code> database on the system. This needs to
and UNIX `/etc/passwd` database on the system. This needs to
be done in batch as hundreds of accounts are processed on clubs &amp;
societies day. This is implemented as the <a
href=useradm.html#-sync>sync</a> command in
<code>useradm</code>. Features which <code>rrs</code> provides:</p>
societies day. This is implemented as the sync command in
`useradm`. Features which `rrs` provides:
<ul>
<li>adding new users,
<li>deleting existing users,
<li>renaming existing users,
<li>converting existing users "usertype",
<li>renewing existing users,
<li>retrieving user information for display,
<li>checking the availability of usernames for new users,
<li>searching user and DCU databases,
<li>database statistics,
<li>a detailed log of all actions performed,
</ul>

<li>Prevent username conflicts with other namespaces on the system e.g.
* adding new users,
* deleting existing users,
* renaming existing users,
* converting existing users "usertype",
* renewing existing users,
* retrieving user information for display,
* checking the availability of usernames for new users,
* searching user and DCU databases,
* database statistics,
* a detailed log of all actions performed,

* Prevent username conflicts with other namespaces on the system e.g.
email aliases, mailing lists, DNS entries for the redbrick.dcu.ie and
other domains the society host. Achieved through the use of the <a
href=#reserved>reserved</a> table.

</ul>
other domains the society host. Achieved through the use of the reserved table.

<a name=constraints></a><h3>Constraints</h3>
### Constraints

<ul>

<li>All accounts must have a name (or description) and an alternate
* All accounts must have a name (or description) and an alternate
email address for contact purposes (and as such all UNIX accounts must
have a corresponding entry in the user database).

<li>Users may only have one account on the system (i.e. one student ID
* Users may only have one account on the system (i.e. one student ID
per account).
<li>Member, staff and associate accounts should have a valid DCU
* Member, staff and associate accounts should have a valid DCU
student/staff ID associated with them.

<li>Usernames are limited to what the underlying UNIX OS supports, i.e.
* Usernames are limited to what the underlying UNIX OS supports, i.e.
maximum length of 8 characters, small set of available characters (a-z,
0-9, '-', '_', '.'), etc.

</ul>

<a name=arch></a><h2>System architecture</h2>
## System architecture

<p>The system is 3 tier in nature:</p>
The system is 3 tier in nature:

<a name=clients></a><h3>Clients</h3>
### Clients

<p>There are two client applications:</p>
There are two client applications:

<ul>
<li><a href=rrs.html>rrs:</a> a CGI web interface (primarily for use on
* rrs: a CGI web interface (primarily for use on
the annual clubs &amp; societies day to register new members and renew
existing members)
<li><a href=useradm.html>useradm:</a> a UNIX command line interface for
* useradm: a UNIX command line interface for
day-to-day user administration.
</ul>

<p>Additional maintenance scripts:</p>
Additional maintenance scripts:

<ul>
<li><a href=rebuild_userdb_reserved.html>rebuild_userdb_reserved</a> -
* rebuild_userdb_reserved -
rebuilds reserved table
<li><a href=rebuild_userdb_staff.html>rebuild_userdb_staff</a> - rebuilds
* rebuild_userdb_staff - rebuilds
staff table
<li><a href=rebuild_userdb_students.html>rebuild_userdb_students</a> -
* rebuild_userdb_students -
rebuilds students table
<li>dump_userdb.sh - Unix shell script to backup entire user database
* dump_userdb.sh - Unix shell script to backup entire user database
and provide local text copies for quick perusal with standard Unix
tools such as grep, etc.
</ul>

<a name=middle></a><h3>Middle end</h3>
### Middle end

<p>There are two main modules and a number of supporting modules which the two
client applications (and any potential future applications) use. These are:</p>
There are two main modules and a number of supporting modules which the two
client applications (and any potential future applications) use. These are:

<ul>
<li><a href=rbuserdb.html>rbuserdb:</a> performs all database operations
<li><a href=rbaccount.html>rbaccount:</a> performs all local UNIX
* rbuserdb: performs all database operations
* rbaccount: performs all local UNIX
account operations
<li><a href=rberror.html>rberror:</a> contains custom exception classes
* rberror: contains custom exception classes
(RBError, RBFatalError, RBWarningError) for our own types of errors
<li><a href="rbuser.html">rbuser:</a> contains RBUser class for
* rbuser: contains RBUser class for
representing a user
<li><a href="rbopt.html">rbopt:</a> contains RBOpt class for storing
* rbopt: contains RBOpt class for storing
user options and sharing between the various modules
</ul>

<p>Note that the web interface does not make use of the rbaccount module however,
as it operates on the database only.</p>
Note that the web interface does not make use of the rbaccount module however,
as it operates on the database only.

<a name=back></a><h3>Back end</h3>
### Back end

<p>A PostgresSQL database contains the following tables:</p>
A PostgresSQL database contains the following tables:

<ul>
<li><a href=#users>users</a> - the current user table
* users - the current user table

<li>users&lt;YEAR&gt; - the user table(s) for previous years. These are
* users&lt;YEAR&gt; - the user table(s) for previous years. These are
kept for reference and archival purposes only and are not actively used.

<li><a href=#usertypes>usertypes</a> - contains a list of accepted usertypes
* usertypes - contains a list of accepted usertypes

<li><a href=#students>students</a> - contains basic information on all
* students - contains basic information on all
DCU students (id number, name, email, course, year).

<li><a href=#staff>staff</a> - contains basic information on most
* staff - contains basic information on most
DCU staff (id number, name, email).

<li><a href=#reserved>reserved</a> - contains a list of additional
* reserved - contains a list of additional
reserved names.

</ul>

<p>The traditional <code>/etc/passwd</code>, <code>/etc/shadow</code> and
<code>/etc/group</code> files in addition to the filesystem store Unix account
information.</p>
The traditional `/etc/passwd`, `/etc/shadow` and
`/etc/group` files in addition to the filesystem store Unix account
information.

<a name=data></a><h2>User data</h2>
## User data

<p>The traditional UNIX <code>/etc/passwd</code> database doesn't contain
The traditional UNIX `/etc/passwd` database doesn't contain
enough information for user accounts for RedBrick's needs (nor does it support
complex queries that a database can) hence the need for a user database. Following
are descriptions of the various database tables:

<a name=sql-users></a><h3>users [<a href=userdb_users.sql>schema</a>]</h3>
### users [schema]

<dt>Username</dt>

@@ -314,7 +271,7 @@ are descriptions of the various database tables:
<dt>Usertype</dt>

<dd>Corresponds to both UNIX group and type of user. This references
the usertype foreign key in the <a href=#usertypes>usertypes</a> table to
the usertype foreign key in the usertypes table to
ensure it is valid.</dd>

<dt>Newbie</dt>
@@ -372,14 +329,14 @@ the current time &amp; date so there's no need to explicitly set it.</dd>
Only applies to real user accounts (i.e. member, staff, associat, committe,
guest).</dd>

<a name=usertypes></a><h3>usertypes [<a href=userdb_usertypes.sql>schema</a>]</h3>
### usertypes [schema]

<dt>Usertype</dt>

<dd>Name of usertype. As these correspond to real Unix groups, there is a limit
of maximum length 8 characters.

<p>Description of usertypes:</p>
Description of usertypes:

<dt>system</dt>

@@ -431,7 +388,7 @@ current secretary/chair of the society.

<dd>Account for a Redbrick/DCU/Academic/Course project. Username set to
abbreviation of project name, name set to full project name, email set to a
contact address for the project leader.</a>
contact address for the project leader.

<dt>redbrick</dt>

@@ -444,12 +401,11 @@ if appropriate, otherwise the redbrick committee.</dd>
<dd>Guest accounts. For accounts that don't fit into any of the above types.
These must be approved by the committee on a per-user basis.</dd>

<a name=students></a><h3>students [<a href=userdb_students.sql>schema</a>]</h3>
### students [schema]

<p>This database is updated nightly from DCU's LDAP server (host: atlas.dcu.ie,
base DN: 'ou=Students, o=DCU', search filter: objectClass=person) by <a
href=rebuild_userdb_students.html>rebuild_userdb_students</a> launched by
cron.</p>
This database is updated nightly from DCU's LDAP server (host: atlas.dcu.ie,
base DN: 'ou=Students, o=DCU', search filter: objectClass=person) by rebuild_userdb_students launched by
cron.

<dt>id</dt>

@@ -473,12 +429,11 @@ cron.</p>
used sometimes, e.g: 'X' for exchange student, so can't use an integer
type).</dd>

<a name=staff></a><h3>staff [<a href=userdb_staff.sql>schema</a>]</h3>
### staff [schema]

<p>This database is updated nightly from DCU's LDAP server (host: atlas.dcu.ie,
base DN: 'ou=Staff, o=DCU', search filter: objectClass=person) by <a
href=rebuild_userdb_staff.html>rebuild_userdb_staff</a> launched by
cron.</p>
This database is updated nightly from DCU's LDAP server (host: atlas.dcu.ie,
base DN: 'ou=Staff, o=DCU', search filter: objectClass=person) by rebuild_userdb_staff launched by
cron.

<dt>id</dt>

@@ -493,15 +448,15 @@ Non-null unique integer.</dd>

<dd>DCU email address. Non-null string.</dd>

<a name=reserved></a><h3>reserved [<a href=userdb_reserved.sql>schema</a>]</h3>
### reserved [schema]

<p>This database is updated nightly from the various email alias files, Unix
This database is updated nightly from the various email alias files, Unix
group names and DCU entries for the redbrick domain and any other zones the
society host. Note that the entries in this table are not strictly reserved,
they can be ignored if necessary (e.g. creating a system user in the database
which already has the Unix group setup in advance, etc.). Also of note is that
these entries are not permanent, as the entire table is purged and rebuilt.
Permanent reserved entries belong in the users table as noted previously.</p>
Permanent reserved entries belong in the users table as noted previously.

<dt>username</dt>

@@ -512,34 +467,25 @@ Permanent reserved entries belong in the users table as noted previously.</p>
<dd>Information about the source/nature of this reserved username. Non-null
string.</dd>

<a name=boundary></a><h2>Software and Hardware Boundaries</h2>
## Software and Hardware Boundaries

<p>The project uses the OS native command line tools for performing all
UNIX <code>/etc/passwd</code> operations and the majority of account
operations. The 3rd party utility <code>setquota</code> is used for
The project uses the OS native command line tools for performing all
UNIX `/etc/passwd` operations and the majority of account
operations. The 3rd party utility `setquota` is used for
the modification of disk quotas. DCU student and staff information is retrieved
from the publically accessible LDAP service on <code>atlas.dcu.ie</code>.</p>
from the publically accessible LDAP service on `atlas.dcu.ie`.

<a name=refs></a><h2>References</h2>
## References

<h3>Software</h3>
### Software

<ul>
<li><a href='http://www.python.org/'>Python</a>
<li><a href='http://www.postgresql.org/'>PostgresSQL</a>
</ul>
* Python
* PostgresSQL

<h3>UNIX (Solaris) user administration tool manpages</h3>
### UNIX (Solaris) user administration tool manpages

<ul>
<li><a href="http://www.uwsg.iu.edu/usail/man/solaris/useradd.1.html">useradd</a>
<li><a href="http://www.uwsg.iu.edu/usail/man/solaris/usermod.1.html">usermod</a>
<li><a href="http://www.uwsg.iu.edu/usail/man/solaris/userdel.1.html">userdel</a>
</ul>

<hr>
* useradd
* usermod
* userdel

$Id: tech-manual.html,v 1.1 2003/03/28 16:37:38 cns Exp $

</body>
</html>

+ 306
- 0
docs/user-manual.md View File

@@ -0,0 +1,306 @@
# User Manual: RedBrick Registration System

*Cillian Sharkey, CASE3, 50716197*

1. Using useradm
* Running useradm
* Using useradm
* Common command line options
2. Using rrs web interface
* card - card reader interface
* add - Add new user
* delete - Delete user
* renew - Renew user
* update - Update user
* rename - Rename user
* convert - Convert user to new usertype
* show - Show user information
* freename - Check if a username is free
* search - Search user and DCU databases
* stats - Database statistics
* log - Log of all actions

## Using useradm

### Running useradm

For performing any account operations, `useradm` 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.

The `useradm` 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 `/usr/local/rrs`. It could be run as follows:

```
main# <b>/usr/local/rrs/useradm</b>
Usage: useradm command [options]
'useradm -h' for more info on available commands
```
*[OR]*

```
main# <b>cd /usr/local/rrs</b>
main# <b>./useradm</b>
Usage: useradm command [options]
'useradm -h' for more info on available commands
```

"`useradm -h`" gives a full listing of all commands available. For
full usage and command line options for a given command, use "`useradm
command -h`" e.g:

```
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 &amp; 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)
```

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.

### Using useradm

The basic operation involves the prompting of the user for information. Examples
of the prompt follow:

```
Enter usertype
(hints) [member] &gt;&gt;

Enter new username
[no default] &gt;&gt;

Enter birthday as 'YYYY-MM-DD'
(optional) [1982-06-20] &gt;&gt;
```

The prompt has the following features:


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

* Default answer - if a default answer is provided, it is shown in
square brackets `[like this]`. To accept the default, simply
hit `RETURN`. If no default is provided it will be shown as
`[no default]`. In this case hitting `RETURN` is
equivalent to giving an empty answer.

* Optional questions - indicated by "`(optional)`" 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 (`EOF`)
control sequence (instead of `RETURN` which will give the
default answer). `EOF` is typically Control-D on UNIX
systems.

* Tab completion - if a default answer is provided or a set of hints
(indicated by "`(hints)`" beside the prompt) then pressing
`TAB` will cycle through all possible answers when no text
has been entered at the prompt. When some text has been entered and
`TAB` is pressed, it will only cycle through possible answers
that start with the given text.

* 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
`WARNING` and not `FATAL`, 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 `WARNING` errors that occur when
action is performed after all user input is complete will also be
ignored (they will be displayed however).



### Common command line options

A number of command line options are common to all commands:

* `-T` 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 `unpaid_delete` or `sync` for
example.

* `-d` 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.

* `-a` account only mode. This ensures that only account
actions will be performed. This is especially useful if for example
a database &amp; 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 `rename` or a `convert` 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 `usermod` 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.


## Using rrs web interface

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:

### card - card reader interface

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.

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 `RETURN` is enough to
renew the user after checking that their user details are correct.

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.

### add - Add new user

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.

### delete - Delete user

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.

### renew - Renew user

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.

### update - Update user

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 `updated_by` and `updated_at`
attributes.

### rename - Rename user

Simply changes a user's username. Note that currently the old username
becomes available as soon as it is renamed.

### convert - Convert user to new usertype

Note that only conversions for "paying" usertypes are supported.

### show - Show user information

Shows database information for given username.

### freename - Check if a username is free

Simply checks for a free new username.

### search - Search user and DCU databases

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 *same* DCU ID number) will appear
with a 'show' button so that their database entry can be displayed quickly and
easily.

### stats - Database statistics

Simply displays database statistics.

### log - Log of all actions

Shows a detailed log of all user actions that were performed and all user
input that was given including a time stamp.

$Id: user-manual.html,v 1.1 2003/03/28 16:39:08 cns Exp $

Loading…
Cancel
Save