From bf396e0654d7b5886e0734860f3966a30f3278cc Mon Sep 17 00:00:00 2001 From: richard Date: Wed, 11 Feb 2004 00:41:33 +0000 Subject: [PATCH] maintenance -> admin guide git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@2071 57a73879-2fb5-44c3-a270-3262357dd7e2 --- doc/Makefile | 2 +- doc/{maintenance.txt => admin_guide.txt} | 45 ++++++- doc/customizing.txt | 8 +- doc/index.txt | 4 +- doc/installation.txt | 12 +- doc/security.txt | 159 ----------------------- doc/upgrading.txt | 12 +- 7 files changed, 59 insertions(+), 183 deletions(-) rename doc/{maintenance.txt => admin_guide.txt} (68%) delete mode 100644 doc/security.txt diff --git a/doc/Makefile b/doc/Makefile index b059b71..449d089 100644 --- 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/maintenance.txt b/doc/admin_guide.txt similarity index 68% rename from doc/maintenance.txt rename to doc/admin_guide.txt index e761190..a48678a 100644 --- a/doc/maintenance.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 index 6568c6a..827c3f7 100644 --- 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 3b1cdf6..b6bc191 100644 --- 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 7c0741c..4f3e4fa 100644 --- 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 deleted file mode 100644 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 bc1c970..31b30ca 100644 --- 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 -- 2.30.2