Go to the first, previous, next, last section, table of contents.


Configuration

gnats2w can be configured basically by setting the variables in the `config.py' file. This defines basic installation directories, e-mails, URLs, GNATS database, some Web forms element appearance, etc. User specific customization can be achieved through environment variables, which can be set by the Web server with respect to an URL, from which a CGI script was invoked.

Special care is applied to access rights. gnats2w allows you to define fine control about who can access the bug database and who can modify it, allowing any authentization method you can use in Python.

Finally, gnats2w has FCGI support to reduce overhead caused by Python startup times. With a bit of configuration, you can avoid this overhead.

Basic configuration

The main configuration place is the file `config.py'. It consists mainly of configuration variables, which you should set according to your local installation and your local requirements. Primarily URLs and paths are set here.

The file contains configuration variables and their values separated by the `=' operator. This is standard Python module file but do not worry if you do not know Python. All special you need to know is that strings are enclosed in apostrophes or double quotes and that None is something like nil in Lisp or NULL in C.

Installation specific configuration

You must set all the variables here to values specific to your site and gnats2w installation.

Directory paths:

GNATS_PRG_DIR
The directory, where all the GNATS internal programs and scripts sit.
TEMPLATE_DIR
The directory containing DTML templates.
DICTIONARY_DIR
The directory containing language dictionaries.

URLs:

HOST_URL
Host URL, including protocol and port number (if needed).
BASE_URL
Base URL for static HTML documents, it must be a full pointer to `index.html'. This should be HOST_URL and the `index.html' paths.

Mailing:

MAIL
Command to send an e-mail given on the standard input.
ADMIN_MAIL
E-mail address of the gnats2w administrator.

Database specific configuration

The following configuration variables specify your database setup.

GNATS_DIR
The default database directory.
SITE
Site to submit bugs to, as defined by `GNATS_SITE', See section `config file' in The GNATS manual.
DEFAULT_CATEGORY
The category, which is offered as the default one in the Web bug submitting form.
AUTO_CONFIDENTIAL
This is boolean flag denoting confidentiality handling. If it is 0, there is nothing special about confidentiality. If it is 1, new reports can be set confidential, See section `Problem Report fields' in The GNATS manual, automatically for some categories. Such auto-confidential categories are denoted by the * character at the very beginning of their category description in the `categories' file, the second field, See section `categories file' in The GNATS manual. (1)

Language configuration

One important thing in bug hunting is to allow users accessing a bug tracking system in their own language. gnats2w has some support for message translations. (2) gnats2w consideres language codes given by the Web browser to it and selects appropriate available message catalog and HTML templates.

The default language is English. If you want to support another language, you need translated `*.dtml' files and a message catalog. Translated `*.dtml' files have an additional extension, which is the ISO language code, e.g. Czech document templates have the extension `*.dtml.cs'. Message catalogs have names equal to the language code and are placed in the directory defined by the variable DICTIONARY_DIR, See section Installation specific configuration. Additionally, you can have your own catalogs in the directory defined by the variable DICTIONARY_DIR_LOCAL (see below) for new messages appearing in your own extension code.

The format of message catalog files is as follows:

dictionary = {
  'English message 1': 'translation 1',
  'English message 2': 'translation 2',
  'English message 3': 'translation 3',
  ...
  'English message N': 'translation N'
}

I.e. it contains Python variable dictionary, which is an associative array with English messages as keys and their translations as values.

The following configuration variables has some relation to the translations:

