Redbrick User management tool
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

546 lines
19 KiB

  1. <html>
  2. <head>
  3. <title>Technical Manual: RedBrick Registration System</title>
  4. <link rel="stylesheet" href="doc.css" type="text/css">
  5. </head>
  6. <body>
  7. <h1>Technical Manual:<br>RedBrick Registration System</h1>
  8. <p><i>Cillian Sharkey, CASE3, 50716197</i></p>
  9. <ol>
  10. <li><a href="#overview">Overview of project</a>
  11. <ol>
  12. <li><a href="#background">Background</a>
  13. <li><a href="#users">Users</a>
  14. <li><a href="#features">Features</a>
  15. <li><a href="#constraints">Constraints</a>
  16. </ol>
  17. <li><a href="#arch">System architecture</a>
  18. <ol>
  19. <li><a href="#clients">Clients</a>
  20. <li><a href="#middle">Middle end</a>
  21. <li><a href="#back">Back end</a>
  22. </ol>
  23. <li><a href="#data">User data</a>
  24. <ol>
  25. <li><a href="#sql-users">users</a>
  26. <li><a href="#usertypes">usertypes</a>
  27. <li><a href="#students">students</a>
  28. <li><a href="#staff">staff</a>
  29. <li><a href="#reserved">reserved</a>
  30. </ol>
  31. <li><a href="#boundary">Software and Hardware Boundaries</a>
  32. <li><a href="#refs">References</a>
  33. </ol>
  34. <a name=overview></a><h2>Overview of project</h2>
  35. <a name=background></a><h3>Background</h3>
  36. <p>There are just over 1,800 accounts on the RedBrick UNIX system and so the
  37. administration of user accounts forms a large part of the system
  38. administrators' workload. As one of the system administrators for RedBrick
  39. myself, I have first hand experience of the amount of work required in
  40. administrating user accounts and dealing with account requests on an often
  41. daily basis. In addition to this, each year at the clubs &amp; societies day
  42. the registration of new and renewal of existing users takes place. Hundreds
  43. of users are processed on a small isolated network of computers. The goal of
  44. this project is to reduce the workload of system administrators and ease the
  45. administration and registration of users both on a daily basis and for the annual
  46. clubs and societies day.</p>
  47. <a name=users></a><h3>Users</h3>
  48. <p>The users of the system will be restricted to the system administrators
  49. for day to day user administration as it requires root (superuser) access, however
  50. for registration on clubs &amp; societies day it is usual for other members of the
  51. society committee to help out.</p>
  52. <a name=features></a><h3>Features</h3>
  53. <ul>
  54. <li><p>The entire system is written in Python, whose website describes
  55. it as:</p>
  56. <blockquote>
  57. <p>"Python is an interpreted, interactive, object-oriented
  58. programming language. It is often compared to Tcl, Perl, Scheme
  59. or Java. Python combines remarkable power with very clear
  60. syntax. It has modules, classes, exceptions, very high level
  61. dynamic data types, and dynamic typing. The Python
  62. implementation is portable: it runs on many brands of UNIX, on
  63. Windows, DOS, OS/2, Mac, Amiga... "</p>
  64. </blockquote>
  65. <li><p>Provides a flexible, automated and consistent (UNIX command
  66. line) interface (<code>useradm</code>) for performing both common
  67. day-to-day and occassional "batch" user administration operations on
  68. the actual accounts (home directories, mail spools, disk quotas etc.),
  69. the UNIX <code>/etc/passwd</code> "database" and the user database
  70. ensuring that all are kept in sync. The following functions are
  71. provided:</p>
  72. <ul>
  73. <li>adding new accounts,
  74. <li>deleting existing accounts,
  75. <li>renaming existing accounts,
  76. <li>converting existing accounts "usertype",
  77. <li>renewing existing accounts,
  78. <li>reseting accounts with new random password (and emailing password
  79. to user)
  80. <li>reseting accounts with disabled Unix shells,
  81. <li>retrieving account information for display,
  82. <li>checking the availability of usernames for new accounts,
  83. </ul>
  84. <p>Batch account operations include:</p>
  85. <ul>
  86. <li>emailing renewal reminders to non-renewed accounts
  87. <li>expiring non-renewed accounts (i.e. disabling login shell)
  88. <li>deleting non-renewed accounts after a grace period
  89. <li>checking for inconsistencies between the user database and the
  90. UNIX <code>/etc/passwd</code> database
  91. <li>interactive update of the user database from the latest copy of
  92. the public DCU student database
  93. </ul>
  94. <p>Other information available:</p>
  95. <ul>
  96. <li>searching user and DCU databases,
  97. <li>database and account statistics
  98. </ul>
  99. <p>The following is the output for the command usage help from
  100. <code>useradm</code> when given the '-h' option which lists all
  101. the names of the functions the script performs.</p>
  102. <pre>Usage: useradm command [options]
  103. Single user commands:
  104. add Add new user
  105. delete Delete user
  106. renew Renew user
  107. update Update user
  108. rename Rename user
  109. convert Change user to a different usertype
  110. Single account commands:
  111. resetpw Set new random password and mail it to user
  112. resetsh Reset user's shell
  113. disuser Disuser a user
  114. reuser Re-user a user
  115. Single user information commands:
  116. show Show user details
  117. freename Check if a username is free
  118. Interactive batch commands:
  119. search Search user and dcu databases
  120. sync Synchronise accounts with userdb (for RRS)
  121. sync_dcu_info Interactive update of userdb using dcu database info
  122. Batch commands:
  123. newyear Prepare database for start of new academic year
  124. unpaid_warn Warn (mail) all non-renewed users
  125. unpaid_disable Disable all normal non-renewed users
  126. unpaid_delete Delete all grace non-renewed users
  127. Batch information commands:
  128. newbies_list List all paid newbies
  129. renewals_list List all paid renewals (non-newbie)
  130. freename_list List all usernames that are taken
  131. unpaid_list List all non-renewed users
  132. unpaid_list_normal List all normal non-renewed users
  133. unpaid_list_reset List all normal non-renewed users with reset shells
  134. unpaid_list_grace List all grace non-renewed users
  135. Miscellaneous commands:
  136. checkdb Check database for inconsistencies
  137. stats Show database and account statistics
  138. 'useradm command -h' for more info on a command's options &amp; usage.</pre>
  139. <li><p>Provides a web interface (<code>rrs</code>) to offer a similar
  140. set of single user administration operations for use on the clubs &amp;
  141. societies day. While not as fully featured or as flexible as
  142. <code>useradm</code>, the interface is designed primarily for speed and
  143. efficiency.</p>
  144. <p>To achieve this, user input fields are automatically focused on page
  145. load (using Javascript) to save using the keyboard or mouse to select
  146. the input box; input from barcode scanners or magnetic strip
  147. readers (for use with DCU staff and student cards) is accepted which
  148. considerably speeds up the process and eliminates the potential for
  149. human error.</p>
  150. <p>The setup is generally that of a small number of networked computers
  151. that are isolated from the RedBrick servers so changes would be made to
  152. a local (seperate) copy of the user database and at the end of the day
  153. all of these changes (i.e. new, renewed, renamed, converted, etc.
  154. accounts) must be detected and synchronised with the actual accounts
  155. and UNIX <code>/etc/passwd</code> database on the system. This needs to
  156. be done in batch as hundreds of accounts are processed on clubs &amp;
  157. societies day. This is implemented as the <a
  158. href=useradm.html#-sync>sync</a> command in
  159. <code>useradm</code>. Features which <code>rrs</code> provides:</p>
  160. <ul>
  161. <li>adding new users,
  162. <li>deleting existing users,
  163. <li>renaming existing users,
  164. <li>converting existing users "usertype",
  165. <li>renewing existing users,
  166. <li>retrieving user information for display,
  167. <li>checking the availability of usernames for new users,
  168. <li>searching user and DCU databases,
  169. <li>database statistics,
  170. <li>a detailed log of all actions performed,
  171. </ul>
  172. <li>Prevent username conflicts with other namespaces on the system e.g.
  173. email aliases, mailing lists, DNS entries for the redbrick.dcu.ie and
  174. other domains the society host. Achieved through the use of the <a
  175. href=#reserved>reserved</a> table.
  176. </ul>
  177. <a name=constraints></a><h3>Constraints</h3>
  178. <ul>
  179. <li>All accounts must have a name (or description) and an alternate
  180. email address for contact purposes (and as such all UNIX accounts must
  181. have a corresponding entry in the user database).
  182. <li>Users may only have one account on the system (i.e. one student ID
  183. per account).
  184. <li>Member, staff and associate accounts should have a valid DCU
  185. student/staff ID associated with them.
  186. <li>Usernames are limited to what the underlying UNIX OS supports, i.e.
  187. maximum length of 8 characters, small set of available characters (a-z,
  188. 0-9, '-', '_', '.'), etc.
  189. </ul>
  190. <a name=arch></a><h2>System architecture</h2>
  191. <p>The system is 3 tier in nature:</p>
  192. <a name=clients></a><h3>Clients</h3>
  193. <p>There are two client applications:</p>
  194. <ul>
  195. <li><a href=rrs.html>rrs:</a> a CGI web interface (primarily for use on
  196. the annual clubs &amp; societies day to register new members and renew
  197. existing members)
  198. <li><a href=useradm.html>useradm:</a> a UNIX command line interface for
  199. day-to-day user administration.
  200. </ul>
  201. <p>Additional maintenance scripts:</p>
  202. <ul>
  203. <li><a href=rebuild_userdb_reserved.html>rebuild_userdb_reserved</a> -
  204. rebuilds reserved table
  205. <li><a href=rebuild_userdb_staff.html>rebuild_userdb_staff</a> - rebuilds
  206. staff table
  207. <li><a href=rebuild_userdb_students.html>rebuild_userdb_students</a> -
  208. rebuilds students table
  209. <li>dump_userdb.sh - Unix shell script to backup entire user database
  210. and provide local text copies for quick perusal with standard Unix
  211. tools such as grep, etc.
  212. </ul>
  213. <a name=middle></a><h3>Middle end</h3>
  214. <p>There are two main modules and a number of supporting modules which the two
  215. client applications (and any potential future applications) use. These are:</p>
  216. <ul>
  217. <li><a href=rbuserdb.html>rbuserdb:</a> performs all database operations
  218. <li><a href=rbaccount.html>rbaccount:</a> performs all local UNIX
  219. account operations
  220. <li><a href=rberror.html>rberror:</a> contains custom exception classes
  221. (RBError, RBFatalError, RBWarningError) for our own types of errors
  222. <li><a href="rbuser.html">rbuser:</a> contains RBUser class for
  223. representing a user
  224. <li><a href="rbopt.html">rbopt:</a> contains RBOpt class for storing
  225. user options and sharing between the various modules
  226. </ul>
  227. <p>Note that the web interface does not make use of the rbaccount module however,
  228. as it operates on the database only.</p>
  229. <a name=back></a><h3>Back end</h3>
  230. <p>A PostgresSQL database contains the following tables:</p>
  231. <ul>
  232. <li><a href=#users>users</a> - the current user table
  233. <li>users&lt;YEAR&gt; - the user table(s) for previous years. These are
  234. kept for reference and archival purposes only and are not actively used.
  235. <li><a href=#usertypes>usertypes</a> - contains a list of accepted usertypes
  236. <li><a href=#students>students</a> - contains basic information on all
  237. DCU students (id number, name, email, course, year).
  238. <li><a href=#staff>staff</a> - contains basic information on most
  239. DCU staff (id number, name, email).
  240. <li><a href=#reserved>reserved</a> - contains a list of additional
  241. reserved names.
  242. </ul>
  243. <p>The traditional <code>/etc/passwd</code>, <code>/etc/shadow</code> and
  244. <code>/etc/group</code> files in addition to the filesystem store Unix account
  245. information.</p>
  246. <a name=data></a><h2>User data</h2>
  247. <p>The traditional UNIX <code>/etc/passwd</code> database doesn't contain
  248. enough information for user accounts for RedBrick's needs (nor does it support
  249. complex queries that a database can) hence the need for a user database. Following
  250. are descriptions of the various database tables:
  251. <a name=sql-users></a><h3>users [<a href=userdb_users.sql>schema</a>]</h3>
  252. <dt>Username</dt>
  253. <dd>Unique UNIX username. Primary key, must be non-null and 8 characters maximum.</dd>
  254. <dt>Usertype</dt>
  255. <dd>Corresponds to both UNIX group and type of user. This references
  256. the usertype foreign key in the <a href=#usertypes>usertypes</a> table to
  257. ensure it is valid.</dd>
  258. <dt>Newbie</dt>
  259. <dd>Boolean; true if user is a new user this academic year. Must be
  260. non-null.</dd>
  261. <dt>Name/Description</dt>
  262. <dd>User's full name or a description for non-user accounts (e.g.
  263. project/system accounts). Must be non-null.</dd>
  264. <dt>Email</dt>
  265. <dd>Alternate contact address (typically DCU email address). Must be non-null.</dd>
  266. <dt>Student ID</dt>
  267. <dd>DCU student (or staff) ID number, compulsory for member, staff and
  268. associates optional for all other usertypes. Must be unique.</dd>
  269. <dt>Years paid</dt>
  270. <dd>Number of years paid, compulsory for member, staff and associates optional
  271. for all other usertypes (only used by committe and guests though). Non-renewed
  272. accounts (referred to as 'normal') will be 0 if they were renewed for the
  273. previous year or -1 (referred to as 'grace') if they were not.</dd>
  274. <dt>Updated by</dt>
  275. <dd>Username of the administrator who last updated the database entry. Must be
  276. non-null.</dd>
  277. <dt>Updated at</dt>
  278. <dd>Date &amp; time of when the database entry was last updated. This is
  279. updated automatically by a database trigger for all INSERT and UPDATE
  280. operations on the table by setting it to the current time &amp; date.</dd>
  281. <dt>Created by</dt>
  282. <dd>Username of the administrator who first created the account. This should be
  283. set once at account creation time (INSERT). The default value for this is the
  284. same as updated_by, so there's no need to explicitly set it.</dd>
  285. <dt>Created at</dt>
  286. <dd>Date &amp; time of when the database entry was first created. This should
  287. be set once at account creation time (INSERT). The default value for this is
  288. the current time &amp; date so there's no need to explicitly set it.</dd>
  289. <dt>Birthday</dt>
  290. <dd>Optional date, to be potentially used for birthday notifications, etc.
  291. Only applies to real user accounts (i.e. member, staff, associat, committe,
  292. guest).</dd>
  293. <a name=usertypes></a><h3>usertypes [<a href=userdb_usertypes.sql>schema</a>]</h3>
  294. <dt>Usertype</dt>
  295. <dd>Name of usertype. As these correspond to real Unix groups, there is a limit
  296. of maximum length 8 characters.
  297. <p>Description of usertypes:</p>
  298. <dt>system</dt>
  299. <dd>System accounts, pseudo-user accounts etc. Default name: 'System Account',
  300. default email: 'admins@redbrick.dcu.ie'.</dd>
  301. <dt>reserved</dt>
  302. <dd>Permanent reserved names (e.g. server hostnames, usernames that may cause
  303. potential confusion or misuse e.g. a username of 'redbrick', 'admin' etc.). These
  304. entries do NOT have corresponding Unix accounts (the system usertype is for that).
  305. Default name: 'Reserved Name, default email: 'admins@redbrick.dcu.ie'.
  306. <dt>founders</dt>
  307. <dd>A founder of the society member. A rather closed group, admittedly.</dd>
  308. <dt>member</dt>
  309. <dd>Current students of DCU only. Email should be their DCU email address.</dd>
  310. <dt>associat</dt>
  311. <dd>Graduates, former DCU students/staff or people otherwise officially
  312. associated with DCU (must have a DCU ID number).</dd>
  313. <dt>staff</dt>
  314. <dd>Current DCU staff members only. Email should be their DCU email address.</dd>
  315. <dt>club / society</dt>
  316. <dd>DCU Club/Society account. Name set to official name of club/society, email
  317. preferably set to a contact address for the current secretary/chair of that
  318. club/society.</dd>
  319. <dt>dcu</dt>
  320. <dd>General DCU body, organisation or role account (e.g. 'supres'). Name must
  321. be full description of entity, email address should be a DCU one.</dd>
  322. <dt>intersoc</dt>
  323. <dd>Account for another networking society. Username set to abbreviation of
  324. society name, name set to society name, email set to a contact address for the
  325. current secretary/chair of the society.
  326. <dt>projects</dt>
  327. <dd>Account for a Redbrick/DCU/Academic/Course project. Username set to
  328. abbreviation of project name, name set to full project name, email set to a
  329. contact address for the project leader.</a>
  330. <dt>redbrick</dt>
  331. <dd>Account for miscellaneous Redbrick activities (e.g. 'semnet', 'tutorial').
  332. Name set to description of account. Email set to redbrick user in charge of it
  333. if appropriate, otherwise the redbrick committee.</dd>
  334. <dt>guest</dt>
  335. <dd>Guest accounts. For accounts that don't fit into any of the above types.
  336. These must be approved by the committee on a per-user basis.</dd>
  337. <a name=students></a><h3>students [<a href=userdb_students.sql>schema</a>]</h3>
  338. <p>This database is updated nightly from DCU's LDAP server (host: atlas.dcu.ie,
  339. base DN: 'ou=Students, o=DCU', search filter: objectClass=person) by <a
  340. href=rebuild_userdb_students.html>rebuild_userdb_students</a> launched by
  341. cron.</p>
  342. <dt>id</dt>
  343. <dd>DCU Student ID (one of the values of 'cn'). Non-null unique integer.</dd>
  344. <dt>name</dt>
  345. <dd>Name (value of 'givenName' and 'sn' concatenated). Non-null string.</dd>
  346. <dt>email</dt>
  347. <dd>DCU email address. Non-null string.</dd>
  348. <dt>course</dt>
  349. <dd>DCU course (abbreviated version). Non-null string.</dd>
  350. <dt>year</dt>
  351. <dd>Year in DCU or 'N/A' if not available. Non-null string (characters are also
  352. used sometimes, e.g: 'X' for exchange student, so can't use an integer
  353. type).</dd>
  354. <a name=staff></a><h3>staff [<a href=userdb_staff.sql>schema</a>]</h3>
  355. <p>This database is updated nightly from DCU's LDAP server (host: atlas.dcu.ie,
  356. base DN: 'ou=Staff, o=DCU', search filter: objectClass=person) by <a
  357. href=rebuild_userdb_staff.html>rebuild_userdb_staff</a> launched by
  358. cron.</p>
  359. <dt>id</dt>
  360. <dd>DCU Staff ID (one of the values of 'cn', or extracted from 'gecos').
  361. Non-null unique integer.</dd>
  362. <dt>name</dt>
  363. <dd>Name (value of 'givenName' and 'sn' concatenated). Non-null string.</dd>
  364. <dt>email</dt>
  365. <dd>DCU email address. Non-null string.</dd>
  366. <a name=reserved></a><h3>reserved [<a href=userdb_reserved.sql>schema</a>]</h3>
  367. <p>This database is updated nightly from the various email alias files, Unix
  368. group names and DCU entries for the redbrick domain and any other zones the
  369. society host. Note that the entries in this table are not strictly reserved,
  370. they can be ignored if necessary (e.g. creating a system user in the database
  371. which already has the Unix group setup in advance, etc.). Also of note is that
  372. these entries are not permanent, as the entire table is purged and rebuilt.
  373. Permanent reserved entries belong in the users table as noted previously.</p>
  374. <dt>username</dt>
  375. <dd>A reserved username. Primary key.</dd>
  376. <dt>info</dt>
  377. <dd>Information about the source/nature of this reserved username. Non-null
  378. string.</dd>
  379. <a name=boundary></a><h2>Software and Hardware Boundaries</h2>
  380. <p>The project uses the OS native command line tools for performing all
  381. UNIX <code>/etc/passwd</code> operations and the majority of account
  382. operations. The 3rd party utility <code>setquota</code> is used for
  383. the modification of disk quotas. DCU student and staff information is retrieved
  384. from the publically accessible LDAP service on <code>atlas.dcu.ie</code>.</p>
  385. <a name=refs></a><h2>References</h2>
  386. <h3>Software</h3>
  387. <ul>
  388. <li><a href='http://www.python.org/'>Python</a>
  389. <li><a href='http://www.postgresql.org/'>PostgresSQL</a>
  390. </ul>
  391. <h3>UNIX (Solaris) user administration tool manpages</h3>
  392. <ul>
  393. <li><a href="http://www.uwsg.iu.edu/usail/man/solaris/useradd.1.html">useradd</a>
  394. <li><a href="http://www.uwsg.iu.edu/usail/man/solaris/usermod.1.html">usermod</a>
  395. <li><a href="http://www.uwsg.iu.edu/usail/man/solaris/userdel.1.html">userdel</a>
  396. </ul>
  397. <hr>
  398. $Id: tech-manual.html,v 1.1 2003/03/28 16:37:38 cns Exp $
  399. </body>
  400. </html>