idnits 2.17.1 draft-ietf-nntpext-imp-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Found some kind of copyright notice around line 1168 but it does not match any copyright boilerplate known by this tool. Expected boilerplate is as follows today (2024-03-28) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 25 longer pages, the longest (page 2) being 60 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 26 pages -- Found 26 instances of the string 'FORMFEED[Page...' -- is this a case of missing nroff postprocessing? Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 567 instances of lines with control characters in the document. ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 57 has weird spacing: '...for the devel...' == Line 789 has weird spacing: '...log the event...' == Line 1148 has weird spacing: '...ference imple...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 1998) is 9357 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: 'GMT' on line 217 -- Looks like a reference, but probably isn't: '0-9a-zA-Z' on line 954 ** Obsolete normative reference: RFC 977 (ref. '1') (Obsoleted by RFC 3977) -- Possible downref: Non-RFC (?) normative reference: ref. '2' ** Obsolete normative reference: RFC 1036 (ref. '3') (Obsoleted by RFC 5536, RFC 5537) -- Possible downref: Non-RFC (?) normative reference: ref. '4' -- Possible downref: Non-RFC (?) normative reference: ref. '5' -- Possible downref: Non-RFC (?) normative reference: ref. '6' -- Possible downref: Non-RFC (?) normative reference: ref. '7' ** Obsolete normative reference: RFC 1305 (ref. '9') (Obsoleted by RFC 5905) Summary: 14 errors (**), 0 flaws (~~), 7 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT S. Barber 3 Expires: January 7, 1999 Academ Consulting Services 4 August 1998 5 Common NNTP Extensions 6 draft-ietf-nntpext-imp-03.txt 8 Status of this Document 10 This document is an Internet-Draft. Internet-Drafts are working docu- 11 ments of the Internet Engineering Task Force (IETF), its areas, and its 12 working groups. Note that other groups may also distribute working doc- 13 uments as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six months 16 and may be updated, replaced, or obsoleted by other documents at any 17 time. It is inappropriate to use Internet- Drafts as reference material 18 or to cite them other than as ``work in progress.'' 20 To learn the current status of any Internet-Draft, please check the 21 ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow 22 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 23 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 24 ftp.isi.edu (US West Coast). 26 Copyright 28 Copyright (C) The Internet Society (1998). All Rights Reserved. 30 Abstract 32 In this document, a number of popular extensions to the NNTP protocol 33 defined in RFC977 are documented and discussed. While this document is 34 not intended to serve as a standard of any kind, it will hopefully serve 35 as a reference document for future implementers of the NNTP protocol. In 36 the role, this document would hopefully create the possibility for some 37 level of interoperability among implementations that make use of exten- 38 sions. 40 Introduction 42 RFC977[1] defines the NNTP protocol and was released over a decade ago. 43 Since then, NNTP has become one of the most popular protocols in use on 44 the Internet. Many implementations of the protocol have been created on 45 many different platforms and operating systems. With the growth in use 46 of the protocol, work began on a revision to NNTP in 1991, but that work 47 did not result in a new standard protocol specification. However, many 48 ideas from that working group did find their way into many implementa- 49 tions of NNTP. Additionally, many other extensions, often created by 50 newsreader authors, are also in use. This document will capture and 51 define all known extensions to NNTP available in official NNTP server 52 releases of some type as of this writing. Where possible, the server 53 software first implementing a particular extension will be noted. It is 54 the hope of the author that using this document in tandem with RFC977 55 will limit the addition of new extensions that essentially do the same 56 thing. Software developers may wish to use this document and others[2] 57 as a resource for the development of new software. 59 This document does not specify an Internet Standard of any kind. It 60 only attempts to document current practices. While this document may 61 clarify some ambiguity in RFC977, RFC977 should be regarded as authori- 62 tative in all cases. There are some implementations that are not 63 strictly RFC977 compliant and where necessary, these deviations from the 64 standard will be noted. This document does reflect the work of the IETF 65 NNTP-EXT working group chaired by Ned Freed and Stan Barber. 67 This document is provided to help implementers have a uniform source of 68 information about extensions, however, it is important for any prospec- 69 tive implementer to understand that the extensions listed here are NOT 70 part of any current standard for NNTP. In fact, some of the ones listed 71 in this document should not be included in new NNTP implementations as 72 they should no longer be used modern NNTP environments. Such commands 73 should be considered historic and are documented as such in this docu- 74 ment. 76 Extensions fall into three categories: transport, newsreader and other. 77 Transport extensions are additions to the NNTP specification that were 78 made specifically to move news articles from one server to another 79 server. Newsreader extensions are additions to the NNTP specification 80 that were made to assist NNTP clients in selecting and retrieving news 81 articles from servers. Other extensions to the NNTP specification are 82 those which did not specifically fall into either of the other two cate- 83 gories. Examples of other extensions include authentication and time-of- 84 day extensions. 86 For each command, the format of section 3 of RFC977 will be used. 88 1. Transport Extensions 90 A transport extension is one which is primarily used in interserver com- 91 munications. Following are the descriptions of each transport extension 92 commands and the responses which will be returned by those commands. 94 Each command is shown in upper case for clarity, although case is 95 ignored in the interpretation of commands by the NNTP server. Any 96 parameters are shown in lower case. A parameter shown in [square brack- 97 ets] is optional. For example, [GMT] indicates that the triglyph GMT 98 may present or omitted. A parameter that may be repeated is followed by 99 an ellipsis. 101 1.1. The CHECK command 103 CHECK 105 CHECK is used by a peer to discover if the article with the specified 106 message-id should be sent to the server using the TAKETHIS command. The 107 peer does not have to wait for a response from the server before sending 108 the next command. 110 >From using the responses to the sequence of CHECK commands, a list of 111 articles to be sent can be constructed for subsequent use by the 112 TAKETHIS command. 114 The use of the CHECK command for streaming is optional. Some implementa- 115 tions will directly use the TAKETHIS command and send all articles in 116 the send queue on that peer for the server. 118 On some implementations, the use of the CHECK command is not permitted 119 when the server is in slave mode (via the SLAVE command). 121 Responses that are of the form X3X must specify the message-id in the 122 response. 124 1.1.1. Responses 126 238 no such article found, please send it to me 127 400 not accepting articles 128 431 try sending it again later 129 438 already have it, please don't send it to me 130 480 Transfer permission denied 131 500 Command not understood 133 1.2. The MODE STREAM command 135 MODE STREAM 137 MODE STREAM is used by a peer to indicate to the server that it would 138 like to suspend the lock step conversational nature of NNTP and send 139 commands in streams. This command should be used before TAKETHIS and 140 CHECK. See the section on the commands TAKETHIS and CHECK for more 141 details. 143 1.2.1. Responses 145 203 Streaming is OK 146 500 Command not understood 148 1.3. The TAKETHIS command 150 TAKETHIS 152 TAKETHIS is used to send articles to a server when in streaming mode. 153 The entire article (header and body, in that sequence) is sent immedi- 154 ately after the peer sends the TAKETHIS command. The peer does not have 155 to wait for a response from the server before sending the next command 156 and the associated article. 158 During transmission of the article, the peer should send the entire 159 article, including header and body, in the manner specified for text 160 transmission from the server. See RFC977, Section 2.4.1 for details. 162 Responses that are of the form X3X must specify the message-id in the 163 response. 165 1.3.1. Responses 167 239 article transferred ok 168 400 not accepting articles 169 439 article transfer failed 170 480 Transfer permission denied 171 500 Command not understood 173 1.4. The XREPLIC command 175 XREPLIC ggg:nnn[,ggg:nnn...] 177 The XREPLIC command makes it possible to exactly duplicate the news 178 spool structure of one server in another server. It first appeared in 179 INN. 181 This command works similarly to the IHAVE command as specified in 182 RFC977. The same response codes are used. The command line arguments 183 consist of entries separated by a single comma. Each entry consists of a 184 news group name, a colon, and an article number. If the server responds 185 with a 335 response, the article should be filed in the news group(s) 186 and article number(s) specified in the XREPLIC command line. If the 187 server cannot do successfully install the article once it has accepted 188 it, a 436 or 437 response code can be used to indicate the failure. 190 This command should only be used when the receiving server is being fed 191 by only one other server. It is likely that when used with servers that 192 have multiple feeds that this command will frequently fail. 194 XREPLIC slaving has been deprecated in INN version 1.7.2 and later. INN 195 now has the ability to slave servers via transparent means, simply by 196 having the article's Xref header transferred. (In previous versions, 197 this header was generated locally and stripped off on outgoing feeds.) 198 It is likely that future versions of INN will no longer support XREPLIC. 200 1.4.1. Responses 202 235 article transferred ok 203 335 send article to be transferred. End with . 204 435 article not wanted - do not send it 205 436 transfer failed - try again later 206 437 article rejected - do not try again 208 2. Newsreader Extensions 210 Newsreader extensions are those which are primarily used by newsreading 211 clients. Following are the descriptions of each newsreader extension 212 commands and the responses which will be returned by those commands. 214 Each command is shown in upper case for clarity, although case is 215 ignored in the interpretation of commands by the NNTP server. Any 216 parameters are shown in lower case. A parameter shown in [square brack- 217 ets] is optional. For example, [GMT] indicates that the triglyph GMT 218 may present or omitted. A parameter that may be repeated is followed by 219 an ellipsis. Mutually exclusive parameters are separated by a vertical 220 bar (|) character. For example, ggg| indicates that a group 221 name or a may be specified, but not both. Some parameters, 222 notably , is case specific. See RFC 1036 for these details. 224 Also, certain commands make use of a pattern for selection of multiple 225 news groups. The pattern in all cases is based on the wildmat[4] format 226 introduced by Rich Salz in 1986. Arguments expected to be in wildmat 227 format will be represented by the string wildmat. This format is dis- 228 cussed in detail in section 3.3 of this document. 230 2.1. Extensions to the LIST command 232 The original LIST command took no arguments in RFC977 and returned the 233 contents of the active file in a specific format. Since the original 234 newsreaders made use of other information available in the news trans- 235 port software in addition to the active file, extensions to the LIST 236 command were created to make that information available to NNTP news- 237 readers. There may be other extensions to the LIST command that simply 238 return the contents of a file. This approach is suggested over the addi- 239 tion of over verbs. For example, LIST MOTD could be used instead of 240 adding XMOTD. 242 2.1.1. LIST ACTIVE 244 LIST ACTIVE [wildmat] 246 LIST ACTIVE is exactly the same as the LIST command specified in RFC977. 247 The responses and the format should exactly match the LIST command with- 248 out arguments. If the optional matching parameter is specified, the 249 list is limited to only the groups that match the pattern. Specifying a 250 single group is usually very efficient for the server, and multiple 251 groups may be specified by using wildmat patterns (described later in 252 this document), not regular expressions. If nothing is matched an empty 253 list is returned, not an error. This command first appeared in the UNIX 254 reference version. 256 2.1.2. LIST ACTIVE.TIMES 258 LIST ACTIVE.TIMES 260 The active.times file is maintained by some news transports systems to 261 contain information about the when and who created a particular news 262 group. The format of this file generally include three fields. The first 263 field is the name of the news group. The second is the time when this 264 group was created on this news server measured in seconds since January 265 1, 1970. The third is the email address of the entity that created the 266 news group. When executed, the information is displayed following the 267 215 response. When display is completed, the server will send a period 268 on a line by itself. If the information is not available, the server 269 will return the 503 error response. This command first appeared in the 270 UNIX reference version. 272 2.1.2.1. Responses 274 215 information follows 275 503 program error, function not performed 277 2.1.3. LIST DISTRIBUTIONS 279 LIST DISTRIBUTIONS 281 The distributions file is maintained by some news transport systems to 282 contain information about valid values for the Distribution: line in a 283 news article header and about what the values mean. Each line contains 284 two fields, the value and a short explanation on the meaning of the 285 value. When executed, the information is displayed following the 215 286 response. When display is completed, the server will send a period on a 287 line by itself. If the information is not available, the server will 288 return the 503 error response. This command first appeared in the UNIX 289 reference version. 291 2.1.3.1. Responses 293 215 information follows 294 503 program error, function not performed 296 2.1.4. LIST DISTRIB.PATS 298 LIST DISTRIB.PATS 300 The distrib.pats file is maintained by some news transport systems to 301 contain default values for the Distribution: line in a news article 302 header when posting to particular news groups. This information could be 303 used to provide a default value for the Distribution: line in the header 304 when posting an article. The information returned involves three fields 305 separated by colons. The first column is a weight. The second is a 306 group name or a pattern that can be used to match a group name in the 307 wildmat format. The third is the value of the Distribution: line that 308 should be used when the group name matches and the weight value is the 309 highest. All this processing is done by the news posting client and not 310 by the server itself. The server just provides this information to the 311 client for it to use or ignore as it chooses. When executed, the infor- 312 mation is displayed following the 215 response. When display is com- 313 pleted, the server will send a period on a line by itself. If the infor- 314 mation is not available, the server will return the 503 error response. 315 This command first appeared in INN. 317 2.1.4.1. Responses 319 215 information follows 320 503 program error, function not performed 322 2.1.5. LIST NEWSGROUPS 324 LIST NEWSGROUPS [wildmat] 326 The newsgroups file is maintained by some news transport systems to con- 327 tain the name of each news group which is active on the server and a 328 short description about the purpose of each news group. Each line in the 329 file contains two fields, the news group name and a short explanation of 330 the purpose of that news group. When executed, the information is dis- 331 played following the 215 response. When display is completed, the server 332 will send a period on a line by itself. If the information is not avail- 333 able, the server will return the 503 response. If the optional matching 334 parameter is specified, the list is limited to only the groups that 335 match the pattern (no matching is done on the group descriptions). 336 Specifying a single group is usually very efficient for the server, and 337 multiple groups may be specified by using wildmat patterns (similar to 338 file globbing), not regular expressions. If nothing is matched an empty 339 list is returned, not an error. 341 When the optional parameter is specified, this command is equivalent to 342 the XGTITLE command, though the response code are different. 344 2.1.5.1. Responses 346 215 information follows 347 503 program error, function not performed 349 2.1.6. LIST OVERVIEW.FMT 351 LIST OVERVIEW.FMT 353 The overview.fmt file is maintained by some news transport systems to 354 contain the order in which header information is stored in the overview 355 databases for each news group. When executed, news article header 356 fields are displayed one line at a time in the order in which they are 357 stored in the overview database[5] following the 215 response. When 358 display is completed, the server will send a period on a line by itself. 359 If the information is not available, the server will return the 503 360 response. 362 Please note that if the header has the word "full" (without quotes) 363 after the colon, the header's name is prepended to its field in the out- 364 put returned by the server. 366 Many newsreaders work better if Xref: is one of the optional fields. 368 It is STRONGLY recommended that this command be implemented in any 369 server that implements the XOVER command. See section 2.8 for more 370 details about the XOVER command. 372 2.1.6.1. Responses 374 215 information follows 375 503 program error, function not performed 377 2.1.7. LIST SUBSCRIPTIONS 379 LIST SUBSCRIPTIONS 380 This command is used to get a default subscription list for new users of 381 this server. The order of groups is significant. 383 When this list is available, it is preceded by the 215 response and fol- 384 lowed by a period on a line by itself. When this list is not available, 385 the server returns a 503 response code. 387 2.1.7.1. Responses 389 215 information follows 390 503 program error, function not performed 392 2.2. LISTGROUP 394 LISTGROUP [ggg] 396 The LISTGROUP command is used to get a listing of all the article num- 397 bers in a particular news group. 399 The optional parameter ggg is the name of the news group to be selected 400 (e.g. "news.software.b"). A list of valid news groups may be obtained 401 from the LIST command. If no group is specified, the current group is 402 used as the default argument. 404 The successful selection response will be a list of the article numbers 405 in the group followed by a period on a line by itself. 407 When a valid group is selected by means of this command, the internally 408 maintained "current article pointer" is set to the first article in the 409 group. If an invalid group is specified, the previously selected group 410 and article remain selected. If an empty news group is selected, the 411 "current article pointer" is in an indeterminate state and should not be 412 used. 414 Note that the name of the news group is not case-dependent. It must 415 otherwise match a news group obtained from the LIST command or an error 416 will result. 418 2.2.1. Responses 420 211 list of article numbers follow 421 412 Not currently in newsgroup 422 502 no permission 424 2.3. MODE READER 426 MODE READER is used by the client to indicate to the server that it is a 427 news reading client. Some implementations make use of this information 428 to reconfigure themselves for better performance in responding to news 429 reader commands. This command can be contrasted with the SLAVE command 430 in RFC 977, which was not widely implemented. MODE READER was first 431 available in INN. 433 2.3.1. Responses 435 200 Hello, you can post 436 201 Hello, you can't post 438 2.4. XGTITLE 440 XGTITLE [wildmat] 442 The XGTITLE command is used to retrieve news group descriptions for spe- 443 cific news groups. 445 This extension first appeared in ANU-NEWS, an NNTP implementation for 446 DEC's VMS. The optional parameter is a pattern in wildmat format. When 447 executed, a 282 response is given followed by lines that have two 448 fields, the news group name (which matches the pattern in the argument) 449 and a short explanation of the purpose of the news group. When no argu- 450 ment is specified, the default argument is the current group name. When 451 display is completed, the server sends a period on a line by itself. 453 Please note that this command and the LIST NEWSGROUP command provide the 454 same functionality with different response codes. 456 Since this command provides the same functionality as LIST NEWSGROUP it 457 is suggested that this extension be deprecated and no longer be used in 458 newsreading clients. 460 Note that there is a conflict in one of the response codes from XGTITLE 461 and some of the authentication extensions. 463 2.4.1. Responses 465 481 Groups and descriptions unavailable 466 282 list of groups and descriptions follows 468 2.5. XHDR 470 XHDR header [range|] 471 The XHDR command is used to retrieve specific headers from specific 472 articles. 474 The required parameter is the name of a header line (e.g. "subject") in 475 a news group article. See RFC-1036 for a list of valid header lines. The 476 optional range argument may be any of the following: 478 an article number 479 an article number followed by a dash to indicate all following 480 an article number followed by a dash followed by another article 481 number 483 The optional message-id argument indicates a specific article. The range 484 and message-id arguments are mutually exclusive. If no argument is spec- 485 ified, then information from the current article is displayed. Success- 486 ful responses start with a 221 response followed by a the matched head- 487 ers from all matched messages. Each line containing matched headers 488 returned by the server has an article number (or message ID, if a mes- 489 sage ID was specified in the command), then one or more spaces, then the 490 value of the requested header in that article. Once the output is com- 491 plete, a period is sent on a line by itself. If the optional argument is 492 a message-id and no such article exists, the 430 error response is 493 returned. If a range is specified, a news group must have been selected 494 earlier, else a 412 error response is returned. If no articles are in 495 the range specified, a 420 error response is returned by the server. A 496 502 response will be returned if the client only has permission to 497 transfer articles. 499 Some implementations will return "(none)" followed by a period on a line 500 by itself if no headers match in any of the articles searched. Others 501 return the 221 response code followed by a period on a line by itself. 503 The XHDR command has been available in the UNIX reference implementation 504 from its first release. However, until now, it has been documented only 505 in the source for the server. 507 2.5.1. Responses 509 221 Header follows 510 412 No news group current selected 511 420 No current article selected 512 430 no such article 513 502 no permission 515 2.6. XINDEX 517 XINDEX ggg 518 The XINDEX command is used to retrieve an index file in the format of 519 originally created for use by the TIN[6] news reader. 521 The required parameter ggg is the name of the news group to be selected 522 (e.g. "news.software.b"). A list of valid news groups may be obtained 523 from the LIST command. 525 The successful selection response will return index file in the format 526 used by the TIN news reader followed by a period on a line by itself. 528 When a valid group is selected by means of this command, the internally 529 maintained "current article pointer" is set to the first article in the 530 group. If an invalid group is specified, the previously selected group 531 and article remain selected. If an empty news group is selected, the 532 "current article pointer" is in an indeterminate state and should not be 533 used. 535 Note that the name of the news group is not case-dependent. It must 536 otherwise match a news group obtained from the LIST command or an error 537 will result. 539 The format of the tin-style index file is discussed in the documentation 540 for the TIN newsreader. Since more recent versions of TIN support the 541 news overview (NOV) format, it is recommended that this extension become 542 historic and no longer be used in current servers or future implementa- 543 tions. 545 2.6.1. Responses 547 218 tin-style index follows 548 418 no tin-style index is available for this news group 550 2.7. XOVER 552 XOVER [range] 554 The XOVER command returns information from the overview database for the 555 article(s) specified. This command was originally suggested as part of 556 the OVERVIEW work described in "The Design of a Common Newsgroup 557 Overview Database for Newsreaders" by Geoff Collyer. This document is 558 distributed in the Cnews distribution. 560 The optional range argument may be any of the following: 562 an article number 563 an article number followed by a dash to indicate all following 564 an article number followed by a dash followed by another article 565 number 567 If no argument is specified, then information from the current article 568 is displayed. Successful responses start with a 224 response followed by 569 the overview information for all matched messages. Once the output is 570 complete, a period is sent on a line by itself. If no argument is speci- 571 fied, the information for the current article is returned. A news group 572 must have been selected earlier, else a 412 error response is returned. 573 If no articles are in the range specified, a 420 error response is 574 returned by the server. A 502 response will be returned if the client 575 only has permission to transfer articles. 577 Each line of output will be formatted with the article number, followed 578 by each of the headers in the overview database or the article itself 579 (when the data is not available in the overview database) for that arti- 580 cle separated by a tab character. The sequence of fields must be in 581 this order: subject, author, date, message-id, references, byte count, 582 and line count. Other optional fields may follow line count. Other 583 optional fields may follow line count. These fields are specified by 584 examining the response to the LIST OVERVIEW.FMT command. Where no data 585 exists, a null field must be provided (i.e. the output will have two tab 586 characters adjacent to each other). Servers should not output fields for 587 articles that have been removed since the XOVER database was created. 589 The LIST OVERVIEW.FMT command should be implemented if XOVER is imple- 590 mented. A client can use LIST OVERVIEW.FMT to determine what optional 591 fields and in which order all fields will be supplied by the XOVER com- 592 mand. See Section 2.1.7 for more details about the LIST OVERVIEW.FMT 593 command. 595 Note that any tab and end-of-line characters in any header data that is 596 returned will be converted to a space character. 598 2.7.1. Responses 600 224 Overview information follows 601 412 No news group current selected 602 420 No article(s) selected 603 502 no permission 605 2.8. XPAT 607 XPAT header range| pat [pat...] 609 The XPAT command is used to retrieve specific headers from specific 610 articles, based on pattern matching on the contents of the header. This 611 command was first available in INN. 613 The required header parameter is the name of a header line (e.g. "sub- 614 ject") in a news group article. See RFC-1036 for a list of valid header 615 lines. The required range argument may be any of the following: 617 an article number 618 an article number followed by a dash to indicate all following 619 an article number followed by a dash followed by another article 620 number 622 The required message-id argument indicates a specific article. The range 623 and message-id arguments are mutually exclusive. At least one pattern in 624 wildmat must be specified as well. If there are additional arguments the 625 are joined together separated by a single space to form one complete 626 pattern. Successful responses start with a 221 response followed by a 627 the headers from all messages in which the pattern matched the contents 628 of the specified header line. This includes an empty list. Once the out- 629 put is complete, a period is sent on a line by itself. If the optional 630 argument is a message-id and no such article exists, the 430 error 631 response is returned. A 502 response will be returned if the client only 632 has permission to transfer articles. 634 2.8.1. Responses 636 221 Header follows 637 430 no such article 638 502 no permission 640 2.9. The XPATH command 642 XPATH 644 The XPATH command is used to determine the filenames in which an article 645 is filed. It first appeared in INN. 647 The required parameter message-id is the message id of an article as 648 shown in that article's message-id header. According to RFC 1036[3], all 649 message ids for all articles within the netnews environment are unique, 650 but articles may be crossposted to multiple groups. The response to an 651 XPATH command will include a listing of all filenames in which an arti- 652 cle is stored separated by spaces or a response indicating that no arti- 653 cle with the specified message-id exists. The returned data is only use- 654 ful if the news client knows the implementation details of the server. 655 Because of this, it is recommended that client avoid using this command. 657 2.9.1. Responses 659 223 path1[ path2 ...] 660 430 no such article on server 662 2.10. The XROVER command 664 XROVER [range] 666 The XROVER command returns reference information from the overview 667 database for the article(s) specified. This command first appeared in 668 the Unix reference implementation. 670 The optional range argument may be any of the following: 672 an article number 673 an article number followed by a dash to indicate all following 674 an article number followed by a dash followed by another article 675 number 677 Successful responses start with a 224 response followed by the contents 678 of reference information for all matched messages. Once the output is 679 complete, a period is sent on a line by itself. If no argument is speci- 680 fied, the information for the current article is returned. A news group 681 must have been selected earlier, else a 412 error response is returned. 682 If no articles are in the range specified, a 420 error response is 683 returned by the server. A 502 response will be returned if the client 684 only has permission to transfer articles. 686 The output will be formatted with the article number, followed by the 687 contents of the References: line for that article, but does not contain 688 the field name itself. 690 This command provides the same basic functionality as using the XHDR 691 command and "references" as the header argument. 693 2.10.1. Responses 695 224 Overview information follows 696 412 No news group current selected 697 420 No article(s) selected 698 502 no permission 700 2.11. XTHREAD 702 XTHREAD [DBINIT|THREAD] 704 The XTHREAD command is used to retrieve threading information in format 705 of originally created for use by the TRN[7] news reader. 707 The command XTHREAD DBINIT may be issued prior to entering any groups to 708 see if a thread database exists. If it does, the database's byte order 709 and version number are returned as binary data. 711 If no parameter is given, XTHREAD THREAD is assumed. 713 To use XTHREAD THREAD, a news group must have been selected earlier, 714 else a 412 error response is returned. 716 A 502 response will be returned if the client only has permission to 717 transfer articles. A 503 response is returned if the threading files are 718 not available. 720 The format of the trn-style thread format is discussed in the documenta- 721 tion for the TRN newsreader. Since more recent versions of TRN support 722 the news overview (NOV) format, it is recommended that this extension 723 become historic and no longer be used in current servers or future 724 implementations. 726 2.11.1. Responses 728 288 Binary data to follow 729 412 No newsgroup current selected 730 502 No permission 731 503 program error, function not performed 733 3. Other Extensions 735 3.1. AUTHINFO 737 AUTHINFO is used to inform a server about the identity of a user of the 738 server. In all cases, clients must provide this information when 739 requested by the server. Servers are not required to accept authentica- 740 tion information that is volunteered by the client. Clients must accom- 741 modate servers that reject any authentication information volunteered by 742 the client. 744 There are three forms of AUTHINFO in use. The original version, an NNTP 745 v2 revision called AUTHINFO SIMPLE and a more recent version which is 746 called AUTHINFO GENERIC. 748 3.1.1. Original AUTHINFO 750 AUTHINFO USER username 751 AUTHINFO PASS password 753 The original AUTHINFO is used to identify a specific entity to the 754 server using a simple username/password combination. It first appeared 755 in the UNIX reference implementation. 757 When authorization is required, the server will send a 480 response 758 requesting authorization from the client. The client must enter AUTHINFO 759 USER followed by the username. Once sent, the server will cache the 760 username and may send a 381 response requesting the password associated 761 with that username. Should the server request a password using the 381 762 respose, the client must enter AUTHINFO PASS followed by a password and 763 the server will then check the authentication database to see if the 764 username/password combination is valid. If the combination is valid or 765 if no password is required, the server will return a 281 response. The 766 client should then retry the original command to which the server 767 responded with the 480 response. The command should then be processed by 768 the server normally. If the combination is not valid, the server will 769 return a 502 response. 771 Clients must provide authentication when requested by the server. It is 772 possible that some implementations will accept authentication informa- 773 tion at the beginning of a session, but this was not the original intent 774 of the specification. If a client attempts to reauthenticate, the server 775 may return 482 response indicating that the new authentication data is 776 rejected by the server. The 482 code will also be returned when the 777 AUTHINFO commands are not entered in the correct sequence (like two 778 AUTHINFO USERs in a row, or AUTHINFO PASS preceding AUTHINFO USER). 780 All information is passed in cleartext. 782 When authentication succeeds, the server will create an email address 783 for the client from the user name supplied in the AUTHINFO USER command 784 and the hostname generated by a reverse lookup on the IP address of the 785 client. If the reverse lookup fails, the IP address, represented in dot- 786 ted-quad format, will be used. Once authenticated, the server shall gen- 787 erate a Sender: line using the email address provided by authentication 788 if it does not match the client-supplied From: line. Additionally, the 789 server should log the event, including the email address This will pro- 790 vide a means by which subsequent statistics generation can associate 791 newsgroup references with unique entities - not necessarily by name. 793 3.1.1.1. Responses 795 281 Authentication accepted 796 381 More authentication information required 797 480 Authentication required 798 482 Authentication rejected 799 502 No permission 801 3.1.2. AUTHINFO SIMPLE 803 AUTHINFO SIMPLE 804 user password 805 This version of AUTHINFO was part of a proposed NNTP V2 specification, 806 which was started in 1991 but never completed, and is implemented in 807 some servers and clients. It is a refinement of the original AUTHINFO 808 and provides the same basic functionality, but the sequence of commands 809 is much simpler. 811 When authorization is required, the server sends a 450 response request- 812 ing authorization from the client. The client must enter AUTHINFO SIM- 813 PLE. If the server will accept this form of authentication, the server 814 responds with a 350 response. The client must then send the username 815 followed by one or more space characters followed by the password. If 816 accepted, the server returns a 250 response and the client should then 817 retry the original command to which the server responded with the 450 818 response. The command should then be processed by the server normally. 819 If the combination is not valid, the server will return a 452 response. 821 Note that the response codes used here were part of the proposed NNTP V2 822 specification and are violations of RFC 977. It is recommended that 823 this command not be implemented, but use either or both of the other 824 forms of AUTHINFO if such functionality if required. 826 3.1.2.1. Responses 828 250 Authorization accepted 829 350 Continue with authorization sequence 830 450 Authorization required for this command 831 452 Authorization rejected 833 3.1.3. AUTHINFO GENERIC 835 AUTHINFO GENERIC authenticator arguments... 837 AUTHINFO GENERIC is used to identify a specific entity to the server 838 using arbitrary authentication or identification protocols. The desired 839 protocol is indicated by the authenticator parameter, and any number of 840 parameters can be passed to the authenticator. 842 When authorization is required, the server will send a 480 response 843 requesting authorization from the client. The client should enter 844 AUTHINFO GENERIC followed by the authenticator name, and the arguments 845 if any. The authenticator and arguments must not contain the sequence 846 "..". 848 The server will attempt to engage the server end authenticator, simi- 849 larly, the client should engage the client end authenticator. The 850 server end authenticator will then initiate authentication using the 851 NNTP sockets (if appropriate for that authentication protocol), using 852 the protocol specified by the authenticator name. These authentication 853 protocols are not included in this document, but are similar in struc- 854 ture to those referenced in RFC 1731[8] for the IMAP-4 protocol. 856 If the server returns 501, this means that the authenticator invocation 857 was syntactically incorrect, or that AUTHINFO GENERIC is not supported. 858 The client should retry using the AUTHINFO USER command. 860 If the requested authenticator capability is not found, the server 861 returns the 503 response code. 863 If there is some other unspecified server program error, the server 864 returns the 500 response code. 866 The authenticators converse using their protocol until complete. If the 867 authentication succeeds, the server authenticator will terminate with a 868 281, and the client can continue by reissuing the command that prompted 869 the 380. If the authentication fails, the server will respond with a 870 502. 872 The client must provide authentication when requested by the server. 873 The server may request authentication at any time. Servers may request 874 authentication more than once during a single session. 876 When the server authenticator completes, it provides to the server (by a 877 mechanism herein undefined) the email address of the user, and poten- 878 tially what the user is allowed to access. Once authenticated, the 879 server shall generate a Sender: line using the email address provided by 880 the authenticator if it does not match the user-supplied From: line. 881 Additionally, the server should log the event, including the user's 882 authenticated email address (if available). This will provide a means by 883 which subsequent statistics generation can associate newsgroup refer- 884 ences with unique entities - not necessarily by name. 886 Some implementations make it possible to obtain a list of authentication 887 procedures available by sending the server AUTHINFO GENERIC with no 888 arguments. The server then returns a list of supported mechanisms fol- 889 lowed by a period on a line by itself. 891 3.1.3.1. Responses 893 281 Authentication succeeded 894 480 Authentication required 895 500 Command not understood 896 501 Command not supported 897 502 No permission 898 503 Program error, function not performed 899 nnn authenticator-specific protocol. 901 3.2. DATE 903 DATE 905 The first NNTP working group discussed and proposed a syntax for this 906 command to help clients find out the current time from the server's per- 907 spective. At the time this command was discussed (1991-1992), the Net- 908 work Time Protocol [9] (NTP) was not yet in wide use and there was also 909 some concern that small systems may not be able to make effective use of 910 NTP. 912 This command returns a one-line response code of 111 followed by the 913 GMT date and time on the server in the form YYYYMMDDhhmmss. 915 3.2.1. Responses 917 111 YYYYMMDDhhmmss 919 3.3. The WILDMAT Format 921 The WILDMAT format was first developed by Rich Salz based on the format 922 used in the UNIX "find" command to articulate file names. It was devel- 923 oped to provide a uniform mechanism for matching patterns in the same 924 manner that the UNIX shell matches filenames. Patterns are implicitly 925 anchored at the beginning and end of each string when testing for a 926 match. There are five pattern matching operations other than a strict 927 one-to-one match between the pattern and the source to be checked for a 928 match. The first is an asterisk (*) to match any sequence of zero or 929 more characters. The second is a question mark (?) to match any single 930 character. The third specifies a specific set of characters. The set is 931 specified as a list of characters, or as a range of characters where the 932 beginning and end of the range are separated by a minus (or dash) char- 933 acter, or as any combination of lists and ranges. The dash can also be 934 included in the set as a character it if is the beginning or end of the 935 set. This set is enclosed in square brackets. The close square bracket 936 (]) may be used in a set if it is the first character in the set. The 937 fourth operation is the same as the logical not of the third operation 938 and is specified the same way as the third with the addition of a caret 939 character (^) at the beginning of the test string just inside the open 940 square bracket. The final operation uses the backslash character to 941 invalidate the special meaning of the a open square bracket ([), the 942 asterisk, backslash or the question mark. Two backslashes in sequence 943 will result in the evaluation of the backslash as a character with no 944 special meaning. 946 3.3.1. Examples 948 a. [^]-] -- matches any single character other than a close square 949 bracket or a minus sign/dash. 951 b. *bdc -- matches any string that ends with the string "bdc" 952 including the string "bdc" (without quotes). 954 c. [0-9a-zA-Z] -- matches any single printable alphanumeric ASCII 955 character. 957 d. a??d -- matches any four character string which begins 958 with a and ends with d. 960 3.4. Additional Headers 962 Many NNTP implementations add headers to Usenet articles when then are 963 POSTed via NNTP. These headers are discussed in this section. None of 964 these headers conflict with those specified in RFC 1036 and should be 965 passed unchanged by Usenet transports conforming to RFC 1036. 967 3.4.1. NNTP-Posting-Host 969 This line is added to the header of a posted article by the server. The 970 contents of the header is either the IP address or the fully qualified 971 domain name of the client host posting the article. The fully qualified 972 domain name should be determined by doing a reverse lookup in the DNS on 973 the IP address of the client. If the client article contains this line, 974 it is removed by the server before acceptance of the article by the 975 Usenet transport system. 977 This header provides some idea of the actual host posting the article as 978 opposed to information in the Sender or From lines that may be present 979 in the article. This is not a fool-proof methodology since reverse 980 lookups in the DNS are vulnerable to certain types of spoofing, but such 981 discussions are outside the scope of this document. 983 3.4.2. X-Newsreader and others 985 There are other lines that are added by clients as well. Most of these 986 indicate the type of newsreader software that is posting the article. 988 4. Common Implementation Issues 990 Many NNTP implementations do not follow the specifications in RFC 977. 991 In this section, some common implementation issues are summarized. 993 4.1. The Response to the LIST command 995 RFC 977 says that the fourth field of the "list of valid newsgroups 996 associated information" returned must be "either 'y' or 'n' indicating 997 whether posting to this newsgroup is allowed ('y') or prohibited ('n'). 998 Most implementations simply output the exact contents of the transport 999 system's active newsgroup list. For more implementations, the fourth 1000 field usually has more values that 'y' or 'n'. 1002 4.2. The Required Headers in an Article and the POST command 1004 RFC 977 notes in section 3.10.1 that articles presented "should include 1005 all required header lines." In fact, modern implementations only require 1006 From, Subject, and Newsgroups header lines and will supply the rest; 1007 further, many implementers believe that it is best for clients to gener- 1008 ate as few headers as possible, since clients often do not format other 1009 headers correctly. 1011 This implementation behavior is consistent with both Bnews and Cnews 1012 which would supply missing headers for articles directly submitted to 1013 them. 1015 4.3. Article Numbering 1017 RFC977 does not directly address the rules concerning articles number, 1018 but the current practice is simple. New articles have monotonically 1019 increasing numbers within a group, and articles may disappear or be 1020 reinstated at any time (and thus between any two commands). The low 1021 water mark returned in a GROUP command is an absolute minimum (though 1022 that article might not exist), but there could be articles above the 1023 high water mark (that have appeared since the GROUP command was issued), 1024 and so it should be treated as advisory only. Similarly, the results of 1025 sequences of NEXT and LAST commands might not be consistent. 1027 4.4. Availability of commands defined in RFC977 1029 Some implementations permit administrators to disable commands defined 1030 RFC977. Some implementations have some set of commands disabled by 1031 default. This means that client implementations cannot depend on the 1032 availability of the disabled set of commands. This increases the com- 1033 plexity of the client and does not encourage implementors to optimize 1034 the implementation of commands that don't perform well. 1036 NEWNEWS is one of the commands frequently disabled by news server man- 1037 agers. 1039 4.5. The Distribution header and NEWNEWS 1041 In section 12.4 of RFC977, the optional distributions argument is 1042 described. This argument, according to RFC977, would limit the responses 1043 to articles that were in newsgroups with prefixes that matched the 1044 optional distributions argument. 1046 Some implementations implement this by matching the Distributions header 1047 in articles to the distribution argument. Others do the match against 1048 segments of the newsgroup's name. 1050 This variation is probably best explained by the evolution of the USENET 1051 article format. At the time RFC977 was specified, the newsgroup name 1052 defined how the group was distributed thoughout USENET. RFC1036 changed 1053 this convention. So, those that are strictly implementing RFC977 would 1054 match the newsgroup name prefix against the distribution arguement and 1055 only display matches. Those that implement against the intent of the 1056 command (as modified by the redefinition of the article format)would 1057 match the Distributions header against the distribution argument and 1058 only display those matches. 1060 5. Further Work 1062 With the continued use of NNTP on the Internet, there remains an inter- 1063 est in creating an optimized transport protocol for server-to-server 1064 transfers and an optimized client protocol for client-to-server interac- 1065 tions. There is also considerable interest is building better mechanisms 1066 to provide audit information on which news groups are being read by 1067 which users. 1069 An IETF working group has been formed and it is the hope of this author 1070 that these issues will be addressed in that forum. 1072 6. Security Considerations 1074 The use of the AUTHINFO is optional. This command as documented has a 1075 number of security implications. In the original and simple forms, all 1076 passwords are passed in plaintext and could be discovered by various 1077 forms of network or system surveillance. The AUTHINFO GENERIC command 1078 has the potential for the same problems if a mechanism is used that also 1079 passes cleartext passwords. RFC 1731[8] discusses these issues in 1080 greater detail. 1082 7. References 1084 [1] Kantor, B and P. Lapsley, "Network News Transfer Protocol", 1085 RFC-977, U.C. San Diego and U.C. Berkeley, February, 1986. 1087 [2] Limoncelli, Tom, "Read This Before You Write a Newsreader", 1088 http://mars.superlink.net/tal/writings/news-software-authors.html, 1089 May, 1995. 1091 [3] Horton, M.R. and R. Adams, "Standard for interchange of USENET mes- 1092 sages", RFC-1036, AT&T Bell Laboratories and Center for Seismic 1093 Studies, December, 1987. 1095 [4] Salz, Rich, Manual Page for wildmat(3) from the INN 1.4 distribu- 1096 tion, UUNET Technologies, Revision 1.10, April, 1992. 1098 [5] Robertson, Rob, "FAQ: Overview database / NOV General Information", 1099 http://web.infoave.net/~anonymous/unix/FAQ-NOV, January, 1995. 1101 [6] Lea, Iain, "FAQ about the TIN newsreader", http://nimbus.tem- 1102 ple.edu/pds/tinfaq.html, May 1995. [More recent info about TIN is 1103 at http://www.tin.org.] 1105 [7] Kappesser, Peter, "[news.software.readers] trn newsreader FAQ", 2 1106 parts, http://www.faqs.org/faqs/usenet/software/trn- 1107 faq/part1/index.html and http://www.faqs.org/faqs/usenet/soft- 1108 ware/trn-faq/part2/index.html February, 1995. 1110 [8] Meyers, J, "IMAP4 Authentication Mechanisms", RFC-1731, Carnegie 1111 Mellon, December, 1994. 1113 [9] Mills, David L., "Network Time Protocol (Version 3), Specification, 1114 Implementation and Analysis", RFC-1305, University of Delaware, 1115 March 1992. 1117 8. Notes 1119 DEC is a registered trademark of Compaq Computer Corporation. 1120 UNIX is a registered trademark of the Open Group. 1121 VMS is a registered trademark of Compaq Computer Corporation. 1123 9. Acknowledgments 1125 The author gratefully acknowledges the comments and additional informa- 1126 tion provided by the following individuals: 1128 Wayne Davison 1129 Clive D.W. Feather 1130 Chris Lewis 1131 Tom Limoncelli 1132 Eric Schnoebelen 1133 Rich Salz 1135 This work was precipitated by the work of various newsreader authors and 1136 newsserver authors which includes those listed below: 1138 Rick Adams -- Original author of the NNTP extensions to the RN 1139 newsreader and last maintainer of Bnews 1140 Stan Barber -- Original author of the NNTP extensions to the 1141 newsreaders that are part of Bnews. 1142 Geoff Collyer -- Original author of the OVERVIEW database proposal 1143 and one of the original authors of CNEWS 1144 Dan Curry -- Original author of the xvnews newsreader 1145 Wayne Davison -- Author of the first threading extensions to the RN 1146 newsreader (commonly called TRN). 1147 Geoff Huston -- Original author of ANU NEWS 1148 Phil Lapsey -- Original author of the UNIX reference implementa- 1149 tion of NNTP 1150 Iain Lea -- Original author of the TIN newsreader 1151 Chris Lewis -- First known implementor of the AUTHINFO GENERIC 1152 extension 1153 Rich Salz -- Original author of INN 1154 Henry Spencer -- One of the original authors of CNEWS 1155 Kim Storm -- Original author of the NN newsreader 1157 10. Author's Address 1159 Stan Barber 1160 P.O. Box 300481 1161 Houston, Texas, 77230 1162 Email: 1164 This document expires January 7, 1999 1166 11. Copyright Statement 1168 Copyright (C) The Internet Society (1998). All Rights Reserved. 1170 This document and translations of it may be copied and furnished to oth- 1171 ers, and derivative works that comment on or otherwise explain it or 1172 assist in its implmentation may be prepared, copied, published and dis- 1173 tributed, in whole or in part, without restriction of any kind, provided 1174 that the above copyright notice and this paragraph are included on all 1175 such copies and derivative works. However, this document itself may not 1176 be modified in any way, such as by removing the copyright notice or ref- 1177 erences to the Internet Society or other Internet organizations, except 1178 as needed for the purpose of developing Internet standards in which case 1179 the procedures for copyrights defined in the Internet Standards process 1180 must be followed, or as required to translate it into languages other 1181 than English. 1183 The limited permissions granted above are perpetual and will not be 1184 revoked by the Internet Society or its successors or assigns. 1186 This document and the information contained herein is provided on an "AS 1187 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 1188 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 1189 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 1190 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT- 1191 NESS FOR A PARTICULAR PURPOSE.