|
112
|
1 @node Management
|
|
|
2 @chapter @sc{gnats} Administration
|
|
|
3 @cindex administering @sc{gnats}
|
|
|
4 @cindex managing @sc{gnats}
|
|
|
5 @cindex GNATS management
|
|
|
6 @cindex duties for @code{gnats-admin}
|
|
|
7
|
|
|
8 In daily usage, @sc{gnats} is self-maintaining. However, there are
|
|
|
9 various administrative duties which need to be performed periodically:
|
|
|
10
|
|
|
11 @table @emph
|
|
|
12 @item emptying the @code{pending} directory
|
|
|
13 @cindex emptying the @code{pending} directory
|
|
|
14 If a Problem Report arrives with a @samp{>Category:} value that is
|
|
|
15 unrecognized by the @file{categories} file, or if that field is missing,
|
|
|
16 @sc{gnats} places the PR in the @w{@file{pending}} directory
|
|
|
17 (@pxref{Locations,,Where the tools and utilities reside}). @sc{gnats}
|
|
|
18 has no way of knowing which subdirectory the PR should be filed under.
|
|
|
19 @sc{gnats} sends a notice to the @code{gnats-admin} and to the party
|
|
|
20 responsible for that submitter (as listed in the @file{submitters} file)
|
|
|
21 when this occurs.
|
|
|
22
|
|
|
23 To file these PRs, simply use @code{edit-pr} to repair the problematic
|
|
|
24 fields in each file in the @file{pending} directory. Be sure to change
|
|
|
25 the @samp{>Category:} field of the PR from @samp{pending} to an
|
|
|
26 appropriate category. In many cases the culprit is simply a
|
|
|
27 typographical error, although it may be necessary sometimes to contact
|
|
|
28 the submitter of the PR to decipher her or his intentions.
|
|
|
29
|
|
|
30 Should you run out of disk space, there may be an empty PR in the
|
|
|
31 @file{pending} directory. In that case, look in the file
|
|
|
32 @w{@file{@var{GNATS_ROOT}/gnats-adm/bug.log}}, which should still contain
|
|
|
33 the full message that was submitted.
|
|
|
34
|
|
|
35 @item adding new categories
|
|
|
36 @cindex adding a problem category
|
|
|
37 @cindex @code{mkcat}
|
|
|
38 To add a new category, simply insert a new line in the
|
|
|
39 @w{@file{categories}} file and then run the program @code{mkcat}.
|
|
|
40
|
|
|
41 @emph{Note}: this causes all category lists for @code{send-pr} (except
|
|
|
42 the one on the local machine) to become outdated. Copy the new list on
|
|
|
43 to every machine on your network that has @code{send-pr} installed, and
|
|
|
44 make sure you advise remote submitters that the category list has
|
|
|
45 changed. @xref{mkcat,,Adding a problem category}. Also
|
|
|
46 @ref{categories,,The @code{categories} file}.
|
|
|
47
|
|
|
48 @item removing categories
|
|
|
49 @cindex removing a problem category
|
|
|
50 @cindex @code{rmcat}
|
|
|
51 To remove a category, you need to make sure the relevant subdirectory is
|
|
|
52 empty (in other words, make sure no PRs exist for the category you wish
|
|
|
53 to remove). You can then remove the category listing from the
|
|
|
54 @file{categories} file, and invoke
|
|
|
55
|
|
|
56 @smallexample
|
|
|
57 rmcat @var{category@dots{}}
|
|
|
58 @end smallexample
|
|
|
59
|
|
|
60 @noindent
|
|
|
61 to remove @var{category} (any number of categories may be specified on
|
|
|
62 the command line to @code{rmcat}, so long as they abide by the above
|
|
|
63 constraints).
|
|
|
64
|
|
|
65 @emph{Note}: this causes all category lists for @code{send-pr} (except
|
|
|
66 the one on the local machine) to become outdated. Copy the new list on
|
|
|
67 to every machine on your network that has @code{send-pr} installed, and
|
|
|
68 make sure you advise remote submitters that the category list has
|
|
|
69 changed. @xref{rmcat,,Removing a problem category}. Also
|
|
|
70 @ref{categories,,The @code{categories} file}.
|
|
|
71
|
|
|
72 @item adding and removing maintainers
|
|
|
73 @cindex adding and removing maintainers
|
|
|
74 Edit the @file{responsible} file to add a new maintainer or to remove an
|
|
|
75 existing maintainer. @xref{responsible,,The @code{responsible} file}.
|
|
|
76
|
|
|
77 @item building a distribution of @code{send-pr}
|
|
|
78 @cindex building a distribution of @code{send-pr}
|
|
|
79 @cindex @code{mkdist}
|
|
|
80 You can build a distribution of @code{send-pr} which contains valid
|
|
|
81 information for your site by invoking the command @code{mkdist}.
|
|
|
82 @xref{mkdist,,Configuring @code{send-pr} for the outside world}. You
|
|
|
83 can then distribute your customized @w{@code{send-pr}} to your
|
|
|
84 customers, friends, relatives, etc., so that they can submit Problem
|
|
|
85 Reports to your database.
|
|
|
86
|
|
|
87 @item building a new index
|
|
|
88 @cindex building a new index
|
|
|
89 @cindex @code{gen-index}
|
|
|
90 If your index becomes corrupted, or if you wish to generate a new one
|
|
|
91 for some reason, use the program @code{gen-index}
|
|
|
92 (@pxref{gen-index,,Regenerating the index}).
|
|
|
93
|
|
|
94 @item pruning log files
|
|
|
95 @cindex pruning log files
|
|
|
96 Log files often grow to unfathomable proportions. As with gardening, it
|
|
|
97 is best to prune these as they grow, lest they take over your disk and
|
|
|
98 leave you with no room to gather more Problem Reports. If you keep log
|
|
|
99 files, be sure to keep an eye on them. (@xref{Aliases,,Setting up mail
|
|
|
100 aliases}.)
|
|
|
101 @c "gather ye rosebugs while ye may..."
|
|
|
102
|
|
|
103 @item BACKING UP YOUR DATA
|
|
|
104 @cindex BACK UP YOUR DATA
|
|
|
105 Any database is only useful if its data remains uncorrupted and safe.
|
|
|
106 Performing periodic backups ensures that problems like disk crashes and
|
|
|
107 data corruption are reversible.
|
|
|
108
|
|
|
109 @end table
|
|
|
110
|
|
|
111 @xref{Locations,,Where @sc{gnats} lives}.
|
|
|
112
|
|
|
113 @menu
|
|
|
114 * Networked management:: Managing GNATS over a network
|
|
|
115 * Local configuration:: Changing your local configuration
|
|
|
116 * Admin files:: Administrative data files
|
|
|
117 * Admin utils:: Administrative utilities
|
|
|
118 * Internal utils:: Internal utilities
|
|
|
119 @end menu
|
|
|
120
|
|
|
121 @node Networked management
|
|
|
122 @section Managing @sc{gnats} over a network
|
|
|
123 @cindex networked management
|
|
|
124 @cindex managing @sc{gnats} over a network
|
|
|
125
|
|
|
126 If you have installed the @sc{gnats} user tools on machines around your
|
|
|
127 local network, there are a few things you need to remember.
|
|
|
128
|
|
|
129 @code{mkcat} and @code{rmcat} do not update the categories list for
|
|
|
130 other machines on your network which have @code{send-pr} installed,
|
|
|
131 unless those machines share @var{prefix} with the host machine). To
|
|
|
132 update these lists, copy the @code{send-pr} categories list to each of
|
|
|
133 the other hosts. This categories list is
|
|
|
134 @w{@file{@var{prefix}/lib/gnats/@var{site}}}, where @var{site} is the
|
|
|
135 name tag for your local site, as specified in the @file{config} file as
|
|
|
136 @samp{GNATS_SITE} (@pxref{config,,The @code{config} file}).
|
|
|
137
|
|
|
138 It is also important to note that only your local @code{send-pr} has
|
|
|
139 access to this new information; any copies of @code{send-pr} which you
|
|
|
140 have distributed to outside submitters now have outdated category lists.
|
|
|
141 You must either contact your submitters and instruct them to update
|
|
|
142 their copy of the categories list, which they installed in
|
|
|
143 @w{@file{@var{prefix}/lib/gnats/@var{support-site}}} from the
|
|
|
144 distribution you provided, or you must build another distribution of
|
|
|
145 @code{send-pr} with this new information and redistribute it.
|
|
|
146
|
|
|
147 If you need to use @sc{gnats} utilities, like @code{query-pr} and
|
|
|
148 @code{edit-pr}, on other systems besides the one where @sc{gnats} itself
|
|
|
149 resides, @pxref{Installing tools,,Installing the user tools}.
|
|
|
150
|
|
|
151 @c FIXME - anything else?
|
|
|
152
|
|
|
153 @node Local configuration
|
|
|
154 @section Changing your local configuration
|
|
|
155 @cindex local configuration
|
|
|
156 @cindex changing your local configuration
|
|
|
157
|
|
|
158 @xref{Locations,,Where @sc{gnats} lives}.
|
|
|
159
|
|
|
160 Your local configuration is determined by the data files in the
|
|
|
161 directory @w{@file{@var{GNATS_ROOT}/gnats-adm}}. These can be altered at
|
|
|
162 any time by editing the pertinent file.
|
|
|
163
|
|
|
164 @table @code
|
|
|
165 @cindex @code{config} file
|
|
|
166 @item config
|
|
|
167 Variables which control certain behavior. @xref{config,,The
|
|
|
168 @code{config} file}. Behaviors you can change here include
|
|
|
169
|
|
|
170 @itemize @bullet
|
|
|
171 @item
|
|
|
172 The address where your site receives Problem Reports.
|
|
|
173
|
|
|
174 @item
|
|
|
175 The address of the @sc{gnats} administrator.
|
|
|
176
|
|
|
177 @item
|
|
|
178 The nametag for your Support Site (your organization, company,
|
|
|
179 group, etc.).
|
|
|
180
|
|
|
181 @item
|
|
|
182 The nametag for your local Submitter Site.
|
|
|
183
|
|
|
184 @item
|
|
|
185 The default release for your site.
|
|
|
186
|
|
|
187 @item
|
|
|
188 The default value for the @samp{>Organization:} field (this value
|
|
|
189 appears as the default when you run @code{send-pr}).
|
|
|
190
|
|
|
191 @item
|
|
|
192 Whether or not to remind maintainers if a requisite time period has
|
|
|
193 passed before they change the state of a Problem Report to
|
|
|
194 @samp{analyzed}. (Also see @ref{submitters,,The @code{submitters}
|
|
|
195 file}, and @ref{at-pr,,Timely Reminders}.
|
|
|
196
|
|
|
197 @item
|
|
|
198 Whether or not to send an automatic acknowledgement to the originator of
|
|
|
199 a problem report when the @sc{gnats} first receives the PR.
|
|
|
200
|
|
|
201 @item
|
|
|
202 The value @sc{gnats} assigns to PRs which come in with missing or unknown
|
|
|
203 values for the @samp{>Submitter-Id:} field.
|
|
|
204
|
|
|
205 @item
|
|
|
206 Whether or not @sc{gnats} should retain @samp{Received:}
|
|
|
207 mail headers from incoming mail.
|
|
|
208
|
|
|
209 @item
|
|
|
210 Whether or not @sc{gnats} is in a mode for debugging.
|
|
|
211
|
|
|
212 @item
|
|
|
213 The values which define business hours.
|
|
|
214 @end itemize
|
|
|
215
|
|
|
216 @cindex @code{categories} file
|
|
|
217 @item categories
|
|
|
218 The list of categories that @sc{gnats} accepts as valid for the
|
|
|
219 @samp{>Category:} field, and the maintainers responsible for each
|
|
|
220 category. Update this file whenever you have a new category, or
|
|
|
221 whenever a category is no longer valid. You must also update this file
|
|
|
222 whenever responsiblility for a category changes, or if a maintainer is
|
|
|
223 no longer valid. @xref{categories,,The @code{categories} file}. Also
|
|
|
224 see @ref{mkcat,,Adding a new problem category}, and @ref{rmcat,,Removing
|
|
|
225 a problem category}.
|
|
|
226
|
|
|
227 @cindex @code{responsible} file
|
|
|
228 @item responsible
|
|
|
229 The list of maintainers. Update this file whenever you have a new
|
|
|
230 maintainer, or whenever a maintainer is no longer valid.
|
|
|
231 @xref{responsible,,The @code{responsible} file}.
|
|
|
232
|
|
|
233 @cindex @code{submitters} file
|
|
|
234 @item submitters
|
|
|
235 The list of Submitter Sites from whom @sc{gnats} accepts Problem Reports.
|
|
|
236 This file is mandatory, although the feature it provides is not; see
|
|
|
237 @ref{submitters,,The @code{submitters} file}.
|
|
|
238 @end table
|
|
|
239
|
|
|
240 @menu
|
|
|
241 * default behavior::
|
|
|
242 * config:: The `config' file
|
|
|
243 * categories:: The `categories' file
|
|
|
244 * responsible:: The `responsible' file
|
|
|
245 * submitters:: The `submitters' file
|
|
|
246 @end menu
|
|
|
247
|
|
|
248 @node default behavior
|
|
|
249 @subsection Default behavior
|
|
|
250
|
|
|
251 The default behavior for @sc{gnats} is as follows:
|
|
|
252
|
|
|
253 @cindex default behavior
|
|
|
254 @itemize @bullet
|
|
|
255 @item
|
|
|
256 The address where your site receives Problem Reports is @samp{bugs} (a
|
|
|
257 local address).
|
|
|
258
|
|
|
259 @item
|
|
|
260 The address of the @sc{gnats} administrator is @samp{gnats-admin} (a local
|
|
|
261 address).
|
|
|
262
|
|
|
263 @item
|
|
|
264 The nametag for your Support Site (your organization, company, group,
|
|
|
265 etc.) is the second-to-last field in your domain name.
|
|
|
266
|
|
|
267 @item
|
|
|
268 The nametag for your local Submitter Site is the nametag for your
|
|
|
269 Support Site.
|
|
|
270
|
|
|
271 @item
|
|
|
272 The default release for your site is @samp{unknown-1.0}.
|
|
|
273
|
|
|
274 @item
|
|
|
275 The default value for the @samp{>Organization:} field (this value appears as the
|
|
|
276 default when you run @code{send-pr}) is the nametag for your Support
|
|
|
277 Site.
|
|
|
278
|
|
|
279 @item
|
|
|
280 @sc{gnats} reminds maintainers if a requisite time period has passed
|
|
|
281 before they change the state of a Problem Report to @samp{analyzed}.
|
|
|
282
|
|
|
283 @item
|
|
|
284 An automatic acknowledgement is sent to the originator of a problem
|
|
|
285 report when the @sc{gnats} first receives the PR.
|
|
|
286
|
|
|
287 @item
|
|
|
288 The value @sc{gnats} assigns to the @samp{>Submitter-Id:} field in PRs
|
|
|
289 which arrive with missing or unknown values for that field is
|
|
|
290 @samp{unknown}.
|
|
|
291
|
|
|
292 @item
|
|
|
293 @samp{Received@dots{}} mail headers are retained.
|
|
|
294
|
|
|
295 @item
|
|
|
296 @sc{gnats} is not in a debugging mode.
|
|
|
297
|
|
|
298 @item
|
|
|
299 @dfn{business hours} are defined as 8:00am to 5:00pm, Monday through
|
|
|
300 Friday.
|
|
|
301 @end itemize
|
|
|
302
|
|
|
303
|
|
|
304 @node config
|
|
|
305 @subsection The @code{config} file
|
|
|
306 @cindex @code{config} file
|
|
|
307
|
|
|
308 Much of the behavior @sc{gnats} exhibits depends on the values of fields
|
|
|
309 in the file @w{@file{@var{GNATS_ROOT}/gnats-adm/config}}. The
|
|
|
310 @file{config} file contains a list of variables (using Bourne-shell
|
|
|
311 syntax) which control the following behavior. These values can be
|
|
|
312 changed at any time; the new values take effect for all subsequent
|
|
|
313 iterations of the tools.
|
|
|
314
|
|
|
315 @table @code
|
|
|
316 @cindex @code{GNATS_ADDR}
|
|
|
317 @item GNATS_ADDR="@var{address}"
|
|
|
318 The address where your site receives Problem Reports. This address is
|
|
|
319 aliased in the file @w{@file{/etc/aliases}} so that it directs incoming
|
|
|
320 mail into @code{queue-pr} (@pxref{Installing utils,,Installing the
|
|
|
321 utilities}).
|
|
|
322
|
|
|
323 The default is @samp{bugs} (a local address).
|
|
|
324
|
|
|
325 @cindex @code{GNATS_ADMIN}
|
|
|
326 @item GNATS_ADMIN="@var{address}"
|
|
|
327 The address of the @sc{gnats} administrator. Normally this is set to
|
|
|
328 @samp{gnats-admin}, which is an alias in @file{/etc/aliases} that points
|
|
|
329 toward the person responsible for administrating @sc{gnats}.
|
|
|
330 @xref{Installing utils,,Installing the utilities}.
|
|
|
331
|
|
|
332 The default is @samp{gnats-admin} (a local address).
|
|
|
333
|
|
|
334 @cindex @code{GNATS_SITE}
|
|
|
335 @item GNATS_SITE="@var{site}"
|
|
|
336 The nametag for your Support Site (your organization, company, group,
|
|
|
337 etc.). This nametag should also appear in the @file{submitters} file,
|
|
|
338 so that users at your site can submit Problem Reports locally.
|
|
|
339
|
|
|
340 @var{site} is also used as the name of the file containing a valid
|
|
|
341 category list for your site. This file is installed locally as
|
|
|
342 @w{@file{@var{prefix}/lib/gnats/@var{site}}}. @emph{Warning:} if you
|
|
|
343 change this variable after @sc{gnats} is installed, you must also change
|
|
|
344 the name of this file, as well as the name of the alias for your local
|
|
|
345 submitters (@pxref{Aliases,,Setting up mail aliases}).
|
|
|
346
|
|
|
347 The default is the second-to-last field in your domain name. For
|
|
|
348 example, if your domain name is @w{@samp{unleaded.truckstop.org}}, your
|
|
|
349 default @var{site} is @w{@samp{truckstop}}.
|
|
|
350
|
|
|
351 @cindex @code{SUBMITTER}
|
|
|
352 @item SUBMITTER="@var{submitter-id}"
|
|
|
353 The nametag for your local Submitter Site (this value appears as the
|
|
|
354 default value for @samp{>Submitter-Id} when you run @code{send-pr}).
|
|
|
355 Even though you are a Support Site, if you submit Problem Reports to
|
|
|
356 your own organization you become a Submitter Site. The value
|
|
|
357 @var{submitter-id} is the default value for the @samp{>Submitter-Id:}
|
|
|
358 field that your maintainers see when they submit Problem Reports
|
|
|
359 locally.
|
|
|
360
|
|
|
361 The default is the value of @samp{GNATS_SITE}.
|
|
|
362
|
|
|
363 @cindex @code{DEFAULT_RELEASE}
|
|
|
364 @item DEFAULT_RELEASE="@var{release}"
|
|
|
365 The default release for your site (this value appears as the default
|
|
|
366 value for @samp{>Release:} when you run @code{send-pr}).
|
|
|
367
|
|
|
368 The default is @samp{unknown-1.0}.
|
|
|
369
|
|
|
370 @cindex @code{DEFAULT_ORGANIZATION}
|
|
|
371 @item DEFAULT_ORGANIZATION="@var{text}"
|
|
|
372 The default value for the @samp{>Organization:} field (this value
|
|
|
373 appears as the default when you run @code{send-pr}).
|
|
|
374
|
|
|
375 The default is the value of @samp{GNATS_SITE}.
|
|
|
376
|
|
|
377 @c FIXME - where else to mention this stuff?
|
|
|
378 @cindex @code{NOTIFY}
|
|
|
379 @item NOTIFY=@var{boolean}
|
|
|
380 Determines whether or not to remind maintainers if a requisite time
|
|
|
381 period has passed before they change the state of a Problem Report to
|
|
|
382 @samp{analyzed}. This feature uses the program @code{at-pr}; see
|
|
|
383 @ref{at-pr,,Timely Reminders}.
|
|
|
384
|
|
|
385 This requisite time is determined for each submitter individually; see
|
|
|
386 @ref{submitters,,The @code{submitters} file}. The time is measured in
|
|
|
387 @dfn{business hours}, which by default are 8:00am to 5:00pm, Monday
|
|
|
388 through Friday. Business hours can be redefined by changing the
|
|
|
389 variables @code{BDAY_START}, @code{BDAY_END}, @code{BWEEK_START}, and
|
|
|
390 @code{BWEEK_END} in the @file{config} file (see below).
|
|
|
391
|
|
|
392 If @var{boolean} is @samp{1}, this feature is active. If @var{boolean}
|
|
|
393 is @samp{0}, the feature is turned off. The default value for
|
|
|
394 @samp{NOTIFY} is @samp{1}.
|
|
|
395
|
|
|
396 @cindex @code{ACKNOWLEDGE}
|
|
|
397 @item ACKNOWLEDGE=@var{boolean}
|
|
|
398 Determines whether or not to send an automatic acknowledgement to the
|
|
|
399 originator of a problem report when the @sc{gnats} first receives the PR.
|
|
|
400
|
|
|
401 If @var{boolean} is @samp{1}, this feature is active. If @var{boolean}
|
|
|
402 is @samp{0}, the feature is turned off. The default for
|
|
|
403 @samp{ACKNOWLEDGE} is @samp{1}.
|
|
|
404
|
|
|
405 The acknowledgment is of the form:
|
|
|
406
|
|
|
407 @smallexample
|
|
|
408 @group
|
|
|
409 To: @var{your-address}
|
|
|
410 From: gnats
|
|
|
411 Subject: Re: @var{category}/@var{gnats-id}:@var{Synopsis}
|
|
|
412 In-Reply-To: Your message of @var{date}
|
|
|
413
|
|
|
414 Thank you very much for your problem report.
|
|
|
415 It has the internal identification: @var{category}/@var{gnats-id}
|
|
|
416 The individual assigned to look at your bug is:
|
|
|
417 @var{responsible}
|
|
|
418
|
|
|
419 Category: @var{category of the PR}
|
|
|
420 Responsible: @var{responsible}
|
|
|
421 Synopsis: @var{Synopsis from submitted PR}
|
|
|
422 Arrival-Date: @var{arrival date}
|
|
|
423 @end group
|
|
|
424 @end smallexample
|
|
|
425
|
|
|
426 @cindex @code{DEFAULT_SUBMITTER}
|
|
|
427 @item DEFAULT_SUBMITTER="submitter-id"
|
|
|
428 The value @sc{gnats} assigns to PRs which come in with missing or unknown
|
|
|
429 values for the @samp{>Submitter-Id:} field. This value must also appear
|
|
|
430 in the @file{submitters} file; see @ref{submitters,,The
|
|
|
431 @code{submitters} file}.
|
|
|
432
|
|
|
433 @cindex disabling @var{submitter-id}
|
|
|
434 To disable the feature of @sc{gnats} which tracks the
|
|
|
435 @samp{>Submitter-Id:}, simply alter the @file{submitters} file to only
|
|
|
436 contain the @var{submitter-id} value which appears in
|
|
|
437 @w{@code{DEFAULT_SUBMITTER}}, and and instruct your submitters to ignore
|
|
|
438 the field.
|
|
|
439
|
|
|
440 The default value for @samp{DEFAULT_SUBMITTER} is @samp{unknown}.
|
|
|
441
|
|
|
442 @cindex @code{KEEP_RECEIVED_HEADERS}
|
|
|
443 @item KEEP_RECEIVED_HEADERS=@var{boolean}
|
|
|
444 Determines whether or not @sc{gnats} should retain the
|
|
|
445 @w{@samp{Received:}} mail headers from incoming mail. These headers
|
|
|
446 often take up a lot of space, and they are seldom used.
|
|
|
447
|
|
|
448 If @var{boolean} is @samp{1}, this feature is active. If @var{boolean}
|
|
|
449 is @samp{0}, the feature is turned off. The default value for
|
|
|
450 @samp{KEEP_RECEIVED_HEADERS} is @samp{1}.
|
|
|
451
|
|
|
452 @item DEBUG_MODE=@var{boolean}
|
|
|
453 Determines whether or not @sc{gnats} is operating in a mode for
|
|
|
454 debugging. When @var{boolean} is @samp{1}, @sc{gnats} fowards all mail
|
|
|
455 to the @sc{gnats} administrator, @w{@code{gnats-admin}}.
|
|
|
456
|
|
|
457 @cindex business hours
|
|
|
458 @item BDAY_START=@var{integer}
|
|
|
459 @itemx BDAY_END=@var{integer}
|
|
|
460 @itemx BWEEK_START=@var{integer}
|
|
|
461 @itemx BWEEK_END=@var{integer}
|
|
|
462 The definition of @dfn{business hours}. These values are only used if
|
|
|
463 @code{NOTIFY} is set to @samp{1} in the @file{config} file (see above).
|
|
|
464
|
|
|
465 By default, business hours are 8:00am to 5:00pm Monday through Friday,
|
|
|
466 local time.
|
|
|
467
|
|
|
468 @table @code
|
|
|
469 @item BDAY_START=@var{integer}
|
|
|
470 Defines the hour of the day when business hours begin. @var{integer}
|
|
|
471 values must fall between @samp{0} (midnight) and @samp{23} (11:00pm).
|
|
|
472 The default is @samp{8} (8:00am).
|
|
|
473
|
|
|
474 @item BDAY_END=@var{integer}
|
|
|
475 Defines the hour of the day when business hours end. @var{integer}
|
|
|
476 values must fall between @samp{0} (midnight) and @samp{23} (11:00pm).
|
|
|
477 The default is @samp{17} (5:00pm).
|
|
|
478
|
|
|
479 @item BWEEK_START=@var{integer}
|
|
|
480 Defines the beginning day of the business week. @var{integer} values
|
|
|
481 must fall between @samp{0} (Sunday) and @samp{6} (Saturday). The
|
|
|
482 default is @samp{1} (Monday).
|
|
|
483
|
|
|
484 @item BWEEK_END=@var{integer}
|
|
|
485 Defines the ending day of the business week. @var{integer} values must
|
|
|
486 fall between @samp{0} (Sunday) and @samp{6} (Saturday). The default is
|
|
|
487 @samp{5} (Friday).
|
|
|
488 @end table
|
|
|
489
|
|
|
490 @end table
|
|
|
491
|
|
|
492 @node categories
|
|
|
493 @subsection The @code{categories} file
|
|
|
494 @cindex @code{categories} file
|
|
|
495
|
|
|
496 The @file{categories} file contains a list of problem categories,
|
|
|
497 specific to your site, which @sc{gnats} tracks. This file also matches
|
|
|
498 responsible people with these categories. You must edit this file
|
|
|
499 initially, creating valid categories and then running @code{mkcat} to
|
|
|
500 create the corresponding subdirectories of @w{@code{@var{GNATS_ROOT}}}
|
|
|
501 and update the valid categories list for @w{@code{send-pr}}. For
|
|
|
502 instructions on running @code{mkcat}, see @ref{mkcat,,Adding a problem
|
|
|
503 category}.
|
|
|
504
|
|
|
505 To create a new category, log in as @sc{gnats}, add a line to this file,
|
|
|
506 and run @code{mkcat}. Lines beginning with @samp{#} are ignored.
|
|
|
507
|
|
|
508 A line in the @file{categories} file consists of four fields delimited
|
|
|
509 by colons, as follows:
|
|
|
510
|
|
|
511 @smallexample
|
|
|
512 @var{category}:@var{description}:@var{responsible}:@var{notify}
|
|
|
513 @end smallexample
|
|
|
514
|
|
|
515 @noindent
|
|
|
516 @table @var
|
|
|
517 @item category
|
|
|
518 A unique category name, made up of text characters. This name cannot
|
|
|
519 contain spaces or any of the following characters:
|
|
|
520
|
|
|
521 @smallexample
|
|
|
522 ! $ & * ( ) @{ @} [ ] ` ' " ; : < > ~
|
|
|
523 @end smallexample
|
|
|
524
|
|
|
525 @noindent
|
|
|
526 Ideally, category names should not contain commas or begin with periods.
|
|
|
527 Each line has a corresponding subdirectory in the main @sc{gnats}
|
|
|
528 directory (@var{GNATS_ROOT}).
|
|
|
529
|
|
|
530 @ignore
|
|
|
531 It is possible that if you set up the database with categories
|
|
|
532 which contain characters that describe subdirectories, such as a slash
|
|
|
533 (@key{/}) in @sc{Unix}, you could effectively build subdirectories
|
|
|
534 within each category, and @sc{gnats} would read and write to these
|
|
|
535 files as it would any other. This is not recommended. It doesn't
|
|
|
536 break any of the existing tools, and is a fine way to keep category
|
|
|
537 directories from growing too large. It is, however, quite untested.
|
|
|
538 @end ignore
|
|
|
539
|
|
|
540 @item description
|
|
|
541 A terse textual description of the category.
|
|
|
542
|
|
|
543 @item responsible
|
|
|
544 The name tag of the party responsible for this category of problems, as
|
|
|
545 listed in the @file{responsible} file (@pxref{responsible,,The
|
|
|
546 @code{responsible} file}).
|
|
|
547
|
|
|
548 @item notify
|
|
|
549 One or more other parties which should be notified when a Problem Report
|
|
|
550 with this category arrives, such as a project manager, other members of
|
|
|
551 the same project, other interested parties, or even log files. These
|
|
|
552 should be separated with commas.
|
|
|
553 @end table
|
|
|
554
|
|
|
555 A good strategy for configuring this file is to have a different
|
|
|
556 category for each product your organization supports or wishes to track
|
|
|
557 information for, or perhaps with sub-categories within each category.
|
|
|
558 For instance, if you wish to track documentation problems in a variety of
|
|
|
559 areas, you could have entries such as
|
|
|
560
|
|
|
561 @smallexample
|
|
|
562 doc:General Doc Questions:myboss:me,barney
|
|
|
563 doc-rock:Doc for ROCK program:me:myboss
|
|
|
564 doc-stone:Docs for STONE utils:barney:fred
|
|
|
565 doc-local:in-house documentation:me:doc-local-log
|
|
|
566 @end smallexample
|
|
|
567
|
|
|
568 In the above example, the nametags @samp{myboss}, @samp{me},
|
|
|
569 @samp{fred}, and @samp{barney} must be defined in the @file{responsible}
|
|
|
570 file (@pxref{responsible,,The @code{responsible} file}).
|
|
|
571
|
|
|
572 Problem Reports with a category of @samp{doc} are sent to the local mail
|
|
|
573 address (or alias) @samp{myboss}, and also sent to the addresses
|
|
|
574 @samp{me} and @samp{barney}. PRs with a category of @samp{doc-rock} are
|
|
|
575 sent to the local addresses @samp{me} and @samp{myboss} only, while PRs
|
|
|
576 with the category @samp{doc-stone} are sent to @samp{fred} as well as to
|
|
|
577 @samp{barney}. PRs with a category of @samp{doc-local} are sent only to
|
|
|
578 @samp{me}, and are also filed in @code{doc-local-log} (in this case, an
|
|
|
579 alias should be set up in @file{/etc/aliases} to reflect a location for
|
|
|
580 the log file, such as @w{@samp{doc-local-log: /users/me/local-log}}).
|
|
|
581
|
|
|
582 Whenever you add a new category, be sure to run @code{mkcat} to create a
|
|
|
583 subdirectory for it and update the local categories list.
|
|
|
584
|
|
|
585 Only one category must be present for @sc{gnats} to function:
|
|
|
586
|
|
|
587 @smallexample
|
|
|
588 pending:Category for faulty PRs: gnats-admin:
|
|
|
589 @end smallexample
|
|
|
590
|
|
|
591 @cindex @code{pending} file
|
|
|
592 The @file{pending} directory is created automatically when you run
|
|
|
593 @w{@samp{make install}} (@pxref{Configure and make,,Configuring and
|
|
|
594 compiling the software}).
|
|
|
595
|
|
|
596 @node responsible
|
|
|
597 @subsection The @code{responsible} file
|
|
|
598 @cindex @code{responsible} file
|
|
|
599
|
|
|
600 This file contains a list of the responsible parties. Lines beginning
|
|
|
601 with @samp{#} are ignored. Each entry contains three fields, separated
|
|
|
602 by colons:
|
|
|
603
|
|
|
604 @smallexample
|
|
|
605 @var{responsible}:@var{full-name}:@var{mail-address}
|
|
|
606 @end smallexample
|
|
|
607
|
|
|
608 @noindent
|
|
|
609 @table @var
|
|
|
610 @item responsible
|
|
|
611 A name-tag description of the party in question, such as her or his user
|
|
|
612 name, or the name of the group. This name is listed in the PR in
|
|
|
613 the @samp{>Responsible:} field.
|
|
|
614
|
|
|
615 @item full-name
|
|
|
616 The full name of the party (``Charlotte Bronte''; ``Compiler Group'').
|
|
|
617
|
|
|
618 @item mail-address
|
|
|
619 The full, valid mail address of the party. This field is only necessary
|
|
|
620 if the responsible party has no local mail address or alias.
|
|
|
621 @end table
|
|
|
622
|
|
|
623 @noindent
|
|
|
624 A sample @file{responsible} listing might be:
|
|
|
625
|
|
|
626 @smallexample
|
|
|
627 ren:Ren Hoek:
|
|
|
628 stimpy:Stimpson J. Cat:stimpy@@lederhosen.org
|
|
|
629 @end smallexample
|
|
|
630
|
|
|
631 Here, @code{ren} is a local user. @code{stimpy} is remote, so his full
|
|
|
632 address must be specified.
|
|
|
633
|
|
|
634 The following entry must be present for @sc{gnats} to function:
|
|
|
635
|
|
|
636 @smallexample
|
|
|
637 gnats-admin: GNATS administrator:
|
|
|
638 @end smallexample
|
|
|
639
|
|
|
640 @noindent
|
|
|
641 (@code{gnats-admin} is a mail alias, so for this purpose
|
|
|
642 @code{gnats-admin} is a local address.)
|
|
|
643
|
|
|
644 @node submitters
|
|
|
645 @subsection The @code{submitters} file
|
|
|
646 @cindex @code{submitters} file
|
|
|
647
|
|
|
648 This is a database of sites which submit bugs to your support site. It
|
|
|
649 contains six fields delineated by colons. Lines beginning with @samp{#}
|
|
|
650 will be ignored.
|
|
|
651
|
|
|
652 Entries are of the format:
|
|
|
653
|
|
|
654 @smallexample
|
|
|
655 @var{submitter-id}:@var{name}:@var{type}:@var{resp-time}:@var{contact}:@var{notify}
|
|
|
656 @end smallexample
|
|
|
657
|
|
|
658 @noindent
|
|
|
659 @table @var
|
|
|
660 @item submitter-id
|
|
|
661 A unique identifier for a specific site or other entity who submits
|
|
|
662 Problem Reports.
|
|
|
663
|
|
|
664 @item name
|
|
|
665 A textual description of this entity.
|
|
|
666
|
|
|
667 @item type
|
|
|
668 Optional description for the type of relationship this submitter to your
|
|
|
669 support site. This could indicate a contract type, a level of
|
|
|
670 expertise, etc., or it can remain blank.
|
|
|
671
|
|
|
672 @item resp-time
|
|
|
673 Optional quoted response time, in @dfn{business hours}. @sc{gnats} is
|
|
|
674 capable of reminding responsible parties when Problem Reports marked
|
|
|
675 with a @samp{>Severity} value of @samp{critical}, or those with a
|
|
|
676 @samp{>Severity} of @samp{serious} and a @samp{>Priority} value of
|
|
|
677 @samp{high}, are neglected for a certain period. This argument defines
|
|
|
678 that response period for each @var{submitter-id}. Business hours are
|
|
|
679 defined by default as 8:00am to 5:00pm, Monday through Friday. For
|
|
|
680 example, three business days would be equal to 24 business hours.
|
|
|
681
|
|
|
682 This function is active if the @code{NOTIFY} field is defined as
|
|
|
683 @samp{1} in the @file{config} file (@pxref{Local configuration,,Changing
|
|
|
684 your local configuration}). If @code{NOTIFY} is @samp{0}, this field is
|
|
|
685 ignored. For information on @code{at-pr}, the program which sends out
|
|
|
686 this reminder, see @ref{at-pr,,Timely Reminders}.
|
|
|
687
|
|
|
688 @item contact
|
|
|
689 The name tag of the main @dfn{contact} at the Support Site for this
|
|
|
690 submitter. This contact should be in the @file{responsible} file
|
|
|
691 (@pxref{responsible,,The @code{responsible} file}). Incoming bugs from
|
|
|
692 @var{submitter} are sent to this contact. Optionally, this field can be
|
|
|
693 left blank.
|
|
|
694
|
|
|
695 @item notify
|
|
|
696 Any other parties who should receive copies of Problem Reports sent in
|
|
|
697 by @var{submitter}.
|
|
|
698 @end table
|
|
|
699
|
|
|
700 A few example entries in the @file{submitters} file:
|
|
|
701
|
|
|
702 @smallexample
|
|
|
703 univ-hell: University of Hades:eternal:3:beelzebub:lucifer
|
|
|
704 tta: Telephones and Telegraphs of America:support:720:dave:
|
|
|
705 @end smallexample
|
|
|
706
|
|
|
707 @noindent
|
|
|
708 In this example, when a PR comes in from the University of Hades (who
|
|
|
709 has an eternal contract), it should have @samp{univ-hell} in its
|
|
|
710 @samp{Submitter-Id} field. This Problem Report goes to @code{beelzebub}
|
|
|
711 (who should be in the @file{responsible} file), and if it is not
|
|
|
712 analyzed within three business hours a reminder message is sent.
|
|
|
713 @code{lucifer} also receives a copy of the bug, and a copy of the
|
|
|
714 reminder message as well (if it is sent). When Telephones and
|
|
|
715 Telegraphs of America utilizes their support contract and submits a bug,
|
|
|
716 a copy is sent only to @code{dave}, who has 720 business hours to return
|
|
|
717 an analysis before a reminder is sent.
|
|
|
718
|
|
|
719 @cindex disabling @var{submitter-id}
|
|
|
720 To disable the feature of @sc{gnats} which tracks the
|
|
|
721 @samp{>Submitter-Id:}, simply alter the @file{submitters} file to only
|
|
|
722 contain the @var{submitter-id} value which appears as the
|
|
|
723 @samp{DEFAULT_SUBMITTER} value in the @file{config} file
|
|
|
724 (@pxref{config,,The @code{config} file}), and instruct your submitters
|
|
|
725 to ignore the field.
|
|
|
726
|
|
|
727 @node Admin files
|
|
|
728 @section Administrative data files
|
|
|
729 @cindex admin files
|
|
|
730 @cindex files used for @sc{gnats} administration
|
|
|
731
|
|
|
732 The following files are located in @file{@var{GNATS_ROOT}/gnats-adm},
|
|
|
733 where @var{GNATS_ROOT} is the resident directory of @sc{gnats}. These
|
|
|
734 files are maintained by @sc{gnats}; you should never touch them.
|
|
|
735
|
|
|
736 @menu
|
|
|
737 * index file:: The `index' file
|
|
|
738 * current file:: The `current' file
|
|
|
739 @end menu
|
|
|
740
|
|
|
741 @node index file
|
|
|
742 @subsection The @code{index} file
|
|
|
743 @cindex @code{index} file
|
|
|
744
|
|
|
745 The index is used to accelerate searches on the database by
|
|
|
746 @code{query-pr} and @code{edit-pr}. This file is not created until the
|
|
|
747 first PR comes in. It is then kept up to date by @sc{gnats}; you should
|
|
|
748 never touch this file.
|
|
|
749
|
|
|
750 Any searches on subjects contained in the index are much faster than
|
|
|
751 searches which depend on data not in the index. The index contains
|
|
|
752 single-line entries for the following fields, in order, separated by
|
|
|
753 colons (@samp{:}) except for @samp{>Category:} and @samp{>Number:},
|
|
|
754 which are separated by a slash (@samp{/}) (the @samp{>} and @samp{:}
|
|
|
755 Problem Report fieldname delimiters have been removed for the sake of
|
|
|
756 brevity and readability)::
|
|
|
757
|
|
|
758 @smallexample
|
|
|
759 Category Number Submitter-Id
|
|
|
760 Responsible State Confidential
|
|
|
761 Severity Priority
|
|
|
762 @end smallexample
|
|
|
763
|
|
|
764 To see an example index, run @code{gen-index} without any options
|
|
|
765 (@pxref{gen-index,,Regenerating the index}).
|
|
|
766
|
|
|
767 @node current file
|
|
|
768 @subsection The @code{current} file
|
|
|
769 @cindex @code{current} file
|
|
|
770
|
|
|
771 This file contains the last serial number assigned to an incoming PR.
|
|
|
772 It is used internally by @sc{gnats}; you need never touch this file.
|
|
|
773
|
|
|
774 @node Admin utils
|
|
|
775 @section Administrative utilities
|
|
|
776 @cindex administrative utilities
|
|
|
777
|
|
|
778 These tools are used by the @sc{gnats} administrator as part of the
|
|
|
779 periodic maintenance and configuration of @sc{gnats}.
|
|
|
780 @xref{Management,,@sc{gnats} Administration}.
|
|
|
781
|
|
|
782 @menu
|
|
|
783 * mkcat:: Adding a problem category
|
|
|
784 * rmcat:: Removing a problem category
|
|
|
785 * gen-index:: Regenerating the index
|
|
|
786 * mkdist:: Configuring send-pr for the outside world
|
|
|
787 @end menu
|
|
|
788
|
|
|
789 @node mkcat
|
|
|
790 @subsection Adding a problem category
|
|
|
791 @cindex @code{mkcat}
|
|
|
792 @cindex adding a problem category
|
|
|
793 @cindex new problem categories
|
|
|
794 @cindex @code{categories} file
|
|
|
795
|
|
|
796 To add new categories to the database:
|
|
|
797
|
|
|
798 @enumerate 1
|
|
|
799 @item
|
|
|
800 Add a line to the @file{categories} file under
|
|
|
801 @w{@file{@var{GNATS_ROOT}/gnats-adm}} for each new category.
|
|
|
802 @xref{categories,,The @code{categories} file}.
|
|
|
803
|
|
|
804 @item
|
|
|
805 Run @code{mkcat}. @code{mkcat} creates a directory under
|
|
|
806 @w{@var{GNATS_ROOT}} for any new categories which appear in the
|
|
|
807 @file{categories} file. @code{mkcat} also recreates the list of valid
|
|
|
808 categories for both your locally installed @code{send-pr} and for the
|
|
|
809 @code{send-pr} distribution template in
|
|
|
810 @w{@file{@var{prefix}/lib/gnats/dist}} (@pxref{Locations,,Where @sc{gnats}
|
|
|
811 lives}.
|
|
|
812 @end enumerate
|
|
|
813
|
|
|
814 @emph{Note:} @code{mkcat} does not update the categories list for other
|
|
|
815 machines on your network which have @code{send-pr} installed (unless
|
|
|
816 the two machines share the directory @var{prefix}).
|
|
|
817 @xref{Networked management,,Managing @sc{gnats} over a network}.
|
|
|
818
|
|
|
819 It is also important to note that only your local @code{send-pr} has
|
|
|
820 access to this new information; any copies of @code{send-pr} which you
|
|
|
821 have distributed to outside submitters now have outdated category lists.
|
|
|
822 You must either contact your submitters and instruct them to update
|
|
|
823 their copy of the categories list, which they installed in
|
|
|
824 @w{@file{@var{prefix}/lib/gnats/@var{support-site}}} (@emph{Note:} the
|
|
|
825 value for @var{prefix} may be different from yours) from the
|
|
|
826 distribution you provided, or you must build another distribution of
|
|
|
827 @code{send-pr} with this new information and redistribute it
|
|
|
828 (@pxref{mkdist,,Configuring @code{send-pr} for the outside world}).
|
|
|
829
|
|
|
830 @node rmcat
|
|
|
831 @subsection Removing a problem category
|
|
|
832 @cindex @code{rmcat}
|
|
|
833 @cindex removing a problem category
|
|
|
834 @cindex @code{categories} file
|
|
|
835
|
|
|
836 To remove a category from the database:
|
|
|
837
|
|
|
838 @enumerate 1
|
|
|
839 @item
|
|
|
840 Remove the Problem Reports from the subdirectories corresponding to the
|
|
|
841 categories you wish to remove, or assign the PRs to new categories. All
|
|
|
842 PRs for a given category reside in
|
|
|
843 @w{@file{@var{GNATS_ROOT}/@var{category}}}. Make sure you do this for
|
|
|
844 each category you wish to remove.
|
|
|
845
|
|
|
846 @item
|
|
|
847 Run @code{rmcat} using
|
|
|
848
|
|
|
849 @smallexample
|
|
|
850 rmcat @var{category} [ @var{category@dots{}} ]
|
|
|
851 @end smallexample
|
|
|
852
|
|
|
853 @noindent
|
|
|
854 where @var{category} is the category you wish to remove. You can
|
|
|
855 specify as many categories as you wish as long as each category has no
|
|
|
856 PRs associated with it. @code{rmcat} removes the directory under
|
|
|
857 @w{@var{GNATS_ROOT}} where the Problem Reports for that category had been
|
|
|
858 stored. @code{rmcat} also deletes the category from the list of valid
|
|
|
859 categories for both your locally installed @code{send-pr} and for the
|
|
|
860 @code{send-pr} distribution template in
|
|
|
861 @w{@file{@var{prefix}/lib/gnats/dist}} (@pxref{Locations,,Where @sc{gnats}
|
|
|
862 lives}).
|
|
|
863 @end enumerate
|
|
|
864
|
|
|
865 @emph{Note:} @code{rmcat} does not update the categories list for other
|
|
|
866 machines on your network which have @code{send-pr} installed.
|
|
|
867 @xref{Networked management,,Managing @sc{gnats} over a network}.
|
|
|
868
|
|
|
869 It is also important to note that only your local @code{send-pr} has
|
|
|
870 access to this new information; any copies of @code{send-pr} which you
|
|
|
871 have distributed to outside submitters now have outdated category lists.
|
|
|
872 You must either contact your submitters and instruct them to update
|
|
|
873 their copy of the categories list, which they installed in
|
|
|
874 @w{@file{@var{prefix}/lib/gnats/@var{support-site}}} (@emph{Note:} the
|
|
|
875 value for @var{prefix} may be different from yours) from the
|
|
|
876 distribution you provided, or you must build another distribution of
|
|
|
877 @code{send-pr} with this new information and redistribute it
|
|
|
878 (@pxref{mkdist,,Configuring @code{send-pr} for the outside world}).
|
|
|
879
|
|
|
880 @c FIXME! Should we suggest this?
|
|
|
881 @ignore
|
|
|
882 To reassign a group of categories....
|
|
|
883
|
|
|
884 (The idea is to call "query-pr --full", run the output through sed, and
|
|
|
885 then throw it at pr-edit. This approach is untested, and may be unhealthy.)
|
|
|
886
|
|
|
887 @end ignore
|
|
|
888
|
|
|
889 @node gen-index
|
|
|
890 @subsection Regenerating the index
|
|
|
891 @cindex @code{gen-index}
|
|
|
892 @cindex @code{index} file
|
|
|
893
|
|
|
894 If your @file{index} file becomes corrupted, or if you need a copy of
|
|
|
895 the current index for some reason, use
|
|
|
896
|
|
|
897 @smallexample
|
|
|
898 gen-index [ -n | --numeric ]
|
|
|
899 [ -d @var{directory} | --directory=@var{directory} ]
|
|
|
900 [ -c @var{filename} | --catfile=@var{filename} ]
|
|
|
901 [ -o @var{filename} | --outfile=@var{filename} ]
|
|
|
902 [ -h | --help] [ -V | --version ]
|
|
|
903 @end smallexample
|
|
|
904
|
|
|
905 @noindent
|
|
|
906 With no options, @code{gen-index} generates an index that is ordered the
|
|
|
907 same as the order of the categories as they appear in the
|
|
|
908 @file{categories} file, and prints it to standard output. The options
|
|
|
909 are:
|
|
|
910
|
|
|
911 @table @code
|
|
|
912 @item -n
|
|
|
913 @itemx --numeric
|
|
|
914 Sorts index entries numerically.
|
|
|
915
|
|
|
916 @item -d @var{directory}
|
|
|
917 @itemx --directory=@var{directory}
|
|
|
918 Uses @var{directory} as the directory containing the database, by
|
|
|
919 default @w{@var{GNATS_ROOT}} (@pxref{Locations,,Where @sc{gnats} lives}).
|
|
|
920
|
|
|
921 @item -o @var{filename}
|
|
|
922 @itemx --outfile=@var{filename}
|
|
|
923 Places output in @var{filename} rather than sending it to standard
|
|
|
924 output.
|
|
|
925
|
|
|
926 @item -c @var{filename}
|
|
|
927 @itemx --catfile=@var{filename}
|
|
|
928 Point to @var{filename}, the file listing the valid categories.
|
|
|
929
|
|
|
930 @item -h
|
|
|
931 @itemx --help
|
|
|
932 Prints the usage for @code{gen-index}.
|
|
|
933
|
|
|
934 @item -V
|
|
|
935 @itemx --version
|
|
|
936 Prints the version number for @code{gen-index}.
|
|
|
937 @end table
|
|
|
938
|
|
|
939 @node mkdist
|
|
|
940 @subsection Configuring @code{send-pr} for the outside world
|
|
|
941 @cindex configuring @code{send-pr} for the outside world
|
|
|
942 @cindex invoking @code{mkdist}
|
|
|
943 @cindex using @code{mkdist}
|
|
|
944
|
|
|
945 Now that @sc{gnats} is up and running on your system, you probably want
|
|
|
946 to distribute @code{send-pr} to all your friends, relatives, enemies,
|
|
|
947 etc. so they can more easily submit bugs to your organization. To do
|
|
|
948 this, create a new directory @var{dist-directory} to hold the
|
|
|
949 distribution. Then run the program
|
|
|
950
|
|
|
951 @smallexample
|
|
|
952 mkdist --release=@var{release} @var{dist-directory}
|
|
|
953 @end smallexample
|
|
|
954
|
|
|
955 @noindent
|
|
|
956 This populates @var{dist-directory} with a full distribution of the
|
|
|
957 program @code{send-pr}, including a @file{Makefile} and all the
|
|
|
958 @code{send-pr} documentation. You can then simply package up this
|
|
|
959 directory and send it to your bug report submitters. For example,
|
|
|
960 when logged in as @code{gnats} you can do the following:
|
|
|
961
|
|
|
962 @smallexample
|
|
|
963 mkdir new-dist
|
|
|
964 mkdist --release=tools-1.2 new-dist
|
|
|
965 tar cvf send-pr.tar new-dist
|
|
|
966 @end smallexample
|
|
|
967
|
|
|
968 This creates a file called @file{send-pr.tar} which contains a full
|
|
|
969 distribution of @code{send-pr} customized for your site, with a default
|
|
|
970 release number of @samp{tools-1.2}. You can then place this onto a disk
|
|
|
971 or tape and send it to your submitters, or instruct your submitters to
|
|
|
972 download it using @code{ftp}.
|
|
|
973
|
|
|
974 If you only have one submitter, you can set the Submitter ID in the
|
|
|
975 send-pr script by specifying the --submitter option to mkdist. If you
|
|
|
976 do this, the submitter will not have to run install-sid.
|
|
|
977
|
|
|
978 @node Internal utils
|
|
|
979 @section Internal utilities
|
|
|
980 @cindex internal utilities
|
|
|
981
|
|
|
982 These tools are used internally by @sc{gnats}. You should never need to
|
|
|
983 run these by hand; however, a complete understanding may help you locate
|
|
|
984 problems with the @sc{gnats} tools or with your local implementation.
|
|
|
985
|
|
|
986 @menu
|
|
|
987 * queue-pr:: Handling incoming traffic
|
|
|
988 * file-pr:: Processing incoming traffic
|
|
|
989 * at-pr:: Timely reminders
|
|
|
990 * pr-edit:: The edit-pr driver
|
|
|
991 * pr-addr:: Address retrieval
|
|
|
992 @end menu
|
|
|
993
|
|
|
994 @node queue-pr
|
|
|
995 @subsection Handling incoming traffic
|
|
|
996 @cindex @code{queue-pr}
|
|
|
997 @cindex handling incoming traffic
|
|
|
998
|
|
|
999 The program @code{queue-pr} handles traffic coming into @sc{gnats}.
|
|
|
1000 @code{queue-pr} queues incoming Problem Reports in the directory
|
|
|
1001 @w{@file{@var{GNATS_ROOT}/gnats-queue}}, and then periodically (via
|
|
|
1002 @code{cron}) passes them on to @code{file-pr} to be filed in the
|
|
|
1003 @sc{gnats} database. @xref{Installation,,Installing @sc{gnats}}.
|
|
|
1004
|
|
|
1005 The usage for @code{queue-pr} is as follows:
|
|
|
1006
|
|
|
1007 @smallexample
|
|
|
1008 queue-pr [ -q | --queue ] [ -r | --run ]
|
|
|
1009 [ -f @var{filename} | --file=@var{filename} ]
|
|
|
1010 [ -d @var{directory} | --directory=@var{directory} ]
|
|
|
1011 @end smallexample
|
|
|
1012
|
|
|
1013 One of @samp{-q} or @samp{-r} (or their longer-named counterparts) must
|
|
|
1014 be present upon each call to @code{queue-pr}. These options provide
|
|
|
1015 different functions, as described below.
|
|
|
1016
|
|
|
1017 @table @code
|
|
|
1018 @item -q
|
|
|
1019 @itemx --queue
|
|
|
1020 Accepts standard input as an incoming mail message, placing this message
|
|
|
1021 in an incrementally numbered file in the @w{@file{gnats-queue}} directory
|
|
|
1022 under @w{@code{@var{GNATS_ROOT}}} (@pxref{Locations,,Where @sc{gnats}
|
|
|
1023 lives}).
|
|
|
1024
|
|
|
1025 @item -r
|
|
|
1026 @itemx --run
|
|
|
1027 Redirects files in the @file{gnats-queue} directory into the program
|
|
|
1028 @code{file-pr} one by one.
|
|
|
1029
|
|
|
1030 @item -f @var{filename}
|
|
|
1031 @itemx --file=@var{filename}
|
|
|
1032 Used with @samp{-q} (or @samp{--queue}), accepts the file denoted by
|
|
|
1033 @var{filename} as input rather than reading from standard input.
|
|
|
1034
|
|
|
1035 @item -d @var{directory}
|
|
|
1036 @itemx --directory=@var{directory}
|
|
|
1037 Resets the default @var{directory} value, which is by default
|
|
|
1038 @w{@file{@var{GNATS_ROOT}/gnats-queue}}. When @w{@samp{-d
|
|
|
1039 @var{directory}}} is used in conjunction with the @samp{-q} (or
|
|
|
1040 @samp{--queue}) option, @w{@code{queue-pr}} files incoming messages into
|
|
|
1041 @var{directory} rather than the @file{gnats-queue} directory. When
|
|
|
1042 @w{@samp{-d @var{directory}}} is used in conjunction with the @samp{-r}
|
|
|
1043 (or @samp{--run}) option, @code{queue-pr} redirects into
|
|
|
1044 @w{@code{file-pr}} files from @var{directory} rather than from the
|
|
|
1045 @w{@file{gnats-queue}} directory.
|
|
|
1046 @end table
|
|
|
1047
|
|
|
1048 @node file-pr
|
|
|
1049 @subsection Processing incoming traffic
|
|
|
1050 @cindex @code{file-pr}
|
|
|
1051 @cindex processing incoming traffic
|
|
|
1052
|
|
|
1053 @code{queue-pr} hands off queued Problem Reports to @code{file-pr} one
|
|
|
1054 at a time. @code{file-pr} checks each Problem Report for correct
|
|
|
1055 information in its fields (particularly a correct @samp{>Category:}),
|
|
|
1056 assigns it an identification number, and files it in the database under
|
|
|
1057 the appropriate category.
|
|
|
1058
|
|
|
1059 If the @samp{>Category:} field does not contain a valid category value
|
|
|
1060 (i.e., matching a line in the @code{categories} file;
|
|
|
1061 @pxref{categories,,The @code{categories} file}), the PR is given a
|
|
|
1062 @samp{>Category:} value of @samp{pending} and is placed in the
|
|
|
1063 @file{pending} directory. The @sc{gnats} administrator is notified of
|
|
|
1064 the unplaceable PR.
|
|
|
1065
|
|
|
1066 @code{file-pr} assigns the Problem Report an identification number,
|
|
|
1067 files it in the @sc{gnats} database (under @w{@samp{pending}}, if the
|
|
|
1068 @samp{>Category:} field contains an invalid category), and sends
|
|
|
1069 acknowledgements to appropriate parties. The person responsible for
|
|
|
1070 that category of problem (@pxref{categories,,The @code{categories}
|
|
|
1071 file}) and the person responsible for the submitter site where the PR
|
|
|
1072 originated (@pxref{submitters,,The @code{submitters} file}) receive a
|
|
|
1073 copy of the PR in its entirety. Optionally, the originator of the PR
|
|
|
1074 receives an acknowledgement that the PR arrived and was filed
|
|
|
1075 (@pxref{Local configuration,,Changing your local configuration}).
|
|
|
1076
|
|
|
1077 The usage for @code{file-pr} is as follows:
|
|
|
1078
|
|
|
1079 @smallexample
|
|
|
1080 file-pr [ -f @var{filename} | --file=@var{filename} ]
|
|
|
1081 [ -d @var{directory} | --directory=@var{directory}b ]
|
|
|
1082 [ -D | --debug ] [ -h | --help ] [ -V | --version ]
|
|
|
1083 @end smallexample
|
|
|
1084
|
|
|
1085 @code{file-pr} requires no options in order to operate, and takes input
|
|
|
1086 from standard input (normally, the output of @w{@samp{queue-pr -r}})
|
|
|
1087 unless otherwise specified. The options include:
|
|
|
1088
|
|
|
1089 @table @code
|
|
|
1090 @item -f @var{filename}
|
|
|
1091 @itemx --filename=@var{filename}
|
|
|
1092 Uses @var{filename} as input rather than standard input.
|
|
|
1093
|
|
|
1094 @item -d @var{directory}
|
|
|
1095 @itemx --directory=@var{directory}
|
|
|
1096 Performs refiling operations in @var{directory} rather than in
|
|
|
1097 @w{@code{@var{GNATS_ROOT}}}.
|
|
|
1098
|
|
|
1099 @item -D
|
|
|
1100 @itemx --debug
|
|
|
1101 Give debugging output while @code{file-pr} is running.
|
|
|
1102
|
|
|
1103 @item -h
|
|
|
1104 @itemx --help
|
|
|
1105 Prints the usage for @code{file-pr}.
|
|
|
1106
|
|
|
1107 @item -V
|
|
|
1108 @itemx --version
|
|
|
1109 Prints the version number for @code{file-pr}.
|
|
|
1110 @end table
|
|
|
1111
|
|
|
1112 @node at-pr
|
|
|
1113 @subsection Timely reminders
|
|
|
1114 @cindex @code{at-pr}
|
|
|
1115 @cindex timely reminders
|
|
|
1116 @cindex automatic notification
|
|
|
1117 @cindex notification of overdue PRs
|
|
|
1118
|
|
|
1119 @code{at-pr} creates a queued job using @code{at} which, after an
|
|
|
1120 allotted @dfn{response time} is past, checks the PR to see if its state
|
|
|
1121 has changed from @samp{open}.
|
|
|
1122
|
|
|
1123 The @file{submitters} file contains the response time for each
|
|
|
1124 @w{@code{>Submitter-Id:}} (@pxref{submitters,,The @code{submitters} file}).
|
|
|
1125 The time is determined in @dfn{business hours}, which are defined by
|
|
|
1126 default as 8:00am to 5:00pm Monday through Friday, local time. These
|
|
|
1127 hours are defined in the @file{config} file (@pxref{config,,The
|
|
|
1128 @code{config} file}).
|
|
|
1129
|
|
|
1130 If the PR is still open after the requisite time period has passed,
|
|
|
1131 @code{at-pr} sends a reminder to the @sc{gnats} administrator, to the
|
|
|
1132 maintainer responsible for that submitter, and to the maintainer
|
|
|
1133 responsible for the PR with the following message:
|
|
|
1134
|
|
|
1135 @cindex reminder message
|
|
|
1136 @cindex @code{at-pr}
|
|
|
1137 @smallexample
|
|
|
1138 To: @var{submitter-contact} @var{responsible} @var{gnats-admin}
|
|
|
1139 Subject: PR @var{gnats-id} not analyzed in @var{#hours} hours
|
|
|
1140
|
|
|
1141 PR @var{gnats-id} was not analyzed within the acknowledgment period
|
|
|
1142 of @var{#hours} business hours. The pertinent information is:
|
|
|
1143
|
|
|
1144 Submitter-Id: @var{submitter}
|
|
|
1145 Originator: @var{full name of the submitter}
|
|
|
1146 Synopsis: @var{synopsis}
|
|
|
1147 Person responsible for the PR: @var{responsible}
|
|
|
1148
|
|
|
1149 --
|
|
|
1150 The GNU Problem Report Management System (GNATS)
|
|
|
1151 @end smallexample
|
|
|
1152
|
|
|
1153 @node pr-edit
|
|
|
1154 @subsection The @code{edit-pr} driver
|
|
|
1155 @cindex @code{pr-edit}
|
|
|
1156 @cindex @code{edit-pr} driver
|
|
|
1157 @cindex driver for @code{edit-pr}
|
|
|
1158
|
|
|
1159 @code{pr-edit} does the background work for @code{edit-pr}, including
|
|
|
1160 error-checking and refiling newly edited Problem Reports and handling
|
|
|
1161 file locks. It can be called interactively, though it has no useable
|
|
|
1162 editing interface.
|
|
|
1163
|
|
|
1164 The usage for @code{pr-edit} is:
|
|
|
1165
|
|
|
1166 @smallexample
|
|
|
1167 pr-edit [ -l @var{maintainer} --lock=@var{maintainer} ]
|
|
|
1168 [ -u | --unlock ] [ -c | --check ] [ -F ]
|
|
|
1169 [ -L | --lockdb ] [ -U | --unlockdb ]
|
|
|
1170 [ -f @var{filename} | --filename=@var{filename} ]
|
|
|
1171 [ -d @var{directory} | --directory=@var{directory} ]
|
|
|
1172 [ -h | --help ] [ -V | --version ]
|
|
|
1173 [ @var{gnats-id} ]
|
|
|
1174 @end smallexample
|
|
|
1175
|
|
|
1176 @cindex PR locks
|
|
|
1177 @cindex locks
|
|
|
1178 A @dfn{lock} is placed on a Problem Report while the PR is being edited.
|
|
|
1179 The lock is simply a file in the same directory as the PR, with the name
|
|
|
1180 @w{@file{@var{gnats-id}.lock}}, which contains the name of the maintainer
|
|
|
1181 who created the lock. @var{maintainer} then ``owns'' the lock, and must
|
|
|
1182 remove it before the PR can be locked again, even by the same
|
|
|
1183 @var{maintainer}@footnote{This approach may seem heavy-handed, but it
|
|
|
1184 ensures that changes are not overwritten.}. If a PR is already locked
|
|
|
1185 when you attempt to edit it, @code{pr-edit} prints an error message
|
|
|
1186 giving the name of the maintainer who is currently editing the PR.
|
|
|
1187
|
|
|
1188 If you do not specify @w{@var{gnats-id}}, @code{pr-edit} reads from
|
|
|
1189 standard input. You must specify @w{@var{gnats-id}} for the functions
|
|
|
1190 which affect PR locks, @samp{--lock=@var{maintainer}} and
|
|
|
1191 @samp{--unlock}.
|
|
|
1192
|
|
|
1193 @table @code
|
|
|
1194 @item -l @var{maintainer}
|
|
|
1195 @itemx --lock=@var{maintainer}
|
|
|
1196 Locks Problem Report @w{@var{gnats-id}}, failing (and returning an error
|
|
|
1197 message) if @w{@var{gnats-id}} is already locked, or if @w{@var{gnats-id}}
|
|
|
1198 does not exist. @code{pr-edit} requires that you specify
|
|
|
1199 @w{@var{gnats-id}} when using this option.
|
|
|
1200
|
|
|
1201 @item -u
|
|
|
1202 @itemx --unlock
|
|
|
1203 Unlocks Problem Report @w{@var{gnats-id}}. @code{pr-edit} requires that
|
|
|
1204 you specify @w{@var{gnats-id}} when using this option. You must own a
|
|
|
1205 file lock to remove it.
|
|
|
1206
|
|
|
1207 @item -L
|
|
|
1208 @itemx --lockdb
|
|
|
1209 Locks the GNATS database as a whole. This will prevent any modification
|
|
|
1210 to any part of the system while it's locked.
|
|
|
1211
|
|
|
1212 @item -U
|
|
|
1213 @itemx --unlockdb
|
|
|
1214 Unlocks the GNATS database as a whole, allowing modification of its
|
|
|
1215 files.
|
|
|
1216
|
|
|
1217 @item -c
|
|
|
1218 @itemx --check
|
|
|
1219 Checks the Problem Report in @w{@var{gnats-id}} (or standard input, if
|
|
|
1220 @w{@var{gnats-id}} is not present) for correct information in its
|
|
|
1221 @w{@sc{Enumerated}} fields. @code{pr-edit} complains about any bogus
|
|
|
1222 information in the Problem Report.
|
|
|
1223
|
|
|
1224 @item -F
|
|
|
1225 Forces the PR to be submitted to the database, even if there is no
|
|
|
1226 current index entry for it (i.e., even if the PR did not exist in the
|
|
|
1227 database previously).
|
|
|
1228
|
|
|
1229 @emph{Warning: using this option may corrupt your index.} If you use
|
|
|
1230 it, be sure you know what you are doing.
|
|
|
1231
|
|
|
1232 @item -f @var{filename}
|
|
|
1233 @itemx --filename=@var{filename}
|
|
|
1234 Reads @var{filename} rather than standard input.
|
|
|
1235
|
|
|
1236 @item -d @var{directory}
|
|
|
1237 @itemx --directory=@var{directory}
|
|
|
1238 Resets the operating directory (@w{@code{@var{GNATS_ROOT}}}).
|
|
|
1239
|
|
|
1240 @item -h
|
|
|
1241 @itemx --help
|
|
|
1242 Prints the usage for @code{pr-edit}.
|
|
|
1243
|
|
|
1244 @item -V
|
|
|
1245 @itemx --version
|
|
|
1246 Prints the version number for @code{pr-edit}.
|
|
|
1247 @end table
|
|
|
1248 @node pr-addr
|
|
|
1249 @subsection Address retrieval
|
|
|
1250 @cindex address retrieval
|
|
|
1251 @cindex @code{pr-addr}
|
|
|
1252
|
|
|
1253 Returns an electronic mail address when given a valid @dfn{nametag}, as
|
|
|
1254 it appears in the @file{responsible} file (@pxref{responsible,,The
|
|
|
1255 @code{responsible} file}). If @var{nametag} is not valid, @code{pr-addr}
|
|
|
1256 will tell the user that it could not find the requested address.
|
|
|
1257
|
|
|
1258 Usage is simply:
|
|
|
1259
|
|
|
1260 @smallexample
|
|
|
1261 pr-addr @var{name}
|
|
|
1262 @end smallexample
|
