4
The GNU Problem Report Management System
6
Installation Guide for Gnatsweb 4
9
Quick start for the impatient
10
=============================
12
1. The following procedure assumes that you have a working
13
installation of GNATS version 4. If not, refer to the installation
14
instructions in Chapter 3, `Installing GNATS' of the GNATS manual.
16
PLEASE NOTE: Gnatsweb 4 does not work with GNATS 3.x servers. It
17
only supports GNATS 4.0 or newer.
19
If you are upgrading from an old Gnatsweb 4 installation, see the
20
notice about upgrading under item 6 below.
22
If you are migrating to GNATS 4 from GNATS 3.x and are upgrading
23
from an old Gnatsweb 2.x installation, you should back up and
24
remove the Gnatsweb files in your cgi-bin directory before
27
2. Since Gnatsweb runs on your web server, you need to grant the web
28
server access to the GNATS database. Here are two different ways
31
a. Grant 'edit' access to the web server in the gnatsd.host_access
32
file. This file is located in /usr/local/etc/gnats by default,
33
but this may have been overridden when GNATS was installed.
34
Typically, the web server is running on the same machine as the
35
GNATS server, so that the following line needs to be added to
40
Do note that this disables all security -- anyone with access to
41
the Gnatsweb script on the web server gets edit access to your
42
GNATS databases. Gnatsweb will still prompt for a username at
43
login, but this username will only be used for generating
44
Audit-Trail entries to track PR edits. This means that you
45
don't need to maintain a GNATS user database since any login
48
b. Grant restricted access only to the web server in the
49
gnatsd.host_access file. Grant higher access to individual
50
users by adding username/password entries in the
51
gnats-adm/gnatsd.access file or the global gnatsd.access file by
52
default located in /usr/local/etc/gnats. The web server must
53
have at least 'listdb' access. If the web server is running on
54
the same machine as the GNATS server, the following line needs
55
to be added to gnatsd.host_access:
59
If you want more restrictions than provided by those solutions,
60
consider restricting access to your web server, or the
61
particular CGI directory where you plan to install gnatsweb.
63
For more information about GNATS access control, see Appendix C,
64
`Controlling access to databases' of the GNATS 4 manual.
66
3. If your GNATS server is on the same host as your web server, skip
67
this step for now. If not, edit 'gnatsweb-site.pl', the site
68
configuration file. You need to set the variables $site_gnats_host
69
and $site_gnats_port to point to your GNATS server.
71
Default installations of GNATS run on port 1529, so if you have a
72
default GNATS installation running on the host `gnats.example.com',
73
you would set $site_gnats_host to 'gnats.example.com' and
74
$site_gnats_port to '1529'.
76
4. In order for Gnatsweb to work properly, you need to install two
77
Perl modules on your system. Some systems may already have them
78
installed, but the following procedure ensures that you have the
79
correct versions of them on your system:
81
CGI.pm v2.56 or newer (the unofficial version 3.x of CGI.pm will
82
not work): Gnatsweb will not work at all without this module. On
83
most systems, the following command (run as root) installs the
86
perl -MCPAN -e 'install CGI'
88
MIME::BASE64 (Gnatsweb will run without it, but attachment handling
89
will be disabled). Most systems get the right version when the
90
following command is run (as root):
92
perl -MCPAN -e 'install MIME::Base64'
94
5. Change line 1 of gnatsweb.pl to point to the location of your
95
'perl' executable. Perl must be version 5.
97
6. Run the tests to make sure the setup is OK. Specify a
98
username/password/database_name on the command line like so:
100
make test USERNAME=user PASSWORD=password DATABASE=database
102
where 'user' is the name of a user defined in your GNATS server's
103
gnatsd.access files, 'password' is the user's password and
104
'database' is the name of one of the databases on your server.
106
If you don't see the message "All tests passed", investigate. The
107
TROUBLESHOOTING document distributed with Gnatsweb contains some
108
useful advice. See also the end of this document.
110
7. Install gnatsweb.pl and gnatsweb-site.pl into a CGI-enabled
111
directory on your web server. For a typical Apache web server
114
make install CGI_DIR=/usr/local/apache/cgi-bin
118
If your cgi-bin directory already contains the files gnatsweb.pl
119
and gnatsweb.html, these will be renamed to gnatsweb.pl.old and
120
gnatsweb-site.html.old before the new files are installed. If you
121
already have a gnatsweb-site.pl file, this file will not be touched
122
during installation. However, you should compare the
123
gnatsweb-site.pl in the distribution with the currently installed
124
file and make sure that there isn't any new stuff which you need to
125
copy into your installed configuration.
131
You should now have a basic, working Gnatsweb installation. To tailor
132
it further to your site's needs, go on to read the CUSTOMIZE document.
135
What to do if you have problems
136
===============================
138
- Go through the TROUBLESHOOTING document.
139
- Try sifting through the GNATS-related mailing list archives at
140
http://savannah.gnu.org/mail/?group_id=65
141
- If you still have problems, try posting to the help-gnats mailing
142
list. Subscribe from http://savannah.gnu.org/mail/?group_id=65
143
Please avoid posting until you are completely certain that there is
144
nothing relevant in the mailinglist archives.
added
removed
contrib/gnatsweb/INSTALL
