@c This file is included as a chapter in gnats.texi.

@cindex installing GNATS
@cindex configuring  GNATS
@cindex setting up GNATS
@cindex building GNATS

See also @ref{Locations,,Where the tools and utilities reside}.

There are several steps you need to follow to fully configure and
install @sc{gnats} on your system.  You need @code{root} access in order
to create a new account for @code{gnats} and to install the @sc{gnats}
utilities.  You may need @code{root} access on some systems in order to
set up mail aliases and to allow this new account access to
@code{cron} and @code{at}.

If you are updating an older version of @sc{gnats} rather than installing
from scratch, see @ref{Upgrading,,Upgrading from older versions}.

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

To build and install @sc{gnats}, you must:

@itemize @bullet
@item
Run @code{configure}, with correct options if the defaults are
unsuitable for your site.  @xref{Configure and make,,Configuring and
compiling the software}.  Default installation locations are in
@ref{Locations,,Where @sc{gnats} lives}.

@item
Compile the @sc{gnats} programs on your system.  @xref{Configure and
make,,Configuring and compiling the software}.

@item
Create an initial database by using the @code{mkdb} command.
@xref{Setting up the default database}.

@item
Set up periodic jobs, using cron, to handle Problem Reports arriving by
mail.  @xref{Setting up periodic jobs}.

@item
Set up mail aliases for @sc{gnats}.  @xref{Aliases,,Setting up mail
aliases}.

@item
Install the @sc{gnats} tools and utilities locally, and install the user
tools (@code{query-pr}, @code{edit-pr}, @code{send-pr}) on every machine
in your local network.  @xref{Installing tools,,Installing the
user tools}.

@item
Install the @sc{gnats} daemon @file{gnatsd}.  @xref{Installing the
daemon}.

@item
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 @sc{gnats} tools
@code{query-pr}, @code{edit-pr} and @code{send-pr} for their systems.
However, for many sites, setting up a remote access interface to
@sc{gnats}, such as Gnatsweb is a better solution since this requires
no configuration on the remote side.
@end itemize

@menu
* Configure and make::               Configuring and compiling the software
* Installing utils::                 Installing the utilities
* Setting up the default database::  Setting up the default database
* Setting up periodic jobs::         Setting up periodic jobs
* Aliases::                          Setting up mail aliases
* Installing the daemon::            Installing the daemon
* Installing tools::                 Installing the user tools
* Upgrading::                        Upgrading from older versions
@end menu

@node Configure and make
@section Configuring and compiling the software
@cindex unpacking the distribution
@cindex configuring and compiling the software
@cindex compiling the software
@cindex @code{configure}
@cindex @code{make}

@enumerate 1
@item
First, unpack your distribution.  We provide source code in a @code{tar}
file which was compressed using @code{gzip}.  The code can be extracted
into a directory @var{unpackdir} using

@smallexample
cd @var{unpackdir}
gunzip gnats-@value{VERSION}.tar.gz
tar xvf gnats-@value{VERSION}.tar
@end smallexample

