	Installation procedures for GNATS

*** This is a very brief discussion of the installation procedure ***
*** for GNATS.  It is strongly reccommended that anyone attempting ***
*** to install and operate GNATS refer to the file gnats.texi.      ***

Configuring and installing `GNATS'
*********************************

   There are several steps you need to go through to fully configure and
install `GNATS' on your system.  You will need `root' access in order to
make a new account for `gnats', to allow this "user" access to `cron'
and `at', and to install the `GNATS' utilities.  You may need `root'
access on some systems in order to set mail aliases in place.

  1. *First, unpack your distribution*.
     Whether the distribution you receive is on a tape or from the Net,
     all the sources reside in a directory called `gnats-3.00' when
     unpacked.  We will call this the "top level" of the "source
     directory", or "srcdir".  The sources for the `GNATS' tools are in
     the subdirectory `gnats-3.00/gnats/*'.

     Lists of files included in the distribution are in each directory
     in the file `MANIFEST'.

  2. *From the top level of the source directory, edit
          `/gnats/Makefile.in'*.
     In the file `gnats-3.00/gnats/Makefile.in', set the following
     variables:

    `GNATS_ROOT'
          The directory where the database, all administration files,
          etc., resides.  After installing, any changes should be made
          in this directory.  From now on, we will refer to this
          directory as GNATS_ROOT.

    `GNATS_ADDR'
          The address to which software users should submit bugs.  For
          instance, if you wish all problem reports to be sent to your
          site at `bug-reports@YOUR-ORGANIZATION', this full address
          should be the value of `GNATS_ADDR'.

    `GNATS_SITE'
          A one-word name tag for your site, to be used as an alias for
          anyone who submits bug reports.  You should also include this
          name in the `submitters' file so `GNATS' can recognize bug
          reports originating from inside your organization (see step
          12).  This value also becomes the name of a list of
          categories your organization supports, which is kept up to
          date locally when you run the program `mkcat' (see the section
          "The `categories' file" in the GNATS manual) and is created
          for outside users when you use the utility `mkdist' (see the
          section "Configuring `send-pr' for the outside world" in the
          GNATS manual).

    `DEFAULT_RELEASE'
          Used by `send-pr' as a default value for the `>Release:'
          field.  Use the name or release number of your most recent
          release, or just leave it blank to set no default.

     This is the only `Makefile' you should edit in this distribution.

  3. *Edit the file `gnats-3.00/gnats/config.h'*.
     This file contains variables which establish some behavior traits
     of `GNATS'.  See the section "The `config.h' file" in the GNATS 
     manual.

  4. *Run `configure' at the top level*.
     You can nearly always run `configure' from the top level of the
     source directory, `gnats-3.00', with the command

          ./configure HOST

     (where HOST is your host) and the "Right Thing" will happen:
     `GNATS' will be configured in the same directory you unpacked it in;
     when built, it will be able to run on the machine you're building
     it on; and when installed, files which should be public will be
     installed in `/usr/local'.

     You may wish to build `GNATS' in a different directory from the
     source directory, or install the user utilities like `query-pr' in
     a directory different from `/usr/local'.  For instructions on this,
     see the section "Configuring `GNATS' on your system" in the GNATS 
     manual.

  5. *Run `make all' at the top level*.
     *Do not* run `make install' at this point, as installation must be
     done with `root' privileges.

*****The following steps may require `root' privileges******

  6. *`su root' to acquire `root' privileges*.

  7. *Create a `passwd' entry for `gnats'*.
     In other words, create an account for a user named "`gnats'".  The
     home directory for this account should be the same directory you
     specified for GNATS_ROOT in the file `Makefile.in'.  Also, the
     default path for this "user" should contain `GNATS_ROOT/gnats-bin'.

  8. *Run*
          make install GNATS=install-gnats

     from the top level of your source directory. This installs `GNATS'
     in the directory you specified with `GNATS_ROOT'.  It also installs
     the other files associated with `GNATS', including the program
     `send-pr', the GNU library `libiberty', and several others.

  9. *Allow `cron' and `at' commands for the user `gnats'*.
     `GNATS' requires access to both `cron' and `at', so it may be
     necessary to explicitly allow the user `gnats' access by adding it
     to the files

          /var/spool/cron/cron.allow *and*
          /var/spool/cron/at.allow

     if these files exist.  If they do *not* exist, and the name `gnats'
     does not appear in the corresponding files `cron.deny' or
     `at.deny', then no further action is necessary.

 10. *If you need to use `GNATS' utilities, like `query-pr' and
     `edit-pr', on other systems* besides the one `GNATS' itself resides
     on, see the section "Using `GNATS' over a network" in the GNATS 
     manual.

 11. In the file `/etc/aliases', or wherever your mail system looks for
     mail aliases, create an alias for `gnats-admin', the `GNATS'
     administrator.  Assign this alias to the person in charge of
     `GNATS'.  See the section "Managing `GNATS'" in the GNATS manual.

 12. Create an alias to redirect incoming bugs.  This alias should
     redirect incoming mail via a "pipe" to the program `queue-pr -q'.
     For example, if PRs coming to your site are to arrive at the
     address `bugs@your.company.com', create an alias to the effect of:

          bugs:      "| GNATS_ROOT/gnats-bin/queue-pr -q > /dev/null 2>&1"

     where GNATS_ROOT is the directory where `GNATS' resides, which you
     indicated in the file `Makefile.in'.  This places all incoming
     bugs in the directory `GNATS_ROOT/gnats-queue'.

 13. Create an alias for your site.  This name should be the same name
     you indicated in `Makefile.in' above with the variable
     `GNATS_SITE', with the suffix `-gnats', and should point toward the
     local submission address.  For instance, if your site is Killer
     Technologies, the presence of `GNATS' on your SITE would be aliased
     as

          bugs:      "| GNATS_ROOT/gnats-bin/queue-pr -q > /dev/null 2>&1"
          killer-gnats: bugs

     The report-submission utility `send-pr' automatically appends the
     `-gnats' to any arguments you specify.  The `send-pr' which was
     installed when you typed `make install' has a default argument of
     GNATS_SITE, your site, so that when your local users simply type
     `send-pr' mail will be sent to your local `GNATS'.  Part of the
     installation process for `send-pr' is to set up an alias for the
     support site they received `send-pr' from, so that anyone you
     distribute `send-pr' to will be instructed to make an alias

          killer-gnats: bugs@killer.com

     This allows users at your site, as well as anyone to whom you
     distribute `send-pr', to type `send-pr killer' on the command line
     and submit PRs to your site.  This aliasing is to allow your
     organization and its affiliates to use the same `send-pr' to submit
     bugs to more than one support site.  For instance, if you also
     submit PRs to a `GNATS' located at Bumblebee BASIC, Inc., and
     Unencumbered Unix (a well-known supporter of Free Software), your
     `/etc/aliases' file might resemble something like the following:

          # local and external GNATS sites
          # local first
          bugs:      "| GNATS_ROOT/gnats-bin/queue-pr -q > /dev/null 2>&1"
          killer-gnats:       local-bugs
          # other sites
          bumblebee-gnats:    bumblebugs@bumblebee.com
          unencumbered-gnats: unencumberbugs@unencumbered.org

     With these aliases, your users may simply type `send-pr bumblebee'
     to send Problem Reports to Bumblebee BASIC, or more precisely to
     `bumblebugs', their `GNATS' alias.

     Any of your affiliates who do not run `GNATS' themselves will have a
     copy of `send-pr' which sends mail by default to
     `bugs@killer.com'.  If these outside folk *do* run `GNATS', it is
     up to the system administrator at each local site to decide on a
     default address.  See the section "Installing `send-pr' on your system"
     in the send-pr manual "Reporting Problems With send-pr".  See the
     section "Introduction" in the GNATS manual for more discussion on
     the `GNATS' paradigm.

 14. You may also wish to forward a copy of each incoming Problem
     Report to a log.  This can be accomplished via the mail aliases
     function with something like:

          bugs-queue:  "| GNATS_ROOT/gnats-bin/queue-pr -q > /dev/null 2>&1"
          bugs-log:    GNATS_ROOT/bug.log
          bugs:        bugs-queue, bugs-log

     where GNATS_ROOT is the directory `GNATS' resides in, which you
     specified in the file `gnats-3.00/gnats/Makefile.in'.  This
     configuration will archive mail in the file `GNATS_ROOT/bug.log',
     and also feed it to the program `queue-pr'.  (Remember, `bug.log'
     needs to be world-writable, and should be pruned regularly; see
     the section "Managing `GNATS'"in the GNATS manual.)

 15. *Exit from the `root' shell*.

 16. *Log in as `gnats'*, the new account you created.  foobar

 17. *Edit the files you just installed in `GNATS_ROOT/gnats-adm'*.
     You will need to edit:

        * `GNATS_ROOT/gnats-adm/categories',

        * `GNATS_ROOT/gnats-adm/submitters', and

        * `GNATS_ROOT/gnats-adm/responsible'.

     to reflect your site's schema for collecting data.  See the
     section "Files used for `GNATS' administration" in the GNATS manual
     for detailed discussions of the formats of these files.  For more
     discussion on data collection schematics, see the section
     "Introducing `GNATS'" in the GNATS manual.

 18. *Run `GNATS_ROOT/gnats-bin/mkcat'*.
     This script sets up the subdirectories of GNATS_ROOT which will
     contain submitted Problem Reports.  Each subdirectory is named for
     the category its bugs will belong to; for instance, all bugs
     submitted with a category of *carbuerator* will be filed in the
     directory `GNATS_ROOT/carbuerator'.  `mkcat' creates these
     directories according to the data you placed in the `categories'
     file (See the section "The `categories' file" in the GNATS
     manual); it also updates the local list of supported categories
     used by `send-pr'.

     Always run `mkcat' whenever you need to add a new category.  See
     the section "Managing `GNATS'" in the GNATS manual.

 19. *Create a `crontab' entry for the user `gnats'* to periodically run
     the command

          GNATS_ROOT/gnats-bin/queue-pr -r

     The `-r' option causes `queue-pr' to feed all the incoming bugs
     from the directory `GNATS_ROOT/gnats-queue' into the program
     `file-pr', which assigns each new bug an individual serial number,
     notifies responsible parties of the bug's existence, updates the
     index, files the bug in the correct subdirectory, etc.  See the
     section "Introducing `GNATS'" in the GNATS manual.

 20. *Log out from the `gnats' account*.

   `GNATS' is now "live" on your system.  The program `send-pr' (`M-x
send-pr' from within Emacs) helps your local users to submit Problem
Reports.  You should pre-configure and distribute copies of `send-pr'
to all parties you wish to receive bug reports from using the program
`mkdist'; see the section "Configuring `send-pr' for the outside
world" in the GNATS manual.  See also the section "Overview" in the
send-pr manual "Reporting Problems With send-pr".