LANGUAGE
Default language code. If you do not want to specify some local language, just set it to the empty string (").
DICTIONARY_DIR_LOCAL
The directory containing your local message catalogs.

Web interface configuration

The main index page has a part left for local text. For example, you can put links to various category selections here, See section Environment variables.

If the variable LOCAL_INDEX_FUNCTION is None, the local part is left empty. Otherwise LOCAL_INDEX_FUNCTION should be set to a Python function generating an HTML 3.2 code, which will be put to the local part of the main index page. The function takes no arguments, but can access global objects, See section Internals.

There are also some visibility flags, which allow you to hide some information not interesting to your users. All the following variables can have the value 0 (not visible) or 1 (visible):

DISPLAY_CONFIDENTIAL
Whether confidential button and status should be displayed in forms.
DISPLAY_ORGANIZATION
Whether organization name should be displayed in forms.
DISPLAY_IDREQUEST
Whether request for registration link should be displayed on the main index page.

Varying configurations

If the directory with CGI scripts contains a file named `config', all settings in this file take precedence over the ones in `config.py'. This way you can have different configurations for different URLs -- just make symbolink links to all the CGI scripts in another directory and override the options with `config' file in the new directory.

One obvious application of this feature is to allow access to different GNATS databases through different URLs by setting the variable GNATS_DIR, See section Database specific configuration, in different `config' files.

Environment variables

Not everything can be set in a static configuration file. For example, user preferences are difficult to store there. To make such problems easier, gnats2w can be customized also by environment variables. Then you can with enough powerful Web servers (like Apache) customize gnats2w e.g. through URL paths to gnats2w scripts. For example, Apache rewrite rules allow you to set the environment variables based on URL, while rewriting the URL into some canonical form.

There are considered two such environment variables:

GNATS_EXPERT_MODE
By default, gnats2w marks links to help with three question marks and has some verbose explanations in forms. This is because many users can overlook help links consisting of only single question mark and also need more assistance than one would expect. However these extra helps have bad influence on page arrangement and can make the orientation in them less easy. If you set this variable to the value 'on', the helps are reduced.
GNATS_CATEGORIZE
If you want to make "thematic" category sets (e.g. on sites with a lot of categories), you achieve this by grouping categories by some common prefixes and setting this variable to one of the prefixes. Then only categories with this prefix are offered in category lists and only those can be accessed by a user (it can be used thus for simple access regulation, for more sophisticated access regulation see section Access rights). If GNATS_CATEGORIZE is an empty string ("), all accessible categories are visible.

Access rights

@FIXME{}

By default, gnats2w allows access everyone to everything. This is often not what you would like to have. So gnats2w is equipped with some support for access regulation and authentization. The authorization and authentization basic gnats2w principles are described below.

The module `access.py' defines some basic Python classes, of which you can compose your own access customization classes. If you want to change the default behavior, create new access class and assign it to the configuration variable ACCESS, See section Basic configuration.

Access classification

Access rights are divided into three categories:

Submit
The right to submit new problem reports.
View
Viewing search results and individual problem reports.
Edit
Editing problem reports.

For each of this category, the basic rights can be:

Access denied
No access allowed.
Restricted access
Access to non-confidential problem reports only.
Access granted
Full access to the problem.

The abstract class Access defines appropriate constants for all these categories: Access.SUBMIT, Access.VIEW, Access.EDIT, Access.DENIED, Access.RESTRICTED, Access.FULL.

Authentization

Identification of the accessor is composed from the three parts:

Identity
Key name as used in the `responsible', See section `responsible file' in The GNATS manual, and `submitter', See section `submitters file' in The GNATS manual, files.
Name
Real human name.
Email
E-mail address.

The following authentization classes are predefined:

Email_Identity
This class gets user's identity from his e-mail address. Note this authentization method is totally unsafe and can be abused easily.
HTTPS
This class gets user's identity from his SSL certificate. This authentization method is safe, but only if your Web server is configured in such a way, that it allows access only with a valid certificate signed by a trusted certification authority.

Access definition

You can assign whatever subclass of the Access class you define. One useful predefined subclass of the Access class is Enumeration. The following text describes its usage.

Access is defined by a dictionary with keys as users' identities and values defining access for a user with a given identity. If the dictionary contains an item with an empty string as a key, it defines default access. If there is no such an item, access is denied for accessors not presented in the dictionary.

Values are sequences of triples (ACCESS, RESTRICTED_ALLOWED, SPECIAL), where the items mean:

ACCESS
One of the Access class constants SUBMIT, VIEW, or EDIT.
RESTRICTED_ALLOWED
Iff true, access to restricted problems is allowed.
SPECIAL
One of the Enumerated class constants RESPONSIBLE (allow access only for the responsible), ORIGINATOR (allow access only for the originator), RELATED (allow access only for the responsible or the originator); or None (allow access for all).

For a given key, several triples can be defined in its value sequence, with the same of different elements. The most liberal triple for a particular kind of access is considered.

The dictionary described above is simply given as the only argument of the Enumeration constructor. The Enumeration instance is assigned to the ACCESS configuration variable.

Access definition examples

The simplest thing you can do is to allow access anyone to everything:

from gnats2w.access import Access
ACCESS = Access ()

Let us look at more complicated example:

from gnats2w.access import Enumeration
MY_ACCESS = {'administrator': ((Access.SUBMIT, 1, None),
                               (Access.EDIT, 1, None),
                               (Access.VIEW, 1, None)),
             'certificate': ((Access.SUBMIT, 1, None),
                             (Access.EDIT, 1, Access.RELATED),
                             (Access.VIEW, 1, None)),
             '': ((Access.SUBMIT, 0, None),
                  (Access.EDIT, 0, Access.RELATED),
                  (Access.VIEW, 0, None))}
ACCESS = Enumeration (MY_ACCESS)

This configuration has the following features:

To let it work reasonably, there has to be defined mapping on the user identifications certificate and administrator. This can be achieved e.g. in the following way:

from gnats2w import access

class My_Enumeration (Enumeration, access.HTTPS):

    def identity (self):
        name = self.name ()
        if name == 'John Powerful':
            return 'administrator'
        elif name:
            return 'certificate'
        else:
            return ''

ACCESS = My_Enumeration (MY_ACCESS)

FastCGI

To avoid slow Python startups of CGI scripts, gnats2w provides an interface to FastCGI. To use gnats2w with FastCGI, you need have installed the module `fcgi.py'. You can find it at http://www.fastcgi.com.

After this, setup your Web server appropriately to get FastCGI support and you can run gnats2w through the `fcgiscripts.py' module and symbolic links made to it.


Go to the first, previous, next, last section, table of contents.