The sources reside in a directory called @file{gnats-@value{VERSION}}
when unpacked.  We call this the @dfn{top level} of the source
directory, or @dfn{srcdir}.  The sources for the @sc{gnats} tools are in
the subdirectory @file{gnats-@value{VERSION}/gnats/*}.  Lists of files
included in the distribution are in each directory in the file
@file{MANIFEST}.

@cindex lisp file installation
@cindex Emacs lisp file installation
@item
As of @sc{gnats} version 4, having Emacs installed on the @sc{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
@w{@file{@var{prefix}/share/emacs/site-lisp}}, edit the file
@code{@var{srcdir}/gnats/Makefile.in}.  Change the variable
@code{lispdir} from @w{@file{@var{prefix}/emacs/site-lisp}} to the
directory containing your Emacs lisp library.  For information on
@var{prefix}, see @ref{prefix,,@var{prefix}}.

@item
@cindex creating an account for the @sc{gnats} user
Create an account for the @code{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 @code{gnats}.
If you do decide to give it some other name, remember to use the option
@code{--with-gnats-user} when running @code{configure} below.  Below, we
will anyway refer to this user by the name @code{gnats}.

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

@item
Run @code{configure}.  You can nearly always run @code{configure} with
the simple command

@example
./configure
@end example

@noindent
and the ``Right Thing'' happens:

@itemize @bullet
@item
@sc{gnats} is configured in the same directory you unpacked it in;

@item
when built, @sc{gnats} runs on the machine you're building it on;

@item
when installed, files are installed under @file{/usr/local}
(@pxref{Locations,,Where @sc{gnats} lives}).

@item
all @sc{gnats} utilities operate on the @dfn{default database}, assumed
to be named @emph{default} and to be located in
@w{@file{/usr/local/com/default}}, unless you invoke the utilities with
@code{-d} @var{databasename} or @code{--directory=}@var{databasename}, or
set the @var{GNATSDB} environment variable to point to some other database.
@end itemize

@cindex @code{configure}
The most common options to @code{configure} are listed below:

@smallexample
configure [ --prefix=@var{prefix} ]
          [ --exec-prefix=@var{exec-prefix} ]
          [ --with-gnats-service=@w{@var{service-name}} ]
          [ --with-gnats-user=@w{@var{username}} ]
          [ --with-gnatsd-user-access-file=@w{@var{path}} ]
          [ --with-gnatsd-host-access-file=@w{@var{path}} ]
          [ --with-gnats-dblist-file=@w{@var{path}} ]
          [ --with-gnats-default-db=@w{@var{path}} ]
          [ --with-kerberos ] [ --with-krb4 ]
          [ --verbose ]
@end smallexample

@table @code
@cindex @var{prefix}
@item --prefix=@var{prefix}
All host-independent programs and files are to be installed under
@var{prefix}.  (Host-dependent programs and files are also installed in
@var{prefix} by default.)  The default for @var{prefix} is
@w{@file{/usr/local}}.  @xref{Locations,,Where @sc{gnats} lives}.

@cindex @var{exec-prefix}
@item --exec-prefix=@var{exec-prefix}
All host-dependent programs and files are to be installed under
@var{exec-prefix}.  The default for @var{exec-prefix} is @var{prefix}.
@xref{Locations,,Where @sc{gnats} lives}.

@cindex --with-gnats-service
@item --with-gnats-service=@w{@var{service-name}}
Set @var{service-name} to be the @sc{gnats} network service.  Default
name is @var{support}.

@cindex --with-gnats-user
@item --with-gnats-user=@w{@var{username}}
Set @var{username} to be the user name for @sc{gnats}.  Default username
is @var{gnats}.

@cindex --with-gnatsd-user-access-file
@item --with-gnatsd-user-access-file=@w{@var{path}}
Set global (across all databases) gnatsd user access file to
@var{path}. Default is
@file{@var{/usr/local/etc/gnats/gnatsd.user_access}}.  Per-database
user access permissions are set in a @file{gnatsd.user_access} file in
the @file{gnats-adm} subdirectory of each database.

@cindex --with-gnatsd-host-access-file
@item --with-gnatsd-host-access-file=@w{@var{path}}
Set global (across all databases) gnatsd host access file to
@var{path}. Default is
@file{/usr/local/etc/gnats/gnatsd_host.access}.  There is currently
no way to specify host access permissions on a per-database basis.

@cindex --with-gnats-dblist-file
@item --with-gnats-dblist-file=@w{@var{path}}
Specify the file containing the list of databases.

Default is @w{@file{@var{prefix}/etc/gnats/databases}}.

@cindex --with-gnats-default-db
@item --with-gnats-default-db=@w{@var{path}}
Specify the default database to use when @sc{gnats} tools are invoked
without the @code{-d} or @code{--databasename} option, and when the
@var{GNATSDB} envrionment variable hasn't been set. Default is
@file{/@var{prefix}/com/gnatsdb}.

@cindex --with-kerberos
@item --with-kerberos
Include code for Kerberos authentication.

@cindex --with-krb4
@item --with-krb4
Support Kerberos 4.

@item --verbose
Give verbose output while @code{configure} runs.
@end table

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

@cindex building in a different directory
@cindex @var{objdir}
You can build @sc{gnats} in a different directory (@var{objdir}) from the
source code by calling the @code{configure} program from the new
directory, as in

@smallexample
mkdir @var{objdir}
cd @var{objdir}
@var{srcdir}/configure @dots{}
@end smallexample

By default, @code{make} compiles the programs in the same directory
as the sources (@var{srcdir}).

@item
Make sure you have @sc{gnu} @code{make}, then run 

@smallexample
make all info
@end smallexample

@noindent
from the directory where @code{configure} created a @file{Makefile}
(this is @var{objdir} if you used it, otherwise @var{srcdir}.)  These
targets indicate:

@table @code
@item all
Compile all programs

@item info
Create @samp{info} files using @code{makeinfo}.
@end table
@end enumerate

@node Installing utils
@section Installing the utilities
@cindex installing the utilities

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

@enumerate 1
@item
Install the utilities by invoking

@smallexample
make install install-info
@end smallexample

These targets indicate:

@table @code
@item install
Installs all programs into their configured locations
(@pxref{Locations,,Where @sc{gnats} lives}).

@item install-info
Installs @samp{info} files into their configured locations
(@pxref{Locations,,Where @sc{gnats} lives}).
@end table

After you have installed @sc{gnats}, you can remove the object files with

@smallexample
make clean
@end smallexample

@cindex @code{autoload} commands
@cindex loading @code{.el} files
@cindex Emacs functions
@item
If you do not have Emacs installed on your @sc{gnats} server, this step
should be skipped.

Place the following lines in the file @file{default.el} in your Emacs
lisp library, or instruct your local responsible parties to place the
lines in their @file{.emacs}:

@smallexample
(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))  
@end smallexample

@cindex prepare @file{send-pr.conf}
@item
If you want people who are logged into the @sc{gnats} server itself to
be able to use the @code{send-pr} tool to submit problem reports, you
need to create a configuration file for @code{send-pr} on the server.
@xref{send-pr.conf file,,The send-pr.conf configuration file}.

@end enumerate

@node Setting up the default database
@section Installing the default database

For the following steps, log in as the user @code{gnats}.

We are now going to initialize the default @sc{gnats} database.  Run the
following command:

@example
mkdb default
@end example

This creates a database named @code{default}, with all its data stored
below the directory @w{@file{@var{prefix}/com/gnatsdb}}, in a default
installation this corresponds to @w{@file{/usr/local/com/gnatsdb}}.  If
you specified the @code{--with-gnats-default-db} option when running
configure, the default database will be created under the directory you
specified instead.  @code{mkdb} creates the database directory itself,
together with three different subdirectories@footnote{Upgraders from
older versions of @sc{gnats} should note that category directories are
now created ``on-the-fly'' as needed by default.}:

@itemize @bullet
@item A directory for the mandatory @sc{gnats} category @var{pending}.

@item A @file{gnats-queue} directory for queueing new messages to
@sc{gnats} before they are processed by @code{file-pr}.

@item The administrative directory @file{gnats-adm}. This directory is
populated with default configuration files from the
@w{@file{@var{prefix}/etc/gnats/defaults}} directory.
@end itemize

The next configuration step is to edit the default files copied to the
database's @file{gnats-adm} directory by @code{mkdb}.

The default @file{dbconfig} file installed by @code{mkdb} provides a
good basis for many @sc{gnats} databases. The default file causes
similar behaviour to the 3.x versions of @sc{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.
@xref{dbconfig file,,The @file{dbconfig} file}.

Then edit the files @file{categories}, @file{responsible}, and
@file{submitters} in the @w{@file{gnats-adm}} directory (@pxref{Other
config files,,Other database-specific config files}) to reflect your
local needs.  For special configurations, you may also have to edit the
@file{states} and @file{classes} files.

If you used the @code{--with-gnats-default-db} option in the pre-build
configure to change the location of the default database, you need to
edit the @file{databases} config file, see @ref{databases file,,The
@file{databases file}}.  This file is by default located in the
@w{@file{@var{prefix}/etc/gnats}} directory, but may have been changed
by the option @code{--with-gnats-dblist-file} option during configure.

@cindex @code{cron}
@cindex @code{at}
@node Setting up periodic jobs
@section Setting up periodic jobs

Allow the new user @code{gnats} access to @code{cron} and @code{at}.  To
do this, add the name @code{gnats} to the files @w{@file{cron.allow}} and
@w{@file{at.allow}}, which normally reside in the directory
@w{@file{/var/spool/cron}}.  If these files do not exist, make sure
@code{gnats} does not appear in either of the files @w{@file{cron.deny}}
and @w{@file{at.deny}} (in the same directory).  If you changed the name
of the @sc{gnats} user during configure, remember to substitute as
appropriate in the previous steps.

@cindex @code{crontab}
Create a @code{crontab} entry that periodically runs the program
@code{queue-pr} with the @samp{--run} option
(@pxref{queue-pr,,@code{queue-pr}}).  For example, to run
@w{@samp{queue-pr --run}} every ten minutes, create a file called
@file{.mycron} in the home directory of the user @code{gnats} which
contains the line:

@smallexample
0,10,20,30,40,50 * * * * @var{exec-prefix}/libexec/gnats/queue-pr --run
@end smallexample

@noindent
(Specify the full path name for @code{queue-pr}.)  Then run

@smallexample
crontab .mycron
@end smallexample

@noindent
See the @code{man} pages for @code{cron} and @code{crontab} for details
on using @code{cron}.

@node Aliases
@section Setting up mail aliases
@cindex mail aliases
@cindex aliases

The following mail aliases must be added on the machine where the
@sc{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 @file{aliases} file, ask your
mail administrator for advice.

The following aliases should be placed in the file
@w{@file{/etc/aliases}}. Yoy may need @code{root} access to add these
aliases:

@itemize @bullet
@item
@cindex @code{gnats-admin} alias
Create an alias for the @sc{gnats} administrator.  This address should
point to the address of the person in charge of administrating
@sc{gnats}:

@smallexample
gnats-admin:  @var{address}
@end smallexample

@item
@cindex bug alias
@cindex incoming alias for Problem Reports
@cindex alias for incoming Problem Reports
@cindex @code{queue-pr -q}
Create an alias to redirect incoming Problem Reports.  This alias should
redirect incoming mail via a @dfn{pipe} to the program @w{@samp{queue-pr
-q}}.  For example, if Problem Reports coming to your site are to arrive
at the address @samp{bugs@@your.company.com}, create an alias to the
effect of:

@smallexample
bugs:  "| @var{exec-prefix}/libexec/gnats/queue-pr -q"
@end smallexample

@noindent
This places incoming Problem Reports in
the @w{@file{@var{gnats-queue}}} directory of your database.  Remember to
fill in the full path of the @code{queue-pr} command as appropriate for
your installation.

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

@smallexample
bug-q: "| @var{exec-prefix}/libexec/gnats/queue-pr -q"
bug-log:  /some/path/bugs.log
bugs:      bug-q, bug-log
@end smallexample

@noindent
This configuration archives incoming Problem Reports in the file
@w{@file{bug.log}}, and also feeds them to the program @code{queue-pr}.
(Remember, @file{bug.log} needs to be world-writable, and should be
pruned regularly; @pxref{Management,, @sc{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
@sc{gnats} database.

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

@smallexample
query-pr: "| @var{exec-prefix}/libexec/gnats/mail-query"
@end smallexample

@noindent
The @code{mail-query} program uses @samp{--restricted} to search on the
database, and by default only searches for PRs that aren't closed
(@pxref{query-pr,,Querying the database}).

@end itemize

@c ---------------------------------------------------------------
@node Installing the daemon
@section Installing the daemon
@cindex daemon
@cindex using @sc{gnats} over a network

By default, the daemon and clients are set to use port 1529.  Add the line

@smallexample
support		1529/tcp			# GNATS
@end smallexample

@noindent
to your @file{/etc/services} file.  If you want a different service
name, configure @sc{gnats} with

@smallexample
--with-gnats-service=@var{servicename}
@end smallexample

In your @file{inetd.conf} file, add the line

@smallexample
support	stream	tcp	nowait	gnats	/usr/local/libexec/gnats/gnatsd gnatsd
@end smallexample

@noindent
adjusting the path accordingly if you used configure options to make
changes to the defaults.  To make @command{inetd} start spawning the
@sc{gnats} daemon when connected on that port, send it a hangup signal
(@code{HUP}).

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

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

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

Then restart @command{xinetd} to make the new configuration current.

If you use an Internet superserver different from @command{inetd} or
@command{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 @sc{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
@w{@file{/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 @var{site.com} edit access,
use this line:

@var{site.com}:@var{edit}

@noindent
If you run a @sc{gnats} web interface or similar tool on the same
machine as the server is running on, you probably want to grant
@var{localhost} edit access:

@var{localhost}:@var{edit}

If you are using Kerberos, the @file{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 (@file{/var/adm/messages} on many systems).


@c ---------------------------------------------------------------
@node Installing tools
@section Installing the user tools
@cindex networks
@cindex using @sc{gnats} over a network
@cindex configuring @sc{gnats} on a network

When you install the @sc{gnats} utilities, the user tools
@code{send-pr}, @code{query-pr} and @code{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 @sc{gnats} user tools installed are referred to as
@dfn{client} machines.  In general, there are three distinct types of
client that a @sc{gnats} server may have to cater for:

@itemize @minus
@item Machines that are on the same local network as the
@sc{gnats} server, i.e. machines that are under the same
administrative control.

@item Machines on the general, open Internet.

@item Machines behind firewalls etc. which deny direct access
over the network to the @sc{gnats} server.
@end itemize

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

@subsection User tools on a local network
@cindex using @sc{gnats} over a local network
@cindex configuring @sc{gnats} on a local network

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

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

@smallexample
send-pr -d @var{hostname:port:database:username:password}
@end smallexample

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

@smallexample
export GNATSDB=@var{hostname:port:database:username:password}
@end smallexample

Then, @code{send-pr} can simply be invoked without any options.

The other tools, @code{query-pr} and @code{edit-pr}, work in similar
ways, honoring the @code{-d} option as well as the @code{GNATSDB}
environment variable.  @xref{GNATS user tools}.

@subsection User tools for remote users
@cindex using @sc{gnats} remotely
@cindex configuring @sc{gnats} 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 @sc{gnats} tools.  In this case, you may choose to
only provide access through a web interface such as Gnatsweb.  For
clients that need the @sc{gnats} tools, the following needs to be
carried out on the remote machines:

@enumerate 
@item Configure and build @sc{gnats} on the client machine

@item Configure @code{send-pr} on the client machine
@end enumerate

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

@smallexample
cd gnats
make install-tools
cd ../send-pr
make all install
@end smallexample

This builds and installs the @code{send-pr}, @code{query-pr} and
@code{edit-pr} tools on the client machine.  You should now configure
@code{send-pr} by editing the @file{send-pr.conf} file
(@pxref{send-pr.conf file,,The send-pr.conf configuration file}.)

Users on the client machine can now either use the send-pr syntax or the
@code{GNATSDB}environment 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 @sc{gnats}
server, you need to create a problem report template on the @sc{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
@code{send-pr} on the client machine can read the file).  On the
@sc{gnats} server, use the command

@smallexample
send-pr -p > @file{filename}
@end smallexample

The file @file{filename} now contains a PR template for your database.
Copy this file to the client.  Then edit the @file{send-pr.conf} file
that you created on the client, set the @code{TEMPLATE} variable to
point to the template file (@pxref{send-pr.conf file,,The send-pr.conf
configuration file}) and make sure that the @code{MAILPROG} and
@code{MAILADDR} varables in @file{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 @sc{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 @code{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 @code{query-pr} (@pxref{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 @code{send-pr} is set up to work over e-mail, the
@code{GNATSDB} environment variable and the @code{-d} command line
option have no effect since @code{send-pr} is tied to a specific
database by way of the value of @code{MAILADDR} in the
@file{send-pr.conf} file.

@c ---------------------------------------------------------------
@node Upgrading
@section Upgrading from older versions
@cindex upgrading from older versions

The following procedure covers an upgrade from all @sc{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
@file{UPGRADING.old} file in the @sc{gnats} distribution before carrying
out the steps detailed here.

@subsection Overview
@cindex upgrading, overview

Although almost all of the @sc{gnats} internals have been redesigned and
rewritten for @sc{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 @sc{gnats} 4.  Thus, you will
need to regenerate your database index by using the @code{gen-index}
tool.  In addition, if your old @sc{gnats} installation was so-called
``release-based'', you need to make some simple modifications to the
database setup file @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, @file{dbconfig}, is far more complex
and powerful than the old @file{config} file, and while the installation
process creates a sensible set of default values which are similar to
@sc{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 @sc{gnats} user tools (@code{send-pr},
@code{edit-pr} and @code{query-pr}), or they should be given access
through interfaces such as Gnatsweb.

Since the @sc{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
@sc{gnats} 4.  The @file{contrib} directory of this distribution
contains some third-party interfaces, and the @file{README} file
contains pointers to where you can obtain the newest versions of these
tools.

This document only deals with upgrading @sc{gnats} itself.  Third-party
tools should have separate upgrading instructions in their
distributions.

@subsection Upgrading
@cindex upgrade, procedure

@enumerate
@item
Before you begin, make a backup of your entire @sc{gnats} database
directory hierarchy, the @sc{gnats} executables directory and the
@sc{gnats} user tools (@code{send-pr}, @code{query-pr} etc.)  The
locations of these may vary, but in a default @sc{gnats} 3 installation,
the database(s) reside under @w{@file{/usr/local/share/gnats}}, the
executables are located in @w{@file{/usr/local/libexec/gnats}} and the
user tools reside in @w{@file{/usr/local/bin}}.

@item
(optional) In order to avoid confusing your users, you may want to
remove the old @sc{gnats} 3 executables and tools, escpecially if you
plan to install @sc{gnats} 4 in a different location than version 3.

@item
Build and install @sc{gnats} 4.  @xref{Installation,, Installing
@sc{gnats}}.  It is recommended that you use the
@w{@code{--with-gnats-default-db}} option when running @code{configure},
in order to set the default database to be one of your already existing
@sc{gnats} 3 databases.

@item
Edit the @sc{gnats} @file{databases} file and add entries for all your
old @sc{gnats} 3 databases.  In a default @sc{gnats} 4 installation
the file is in @w{@file{/usr/local/etc/gnats}}.  @xref{databases
file,,The @file{databases} file}.

@item
In @sc{gnats} 3, the file @file{gnatsd.conf} specifies minimum access
levels for the different hosts accessing the @sc{gnats} daemon,
@code{gnatsd}.  There is one @file{gnatsd.conf} for each database.  In
@sc{gnats} 4, these files have been replaced by a single file named
@file{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 @file{databases} file.  You need to combine the host access
settings from all your @sc{gnats} 3 databases and add them to the
@file{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 @file{gnatsd.conf} files.  @xref{Access Control,,Controlling
access to @sc{gnats} databases}.

@item
Next, you need to migrate the settings in the old @file{config} files of
your databases to corresponding @file{dbconfig} files.  The database you
specified with the @w{@code{--with-gnats-default-db}} configure option
got a default @file{dbconfig} installed.  This default file contains
field definitions etc. which makes this version of @sc{gnats} behave
almost exactly like older versions.  Copy this default file to the
@w{@file{gnats-adm}} directories of any other @sc{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 @file{config} file and their counterparts (if any) in
@sc{gnats} 4.

@table @var
@item GNATS_ADDR
This setting has no counterpart in @sc{gnats} 4, since @sc{gnats} no
longer needs to know its own mail address.

@item GNATS_ADMIN
This setting is now set in the @file{responsible} file in the
@w{@file{gnats-adm}} directory of your database(s).

@item GNATS_SITE
@sc{gnats} 4 has no concept of a named `site', so this directive is
obsolete.

@item SUBMITTER
Obsolete, since it relates to @var{GNATS_SITE}.

@item DEFAULT_RELEASE
@itemx DEFAULT_ORGANIZATION
The @sc{gnats} 4 @file{dbconfig} file has separate configuration
sections for each defined field.  Field defaults are set with the
@code{default} keyword in these sections.  @xref{dbconfig file,,The
@file{dbconfig} file}.

@item NOTIFY
Controlled by the @code{notify-about-expired-prs} setting in the
@file{dbconfig} file.

@item ACKNOWLEDGE
Controlled by the @code{send-submitter-ack} setting in the
@file{dbconfig} file.

@item DEFAULT_SUBMITTER
The default submitter is now always the first entry in the
@file{submitters} file of your database.

@item KEEP_RECEIVED_HEADERS
Controlled by the @code{keep-all-received-headers} setting in the
@file{dbconfig} file.

@item DEBUG_MODE
Controlled by the @code{debug-mode} setting in the @file{dbconfig} file.

@item BDAY_START
@itemx BDAY_END
@itemx BWEEK_START
@itemx BWEEK_END
Controlled by the settings @code{business-day-hours} and
@code{business-week-days} in the @file{dbconfig} file.

@item DEFINE_CATEGORY
The default category for PRs that arrive without one is now the first
category listed in the @file{categories} file of your database.
@end table

After your are done migrating the settings, you may optionally delete
the old @file{config} files.  Since there are many more configuration
settings available in the @sc{gnats} 4 @file{dbconfig} file, you should
take some time to review them all before proceeding.  @xref{dbconfig
file,,The @file{dbconfig} file}.

If your old @sc{gnats} installations was release-based, i.e. it included
the fields Quarter, Keywords and Date-Required, you need to define those
fields in the @file{dbconfig} file by following the instructions in
@ref{release-based support,,Supporting old @sc{gnats} ``release-based''
fields}.

@item
The file @file{gnatsd.access} has been renamed to @file{gnatsd.user_access}.
Furthermore, @sc{gnats} 4 uses a different password format in the
@file{gnatsd.user_access} file than older versions, since it supports
@code{crypt()} and MD5 passwords (@pxref{Access Control,,Controlling
access to @sc{gnats} databases}).  You need to translate your old
@w{@file{gnatsd.user_access}} files to the new format by using the
@code{gnats-pwconv} tool which was installed in the
@w{@file{@var{EXEC-PREFIX}/libexec/gnats}} directory, typically
@w{@file{/usr/local/libexec/gnats}}.  @xref{gnats-pwconv,,Managing user
passwords}.

@item
The final step involves regenerating the indexes of your databases.  For
this, log in as the user @code{gnats}.  Then run the @code{gen-index}
command for each of your databases.  See @ref{Admin
utils,,Administrative Utilities} for details on how to use
@w{@code{gen-index}}.

@item
Sit back and enjoy your new @sc{gnats} 4 setup...
@end enumerate

@c FIXME - anything else?
