maintenance -> admin guide

git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@2071 57a73879-2fb5-44c3-a270-3262357dd7e2

diff --git a/doc/Makefile b/doc/Makefile
index b059b71a512a5a5b8bde023c7b8067692ecd5b2d..449d0890603f2b3ff16e9f0422c2a8903fd7e859 100644 (file)
--- 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
new file mode 100644 (file)
index 0000000..a48678a
--- /dev/null
+++ b/doc/admin_guide.txt
@@ -0,0 +1,163 @@
+====================
+Administration Guide
+====================
+
+:Version: $Revision: 1.1 $
+
+.. contents::
+
+What does Roundup install?
+==========================
+
+There's two "installations" that we talk about when using Roundup:
+
+1. The installation of the software and its support files. This uses the
+   standard Python mechanism called "distutils" and thus Roundup's core code,
+   executable scripts and support data files are installed in Python's
+   directories. On Windows, this is typically:
+
+   Scripts
+     <python dir>\scripts\...
+   Core code
+     <python dir>\lib\site-packages\roundup\...
+   Support files
+     <python dir>\share\roundup\...
+
+   and on *nix (eg. Linux):
+
+   Scripts
+     <python root>/bin/...
+   Core code
+     <python root>/lib-<python version>/site-packages/roundup/...
+   Support files
+     <python root>/share/roundup/...
+
+2. The installation of a specific tracker. When invoking the roundup-admin
+   "inst" (and "init") commands, you're creating a new Roundup tracker. This
+   installs configuration files, HTML templates, detector code and a new
+   database. You have complete control over where this stuff goes through
+   both choosing your "tracker home" and the DATABASE variable in
+   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
+=====
+
+Maintenance of Roundup can involve one of the following:
+
+1. `tracker backup`_ 
+2. `software upgrade`_
+3. `migrating backends`_
+3. `moving a tracker`_
+
+
+Tracker Backup
+--------------
+
+Stop the web and email frontends and to copy the contents of the tracker home
+directory to some other place using standard backup tools.
+
+
+Software Upgrade
+----------------
+
+Always make a backup of your tracker before upgrading software. Steps you may
+take:
+
+1. ensure that the unit tests run on your system
+2. copy your tracker home to a new directory
+3. follow the steps in the upgrading documentation for the new version of
+   the software
+4. test each of the admin tool, web interface and mail gateway using the new
+   version of the software
+5. stop the production web and email frontends
+6. perform the upgrade steps on the existing tracker directory
+7. upgrade the software
+8. restart your tracker
+
+
+Migrating Backends
+------------------
+
+1. stop the existing tracker web and email frontends (preventing changes)
+2. use the roundup-admin tool "export" command to export the contents of
+   your tracker to disk
+3. copy the tracker home to a new directory
+4. change the backend used in the tracker home ``select_db.py`` file
+5. delete the "db" directory from the new directory
+6. use the roundup-admin "import" command to import the previous export with
+   the new tracker home
+7. test each of the admin tool, web interface and mail gateway using the new
+   backend
+8. move the old tracker home out of the way (rename to "tracker.old") and 
+   move the new tracker home into its place
+9. restart web and email frontends
+
+
+Moving a Tracker
+----------------
+
+If you're moving the tracker to a similar machine, you should:
+
+1. install Roundup on the new machine and test that it works there,
+2. stop the existing tracker web and email frontends (preventing changes),
+3. copy the tracker home directory over to the new machine, and
+4. start the tracker web and email frontends on the new machine.
+
+Most of the backends are actually portable across platforms (ie. from Unix to
+Windows to Mac). If this isn't the case (ie. the tracker doesn't work when
+moved using the above steps) then you'll need to:
+
+1. install Roundup on the new machine and test that it works there,
+2. stop the existing tracker web and email frontends (preventing changes),
+3. use the roundup-admin tool "export" command to export the contents of
+   the existing tracker,
+4. copy the export to the new machine,
+5. use the roundup-admin "import" command to import the tracker on the new
+   machine, and
+6. start the tracker web and email frontends on the new machine.
+
+
+-------------------
+
+Back to `Table of Contents`_
+
+.. _`Table of Contents`: index.html
+.. _`customisation documentation`: customizing.html
+

