Gnats
 
GNATS > GNATS 4 INSTALLATION

Gnats 4 Installation

(minimum survival edition 0.1)

These are the minimum of steps needed to install the Gnats 4 version from CVS as of mid-March 2001. The procedure is believed to be workable, but needs a bit more proofreading and testing. Please send any corrections or other suggestions to yngve.svendsen@clustra.com.

Prerequisites

If you are installing GNATS on a machine which doesn't have any GNU software installed, you need to begin by getting and installing GNU make. The list of GNU FTP mirror sites is at http://www.gnu.org/order/ftp.html. In order to have the documentation available in Info format (which allows you to read Gnats documentation by way of the 'info' command), you also need to have Texinfo installed.

Configuring and compiling the software

Getting GNATS 4

Get the current development version of GNATS 4 from CVS.

cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/gnats login
{enter "anoncvs" as the password}
cvs -z9 -d :pserver:anoncvs@sources.redhat.com:/cvs/gnats co -P gnats

This creates a 'gnats' subdirectory of the current directory, containing the GNATS 4 source code.

Change Emacs Lisp directory (optional)

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 the next section.

Configure

You can nearly always run configure with the command

./configure

and the "Right Thing" happens:

The last point is worth remembering. If you run multiple databases it is a good practice to always specify the databasename explicitly when invoking GNATS utilities manually, even if you want to operate on the default database.

The most common options for 'configure' are:

configure  [ --prefix=PREFIX ]
  [ --exec-prefix=EXEC-PREFIX ]
  [ --with-gnats-service=SERVICE-NAME ]
  [ --with-gnats-user=USERNAME ]
  [ --with-gnatsd-user-access-file=PATH ]
  [ --with-gnatsd-host-access-file=PATH ]
  [ --with-gnats-dblist-file=PATH ]
  [ --with-gnats-default-db=PATH ]
  [ --with-kerberos ]
  [ --with-krb4 ]

--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'.

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

--with-gnats-service=SERVICE-NAME
Set SERVICE-NAME to be the GNATS network service. Default name is 'support'.

--with-gnats-user=USERNAME
Set the username for GNATS from the passwd file to NAME. Default username is 'gnats'.

--with-gnatsd-user-access-file=PATH
Set global (across all databases) gnatsd access file to PATH. Default is /usr/local/share/gnats/gnatsd.access. Per-database user access permissions are set in a gnatsd.access file in the gnats-adm subdirectory of each database directory.

--with-gnatsd-host-access-file=PATH
Set global (across all databases) gnatsd access file to PATH. Default is /usr/local/share/gnats/gnatsd_host.access. There is currently no way to specify host access permissions on a per-database basis.

--with-gnats-dblist-file=PATH
Specify the file containing the list of databases. Default is /usr/local/etc/gnats/databases.

--with-gnats-default-db=DEFAULT_DB_DIR
Specify the default database directory to use. Default value is /usr/local/com/gnatsdb. Utilities such as send-pr operate on this database when no -d or --databasename is given.

--with-kerberos
Include code for Kerberos authentication. (Currently undocumented)

--with-krb4
Support Kerberos 4 (Currently undocumented)

For a complete list of options supported by configure, run ./configure --help in the source directory. Complete documentation of configure can be found in the 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.

Build

Now, we should be ready to 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'.

Installing the utilities

NOTE: Need to document send-pr.conf. Hasn't it been updated to work with the dbconfig file????

Create the GNATS user

The following steps are necessary for a complete installation. You may need `root' access for these. In the steps below, we assume that you ran the pre-build configure without the --with-gnats-user option, so that you GNATS user is named 'gnats'. If you modified the name, substitute for the name 'gnats' below as appropriate.

Create an account for the user named `gnats'. This user must have an entry in the file `/etc/passwd'. If you did a configure with no options, the home directory for this account could be set to /usr/local/com, i.e. the parent directory of the default database directory. If you modified the default database directory name, it is recommended that you use the parent directory of the database directory as the home directory for the gnats user.

Also, the default `PATH' for this user should contain `EXEC-PREFIX/bin' and `EXEC-PREFIX/libexec/gnats'.

Install the utilities

Install the utilities by invoking

make install install-info

These targets indicate:

install
Installs all programs into their configured locations (*note Where GNATS lives: Locations.).

install-info

Installs `info' files into their configured locations.

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

make clean

Set up Emacs

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' configuration file:

(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.

Setting up the database

For the following steps, log in as the gnats user.

We begin by initializing the default database with the command 'mkdb'. If you ran the pre-build configure with the --with-gnats-default-db option, substitute the path below for the one you specified:

mkdb /usr/local/com/gnatsdb

This creates a database named gnatsdb with data directory as specified. mkdb creates the data directory. Three subdirectories of the data directory are created:

NOTE for upgraders from GNATS 3: In order to make a new category, you now only need to add it to the categories file. Category directories are now created on-the-fly, and the mkcat utility is no longer needed. (NOTE doesn't this create problems for the emacs macros????)

We then set about editing the default database configuration files in /usr/local/com/gnatsdb/gnats-adm.

Begin with the file 'dbconfig', then edit 'categories', 'responsible' and 'submitters' to match your desired config. You may also want to edit 'addresses'. The files 'classes' and 'states' have sensible defaults that should fit most installations.

If you used the --with-gnats-default-db option in the pre-build configure to change the location of the default database, you need to edit the databases config file. By default, this file is `/usr/local/etc/gnats/databases', but this is possible to change by using the --with-gnats-dblist-file option in the pre-build configure. The entry format is described in the file itself.

Set up GNATS cron jobs

To allow the new user `gnats' access to `cron' and `at', 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). These files may not exist either, in which case this step is unnecessary.

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' which contains the following line in the home directory of the user `gnats' :

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

Specify the full path name for `queue-pr' as it is installed on your system. On a system with default configuration, the path would be /usr/local/libexec/gnats/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 added on the machine where the GNATS tools are installed. You may need `root' access to add these aliases. Different mail systems have different ways of setting up mail aliases. The following instructions refer to mail systems such as Sendmail, which specify their mail aliases in the file '/etc/aliases'. Consult the documentation for your particular system if the '/etc/aliases' file doesn't exist.

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

bug-queue: "| EXEC-PREFIX/libexec/gnats/queue-pr -q"
bug-log: GNATS_ROOT/gnats-adm/bugs.log
bugs: bug-queue, 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)

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.

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 service name or port, you could use the following options for the pre-build configure:

--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 according to your configuration. To make `inetd' start spawning the GNATS daemon when connected on that port, send it a hangup signal (`HUP').

At this point, you'll probably want to set the access permissions of different hosts that are going to be working with your GNATS database. The access permissions can currently only be set on a global scale (across all databases on the GNATS server). The location and name of the global host access configuration file can be set during the pre-build configure as shown above, but by default the file is `/usr/local/share/gnatsd_host.access'. It lists the hosts allowed to access your server and their default access level. The format is reserved for future revision; only the first two fields are actually used:

site.com:view:

Access attempts that are denied are logged to the file that logs syslog messages, usually `/var/adm/messages' or `/var/log/messages'


GNATS > GNATS 4 INSTALLATION
 
First published: Saturday, 17-Mar-2001 02:04:10 MET
Last modified: Saturday, 17-Mar-2001 02:04:10 MET
yngve.svendsen@clustra.com