[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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:

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  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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:

    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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

  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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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:


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]