maintenance -> admin guide

Richard Jones · Richard Jones · commit 7d2395e1487b · 2004-02-11T00:41:33.000Z
diff --git a/doc/Makefile b/doc/Makefile
@@ -3,7 +3,7 @@ STXTOHTML = rst2html
 
 SOURCE = announcement.txt customizing.txt developers.txt FAQ.txt features.txt \
     glossary.txt implementation.txt index.txt design.txt mysql.txt \
-    installation.txt upgrading.txt user_guide.txt maintenance.txt \
+    installation.txt upgrading.txt user_guide.txt admin_guide.txt \
 	postgresql.txt
 
 COMPILED := $(SOURCE:.txt=.html)
diff --git a/doc/admin_guide.txt b/doc/admin_guide.txt
@@ -1,8 +1,8 @@
-============================
-Maintaining Roundup Trackers
-============================
+====================
+Administration Guide
+====================
 
-:Version: $Revision: 1.3 $
+:Version: $Revision: 1.1 $
 
 .. contents::
 
@@ -40,6 +40,42 @@ There's two "installations" that we talk about when using Roundup:
    config.py.
 
 
+Users and Security
+==================
+
+Roundup holds its own user database which primarily contains a username,
+password and email address for the user. Roundup *must* have its own user
+listing, in order to maintain internal consistency of its data. It is a
+relatively simple exercise to update this listing on a regular basis, or on
+demand, so that it matches an external listing (eg. unix passwd file, LDAP,
+etc.)
+
+Roundup identifies users in a number of ways:
+
+1. Through the web, users may be identified by either HTTP Basic
+   Authentication or cookie authentication. If you are running the web
+   server (roundup-server) through another HTTP server (eg. apache or IIS)
+   then that server may require HTTP Basic Authentication, and it will pass
+   the ``REMOTE_USER`` variable through to Roundup. If this variable is not
+   present, then Roundup defaults to using its own cookie-based login
+   mechanism.
+2. In email messages handled by roundup-mailgw, users are identified by the
+   From address in the message.
+
+In both cases, Roundup's behaviour when dealing with unknown users is
+controlled by Permissions defined in the "SECURITY SETTINGS" section of the
+tracker's ``dbinit.py`` module:
+
+Web Registration
+  If granted to the Anonymous Role, then anonymous users will be able to
+  register through the web.
+Email Registration
+  If granted to the Anonymous Role, then email messages from unknown users
+  will result in those users being registered with the tracker.
+
+More information about how to customise your tracker's security settings
+may be found in the `customisation documentation`_.
+
 Tasks
 =====
 
@@ -123,4 +159,5 @@ moved using the above steps) then you'll need to:
 Back to `Table of Contents`_
 
 .. _`Table of Contents`: index.html
+.. _`customisation documentation`: customizing.html
 
diff --git a/doc/customizing.txt b/doc/customizing.txt
@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.110 $
+:Version: $Revision: 1.111 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -22,7 +22,7 @@ Customisation of Roundup can take one of six forms:
 2. database, or `tracker schema`_ changes
 3. "definition" class `database content`_ changes
 4. behavioural changes, through detectors_
-5. `access controls`_
+5. `security / access controls`_
 6. change the `web interface`_
 
 The third case is special because it takes two distinctly different forms
@@ -592,8 +592,8 @@ See "`adding a new field to the classic schema`_" for an example that
 requires database content changes.
 
 
-Access Controls
-===============
+Security / Access Controls
+==========================
 
 A set of Permissions is built into the security module by default:
 
diff --git a/doc/index.txt b/doc/index.txt
@@ -10,7 +10,7 @@ Contents
 - `Frequently Asked Questions`_
 - `User Guide`_
 - Configuring and `Customising Roundup`_
-- `Maintaining Roundup Trackers`_
+- `Administering Roundup Trackers`_
 - `Roundup's Design`_ (original_)
 - `Developing Roundup`_ 
 - Contact_
@@ -112,7 +112,7 @@ See COPYING.txt in the software distribution for the licensing terms.
 .. _`Frequently Asked Questions`: FAQ.html
 .. _`User Guide`: user_guide.html
 .. _`Customising Roundup`: customizing.html
-.. _`Maintaining Roundup Trackers`: maintenance.html
+.. _`Administering Roundup Trackers`: admin_guide.html
 .. _`Roundup's Design`: design.html
 .. _`Developing Roundup`: developers.html
 .. _original: spec.html
diff --git a/doc/installation.txt b/doc/installation.txt
@@ -2,7 +2,7 @@
 Installing Roundup
 ==================
 
-:Version: $Revision: 1.67 $
+:Version: $Revision: 1.68 $
 
 .. contents::
 
@@ -97,8 +97,8 @@ installation:
    UNIX machine and want to restrict local access to roundup
 6. `additional language codecs`_
 
-For information about how Roundup installs, see the `maintenance
-documentation`_.
+For information about how Roundup installs, see the `administration
+guide`_.
 
 
 Basic Installation Steps
@@ -263,7 +263,7 @@ database.
 
 You may set your tracker up with the anydbm backend (which is guaranteed to be
 available) and switch to one of the other backends at any time using the
-instructions in the `maintenance documentation`_.
+instructions in the `administration guide`_.
 
 
 Configure a Web Interface
@@ -446,7 +446,7 @@ http://cjkpython.berlios.de/
 Maintenance
 ===========
 
-Read the separate `maintenance documentation`_ for information about how to
+Read the separate `administration guide`_ for information about how to
 perform common maintenance tasks with Roundup.
 
 
@@ -580,7 +580,7 @@ Next: `User Guide`_
 .. _`customisation documentation`: customizing.html
 .. _`customising roundup`: customizing.html
 .. _`upgrading document`: upgrading.html
-.. _`maintenance documentation`: maintenance.html
+.. _`administration guide`: admin_guide.html
 .. _sqlite: http://www.hwaci.com/sw/sqlite/
 .. _metakit: http://www.equi4.com/metakit/
 
diff --git a/doc/security.txt b/doc/security.txt
diff --git a/doc/upgrading.txt b/doc/upgrading.txt
@@ -3,7 +3,8 @@ Upgrading to newer versions of Roundup
 ======================================
 
 Please read each section carefully and edit your tracker home files
-accordingly.
+accordingly. Note that there is informaiton about upgrade procedures in the
+`administration guide`_.
 
 .. contents::
 
@@ -13,13 +14,9 @@ Migrating from 0.6 to 0.7
 0.7.0 Getting the current user id
 ---------------------------------
 
-Removed Database.curuserid attribute. Any code referencing this attribute should
-be replaced with a call to Database.getuid().
+Removed Database.curuserid attribute. Any code referencing this attribute
+should be replaced with a call to Database.getuid().
 
-0.7 creates indexes when using RDBMS backends. The yet-to-be-written
-'refreshdb' roundup-admin command will create most indexes, but you 
-might still need to create an index "create index ids_name_idx on 
-ids(name)".
 
 0.7.0 ZRoundup changes
 ----------------------
@@ -922,3 +919,4 @@ copy.
 
 .. _`customisation documentation`: customizing.html
 .. _`security documentation`: security.html
+.. _`administration guide`: admin.html