diff --git a/doc/customizing.txt b/doc/customizing.txt
index 6568c6a9c3de0b54ab265c4c19ddf967b384f611..827c3f76525051acb7742c6e198956326edeaf11 100644 (file)
--- 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
index 3b1cdf64d1c03f8e4c1e8d57eb2065f571a3e2f6..b6bc191ba379a09d7474ee8923731f3c24b131b8 100644 (file)
--- 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
index 7c0741c060b920d608386e5d5da6cf74283f1f53..4f3e4fab1916795f9ae4f64919e9c6582ad94c89 100644 (file)
--- 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/maintenance.txt b/doc/maintenance.txt
deleted file mode 100644 (file)
index e761190..0000000
--- a/doc/maintenance.txt
+++ /dev/null
@@ -1,126 +0,0 @@
-============================
-Maintaining Roundup Trackers
-============================
-
-:Version: $Revision: 1.3 $
-
-.. contents::
-
-What does Roundup install?
-==========================
-
-There's two "installations" that we talk about when using Roundup:
-
-1. The installation of the software and its support files. This uses the
-   standard Python mechanism called "distutils" and thus Roundup's core code,
-   executable scripts and support data files are installed in Python's
-   directories. On Windows, this is typically:
-
-   Scripts
-     <python dir>\scripts\...
-   Core code
-     <python dir>\lib\site-packages\roundup\...
-   Support files
-     <python dir>\share\roundup\...
-
-   and on *nix (eg. Linux):
-
-   Scripts
-     <python root>/bin/...
-   Core code
-     <python root>/lib-<python version>/site-packages/roundup/...
-   Support files
-     <python root>/share/roundup/...
-
-2. The installation of a specific tracker. When invoking the roundup-admin
-   "inst" (and "init") commands, you're creating a new Roundup tracker. This
-   installs configuration files, HTML templates, detector code and a new
-   database. You have complete control over where this stuff goes through
-   both choosing your "tracker home" and the DATABASE variable in
-   config.py.
-
-
-Tasks
-=====
-
-Maintenance of Roundup can involve one of the following:
-
-1. `tracker backup`_ 
-2. `software upgrade`_
-3. `migrating backends`_
-3. `moving a tracker`_
-
-
-Tracker Backup
---------------
-
-Stop the web and email frontends and to copy the contents of the tracker home
-directory to some other place using standard backup tools.
-
-
-Software Upgrade
-----------------
-
-Always make a backup of your tracker before upgrading software. Steps you may
-take:
-
-1. ensure that the unit tests run on your system
-2. copy your tracker home to a new directory
-3. follow the steps in the upgrading documentation for the new version of
-   the software
-4. test each of the admin tool, web interface and mail gateway using the new
-   version of the software
-5. stop the production web and email frontends
-6. perform the upgrade steps on the existing tracker directory
-7. upgrade the software
-8. restart your tracker
-
-
-Migrating Backends
-------------------
-
-1. stop the existing tracker web and email frontends (preventing changes)
-2. use the roundup-admin tool "export" command to export the contents of
-   your tracker to disk
-3. copy the tracker home to a new directory
-4. change the backend used in the tracker home ``select_db.py`` file
-5. delete the "db" directory from the new directory
-6. use the roundup-admin "import" command to import the previous export with
-   the new tracker home
-7. test each of the admin tool, web interface and mail gateway using the new
-   backend
-8. move the old tracker home out of the way (rename to "tracker.old") and 
-   move the new tracker home into its place
-9. restart web and email frontends
-
-
-Moving a Tracker
-----------------
-
-If you're moving the tracker to a similar machine, you should:
-
-1. install Roundup on the new machine and test that it works there,
-2. stop the existing tracker web and email frontends (preventing changes),
-3. copy the tracker home directory over to the new machine, and
-4. start the tracker web and email frontends on the new machine.
-
-Most of the backends are actually portable across platforms (ie. from Unix to
-Windows to Mac). If this isn't the case (ie. the tracker doesn't work when
-moved using the above steps) then you'll need to:
-
-1. install Roundup on the new machine and test that it works there,
-2. stop the existing tracker web and email frontends (preventing changes),
-3. use the roundup-admin tool "export" command to export the contents of
-   the existing tracker,
-4. copy the export to the new machine,
-5. use the roundup-admin "import" command to import the tracker on the new
-   machine, and
-6. start the tracker web and email frontends on the new machine.
-
-
--------------------
-
-Back to `Table of Contents`_
-
-.. _`Table of Contents`: index.html
-

