1\input texinfo @c -*-texinfo-*- 2@setfilename gnats.info 3 4@include version.texi 5 6@ifinfo 7@format 8START-INFO-DIR-ENTRY 9* Keeping Track: (gnats). GNU Problem Report Management System 10END-INFO-DIR-ENTRY 11@end format 12@end ifinfo 13 14@ifinfo 15Copyright @copyright{} 1993, 1995, 2001, 2002, 2003 Free Software Foundation, Inc. 16 17Permission is granted to make and distribute verbatim copies of 18this manual provided the copyright notice and this permission notice 19are preserved on all copies. 20 21@ignore 22Permission is granted to process this file through TeX and print the 23results, provided the printed document carries a copying permission 24notice identical to this one except for the removal of this paragraph 25(this paragraph not being relevant to the printed manual). 26@end ignore 27 28Permission is granted to copy and distribute modified versions of this 29manual under the conditions for verbatim copying, provided also that 30the entire resulting derived work is distributed under the terms of a 31permission notice identical to this one. 32 33Permission is granted to copy and distribute translations of this manual 34into another language, under the above conditions for modified versions. 35@end ifinfo 36 37@c NOTE TO ANYONE FORMATTING THIS DOCUMENT FOR PRINTING... 38@c Comment the following line out if you don't have access to a 39@c PostScript printer or viewer 40 41@set POSTSCRIPT 42 43@settitle Keeping Track 44@setchapternewpage odd 45@finalout 46@titlepage 47@title Keeping Track 48@subtitle Managing Messages With @sc{gnats} 49@subtitle The @sc{gnu} Problem Report Management System 50@subtitle Version @value{VERSION} 51@subtitle August 2003 52@author Jeffrey M. Osier 53@author Brendan Kehoe 54@author Cygnus Support 55@author Revised for GNATS 4 by Yngve Svendsen 56@page 57 58@vskip 0pt plus 1filll 59Copyright @copyright{} 1993, 1995, 2001, 2002, 2003 Free Software Foundation, Inc. 60 61Permission is granted to make and distribute verbatim copies of 62this manual provided the copyright notice and this permission notice 63are preserved on all copies. 64 65Permission is granted to copy and distribute modified versions of this 66manual under the conditions for verbatim copying, provided also that 67the entire resulting derived work is distributed under the terms of a 68permission notice identical to this one. 69 70Permission is granted to copy and distribute translations of this manual 71into another language, under the above conditions for modified versions. 72 73@end titlepage 74 75@contents 76 77@node Top 78@top Overview 79@cindex overview to GNATS 80@cindex foreword 81 82This manual documents @sc{gnats}, the @sc{gnu} Problem Report Management 83System, version @value{VERSION}. @sc{gnats} is a bug-tracking tool 84designed for use at a central @dfn{Support Site}. Users who experience 85problems use electronic mail, web-based or other clients communicating 86with the @sc{gnats} network daemon running at the support site or direct 87database submissions to communicate these problems to @dfn{maintainers} 88at that Support Site. @sc{gnats} partially automates the tracking of 89these @dfn{Problem Reports} (@dfn{PR}s) by: 90 91@itemize @bullet 92@item 93organizing problem reports into a database and notifying responsible 94parties of suspected bugs; 95 96@item 97allowing support personnel and their managers to edit and query 98accumulated bugs; and 99 100@item 101providing a reliable archive of problems (and their subsequent 102solutions) with a given program. 103@end itemize 104 105@sc{gnats} offers many of the same features offered by more generalized 106databases, including editing, querying, and basic reporting. The 107@sc{gnats} database itself is an ordered repository for problem reports; 108each PR receives a unique, incremental @dfn{PR number} which identifies 109it throughout its lifetime. For a discussion on the working system 110adopted by @sc{gnats}, see @ref{Paradigm,,The database paradigm}. 111 112You can access the submitting, editing, and querying functions of 113@sc{gnats} from within @sc{gnu} Emacs. @xref{GNATS user tools,,The 114@sc{gnats} user tools}. 115 116@menu 117* Introduction:: Introducing GNATS. 118* GNATS user tools:: The GNATS user tools. 119* Installation:: Installing GNATS. 120* Management:: GNATS Administration. 121* Locations:: Where GNATS lives. 122* gnatsd:: The GNATS network server. 123* Access Control:: Controlling access to GNATS databases. 124* Regexps:: Querying using regular expressions. 125* dbconfig recipes:: Useful dbconfig tricks. 126* Support:: GNATS related sites and mailing lists. 127* Index:: 128@end menu 129 130@c =============================================================== 131@node Introduction 132@chapter Introducing @sc{gnats} 133@cindex introduction to GNATS 134@cindex rationale 135@cindex database rationale 136 137Any support organization realizes that a large amount of data flows back 138and forth between the maintainers and the users of their products. This 139data often takes the form of problem reports and communication via 140electronic mail. @sc{gnats} addresses the problem of organizing this 141communication by defining a database made up of archived and indexed 142problem reports. 143 144@sc{gnats} was designed as a tool for software maintainers. It consists 145of several utilities which, when used in concert, formulate and 146administer a database of Problem Reports grouped by site-defined 147@dfn{problem categories}. It allows a support organization to keep 148track of problems (hence the term @dfn{Problem Report}) in an organized 149fashion. Essentially, @sc{gnats} acts as an active archive for 150field-separated textual data. 151 152@menu 153* Paradigm:: The database paradigm 154* Flowchart:: Flowchart of GNATS activities 155* States:: States of Problem Reports 156* Fields:: Problem Report format 157@end menu 158 159@node Paradigm 160@section The database paradigm 161@cindex paradigm 162@cindex database paradigm 163@cindex why GNATS 164@cindex support site 165@cindex maintenance 166@cindex so what does it do 167 168It is in your best interest as the maintainer of a body of work to 169organize the feedback you receive on that work, and to make it easy for 170users of your work to report problems and suggestions. 171 172@sc{gnats} makes this easy by automatically filing incoming problem 173reports into appropriate places, by notifying responsible parties of the 174existence of the problem and (optionally) sending an acknowledgment to 175the submitter that the report was received, and by making these Problem 176Reports accessible to queries and easily editable. @sc{gnats} is a 177database specialized for a specific task. 178 179@sc{gnats} was designed for use at a Support Site that handles a high 180level of problem-related traffic. It maintains Problem Reports in the 181form of text files with defined @dfn{fields} 182(@pxref{Fields,,@sc{gnats} data fields}). The location of the database, 183as well as the categories it accepts as valid, the maintainers for whom 184it provides service, and the submitters from whom it accepts Problem 185Reports, are all definable by the @dfn{Support Site}. 186@xref{Management,,@sc{gnats} administration}. 187 188@cindex what is a PR 189Each PR is a separate file within a main repository 190(@pxref{Locations,,Where @sc{gnats} lives}). Editing access to the 191database is regulated to maintain consistency. To make queries on 192the database faster, an index is kept automatically (@pxref{index 193file,,The @code{index} file}). 194 195We provide several software tools so that users may submit new Problem 196Reports, edit existing Problem Reports, and query the database. 197 198@itemize @bullet 199@item 200@w{@code{send-pr}} is used by both product maintainers and the end users 201of the products they support to submit PRs to the database. 202 203@item 204@w{@code{edit-pr}} is used by maintainers when editing problem 205reports in the database. 206 207@item 208Maintainers, managers and administrators can use @w{@code{query-pr}} to 209make inquiries about individual PRs or groups of PRs. 210 211@end itemize 212 213Other interfaces to @sc{gnats} include Gnatsweb, a web-based tool which 214provides features for submitting and editing PRs and querying the 215database, and TkGnats, a Tcl/Tk-based frontend. These tools are 216distributed together with @sc{gnats}. 217 218@cindex GNATS administrator 219At the Support Site, a @sc{gnats} @dfn{administrator} is charged with the 220duty of maintaining @sc{gnats}. These duties are discussed in detail in 221@ref{Management,,@sc{gnats} Administration}, and generally include 222configuring @sc{gnats} for the Support Site, editing PRs that @sc{gnats} 223cannot process, pruning log files, setting up new problem categories, 224backing up the database, and distributing @code{send-pr} so that others 225may submit Problem Reports. 226 227Responsibility for a given Problem Report initially depends on the 228category of the problem. Optionally, an automated reminder can be 229sent to the responsible person if a problem report is neglected for a 230requisite time period. @xref{GNATS configuration,,Overview of 231@sc{gnats} configuration}. 232 233@cindex @code{pending} directory 234@cindex unparseable incoming PRs 235@cindex incoming PRs that @sc{gnats} cannot parse 236@sc{gnats} does not have the ability to decipher random text. 237If there is no default category set, any 238problem reports which arrive in a format @sc{gnats} does not recognize 239are placed in a separate directory pending investigation by the 240@sc{gnats} administrator (@pxref{Management,,@sc{gnats} Administration}). 241 242Once a problem is recorded in the database, work can begin toward a 243solution. A problem's initial @dfn{state} type is @dfn{open} 244(@pxref{States,,States of Problem Reports}). An acknowledgment may be 245sent to the originator of the bug report (depending on whether this 246feature has been switched on in the @sc{gnats} configuration). 247@sc{gnats} forwards copies of the report to the party responsible for 248that problem category and to the person responsible for problems 249arriving from that submitter. 250@c (@pxref{Glossary,,Glossary}). 251 252When a problem has been identified, the maintainer can change its state 253to @dfn{analyzed}, and then to @dfn{feedback} when a solution is found. 254@sc{gnats} may be configured so that each time the state of a PR 255changes, the submitter of the problem report is notified of the reason 256for the change. If the party responsible for the PR changes, the 257previous responsible party and the new responsible party receive notice 258of the change. The change and reason are also recorded in the 259@code{Audit-Trail} field of the Problem Report. (@xref{edit-pr,,Editing 260existing Problem Reports}. For information on the @code{Audit-Trail} 261field, see @ref{Fields,,Problem Report format}.) 262 263When the originator of the Problem Report confirms that the solution 264works, the maintainer can change the state to @dfn{closed}. If the PR 265cannot be closed, the maintainer can change its state to @dfn{suspended} 266as a last resort. (For a more detailed description of the standard 267states, see @ref{States,,States of Problem Reports}.) 268 269It should be emphasized that what we describe here is the default way 270that @sc{gnats} works, but as of version 4, @sc{gnats} is extremely 271customizable, allowing sites to tailor almost every aspect of its 272behavior. See for instance @ref{dbconfig file,,The @code{dbconfig} 273file} and @xref{States,,States of Problem Reports}.) 274 275@node Flowchart 276@section Flowchart of @sc{gnats} activities 277@cindex flowchart of GNATS activities 278@cindex visual map of data flow 279 280This informal flowchart shows the relationships of the @sc{gnats} tools 281to each other and to the files with which they interoperate. 282 283@sp 2 284 285@ifset POSTSCRIPT 286@tex 287\input epsf 288\epsffile{flowchart.eps} 289@end tex 290@end ifset 291 292@ifinfo 293@clear POSTSCRIPT 294@end ifinfo 295 296@ifclear POSTSCRIPT 297@cartouche 298@smallexample 299@include flowchart.txt 300@end smallexample 301@end cartouche 302 303@end ifclear 304 305@sp 2 306 307@c --------------------------------------------------------------- 308 309@include states.texi 310 311@c --------------------------------------------------------------- 312@include fields.texi 313 314@c =============================================================== 315 316@include p-usage.texi 317 318@c =============================================================== 319 320@node Installation 321@chapter Installing @sc{gnats} 322@include p-inst.texi 323 324@c =============================================================== 325 326@include p-admin.texi 327 328@c =============================================================== 329 330@node Locations 331@appendix Where @sc{gnats} lives 332@cindex locations 333@cindex where @sc{gnats} lives 334@cindex default installation locations 335 336We use a few conventions when referring to the installation structure 337@sc{gnats} uses. These values are adjustable when you build and install 338@sc{gnats} (@pxref{Installation,,Installing @sc{gnats}}). 339 340@menu 341* prefix:: 342* exec-prefix:: 343* gnats-adm:: 344* defaults:: Default installation locations 345@end menu 346 347@node prefix 348@section @var{prefix} 349@cindex @var{prefix} 350 351@var{prefix} corresponds to the variable @samp{prefix} for 352@code{configure}, which passes it on to the @file{Makefile} it creates. 353@var{prefix} sets the root installation directory for 354@dfn{host-independent} files as follows: 355 356@c FIXME - check these 357@table @asis 358@item the directory path of the default database 359@file{@var{prefix}/com}@* 360 361@item site-wide configuration files 362@file{@var{prefix}/etc/gnats}@* 363 364@item @code{man} pages 365@file{@var{prefix}/man} 366 367@item @code{info} documents 368@file{@var{prefix}/info} 369 370@item @code{include} files 371@file{@var{prefix}/include} 372 373@item @emph{etc@dots{}} 374@end table 375 376The default value for @var{prefix} is @w{@file{/usr/local}}, which can 377be changed on the command line to @code{configure} using 378 379@smallexample 380configure --prefix=@var{prefix} @dots{} 381@end smallexample 382 383@noindent 384@xref{Configure and make,,Configuring and compiling the software}. 385 386@node exec-prefix 387@section @var{exec-prefix} 388@cindex @var{exec-prefix} 389 390@var{exec-prefix} corresponds to the variable @samp{exec-prefix} for 391@code{configure}, which passes it on to the @file{Makefile} it creates. 392@w{@var{exec-prefix}} sets the root installation for 393@dfn{host-dependent} files as follows: 394 395@table @asis 396@item @sc{gnats} user tools 397@file{@var{exec-prefix}/bin} 398 399@item administrative and support utilities 400@file{@var{exec-prefix}/libexec/gnats} 401 402@item compiled libraries 403@file{@var{exec-prefix}/lib}@* 404 405@item @emph{etc@dots{}} 406@end table 407 408@code{configure} supports several more options which allow you to 409specify in great detail where different files are installed. The 410locations given in this appendix do not take into account highly 411customized installations, but fairly ordinary @sc{gnats} installations 412should be covered by the material here. For a complete list of options 413accepted by @code{configure}, run @code{./configure --help} in the 414@file{gnats} subdirectory of the distribution. 415 416Since most installations are not intended to be distributed around a 417network, the default value for @w{@var{exec-prefix}} is the value of 418@samp{prefix}, i.e., @w{@file{/usr/local}}. However, using 419@var{exec-prefix} saves space when you are installing a package on 420several different platforms for which many files are identical; rather 421than duplicate them for each host, these files can be shared in a common 422repository, and you can use symbolic links on each host to find the 423host-dependent files. 424 425Use @var{exec-prefix} in conjunction with @var{prefix} to share 426host-independent files, like libraries and @code{info} documents. For 427example: 428 429@smallexample 430 @emph{for each host:} 431configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-@var{host} 432make all install @dots{} 433@end smallexample 434 435@noindent 436Using this paradigm, all host-dependent binary files are installed into 437@w{@file{/usr/gnu/H-@var{host}/bin}}, while files which do not depend on 438the host type for which they were configured are installed into 439@w{@file{/usr/gnu}}. 440 441You can then use a different symbolic link for @w{@file{/usr/gnu}} 442on each host (@file{/usr} is usually specific to a particular machine; 443it is always specific to a particular architecture). 444 445@smallexample 446 @emph{on host-1:} 447ln -s /usr/gnu/H-@var{host-1} /usr/gnu 448 @emph{on host-2:} 449ln -s /usr/gnu/H-@var{host-2} /usr/gnu 450@end smallexample 451 452@noindent 453To the end user, then, placing @w{@file{/usr/gnu/bin}} in her or his 454@code{PATH} simply works transparently for each @var{host} type. 455 456You can change @w{@var{exec-prefix}} on the command line to 457@code{configure} using 458 459@smallexample 460configure --exec-prefix=@var{exec-prefix} @dots{} 461@end smallexample 462 463We recommend that you consult @ref{Using configure,,Using 464@code{configure},configure,Cygnus configure}, before attempting this. 465 466@node gnats-adm 467@section The @file{gnats-adm} directory 468@cindex @var{gnats-adm} 469 470Each @sc{gnats} database located on a server has its own directory, as 471listed in the @file{databases} (@pxref{databases file,,The 472@code{databases} file} and given when the @code{mkdb} utility is invoked 473to initialize the database (@pxref{mkdb,,Initializing a new database}). 474This directory has several subdirectories, one of which is named 475@file{gnats-adm}. This directory contains all configuration files 476related to this specific database, including the @file{categories}, 477@file{submitters}, @file{responsible}, @file{states}, @file{classes}, 478@file{dbconfig}, @file{addresses}, @file{states} and 479@file{gnatsd.user_access}, as well as two 480files generated and maintained by @sc{gnats}, @file{index} and 481@file{current}. 482 483@node defaults 484@section Default installation locations 485@cindex default installation locations 486 487@table @asis 488@item @var{prefix} 489defaults to @file{/usr/local}; change using @code{configure} 490(@pxref{Configure and make,,Configuring and compiling the software}). 491 492@item @var{exec-prefix} 493defaults to @var{prefix}; change using @code{configure} 494(@pxref{Configure and make,,Configuring and compiling the software}). 495@end table 496 497@noindent 498@sc{gnats} installs tools, utilities, and files into the following 499locations. 500 501@table @code 502 503@item @var{exec-prefix}/bin 504 505@table @code 506@item send-pr 507@xref{send-pr,,Submitting Problem Reports}. 508@item edit-pr 509@xref{edit-pr,,Editing existing Problem Reports}. 510@item query-pr 511@xref{query-pr,,Querying the database}. 512@end table 513 514@item @var{exec-prefix}/libexec/gnats 515 516@table @code 517@item at-pr 518@xref{at-pr,,Timely reminders}. 519 520@item check-db 521@xref{check-db,,Checking database health}. 522 523@item delete-pr 524Tool for deleting PRs. Deprecated. Use the --delete-pr option of 525@code{pr-edit} instead (@pxref{pr-edit,,The edit-pr driver}). 526 527@item diff-prs 528@xref{diff-prs,,The @code{diff-prs} tool}. 529 530@item file-pr 531@xref{file-pr,,Interface to pr-edit for filing new PRs}. 532 533@item gen-index 534@xref{gen-index,,Regenerating the index}. 535 536@item gnatsd 537The @sc{gnats} daemon. 538 539@item gnats-pwconv 540@xref{gnats-pwconv,,Converting old password files}. 541 542@item mail-query 543@xref{Aliases,,Setting up mail aliases}. 544 545@item mkcat 546@xref{mkcat,,Adding a problem category}. 547 548@item mkdb 549@xref{mkdb,,Script for creating new databases}. 550 551@item pr-age 552@xref{pr-age,,The @code{pr-age} tool}. 553 554@item pr-edit 555@xref{pr-edit,,The main PR processor}. 556 557@item queue-pr 558@xref{queue-pr,,Handling incoming traffic}. 559 560@item rmcat 561@xref{rmcat,,Removing categories}. 562@end table 563 564@item @var{exec-prefix}/lib/libiberty.a 565The @sc{gnu} @code{libiberty} library. 566 567@item @var{prefix}/etc/gnats 568 569@table @file 570@item databases 571@xref{databases file,,The @file{databases} file}. 572 573@item defaults 574@xref{GNATS configuration,,Overview of @sc{gnats} configuration}. 575 576@item gnatsd.host_access 577@xref{gnatsd.host_access,,The @file{gnatsd.host_access} file}. 578 579@item gnatsd.user_access 580@xref{gnatsd.user_access,,The @file{gnatsd.user_access} file}. 581@end table 582 583@item @var{prefix}/share/emacs/site-lisp 584 585@table @file 586@item gnats.el 587@itemx gnats.elc 588The Emacs versions of the programs @code{send-pr}, @code{query-pr}, 589@code{edit-pr}, and @code{view-pr}. @xref{GNATS user tools,,The 590@sc{gnats} user tools}. To change this directory you must change the 591@code{lispdir} variable in @file{Makefile.in}; see @ref{Configure and 592make,,Configuring and compiling the software}. 593@end table 594 595@item @var{prefix}/info 596 597@table @file 598@item gnats.info 599@itemx send-pr.info 600The @sc{gnats} manuals, in a form readable by @code{info} (the @sc{gnu} 601hypertext browser). @xref{Info,,Reading GNU Online 602Documentation,infoman,GNU Online Documentation}. 603@end table 604 605@item @var{prefix}/man/man1 606@itemx @var{prefix}/man/man8 607 608@table @asis 609@item @code{man} pages for all the @sc{gnats} tools and utilities. 610@xref{GNATS user tools,,The @sc{gnats} user tools}. 611@end table 612 613@item Per-database directory 614 615@table @file 616@item gnats-adm 617Administration and configuration data files that define behaviour of the 618particular database. The files 619 620@table @file 621@item categories 622 623@item submitters 624 625@item responsible 626 627@item states 628 629@item classes 630 631@item dbconfig 632 633@item addresses 634 635@item states 636 637@item gnatsd.user_access 638 639@item index 640(@emph{This file is created by @sc{gnats}.}) 641 642@item current 643(@emph{This file is created by @sc{gnats}.}) 644@end table 645 646@noindent exist here. 647@xref{Other config files,,Other database-specific config files}, 648@ref{Admin files,,Administrative data files} and @ref{Access 649Control,,Controlling access to databases}. 650 651@item gnats-queue 652Incoming Problem Reports are queued here until the next iteration of 653@w{@samp{queue-pr -r}} (@pxref{queue-pr,,Handling incoming traffic}). 654 655@item pending 656If no default category is set, problem reports without a category are 657reassigned to the category @samp{pending} and placed here pending 658intervention by @sc{gnats} administrators. 659@xref{Management,,@sc{gnats} administration}. 660 661@item @var{category} 662Each valid category has a corresponding subdirectory in the database. 663All Problem Reports associated with that category are kept in that 664subdirectory. 665@end table 666 667@end table 668 669@c =============================================================== 670@node gnatsd 671@appendix The @sc{gnats} network server -- @code{gnatsd} 672@cindex @code{gnatsd} 673 674This section describes in details how the @sc{gnats} network daemon 675works. This information is mainly assumed to be useful for developers 676of @sc{gnats} client software. 677 678@menu 679* Description of gnatsd:: 680* gnatsd options:: 681* gnatsd command protocol:: 682* gnatsd commands:: 683* gnatsd environment variables:: 684@end menu 685 686@node Description of gnatsd 687@section Description of @code{gnatsd} 688@cindex @code{gnatsd} description 689 690The @code{gnatsd} network daemon is used to service remote @sc{gnats} 691requests such as querying PRs, PR creation, deletion, and editing, and 692miscellaneous database queries. It uses a simple ASCII-based command 693protocol (similar to SMTP or POP3) for communicating with remote 694clients. 695 696It also provides a security model based either on IP-based 697authentication (generally considered very weak) or username/passwords, 698where passwords may be in cleartext, UNIX crypt or MD5 hash format. 699Access through @code{gnatsd} is granted according to certain predefined 700@dfn{access levels}. Access levels are further discussed in @ref{Access 701Control,,Controlling access to databases}. It should be emphasized that 702security has not been a focus of development until now, but future 703versions are expected to address this more thoroughly. 704 705All of the @sc{gnats} clients are capable of communicating via the @sc{gnats} 706remote protocol to perform their functions. 707@c XXX Add reference to remote tool installation section here. 708 709@code{gnatsd} is usually started from the inetd facility and should run as 710the @code{gnats} user (the actual username of this user is configurable 711during installation, @pxref{Configure and make,,Configuring and 712compiling the software} for details.) 713 714@node gnatsd options 715@section @code{gnatsd} options 716@cindex @code{gnatsd} options 717 718The daemon supports the following command-line options: 719 720@smallexample 721gnatsd [--database database | -d database] 722 [--not-inetd | -n] [--max-access-level @var{level} | -m @var{level}] 723 [--version | -V] [--help | -h] 724@end smallexample 725 726@cindex @code{gnatsd} startup options 727@table @code 728@item -V, --version 729Prints the program version to stdout and exits. 730 731@item -h, --help 732Prints a short help text to stdout and exits. 733 734@item -d, --database 735Specifies the default database which is to be serviced by this 736invocation of @code{gnatsd}. (The selected database may be changed via 737the @code{CHDB} command; the name set with this option is simply the 738default if no @code{CHDB} command is issued.) If no database is 739specified, the database named default is assumed. This option overrides 740the database specified in the @code{GNATSDB} environment variable. 741 742@item -n, --not-inetd 743As its name suggests, indicates that @code{gnatsd} is not being invoked 744from inetd. This can be used when testing @code{gnatsd}, or if it is 745being run via ssh or some other mechanism. 746 747This has the effect of using the local hostname where @code{gnatsd} is 748being invoked for authentication purposes, rather than the remote 749address of the connecting client. 750 751@item --max-access-level, -m 752Specifies the maximum access level that the connecting client can 753authenticate to. Authentication is as normal but if the user or host 754authenticates at a higher level, access level is still forced to this 755level. See @ref{Access Control,,Controlling access to databases} for 756details on access levels. 757@end table 758 759@node gnatsd command protocol 760@section @code{gnatsd} command protocol 761@cindex @code{gnatsd} command protocol 762 763Commands are issued to @code{gnatsd} as one or more words followed by a 764carriage-return/linefeed pair. For example, the @code{CHDB} (change 765database) command is sent as @samp{CHDB database<CR><LF>} (the 766@code{CRLF} will not be explicitly written for future examples.) 767 768Replies from @code{gnatsd} are returned as one or more response lines 769containing a 3-digit numeric code followed by a human-readable string; 770the line is terminated with a @code{<CR><LF>} pair. For example, one 771possible response to the @code{CHDB} command above would be: 772 773@smallexample 774210 Now accessing GNATS database 'database'. 775@end smallexample 776 777The three-digit code is normally followed by a single ASCII space 778(character 0x20). However, if additional response lines are to be 779returned from the server, there will be a single dash @samp{-} instead 780of the space character after the three-digit code. 781 782Response code values are divided into ranges. The first digit reflects 783the general type of response (such as ''successful'' or ''error''), and 784the subsequent digits identify the specific type of response. 785 786@table @var 787@item Codes 200-299 788Positive response indicating that the command was successful. No 789subsequent data will be transmitted with the response. In particular, 790code 210 (@code{CODE_OK}) is used as the positive result code for most 791simple commands. 792 793Commands that expect additional data from the client (such as 794@code{SUBM} or @code{VFLD}) use a two-step mechanism for sending the 795data. The server will respond to the initial command with either a 211 796(@code{CODE_SEND_PR}) or 212 (@code{CODE_SEND_TEXT}) response line, or 797an error code if an error occurred with the initial command. The client 798is then expected to send the remaining data using the same quoting 799mechanism as described for server responses in the 300-349 range. The 800server will then send a final response line to the command. 801 802@item Codes 300-399 803Positive response indicating that the query request was successful, and 804that a PR or other data will follow. Codes 300-349 are used when 805transmitting PRs, and 350-399 are used for other responses. 806 807Codes in the 300-349 range are followed by a series of 808@code{CRLF}-terminated lines containing the command response, usually a 809PR. The final line of the result is a single period @samp{.}. Result 810lines that begin with a period have an extra period prepended to them. 811 812Codes in the 350-399 range use a different scheme for sending their 813responses. The three-digit numeric code will be followed by either a 814dash @samp{-} or a single space. If the code is followed by a dash, 815that indicates that another response line will follow. The final line 816of the response has a single space after the three-digit code. 817 818In previous versions of the protocol the first line of a 819@code{CODE_INFORMATION} (310) response was to be ignored. This is no 820longer the case. Instead, any lines marked with code 821@code{CODE_INFORMATION_FILLER} (351) are to be ignored. This allows the 822server to transmit additional headers or other human-readable text that 823can be safely ignored by the clients. 824 825@item Codes 400-599 826An error occurred, usually because of invalid command parameters or 827invalid input from the client, missing arguments to the command, or a 828command was issued out of sequence. The human-readable message 829associated with the response line describes the general problem 830encountered with the command. 831 832Multiple error messages may be returned from a command; in this case the 833@samp{-} continuation character is used on all but the last response 834line. 835 836@item Codes 600-799 837An internal error occurred on the server, a timeout occurred reading 838data from the client, or a network failure occurred. These errors are 839of the ''this should not occur'' nature, and retrying the operation may 840resolve the problem. Fortunately, most @sc{gnats} transactions are 841idempotent; unfortunately, locking the database or a PR are not 842repeatable actions (we cannot determine if an existing lock is the one 843we originally requested, or someone else's). 844@end table 845 846@node gnatsd commands 847@section @code{gnatsd} commands 848@cindex @code{gnatsd} commands 849@cindex @code{gnatsd} commands 850 851Note that the set of @sc{gnats} commands and their responses is somewhat 852inconsistent and is very much in flux. At present the @sc{gnats} 853clients are rather simple-minded and not very strict about processing 854responses. For example, if the server were to issue a code 300 855(@code{CODE_PR_READY}) response to a @code{CHDB} command, the client 856would happily expect to see a PR appear (and would print it out if one 857was sent). 858 859It is thus suggested that any clients that use the @sc{gnats} protocol 860be equally flexible about the way received responses are handled; in 861particular, only the first digit of the response code should be assumed 862to be meaningful, although subsequent digits are needed in some cases 863(codes 300-399). No attempt should be made to parse the message strings 864on error response lines; they are only intended to be read by humans, 865and will be changed on a regular basis. 866 867Almost every command may result in the response 440 868(@code{CODE_CMD_ERROR}). This indicates that there was a problem with 869the command arguments, usually because of insufficient or too many 870arguments being specified. 871 872Access to most @code{gnatsd} commands requires a certain @dfn{access 873level}. For details of this, see @ref{Privileged gnatsd 874commands,,Privileged @code{gnatsd} commands}. 875 876@table @code 877@item USER [@var{userid} @var{password}] 878Specifies the userid and password for database access. Either both a 879username and password must be specified, or they both may be omitted; in 880the latter case, the current access level is returned. 881 882The possible server responses are: 883 884@code{350 (CODE_INFORMATION)} 885@*The current access level is specified. 886 887@code{422 (CODE_NO_ACCESS)} 888@*A matching username and password could not be found. 889 890@code{200 (CODE_OK)} 891@*A matching username and password was found, and the login was 892successful. 893 894@item QUIT 895Requests that the connection be closed. Possible responses: 896 897@code{201 (CODE_CLOSING)} 898@*Normal exit. 899 900The @code{QUIT} command has the dubious distinction of being the only command 901that cannot fail. 902 903@item LIST @var{list type} 904Describes various aspects of the database. The lists are returned as a 905list of records, one per line. Each line may contain a number of 906colon-separated fields. 907 908Possible values for @var{list type} include 909 910@code{Categories} 911@*Describes the legal categories for the database. 912 913@code{Submitters} 914@*Describes the set of submitters for the database. 915 916@code{Responsible} 917@*Lists the names in the responsible administrative file, including 918their full names and email addresses. 919 920@code{States} 921@*Lists the states listed in the state administrative file, including 922the state type (usually blank for most states; the closed state has a 923special type). 924 925@code{FieldNames} 926@*Lists the entire set of PR fields. 927 928@code{InitialInputFields} 929@*Lists the fields that @emph{should} be present when a PR is 930initially entered. 931 932@code{InitialRequiredFields} 933@*Lists fields that @emph{have} to be present and nonempty when a PR 934is initially entered (fields containing only blank characters such as 935spaces or newlines are considered empty.) 936 937@code{Databases} 938@*Lists the set of databases. 939 940The possible responses are: 941 942@code{301 (CODE_TEXT_READY)} 943@*Normal response, followed by the records making up the list as 944described above. 945 946@code{416 (CODE_INVALID_LIST)} 947@*The requested list does not exist. 948 949@item FTYP @var{field} [@var{field} ...] 950Describes the type of data held in the field(s) specified with the 951command. The currently defined data types are: 952 953@code{Text} 954@*A plain text field, containing exactly one line. 955 956@code{MultiText} 957@*A text field possibly containing multiple lines of text. 958 959@code{Enum} 960@*An enumerated data field; the value is restricted to one entry out of 961a list of values associated with the field. 962 963@code{MultiEnum} 964@*The field contains one or more enumerated values. Values are 965separated with spaces or colons @samp{:}. 966 967@code{Integer} 968@*The field contains an integer value, possibly signed. 969 970@code{Date} 971@*The field contains a date. 972 973@code{TextWithRegex} 974@*The value in the field must match one or more regular expressions 975associated with the field. 976 977The possible responses are: 978 979@code{350 (CODE_INFORMATION)} 980@*The normal response; the supplied text is the data type. 981 982@code{410 (CODE_INVALID_FIELD_NAME)} 983@*The specified field does not exist. 984 985If multiple field names were given, multiple response lines will be 986sent, one for each field, using the standard continuation protocol; each 987response except the last will have a dash @samp{-} immedately after the 988response code. 989 990@item FTYPINFO @var{field} @var{property} 991 992Provides field-type-related information. Currently, only the property 993@samp{separators} for MultiEnum fields is supported. When 994@samp{separators} is specified, the possible return codes are: 995 996@code{350 (CODE_INFORMATION)} 997A proper MultiEnum @var{field} was specified and the returned text is 998the string of separators specified for the field in the dbconfig file 999(@pxref{Field datatypes}) quoted in @code{'}'s. 1000 1001@code{435 (CODE_INVALID_FTYPE_PROPERTY)} 1002The @samp{separators} property is not defined for this field, i.e. the 1003specified @var{field} is not of type MultiEnum. 1004 1005Currently, specifying a different property than @samp{separators} 1006results in return code 435 as above. 1007 1008@item FDSC @var{field} [@var{field} ... ] 1009Returns a human-readable description of the listed field(s). The 1010possible responses are: 1011 1012@code{350 (CODE_INFORMATION)} 1013The normal response; the supplied text is the field description. 1014 1015@code{410 (CODE_INVALID_FIELD_NAME)} 1016The specified field does not exist. 1017 1018Like the @code{FVLD} command, the standard continuation protocol will be 1019used if multiple fields were specified with the command. 1020 1021@item FIELDFLAGS @var{field} [@var{field} ... ] 1022Returns a set of flags describing the specified field(s). The possible 1023responses are either 1024 1025@code{410 (CODE_INVALID_FIELD_NAME)} 1026@*meaning that the specified field is invalid or nonexistent, or 1027 1028@code{350 (CODE_INFORMATION)} 1029@*which contains the set of flags for the field. The flags may be 1030blank, which indicate that no special flags have been set for this 1031field. 1032 1033Like the @code{FDSC} and @code{FTYP} commands, multiple field names may 1034be listed with the command, and a response line will be returned for 1035each one in the order that the fields appear on the command line. 1036 1037The flags include: 1038 1039@code{textsearch} 1040@*The field will be searched when a text field search is requested. 1041 1042@code{allowAnyValue} 1043@*For fields that contain enumerated values, any legal value may be used 1044in the field, not just ones that appear in the enumerated list. 1045 1046@code{requireChangeReason} 1047@*If the field is edited, a reason for the change must be supplied in 1048the new PR text describing the reason for the change. The reason must be 1049supplied as a multitext PR field in the new PR whose name is 1050@code{field-Changed-Why} (where @code{field} is the name of the field 1051being edited). 1052 1053@code{readonly} 1054@*The field is read-only, and cannot be edited. 1055 1056@item FVLD @var{field} 1057@*Returns one or more regular expressions or strings that describe the 1058valid types of data that can be placed in field. Exactly what is 1059returned is dependent on the type of data that can be stored in the 1060field. For most fields a regular expression is returned; for enumerated 1061fields, the returned values are the list of legal strings that can be 1062held in the field. 1063 1064The possible responses are: 1065 1066@code{301 (CODE_TEXT_READY)} 1067@*The normal response, which is followed by the list of regexps or 1068strings. 1069 1070@code{410 (CODE_INVALID_FIELD_NAME)} 1071The specified field does not exist. 1072 1073@item VFLD @var{field} 1074@code{VFLD} can be used to validate a given value for a field in the 1075database. The client issues the @code{VFLD} command with the name of 1076the field to validate as an argument. The server will either respond 1077with @code{212 (CODE_SEND_TEXT)}, or @code{410 1078(CODE_INVALID_FIELD_NAME)} if the specified field does not exist. 1079 1080Once the @code{212} response is received from the server, the client 1081should then send the line(s) of text to be validated, using the normal 1082quoting mechanism described for PRs. The final line of text is followed 1083by a line containing a single period, again as when sending PR text. 1084 1085The server will then either respond with @code{210 (CODE_OK)}, 1086indicating that the text is acceptable, or one or more error codes 1087describing the problems with the field contents. 1088 1089@item INPUTDEFAULT @var{field} [@var{field} ... ] 1090Returns the suggested default value for a field when a PR is initially 1091created. The possible responses are either @code{410 1092(CODE_INVALID_FIELD_NAME)}, meaning that the specified field is invalid 1093or nonexistent, or @code{350 (CODE_INFORMATION)} which contains the 1094default value for the field. 1095 1096Like the @code{FDSC} and @code{FTYP} commands, multiple field names may 1097be listed with the command, and a response line will be returned for 1098each one in the order that the fields appear on the command line. 1099 1100@item RSET 1101Used to reset the internal server state. The current query expression 1102is cleared, and the index of PRs may be reread if it has been updated 1103since the start of the session. The possible responses are: 1104 1105@code{200 (CODE_OK)} 1106@*The state has been reset. 1107 1108@code{440 (CODE_CMD_ERROR)} 1109@*One or more arguments were supplied to the command. 1110 1111@code{6xx (internal error)} 1112@*There were problems resetting the state (usually because the index could 1113not be reread). The session will be immediately terminated. 1114 1115@item LKDB 1116Locks the main @sc{gnats} database. No subsequent database locks will 1117succeed until the lock is removed. Sessions that attempt to write to 1118the database will fail. The possible responses are: 1119 1120@code{200 (CODE_OK)} 1121The lock has been established. 1122 1123@code{440 (CODE_CMD_ERROR)} 1124One or more arguments were supplied to the command. 1125 1126@code{431 (CODE_GNATS_LOCKED)} 1127The database is already locked, and the lock could not be obtained after 112810 seconds. 1129 1130@code{6xx (internal error)} 1131An internal error occurred, usually because of permission or other 1132filesystem-related problems. The lock may or may not have been 1133established. 1134 1135@item UNDB 1136 1137Unlocks the database. Any session may steal a database lock; no 1138checking of any sort is done. The possible responses are: 1139 1140@code{200 (CODE_OK)} 1141@*The lock has been removed. 1142 1143@code{432 (CODE_GNATS_NOT_LOCKED)} 1144@*The database was not locked. 1145 1146@code{440 (CODE_CMD_ERROR)} 1147@*One or more arguments were supplied to the command. 1148 1149@code{6xx (internal error)} 1150@*The database lock could not be removed, usually because of permissions 1151or other filesystem-related issues. 1152 1153@item LOCK @var{PR user} [@var{pid}] 1154Locks the specified @var{PR}, marking the lock with the @var{user} name 1155and the optional @var{pid}. (No checking is done that the @var{user} or 1156@var{pid} arguments are valid or meaningful; they are simply treated as 1157strings.) 1158 1159The @code{EDIT} command requires that the PR be locked before it may be 1160successfully executed. However, it does not require that the lock is 1161owned by the editing session, so the usefulness of the lock is simply as 1162an advisory measure. 1163 1164The @code{APPN} and @code{REPL} commands lock the PR as part of the 1165editing process, and they do not require that the PR be locked before 1166they are invoked. 1167 1168The possible responses are: 1169 1170@code{440 (CODE_CMD_ERROR)} 1171@*Insufficient or too many arguments were specified to the command. 1172 1173@code{300 (CODE_PR_READY)} 1174@*The lock was successfully obtained; the text of the PR (using the 1175standard quoting mechanism for PRs) follows. 1176 1177@code{400 (CODE_NONEXISTENT_PR)} 1178@*The PR specified does not exist. 1179 1180@code{430 (CODE_LOCKED_PR)} 1181@*The PR is already locked by another session. 1182 1183@code{6xx (internal error)} 1184@*The PR lock could not be created, usually because of permissions or 1185other filesystem-related issues. 1186 1187@item UNLK @var{PR} 1188Unlocks @var{PR}. Any user may unlock a PR, as no checking is done to 1189determine if the requesting session owns the lock. 1190 1191The possible responses are: 1192 1193@code{440 (CODE_CMD_ERROR)} 1194@*Insufficient or too many arguments were specified to the command. 1195 1196@code{200 (CODE_OK)} 1197@*The PR was successfully unlocked. 1198 1199@code{433 (CODE_PR_NOT_LOCKED)} 1200@*The PR was not locked. 1201 1202@code{6xx (internal error)} 1203@*The PR could not be unlocked, usually because of permission or other 1204filesystem-related problems. 1205 1206@item DELETE @var{PR} 1207Deletes the specified @var{PR}. The user making the request must have 1208admin privileges (@pxref{Access Control,,Controlling access to 1209databases}). If successful, the PR is removed from the filesystem and 1210the index file; a gap will be left in the numbering sequence for PRs. 1211No checks are made that the PR is closed. 1212 1213The possible responses are: 1214 1215@code{200 (CODE_OK)} 1216@*The PR was successfully deleted. 1217 1218@code{422 (CODE_NO_ACCESS)} 1219@*The user requesting the delete does not have admin privileges. 1220 1221@code{430 (CODE_LOCKED_PR)} 1222@*The PR is locked by another session. 1223 1224@code{431 (CODE_GNATS_LOCKED)} 1225@*The database has been locked, and no PRs may be updated until the lock 1226is cleared. 1227 1228@code{6xx (internal error)} 1229@*The PR could not be successfully deleted, usually because of 1230permission or other filesystem-related problems. 1231 1232@item CHEK [initial] 1233Used to check the text of an entire PR for errors. Unlike the 1234@code{VFLD} command, it accepts an entire PR at once instead of the 1235contents of an individual field. 1236 1237The @code{initial} argument indicates that the PR text to be checked is 1238for a PR that will be newly created, rather than an edit or replacement 1239of an existing PR. 1240 1241After the @code{CHEK} command is issued, the server will respond with 1242either a @code{440 (CODE_CMD_ERROR)} response indicating that the 1243command arguments were incorrect, or a @code{211 (CODE_SEND_PR)} 1244response code will be sent. 1245 1246Once the @code{211} response is received from the server, the client 1247should send the PR using the normal PR quoting mechanism; the final line 1248of the PR is then followed by a line containing a single period, as 1249usual. 1250 1251The server will then respond with either a @code{200 (CODE_OK)} 1252response, indicating there were no problems with the supplied text, or 1253one or more error codes listing the problems with the PR. 1254 1255@item EDIT @var{PR} 1256Verifies the replacement text for @var{PR}. If the command is 1257successful, the contents of @var{PR} are completely replaced with the 1258supplied text. The PR must previously have been locked with the 1259@code{LOCK} command. 1260 1261The possible responses are: 1262 1263@code{431 (CODE_GNATS_LOCKED)} 1264@*The database has been locked, and no PRs may be updated until the lock 1265is cleared. 1266 1267@code{433 (CODE_PR_NOT_LOCKED)} 1268@*The PR was not previously locked with the @code{LOCK} command. 1269 1270@code{400 (CODE_NONEXISTENT_PR)} 1271@*The specified PR does not currently exist. The @code{SUBM} command 1272should be used to create new PRs. 1273 1274@code{211 (CODE_SEND_PR)} 1275@*The client should now transmit the replacement PR text using the 1276normal PR quoting mechanism. After the PR has been sent, the server 1277will respond with either @code{200 (CODE_OK)} indicating that the edit 1278was successful, or one or more error codes listing problems either with 1279the replacement PR text or errors encountered while updating the PR file 1280or index. 1281 1282@item EDITADDR @var{address} 1283Sets the e-mail address of the person communicating with 1284@code{gnatsd}. The command requires at least the @code{edit} access 1285level. 1286 1287The possible responses are: 1288 1289@code{200 (CODE_OK)} 1290@*The address was successfully set. 1291 1292@code{440 (CODE_CMD_ERROR)} 1293@*Invalid number of arguments were supplied. 1294 1295@item APPN @var{PR} @var{field} 1296@itemx REPL @var{PR} @var{field} 1297Appends to or replaces the contents of @var{field} in @var{PR} with the 1298supplied text. The command returns a @code{201 (CODE_SEND_TEXT)} 1299response; the client should then transmit the new field contents using 1300the standard PR quoting mechanism. After the server has read the new 1301contents, it then attempts to make the requested change to the PR. 1302 1303The possible responses are: 1304 1305@code{200 (CODE_OK)} 1306@*The PR field was successfully changed. 1307 1308@code{400 (CODE_NONEXISTENT_PR)} 1309@*The PR specified does not exist. 1310 1311@code{410 (CODE_INVALID_FIELD_NAME)} 1312@*The specified field does not exist. 1313 1314@code{402 (CODE_UNREADABLE_PR)} 1315@*The PR could not be read. 1316 1317@code{431 (CODE_GNATS_LOCKED)} 1318@*The database has been locked, and no PRs may be updated until the lock 1319is cleared. 1320 1321@code{430 (CODE_LOCKED_PR)} 1322@*The PR is locked, and may not be altered until the lock is cleared. 1323 1324@code{413 (CODE_INVALID_FIELD_CONTENTS)} 1325@*The supplied (or resulting) field contents are not valid for the 1326field. 1327 1328@code{6xx (internal error)} 1329@*An internal error occurred, usually because of permission or other 1330filesystem-related problems. The PR may or may not have been altered. 1331 1332@item SUBM 1333Submits a new PR into the database. The supplied text is verified for 1334correctness, and if no problems are found a new PR is created. 1335 1336The possible responses are: 1337 1338@code{431 (CODE_GNATS_LOCKED)} 1339@*The database has been locked, and no PRs may be submitted until the 1340lock is cleared. 1341 1342@code{211 (CODE_SEND_PR)} 1343@*The client should now transmit the new PR text using the normal 1344quoting mechanism. After the PR has been sent, the server will respond 1345with either @code{351 (CODE_INFORMATION_FILLER)} and 1346@code{350 (CODE_INFORMATION)} responses indicating that the new PR 1347has been created and supplying the number assigned to it, or one or 1348more error codes listing problems with the new PR text. 1349 1350@item CHDB @var{database} 1351Switches the current database to the name specified in the command. 1352 1353The possible responses are: 1354 1355@code{422 (CODE_NO_ACCESS)} 1356@*The user does not have permission to access the requested database. 1357 1358@code{417 (CODE_INVALID_DATABASE)} 1359@*The database specified does not exist, or one or more configuration 1360errors in the database were encountered. 1361 1362@code{220 (CODE_OK)} 1363@*The current database is now @var{database}. Any operations performed 1364will now be applied to @var{database}. 1365 1366@item DBLS 1367Lists the known set of databases. 1368 1369The possible responses are: 1370 1371@code{6xx (internal error)} 1372@*An internal error was encountered while trying to obtain the list of 1373available databases, usually due to lack of permissions or other 1374filesystem-related problems, or the list of databases is empty. 1375 1376@code{301 (CODE_TEXT_READY)} 1377@*The list of databases follows, one per line, using the standard 1378quoting mechanism. Only the database names are sent. 1379 1380The @code{gnatsd} access level @samp{listdb} denies access until the 1381user has authenticated with the USER command. The only other command 1382available at this access level is @code{DBLS}. This access level 1383provides a way for a site to secure its @sc{gnats} databases while still 1384providing a way for client tools to obtain a list of the databases for 1385use on login screens etc. @xref{Access 1386Control,,Controlling access to databases}. 1387 1388@item DBDESC @var{database} 1389Returns a human-readable description of the specified @var{database}. 1390 1391Responses include: 1392 1393@code{6xx (internal error)} 1394@*An internal error was encountered while trying to read the list of 1395available databases, usually due to lack of permissions or other 1396filesystem-related problems, or the list of databases is empty. 1397 1398@code{350 (CODE_INFORMATION)} 1399@*The normal response; the supplied text is the database description. 1400 1401@code{417 (CODE_INVALID_DATABASE)} 1402@*The specified database name does not have an entry. 1403 1404@item EXPR @var{query expression} 1405Specifies a @var{query expression} used to limit which PRs are returned 1406from the @code{QUER} command. The expression uses the normal query 1407expression syntax, (@pxref{Query expressions}). 1408 1409Multiple @code{EXPR} commands may be issued; the expressions are boolean 1410ANDed together. 1411 1412Expressions are cleared by the @code{RSET} command. 1413 1414Possible responses include: 1415 1416@code{415 (CODE_INVALID_EXPR)} 1417@*The specified expression is invalid, and could not be parsed. 1418 1419@code{200 (CODE_OK)} 1420@*The expression has been accepted and will be used to limit the 1421results returned from @code{QUER}. 1422 1423@item QFMT @var{query format} 1424Use the specified @var{query format} to format the output of the 1425@code{QUER} command. The query format may be either the name of a query 1426format known to the server (@pxref{Named query definitions}), or an 1427actual query format (@pxref{Formatting query-pr output}). The possible 1428responses are: 1429 1430@code{200 (CODE_OK)} 1431@*The normal response, which indicates that the query format is 1432acceptable. 1433 1434@code{440 (CODE_CMD_ERROR)} 1435@*No query format was supplied. 1436 1437@code{418 (CODE_INVALID_QUERY_FORMAT)} 1438@*The specified query format does not exist, or could not be parsed. 1439 1440@item QUER [@var{PR}] [@var{PR}] [...] 1441Searches the contents of the database for PRs that match the 1442(optional) specified expressions with the @code{EXPR} command. If no 1443expressions were specified with @code{EXPR}, the entire set of PRs is 1444returned. 1445 1446If one or more PRs are specified on the command line, only those PRs 1447will be searched and/or output. 1448 1449The format of the output from the command is determined by the query 1450format selected with the @code{QFMT} command. 1451 1452The possible responses are: 1453 1454@code{418 (CODE_INVALID_QUERY_FORMAT)} 1455@*A valid format was not specified with the @code{QFMT} command prior to 1456invoking @code{QUER}. 1457 1458@code{300 (CODE_PR_READY)} 1459@*One or more PRs will be output using the requested query format. The 1460PR text is quoted using the normal quoting mechanisms for PRs. 1461 1462@code{220 (CODE_NO_PRS_MATCHED)} 1463@*No PRs met the specified criteria. 1464 1465@item ADMV @var{field key} [@var{subfield}] 1466Returns an entry from an administrative data file associated with 1467@var{field}. @var{key} is used to look up the entry in the data file. If 1468@var{subfield} is specified, only the value of that subfield is 1469returned; otherwise, all of the fields in the adm data file are 1470returned, separated by colons @samp{:}. 1471 1472The responses are: 1473 1474@code{410 (CODE_INVALID_FIELD_NAME)} 1475The specified field does not exist. 1476 1477@code{221 (CODE_NO_ADM_ENTRY)} 1478An adm entry matching the key was not found, or the field does not have 1479an adm file associated with it. 1480 1481@code{350 (CODE_INFORMATION)} 1482The normal response; the supplied text is the requested field(s). 1483@end table 1484 1485@node gnatsd environment variables 1486@section @code{gnatsd} environment variables 1487@cindex @code{gnatsd} environment variables 1488@cindex @code{GNATSDB} 1489 1490@code{gnatsd} supports the @code{GNATSDB} environment varable, 1491@xref{Environment}, in almost the same way as the @sc{gnats} tools do. 1492This variable is used to determine which database to use. For a local 1493database, it contains the name of the database to 1494access. @code{gnatsd} cannot service remote databases (though it might 1495be interesting if it could) so the database is always assumed to be 1496local. 1497 1498If @code{GNATSDB} is not set and the @code{--database} option is not 1499supplied, it is assumed that the database is local and that its name is 1500@samp{default}. 1501 1502@c =============================================================== 1503@node Access Control 1504@appendix Controlling access to databases 1505 1506@menu 1507* Overview:: 1508* Overall gnatsd access level:: 1509* gnatsd.host_access:: Per-host access settings 1510* gnatsd.user_access:: Access levels per user 1511* Privileged gnatsd commands:: 1512@end menu 1513 1514@node Overview 1515@section Overview 1516 1517@sc{gnats} supports granting various levels of access to the @sc{gnats} 1518databases served by the network daemon, @code{gnatsd}. 1519 1520@sc{gnats} access can be controlled at these levels: 1521 1522@table @code 1523@item deny 1524gnatsd closes the connection 1525 1526@item none 1527no further access until userid and password given 1528 1529@item listdb 1530only listing of available databases is allowed 1531 1532@item view 1533query and view PRs with Confidential=no only 1534 1535@item viewconf 1536query and view PRs with Confidential=yes 1537 1538@item edit 1539full edit access 1540 1541@item admin 1542full admin access 1543@end table 1544 1545@noindent These access levels are used in the following settings: 1546 1547@itemize @bullet 1548@item overall gnatsd access level 1549 1550@item overall access level set by host name or IP address 1551 1552@item overall access level set by userid and password 1553 1554@item per-database access level set by userid and password 1555@end itemize 1556 1557@node Overall gnatsd access level 1558@section Overall @code{gnatsd} access level 1559 1560@noindent The overall @code{gnatsd} access level is set by starting @code{gnatsd} 1561with the option 1562 1563@example 1564@code{-m} @var{level} or @code{--maximum-access-level}=@var{level}, 1565@end example 1566 1567@noindent where @var{level} is one of the six access levels listed 1568above. This restricts any access to the @sc{gnats} daemon to levels up 1569to and including @var{level}, regardless of the settings in the access 1570control files discussed below. If this option is left out, any access 1571levels set in the access control files will be allowed. 1572 1573The discussion below assumes that the pre-build configure of @sc{gnats} 1574was done without altering the default values for the 1575@code{--with-gnatsd-user-access-file} and 1576@code{--with-gnatsd-host-access-file} options. If non-default values 1577were given, substitute as appropriate below. 1578 1579@node gnatsd.host_access 1580@section Overall access levels per host 1581@cindex @file{gnatsd.host_access} 1582 1583The host access file (by default 1584@file{/usr/local/etc/gnats/gnatsd.host_access}) controls overall 1585access levels on a per-host basis, meaning that settings in this file 1586apply across all databases on the server. Entries in this file are in 1587the following format: 1588 1589@var{host:access-level:whatever} 1590 1591@noindent @var{host} is the hostname or IP address of the host contacting 1592gnatsd. Wildcard characters are supported: @samp{*} matches anything; 1593@samp{?} matches any single character. By using wildcards, you can 1594specify access levels for entire network subnets and domains. Note 1595that when @sc{gnats} authenticates hosts, it reads the entries in this 1596file in sequence until a match is found. This means that wildcard 1597entries must be placed near the end of the file, otherwise, they 1598will override non-wildcard entries appearing after the wildcard 1599ones. 1600 1601The second field is the access level of @var{host}. The default is 1602@code{deny}. If the user's hostname isn't in the file or its access 1603level is set to @code{deny}, the connection is closed immediately. 1604 1605@sc{gnats} currently doesn't make use of the third field. Remember to 1606still include the second @samp{:} on the line if you choose to leave the third 1607field empty. 1608 1609Whenever a @code{CHDB} command is processed (or defaulted), the user's 1610access level is set to the level for their host, as determined by the 1611values in the @file{gnatsd.host_access} file. However, even if a host 1612is given the @code{none} access level, an individual can still give the 1613@code{USER} command to possibly gain a higher (but never lower) access 1614than is set for their host. The gnatsd @code{USER} command takes two 1615arguments: @code{USER <userid> <passwd>}. 1616 1617@node gnatsd.user_access 1618@section Access levels per user 1619@cindex @file{gnatsd.user_access} 1620 1621Access levels per user can be set both across all databases on the 1622server or on a per-database basis. The @file{gnatsd.user_access} file 1623in a database's @file{gnats-adm} directory specifies the user access 1624rules for that database. If it doesn't exist, or doesn't contain the 1625user name given to @code{gnatsd}, then the overall user access file 1626(by default @w{@file{/usr/local/etc/gnats/gnatsd.user_access}}) 1627specifying the per-user access levels across all the databases on the 1628server is checked. 1629 1630The user access files can only @emph{increase} the access level 1631defined in the host access files for the given host, they can never 1632lower it. 1633 1634If the access level is @code{none} after processing the userid and 1635password, the connection is closed. 1636 1637The @file{gnatsd.user_access} files can contain plain text passwords, in 1638such a case they should be owned by the @sc{gnats} user with file 1639permission 600. 1640 1641Wildcard characters are supported for the userid and password with 1642plain text passwords. A null string or @samp{*} matches anything; 1643@samp{?} matches any one character. Note that when @sc{gnats} 1644authenticates users, it reads the entries in this file in sequence 1645until a match is found. This means that wildcard entries must be 1646placed near the end of the file, otherwise, they will override 1647non-wildcard entries appearing after the wildcard ones. 1648 1649Entries in the database-specific @file{gnatsd.user_access} user access file 1650in the @file{gnats-adm} directory of the database have the following 1651general format: 1652 1653@var{userid:password:access-level} 1654 1655The overall @file{gnatsd.user_access} user access file adds a fourth 1656@var{databases} field: 1657 1658@var{userid:password:access-level:databases} 1659 1660@noindent @var{password} should either be in plain text, DES 1661@code{crypt()}@footnote{DES crypt is the standard password encryption 1662format used by most UNIX systems} or MD5 hash format@footnote{MD5 is 1663only supported on platforms that have a @code{crypt()} function that 1664supports MD5. Among others, this currently includes @sc{gnu} Linux and 1665OpenBSD.}. 1666 1667If the password is in plain text format, it must be prefixed by 1668@samp{$0$} and if it is in MD5 format, it needs to be prefixed by the 1669string @samp{$1$}.@footnote{Some systems support even more encryption 1670methods. In FreeBSD, for instance, a prefix of @samp{$2$} implies 1671Blowfish encoding. @sc{gnats} will happily accept any encryption that 1672the OS supports.} Passwords encrypted by @code{crypt()} should have no 1673prefix. If no password is given then users can login with an empty 1674password string. 1675 1676A @code{gnats-passwd} tool to manage @file{gnatsd.user_access} files is 1677planned. In the meantime, @code{crypt()} passwords can be generated by 1678using standard UNIX passwords tools, while MD5 passwords can be 1679generated with the following little Perl snippet: 1680 1681@example 1682perl -e 'use Crypt::PasswdMD5 ; print Crypt::PasswdMD5::unix_md5_crypt 1683"@var{password}" , time() % 100000000' 1684@end example 1685 1686@noindent If your Perl installation doesn't have the Crypt module 1687installed, you need to install it. On most systems, the following 1688command achieves this: 1689 1690@example 1691perl -MCPAN -e 'install Crypt::PasswdMD5' 1692@end example 1693 1694A tool for conversion of pre-version 4 @file{gnatsd.user_access} files is 1695distributed with @sc{gnats} 4. @xref{gnats-pwconv,,Converting old 1696password files}. 1697 1698@noindent The @var{access-level} field should contain one of the values listed at 1699the beginning of this appendix. This overrides (increases but never 1700lowers) the access level given as the default for the user's host in the 1701global gnatsd.host_access file. 1702 1703The following shows an example @file{gnatsd.user_access} file with 1704plain text passwords: 1705 1706@example 1707rickm:$0$ruckm:edit 1708pablo:$0$pueblo:view 1709*::none 1710@end example 1711 1712@noindent And this is the same file with MD5-encrypted passwords: 1713@example 1714rickm:$1$92388613$D7ZIYikzTUqd./dODTFrI.:edit 1715pablo:$1$92388652$QRfAhIBG5elT.FQjQKhj80:view 1716*::none 1717@end example 1718 1719@noindent In these examples, anybody other than rickm and pablo get 1720denied access, assuming that the host access level is also @code{none}. 1721You could set the catch-all rule at the end to be @code{*::view} to 1722allow view access to anyone who does not supply a password. Note the 1723important detail that such a rule would allow view access only to 1724persons who do not supply a password at all, i.e. if rickm or pablo tries 1725to log in but mistypes his password, this rule would not apply and 1726they would be denied access entirely. This is by design, since people 1727might be surprised if they suddenly found themselves logged in, but with 1728a lower access level than they usually have. 1729 1730The @var{databases} field contains a comma-separated list of database 1731names, as defined in the @file{databases} file (@pxref{databases 1732file,,The @code{databases} file}. Wildcard characters are 1733supported. The databases listed in this field are the ones to which 1734the other settings on the same line will be applied. 1735 1736@node Privileged gnatsd commands 1737@section Privileged @code{gnatsd} commands 1738 1739Every @code{gnatsd} command has a minimum access level attached to 1740it. If your access level is too low for a command, you get this 1741response: 1742 1743@example 1744 LOCK 12 1745 422 You are not authorized to perform this operation (LOCK). 1746@end example 1747 1748@noindent The commands @code{CHDB}, @code{USER} and @code{QUIT} are 1749unrestricted. 1750 1751@noindent The @code{DBLS} command requires at least @code{listdb} access. 1752 1753@noindent A user must have at least @code{edit} access for these commands: 1754 1755@table @code 1756@item LKDB 1757lock the main @sc{gnats} database. 1758 1759@item UNDB 1760unlock the main @sc{gnats} database. 1761 1762@item LOCK @var{PR user pid} 1763lock @var{PR} for @var{user} and optional @var{pid} and return PR text. 1764 1765@item UNLK @var{PR} 1766unlock @var{PR}. 1767 1768@item EDIT @var{PR} 1769check in edited @var{PR}. 1770 1771@item APPN @var{PR} @var{field}, REPL @var{PR} @var{field} 1772Appends to or replaces the contents of @var{field} in @var{PR}. 1773@end table 1774 1775The @code{DELETE} @var{PR} command is special in that it requires 1776@code{admin} access. 1777 1778@noindent All other commands require @code{view} access. 1779 1780@code{edit-pr} and @code{query-pr} accept the command line arguments 1781@code{-v|--user} and @code{-w|--passwd}. @xref{GNATS user tools,,The 1782@sc{gnats} User Tools}. 1783 1784@c =============================================================== 1785@node Regexps 1786@appendix Querying using regular expressions 1787@cindex querying using regexps 1788@cindex regular expressions 1789@cindex syntax of regexps 1790 1791See also @ref{Query expressions}. 1792 1793Unfortunately, we do not have room in this manual for a complete 1794exposition on regular expressions. The following is a basic summary of 1795some regular expressions you might wish to use. 1796 1797@emph{NOTE: When you use query expressions containing regular 1798expressions as part of an ordinary query-pr shell command line, you need 1799to quote them with @code{''}, otherwise the shell will try to interpret 1800the special characters used, yielding highly unpredictable results.} 1801 1802@xref{Regular Expression Syntax,,Regular Expression Syntax,regex,Regex}, 1803for details on regular expression syntax. Also see @ref{Regexps,,Syntax 1804of Regular Expressions,emacs,GNU Emacs Manual}, but beware that the 1805syntax for regular expressions in Emacs is slightly different. 1806 1807All search criteria options to @code{query-pr} rely on regular 1808expression syntax to construct their search patterns. For example, 1809 1810@smallexample 1811query-pr --expr 'State="open"' --format full 1812@end smallexample 1813 1814@noindent 1815matches all PRs whose @code{State} values match with the regular 1816expression @samp{open}. 1817 1818We can substitute the expression @samp{o} for @samp{open}, according 1819to @sc{gnu} regular expression syntax. This matches all values of 1820@code{State} which begin with the letter @samp{o}. 1821 1822We see that 1823 1824@smallexample 1825query-pr --expr 'State="o"' --format full 1826@end smallexample 1827 1828is equivalent to 1829 1830@smallexample 1831query-pr --expr 'State="open"' --format full 1832@end smallexample 1833 1834@noindent 1835in this case, since the only value for @code{State} which matches 1836the expression @samp{o} in a standard installation is @samp{open}. 1837@samp{State="o"} also matches @samp{o}, @samp{oswald}, and even 1838@samp{oooooo}, but none of those values are valid states for a Problem 1839Report in default @sc{gnats} installations. 1840 1841We can also use the expression operator @samp{|} to signify a logical 1842@code{OR}, such that 1843 1844@smallexample 1845query-pr --expr 'State="o|a"' --format full 1846@end smallexample 1847 1848@noindent 1849matches all @samp{open} or @samp{analyzed} Problem Reports. 1850 1851Regular expression syntax considers a regexp token surrounded with 1852parentheses, as in @w{@samp{(@var{regexp})}}, to be a @dfn{group}. This 1853means that @w{@samp{(ab)*}} matches any number (including zero) of 1854contiguous instances of @samp{ab}. Matches include @samp{}, @samp{ab}, 1855and @samp{ababab}. 1856 1857Regular expression syntax considers a regexp token surrounded with 1858square brackets, as in @w{@samp{[@var{regexp}]}}, to be a @dfn{list}. 1859This means that @w{@samp{Char[(ley)(lene)(broiled)}} matches any of the 1860words @samp{Charley}, @samp{Charlene}, or @samp{Charbroiled} (case is 1861significant; @samp{charbroiled} is not matched). 1862 1863Using groups and lists, we see that 1864 1865@smallexample 1866query-pr --expr 'Category="gcc|gdb|gas"' --format full 1867@end smallexample 1868 1869@noindent 1870is equivalent to 1871 1872@smallexample 1873query-pr --expr 'Category="g(cc|db|as)"' --format full 1874@end smallexample 1875 1876@noindent 1877and is also very similar to 1878 1879@smallexample 1880query-pr --expr 'Category="g[cda]"' --format full 1881@end smallexample 1882 1883@noindent 1884with the exception that this last search matches any values which begin 1885with @samp{gc}, @samp{gd}, or @samp{ga}. 1886 1887The @samp{.} character is known as a @dfn{wildcard}. @samp{.} matches 1888on any single character. @samp{*} matches the previous character 1889(except newlines), list, or group any number of times, including zero. 1890Therefore, we can understand @samp{.*} to mean ``match zero or more 1891instances of any character.'' 1892 1893@smallexample 1894query-pr --expr 'State=".*a"' --format full 1895@end smallexample 1896 1897@noindent 1898matches all values for @code{State} which contain an @samp{a}. (These 1899include @samp{analyzed} and @samp{feedback}.) 1900 1901Another way to understand what wildcards do is to follow them on their 1902search for matching text. By our syntax, @samp{.*} matches any 1903character any number of times, including zero. Therefore, @samp{.*a} 1904searches for any group of characters which end with @samp{a}, ignoring 1905the rest of the field. @samp{.*a} matches @samp{analyzed} (stopping at 1906the first @samp{a}) as well as @samp{feedback}. 1907 1908@emph{Note:} When using @samp{fieldtype:Text} or 1909@samp{fieldtype:Multitext} (@pxref{Query expressions}), you do not have 1910to specify the token @samp{.*} at the beginning of your expression to 1911match the entire field. For the technically minded, this is because 1912these queries use @samp{re_search} rather than @samp{re_match}. 1913@samp{re_match} @dfn{anchors} the search at the beginning of the field, 1914while @samp{re_search} does not anchor the search. 1915 1916For example, to search in the @code{>Description:} field for the text 1917 1918@smallexample 1919The defrobulator component returns a nil value. 1920@end smallexample 1921 1922@noindent 1923we can use 1924 1925@smallexample 1926query-pr --expr 'fieldtype:Multitext="defrobulator.*nil"' --format full 1927@end smallexample 1928 1929To also match newlines, we have to include the expression @samp{(.|^M)} 1930instead of just a dot (@samp{.}). @samp{(.|^M)} matches ``any single 1931character except a newline (@samp{.}) @emph{or} (@samp{|}) any newline 1932(@samp{^M}).'' This means that to search for the text 1933 1934@smallexample 1935The defrobulator component enters the bifrabulator routine 1936and returns a nil value. 1937@end smallexample 1938 1939@noindent 1940we must use 1941 1942@smallexample 1943query-pr --expr 'fieldtype:Multitext="defrobulator(.|^M)*nil"' 1944 --format full 1945@end smallexample 1946 1947To generate the newline character @samp{^M}, type the following 1948depending on your shell: 1949 1950@table @code 1951@item csh 1952@samp{@emph{control}-V @emph{control}-M} 1953 1954@item tcsh 1955@samp{@emph{control}-V @emph{control}-J} 1956 1957@item sh (@emph{or} bash) 1958Use the @key{RETURN} key, as in 1959 1960@smallexample 1961(.| 1962) 1963@end smallexample 1964@end table 1965 1966Again, see @ref{Regular Expression Syntax,,Regular Expression 1967Syntax,regex,Regex}, for a much more complete discussion on regular 1968expression syntax. 1969 1970@c =============================================================== 1971 1972@node dbconfig recipes 1973@appendix @file{dbconfig} recipes 1974@cindex dbconfig 1975@cindex @file{dbconfig} recipes 1976 1977The @file{dbconfig} file (@ref{dbconfig file,,The @file{dbconfig} 1978file}) is the heart of any @sc{gnats} installation. It contains some 1979very powerful machinery, something which this appendix tries to 1980illustrate. 1981 1982We provide a range of examples that are both intended to be useful in 1983their own right and to serve as starting points or building blocks for 1984your own modifications. 1985 1986@subsubheading Provide Gnatsweb URL in initial response 1987 1988Sites that have Gnatsweb installed may wish to modify the response 1989e-mail which is sent to the submitter of a PR so that it includes a 1990URL where the status of the PR can be monitored. In order to allow 1991this, you should first create an entry in @file{gnatsd.user_access} 1992which allows viewing of PRs in your database 1993(@xref{gnatsd.user_access,,The @file{gnatsd.user_access} file}.) 1994 1995Next, locate the entry @code{mail-format 1996"initial-response-to-submitter"} in the @file{dbconfig} file of your 1997database and add the following @emph{before} the line reading ``The 1998individual assigned...'' in the @code{body} section: 1999 2000@verbatim 2001\nYou can follow the status of this report on\n\ 2002http://hostname/cgi-bin/scriptname?\n\ 2003cmd=view&database=dbname&user=username&\n\ 2004password=passwd&pr=%s\n\n\ 2005@end verbatim 2006 2007@noindent 2008Substitute @code{hostname}, @code{cgi-bin} and @code{scriptname} as 2009appropriate for the setup of your web server. The part before the 2010@samp{?} would typically look something like 2011@code{http://www.example.com/cgi-bin/gnatsweb.pl}. Substitute the 2012name of your database for @code{dbname}, and the username and password 2013of the user with @code{view} rights for @code{username} and 2014@code{passwd}. 2015 2016@noindent 2017Next, add a @code{Number} to the @code{fields} list statement inside 2018the @code{body} so it reads as follows: 2019 2020@verbatim 2021fields { "Category" "Number" "Number" "Responsible" 2022 "Category" "Responsible" "Synopsis" 2023 "Arrival-Date" } 2024@end verbatim 2025 2026@subsubheading State full name of responsible in initial response 2027 2028The initial e-mail response to the submitter of a PR identifies the 2029responsible person assigned to the PR as follows: ``The individual 2030assigned to look at your report is: @var{GNATS username}''. Some 2031sites may wish to modify this so that the full name of the responsible 2032person is used instead of the @sc{gnats} user name. 2033 2034The full name is contained in the @code{fullname} subfield of the 2035user's entry in the @file{responsible} file and can be accessed as 2036@code{Responsible[fullname]} (@pxref{administrative files,,Enumerated 2037field administrative files}.) 2038 2039The change is achieved by editing the @file{dbconfig} item 2040@code{mail-format "initial-response-to-submitter"} and changing the 2041@code{fields} part of the @code{Body} from 2042 2043@verbatim 2044fields { "Category" "Number" "Responsible" 2045 "Category" "Responsible" "Synopsis" 2046 "Arrival-Date" } 2047@end verbatim 2048 2049@noindent 2050to 2051 2052@verbatim 2053fields { "Category" "Number" "Responsible[fullname]" 2054 "Category" "Responsible" "Synopsis" 2055 "Arrival-Date" } 2056@end verbatim 2057 2058@subsubheading Append-only Audit-Trail 2059 2060The Audit-Trail of a PR is by default editable. For some 2061applications, one might want to make the Audit-Trail append-only, so 2062it provides a full and unchangeable case history. Also by default, 2063only certain changes, such as change of state and change of 2064responsible gets recorded in the Audit-Trail. In some cases, it might 2065also be convenient to have a way of inserting comments directly into 2066the Audit-Trail. 2067 2068The following procedure creates such an append-only Audit-Trail and 2069adds a PR field which makes it possible to register comments in the 2070Audit-Trail. 2071 2072@noindent 2073First, add the keyword @code{read-only} to the Audit-Trail field 2074definition in @file{dbconfig}. 2075 2076@noindent 2077Then, add the following field definition to @file{dbconfig}: 2078 2079@verbatim 2080field "Add-To-Audit-Trail" { 2081 description "Add a log entry to the Audit Trail" 2082 multitext { default "\n" } 2083 on-change { 2084 add-audit-trail 2085 audit-trail-format { 2086 format "**** Comment added by %s on %s ****\n %s\n\n" 2087 fields { "$EditUserEmailAddr" "$CurrentDate" "$NewValue" 2088 } 2089 } 2090 } 2091 on-change { 2092 set-field "Add-To-Audit-Trail" { "\n" } 2093 } 2094} 2095@end verbatim 2096 2097@anchor{release-based support} 2098@subsubheading Supporting @sc{gnats} ``release-based'' fields 2099 2100When installing @sc{gnats} version 3.x, it was possible to choose 2101whether to enable three optional fields: @code{Quarter}, @code{Keywords} 2102and @code{Date-Required}. Default installations had these fields 2103switched off, and installations which had them were called 2104``release-based''. 2105 2106The default @file{dbconfig} shipped with @sc{gnats} version 4 or newer 2107does not have these fields, so if you are upgrading from an old 2108release-based system, you need to add the following field definitions to 2109your @file{dbconfig} file: 2110 2111@verbatim 2112field "Quarter" { 2113 description "What quarter does the PR fall into?" 2114 text 2115 query-default inexact-regexp 2116 textsearch 2117} 2118 2119field "Keywords" { 2120 description "Keywords used to index this PR" 2121 text 2122 query-default inexact-regexp 2123 textsearch 2124} 2125 2126field "Date-Required" { 2127 description "Date that the PR must be fixed by" 2128 date 2129} 2130@end verbatim 2131 2132A side note: Pre-release versions of @sc{gnats} 4 also had a field 2133named @code{Cases}. For those who may need it, here is the field 2134definition of @code{Cases}: 2135 2136@verbatim 2137field "Cases" { 2138 text 2139 query-default inexact-regexp 2140 textsearch 2141} 2142@end verbatim 2143@c =============================================================== 2144 2145@node Support 2146@appendix @sc{gnats} support 2147 2148@cindex @sc{gnats} support 2149The @sc{gnats} home page is located at 2150@url{http://www.gnu.org/software/gnats}. It contains all the 2151important references to the available information about @sc{gnats} and 2152the related software. 2153 2154There is also a special page dedicated to the @sc{gnats} development 2155at @url{http://savannah.gnu.org/projects/gnats}. 2156 2157@cindex mailing lists 2158There are several @sc{gnats} mailing lists. The most important ones 2159are: 2160 2161@table @email 2162@item info-gnats@@gnu.org 2163Announcements and other important information about @sc{gnats} and the 2164related software. This is a very low volume moderated list. 2165 2166@item bug-gnats@@gnu.org 2167The bug reporting mailing list on the @sc{gnats} itself. Please note 2168that the preferred way to report @sc{gnats} bugs is to submit them via 2169the web interface at 2170@url{http://bugs.gnu.org/cgi-bin/gnatsweb.pl?database=gnats}. New bug 2171reports submitted via the web interface are copied to the mailing list 2172automatically. 2173 2174@item help-gnats@@gnu.org 2175General discussion about @sc{gnats}. Anything related to @sc{gnats} 2176(user questions, development, suggestions, etc.) can be discussed 2177there. 2178@end table 2179 2180The complete list of @sc{gnats} related mailing lists is available 2181from the web page at @url{http://savannah.gnu.org/project/gnats}. 2182 2183@cindex bug reporting 2184When you report problems concerning @sc{gnats} itself, please do not 2185forget to provide especially the following information: 2186 2187@itemize @bullet 2188@item 2189The @sc{gnats} version you are using. 2190 2191@item 2192The @emph{exact} way how to reproduce the bug. 2193 2194@item 2195Your configuration. 2196 2197@item 2198If you encounter a compilation or build problem, it is especially 2199important to mention the operating system, compiler and possibly other 2200build utilities you use. 2201@end itemize 2202 2203Providing this information in the initial report avoids further 2204unnecessary communication, saves our limited development resources and 2205helps to track down and fix the problem soon. 2206 2207@c =============================================================== 2208 2209@ignore 2210@c complete this someday... 2211@node Glossary 2212@unnumbered Glossary 2213 2214@table @strong 2215@item PR 2216Short for ``Problem Report''. An electronic mail message which reports 2217a problem. A @dfn{record} in the @sc{gnats} database. 2218 2219@item Support Site 2220A central site that provides resources for maintainers of a body of 2221work, such as a software package. We refer to the Support Site as the 2222location where @sc{gnats} is installed and functional. 2223 2224@item Database 2225An organized collection of information. 2226 2227@item @sc{gnats} 2228The @sc{gnu} Problem Report Management System. 2229 2230@item Field 2231A location for specific information. A group of fields make up a 2232Problem Report. 2233 2234@item Mail header 2235Defined by the Internet Internet standard RFC-822 2236 2237@item Category 2238@item Submitter 2239@item Originator 2240@item Query 2241@item Report 2242@item Site 2243@item Edit 2244@item Submit 2245@item Bug 2246@item State 2247@item ID Number 2248@item Synopsis 2249@item Confidential 2250@item Severity 2251@item Priority 2252@item Responsible 2253@item Configuration 2254@item Class 2255@item Environment 2256@item Description 2257@item Audit-Trail 2258@item Unformatted 2259@item Fix 2260@item Release 2261@item Makefile 2262@item gnats-admin 2263@item pending 2264@item send-pr 2265@item edit-pr 2266@item Maintainers 2267@item timestamp 2268@item utility 2269@item tool 2270 2271@end table 2272 2273@end ignore 2274 2275@node Index 2276@unnumbered Index 2277 2278@printindex cp 2279 2280@bye 2281 2282