See Where the tools and utilities reside.

There are several steps you need to follow to fully configure and install GNATS on your system.  You need root access in order to create a new account for gnats and to install the GNATS utilities.  You may need root access on some systems in order to set mail aliases in place and to allow this new account access to cron and at.

If you are updating an older version of GNATS rather than installing from scratch, see Upgrading from older versions.

To build GNATS, you must:

  * Run configure, with correct options if the defaults are unsuitable for your site.  See Configuring and compiling the software.  Default installation locations are in Where GNATS lives.

  * Compile the GNATS programs on your system.  See Configuring and compiling the software.

  * Install the GNATS tools and utilities locally, and install the user tools on every machine in your local network.  See Installing the utilities.

  * Set up mail aliases for GNATS.  See Setting up mail aliases.

  * Install the GNATS user tools (query-pr, nquery-pr, edit-pr, send-pr) around your network.  See Installing the user tools.

  * Install the GNATS daemon gnatsd.

  * Update the local configuration files

          config      categories  submitters  responsible  gnatsd.conf

     in GNATS_ROOT/gnats-adm.  See Changing your local configuration.

  * Create a distribution of send-pr for submitters outside your organization.  See Configuring send-pr for the outside world.

Configuring and compiling the software
======================================

 1. First, unpack your distribution.  We provide source code in a tar file which was compressed using gzip.  The code can be extracted into a directory UNPACKDIR using

          mkdir UNPACKDIR
          cd UNPACKDIR
          tar zxvf gnats-VERSION.tar.z

     The sources reside in a directory called gnats-VERSION when unpacked.  We call this the top level of the source directory, or srcdir.  The sources for the GNATS tools are in the subdirectory gnats-VERSION/gnats/*.  Lists of files included in the distribution are in each directory in the file MANIFEST.

 2. You may wish to alter the installation directory for the Emacs lisp files.  If your Emacs lisp library is not in PREFIX/lib/emacs/lisp, edit the files

          SRCDIR/gnats/Makefile.in   and
          SRCDIR/send-pr/Makefile.in

     Change the variable lispdir from $(datadir)/emacs/lisp to the directory containing your Emacs lisp library.  For information on PREFIX, see PREFIX.

 3. Run configure.  You can nearly always run configure with the command

          ./configure --with-full-gnats

     and the ``Right Thing'' happens:

       * GNATS is configured in the same directory you unpacked it in;

       * when built, GNATS runs on the machine you're building it on;

       * when installed, files are installed under /usr/local (see Where GNATS lives).

       * GNATS operates by default behavior (see Default behavior).

     The full usage for configure is:

          configure [ --with-full-gnats ]
                    [ --prefix=PREFIX ]
                    [ --exec-prefix=EXEC-PREFIX ]
                    [ --with-gnats-root=GNATS_ROOT ]
                    [ --with-gnats-server=HOSTNAME ]
                    [ --with-gnats-service=SERVICE-NAME ]
                    [ --with-gnats-user=USERNAME ]
                    [ --with-gnats-port=PORT-NUMBER ]
                    [ --verbose ]

     --with-full-gnats
          All programs are to be built; this includes the user utilities, the administrative utilities, and the internal utilities.  Use this when configuring the utilities for the machine where GNATS is to run. Omit it when building only the user utilities for other machines on your network; see Installing the user tools.

     --prefix=PREFIX
          All host-independent programs and files are to be installed under PREFIX.  (Host-dependent programs and files are also installed in PREFIX by default.)  The default for PREFIX is /usr/local.  See Where GNATS lives.

     --exec-prefix=EXEC-PREFIX
          All host-dependent programs and files are to be installed under EXEC-PREFIX.  The default for EXEC-PREFIX is PREFIX. See Where GNATS lives.

     --with-gnats-root=GNATS_ROOT
          The database and its data files are to be installed into GNATS_ROOT.  The default for GNATS_ROOT is PREFIX/lib/gnats/gnats-db.  See Where GNATS lives.

     --with-gnats-root=hostname
          FIXME

     --with-gnats-root=SERVICE-NAME
          FIXME

     --with-gnats-user=USERNAME
          FIXME

     --with-gnats-port=PORT-NUMBER
          FIXME

     --verbose
          Give verbose output while configure runs.

     See Using configure (Cygnus configure).

     You can build GNATS in a different directory (OBJDIR) from the source code by calling the configure program from the new directory, as in

          mkdir OBJDIR
          cd OBJDIR
          SRCDIR/configure ...
          make all

     By default, configure compiles the programs in the same directory as the sources (SRCDIR).  Emacs lisp files are byte-compiled if make can find Emacs on your local system.

 4. Run

          make all info

     from the directory where configure created a Makefile. (This may not be the same directory as the source directory.)  These targets indicate:

     all
          Compile all programs

     info
          Create info files using makeinfo.

Installing the utilities
========================

The following steps are necessary for a complete installation.  You may need root access for these.

 1. Install the utilities by invoking

          make install install-info

     These targets indicate:

     install
          Installs all programs into their configured locations (see Where GNATS lives).

     install-info
          Installs info files into their configured locations (see Where GNATS lives).

     After you have installed GNATS, you can remove the object files with

          make clean

 2. Place the following lines in the file default.el in your Emacs lisp library, or instruct your local responsible parties to place the lines in their local editions of .emacs:

          (autoload 'edit-pr "gnats"
             "Command to edit a problem report." t)
          (autoload 'view-pr "gnats"
             "Command to view a problem report." t)
          (autoload 'unlock-pr "gnats"
             "Unlock a problem report." t)
          (autoload 'query-pr "gnats"
             "Command to query information about problem reports." t)
          (autoload 'send-pr-mode "send-pr"
             "Major mode for sending problem reports." t)
          (autoload 'send-pr "send-pr"
             "Command to create and send a problem report." t)

     Emacs lisp files are byte-compiled if make can find Emacs on your local system.

 3. Create an account for a user named GNATS.  This user must have an entry in the file /etc/passwd.  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 EXEC-PREFIX/bin and EXEC-PREFIX/lib/gnats.

 4. Allow the new user gnats access to cron and at.  To do this, add the name gnats to the files cron.allow and at.allow, which normally reside in the directory /var/spool/cron.  If these files do not exist, make sure gnats does not appear in either of the files cron.deny and at.deny (in the same directory).

     For the following steps, log in as gnats.

       * Edit the files categories, responsible, and submitters in the directory GNATS_ROOT/gnats-adm (see Changing your local configuration) to reflect your local needs.  Be sure to run mkcat after you update the categories file (see Adding a new problem category).  Note: these templates are not installed if they already exist, i.e. if you are upgrading.  See Upgrading from older versions.

       * If you wish to install the GNATS user tools on other machines on your network, see Installing the user tools.

 5. Create a crontab entry that periodically runs the program queue-pr with the --run option.  For example, to run queue-pr --run every ten minutes, create a file called .mycron in the home directory of the user gnats which contains the line:

          0,10,20,30,40,50 * * * * EXEC-PREFIX/lib/gnats/queue-pr --run

     (Specify the full path name for queue-pr.)  Then run

          crontab .mycron

     See the man pages for cron and crontab for details on using cron.

Setting up mail aliases
=======================

The following mail aliases must be placed in the file /etc/aliases on the same machine where the GNATS tools are installed.  You may need root access to add these aliases.

  * Create an alias for the GNATS administrator.  This address should point to the address of the person in charge of administrating GNATS:

          gnats-admin:  ADDRESS

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

          bugs:  "| EXEC-PREFIX/lib/gnats/queue-pr -q"

     This places incoming Problem Reports in GNATS_ROOT/gnats-queue.

  * Create an alias for your site. This alias should be the same nametag indicated by the variable GNATS_SITE in the file GNATS_ROOT/gnats-adm/config (see The config file), with an added suffix -gnats.  This alias, GNATS_SITE-gnats, should point toward the local submission address.  For instance, if your site is Tofu Technologies, the presence of GNATS on your SITE would be aliased as the following (the previous example is also shown):

          bugs:  "| EXEC-PREFIX/lib/gnats/queue-pr -q"
          tofu-gnats: bugs

     The report submission utility send-pr automatically appends the -gnats to any arguments you specify (see Submitting Problem Reports).  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 is sent to your local GNATS.  Part of the installation process a Submitter Site follows when installing send-pr is to set up an alias for the Support Site from whom this submitter received send-pr.  In other words, anyone you distribute send-pr to is instructed to make an alias

          tofu-gnats: bugs@tofu.com

  * You may also wish to forward a copy of each incoming Problem Report to a log.  This can be accomplished with something like:

          bug-q: "| EXEC-PREFIX/lib/gnats/queue-pr -q"
          bug-log:  GNATS_ROOT/gnats-adm/bugs.log
          bugs:      bug-q, bug-log

     This configuration archives incoming Problem Reports in the file GNATS_ROOT/gnats-adm/bug.log, and also feeds them to the program queue-pr.  (Remember, bug.log needs to be world-writable, and should be pruned regularly; see GNATS Administration.)

  * If you want your users to be able to query the database by mail, use the following alias:

          query-pr: "| EXEC-PREFIX/lib/gnats/mail-query"

     The mail-query program uses --restricted to search on the database, and by default only searches for PRs that aren't closed (see Querying the database).

Installing the daemon
=====================

By default, the daemon and clients are set to use port 1529.  Add the line

     support		1529/tcp			# GNATS

to your /etc/services file.  If you want a different port, or a different service name or port, configure GNATS with

     --with-gnats-service=SERVICENAME
     --with-gnats-port=PORTNUMBER

In your inetd.conf file, add the line

     support	stream	tcp	nowait	gnats	/usr/local/lib/gnats/gnatsd gnatsd

adjusting the path accordingly.  To make inetd start spawning the GNATS daemon when connected on that port, send it a hangup signal (HUP).

By default, the server for the GNATS daemon is assumed to be one with the name of gnats.  If you'd like something else, use

     --with-gnats-server=HOSTNAME

In the gnats-adm directory, you'll want to edit gnatsd.conf. It lists the hosts allowed to access your server.  Or, if you're using Kerberos, it shows the sites that don't require Kerberos authentication. The format is reserved for future revision; only the first field is actually used:

     site.com::

The second field may be used for things like controlling what categories, submitter-id'd PRs, etc., can be accessed from that site. In the file that logs syslog messages (/var/adm/messages, for example) you'll find the notification of denied access.

Installing the user tools
=========================

When you install the GNATS utilities, the user tools are installed by default on the host machine.  If your machine is part of a network, however, you may wish to install the user tools on each machine in the network so that responsible parties on those machines can submit new Problem Reports, query the database, and edit existing PRs.  To do this, follow these steps on each new host.  You may need root access on each machine.

 1. Make sure that the directory where GNATS resides is mounted to each system that will need access to it, so GNATS_ROOT will be the same for each host.  (You can do this with symbolic links as well.)

 2. Either mount the disk which contains your source directory, or make a copy of the GNATS source code tree in a separate directory on each system you wish to build on.

 3. Run configure, without specifying --with-full-gnats, and using the same argument (if any) for the option

          --with-gnats-root=GNATS_ROOT

     that you specified when building the GNATS utilites (see Configuring and compiling the software). You may use different values for the other options to configure. Again, do not use --with-full-gnats at this point, as that creates all the GNATS programs.  Without this option, configure only instructs the resulting Makefile to create the user utilities.

     You may need root access on each host for the following steps.

 4. Create an account for a user named GNATS on the new host.  This user must have an entry in the file /etc/passwd.  The user ID for gnats must be the same as on the main GNATS host.

 5. Run

          make all info install install-info

     This builds and installs the gnats user tools query-pr, edit-pr, and send-pr on the new host, and installs them in EXEC-PREFIX/bin on the new host (Note: the value for EXEC-PREFIX on the new host may be different from the value you used when building the GNATS utilities; see EXEC-PREFIX).  The programs pr-edit and pr-addr are installed into EXEC-PREFIX/lib/gnats.

     info files are created as well, and are installed into PREFIX/info.  The Elisp files gnats.el and send-pr.el (and possibly gnats.elc if make was able to compile them using Emacs) are installed into PREFIX/lib/emacs/lisp unless you change the lispdir variable in Makefile.in (see Configuring and compiling the software).

 6. Add the following lines to the file default.el in the Emacs lisp repository on the new host, or instruct your responsible parties who use these hosts to add them to their .emacs files:

          (autoload 'edit-pr "gnats"
             "Command to edit a problem report." t)
          (autoload 'view-pr "gnats"
             "Command to view a problem report." t)
          (autoload 'unlock-pr "gnats"
             "Unlock a problem report." t)
          (autoload 'query-pr "gnats"
             "Command to query information about problem reports." t)
          (autoload 'send-pr-mode "send-pr"
             "Major mode for sending problem reports." t)
          (autoload 'send-pr "send-pr"
             "Command to create and send a problem report." t)

 7. Copy the file PREFIX/lib/gnats/SITE from the original host to the new host (which may have a different value for PREFIX).  This is the list of valid categories that send-pr uses (see Where GNATS lives). SITE is your local site, the value of GNATS_SITE in the config file (see The config file).

Upgrading from older versions
=============================

If you are upgrading from a previous release of GNATS, you probably do not want to delete your current configuration files or your current database.  The new GNATS can be installed around the older version.

You need to:

  * Specify your current GNATS_ROOT on the command line to configure when you build the new tools, with

          configure --with-full-gnats --with-gnats-root=GNATS_ROOT

     (see Configuring and compiling the software.)

  * Remove the directory gnats-bin from GNATS_ROOT; it is no longer used.

  * Update your current mail aliases to reflect that queue-pr now resides in EXEC-PREFIX/lib/gnats rather than GNATS_ROOT/gnats-bin (see Where GNATS lives).

  * Change the default PATH for the gnats user to search the directories EXEC-PREFIX/bin and EXEC-PREFIX/lib/gnats.

  * Reinstall the GNATS user tools on all other hosts on your network (see Installing the user tools).

  * Redistribute send-pr to your Submitter Sites (see Configuring send-pr for the outside world). This is not absolutely necessary, as GNATS can read Problem Reports generated by older versions of send-pr.  It should be done eventually, however, as send-pr is improved over older verisons.