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.

326 lines
13 KiB

  1. <html>
  2. <head>
  3. <title>User Manual: RedBrick Registration System</title>
  4. <link rel="stylesheet" href="doc.css" type="text/css">
  5. </head>
  6. <body>
  7. <h1>User Manual:<br>RedBrick Registration System</h1>
  8. <p><i>Cillian Sharkey, CASE3, 50716197</i></p>
  9. <ol>
  10. <li><a href="#useradm">Using useradm</a>
  11. <ol>
  12. <li><a href="#running">Running useradm</a>
  13. <li><a href="#using">Using useradm</a>
  14. <li><a href="#common">Common command line options</a>
  15. </ol>
  16. <li><a href="#rrs">Using rrs web interface</a>
  17. <ol>
  18. <li><a href="#card">card - card reader interface</a>
  19. <li><a href="#add">add - Add new user</a>
  20. <li><a href="#delete">delete - Delete user</a>
  21. <li><a href="#renew">renew - Renew user</a>
  22. <li><a href="#update">update - Update user</a>
  23. <li><a href="#rename">rename - Rename user</a>
  24. <li><a href="#convert">convert - Convert user to new usertype</a>
  25. <li><a href="#show">show - Show user information</a>
  26. <li><a href="#freename">freename - Check if a username is free</a>
  27. <li><a href="#search">search - Search user and DCU databases</a>
  28. <li><a href="#stats">stats - Database statistics</a>
  29. <li><a href="#log">log - Log of all actions</a>
  30. </ol>
  31. </ol>
  32. <a name=useradm></a><h2>Using useradm</h2>
  33. <a name=running></a><h3>Running useradm</h3>
  34. <p>For performing any account operations, <code>useradm</code> must be run as
  35. root (superuser). For accessing only database information, an unprivilged user
  36. account (that has been granted access to the database) can be used. All
  37. examples below assume running as root on the main server where both accounts
  38. and user database live.</p>
  39. <p>The <code>useradm</code> script can be run from anywhere, as long as it is
  40. in the same directory as the rest of the rrs distribution. Say rrs is installed
  41. in <code>/usr/local/rrs</code>. It could be run as follows:</p>
  42. <pre>
  43. main# <b>/usr/local/rrs/useradm</b>
  44. Usage: useradm command [options]
  45. 'useradm -h' for more info on available commands
  46. <i>[OR]</i>
  47. main# <b>cd /usr/local/rrs</b>
  48. main# <b>./useradm</b>
  49. Usage: useradm command [options]
  50. 'useradm -h' for more info on available commands</pre>
  51. <p>"<code>useradm -h</code>" gives a full listing of all commands available. For
  52. full usage and command line options for a given command, use "<code>useradm
  53. command -h</code>" e.g:</p>
  54. <pre>
  55. main# <b>./useradm -h</b>
  56. Usage: useradm command [options]
  57. Single user commands:
  58. add Add new user
  59. delete Delete user
  60. renew Renew user
  61. update Update user
  62. rename Rename user
  63. convert Change user to a different usertype
  64. Single account commands:
  65. resetpw Set new random password and mail it to user
  66. resetsh Reset user's shell
  67. disuser Disuser a user
  68. reuser Re-user a user
  69. Single user information commands:
  70. show Show user details
  71. freename Check if a username is free
  72. Interactive batch commands:
  73. search Search user and dcu databases
  74. sync Synchronise accounts with userdb (for RRS)
  75. sync_dcu_info Interactive update of userdb using dcu database info
  76. Batch commands:
  77. newyear Prepare database for start of new academic year
  78. unpaid_warn Warn (mail) all non-renewed users
  79. unpaid_disable Disable all normal non-renewed users
  80. unpaid_delete Delete all grace non-renewed users
  81. Batch information commands
  82. newbies_list List all paid newbies
  83. renewals_list List all paid renewals (non-newbie)
  84. freename_list List all usernames that are taken
  85. unpaid_list List all non-renewed users
  86. unpaid_list_normal List all normal non-renewed users
  87. unpaid_list_reset List all normal non-renewed users with reset shells
  88. unpaid_list_grace List all grace non-renewed users
  89. Miscellaneous commands:
  90. checkdb Check database for inconsistencies
  91. stats Show database and account statistics
  92. 'useradm command -h' for more info on a command's options &amp; usage.
  93. main# <b>./useradm add -h</b>
  94. Add new user
  95. Usage: useradm add [options] [username]
  96. -h Display this usage
  97. -T Test mode, show what would be done
  98. -d Perform database operations only
  99. -a Perform unix account operations only
  100. -u username Unix username of who updated this user
  101. -f Set newbie (fresher) to true
  102. -F Opposite of -f
  103. -m Send account details to user's alternate email address
  104. -M Opposite of -m
  105. -o Override warning errors
  106. -p Set new random password
  107. -P Opposite of -p
  108. -t usertype Type of account
  109. -n name Real name or account description
  110. -e email Alternative email address
  111. -i id Student/Staff ID
  112. -c course DCU course (abbreviation)
  113. -y year DCU year
  114. -s years paid Number of years paid (subscription)
  115. -b birthday Birthday (format YYYY-MM-DD)</pre>
  116. <p>While useradm is primarily designed for user interaction, all required user
  117. input can be provided on the command line by the use of options and
  118. arguments as shown above.</p>
  119. <a name=using></a><h3>Using useradm</h3>
  120. <p>The basic operation involves the prompting of the user for information. Examples
  121. of the prompt follow:</p>
  122. <pre>
  123. Enter usertype
  124. (hints) [member] &gt;&gt;
  125. Enter new username
  126. [no default] &gt;&gt;
  127. Enter birthday as 'YYYY-MM-DD'
  128. (optional) [1982-06-20] &gt;&gt;</pre>
  129. <p>The prompt has the following features:</p>
  130. <ul>
  131. <li>Line editing (provided by readline) - this allows for easy editing
  132. of data at the prompt and provides a history of previously input data
  133. that is accessible by using the up and down arrow keys.
  134. <li>Default answer - if a default answer is provided, it is shown in
  135. square brackets <code>[like this]</code>. To accept the default, simply
  136. hit <code>RETURN</code>. If no default is provided it will be shown as
  137. <code>[no default]</code>. In this case hitting <code>RETURN</code> is
  138. equivalent to giving an empty answer.</p>
  139. <li>Optional questions - indicated by "<code>(optional)</code>" beside
  140. the prompt. Giving an empty answer is taken as not answering the
  141. question. If however, a default answer is provided and you want to give
  142. an empty answer, you must use the End Of File (<code>EOF</code>)
  143. control sequence (instead of <code>RETURN</code> which will give the
  144. default answer). <code>EOF</code> is typically Control-D on UNIX
  145. systems.
  146. <li>Tab completion - if a default answer is provided or a set of hints
  147. (indicated by "<code>(hints)</code>" beside the prompt) then pressing
  148. <code>TAB</code> will cycle through all possible answers when no text
  149. has been entered at the prompt. When some text has been entered and
  150. <code>TAB</code> is pressed, it will only cycle through possible answers
  151. that start with the given text.
  152. <li>Error handling - if an error occurs during the input of user data
  153. it will be displayed and the question will be asked again until correct
  154. or valid input is provided. If however, the error is only a
  155. <code>WARNING</code> and not <code>FATAL</code>, then the option to
  156. override (i.e. essentially "ignore") the error is provided. If you
  157. answer No, you go back to the question prompt again. If you answer Yes,
  158. you advance to the next question or step. Answering yes also sets the
  159. 'override' option so any <code>WARNING</code> errors that occur when
  160. action is performed after all user input is complete will also be
  161. ignored (they will be displayed however).
  162. </ul>
  163. <a name=common></a><h3>Common command line options</h3>
  164. <p>A number of command line options are common to all commands:</p>
  165. <ul>
  166. <li><code>-T</code> test mode. This runs through all user input and
  167. questions but it does not perform any actions. Rather, it prints out
  168. exactly what would be done. Any SQL INSERTs, UPDATEs or DELETEs that
  169. would be sent to the database, what local commands (and their
  170. arguments) would be executed (and any input that would be given to
  171. them) the contents of any email messages that would be sent, etc. This
  172. is extremely handy if you are unsure as to what a command will do or if
  173. you just want to be careful before performing any of the batch
  174. operations, like <code>unpaid_delete</code> or <code>sync</code> for
  175. example.
  176. <li><code>-d</code> database only mode. This ensures that only database
  177. actions will be performed. This is especially useful when using useradm
  178. with the web setup where the local accounts don't exist. It is also
  179. useful for making changes to the database so that is up to date with
  180. the corresponding account(s) if they are out of sync.
  181. <li><code>-a</code> account only mode. This ensures that only account
  182. actions will be performed. This is especially useful if for example
  183. a database &amp; account operation failed on the account operation and
  184. needed to be completed later after fixing the source of the problem. An
  185. example of this is a <code>rename</code> or a <code>convert</code> of a
  186. user who was currently logged in at the time. In this case the database
  187. operation would complete succesfully however the account operation which
  188. uses <code>usermod</code> would fail as it would not operate on a
  189. currently logged-in user. Note that this was only apparent with the Solaris
  190. implementation of the command. Other uses would be to operate on an account
  191. that does not exist in the database for whatever reasons.
  192. </ul>
  193. <a name=rrs></a><h2>Using rrs web interface</h2>
  194. <p>The web interface is designed to be rather intuitive and easy to use. The
  195. top of the page contains a menu with the following commands available:</p>
  196. <a name=card></a><h3>card - card reader interface</h3>
  197. <p>This is designed to be the main interface when using rrs. The card ID input
  198. field is automatically focused on page load so it is ready to accept input from
  199. either a magnetic card reader, barcode scanner or plain user input.</p>
  200. <p>If the given DCU ID number is already in the database it will present the
  201. user renewal form with the users' current details along with any updated
  202. details from the DCU databases (e.g. course and year will change for students,
  203. or an invalid email address may have been fixed, etc.). If the user has already
  204. paid however, it will issue a warning message and remain on the card reader
  205. page. This is prevents users accidentally paying again for an already paid
  206. account. The new username input field is automatically focused to allow for
  207. quick entry of the user's preferred choice of new username (if any). Typically
  208. nothing needs to be changed so simply pressing <code>RETURN</code> is enough to
  209. renew the user after checking that their user details are correct.</p>
  210. <p>Otherwise it must be a new user so details are loaded in from the DCU
  211. databases along with reasonable default values (e.g. years paid will be 1). The
  212. username input field will be automatically focused to allow for quick entry of
  213. the user's preferred choice of username.</p>
  214. </p>
  215. <a name=add></a><h3>add - Add new user</h3>
  216. <p>A more 'manual' approach to adding new users. It provides a blank form for
  217. adding a new user. Leaving out details and submitting the form will fill in any
  218. missing information if possible until there is enough information to add the
  219. user succesfully.</p>
  220. <a name=delete></a><h3>delete - Delete user</h3>
  221. <p>Simply deletes user from database. Note that in reality it should be very
  222. rare for anyone to request an account deletion but the feature is provided just
  223. in case.</p>
  224. <a name=renew></a><h3>renew - Renew user</h3>
  225. <p>A more 'manual' approach to renewing users. It provides a blank form for
  226. renewing a new user. Leaving out details and submitting the form will fill in
  227. any missing information if possible until there is enough information to renew
  228. the user succesfully.</p>
  229. <a name=update></a><h3>update - Update user</h3>
  230. <p>Similar to the renewal form except only the users' current database
  231. information is displayed for easy modification. No new information from the DCU
  232. databases or defaults are provided so an update of a user without changing any
  233. of the input fields has no visible change of the users' information other than
  234. the updating of the <code>updated_by</code> and <code>updated_at</code>
  235. attributes.</p>
  236. <a name=rename></a><h3>rename - Rename user</h3>
  237. <p>Simply changes a user's username. Note that currently the old username
  238. becomes available as soon as it is renamed.</p>
  239. <a name=convert></a><h3>convert - Convert user to new usertype</h3>
  240. <p>Note that only conversions for "paying" usertypes are supported.</p>
  241. <a name=show></a><h3>show - Show user information</h3>
  242. <p>Shows database information for given username.</p>
  243. <a name=freename></a><h3>freename - Check if a username is free</h3>
  244. <p>Simply checks for a free new username.</p>
  245. <a name=search></a><h3>search - Search user and DCU databases</h3>
  246. <p>Allows for searching by username, name or ID number. Note that the SQL
  247. wildcard characters '_' for a single character and '%' for any number of
  248. characters can be used. Any student or staff entries that have a RedBrick
  249. account (i.e. a datbase entry with the <i>same</i> DCU ID number) will appear
  250. with a 'show' button so that their database entry can be displayed quickly and
  251. easily.</p>
  252. <a name=stats></a><h3>stats - Database statistics</h3>
  253. <p>Simply displays database statistics.</p>
  254. <a name=log></a><h3>log - Log of all actions</h3>
  255. <p>Shows a detailed log of all user actions that were performed and all user
  256. input that was given including a time stamp.</p>
  257. <hr>
  258. $Id: user-manual.html,v 1.1 2003/03/28 16:39:08 cns Exp $
  259. </body>
  260. </html>