3. Installing GNATS

See also 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.

GNATS installation relies on two other freely available software packages, which should be installed before you go on to configure and build GNATS. These are GNU make and Texinfo (version 4.2 or higher). Both are available from the GNU FTP site at ftp://ftp.gnu.org.

To build and install 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.
• Create an initial database by using the mkdb command. See section Installing the default database.
• Set up periodic jobs, using cron, to handle Problem Reports arriving by mail. See section Setting up periodic jobs.
• Set up mail aliases for GNATS. See section Setting up mail aliases.
• Install the GNATS tools and utilities locally, and install the user tools (query-pr, edit-pr, send-pr) on every machine in your local network. See section Installing the user tools.
• Install the GNATS daemon ‘gnatsd’. See section Installing the daemon.
• If there are people outside your organization who will be submitting PRs or who are supposed to be able to query and/or edit PRs, you may need to instruct them to obtain and build the GNATS tools query-pr, edit-pr and send-pr for their systems. However, for many sites, setting up a remote access interface to GNATS, such as Gnatsweb is a better solution since this requires no configuration on the remote side.

3.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 gunzip gnats-4.2.0.tar.gz tar xvf gnats-4.2.0.tar

   The sources reside in a directory called ‘gnats-4.2.0’ 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-4.2.0/gnats/*’. Lists of files included in the distribution are in each directory in the file ‘MANIFEST’.

2. As of GNATS version 4, having Emacs installed on the GNATS server is no longer a requirement. If you do not have Emacs installed, disregard this step altogether.

   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 file srcdir/gnats/Makefile.in. Change the variable lispdir from ‘prefix/emacs/site-lisp’ to the directory containing your Emacs lisp library. For information on prefix, see prefix.

3. Create an account for the gnats user. You can actually name this user whatever you want to, as long as it is a valid username on your system, but we strongly recommend that you call the user gnats. If you do decide to give it some other name, remember to use the option --enable-gnats-user when running configure below. Below, we will anyway refer to this user by the name gnats.

   This user must have an entry in the file ‘/etc/passwd’. As for ordinary users, create a standard home directory for the gnats user. The default PATH for this user should contain ‘exec-prefix/bin’ and ‘exec-prefix/libexec/gnats’. The exec-prefix value is configurable with the --exec-prefix configure option described below, but for standard installations, these two directories correspond to ‘/usr/local/bin’ and ‘/usr/local/libexec/gnats’.

4. Run configure. You can nearly always run configure with the simple command

   ./configure

   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).
   • all GNATS utilities operate on the default database, assumed to be named default and to be located in ‘/usr/local/com/default’, unless you invoke the utilities with -d databasename or --directory=databasename, or set the GNATSDB environment variable to point to some other database.

   The most common options to configure are listed below:

   configure [ --prefix=prefix ] [ --exec-prefix=exec-prefix ] [ --enable-gnats-service=service-name ] [ --enable-gnats-user=username ] [ --enable-gnatsd-user-access-file=path ] [ --enable-gnatsd-host-access-file=path ] [ --enable-gnats-dblist-file=path ] [ --enable-gnats-default-db=path ] [ --with-kerberos ] [ --with-krb4 ] [ --verbose ]

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

   --enable-gnats-service=service-name

   Set service-name to be the GNATS network service. Default name is support.

   --enable-gnats-user=username

   Set username to be the user name for GNATS. Default username is gnats.

   --enable-gnatsd-user-access-file=path

   Set global (across all databases) gnatsd user access file to path. Default is ‘/usr/local/etc/gnats/gnatsd.user_access’. Per-database user access permissions are set in a ‘gnatsd.user_access’ file in the ‘gnats-adm’ subdirectory of each database.

   --enable-gnatsd-host-access-file=path

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

   --enable-gnats-dblist-file=path

   Specify the file containing the list of databases.

   Default is ‘prefix/etc/gnats/databases’.

   --enable-gnats-default-db=path

   Specify the default database to use when GNATS tools are invoked without the -d or --databasename option, and when the GNATSDB envrionment variable hasn’t been set. Default is ‘/prefix/com/gnatsdb’.

   --with-kerberos

   Include code for Kerberos authentication.

   --with-krb4

   Support Kerberos 4.

   --verbose

   Give verbose output while configure runs.

   configure supports several more options which allow you to specify in great detail where files are installed. For a complete list of options, run ./configure --help in the source directory.

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

5. Make sure you have GNU make, then 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.

3.2 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 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

2. If you do not have Emacs installed on your GNATS server, this step should be skipped.

   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 'send-pr "gnats" "Command to create and send a problem report." t) (autoload 'edit-pr "gnats" "Command to edit a problem report." t) (autoload 'view-pr "gnats" "Command to view a problem report." t) (autoload 'query-pr "gnats" "Command to query information about problem reports." t) (autoload 'unlock-pr "gnats" "Unlock a problem report." t) (autoload 'gnats-dbconfig-mode "gnats" "Major mode for editing the `dbconfig' GNATS configuration file." t) (add-to-list 'auto-mode-alist '("\\<dbconfig$" . gnats-dbconfig-mode))

3. If you want people who are logged into the GNATS server itself to be able to use the send-pr tool to submit problem reports, you need to create a configuration file for send-pr on the server. See section The send-pr.conf configuration file.

3.3 Installing the default database

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

We are now going to initialize the default GNATS database. Run the following command:

mkdb default

This creates a database named default, with all its data stored below the directory ‘prefix/com/gnatsdb’, in a default installation this corresponds to ‘/usr/local/com/gnatsdb’. If you specified the --enable-gnats-default-db option when running configure, the default database will be created under the directory you specified instead. mkdb creates the database directory itself, together with three different subdirectories(2):

• A directory for the mandatory GNATS category pending.
• A ‘gnats-queue’ directory for queueing new messages to GNATS before they are processed by file-pr.
• The administrative directory ‘gnats-adm’. This directory is populated with default configuration files from the ‘prefix/etc/gnats/defaults’ directory.

The next configuration step is to edit the default files copied to the database’s ‘gnats-adm’ directory by mkdb.

The default ‘dbconfig’ file installed by mkdb provides a good basis for many GNATS databases. The default file causes similar behaviour to the 3.x versions of GNATS. However, even if this might be precisely what you want, you should still go through the file and check that the default settings suit your needs. See section The ‘dbconfig’ file.

Then edit the files ‘categories’, ‘responsible’, and ‘submitters’ in the ‘gnats-adm’ directory (see section Other database-specific config files) to reflect your local needs. For special configurations, you may also have to edit the ‘states’ and ‘classes’ files.

If you used the --enable-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, see The ‘databases file’. This file is by default located in the ‘prefix/etc/gnats’ directory, but may have been changed by the option --enable-gnats-dblist-file option during configure.

3.4 Setting up periodic jobs

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). If you changed the name of the GNATS user during configure, remember to substitute as appropriate in the previous steps.

Create a crontab entry that periodically runs the program queue-pr with the ‘--run’ option (see section queue-pr). 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.

3.5 Setting up mail aliases

The following mail aliases must be added on the machine where the GNATS server is installed. The instructions below are for Sendmail or Sendmail-like mail systems. If these instructions don’t fit your system, particularly if you do not have an ‘aliases’ file, ask your mail administrator for advice.

The following aliases should be placed in the file ‘/etc/aliases’. Yoy 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 the ‘gnats-queue’ directory of your database. Remember to fill in the full path of the queue-pr command as appropriate for your installation.

• 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: /some/path/bugs.log bugs: bug-q, bug-log

  This configuration archives incoming Problem Reports in the file ‘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.) In order for the log file to protect fully against data loss in case a disk runs full, try to place it on a different disk volume than the GNATS database.

• 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).

3.6 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, configure GNATS with

--enable-gnats-service=servicename

In your ‘inetd.conf’ file, add the line

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

adjusting the path accordingly if you used configure options to make changes to the defaults. To make inetd start spawning the GNATS daemon when connected on that port, send it a hangup signal (HUP).

Some operating systems have replaced inetd with the more modern xinetd. Instead of editing ‘inetd.conf’, you should create the file ‘/etc/xinetd.d/support’, containing something like the following:

service support
{
   disable = no
   socket_type = stream
   protocol = tcp
   wait = no
   user = gnats
   server = /usr/local/libexec/gnats/gnatsd
}

If you specified a different service name when running configure, you need to give the file the same name as the service name, and you need to adjust the service line above. If the --prefix or --exec-prefix options were passed to configure, adjust the server line above, and if you used the --enable-gnats-user option, adjust the user line.

Then restart xinetd to make the new configuration current.

If you use an Internet superserver different from inetd or xinetd, please refer to its documentation for information how to configure it.

At this point, you will probably want to set the access permissions of the different hosts that are going to be accessing your databases. The access permissions can currently only be set on a global scale (that is, across all the databases on a 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/etc/gnats/gnatsd_host.access’. It lists the hosts allowed to access your server, and what their default access levels are. Each line in the file denotes one server, or one part of a network domain. There are three fields on each line, but only two are currently used. To grant all hosts from the domain site.com edit access, use this line:

site.com:edit

If you run a GNATS web interface or similar tool on the same machine as the server is running on, you probably want to grant localhost edit access:

localhost:edit

If you are using Kerberos, the ‘gnatsd_host.access’ file shows the sites that don’t require Kerberos authentication.

The third field might in the future be used for things like controlling what categories, submitter-id’s PRs, etc., can be accessed from that site. Access attempts that are denied are logged to the syslog messages file (‘/var/adm/messages’ on many systems).

3.7 Installing the user tools

When you install the GNATS utilities, the user tools send-pr, query-pr and edit-pr are installed on the server 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. In the following discussion, machines with the GNATS user tools installed are referred to as client machines. In general, there are three distinct types of client that a GNATS server may have to cater for:

• - Machines that are on the same local network as the GNATS server, i.e. machines that are under the same administrative control.
• - Machines on the general, open Internet.
• - Machines behind firewalls etc. which deny direct access over the network to the GNATS server.

Each type of client requires a different approach when it comes to providing access.

3.7.1 User tools on a local network

If all the machines involved reside on the same local network as the GNATS server, you can simply share out the directories on the server that contain the user tools, by default ‘/usr/local/bin’ and the directory which contains the ‘send-pr.conf’ configuration file (see section The send-pr.conf configuration file), by default ‘/usr/local/etc/gnats’. If you have a heterogeneous environment, i.e. hosts running different operating systems, you need to create several shared GNATS installations, one for each platform. The ‘send-pr.conf’ file is platform-independent, though.

In order to submit a new PR, send-pr would then be invoked as follows on the client machines:

send-pr -d hostname:port:database:username:password

Or by first setting the environment variable GNATSDB as follows (the exact syntax will vary depending on what shell you use):

export GNATSDB=hostname:port:database:username:password

Then, send-pr can simply be invoked without any options.

The other tools, query-pr and edit-pr, work in similar ways, honoring the -d option as well as the GNATSDB environment variable. See section The GNATS User Tools.

3.7.2 User tools for remote users

When client machines reside on the general Internet, both security and practical considerations may make it impossible to provide a shared installation of the GNATS tools. In this case, you may choose to only provide access through a web interface such as Gnatsweb. For clients that need the GNATS tools, the following needs to be carried out on the remote machines:

1. Configure and build GNATS on the client machine
2. Configure send-pr on the client machine

You should unpack the distribution and run configure on the client machine in the same way as described in Configuring and compiling the software. Note, however, that you do not need to create a gnats user on the client and you should not use the make all info command to build. Instead, issue the following commands from the top level directory of the source distribution:

cd gnats
make install-tools
cd ../send-pr
make all install

This builds and installs the send-pr, query-pr and edit-pr tools on the client machine. You should now configure send-pr by editing the ‘send-pr.conf’ file (see section The send-pr.conf configuration file.)

Users on the client machine can now either use the send-pr syntax or the GNATSDBenvironment variable described in the previous section.

For sites that need to submit Problem Reports by having send-pr send e-mail instead of speaking directly over the network to the GNATS server, you need to create a problem report template on the GNATS server and have that template copied to a suitable location on the client machine (any filename and any location will do, as long as send-pr on the client machine can read the file). On the GNATS server, use the command

send-pr -p > ‘filename’

The file ‘filename’ now contains a PR template for your database. Copy this file to the client. Then edit the ‘send-pr.conf’ file that you created on the client, set the TEMPLATE variable to point to the template file (see section The send-pr.conf configuration file) and make sure that the MAILPROG and MAILADDR varables in ‘send-pr.conf’ are correctly set. You should now have a working remote tool installation.

For clients that have no direct network access to your GNATS server, such as those that are located behind strict firewalls, you either need to set up a web interface such as Gnatsweb (provided that the firewall lets web traffic through) or use the procedure above which sets up send-pr to submit Problem Reports by e-mail. In order to query PRs, users on the remote machines will then have to use the the e-mail functionality of query-pr (see section Invoking query-pr. Editing PRs by e-mail is not possible, so clients in this group who need edit access have to get access through a web interface if possible.

Note that when send-pr is set up to work over e-mail, the GNATSDB environment variable and the -d command line option have no effect since send-pr is tied to a specific database by way of the value of MAILADDR in the ‘send-pr.conf’ file.

3.8 Upgrading from older versions

The following procedure covers an upgrade from all GNATS 3 versions newer than 3.108. If your installation is an older 3.10x version, or even the ancient 3.2 version, you need to review the ‘UPGRADING.old’ file in the GNATS distribution before carrying out the steps detailed here.

3.8.1 Overview

Although almost all of the GNATS internals have been redesigned and rewritten for GNATS 4, little has changed in the format and structure of the database data. The only change that needs to be taken into account when upgrading is the fact that the database index format is binary in a default installation of GNATS 4. Thus, you will need to regenerate your database index by using the gen-index tool. In addition, if your old GNATS installation was so-called “release-based”, you need to make some simple modifications to the database setup file ‘dbconfig’. See below for details.

Apart from building and installing new binaries, the major changes which impinge on the upgrade procedure are all on the configuration side. The main database configuration file, ‘dbconfig’, is far more complex and powerful than the old ‘config’ file, and while the installation process creates a sensible set of default values which are similar to GNATS 3.11x’s defaults, you still need to migrate any changes you may have made to your own local configuration.

Another aspect which needs consideration are remote submitter sites. Such sites either need to be instructed to upgrade their locally installed copies of the GNATS user tools (send-pr, edit-pr and query-pr), or they should be given access through interfaces such as Gnatsweb.

Since the GNATS network daemon has been completely reworked, with an entirely new command set, all network-based interfaces, such as Gnatsweb and TkGnats need to be upgraded to versions that support GNATS 4. The ‘contrib’ directory of this distribution contains some third-party interfaces, and the ‘README’ file contains pointers to where you can obtain the newest versions of these tools.

This document only deals with upgrading GNATS itself. Third-party tools should have separate upgrading instructions in their distributions.

3.8.2 Upgrading

1. Before you begin, make a backup of your entire GNATS database directory hierarchy, the GNATS executables directory and the GNATS user tools (send-pr, query-pr etc.) The locations of these may vary, but in a default GNATS 3 installation, the database(s) reside under ‘/usr/local/share/gnats’, the executables are located in ‘/usr/local/libexec/gnats’ and the user tools reside in ‘/usr/local/bin’.
2. (optional) In order to avoid confusing your users, you may want to remove the old GNATS 3 executables and tools, escpecially if you plan to install GNATS 4 in a different location than version 3.
3. Build and install GNATS 4. See section Installing GNATS. It is recommended that you use the --enable-gnats-default-db option when running configure, in order to set the default database to be one of your already existing GNATS 3 databases.
4. Edit the GNATS ‘databases’ file and add entries for all your old GNATS 3 databases. In a default GNATS 4 installation the file is in ‘/usr/local/etc/gnats’. See section The ‘databases’ file.
5. In GNATS 3, the file ‘gnatsd.conf’ specifies minimum access levels for the different hosts accessing the GNATS daemon, gnatsd. There is one ‘gnatsd.conf’ for each database. In GNATS 4, these files have been replaced by a single file named ‘gnatsd.host_access’ which contains settings that apply across all the databases on the server. This file is located in the same directory as the ‘databases’ file. You need to combine the host access settings from all your GNATS 3 databases and add them to the ‘gnatsd.host_access’ file. Note that you are no longer able to control host access on a per-database basis. Optionally, you may delete the old ‘gnatsd.conf’ files. See section Controlling access to GNATS databases.
6. Next, you need to migrate the settings in the old ‘config’ files of your databases to corresponding ‘dbconfig’ files. The database you specified with the --enable-gnats-default-db configure option got a default ‘dbconfig’ installed. This default file contains field definitions etc. which makes this version of GNATS behave almost exactly like older versions. Copy this default file to the ‘gnats-adm’ directories of any other GNATS databases that you may have on your host before you proceed to migrate your old configuration settings.

   The following is a list of the configuration directives that may be present in a ‘config’ file and their counterparts (if any) in GNATS 4.

   GNATS_ADDR

   This setting has no counterpart in GNATS 4, since GNATS no longer needs to know its own mail address.

   GNATS_ADMIN

   This setting is now set in the ‘responsible’ file in the ‘gnats-adm’ directory of your database(s).

   GNATS_SITE

   GNATS 4 has no concept of a named ‘site’, so this directive is obsolete.

   SUBMITTER

   Obsolete, since it relates to GNATS_SITE.

   DEFAULT_RELEASE

   DEFAULT_ORGANIZATION

   The GNATS 4 ‘dbconfig’ file has separate configuration sections for each defined field. Field defaults are set with the default keyword in these sections. See section The ‘dbconfig’ file.

   NOTIFY

   Controlled by the notify-about-expired-prs setting in the ‘dbconfig’ file.

   ACKNOWLEDGE

   Controlled by the send-submitter-ack setting in the ‘dbconfig’ file.

   DEFAULT_SUBMITTER

   The default submitter is now always the first entry in the ‘submitters’ file of your database.

   KEEP_RECEIVED_HEADERS

   Controlled by the keep-all-received-headers setting in the ‘dbconfig’ file.

   DEBUG_MODE

   Controlled by the debug-mode setting in the ‘dbconfig’ file.

   BDAY_START

   BDAY_END

   BWEEK_START

   BWEEK_END

   Controlled by the settings business-day-hours and business-week-days in the ‘dbconfig’ file.

   DEFINE_CATEGORY

   The default category for PRs that arrive without one is now the first category listed in the ‘categories’ file of your database.

   After your are done migrating the settings, you may optionally delete the old ‘config’ files. Since there are many more configuration settings available in the GNATS 4 ‘dbconfig’ file, you should take some time to review them all before proceeding. See section The ‘dbconfig’ file.

   If your old GNATS installations was release-based, i.e. it included the fields Quarter, Keywords and Date-Required, you need to define those fields in the ‘dbconfig’ file by following the instructions in Supporting old GNATS “release-based” fields.

7. The file ‘gnatsd.access’ has been renamed to ‘gnatsd.user_access’. Furthermore, GNATS 4 uses a different password format in the ‘gnatsd.user_access’ file than older versions, since it supports crypt() and MD5 passwords (see section Controlling access to GNATS databases). You need to translate your old ‘gnatsd.user_access’ files to the new format by using the gnats-pwconv tool which was installed in the ‘EXEC-PREFIX/libexec/gnats’ directory, typically ‘/usr/local/libexec/gnats’. See section Managing user passwords.
8. The final step involves regenerating the indexes of your databases. For this, log in as the user gnats. Then run the gen-index command for each of your databases. See Administrative Utilities for details on how to use gen-index.
9. Sit back and enjoy your new GNATS 4 setup...

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.