February 14, 1997

README - CERN WWWGNATS V2.0


This following provides instructions on installing the new release of
the CERN version of wwwgnats. This version requires the Gnats V3.100
beta release. 

As a prerequisite perl5 must be installed on your machine. All the
scripts look for it in /usr/local/bin/perl5. If you have installed
Perl in a  different place the scripts must be edited to reflect this.

You also need an HTTP server running on your machine. Our package is
currently using the CERN httpd v3.0A, which is the one we recommend
since the configuration file we distribute runs with it. We are
currently looking into the possibility of using an alternative
server. You can find the CERN httpd at the following url: 

           http://www.w3.org/pub/WWW/Daemon/

Gnats can be downloaded using anonymous ftp from "ftp.cygnus.com"
where you will find the tar file in the /pub directory.

Unpack gnats wherever you want. Refer to the Gnats documentation for
the installation instructions. 

First you've had to download this kit, if not you won't be reading
this file.

You will have to replace some source code from Gnats before compiling
it. These files are the ones in 3.100-B_src-mods. To keep the old
source you can move the  old files to *.orig. After copying the new
files compile Gnats as described in the installation documentation.

It is recommended that the kit be unpacked in the area where you have
your HTTP server. It'll create the following directories:

/3.100-B_src-mods		which contains the source code
				modifications.
/Web				which contains the file help.html.
/config				which contains the httpd.conf and
                                pwfile examples.
/cgi-bin			which contains cgi scripts to run
				Gnats in Web mode.
/config_file_examples		which contains the examples for the 
				gnats config files.

 In these directories you will need to make the following
modifications:

/3.100-B_src-mods   No modifications. Replace the same files in the
		    source code of Gnats.

/Web		    No modifications.

/config          

     httpd.conf:    Modify the following values to match your system:

                    - ServerRoot, this is the directory where your
		      HTTP server lives.
                    - UserId and GroupId.
                    - AccessLog and ErrorLog, the access and error log 
                      locations.
                    - The Pass rule and the Exec rule pointing to the 
                      directories you use.
                    - The mapping rule which maps the /file*.
                    - Protection Setup (if wanted). Modify:
	                  - The path for the password file.
	                  - The mask.
	                  - The UserId, GroupId and ServerId (if
			    necessary).


     pwfile:        This is an example of the password file used if
		    the editing of problem reports needs to be
		    protected. This is managed using the htadm tool
		    which comes with the CERN httpd.


/cgi-bin

     edit_pr.pl:    Change the two "require" statements to point to
                    the right path to get the libraries.

     gnats_home.pl: Modify the "require" statement to get the library 
		    from the right path. After that modify the html 
		    document: the title, the text, put the name of 
		    your server in the anchor (replace the 
		    nnnn.nnn.nn), replace the TEST domain with your 
		    own domains and add a new different link for any 
		    new domain in your system. 

     libgnats.pl:   Check the configuration: all the GNATS_*
		    variables, specially $GNATS_ROOT and $GNATS_ADDR.
		    In the last one, replace nnnn.nnn.nn by your 
		    machine's name.

     mailto.sh:     Put the right path for the variable CGIPARSE.

     sendmailto.pl: Put the right path in the "require" statement to
		    take the cgi library. In the <FORM> tag, specify
		    in the "ACTION" the name of your server (replace
		    nnnn.nnn.nn).

     wwwgnats.pl:   Change the two "require" statements to point to
		    the right path to get the libraries. In the 
		    definition of the routine query_full, there is a
		    <FORM> tag where the name of your server has to
		    be specified in the "ACTION" (replacing
		    nnnn.nnn.nn).


/config_file_examples

     categories:    Use this example to build your own file for your
		    site. After that put it in the $GNATS_ADM
		    directory (check which directory is it in 
		    libgnats.pl). Move the original file (the one
		    which is in the $GNATS_ADM directory) to 
                    categories.orig.

     categories-TEST: This file contains entries for the categories in
		    the TEST domain. It's necessary to create a
		    different file for each domain in your system.
		    Copy all of them in the $GNATS_ADM directory.

     domains:       Edit this file to contain a list of your domains
		    (one per line). Copy it to the $GNATS_ADM
		    directory.

     editors-TEST:  Use the example to create a different editors file
		    for each domain, afterwards put them in the
		    $GNATS_ADM directory.

     responsible:   Use this example to build your own file for your
		    site. After that put it in the $GNATS_ADM
		    directory (check which directory is it in
		    libgnats.pl). Move the original file (the one
		    which is in the $GNATS_ADM directory) to
		    responsible.orig.

     responsible-TEST: This file contains entries for the responsible
		    persons in the TEST domain. It's necessary to 
		    create a different file for each domain in your
		    system. Copy all of them in the $GNATS_ADM 
		    directory.

     mail2sendpr:   This is a script which converts a mail to a
		    formatted problem report. We have added filters to
		    redirect mails from external sources or the ones
		    produced by internal alarm systems. Change the 
		    $adm_path variable and put the whole path for your
		    $GNATS_ADM directory. If you would like to use the
		    filter for the mails from outside and/or the one
		    for the alarm system, you should uncomment and
                    adapt the following lines (there are comments in
		    the lines above them for more information):

          #$addr_cern = ($fromaddr=~/cern\.ch/i || $fromaddr !~ /@/ );
	  [...]
          # elsif (($subject)=~/SURE UPDATE$/) { exit; }


                    Also modify the message that is at the end of the
		    file in order to adapt it to your site. After the 
                    modifications, put the file in the $GNATS_ADM
		    directory.

     sendprform:    This is the file with the template we use to
		    create a problem report from a mail. Modify the
		    "To:" address, replacing the nnnn.nnn.nn by the
		    name of your machine. Also modify the 
		    ">Submitter-Id:" line and the ">Organization:"
		    line with your own values. After that put the file
		    in the $GNATS_ADM directory.

     catlist:       This file is a list of login_id's and names of
		    categories. If you want to convert mails to
		    different accounts into problem reports you need
		    this file (and also mail2sendpr and sendprform).
		    It's necessary to create one user for each category
		    in your system, including all the categories in
		    all domains. In the home directory of these users
		    write a .forward file containing a pipe to the
		    mail2sendpr script, which is a line like this
		    (double quotes included):

                          "| $GNATS_ADM/mail2sendpr"

                    where $GNATS_ADM has to be replaced for the whole
		    path.



  NOTE: In the $GNATS_ADM directory there is a file called submitters
which is a configuration file to allow you to use different sites
submitting problems in your system. Leave the entry for the unknown
submitter, comment the other entries and add a new one at the end like
the following:

   	your_submitter:Submitter Site:eternal:9:::

  replacing your_submitter with the value you want to use.



Please send any comments or questions to:

gnats.support@cern.ch 

Thanks!
Jesus Sanchez.
