This is Info file ../../info/gnats.info, produced by Makeinfo version 1.68 from the input file gnats.texi. START-INFO-DIR-ENTRY * Keeping Track: (gnats). GNU Problem Report Management System END-INFO-DIR-ENTRY Copyright (C) 1993, 1995 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.  File: gnats.info, Node: edit-pr in Emacs, Next: edit-pr from the shell, Up: edit-pr Using `edit-pr' from within Emacs --------------------------------- Call `edit-pr' from within Emacs with `M-x edit-pr'(1). When `edit-pr' prompts you for a PR identification number, type the number of the PR you wish to edit. If the PR is locked, Emacs announces the login name of the person who has locked the file. If not, `M-x edit-pr' locks the PR, loads it into a buffer named `*edit-pr*', and places the cursor in the `>Number:' field. (*Do not change this field*.) Edit the PR to reflect correct information. Resubmit the PR to the database using `C-c C-c' (see below). The easiest way to edit a PR from Emacs is to use the special key bindings provided. These are: `C-c C-c' `M-x gnats-submit-pr' Saves and resubmits the PR currently being edited. Do this when you finish editing the PR; if you simply kill the buffer, your changes are lost. `C-x C-s' `M-x save-buffer' Saves the current buffer tp a file. You are prompted for a filename. This is not a special key binding, but at one point in the history of GNATS it was used to resubmit the PR (i.e., it was bound to `M-x gnats-submit-pr'). `C-x C-s' now simply saves a copy of the PR. This command *does not* resubmit the PR to the database. Use `C-c C-c' to resubmit the PR. `C-x k' `M-x gnats:kill-buffer (*use this only with Emacs 18*)' `M-x kill-buffer' Kills the current buffer (destroying all changes) and unlocks the current PR. Use this to back out of a change without affecting the database. `C-c C-u' `M-x unlock-pr' Unlocks a PR that you have locked. Use this if you have a locked PR from a failed editing session. You are prompted for the GNATS-ID of a PR to unlock. `C-c C-q' `M-x unlock-buffer' Removes the lock on the current PR, allowing others to edit it. The buffer remains active and non-writeable. To relock a PR, simply type `e' in the buffer containing the Problem Report. `C-c C-e' `M-x edit-pr' Runs `edit-pr' in a new buffer. `C-c C-f' `M-x change-field' Changes the field under the cursor. `edit-pr' prompts you for a new value. If you use C-u C-c C-f *or* C-u M-x change-field you are prompted for a field to change. `C-c C-a' `M-x gnats-mail-reply' Sends mail to the originator of this PR, using the address in the `From:' field of the mail header. The `Subject', `To:', and `Cc:' fields are constructed from the Problem Report currently being edited. Edit the message, and use `C-c C-c' to send it. `C-c RET' `C-c C-m' `M-x gnats-mail-other-window' Splits the current window, and starts a mail message. The `Subject:' field is constructed from the Problem Report currently being edited. Edit the message, and use `C-c C-c' to send it. `C-c C-r' `M-x gnats-responsible-change-from-to' Changes the `>Responsible:' field. `edit-pr' prompts you for the new responsible person, and for a message describing the reason for the change. When you type `C-c C-c' to resubmit the PR, the cursor is placed in a mail buffer containing a copy of the change. You can then edit this buffer and type `C-c C-c' again to send the mail. `C-c C-s' `M-x gnats-state-change-from-to' Changes the `>State:' field. `edit-pr' prompts you for the new state, and for a message describing the reason for the change. When you type `C-c C-c' to resubmit the PR, the cursor is placed in a mail buffer containing a copy of the change. You can then edit this buffer and type `C-c C-c' again to send the mail. `C-c C-t' `M-x category-change-from-to' Changes the `>Category:' field of the PR. `edit-pr' prompts you for the new category. `edit-pr' also prompts you with the question Update the >Responsible field? Type `y' to change the value of the `>Responsible:' field to the name of the party responsible for the new category. Type `n' to keep the current value of `>Responsible:'. `M-C-b' `M-x gnats-backward-field' Moves the cursor to the beginning of the value of the current field. `M-C-f' `M-x gnats-forward-field' Moves the cursor to the end of the value of the current field. `M-p' `M-x gnats-previous-field' Moves the cursor back one field to the beginning of the value of the previous field. `M-n' `M-x gnats-next-field' Moves the cursor forward one field to the beginning of the value of the next field. ---------- Footnotes ---------- (1) If typing `M-x edit-pr' doesn't work, see your system administrator for help loading `edit-pr' into Emacs.  File: gnats.info, Node: edit-pr from the shell, Prev: edit-pr in Emacs, Up: edit-pr Invoking `edit-pr' from the shell --------------------------------- The usage for the `edit-pr' shell script is: edit-pr GNATS-ID [ -V | --version ] [ -h | --help ] You must first determine which PR you want to edit. The options are: `-V *or* --version' Prints the version number for `edit-pr'. `-h *or* --help' Prints the usage for `edit-pr'. `edit-pr' calls the editor specified in your environment variable `EDITOR' on a temporary copy of that PR. (If you don't have the variable `EDITOR' defined in your environment, the default editor `vi' is used.) Edit the PR, changing any relevant fields or adding to existing information. When you exit the editor, `edit-pr' prompts you on standard input for a reason if you've changed either the `>Responsible:' field or the `>State:' field. `edit-pr' tracks the information you provide when changing either of these two fields, along with the change that occurred, your name, and the time of change in the `>Audit-Trail:' field.  File: gnats.info, Node: query-pr, Next: view-pr, Prev: edit-pr, Up: Invoking the tools Querying the database ===================== Obtain information from the database by using the program `query-pr'. `query-pr' uses search parameters you provide to find matching Problem Reports in the database. You can invoke `query-pr' from the shell or from within Emacs. `query-pr' uses the same arguments whether it is invoked from the shell or from Emacs. All arguments and options to `query-pr' are optional. If you do not specify a PR identification number and do not give any search parameters, `query-pr' displays the entire database. All arguments are considered identification numbers of Problem Reports to display. Any number of options can be given (though some make no sense when specified on the same command line); all are connected with a logical `AND'. * Menu: * Invoking query-pr:: * Example queries:: * Reporting::  File: gnats.info, Node: Invoking query-pr, Next: Example queries, Up: query-pr Invoking `query-pr' ------------------- From the shell, simply type `query-pr', followed by any search parameters you wish to exercise. From Emacs, type `M-x query-pr'. `query-pr' prompts you for search parameters in the minibuffer. `query-pr' can also be accessed by electronic mail, if your version of GNATS is configured for this. To use this feature, simply send mail to the address `query-pr@YOUR-SITE' with command line arguments or options in the `Subject:' line of the mail header. GNATS replies to your mail with the results of your query. The default settings for the `query-pr' mail server are --restricted --state="open|analyzed|feedback|suspended" To override the `--state' parameter, specify `--state=STATE' in the `Subject:' line of the mail header. You can not query on confidential Problem Reports by mail. The usage for `query-pr' is: query-pr [ GNATS-ID ] [ -c CATEGORY | --category=CATEGORY ] [ -s STATE | --state=STATE ] [ -r RESPONSIBLE | --responsible=RESPONSIBLE ] [ -S SUBMITTER | --submitter=SUBMITTER ] [ -C [ YES | NO ] | --confidential=[ YES | NO ] ] [ -e SEVERITY | --severity=SEVERITY ] [ -p PRIORITY | --priority=PRIORITY ] [ -O ORIGINATOR | --originator=ORIGINATOR ] [ -L CLASS | --class=CLASS ] [ -t TEXT | --text=TEXT ] [ -m TEXT | --multitext=TEXT ] [ -R | --restricted ] [ -F | --full ] [ -q | --summary ] [ -i | --sql ] [ -P | --print-path ] [ -d DIRECTORY | --directory=DIRECTORY ] [ -o OUTFILE | --output=OUTFILE ] [ -V | --version ] [ -h | --help ] If you run `query-pr' from within Emacs, you can use C-x ` *or* M-x next-error to scroll through Problem Reports one by one after the search is finished. Search criteria --------------- The following arguments and options specify search criteria. The lack of a criterion indicates that all values for the corresponding field are valid for the search. Regular expressions may be used as arguments to search criteria options; see *Note Querying using regular expressions: Regexps. Using an argument to `query-pr' specifies the most stringent search criteria, that of a single PR. `GNATS-ID' The identification number of the PR you wish to view, as shown in the `>Number:' field. Any number of GNATS-ID arguments may be given. `-c CATEGORY' `--category=CATEGORY' Search only for PRs with a `>Category:' value of CATEGORY. For a list of valid categories, type `send-pr -L' from the shell. `-s STATE' `--state=STATE' Search only for PRs with a `>State:' value of STATE. STATE must be one of: `open', `analyzed', `feedback', `closed', or `suspended'. This field may be searched using regular expressions. *Note Querying using regular expressions: Regexps. Also see *Note Example queries: Example queries. `-r RESPONSIBLE' `--responsible=RESPONSIBLE' Search only for PRs with a `>Responsible:' value of RESPONSIBLE. `-S SUBMITTER' `--submitter=SUBMITTER' Search only for PRs with a `>Submitter:' value of SUBMITTER. `-C [YES | NO]' `--confidential=[YES | NO]' Search only for PRs with a `>Confidential:' value of either YES or NO. If this option is not given, all PRs are eligible for the search regardless of their confidentiality. `-e SEVERITY' `--severity=SEVERITY' Search only for PRs with a `>Severity:' value of SEVERITY. SEVERITY must be one of: `critical', `serious', or `non-critical'. `-p PRIORITY' `--priority=PRIORITY' Search only for PRs with a `>Priority:' value of PRIORITY. PRIORITY must be one of: `high', `medium', or `low'. `-O ORIGINATOR' `--originator=ORIGINATOR' Search only for PRs with an `>Originator:' value of ORIGINATOR. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that *is* part of the index (*note The `index' file: index file.). `-L CLASS' `--class=CLASS' Search only for PRs with a `>Class:' value of CLASS. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that *is* part of the index (*note The `index' file: index file.). `-t TEXT' `--text=TEXT' Search the TEXT fields in the database for the regular expression TEXT. TEXT fields include the following (the `>' and `:' Problem Report fieldname delimiters have been removed for the sake of brevity and readability): Submitter-Id Originator Synopsis Category Release Responsible Arrival-Date *Note Querying using regular expressions: Regexps. Queries using this option can be slow. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that *is* part of the index (*note The `index' file: index file.). `-m TEXT' `--multitext=TEXT' Search the MULTITEXT fields in the database for the regular expression TEXT. MULTITEXT fields include the following (again, the fieldname delimiters `>' and `:' have been omitted): Organization Environment Description How-To-Repeat Fix Audit-Trail Unformatted *Note Querying using regular expressions: Regexps. Queries using this option can be very slow. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that *is* part of the index (*note The `index' file: index file.). `-R' `--restricted' Omit from the search path PRs whose `>Confidential:' fields contain the value `yes'. This is equivalent to query-pr --confidential=no and also disallows the use of the options `--outfile=OUTFILE' and `--directory=DIRECTORY'. This option is used with the `mail-query' tool. `-x' `--skip-closed' Omit closed PRs from the search path. This option is ignored if you also use `-s STATE' or `--state=STATE'. Output format ------------- Use the following options to select the format in which the Problem Report is printed. Use only one of these options for a given search. If you do not specify one of these options, a header(1) for the Problem Reports meeting the search criteria is printed. `-F' `--full' Prints all fields in the Problem Report rather than just summary information. `-q' `--summary' Print a short single-line summary of PR information, delimited by whitespace, including the following fields in order (the `>' and `:' Problem Report fieldname delimiters have been removed for the sake of brevity and readability): Number Responsible Category State Severity Priority Submitter-Id Synopsis `-i' `--sql' Prints information on a single line with fields delimited by pipes (`|'), which can be uploaded into a relational database. When you use this option, `query-pr' outputs ENUMERATED fields numerically rather than textually; see *Note Reporting on groups of Problem Reports: Reporting. `query-pr -i' outputs the following fields, in order (again, the fieldname delimiters `>' and `:' have been omitted): Number Category Synopsis Confidential Severity Priority Responsible State Class Submitter-Id Arrival-Date Originator Release When you use the `-i' option, `query-pr' outputs the ENUMERATED fields in the database, namely `>Severity:', `>Priority:', `>State:', and `>Class:', as numbers rather than text. *Note Reporting on groups of Problem Reports: Reporting, for details. Other options ------------- `query-pr' also accepts the following options: `-P' `--print-path' Prints the path which `query-pr' used to find the current PR. A line of the form `DIRECTORY/NUMBER:NUMBER' is printed before each PR. This option is automatically used from within Emacs to facilitate scrolling through groups of PRs with `C-x `'. `-d DIRECTORY' `--directory=DIRECTORY' Changes the search directory to DIRECTORY from GNATS_ROOT. `-o OUTFILE' `--output=OUTFILE' Prints all output to OUTFILE rather than to the standard output. `-V' `--version' Prints the version number for `query-pr'. `-h' `--help' Prints the usage for `query-pr'. ---------- Footnotes ---------- (1) A "header" includes the mail header fields as well as the following fields: `>Number:', `>Category:', `>Synopsis:', `>Confidential:', `>Severity:', `>Priority:', `>Responsible:', `>State:', `>Class:', `>Submitter-Id:', `>Originator:', `>Release:', and `>Arrival-Date:'. For suggestions on using alternate output formats in database reports, see *Note Reporting: Reporting.  File: gnats.info, Node: Example queries, Next: Reporting, Prev: Invoking query-pr, Up: query-pr Example queries --------------- The following simple query: query-pr --category=rats --responsible=fred --state=analyzed yields all PRs in the database which contain the field values: >Category: rats *and* >Responsible: fred *and* >State: analyzed The following query: query-pr --state="o|a" yields all PRs in the database whose `>State:' values match either `open' or `analyzed' (*note Querying using regular expressions: Regexps.. This search is useful as a daily report that lists all Problem Reports which require attention. The report can be further altered using an alternate output format for `query-pr'; see *Note Reporting on groups of Problem Reports: Reporting. A more fine-grained report may be obtained by specifying more search parameters, e.g. narrowing the search down by `>Submitter:' or by `>Responsible:'. The following query: query-pr --text="The quick.*brown fox" yields all PRs whose TEXT fields contain the text `The quick' followed by `brown fox' within the same field. *Note Querying using regular expressions: Regexps.  File: gnats.info, Node: Reporting, Prev: Example queries, Up: query-pr Reporting on groups of Problem Reports -------------------------------------- There currently exists no separate reporting mechanism in GNATS from `query-pr'. However, the `-q' and `-i' options to `query-pr' allow for easy reporting. For example, a report on the current open Problem Reports in the database can be obtained using `awk' with query-pr -q | awk '{print $3 "/" $1 ": " $4}' which yields a list of the form CATEGORY/GNATS-ID: STATE *etc...* For example: sprockets/123: open widgets/456: analyzed *etc...* The `-i' option to `query-pr' yields output delimited by pipes (`|'). This results in the following: GNATS-ID|CATEGORY|SYNOPSIS|CONFIDENTIAL|\ SEVERITY|PRIORITY|RESPONSIBLE|STATE|CLASS|\ SUBMITTER-ID|ARRIVAL-DATE|ORIGINATOR|RELEASE A report on Problem Reports in the database that are currently `open' or `analyzed' might resemble the following (the example is split into two lines in order to fit onto the page; it is intended to be typed on one command line): query-pr -i -s "o|a" | \ awk -F\| '{print $1 " " $2 " " $8 " " $3}' which yields GNATS-ID CATEGORY STATE RESPONSIBLE SYNOPSIS *etc...* For example: 123 sprockets 1 fred The sprockets program gives bad output 456 widgets 2 barney The foo widget doesn't work with 'bar' 789 widgets 1 wilma The 'baz' widget is broken When you use the `-i' option, `query-pr' outputs the ENUMERATED fields in the database, namely `>Severity:', `>Priority:', `>State:', and `>Class:', as numbers rather than text. In the example above, a `>State:' value of `1' means `open', `2' means `analyzed', and so forth. ENUMERATED fields are output according to the following paradigm: >Severity: >Priority: critical 1 high 1 serious 2 medium 2 non-critical 3 low 3 >State: >Class: open 1 sw-bug 1 analyzed 2 doc-bug 2 suspended 3 support 3 feedback 4 change-request 4 closed 5 mistaken 5 duplicate 6 This makes sorting on these values easy, when combined with `sort'. It is left as an exercise for the reader to figure out how to do this.  File: gnats.info, Node: view-pr, Prev: query-pr, Up: Invoking the tools Viewing individual Problem Reports ================================== Use `view-pr' from within Emacs to view individual Problem Reports. Invoke `view-pr' with M-x view-pr You are prompted to enter a Problem Report identification number (GNATS-ID). You can also invoke `view-pr' with C-u GNATS-ID M-x view-pr `view-pr' allows you to view GNATS-ID. This is identical to using C-u GNATS-ID M-x query-pr except that you may choose to edit the PR at any time by pressing `e'.  File: gnats.info, Node: Management, Next: Installation, Prev: Invoking the tools, Up: Top GNATS Administration ******************** In daily usage, GNATS is self-maintaining. However, there are various administrative duties which need to be performed periodically: *emptying the `pending' directory* If a Problem Report arrives with a `>Category:' value that is unrecognized by the `categories' file, or if that field is missing, GNATS places the PR in the `pending' directory (*note Where the tools and utilities reside: Locations.). GNATS has no way of knowing which subdirectory the PR should be filed under. GNATS sends a notice to the `gnats-admin' and to the party responsible for that submitter (as listed in the `submitters' file) when this occurs. To file these PRs, simply use `edit-pr' to repair the problematic fields in each file in the `pending' directory. Be sure to change the `>Category:' field of the PR from `pending' to an appropriate category. In many cases the culprit is simply a typographical error, although it may be necessary sometimes to contact the submitter of the PR to decipher her or his intentions. Should you run out of disk space, there may be an empty PR in the `pending' directory. In that case, look in the file `GNATS_ROOT/gnats-adm/bug.log', which should still contain the full message that was submitted. *adding new categories* To add a new category, simply insert a new line in the `categories' file and then run the program `mkcat'. *Note*: this causes all category lists for `send-pr' (except the one on the local machine) to become outdated. Copy the new list on to every machine on your network that has `send-pr' installed, and make sure you advise remote submitters that the category list has changed. *Note Adding a problem category: mkcat. Also *Note The `categories' file: categories. *removing categories* To remove a category, you need to make sure the relevant subdirectory is empty (in other words, make sure no PRs exist for the category you wish to remove). You can then remove the category listing from the `categories' file, and invoke rmcat CATEGORY... to remove CATEGORY (any number of categories may be specified on the command line to `rmcat', so long as they abide by the above constraints). *Note*: this causes all category lists for `send-pr' (except the one on the local machine) to become outdated. Copy the new list on to every machine on your network that has `send-pr' installed, and make sure you advise remote submitters that the category list has changed. *Note Removing a problem category: rmcat. Also *Note The `categories' file: categories. *adding and removing maintainers* Edit the `responsible' file to add a new maintainer or to remove an existing maintainer. *Note The `responsible' file: responsible. *building a distribution of `send-pr'* You can build a distribution of `send-pr' which contains valid information for your site by invoking the command `mkdist'. *Note Configuring `send-pr' for the outside world: mkdist. You can then distribute your customized `send-pr' to your customers, friends, relatives, etc., so that they can submit Problem Reports to your database. *building a new index* If your index becomes corrupted, or if you wish to generate a new one for some reason, use the program `gen-index' (*note Regenerating the index: gen-index.). *pruning log files* Log files often grow to unfathomable proportions. As with gardening, it is best to prune these as they grow, lest they take over your disk and leave you with no room to gather more Problem Reports. If you keep log files, be sure to keep an eye on them. (*Note Setting up mail aliases: Aliases.) *BACKING UP YOUR DATA* Any database is only useful if its data remains uncorrupted and safe. Performing periodic backups ensures that problems like disk crashes and data corruption are reversible. *Note Where GNATS lives: Locations. * Menu: * Networked management:: Managing GNATS over a network * Local configuration:: Changing your local configuration * Admin files:: Administrative data files * Admin utils:: Administrative utilities * Internal utils:: Internal utilities  File: gnats.info, Node: Networked management, Next: Local configuration, Up: Management Managing GNATS over a network ============================= If you have installed the GNATS user tools on machines around your local network, there are a few things you need to remember. `mkcat' and `rmcat' do not update the categories list for other machines on your network which have `send-pr' installed, unless those machines share PREFIX with the host machine). To update these lists, copy the `send-pr' categories list to each of the other hosts. This categories list is `PREFIX/lib/gnats/SITE', where SITE is the name tag for your local site, as specified in the `config' file as `GNATS_SITE' (*note The `config' file: config.). It is also important to note that only your local `send-pr' has access to this new information; any copies of `send-pr' which you have distributed to outside submitters now have outdated category lists. You must either contact your submitters and instruct them to update their copy of the categories list, which they installed in `PREFIX/lib/gnats/SUPPORT-SITE' from the distribution you provided, or you must build another distribution of `send-pr' with this new information and redistribute it. If you need to use GNATS utilities, like `query-pr' and `edit-pr', on other systems besides the one where GNATS itself resides, *note Installing the user tools: Installing tools..  File: gnats.info, Node: Local configuration, Next: Admin files, Prev: Networked management, Up: Management Changing your local configuration ================================= *Note Where GNATS lives: Locations. Your local configuration is determined by the data files in the directory `GNATS_ROOT/gnats-adm'. These can be altered at any time by editing the pertinent file. `config' Variables which control certain behavior. *Note The `config' file: config. Behaviors you can change here include * The address where your site receives Problem Reports. * The address of the GNATS administrator. * The nametag for your Support Site (your organization, company, group, etc.). * The nametag for your local Submitter Site. * The default release for your site. * The default value for the `>Organization:' field (this value appears as the default when you run `send-pr'). * Whether or not to remind maintainers if a requisite time period has passed before they change the state of a Problem Report to `analyzed'. (Also see *Note The `submitters' file: submitters, and *Note Timely Reminders: at-pr. * Whether or not to send an automatic acknowledgement to the originator of a problem report when the GNATS first receives the PR. * The value GNATS assigns to PRs which come in with missing or unknown values for the `>Submitter-Id:' field. * Whether or not GNATS should retain `Received:' mail headers from incoming mail. * Whether or not GNATS is in a mode for debugging. * The values which define business hours. `categories' The list of categories that GNATS accepts as valid for the `>Category:' field, and the maintainers responsible for each category. Update this file whenever you have a new category, or whenever a category is no longer valid. You must also update this file whenever responsiblility for a category changes, or if a maintainer is no longer valid. *Note The `categories' file: categories. Also see *Note Adding a new problem category: mkcat, and *Note Removing a problem category: rmcat. `responsible' The list of maintainers. Update this file whenever you have a new maintainer, or whenever a maintainer is no longer valid. *Note The `responsible' file: responsible. `submitters' The list of Submitter Sites from whom GNATS accepts Problem Reports. This file is mandatory, although the feature it provides is not; see *Note The `submitters' file: submitters. * Menu: * default behavior:: * config:: The `config' file * categories:: The `categories' file * responsible:: The `responsible' file * submitters:: The `submitters' file  File: gnats.info, Node: default behavior, Next: config, Up: Local configuration Default behavior ---------------- The default behavior for GNATS is as follows: * The address where your site receives Problem Reports is `bugs' (a local address). * The address of the GNATS administrator is `gnats-admin' (a local address). * The nametag for your Support Site (your organization, company, group, etc.) is the second-to-last field in your domain name. * The nametag for your local Submitter Site is the nametag for your Support Site. * The default release for your site is `unknown-1.0'. * The default value for the `>Organization:' field (this value appears as the default when you run `send-pr') is the nametag for your Support Site. * GNATS reminds maintainers if a requisite time period has passed before they change the state of a Problem Report to `analyzed'. * An automatic acknowledgement is sent to the originator of a problem report when the GNATS first receives the PR. * The value GNATS assigns to the `>Submitter-Id:' field in PRs which arrive with missing or unknown values for that field is `unknown'. * `Received...' mail headers are retained. * GNATS is not in a debugging mode. * "business hours" are defined as 8:00am to 5:00pm, Monday through Friday.  File: gnats.info, Node: config, Next: categories, Prev: default behavior, Up: Local configuration The `config' file ----------------- Much of the behavior GNATS exhibits depends on the values of fields in the file `GNATS_ROOT/gnats-adm/config'. The `config' file contains a list of variables (using Bourne-shell syntax) which control the following behavior. These values can be changed at any time; the new values take effect for all subsequent iterations of the tools. `GNATS_ADDR="ADDRESS"' The address where your site receives Problem Reports. This address is aliased in the file `/etc/aliases' so that it directs incoming mail into `queue-pr' (*note Installing the utilities: Installing utils.). The default is `bugs' (a local address). `GNATS_ADMIN="ADDRESS"' The address of the GNATS administrator. Normally this is set to `gnats-admin', which is an alias in `/etc/aliases' that points toward the person responsible for administrating GNATS. *Note Installing the utilities: Installing utils. The default is `gnats-admin' (a local address). `GNATS_SITE="SITE"' The nametag for your Support Site (your organization, company, group, etc.). This nametag should also appear in the `submitters' file, so that users at your site can submit Problem Reports locally. SITE is also used as the name of the file containing a valid category list for your site. This file is installed locally as `PREFIX/lib/gnats/SITE'. *Warning:* if you change this variable after GNATS is installed, you must also change the name of this file, as well as the name of the alias for your local submitters (*note Setting up mail aliases: Aliases.). The default is the second-to-last field in your domain name. For example, if your domain name is `unleaded.truckstop.org', your default SITE is `truckstop'. `SUBMITTER="SUBMITTER-ID"' The nametag for your local Submitter Site (this value appears as the default value for `>Submitter-Id' when you run `send-pr'). Even though you are a Support Site, if you submit Problem Reports to your own organization you become a Submitter Site. The value SUBMITTER-ID is the default value for the `>Submitter-Id:' field that your maintainers see when they submit Problem Reports locally. The default is the value of `GNATS_SITE'. `DEFAULT_RELEASE="RELEASE"' The default release for your site (this value appears as the default value for `>Release:' when you run `send-pr'). The default is `unknown-1.0'. `DEFAULT_ORGANIZATION="TEXT"' The default value for the `>Organization:' field (this value appears as the default when you run `send-pr'). The default is the value of `GNATS_SITE'. `NOTIFY=BOOLEAN' Determines whether or not to remind maintainers if a requisite time period has passed before they change the state of a Problem Report to `analyzed'. This feature uses the program `at-pr'; see *Note Timely Reminders: at-pr. This requisite time is determined for each submitter individually; see *Note The `submitters' file: submitters. The time is measured in "business hours", which by default are 8:00am to 5:00pm, Monday through Friday. Business hours can be redefined by changing the variables `BDAY_START', `BDAY_END', `BWEEK_START', and `BWEEK_END' in the `config' file (see below). If BOOLEAN is `1', this feature is active. If BOOLEAN is `0', the feature is turned off. The default value for `NOTIFY' is `1'. `ACKNOWLEDGE=BOOLEAN' Determines whether or not to send an automatic acknowledgement to the originator of a problem report when the GNATS first receives the PR. If BOOLEAN is `1', this feature is active. If BOOLEAN is `0', the feature is turned off. The default for `ACKNOWLEDGE' is `1'. The acknowledgment is of the form: To: YOUR-ADDRESS From: gnats Subject: Re: CATEGORY/GNATS-ID:SYNOPSIS In-Reply-To: Your message of DATE Thank you very much for your problem report. It has the internal identification: CATEGORY/GNATS-ID The individual assigned to look at your bug is: RESPONSIBLE Category: CATEGORY OF THE PR Responsible: RESPONSIBLE Synopsis: SYNOPSIS FROM SUBMITTED PR Arrival-Date: ARRIVAL DATE `DEFAULT_SUBMITTER="submitter-id"' The value GNATS assigns to PRs which come in with missing or unknown values for the `>Submitter-Id:' field. This value must also appear in the `submitters' file; see *Note The `submitters' file: submitters. To disable the feature of GNATS which tracks the `>Submitter-Id:', simply alter the `submitters' file to only contain the SUBMITTER-ID value which appears in `DEFAULT_SUBMITTER', and and instruct your submitters to ignore the field. The default value for `DEFAULT_SUBMITTER' is `unknown'. `KEEP_RECEIVED_HEADERS=BOOLEAN' Determines whether or not GNATS should retain the `Received:' mail headers from incoming mail. These headers often take up a lot of space, and they are seldom used. If BOOLEAN is `1', this feature is active. If BOOLEAN is `0', the feature is turned off. The default value for `KEEP_RECEIVED_HEADERS' is `1'. `DEBUG_MODE=BOOLEAN' Determines whether or not GNATS is operating in a mode for debugging. When BOOLEAN is `1', GNATS fowards all mail to the GNATS administrator, `gnats-admin'. `BDAY_START=INTEGER' `BDAY_END=INTEGER' `BWEEK_START=INTEGER' `BWEEK_END=INTEGER' The definition of "business hours". These values are only used if `NOTIFY' is set to `1' in the `config' file (see above). By default, business hours are 8:00am to 5:00pm Monday through Friday, local time. `BDAY_START=INTEGER' Defines the hour of the day when business hours begin. INTEGER values must fall between `0' (midnight) and `23' (11:00pm). The default is `8' (8:00am). `BDAY_END=INTEGER' Defines the hour of the day when business hours end. INTEGER values must fall between `0' (midnight) and `23' (11:00pm). The default is `17' (5:00pm). `BWEEK_START=INTEGER' Defines the beginning day of the business week. INTEGER values must fall between `0' (Sunday) and `6' (Saturday). The default is `1' (Monday). `BWEEK_END=INTEGER' Defines the ending day of the business week. INTEGER values must fall between `0' (Sunday) and `6' (Saturday). The default is `5' (Friday).  File: gnats.info, Node: categories, Next: responsible, Prev: config, Up: Local configuration The `categories' file --------------------- The `categories' file contains a list of problem categories, specific to your site, which GNATS tracks. This file also matches responsible people with these categories. You must edit this file initially, creating valid categories and then running `mkcat' to create the corresponding subdirectories of `GNATS_ROOT' and update the valid categories list for `send-pr'. For instructions on running `mkcat', see *Note Adding a problem category: mkcat. To create a new category, log in as GNATS, add a line to this file, and run `mkcat'. Lines beginning with `#' are ignored. A line in the `categories' file consists of four fields delimited by colons, as follows: CATEGORY:DESCRIPTION:RESPONSIBLE:NOTIFY CATEGORY A unique category name, made up of text characters. This name cannot contain spaces or any of the following characters: ! $ & * ( ) { } [ ] ` ' " ; : < > ~ Ideally, category names should not contain commas or begin with periods. Each line has a corresponding subdirectory in the main GNATS directory (GNATS_ROOT). DESCRIPTION A terse textual description of the category. RESPONSIBLE The name tag of the party responsible for this category of problems, as listed in the `responsible' file (*note The `responsible' file: responsible.). NOTIFY One or more other parties which should be notified when a Problem Report with this category arrives, such as a project manager, other members of the same project, other interested parties, or even log files. These should be separated with commas. A good strategy for configuring this file is to have a different category for each product your organization supports or wishes to track information for, or perhaps with sub-categories within each category. For instance, if you wish to track documentation problems in a variety of areas, you could have entries such as doc:General Doc Questions:myboss:me,barney doc-rock:Doc for ROCK program:me:myboss doc-stone:Docs for STONE utils:barney:fred doc-local:in-house documentation:me:doc-local-log In the above example, the nametags `myboss', `me', `fred', and `barney' must be defined in the `responsible' file (*note The `responsible' file: responsible.). Problem Reports with a category of `doc' are sent to the local mail address (or alias) `myboss', and also sent to the addresses `me' and `barney'. PRs with a category of `doc-rock' are sent to the local addresses `me' and `myboss' only, while PRs with the category `doc-stone' are sent to `fred' as well as to `barney'. PRs with a category of `doc-local' are sent only to `me', and are also filed in `doc-local-log' (in this case, an alias should be set up in `/etc/aliases' to reflect a location for the log file, such as `doc-local-log: /users/me/local-log'). Whenever you add a new category, be sure to run `mkcat' to create a subdirectory for it and update the local categories list. Only one category must be present for GNATS to function: pending:Category for faulty PRs: gnats-admin: The `pending' directory is created automatically when you run `make install' (*note Configuring and compiling the software: Configure and make.).  File: gnats.info, Node: responsible, Next: submitters, Prev: categories, Up: Local configuration The `responsible' file ---------------------- This file contains a list of the responsible parties. Lines beginning with `#' are ignored. Each entry contains three fields, separated by colons: RESPONSIBLE:FULL-NAME:MAIL-ADDRESS RESPONSIBLE A name-tag description of the party in question, such as her or his user name, or the name of the group. This name is listed in the PR in the `>Responsible:' field. FULL-NAME The full name of the party ("Charlotte Bronte"; "Compiler Group"). MAIL-ADDRESS The full, valid mail address of the party. This field is only necessary if the responsible party has no local mail address or alias. A sample `responsible' listing might be: ren:Ren Hoek: stimpy:Stimpson J. Cat:stimpy@lederhosen.org Here, `ren' is a local user. `stimpy' is remote, so his full address must be specified. The following entry must be present for GNATS to function: gnats-admin: GNATS administrator: (`gnats-admin' is a mail alias, so for this purpose `gnats-admin' is a local address.)  File: gnats.info, Node: submitters, Prev: responsible, Up: Local configuration The `submitters' file --------------------- This is a database of sites which submit bugs to your support site. It contains six fields delineated by colons. Lines beginning with `#' will be ignored. Entries are of the format: SUBMITTER-ID:NAME:TYPE:RESP-TIME:CONTACT:NOTIFY SUBMITTER-ID A unique identifier for a specific site or other entity who submits Problem Reports. NAME A textual description of this entity. TYPE Optional description for the type of relationship this submitter to your support site. This could indicate a contract type, a level of expertise, etc., or it can remain blank. RESP-TIME Optional quoted response time, in "business hours". GNATS is capable of reminding responsible parties when Problem Reports marked with a `>Severity' value of `critical', or those with a `>Severity' of `serious' and a `>Priority' value of `high', are neglected for a certain period. This argument defines that response period for each SUBMITTER-ID. Business hours are defined by default as 8:00am to 5:00pm, Monday through Friday. For example, three business days would be equal to 24 business hours. This function is active if the `NOTIFY' field is defined as `1' in the `config' file (*note Changing your local configuration: Local configuration.). If `NOTIFY' is `0', this field is ignored. For information on `at-pr', the program which sends out this reminder, see *Note Timely Reminders: at-pr. CONTACT The name tag of the main "contact" at the Support Site for this submitter. This contact should be in the `responsible' file (*note The `responsible' file: responsible.). Incoming bugs from SUBMITTER are sent to this contact. Optionally, this field can be left blank. NOTIFY Any other parties who should receive copies of Problem Reports sent in by SUBMITTER. A few example entries in the `submitters' file: univ-hell: University of Hades:eternal:3:beelzebub:lucifer tta: Telephones and Telegraphs of America:support:720:dave: In this example, when a PR comes in from the University of Hades (who has an eternal contract), it should have `univ-hell' in its `Submitter-Id' field. This Problem Report goes to `beelzebub' (who should be in the `responsible' file), and if it is not analyzed within three business hours a reminder message is sent. `lucifer' also receives a copy of the bug, and a copy of the reminder message as well (if it is sent). When Telephones and Telegraphs of America utilizes their support contract and submits a bug, a copy is sent only to `dave', who has 720 business hours to return an analysis before a reminder is sent. To disable the feature of GNATS which tracks the `>Submitter-Id:', simply alter the `submitters' file to only contain the SUBMITTER-ID value which appears as the `DEFAULT_SUBMITTER' value in the `config' file (*note The `config' file: config.), and instruct your submitters to ignore the field.  File: gnats.info, Node: Admin files, Next: Admin utils, Prev: Local configuration, Up: Management Administrative data files ========================= The following files are located in `GNATS_ROOT/gnats-adm', where GNATS_ROOT is the resident directory of GNATS. These files are maintained by GNATS; you should never touch them. * Menu: * index file:: The `index' file * current file:: The `current' file  File: gnats.info, Node: index file, Next: current file, Up: Admin files The `index' file ---------------- The index is used to accelerate searches on the database by `query-pr' and `edit-pr'. This file is not created until the first PR comes in. It is then kept up to date by GNATS; you should never touch this file. Any searches on subjects contained in the index are much faster than searches which depend on data not in the index. The index contains single-line entries for the following fields, in order, separated by colons (`:') except for `>Category:' and `>Number:', which are separated by a slash (`/') (the `>' and `:' Problem Report fieldname delimiters have been removed for the sake of brevity and readability):: Category Number Submitter-Id Responsible State Confidential Severity Priority To see an example index, run `gen-index' without any options (*note Regenerating the index: gen-index.).  File: gnats.info, Node: current file, Prev: index file, Up: Admin files The `current' file ------------------ This file contains the last serial number assigned to an incoming PR. It is used internally by GNATS; you need never touch this file.  File: gnats.info, Node: Admin utils, Next: Internal utils, Prev: Admin files, Up: Management Administrative utilities ======================== These tools are used by the GNATS administrator as part of the periodic maintenance and configuration of GNATS. *Note GNATS Administration: Management. * Menu: * mkcat:: Adding a problem category * rmcat:: Removing a problem category * gen-index:: Regenerating the index * mkdist:: Configuring send-pr for the outside world  File: gnats.info, Node: mkcat, Next: rmcat, Up: Admin utils Adding a problem category ------------------------- To add new categories to the database: 1. Add a line to the `categories' file under `GNATS_ROOT/gnats-adm' for each new category. *Note The `categories' file: categories. 2. Run `mkcat'. `mkcat' creates a directory under GNATS_ROOT for any new categories which appear in the `categories' file. `mkcat' also recreates the list of valid categories for both your locally installed `send-pr' and for the `send-pr' distribution template in `PREFIX/lib/gnats/dist' (*note Where GNATS lives: Locations.. *Note:* `mkcat' does not update the categories list for other machines on your network which have `send-pr' installed (unless the two machines share the directory PREFIX). *Note Managing GNATS over a network: Networked management. It is also important to note that only your local `send-pr' has access to this new information; any copies of `send-pr' which you have distributed to outside submitters now have outdated category lists. You must either contact your submitters and instruct them to update their copy of the categories list, which they installed in `PREFIX/lib/gnats/SUPPORT-SITE' (*Note:* the value for PREFIX may be different from yours) from the distribution you provided, or you must build another distribution of `send-pr' with this new information and redistribute it (*note Configuring `send-pr' for the outside world: mkdist.).