Gnatsweb
                        Web interface to GNATS
               The GNU Problem Report Management System

                        Customizing Gnatsweb 4


Gnatsweb configuration variables
================================

Gnatsweb ships with a sensible default setup.  Nevertheless, many
sites will wish to modify cosmetics such as background color, shape
and size of fonts, and some sites may wish to change the way Gnatsweb
handles logins and cookies.  These characteristics and more are easily
modified by redefining the values of certain variables used in the
gnatsweb.pl script.

The different configuration variables are treated in detail below.  In
order to override the default value of a variable, set its value in
the gnatsweb-site.pl file which was installed together with
gnatsweb.pl in the cgi-bin directory of your web server.  This file
already contains two settings, one for the name of the GNATS host and
one for the port number on which the GNATS server is running.  You may
already have modified these values as part of the initial installation
of Gnatsweb.  We strongly suggest that you use this approach, and that
you do not modify the gnatsweb.pl file directly, since that will make
future upgrades much more difficult.

The following variables may be used to modify the look and behaviour
of Gnatsweb. The default values are also listed and explained:

$site_gnats_host = 'localhost';
$site_gnats_port = 1529;
These define the host name of the GNATS server and the TCP port the
server listens on.  The default values are for a GNATS server which
runs on the same host as the web server and which uses the default
GNATS port number.  This port number may have been modified during
initial installation of GNATS.


$site_gnatsweb_server_auth = 0;
When set to '1', this variable specifies that the web server itself
handles access authentication to Gnatsweb.  In order to set up a more
secure installation of Gnatsweb, you can have the web server do the
authentication against an htpasswd file, an LDAP server or some other
system supported by the web server.  Combining this with a secure
connection over SSL provides a reasonably high-security interface to
GNATS.

Once the user is authenticated in this fashion, the Gnatsweb
script will use the username supplied from the web server.  For this
to work, GNATS needs to be set up to grant edit access to the web
server.  For more information on what this entails, see the Gnatsweb
INSTALL file and Appendix C, `Controlling access to databases' of the
GNATS 4 manual.


$site_no_gnats_passwords = 0;
The GNATS network mode is quite cavalier about passwords, so some
sites may elect not to use GNATS passwords and instead let users
identify themselves by simply supplying a username.  In such
environments, there is little point in Gnatsweb asking for passwords,
and if this variable is set Gnatsweb will not prompt for a password on
the login page.

This essentially means that anyone can pretend to be anyone, but since
the GNATS command line tools are hardly more secure, this is
relatively unimportant at sites that use these tools.


$no_create_without_access = '';
This variable defines the minimum access level a user must have in
order to have access to the Create PR function in Gnatsweb.  Since
GNATS by default allows anyone to submit PRs this is only likely to be
meaningful at sites where Gnatsweb is the only interface to GNATS.

When this variable is set to an empty value, anyone is allowed access
to the Create function.  If this feature is to be used, a typical
value would be 'edit'.  See the GNATS gnatsd.access files and Appendix
C, `Controlling access to databases' of the GNATS 4 manual for details
on the meaning of the different access levels.


$site_mail_domain = '@yourdomain.here';
This sets the default mail domain for the Responsible field
-- if this field contains a bare user-id, the value of this variable
will be tagged on at the end to generate a clickable mailto link on
the View PR screen.  The value must begin with an '@' sign.


%site_pr_submission_address = ();
This hash should contain the e-mail addresses that your site uses for
submission of PRs.  If it is defined for a given database, the Edit
and View pages will include a mailto link marked "submit a followup by
email" pointing to the defined address for this database and to the
address contained in the Reply-To field of the PR.

The format for this hash is
site_pr_submission_address = ('database'  => 'address');

For example, if you have one database named `default' with submission
address 'support@example.com' and one named `helpdesk' with submission
address 'helpdesk@example.com', you could define the hash as follows:
%site_pr_submission_address = ('default'  => 'support@example.com',
                               'helpdesk' => 'helpdesk@example.com');


