GNATS > GNATS 4 INSTALLATION |
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.
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.
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.
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.
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.
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'.
NOTE: Need to document send-pr.conf. Hasn't it been updated to work with the dbconfig file????
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 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
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.
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.
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'.
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.
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 |