www.delorie.com/gnu/docs/gnats/gnats_46.html

search

	Buy GNU books!

Keeping Track

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