A. Installing GNATS

See section 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 up mail aliases 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.

In order to build GNATS, you will need to have GNU m4 installed; most systems ship with a version of m4 that is not able to work with the `config.m4' file.

To build GNATS, you must:

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

• Compile the GNATS programs on your system. See section 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 section Installing the utilities.

• Set up mail aliases for GNATS. See section Setting up mail aliases.

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

• Install the GNATS daemon `gnatsd'. See section A.4 Installing the daemon.

• Update the local configuration files

  config categories submitters responsible gnatsd.conf gnatsd.access states classes addresses

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

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

A.1 Configuring and compiling the software
A.2 Installing the utilities
A.3 Setting up mail aliases
A.4 Installing the daemon
A.5 Installing the user tools
A.6 Upgrading from older versions

A.1 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

   cd unpackdir tar zxvf gnats-3.113.tar.z

   The sources reside in a directory called `gnats-3.113' 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-3.113/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/share/emacs/site-lisp', edit the files

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

   Change the variable `lispdir' from `$(datadir)/emacs/site-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 section Where GNATS lives).

   • GNATS operates by default behavior (see section 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 section 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 section 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/share/gnats/gnats-db'. See section Where GNATS lives.

   --with-gnats-server=hostname

   Set hostname to be the GNATS network server.

   --with-gnats-service=service-name

   Set service-name to be the GNATS network service.

   --with-gnats-user=username

   Set username to be the user name for GNATS from the passwd file.

   --with-gnats-port=port-number

   Set the server port to be port-number if the service doesn't register.

   --verbose

   Give verbose output while configure runs.

   See section `Using configure' in 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 ...

   By default, make 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 is objdir if you used it, otherwise srcdir.) These targets indicate:

   all

   Compile all programs

   info

   Create `info' files using makeinfo.

A.2 Installing the utilities

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

1. 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. Also, the default PATH for this user should contain `exec-prefix/bin' and `exec-prefix/libexec/gnats'.

2. Install the utilities by invoking

   make install install-info

   These targets indicate:

   install

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

   install-info

   Installs `info' files into their configured locations (see section Where GNATS lives).

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

   make clean

3. 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 `.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.

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 section Changing your local configuration) to reflect your local needs. Be sure to run mkcat after you update the `categories' file (see section Adding a new problem category). Note: these templates are not installed if they already exist, i.e. if you are upgrading. See section 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/libexec/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.

A.3 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/libexec/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 section 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/libexec/gnats/queue-pr -q" tofu-gnats: bugs

  The report submission utility send-pr automatically appends the `-gnats' to any arguments you specify (see section 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/libexec/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 section GNATS Administration.)

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

  query-pr: "| exec-prefix/libexec/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 section Querying the database).

A.4 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 and their default access level. 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 two fields are actually used:

site.com:view:

The third field might in the future 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.

A.5 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 utilities (see section 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 section exec-prefix). The programs pr-edit and pr-addr are installed into `exec-prefix/libexec/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/share/emacs/site-lisp' unless you change the `lispdir' variable in `Makefile.in' (see section 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/share/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 section Where GNATS lives). site is your local site, the value of `GNATS_SITE' in the `config' file (see section The config file).

A.6 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 section 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/libexec/gnats' rather than `GNATS_ROOT/gnats-bin' (see section Where GNATS lives).

• Change the default PATH for the gnats user to search the directories `exec-prefix/bin' and `exec-prefix/libexec/gnats'.

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

• Redistribute send-pr to your Submitter Sites (see section 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 versions.