From: richard Date: Wed, 11 Feb 2004 00:41:33 +0000 (+0000) Subject: maintenance -> admin guide X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=bf396e0654d7b5886e0734860f3966a30f3278cc;p=roundup.git 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 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/admin_guide.txt b/doc/admin_guide.txt new file mode 100644 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 + \scripts\... + Core code + \lib\site-packages\roundup\... + Support files + \share\roundup\... + + and on *nix (eg. Linux): + + Scripts + /bin/... + Core code + /lib-/site-packages/roundup/... + Support files + /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 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/maintenance.txt b/doc/maintenance.txt deleted file mode 100644 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 - \scripts\... - Core code - \lib\site-packages\roundup\... - Support files - \share\roundup\... - - and on *nix (eg. Linux): - - Scripts - /bin/... - Core code - /lib-/site-packages/roundup/... - Support files - /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 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