diff --git a/doc/security.txt b/doc/security.txt
deleted file mode 100644 (file)
index 10dedba..0000000
--- a/doc/security.txt
+++ /dev/null
@@ -1,159 +0,0 @@
-===================
-Security Mechanisms
-===================
-
-:Version: $Revision: 1.16 $
-
-Current situation
-=================
-
-Current logical controls:
-
-ANONYMOUS_ACCESS = 'deny'
- Deny or allow anonymous access to the web interface
-ANONYMOUS_REGISTER = 'deny'
- Deny or allow anonymous users to register through the web interface
-ANONYMOUS_REGISTER_MAIL = 'deny'
- Deny or allow anonymous users to register through the mail interface
-
-Current user interface authentication and controls:
-
-- command-line tool access controlled with passwords, but no logical controls
-- CGI access is by username and password and has some logical controls
-- mailgw access is through identification using sender email address, with
-  limited functionality available
-
-The web interface implements has specific logical controls,
-preventing non-admin users from accessing:
-
- - other user's details pages
- - listing the base classes (not issues or their user page)
- - editing base classes
-
-Issues
-======
-
-1. The current implementation is ad-hoc, and not complete for all `use cases`_.
-2. Currently it is not possible to allow submission of issues through email
-   but restrict those users from accessing the web interface.
-3. Only one user may perform admin functions.
-4. There is no verification of users in the mail gateway by any means other
-   than the From address. Support for strong identification through digital
-   signatures should be added.
-5. The command-line tool has no logical controls.
-6. The anonymous control needs revising - there should only be one way to be
-   an anonymous user, not two (currently there is user==None and
-   user=='anonymous').
-
-
-Possible approaches
-===================
-
-Security controls in Roundup could be approached in three ways:
-
-1) at the hyperdb level, with read/write/modify permissions on classes, items
-   and item properties for all or specific transitions.
-2) at the user interface level, with access permissions on CGI interface
-   methods, mailgw methods, roundup-admin methods, and so on.
-3) at a logical permission level, checked as needed.
-
-In all cases, the security built into roundup assumes restricted access to the
-hyperdatabase itself, through Operating System controls such as user or group
-permissions.
-
-
-Hyperdb-level control
----------------------
-
-Control is implemented at the Class.get, Class.set and Class.create level. All
-other methods must access items through these methods. Since all accesses go
-through the database, we can implement deny by default.
-
-Pros:
-
-   - easier to implement as it only affects one module
-   - smaller number of permissions to worry about
-
-Cons:
-
-   - harder to determine the relationship between user interaction and hyperdb
-     permission.
-   - a lot of work to define
-   - must special-case to handle by-item permissions (editing user details,
-     having private messages)
-
-
-User-interface control
-----------------------
-
-The user interfaces would have an extra layer between that which
-parses the request to determine action and the action method. This layer
-controls access. Since it is possible to require methods be registered
-with the security mechanisms to be accessed by the user, deny by default
-is possible.
-
-Pros:
-
-   - much more obvious at the user level what the controls are
-
-Cons:
-
-   - much more work to implement
-   - most user interfaces have multiple uses which can't be covered by a
-     single permission
-
-Logical control
----------------
-
-At each point that requires an action to be performed, the security mechanisms
-are asked if the current user has permission. Since code must call the
-check function to raise a denial, there is no possibility to have automatic
-default of deny in this situation.
-
-Pros:
-
-   - quite obvious what is going on
-   - is very similar to the current system
-
-Cons:
-
-   - large number of possible permissions that may be defined, possibly
-     mirroring actual user interface controls.
-   - access to the hyperdb must be strictly controlled through program code
-     that implements the logical controls.
-
-
-Action
-======
-
-The CGI interface must be changed to:
-
-- authenticate over a secure connection
-- use unique tokens as a result of authentication, rather than pass the user's
-  real credentials (username/password) around for each request (this means
-  sessions and hence a session database)
-- use the new logical control mechanisms
-
-  - implement the permission module
-  - implement a Role editing interface for users
-  - implement htmltemplate tests on permissions
-  - switch all code over from using config vars for permission checks to using
-    permissions
-  - change all explicit admin user checks for Role checks
-  - include config vars for initial Roles for anonymous web, new web and new
-    email users
-
-The mail gateway must be changed to:
-
-- use digital signatures
-- use the new logical control mechanisms
-
-  - switch all code over from using config vars for permission checks to using
-    permissions
-
-The command-line tool must be changed to:
-
-- use the new logical control mechanisms (only allowing write
-  access by admin users, and read-only by everyone else)
-
-

diff --git a/doc/upgrading.txt b/doc/upgrading.txt
index bc1c9700673068bebdd93cab34c4d1a5d65cccc5..31b30ca2d1e120cf017c12708fe58c9d5a75cfd9 100644 (file)
--- 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