$site_post_max = 1024 * 1024;
The maximum size posting which Gnatsweb will accept (in bytes).  It is
conceivable that someone with malicious intent might try to jam your
server by for instance posting an enormous attachment.  This variable
limits the size of such postings.  The default value of 1 megabyte
should be fairly sensible, but sites may want to implement different
policies here.


$description_in_view = 0;
When set to '1', field descriptions will be shown on the View PR page.
This tends to look messy, so by default descriptions are only shown on
the Edit and Create PR pages.


$help_page_path = './gnatsweb.html';
The path to the Gnatsweb help page.  This is the file that will be
returned when the user clicks on the Help button.  The path is
relative to the directory where gnatsweb.pl is located.


$site_banner_text = 'GNU Gnatsweb';
$site_banner_background = '#000000';
$site_banner_foreground = '#ffffff';
$site_button_background = '#000000';
$site_button_foreground = '#ffffff';
These variables control the name that will be shown in the banner on
top of each page in addition to the database name, and the foreground
and background colors of the banner and the associated button bar.


$site_stylesheet = undef;
When this variable is set to point to a CSS stylesheet, all Gnatsweb
pages are linked to this stylesheet.  You can either specify an
absolute URL like 'http://gnats.example.com/stylesheet.css' or a URL
relative to the document root of your web server.


$include_audit_trail = 1;
When set to 1, the Audit-Trail will be visible by default in the View
PR screen.  Sites that expect large Audit-Trails, i.e. lot of mail
back and forth etc., will want to set this to 0.


$popup_menu_becomes_obnoxious = 20;
When a list contains many items, it is better to use a scrolling list
rather than a popup menu.  This variable specifies when a popup menu
should be considered too large.


$scrolling_menu_default_size = 3;
Specifies the default size for scrolling list fields.  This variable
is overridden for some fields.


$site_background = undef; 
The default background color for all Gnatsweb pages.  If no value is
given, Gnatsweb leaves it up to the browser to decide which background
color to use.


$site_required_field_color = '#ff0000';
Color to use for marking the names of required fields on the Create PR
page.  Default is pure red.


%mark_urls = (
         'urls'       => 1,
         'emails'     => 1,
         'prs'        => 1,
         'max_length' => 1024*100,
        );
Hash which controls the mark_urls routine, which "htmlifies" PRs for
view_pr. mark_urls adds a lot of usability, but can be slow for huge
(100K+) fields.
- urls = make links clickable
- emails = make addresses mailto: links
- prs = make PR numbers links to gnatsweb
- max_length = strings larger than this will not be processed


$use_temp_db_prefs_cookie = 0;
Controls whether a temporary cookie will be used for login
information.  Gnatsweb stores login information in the db_prefs
cookie, and with this variable set to '0' a persistent cookie is
stored on disk, something which is undesirable on machines where
several users use the same browser.  With the variable set to 1, the
cookie is stored only in the browser itself, causing the cookie to be
deleted when the user exits the browser.


$global_cookie_path = '/';
Specifies what to use as path argument in cookies.  Modifying this
variable should not be necessary.


$global_cookie_expires = '+30d';
For installations that use persistent db_prefs cookies (see above),
this variable controls when the cookies expire.  The default is 30
days.


$textwidth = 60;
Controls the width of text fields in forms.


$site_allow_remote_debug = 1;
If this is set to '1', setting the 'debug' param in request URLs to
Gnatsweb will display communications between gnatsd and Gnatsweb in
the browser.  This is really only useful to GNATS administrators for
debugging Gnatsweb or GNATS installation.

To debug, you would use a URL similar to the following:
http://gnats.example.com/cgi-bin/gnatsweb.pl?debug=option
where option is either 'cmd', 'reply' or 'all'.


$attachment_delimiter = "----gnatsweb-attachment----\n";
Delimiter to use within PRs for storage of attachments.  Modifying
this variable should not be necessary and will break existing
attachments.


$gnats_info_top = 'http://www.gnu.org/software/gnats/gnats_toc.html';
The URL of a web site providing the GNATS manual in HTML format.  This
URL is presented if the help page pointed to by $help_page_path is
unavailable