Previous: Installing tools, Up: Installation

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

    This setting has no counterpart in gnats 4, since gnats no longer needs to know its own mail address.
    This setting is now set in the responsible file in the gnats-adm directory of your database(s).
    gnats 4 has no concept of a named `site', so this directive is obsolete.
    Obsolete, since it relates to GNATS_SITE.
    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 The dbconfig file.
    Controlled by the notify-about-expired-prs setting in the dbconfig file.
    Controlled by the send-submitter-ack setting in the dbconfig file.
    The default submitter is now always the first entry in the submitters file of your database.
    Controlled by the keep-all-received-headers setting in the dbconfig file.
    Controlled by the debug-mode setting in the dbconfig file.
    Controlled by the settings business-day-hours and business-week-days in the dbconfig file.
    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 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 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 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...