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.

242 lines
9.1 KiB

  1. <html>
  2. <head>
  3. <title>Installation Manual: RedBrick Registration System</title>
  4. <link rel="stylesheet" href="doc.css" type="text/css">
  5. </head>
  6. <body>
  7. <h1>Installation Manual:<br>RedBrick Registration System</h1>
  8. <p><i>Cillian Sharkey, CASE3, 50716197</i></p>
  9. <ol>
  10. <li><a href="#intro">Introduction</a>
  11. <li><a href="#prereq">Pre-requisites</a>
  12. <ol>
  13. <li><a href="#req-all">Requirements for all setups</a>
  14. <li><a href="#req-main">Requirements for main setup</a>
  15. <li><a href="#req-web">Requirements for web setup</a>
  16. </ol>
  17. <li><a href="#install">Installation</a>
  18. <ol>
  19. <li><a href="#install-sw">Installing software</a>
  20. <li><a href="#setup-db">Setting up database</a>
  21. </ol>
  22. <li><a href="#config">Configuration</a>
  23. </ol>
  24. <a name=intro></a><h2>Introduction</h2>
  25. <p>There are essentially two kinds of setups for RRS:</p>
  26. <ul>
  27. <li>Main setup - this is the setup of the machine where the user
  28. database and accounts permanently reside. There is at a minimum, full
  29. use of <code>useradm</code> for both database and account
  30. administration.
  31. <li>Web setup - this is the machine used for hosting the clubs &amp;
  32. societies day system. Full use of the <code>rrs</code> cgi for database
  33. administration and limited use of useradm for database only
  34. administration.
  35. </ul>
  36. <p>Note that the web setup could also be used on the main setup, so that full use
  37. of <code>useradm</code> and the <code>rrs</code> cgi would be available.</p>
  38. <p>The installation requirements and steps below will indicate if they only
  39. pertain to one of the given setups ('main' or 'web') above, otherwise it can be
  40. assumed that they are required for both types of setup.</p>
  41. <p>It is also worth noting that much of RRS is very specific to the RedBrick
  42. and DCU environment and so as such is not designed for widespread use on
  43. generic machines. The web setup mentioned above however, is not as specific in
  44. its requirements and is intended to be reasonably 'portable'.</p>
  45. <a name=prereq></a><h2>Pre-requisites</h2>
  46. <a name=req-all></a><h3>Requirements for all setups</h3>
  47. <h4>Platform</h4>
  48. <p>RRS is designed primarily to run on a Unix platform however, it should be
  49. possible to run the web interface part on a non-Unix platform although this has
  50. not been tested. Note that root (superuser) access is required for performing
  51. any account or filesystem operations with <code>useradm</code>, everything else
  52. can be performed using a user / unprivileged account (assuming it has access to
  53. the user database).</p>
  54. <h4>PostgresSQL</h4>
  55. <p>PostgresSQL version 7.2 or higher must be installed. Details on doing this vary
  56. depending on the operating system and is outside the scope of this document
  57. however, full instructions can be found on the
  58. <a href="http://www.postgresql.org">PostgresSQL website</a>.</p>
  59. <h4>Python</h4>
  60. <p>Python version 2.2 or higher must be installed. Details on doing this vary
  61. depending on the operating system and is outside the scope of this document
  62. however, full instructions can be found on the
  63. <a href="http://www.python.org">Python website</a>.</p>
  64. <p>The following Python modules are included in the standard Python release,
  65. but may need to be installed or configured to work:</p>
  66. <ul>
  67. <li>readline - provides command line editing and completion
  68. functionality for useradm. Requires <a href="???">GNU readline</a> to
  69. be installed.
  70. </ul>
  71. <p>The following additional 3rd party Python modules must be installed:</p>
  72. <ul>
  73. <li><a href="http://www.druid.net/pygresql/">PyGresSQL</a> - Python
  74. interface to PostgresSQL database. Note that this is actually included
  75. in the PostgresSQL database release, however ensure that version 3.2 or
  76. later is installed.
  77. <li><a href="http://python-ldap.sourceforge.net/">Python-LDAP</a> - a
  78. Python interface to LDAP. Requires
  79. <a href="http://www.openldap.org">OpenLDAP</a> to be installed.
  80. Tested with Python-LDAP version 1.10alpha3 and OpenLDAP 1.2.13. This
  81. module is currently only used by
  82. <a href=rebuild_userdb_students.html>rebuild_userdb_student</a> and the
  83. <a href=rebuild_userdb_staff.html>rebuild_userdb_staff</a> scripts.
  84. </ul>
  85. <a name=req-main></a><h3>Requirements for main setup</h3>
  86. <h4>Account utilities</h4>
  87. <p>The account utilities <code>useradd</code>, <code>usermod</code> and
  88. <code>userdel</code> need to be installed. Typically, these are provided as
  89. part of the native operating system and have been found to have a consistent
  90. interface on Solaris, Linux and NetBSD.</p>
  91. <h4>Setquota</h4>
  92. <p>The 3rd party utility <code>setquota</code> must be installed for the
  93. manipulation of disk quotas. There appear to be a number of implementations of
  94. this command each with different command line syntax for different operating
  95. systems. Tested with a setquota utility for Solaris written by David Mitchell
  96. of Dept of Computer Science, Sheffield University.</p>
  97. <h4>Mailman</h4>
  98. <p>RRS automatically subscribes (and unsubscribes) users to a variety of
  99. RedBrick mailing lists, specifically the announce-redbrick,
  100. redbrick-newsletter, comittee, rb-admins and admin-discuss lists. For this
  101. reason the mailing list software <a href="http://www.list.org">Mailman</a>
  102. should be installed with the above mentioned lists created and working. It is
  103. not entirely necessary however as "dummy" scripts can be used in place of the
  104. <code>add_members</code> and <code>remove_members</code> mailman commands.</p>
  105. <h4>Mail Transfer Agent</h4>
  106. <p>Any MTA that provides the generic <code>sendmail</code> command line
  107. interface will suffice, e.g. Exim, Postfix, Sendmail, etc.</p>
  108. <a name=req-web></a><h3>Requirements for web setup</h3>
  109. <h4>Apache</h4>
  110. <p>A web server is required for the <code>rrs</code> cgi. Web servers other
  111. than Apache should work as the CGI standard is web server independant. Tested
  112. against Apache 1.3.26.</p>
  113. <a name=install></a><h2>Installation</h2>
  114. <a name=install-sw></a><h3>Installing software</h3>
  115. <p>The installation of RRS simply involves unpacking the
  116. <a href=rrs.tar.gz>RRS distribution tarball</a> in a filesystem location
  117. of your choosing. Say you have downloaded the tarball to
  118. <code>/tmp/rrs.tar.gz</code>. Installation to the directory
  119. <code>/usr/local/rrs</code> is as follows:</p>
  120. <pre># <b>cd /usr/local</b>
  121. # <b>tar zxf /tmp/rrs.tar.gz</b></pre>
  122. <a name=setup-db></a><h3>Setting up database</h3>
  123. <p>A database <code>userdb</code> needs to be created with the postgres command
  124. "<code>createdb userdb</code>" run as the postgres user. For the account setup,
  125. the root user will need access to the database. For the web setup, the user the
  126. web server runs as will need access to the database. This is achieved by first
  127. creating the users if they don't already exist with the postgres
  128. <code>createuser</code> command and making sure that postgres is setup to grant
  129. access to the <code>userdb</code> database for these users by appropriate
  130. editing of the <code>pg_hba.conf</code> and possibly <code>pg_ident.conf</code>
  131. files.</p>
  132. <h4>Creating database [main setup]</h4>
  133. <p>This step sets up a new database from scratch.</p>
  134. <p>Create the tables for the database:</p>
  135. <pre>main$ <b>cat userdb_reserved.sql userdb_staff.sql userdb_students.sql \
  136. userdb_usertypes.sql userdb_users.sql | psql userdb</b></pre>
  137. <p>Make sure that access to these tables is granted to all users who need it.
  138. The above scripts include full access for root and SELECT (read only) access
  139. for users <code>www</code> and <code>webgroup</code> as this is the default
  140. used on the RedBrick system.</p>
  141. <p>Then populate the student, staff and reserved tables by running each of the
  142. rebuild scripts, e.g:</p>
  143. <pre>main$ <b>./rebuild_userdb_reserved</b>
  144. userdb/reserved: Purge. Populate. Done [45]
  145. main$ <b>./rebuild_userdb_students</b>
  146. userdb/students: Search [19523]. Purge. Populate. Done [19436/19523].
  147. main$ <b>./rebuild_userdb_staff</b>
  148. userdb/staff: Search [1829]. Purge. Populate. Done [397/1829].</pre>
  149. <h4>Creating database [web setup]</h4>
  150. <p>If the web setup is on a seperate machine to the main system machine, the
  151. database must be copied across. This can be achieved as follows:</p>
  152. <pre>
  153. main$ <b>pg_dump -f userdb.dump userdb</b>
  154. <i>[copy file userdb.dump to the web machine]</i>
  155. web$ <b>psql userdb &lt; userdb.dump</b></pre>
  156. <p>You will need to grant full access to the users table to the user the web
  157. server runs as. The "<code>GRANT ALL ON users TO username</code>" SQL command
  158. achieves this when run as the owner of the userdb.</p>
  159. <p>An empty <code>rrs.log</code> file needs to be created before any actions
  160. can be performed with the web interface. This can be achieved by:</p>
  161. <pre><i>[create rrs.log in directory that rrs is installed]</i>
  162. web$ <b>touch rrs.log</b>
  163. <i>[make sure web server user can write to file]</i>
  164. web$ <b>chown www rrs.log</b></pre>
  165. <a name=config></a><h2>Configuration</h2>
  166. <p>Local configuration can be performed by editing the
  167. <a href=rbconfig.html>rbconfig.py</a> file. The majority of this configuration
  168. file is for providing local account and filesystem location paths to the
  169. <a href=rbaccount.html>rbaccount</a> module. The defaults provided are of
  170. course suited for the RedBrick system.</p>
  171. <p>At this point, all necessary installation and configuration should be
  172. complete for use of RRS.</p>
  173. <hr>
  174. $Id: install-manual.html,v 1.1 2003/03/28 16:33:07 cns Exp $
  175. </body>
  176. </html>