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.