idnits 2.17.1 draft-ietf-nntpext-base-07.txt: ** The Abstract section seems to be numbered 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. Expected boilerplate is as follows today (2024-04-24) 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 document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** 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 -- however, there's a paragraph with a matching beginning. Boilerplate error? ** 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 35 longer pages, the longest (page 36) being 67 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. (A line matching the expected section header was found, but with an unexpected indentation: ' 2. Abstract' ) ** The document seems to lack a Security Considerations section. (A line matching the expected section header was found, but with an unexpected indentation: ' 14. Security Considerations' ) ** 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 an Authors' Addresses Section. ** There are 351 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** The abstract seems to contain references ([2], [3], [4], [0-9a-zA-Z], [5], [6], [C], [7], [8], [9], [GMT], [S], [XX], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- -- 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 (December 1998) is 9262 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) -- Missing reference section? '1' on line 1745 looks like a reference -- Missing reference section? '2' on line 1748 looks like a reference -- Missing reference section? '3' on line 1751 looks like a reference -- Missing reference section? '4' on line 1754 looks like a reference -- Missing reference section? '5' on line 1757 looks like a reference -- Missing reference section? '0-9a-zA-Z' on line 301 looks like a reference -- Missing reference section? 'GMT' on line 1503 looks like a reference -- Missing reference section? '6' on line 1760 looks like a reference -- Missing reference section? 'C' on line 453 looks like a reference -- Missing reference section? 'S' on line 463 looks like a reference -- Missing reference section? '7' on line 1764 looks like a reference -- Missing reference section? '8' on line 1768 looks like a reference -- Missing reference section? '9' on line 1772 looks like a reference Summary: 15 errors (**), 0 flaws (~~), 3 warnings (==), 15 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET DRAFT S. Barber 3 Expires: June 7, 1999 Academ Consulting Services 4 December 1998 6 Network News Transport Protocol 8 draft-ietf-nntpext-base-07.txt 10 1. Status of this Document 12 This document is an Internet-Draft. Internet-Drafts are 13 working documents of the Internet Engineering Task Force 14 (IETF), its areas, and its working groups. Note that other 15 groups may also distribute working documents as Internet- 16 Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or made obsolete by other 20 documents at any time. It is inappropriate to use Internet- 21 Drafts as reference material or to cite them other than as 22 "work in progress." 24 To learn the current status of any Internet-Draft, please 25 check the "1id-abstracts.txt" listing contained in the 26 Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), 27 nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), 28 ftp.ietf.org (US East Coast), or ftp.isi.edu (US West 29 Coast). 31 This document is a product of the NNTP Working Group, chaired 32 by Ned Freed and Stan Barber. 34 2. Abstract 35 The Network News Transport Protocol has been in use in the 36 Internet for a decade and remains one of the most popular 37 protocols (by volume) in use today. This document is a 38 replacement for RFC 977 and officially updates the protocol 39 specification. It clarifies some vagueness in RFC 977, 40 includes some new base functionality and provides a specific 41 mechanism to add standardized extensions to NNTP. 43 3. Introduction 44 This document specifies the Network News Transport Protocol 45 (NNTP), which is used for the distribution, inquiry, 46 retrieval, and posting of net news articles using a reliable 47 stream-based mechanism. For news reading clients, NNTP enables 48 retrieval of news articles that are stored in a central 49 database, giving subscribers the ability to select only those 50 articles they wish to read. 52 The netnews model provides for indexing, cross-referencing, 53 and expiration of aged messages. For server-to-server 54 interaction, NNTP is designed for efficient transmission of 55 net news articles over a reliable full duplex communication 56 method. 58 Every attempt is made to insure that the protocol 59 specification in this document is compatible with the version 60 specified in RFC 977[1]. However, this version does not 61 support the ill-defined SLAVE command and permits four digit 62 years to be specified in the NEWNEWS and NEWGROUPS commands. 63 It changes the default character set to UTF-8[2] instead of 64 US-ASCII[3]. It also extends the newsgroup name matching 65 capabilities already documented in RFC 977. 67 Generally, new functionality is available using new keywords. 68 Part of that new functionality involves a mechanism to 69 discover what new functionality is available to clients from a 70 server. 72 This mechanism can also be used to add more functionality as 73 needs merit such additions. 75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 76 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 77 "OPTIONAL" in this document are to be interpreted as described 78 in RFC 2119[4]. 80 An implementation is not compliant if it fails to satisfy one 81 or more of the MUST requirements for this protocol. An 82 implementation that satisfies all the MUST and all the SHOULD 83 requirements for its protocols is said to be "unconditionally 84 compliant"; one that satisfies all the MUST requirements but 85 not all the SHOULD requirements for NNTP is said to be 86 "conditionally compliant". 88 For the remainder of this memo, the term "client host" refers 89 to a host making use of the NNTP service, while the term 90 "server host" refers to a host that offers the NNTP service. 91 In addition, where examples of interactions between a client 92 host and a server host are provided a "[C]" will be used to 93 represent the client host and a "[S]" will be used to 94 represent the server host. 96 4. Basic Operation. 98 Every NNTP session MUST involve the following in this order: 100 CONNECTION 101 GREETING 102 DISCONNECTION 104 Other steps may occur between the GREETING and DISCONNECTION 105 step. They are: 107 CAPABILITIES DISCOVERY 108 NEWS EXCHANGE 109 CONCLUSION 111 NNTP operates over any reliable data stream 8-bit-wide 112 channel. When running over TCP/IP, the official port for the 113 NNTP service is 119. Initially, the server host starts the 114 NNTP service by listening on a TCP port. When a client host 115 wishes to make use of the service, it MUST establish a TCP 116 connection with the server host by connecting to that host on 117 the same port on which the server is listening. This is the 118 CONNECTION step. When the connection is established, the NNTP 119 server host MUST send a greeting. This is the GREETING step. 120 The client host and server host SHOULD then exchange commands 121 and responses (respectively) until the connection is closed or 122 aborted. This final step is called the DISCONNECTION step. 124 If there is a CONCLUSION step, it MUST immediately precede the 125 DISCONNECTION step. There MUST be only one CONNECTION, 126 CONCLUSION and DISCONNECTION step for each NNTP session. All 127 other steps MAY be repeated as needed. 129 The character set for all NNTP commands is UTF-8. Commands in 130 the NNTP MUST consist of an US-ASCII case-insensitive keyword, 131 which MAY be followed by one or more arguments. An US-ASCII 132 CRLF pair MUST terminate all commands. Multiple commands MUST 133 NOT be on the same line. Keywords MUST consist of printable 134 US-ASCII characters. Unless otherwise noted elsewhere in this 135 document, arguments SHOULD consist of printable US-ASCII 136 characters. Keywords and arguments MUST be each separated by 137 one or more US-ASCII SPACE or US-ASCII TAB characters. 138 Keywords MUST be at least three US-ASCII characters and MUST 139 NOT exceed 12 US-ASCII characters. Command lines MUST NOT 140 exceed 512 octets, which includes the terminating US-ASCII 141 CRLF pair. Arguments MUST NOT exceed 497 octets. 143 Each response MUST start with a three-digit response code that 144 is sufficient to distinguish all responses. Unless 145 specifically specified as one of the valid responses for a 146 command (such as those described later in this document), each 147 response is contained in a single line. However, certain 148 commands MAY permit multi-line responses. All multi-line 149 responses MUST adhear to the following format: After sending 150 the first line of the response and an US-ASCII CRLF, any 151 additional lines are sent, each terminated by an US-ASCII CRLF 152 pair. When all lines of the response have been sent, a final 153 line MUST be sent, consisting of a termination octet (US-ASCII 154 decimal code 046, ".") and an US-ASCII CRLF pair. If any line 155 of the multi-line response begins with the termination octet, 156 the line MUST be "byte-stuffed" by pre-pending the termination 157 octet to that line of the response. Hence, a multi-line 158 response is terminated with the five octets "CRLF.CRLF" (in 159 US-ASCII). When examining a multi-line response, the client 160 MUST check to see if the line begins with the termination 161 octet. If so and if octets other than US-ASCII CRLF follow, 162 the first octet of the line (the termination octet) MUST be 163 stripped away. If so and if US-ASCII CRLF immediately follows 164 the termination character, then the response from the NNTP 165 server is ended and the line containing ".CRLF" (in US-ASCII) 166 MUST NOT considered part of the multi-line response. The 167 keywords that support multi-line responses have the format of 168 those responses described in the responses section. 170 A NNTP server MAY have an inactivity autologout timer. Such a 171 timer MUST be of at least three minutes duration. The receipt 172 of any command from the client during that interval should 173 suffice to reset the autologout timer. When the timer 174 expires, the server should close the TCP connection without 175 sending any response to the client. 177 4.1 Response Codes 179 Each response MUST begin with a three-digit status indicator. 180 These are status reports from the server and indicate the 181 response to the last command received from the client. 183 The first digit of the response broadly indicates the success, 184 failure, or progress of the previous command. 186 1xx - Informative message 187 2xx - Command ok 188 3xx - Command ok so far, send the rest of it. 189 4xx - Command was correct, but couldn't be performed for some 190 reason. 191 5xx - Command unimplemented, or incorrect, or a serious 192 program error occurred. 193 The next digit in the code indicates the function response 194 category. 196 x0x - Connection, setup, and miscellaneous messages 197 x1x - Newsgroup selection 198 x2x - Article selection 199 x3x - Distribution functions 200 x4x - Posting 201 x8x - Nonstandard (private implementation) extensions 202 x9x - Debugging output 204 The exact response codes that can be returned in response to a 205 given command are detailed in the description of the keyword 206 that is the first part of the command. In addition, below is 207 listed a general set of response codes that MAY be received at 208 any time. 210 Certain response codes contain parameters such as numbers and 211 names in addition to the status indicator. In those cases, the 212 number and type of such parameters MUST be fixed for each 213 response code to simplify interpretation of the response. In 214 all other cases, the client MUST only use the status indicator 215 itself to determine the nature of the response. 217 Parameters MUST be separated from the numeric status indicator 218 and from each other by a single US-ASCII space. All numeric 219 parameters MUST be in base 10 (decimal) format, and may have 220 leading zeros. All string parameters MUST begin after the 221 separating space, and MUST end before the following separating 222 space or the US-ASCII CRLF pair at the end of the line. 223 (Therefore, string parameters MUST NOT contain US-ASCII 224 spaces.) All text, if any, in the response which is not a 225 parameter of the response must follow and be separated from 226 the last parameter by an US-ASCII space. Also, note that the 227 text following a response number may vary in different 228 implementations of the server. The 3-digit numeric status 229 indicator should be used to determine what response was sent. 231 Response codes not specified in this standard MAY be used for 232 any installation-specific additional commands also not 233 specified. These SHOULD be chosen to fit the pattern of x8x 234 specified above. (Note that debugging is provided for 235 explicitly in the x9x response codes.) 237 The use of unspecified response codes for a standard command 238 is prohibited. 240 The status indicator pattern x9x is provided for debugging. 241 Since much debugging output may be classed as "informative 242 messages", it MUST be the case that responses 190 through 199 243 WILL be used for various debugging outputs. There is no 244 requirement in this specification for debugging output. 245 However, if such is provided over the connected stream, it 246 MUST use these response codes. If appropriate to a specific 247 implementation, other x9x codes MAY be used for debugging. 248 (For example, response code 290 could be used to acknowledge a 249 remote debugging request.) 251 A server MUST respond to an unrecognized, unimplemented, or 252 syntactically invalid command with a negative response 253 code(status indicators of the form 5XX). A server MUST 254 respond to a command issued when the session is in an 255 incorrect state by responding with a negative status 256 indicator. This may be from either the 4XX or 5XX group as 257 appropriate. 259 5. The WILDMAT format 261 The WILDMAT format[5] described here is based on the version 262 first developed by Rich Salz which was derived from the format 263 used in the UNIX "find" command to articulate file names. It 264 was developed to provide a uniform mechanism for matching 265 patterns in the same manner that the UNIX shell matches 266 filenames. Patterns are implicitly anchored at the beginning 267 and end of each string when testing for a match. There are 268 six pattern-matching operations other than a strict one-to-one 269 match between the pattern and the source to be checked for a 270 match. The first is an asterisk (*) to match any sequence of 271 zero or more UTF-8 characters. The second is a question mark 272 (?) to match any single UTF-8 character. The third specifies a 273 specific set of characters. The set is specified as a list of 274 characters, or as a range of characters where the beginning 275 and end of the range are separated by a minus (or dash) 276 character, or as any combination of lists and ranges. The dash 277 can also be included in the set as a character it if is the 278 beginning or end of the set. This set is enclosed in square 279 brackets. The close square bracket (]) may be used in a set if 280 it is the first character in the set. The fourth operation is 281 the same as the logical not of the third operation and is 282 specified the same way as the third with the addition of a 283 caret character (^) at the beginning of the test string just 284 inside the open square bracket. The fifth operation uses the 285 exclamation mark (!) preceding any valid expression built 286 using any of the operators discussed prior to this sentence. 287 The final operation uses the backslash character to invalidate 288 the special meaning of the open square bracket ([), the 289 asterisk, backslash, exclamation mark or the question mark. 290 The meaning of the backslash operator cannot be negated by the 291 exclamation point. Two backslashes in sequence will result in 292 the evaluation of the backslash as a character with no special 293 meaning. 295 5.1 Examples 297 a) [^]-] -- matches any single character other than a 298 close square bracket or a minus sign/dash. 299 b) *bdc -- matches any string that ends with the string 300 "bdc" including the string "bdc" (without quotes). 301 c) [0-9a-zA-Z] -- matches any single printable 302 alphanumeric ASCII character. 303 d) a??d -- matches any four character string which 304 begins with a and ends with d. 306 6. Format for Keyword Descriptions 307 On the following pages are descriptions of each keyword 308 recognized by the NNTP server and the responses that will be 309 returned by those commands. These keywords are grouped by the 310 functional step in which they are used. 312 Each keyword is shown in upper case for clarity, although the 313 NNTP server ignores case in the interpretation of commands. 314 Any parameters are shown in lower case. A parameter shown in 315 [square brackets] is optional. For example, [GMT] indicates 316 that the triglyph GMT may be present or omitted. A parameter 317 that may be repeated is followed by an ellipsis. Mutually 318 exclusive parameters are separated by a vertical bar (|) 319 character. For example, ggg| indicates that a 320 group name or a may be specified, but not both. 321 Some parameters may be case or language specific. See RFC 322 1036[6] for these details. 324 In addition, certain commands make use of a pattern for 325 selection of multiple news groups. The pattern in all cases is 326 based on the WILDMAT format. Arguments expected to be in 327 wildmat format will be represented by the string wildmat. This 328 format is discussed in detail in section 5 of this memo. 330 7. The GREETING Step 332 7.1 Initial Connection 334 There is no keyword presented by the client upon initial 335 connection to the server. The server MUST present an 336 appropriate response code as a greeting to the client. This 337 response informs the client about what steps the client should 338 take to reach the news exchange step. 340 The server MUST present a 200 greeting code if the client is 341 authorized to post articles though the use of the POST keyword 342 on this server. 344 The server MUST present a 201 greeting code if the client is 345 not authorized to post articles using the POST keyword. 347 The server MUST present a 502 greeting code if the client is 348 not permitted under any circumstances to interact with the 349 server. The server should immediately close the connection 350 with the client after presenting this code. 352 In all other cases, the server MUST present a 400 greeting 353 code. 355 7.1.1 MODE READER 357 MODE READER 359 MODE READER MAY be used by the client to indicate to the 360 server that it is a news reading client. This command may be 361 entered at any time. The server must present a greeting code 362 (as described in section 7.1.1.1) appropriate to the server's 363 ability to provide service to this client in this mode. 365 7.1.1.1 Responses 366 200 Hello, you can post 367 201 Hello, you can't post 368 400 Service temporarily unavailable 369 502 Service unavailable 371 8. The CAPABILITIES DISCOVERY Step 373 A client NNTP supporting NNTP service extensions should query 374 a server early in the session for extensions session by 375 issuing the LIST EXTENSIONS command. If the NNTP server 376 supports the NNTP service extensions it MUST give a successful 377 response (see section 8.1.1), a failure response (see section 378 8.1.2), or an error response (see section 8.1.3). If the NNTP 379 server does not support any NNTP service extensions, it MUST 380 generate an error response (see section 8.1.4). 382 8.1 LIST EXTENSIONS 384 If successful, the server NNTP MUST respond with code 202. On 385 failure, the server NNTP MUST respond with code 503. On error, 386 the server NNTP MUST respond with one of codes 400, 402, 500, 387 501 and 502. 389 This command MAY be issued at anytime during a session. It is 390 not required that the client issues this command before 391 attempting to make use of any extension. The response 392 generated by this command MAY change during a session because 393 of other state information. However, a client NNTP MUST NOT 394 cache (for use in another session) any information returned if 395 the LIST EXTENSIONS command succeeds. That is, a client NNTP 396 is only able to get the current and correct information 397 concerning available extensions during a session by issuing a 398 LIST EXTENSIONS command during that session and processing 399 that response. 401 8.1.1 Successful response 403 If the server NNTP implements and is able to perform the LIST 404 EXTENSIONS command, it MUST return code 202. 406 Text following the return code on the first line of the reply 407 is free form, and not interpreted, and has no practical use, 408 as this text is not expected to be revealed to end users. The 409 syntax of other reply lines is precisely defined, and if 410 present, MUST be exactly as specified. 412 Each line listing an extension in the extension-listing begins 413 with a single space. That space IS NOT optional, nor does it 414 indicate general white space. This space guarantees that the 415 line can never be misinterpreted as the end of the extension- 416 listing, but is required even where there is no possibility of 417 ambiguity. 419 Each extension supported MUST be listed on a separate line to 420 facilitate the possible inclusion of parameters supported by 421 each extension command. The extension-label to be used in the 422 response to the LIST EXTENSIONS command will be specified as 423 each new extension is added to the NNTP command set. Often it 424 will be the name of a new command added; however this IS NOT 425 required. In fact, it IS NOT required that a new feature 426 actually add a new command or keyword. Any parameters 427 included are to be specified with the definition of the 428 command concerned. 430 That specification SHALL also specify how any parameters 431 present are to be interpreted and how each parameter is 432 seperated from other parameters. 434 The extension-label is nominally case sensitive, however the 435 definitions of specific labels and parameters specify the 436 precise interpretation, and it is to be expected that those 437 definitions will usually specify the label in a case 438 independent manner. Where this is done, implementations are 439 recommended to use US-ASCII upper case letters when 440 transmitting the extension response. 442 The LIST EXTENSIONS command itself is not included in the list 443 of features supported, support for the LIST EXTENSIONS command 444 is indicated by return of a reply other than a 500 or 502 445 reply. 447 The end of the list is defined by the usual period on a line 448 by itself. 450 A typical example reply to the LIST EXTENSIONS command might 451 be a multiline reply of the form: 453 [C] LIST EXTENSIONS 455 [S] 202 Extensions supported: 457 [S] OVER 459 [S] PAT 461 [S] LISTGROUP 463 [S] . 465 The particular extensions shown here are simply examples of 466 what may be defined in other places, no particular meaning 467 should be attributed to them. Recall also, that the extension 468 names returned are not command names, as such, but simply 469 indications that the server possesses some attribute or other. 471 The order in which the extensions are returned is of no 472 importance, NNTP server processes are not required to 473 implement any particular order, or even to consistently return 474 the same order when the command is repeated. 476 8.1.2 Failure response 478 If for some reason the server NNTP is unable to list the 479 service extensions it supports, it MUST return code 503. No 480 list (not even an empty one) will be returned. 482 In the case of a failure response, the client NNTP may try the 483 extensions either as the need arises or configure itself for 484 the basic NNTP functionality defined in this document. 486 8.1.3 Error responses from extended servers 488 If the server NNTP recognizes the LIST EXTENSIONS command, but 489 due to various conditions cannot make any extensions available 490 to the client at the time the client issued the LIST 491 EXTENSIONS command, it MUST return code 402. No list (not even 492 an empty one) will be returned. 494 The client NNTP should configure itself for the basic NNTP 495 functionality defined in this document, or issue commands that 496 might change the state of the server, or issue the QUIT 497 command (see section 10.1) if a particular extension is 498 required for the client to properly operate. 500 If the server NNTP determines that the NNTP service is no 501 longer available (e.g., due to imminent system shutdown), it 502 must return code 400. Note that this is response code should 503 not be generated due to an inactivity timeout as described in 504 section 4. 506 In the case of any error response outlined in this section, 507 the client NNTP should issue the QUIT command (see section 508 10.1). 510 8.1.4 Responses from servers without extensions 512 A server NNTP that conforms to this memo but does not support 513 the extensions specified here will not recognize the LIST 514 EXTENSIONS command and MUST consequently return code 500 or 515 code 501. The server NNTP SHALL stay in the same state after 516 returning this code. The client NNTP may try the extensions 517 either as the need arises or configure itself for the basic 518 NNTP functionality defined in this document. 520 8.1.5 Responses from improperly implemented servers 522 A server NNTP that improperly implements the LIST EXTENSIONS 523 command may return an empty list. Clients SHALL accommodate 524 this protocol violation and interpret it as a response code 525 402. 527 The client NNTP should configure itself for the basic NNTP 528 functionality defined in this document, or issue commands that 529 might change the state of the server, or issue the QUIT 530 command (see section 10.1) if a particular extension is 531 required for the client to properly operate. 533 9. The NEWS EXCHANGE Step 535 During this step, two basic types of transactions occur: 537 . article retrieval from the server 538 . article posting to the server 540 9.1 Article Retrieval 542 News reading clients have available a variety of mechanisms to 543 retrieve articles via NNTP. The news articles are stored and 544 indexed using three types of keys. One key is the message id 545 of an article. According to RFC 1036, this identifier should 546 be globally unique. Another key is composed of the news group 547 name and the article number within that news group. That key 548 MUST be unique to a particular server (there will be only one 549 article with that number within a particular news group), but 550 is not required to be globally unique. Additionally, because 551 the same article can be cross-posted to multiple news groups, 552 there may be multiple keys that point to the same article on 553 the same server. The final key is the arrival timestamp, 554 giving the time that the article arrived at the server. 556 The server MUST ensure that article numbers are issued in 557 order of arrival timestamp; that is, articles arriving later 558 MUST have higher numbers than those that arrive earlier. The 559 server SHOULD allocate the next sequential unused number to 560 each new article. 562 Article numbers MUST lie between 1 and 4,294,967,295 563 inclusive. The client and server SHOULD NOT use leading zeroes 564 in specifying article numbers, and MUST NOT use more than 16 565 digits. In some situations, the value zero replaces an article 566 number to show some special situation. One case involves 567 responses to the ARTICLE, STAT, BODY and HEAD commands where a 568 is specified as the argument. In those cases, the 569 "current article pointer" is not changed. 571 9.1.1 Article Retrieval by News Group Name and Article Number 573 The following commands are used to set the current news group 574 name and the "current article pointer" which is used by other 575 commands for article retrieval. 577 9.1.1.1 GROUP 579 GROUP ggg 581 The required parameter ggg is the name of the news group to be 582 selected (e.g. "news.software.b"). A list of valid news groups 583 may be obtained by using the LIST keyword. See section 9.4 584 for more information on the LIST keyword. 586 The successful selection response will return the article 587 numbers of the first and last articles in the group at the 588 moment of selection (these numbers are referred to as the 589 "reported low water mark" and the "reported high water mark"), 590 and an estimate of the number of articles on file in the 591 group. 593 If the group is not empty, the estimate MUST be at least the 594 actual number of articles available, and MUST be no greater 595 than one more than the difference between the reported low and 596 high water marks. (Some implementations will actually count 597 the number of articles on file. Others will just subtract the 598 low water mark from the high water mark and add one to get an 599 estimate.) 601 If the group is empty, one of the following three situations 602 will occur. Clients MUST accept all three cases; servers MUST 603 NOT represent an empty group in any other way. 605 . The high water mark will be one less than the low water mark, 606 and the estimated article count will be zero. Servers SHOULD 607 use this method to show an empty group. This is the only time 608 that the high water mark can be less than the low water mark. 609 . All three numbers will be zero. 610 . The high water mark is greater than or equal to the low water 611 mark; the estimated article count might be zero or non-zero; 612 if non-zero, the same requirements apply as for a non-empty 613 group. 615 The set of articles in a group may change after the GROUP 616 command is carried out. That is: 618 . articles may be removed from the group 619 . articles may be reinstated in the group with the same article 620 number, but those articles MUST have numbers no less than the 621 reported low water mark (note that this is a reinstatement of 622 the previous article, not a new article reusing the number) 623 . new articles may be added with article numbers greater than 624 the reported high water mark (if an article that was the one 625 with the highest number has been removed, the next new article 626 will not have the number one greater than the reported high 627 water mark) 629 Except when the group is empty and all three numbers are zero, 630 whenever a subsequent GROUP command for the same news group is 631 issued, either by the same client or a different client, the 632 reported low water mark in the response MUST be no less than 633 that in any previous response for that news group sent to any 634 client. The client may make use of the low water mark to 635 remove all remembered information about articles with lower 636 numbers, as these will never recur. This includes the 637 situation when the high water mark is one less than the low 638 water mark. 640 No similar assumption can be made about the high water mark, 641 as this can decrease if an article is removed, and then 642 increase again if it is reinstated or if new articles arrive. 644 When a valid group is selected by means of this command, the 645 internally maintained "current article pointer" MUST be set to 646 the first article in the group and the name of the current 647 news group MUST be set to the selected news group name. If an 648 invalid group is specified, the previously selected group and 649 article MUST remain selected. If an empty news group is 650 selected, the "current article pointer" is in an indeterminate 651 state and MUST NOT be used. 653 The GROUP keyword MUST be used by a client and a successful 654 response received before the any other command is used that 655 depends on having the "current article pointer" be valid. 657 9.1.1.1.1 Responses 659 211 n f l s group selected 660 (n = estimated number of articles in group, f = first 661 article number in the group, l = last article number in 662 the group, s = name of the group.) 663 411 no such news group 665 9.1.1.2 LAST 667 LAST 668 The internally maintained "current article pointer" MUST be 669 set to the previous article in the current news group. If 670 already positioned at the first article of the news group, an 671 error message MUST be returned and the current article MUST 672 remain selected. 674 There MAY be no previous article in the group, although the 675 current article number is not the reported low water mark. 676 There MUST NOT be a previous article when the current article 677 number is the reported low water mark. 679 Because articles can be removed and added, the results of 680 multiple LAST and NEXT commands MAY not be consistent over the 681 life of a particular NNTP session. 683 The internally-maintained "current article pointer" MUST be 684 set by this command. 686 A response indicating the current article number and a 687 message-id string MUST be returned. No text is sent in 688 response to this command. 690 9.1.1.2.1 Responses 692 223 n a article retrieved - request text separately (n = 693 article number, a = unique article id) 694 412 no news group selected 695 420 no current article has been selected 696 422 no previous article in this group 698 9.1.1.3 NEXT 700 NEXT 702 The internally maintained "current article pointer" MUST be 703 advanced to the next article in the current news group. If no 704 more articles remain in the current group, an error message 705 MUST be returned and the current article MUST remain selected. 707 The internally-maintained "current article pointer" MUST be 708 set by this command. 710 A response indicating the current article number and the 711 message-id string MUST be returned. No text is sent in 712 response to this command. 714 9.1.1.3.1 Responses 716 223 n a article retrieved - request text separately (n = 717 article number, a = unique article id) 719 412 no news group selected 720 420 no current article has been selected 721 421 no next article in this group 723 9.2 Retrieval of Articles and Article Sections 725 There are two forms to the ARTICLE command (and the related 726 BODY, HEAD, and STAT commands), each using a different method 727 of specifying which article is to be retrieved. When the 728 ARTICLE keyword is followed by a message-id in angle brackets 729 ("<" and ">"), the first form of the command MUST be used; 730 when a numeric parameter or no parameter is supplied, the 731 second form MUST be invoked. In the cases where the argument 732 is a message-id, the article number specified in the response 733 must be zero. This is one of the special cases described in 734 section 9.1. 736 An article, as defined by RFC 1036, consists of two parts: the 737 article headers and the article body. When responding to an 738 article command, the server returns the entire article 739 contents and does not attempt to alter or translate them in 740 any way. 742 9.2.1 ARTICLE 744 ARTICLE [|nnn] 746 This response displays the header, a blank line, then the body 747 (text) of the specified article. The optional parameter nnn is 748 the numeric id of an article in the current news group and 749 SHOULD be chosen from the range of articles provided when the 750 news group was selected. If it is omitted, the current 751 article is assumed. Message-id is the message id of an article 752 as shown in that article's header. 754 The internally-maintained "current article pointer" MUST NOT 755 be altered when the message-id argument is used. This is both 756 to facilitate the presentation of articles that may be 757 referenced within an article being read, and because of the 758 semantic difficulties of determining the proper sequence and 759 membership of an article which may have been posted to more 760 than one news group. 762 The internally-maintained "current article pointer" MUST be 763 set when a valid article number is specified as the argument. 764 This includes the case when an article number is implied by 765 the use of no argument. 767 A previously valid article number MAY become invalid if the 768 article has been removed. A previously invalid article number 769 MAY become valid if the article has been reinstated, but such 770 an article number MUST be no less than the reported low water 771 mark for that group. 773 If there is a valid article to present in a reply to this 774 command, a response indicating the current article number (or 775 zero when the message-id argument is used), a message-id 776 string, and that text is to follow MUST be returned. 778 The message-id string is an identification string contained 779 within angle brackets ("<" and ">"), which is derived from the 780 header of the article itself. The Message-ID header line 781 (required by RFC 1036) from the article must be used to supply 782 this information. If the message-id header line is missing 783 from the article, a single digit "0" (zero) should be supplied 784 within the angle brackets. 786 Since the message-id field is unique for each article, it may 787 be used by a news reading program to skip duplicate displays 788 of articles that have been posted more than once, or to more 789 than one news group. 791 9.2.1.1 Responses 792 220 n article retrieved - head and body follow (n = 793 article number, = message-id) 794 412 no news group has been selected 795 420 no current article has been selected 796 423 no such article number in this group 797 430 no such article found 798 502 Service unavailable 800 9.2.2 HEAD 801 HEAD [|nnn] 803 This response displays the header of the specified article. 804 The optional parameter nnn is the numeric id of an article in 805 the current news group and SHOULD be chosen from the range of 806 articles provided when the news group was selected. If it is 807 omitted, the current article is assumed. Message-id is the 808 message id of an article as shown in that article's header. 810 The internally-maintained "current article pointer" MUST NOT 811 be altered when the message-id argument is used. This is both 812 to facilitate the presentation of articles that may be 813 referenced within an article being read, and because of the 814 semantic difficulties of determining the proper sequence and 815 membership of an article which may have been posted to more 816 than one news group. 818 The internally-maintained "current article pointer" MUST be 819 set when a valid article number is specified as the argument. 820 This includes the case when an article number is implied by 821 the use of no argument. 823 A previously valid article number MAY become invalid if the 824 article has been removed. A previously invalid article number 825 MAY become valid if the article has been reinstated, but such 826 an article number MUST be no less than the reported low water 827 mark for that group. 829 If there is a valid article to present in a reply to this 830 command, a response indicating the current article number (or 831 zero when the message-id argument is used), a message-id 832 string, and that text is to follow MUST be returned. 834 The message-id string returned is an identification string 835 contained within angle brackets ("<" and ">"), which is 836 derived from the header of the article itself. The Message-ID 837 header line (required by RFC 1036) from the article must be 838 used to supply this information. If the message-id header line 839 is missing from the article, a single digit "0" (zero) should 840 be supplied within the angle brackets. 842 Since the message-id field is unique for each article, it may 843 be used by a news reading program to skip duplicate displays 844 of articles that have been posted more than once, or to more 845 than one news group. 847 9.2.2.1 Responses 848 221 n article retrieved - head follows 849 412 no news group has been selected 850 420 no current article has been selected 851 423 no such article number in this group 852 430 no such article found 853 502 Service unavailable 855 9.2.3 BODY 856 BODY [|nnn] 858 This response displays the body (text) of the specified 859 article. The optional parameter nnn is the numeric id of an 860 article in the current news group and SHOULD be chosen from 861 the range of articles provided when the news group was 862 selected. If it is omitted, the current article is assumed. 863 Message-id is the message id of an article as shown in that 864 article's header. 866 The internally-maintained "current article pointer" MUST NOT 867 be altered when the message-id argument is used. This is both 868 to facilitate the presentation of articles that may be 869 referenced within an article being read, and because of the 870 semantic difficulties of determining the proper sequence and 871 membership of an article which may have been posted to more 872 than one news group. 874 The internally-maintained "current article pointer" MUST be 875 set when a valid article number is specified as the argument. 876 This includes the case when an article number is implied by 877 the use of no argument. 879 A previously valid article number MAY become invalid if the 880 article has been removed. A previously invalid article number 881 MAY become valid if the article has been reinstated, but such 882 an article number MUST be no less than the reported low water 883 mark for that group. 885 If there is a valid article to present in a reply to this 886 command, a response indicating the current article number (or 887 zero when the message-id argument is used), a message-id 888 string, and that text is to follow MUST be returned. 890 The message-id string returned is an identification string 891 contained within angle brackets ("<" and ">"), which is 892 derived from the header of the article itself. The Message-ID 893 header line (required by RFC 1036) from the article must be 894 used to supply this information. If the message-id header line 895 is missing from the article, a single digit "0" (zero) should 896 be supplied within the angle brackets. 898 Since the message-id field is unique for each article, it may 899 be used by a news reading program to skip duplicate displays 900 of articles that have been posted more than once, or to more 901 than one news group. 903 9.2.3.1 Responses 904 222 n article retrieved - body follows 905 412 no news group has been selected 906 420 no current article has been selected 907 423 no such article number in this group 908 430 no such article found 909 502 Service unavailable 911 9.2.4 STAT 912 STAT [|nnn] 914 This response returns only status information; no article 915 contents are returned. The optional parameter nnn is the 916 numeric id of an article in the current news group and SHOULD 917 be chosen from the range of articles provided when the news 918 group was selected. If it is omitted, the current article is 919 assumed. Message-id is the message id of an article as shown 920 in that article's header. 922 The internally-maintained "current article pointer" MUST NOT 923 be altered when the message-id argument is used. This is both 924 to facilitate the presentation of articles that may be 925 referenced within an article being read, and because of the 926 semantic difficulties of determining the proper sequence and 927 membership of an article which may have been posted to more 928 than one news group. 930 The internally-maintained "current article pointer" MUST be 931 set when a valid article number is specified as the argument. 932 This includes the case when an article number is implied by 933 the use of no argument. 935 A previously valid article number MAY become invalid if the 936 article has been removed. A previously invalid article number 937 MAY become valid if the article has been reinstated, but such 938 an article number MUST be no less than the reported low water 939 mark for that group. 941 If there is a valid article to present in a reply to this 942 command, a response indicating the current article number (or 943 zero when the message-id argument is used) and a message-id 944 string MUST be returned. 946 The message-id string returned is an identification string 947 contained within angle brackets ("<" and ">"), which is 948 derived from the header of the article itself. The Message-ID 949 header line (required by RFC 1036) from the article must be 950 used to supply this information. If the message-id header line 951 is missing from the article, a single digit "0" (zero) should 952 be supplied within the angle brackets. 954 Since the message-id field is unique for each article, it may 955 be used by a news reading program to skip duplicate displays 956 of articles that have been posted more than once, or to more 957 than one news group. 959 9.2.4.1 Responses 960 223 n article retrieved - request text separately 961 412 no news group has been selected 962 420 no current article has been selected 963 423 no such article number in this group 964 430 no such article found 965 502 Service unavailable 967 9.3 Article Posting 969 Article posting is done in one of two modes: individual 970 article posting from news reading clients and article transfer 971 from other news servers. 973 9.3.1 POST 975 POST 976 If posting is allowed, response code 340 MUST be returned to 977 indicate that the article to be posted should be sent. 978 Response code 440 MUST be sent if that posting is prohibited 979 for some installation-dependent reason. 981 If posting is permitted, the article MUST be presented to the 982 server by the client in the format specified by RFC 1036. The 983 text forming the header and body of the message to be posted 984 MUST be sent by the client using the conventions for text 985 received from the news server: A single period (".") on a line 986 indicates the end of the text, with lines starting with a 987 period in the original text having that period doubled during 988 transmission. 990 Following the presentation of the termination sequence by the 991 client, the server MUST return a response code indicating 992 success or failure of the article transfer. 994 No attempt shall be made by the server to filter characters, 995 fold or limit lines, or otherwise process incoming text. The 996 intent is that the server just passes the incoming message to 997 be posted to the server installation's news posting software, 998 which is not part of this specification. 1000 9.3.1.1 Responses 1002 240 article received ok 1003 340 send article to be posted. End with . 1004 440 posting not allowed 1005 441 posting failed 1007 9.3.2 IHAVE 1009 IHAVE 1011 The IHAVE command informs the server that the client has an 1012 article whose id is . If the server desires a copy 1013 of that article, it MUST return a response instructing the 1014 client to send the entire article. If the server does not want 1015 the article (if, for example, the server already has a copy of 1016 it), a response indicating that the article is not wanted MUST 1017 be returned. 1019 If transmission of the article is requested, the client MUST 1020 send the entire article, including header and body, in the 1021 manner specified for text transmission from the server. The 1022 server MUST return a response code indicating success or 1023 failure of the transferal of the article. 1025 This function differs from the POST command in that it is 1026 intended for use in transferring already-posted articles 1027 between hosts. It SHOULD NOT be used when the client is a 1028 personal news reading program. In particular, this function 1029 will invoke the server's news posting program with the 1030 appropriate settings (flags, options, etc.) to indicate that 1031 the forthcoming article is being forwarded from another host. 1033 However, the server MAY elect not to post or forward the 1034 article if after further examination of the article it deems 1035 it inappropriate to do so. Reasons for such subsequent 1036 rejection of an article may include such problems as 1037 inappropriate news groups or distributions, disk space 1038 limitations, article lengths, garbled headers, and the like. 1039 These are typically restrictions enforced by the server host's 1040 news software and not necessarily the NNTP server itself. 1042 9.3.2.1 Responses 1044 235 article transferred ok 1045 335 send article to be transferred. End with . 1047 435 article not wanted - do not send it 1048 436 transfer failed - try again later 1049 437 article rejected - do not try again 1051 Because some host news posting software may not be able to 1052 immediately render status on the whether an article is 1053 inappropriate for posting or forwarding, an NNTP server MAY 1054 acknowledge the successful transfer of the article and later 1055 silently discard it. Thus, an NNTP server MAY return the 235 1056 acknowledgment code and later discard the received article. 1058 9.4 The LIST Keyword 1060 9.4.1 LIST 1062 LIST [ACTIVE [wildmat]] 1064 The response to the LIST keyword with no parameters returns a 1065 list of valid news groups and associated information. Each 1066 news group is sent as a line of text in the following format: 1068 group last first status 1070 where is the name of the news group, is the 1071 number of the last known article currently in that news group, 1072 is the number of the first article currently in the 1073 news group, and indicates the current status of the 1074 group on this server. Typically, the will be consist 1075 of the US-ASCII character `y' where posting is permitted, `n' 1076 where posting is not permitted and `m' where postings will be 1077 forwarded to the news group moderator by the news server. 1079 Other status strings may exist. The definition of these other 1080 values are covered in other specifications. 1082 The and fields will always be numeric. They 1083 may have leading zeros. If the field evaluates to less 1084 than the field, there are no articles currently on 1085 file in the news group. 1087 Note that posting may still be prohibited to a client although 1088 the LIST command indicates that posting is permitted to a 1089 particular news group. See the POST command for an explanation 1090 of client prohibitions. The posting flag exists for each news 1091 group because some news groups are moderated or are digests, 1092 and therefore cannot be posted to; that is, articles posted to 1093 them must be mailed to a moderator who will post them for the 1094 original poster. This is independent of the posting 1095 permission granted to a client by the NNTP server. 1097 Please note that an empty list (i.e., the text body returned 1098 by this command consists only of the terminating period) is a 1099 possible valid response, and indicates that there are 1100 currently no valid news groups. 1102 If the optional matching parameter is specified, the list is 1103 limited to only the groups that match the pattern. 1105 Specifying a single group is usually very efficient for the 1106 server, and multiple groups may be specified by using wildmat 1107 patterns (described in section 5), not regular expressions. 1109 9.4.1.1 Responses 1110 215 list of news groups follows 1112 9.4.2 LIST ACTIVE.TIMES 1114 LIST ACTIVE.TIMES [wildmat] 1116 The active.times file is maintained by some news transport 1117 systems to contain information about when and who created a 1118 particular news group. The format of this file generally 1119 includes three fields. The first field is the name of the news 1120 group. The second is the time when this group was created on 1121 this news server measured in seconds since the start of 1122 January 1, 1970. The third is the email address of the entity 1123 that created the news group. When executed, the information is 1124 displayed following the 215 response. When display is 1125 completed, the server will send a period on a line by itself. 1126 If the information is not available, the server will return 1127 the 503 error response. 1129 If the optional matching parameter is specified, the list is 1130 limited to only the groups that match the pattern. 1132 Specifying a single group is usually very efficient for the 1133 server, and multiple groups may be specified by using wildmat 1134 patterns (described in section 5), not regular expression 1136 9.4.2.1 Responses 1138 215 information follows 1139 503 program error, function not performed 1141 9.4.3 LIST DISTRIBUTIONS 1143 LIST DISTRIBUTIONS 1145 The distributions file is maintained by some news transport 1146 systems to contain information about valid values for the 1147 Distribution: line in a news article header and about what the 1148 values mean. Each line contains two fields, the value and a 1149 short explanation on the meaning of the value. When executed, 1150 the information is displayed following the 215 response. When 1151 display is completed, the server will send a period on a line 1152 by itself. If the information is not available, the server 1153 will return the 503 error response. 1155 9.4.3.1 Responses 1157 215 information follows 1158 503 program error, function not performed 1160 9.4.4 LIST DISTRIB.PATS 1162 LIST DISTRIB.PATS 1164 The distrib.pats file is maintained by some news transport 1165 systems to contain default values for the Distribution: line 1166 in a news article header when posting to particular news 1167 groups. This information could be used to provide a default 1168 value for the Distribution: line in the header when posting an 1169 article. The information returned contains three fields 1170 separated by colons. The first column is a weight. The second 1171 is a group name or a wildmat pattern that can be used to match 1172 a group name. The third is the value of the Distribution: 1173 line that should be used when the group name matches and the 1174 weight value is the highest. All this processing is done by 1175 the news posting client and not by the server itself. The 1176 server provides this information to the client for it to use 1177 or ignore as it chooses. When executed, the information is 1178 displayed following the 215 response. When display is 1179 completed, the server will send a period on a line by itself. 1180 If the information is not available, the server will return 1181 the 503 error response. 1183 9.4.4.1 Responses 1185 215 information follows 1186 503 program error, function not performed 1188 9.4.5 LIST NEWSGROUPS 1190 LIST NEWSGROUPS [wildmat] 1192 The newsgroups file is maintained by some news transport 1193 systems to contain the name of each news group that is 1194 active on the server and a short description about the 1195 purpose of each news group. Each line in the file contains 1196 two fields, the news group name and a short explanation of 1197 the purpose of that news group. When executed, the 1198 information is displayed following the 215 response. When 1199 display is completed, the server will send a period on a 1200 line by itself. If the information is not available, the 1201 server will return the 503 response. If the optional 1202 matching parameter is specified, the list is limited to only 1203 the groups that match the pattern (no matching is done on 1204 the group descriptions). Specifying a single group is 1205 usually very efficient for the server, and multiple groups 1206 may be specified by using wildmat patterns (see section 5), 1207 not regular expressions. If nothing is matched an empty list 1208 is returned, not an error. 1210 9.4.5.1 Responses 1212 215 information follows 1213 503 program error, function not performed 1215 9.4.6 LIST OVERVIEW.FMT 1217 LIST OVERVIEW.FMT 1219 The overview.fmt file is maintained by some news transport 1220 systems to contain the order in which header information is 1221 stored in the overview databases for each news group. When 1222 executed, news article header fields are displayed one line at 1223 a time in the order in which they are stored in the overview 1224 database[7] following the 215 response. When display is 1225 completed, the server will send a period on a line by itself. 1226 If the information is not available, the server will return 1227 the 503 response. 1229 If the header has the word "full" (without quotes) after the 1230 colon, the header's name is prepended to its field in the 1231 output returned by the server. 1233 This is command is part of the optional OVER extension which 1234 includes the OVER command defined in section 9.4.9. If the 1235 OVER extension is not implemented, then this command MUST NOT 1236 be implemented. 1238 9.4.6.1 Responses 1240 215 information follows 1241 503 program error, function not performed 1243 9.4.7 LIST SUBSCRIPTIONS 1245 LIST SUBSCRIPTIONS 1247 This command is used to get a default subscription list for 1248 new users of this server. The order of groups is significant. 1250 When this list is available, it is preceded by the 215 1251 response and followed by a period on a line by itself. When 1252 this list is not available, the server returns a 503 response 1253 code. 1255 9.4.7.1 Responses 1257 215 information follows 1258 503 program error, function not performed 1260 9.4.8 LISTGROUP 1262 LISTGROUP [ggg] 1264 The LISTGROUP command is used to get a listing of all the 1265 article numbers in a particular news group. 1267 The optional parameter ggg is the name of the news group to 1268 be selected (e.g. "news.software.b"). A list of valid news 1269 groups may be obtained from the LIST command. If no group is 1270 specified, the current group is used as the default 1271 argument. 1273 The successful selection response will be a list of the 1274 article numbers in the group followed by a period on a line 1275 by itself. 1277 When a valid group is selected by means of this command, the 1278 internally maintained "current article pointer" MUST be set 1279 to the first article in the group. If an invalid group is 1280 specified, the previously selected group and article remain 1281 selected. If an empty news group is selected, the "current 1282 article pointer" may be in an indeterminate state and should 1283 not be used. 1285 The group name MUST match a news group obtained from the 1286 LIST command or an error will result, else the server will 1287 response with the 411 error code. 1289 The LISTGROUP command is an optional extension. It MAY be 1290 implemented. If it is not implemented, then the LISTGROUP 1291 label MUST NOT be included in the response to the LIST 1292 EXTENSIONS command. 1294 9.4.8.1 Responses 1296 211 list of article numbers follow 1297 411 No such group 1298 412 Not currently in news group 1300 9.4.9 OVER 1302 OVER [range] 1304 The OVER command returns information from the overview 1305 database for the article(s) specified. The information 1306 returned in the response to this command can be used by 1307 clients to follow discussion threads. 1309 The optional range argument may be any of the following: 1311 . an article number 1312 . an article number followed by a dash to indicate all following 1313 . an article number followed by a dash followed by another 1314 article number 1316 If no argument is specified, then information from the current 1317 article is displayed. Successful responses start with a 224 1318 response followed by the overview information for all matched 1319 messages. Once the output is complete, a period is sent on a 1320 line by itself. If no argument is specified, the information 1321 for the current article is returned. A news group must have 1322 been selected earlier, else a 412 error response is returned. 1323 If no articles are in the range specified, the server returns 1324 a 420 error response. A 502 response will be returned if the 1325 client only has permission to transfer articles. 1327 Each line of output MUST be formatted with the article number, 1328 followed by each of the headers in the overview database or 1329 the article itself (when the data is not available in the 1330 overview database) for that article separated by a US-ASCII 1331 tab character. The sequence of fields must be in this order: 1332 subject, author, date, message-id, references, byte count, and 1333 line count. Other optional fields may follow line count. These 1334 fields are specified by examining the response to the LIST 1335 OVERVIEW.FMT command. Where no data exists, a null field must 1336 be provided (i.e. the output will have two tab characters 1337 adjacent to each other). Servers should not output fields for 1338 articles that have been removed since the overview database 1339 was created. 1341 Note that all US-ASCII tab characters in any header data that 1342 is returned will be converted to a single US-ASCII space 1343 character. A contiguous sequence of US-ASCII non-printing 1344 characters will be compressed to a single US-ASCII space 1345 character in any output response. 1347 The OVER command is part of the OVER extension, which includes 1348 the LIST OVERVIEW.FMT command. The OVER extension is optional. 1349 If it is not implemented, the response to the LIST EXTENSIONS 1350 command must not include the OVER label. 1352 9.4.9.1 Responses 1354 224 Overview information follows 1355 412 No news group current selected 1356 420 No article(s) selected 1357 502 no permission 1359 9.4.10 PAT 1361 PAT header range| [pat [pat...]] 1363 The PAT command is used to retrieve specific headers from 1364 specific articles, based on pattern matching on the contents 1365 of the header. 1367 The required header parameter is the name of a header line 1368 (e.g. "subject") in a news group article. See RFC-1036 for a 1369 list of valid header lines. The required range argument may be 1370 any of the following: 1372 . an article number 1373 . an article number followed by a dash to indicate all following 1374 . an article number followed by a dash followed by another 1375 article number. 1376 The required message-id argument indicates a specific article. 1377 The range and message-id arguments are mutually exclusive. If 1378 there are additional arguments, they are joined together 1379 separated by a single space to form one complete pattern. If 1380 there are no additional arguments, a wildmat "*" is the 1381 default. Successful responses start with a 221 response 1382 followed by article number, an US-ASCII space, and the header 1383 from that message in which the pattern matched the contents of 1384 the specified header line. A valid response includes an empty 1385 list (indicating that there was no matches). Once the output 1386 is complete, a period is sent on a line by itself. If the 1387 optional argument is a message-id and no such article exists, 1388 the 430 error response shall be returned. A 502 response shall 1389 be returned if the client only has permission to transfer 1390 articles. 1392 The PAT command is optional. If it is not implemented, the 1393 response to the LIST EXTENSIONS command must not include the 1394 PAT label. 1396 9.4.10.1 Responses 1398 221 Header follows 1399 430 no such article 1400 502 no permission 1402 10. The CONCLUSION Step 1404 10.1 QUIT 1406 QUIT 1408 The server process MUST acknowledge the QUIT command and then 1409 closes the connection to the client. This is the preferred 1410 method for a client to indicate that it has finished all its 1411 transactions with the NNTP server. 1413 If a client simply disconnects (or the connection times out or 1414 some other fault occurs), the server SHALL gracefully cease 1415 its attempts to service the client. 1417 10.1.1 Responses 1419 205 closing connection - goodbye! 1421 11. Other Keywords 1423 There are other keywords that may be used at any time between 1424 the beginning of a session and its termination. Using these 1425 keywords do not alter any state information, but the response 1426 generated from the use of these keywords may provide useful 1427 information to clients that use them. 1429 11.1 DATE 1431 DATE 1433 This command exists to help clients find out the current time 1434 from the server's perspective. This command SHOULD NOT be 1435 used as a substitute for NTP[8], but to provide information 1436 that might be useful when using the NEWNEWS command (see 1437 section 11.4). 1439 This command returns a one-line response code of 111 followed 1440 by the UTC (or GMT) date and time on the server in the form 1441 YYYYMMDDhhmmss. 1443 11.1.1 Responses 1445 111 YYYYMMDDhhmmss 1447 11.2 The HELP Command 1449 HELP 1451 This command provides a short summary of commands that are 1452 understood by this implementation of the server. The help text 1453 will be presented as a textual response terminated by a single 1454 period on a line by itself. 1456 This text is not guaranteed to be in any particular format and 1457 SHALL NOT be used by clients as a replacement for the LIST 1458 EXTENSIONS command described in section 8.1. 1460 11.2.1 Responses 1462 100 help text follows 1464 11.3 NEWGROUPS 1466 NEWGROUPS date time [GMT|UTC] 1468 A list of newsgroups created since MUST be 1469 listed in the same format as the LIST command. 1471 The date is sent as 6 or 8 digits in the format [XX]YYMMDD, 1472 where XX is the first two digits of the year, YY is the last 1473 two digits of the year, MM is the two digits of the month 1474 (with leading zero, if appropriate), and DD is the day of the 1475 month (with leading zero, if appropriate). If the first two 1476 digits of the year are not specified, the year is to be taken 1477 from the current century if YY is smaller than or equal to the 1478 current year, otherwise the year is from the previous century. 1480 Time must also be specified. It must be as 6 digits HHMMSS 1481 with HH being hours in the 24-hour clock 00-23, MM minutes 00- 1482 59, and SS seconds 00-60, which allows for leap seconds. The 1483 tokens "GMT" and "UTC" specifies that the date and time are 1484 given in UTC. If the tokens "GMT" and "UTC" are omitted then 1485 the date and time are specified in the server's local 1486 timezone. Note that there is no way within this specification 1487 of NNTP to establish the server's local timezone. 1489 Note that an empty list (i.e., the text body returned by this 1490 command consists only of the terminating period) is a possible 1491 valid response, and indicates that there are currently no new 1492 newsgroups. 1494 Clients SHOULD make all queries using GMT/UTC time when 1495 possible. 1497 11.3.1 Responses 1499 231 list of new newsgroups follows 1501 11.4 NEWNEWS 1503 NEWNEWS newsgroups date time [GMT] 1505 A list of message-ids of articles posted or received to the 1506 specified news group since "date" will be listed. The format 1507 of the listing will be one message-id per line, as though text 1508 were being sent. A single line consisting solely of one 1509 period followed by CR-LF will terminate the list. 1511 Date and time are in the same format as the NEWGROUPS command. 1512 The newsgroups parameter MUST be in wildmat format and MAY 1513 consist of multiple wildmat constructs separated by an US- 1514 ASCII comma character. 1516 Note that an empty list (i.e., the text body returned by this 1517 command consists only of the terminating period) is a possible 1518 valid response, and indicates that there is currently no new 1519 news. 1521 Clients SHOULD make all queries in GMT/UTC time when possible. 1523 11.4.1 Responses 1525 230 list of new articles by message-id follows 1527 12. Framework for NNTP Extensions 1529 Although NNTP is widely and robustly deployed, some parts of 1530 the Internet community might wish to extend the NNTP service. 1531 This memo defines a means whereby an extended NNTP client may 1532 query the server to determine the service extensions that it 1533 supports. 1535 It must be emphasized that any extension to the NNTP service 1536 should not be considered lightly. NNTP's strength comes 1537 primarily from its simplicity. Experience with many protocols 1538 has shown that: 1540 Protocols with few options tend towards ubiquity, whilst 1541 protocols with many options tend towards obscurity. 1543 This means that each and every extension, regardless of its 1544 benefits, must be carefully scrutinized with respect to its 1545 implementation, deployment, and interoperability costs. In 1546 many cases, the cost of extending the NNTP service will likely 1547 outweigh the benefit. 1549 Given this environment, the framework for the extensions 1550 described in this memo consists of: 1552 a) a mechanism for clients to determine a server's available 1553 extensions 1554 b) a registry of NNTP service extensions 1556 The LIST EXTENSIONS command is described in section 8.1 of 1557 this memo and is the mechanism for clients to use to determine 1558 what extensions are available for client use. 1560 The IANA shall maintain a registry of NNTP service extensions. 1562 Associated with each such extension is a corresponding NNTP 1563 keyword value. Each service extension registered with the IANA 1564 MUST be defined in an RFC. Such RFCs either must be on the 1565 standards-track or must define an IESG-approved experimental 1566 protocol. The definition must include: 1568 . the textual name of the NNTP service extension 1569 . the label that is returned by LIST EXTENSIONS that would 1570 indicate to the client that the server supports this 1571 particular extension 1572 . any new NNTP keywords associated with the extension 1573 . the syntax and possible values of parameters associated with 1574 the new NNTP keywords 1575 . any new parameters the extension associates with any other 1576 pre-existing NNTP verbs 1577 . how support for the extension affects the behavior of a server 1578 and client NNTP 1579 . the increment by which the extension is increasing the maximum 1580 length of the any commands over that specified in this 1581 document. 1583 In addition, any NNTP keyword value that starts with an upper 1584 or lower case "X" refers to a local NNTP service extension, 1585 which is used through bilateral, rather than standardized, 1586 agreement. Keywords beginning with "X" MUST NOT be used in a 1587 registered service extension. 1589 Any keyword values presented in the NNTP response that do not 1590 begin with "X" must correspond to a standard, standards-track, 1591 or IESG-approved experimental NNTP service extension 1592 registered with IANA. A conforming server MUST NOT offer non 1593 "X" prefixed keyword values that are not described in a 1594 registered extension. 1596 Additional verbs are bound by the same rules as NNTP keywords; 1597 specifically, verbs beginning with "X" are local extensions 1598 that MUST NOT be registered or standardized and verbs not 1599 beginning with "X" must always be registered. 1601 12.1 Initial IANA Registry 1603 The IANA's initial registry of NNTP service extensions 1604 consists of these entries: 1606 Service Extension NNTP Extension Label Added Behavior 1608 Overview Support OVER Defined in this 1609 document 1611 Specific Article LISTGROUP Defined in this 1612 Numbers document 1614 Header Pattern PAT Defined in this 1615 Matching document 1617 13. Augmented BNF[9] Syntax for NNTP Commands 1619 This syntax defines the non-terminal "command". The non-terminal 1620 "parameter" is used for command parameters whose syntax is 1621 specified elsewhere. The syntax is in alphabetical order. Note 1622 that ABNF strings are case insensitive. 1624 article-command = "ARTICLE" [1*WSP (msg-id / article-number)] 1625 *WSP CRLF 1626 article-number = 1*16DIGIT 1627 augument = parameter ; excluding sequence ".." 1628 body-command = "BODY" [1*WSP (msg-id / article-number)] *WSP 1629 CRLF 1630 command = article-command / 1631 body-command / 1632 date-command / 1633 group-command / 1634 head-command / 1635 help-command / 1636 ihave-command / 1637 last-command / 1638 list-active-times-command / 1639 list-distrib-pats-command / 1640 list-distributions-command / 1641 list-extensions-command / 1642 list-newsgroups-command / 1643 list-overview-fmt-command / 1644 list-subscriptions-command / 1645 list-command / 1646 listgroup-command / 1647 mode-reader-command / 1648 newgroups-command / 1649 newnews-command / 1650 next-command / 1651 over-command / 1652 pat-command / 1653 post-command / 1654 quit-command / 1655 stat-command 1656 CR = %x0D 1657 CRLF = CR LF 1658 date-command = "DATE" *WSP CRLF 1659 date = 6*8DIGIT 1660 DIGIT = %x30-39 1661 group-command = "GROUP" 1*WSP newsgroup *WSP CRLF 1662 head-command = "HEAD" [1*WSP (msg-id / article-number)] *WSP 1663 CRLF 1664 header = parameter 1665 help-command = "HELP" *WSP CRLF 1666 HT = %x09 1667 ihave-command = "IHAVE" 1*WSP msg-id *WSP CRLF 1668 last-command = "LAST" *WSP CRLF 1669 LF = %x0A 1670 list-active-times-command = "LIST" 1*WSP "ACTIVE.TIMES" 1671 [1*WSP wildmat] *WSP CRLF 1672 list-command = "LIST" [1*WSP "ACTIVE" [1*WSP wildmat]] *WSP 1673 CRLF 1674 list-distrib-pats-command = "LIST" 1*WSP "DISTRIB.PATS" *WSP 1675 CRLF 1676 list-distributions-command = "LIST" 1*WSP "DISTRIBUTIONS" *WSP 1677 CRLF 1678 list-extensions-command = "LIST" 1*WSP "EXTENSIONS" *WSP CRLF 1679 list-newsgroups-command = "LIST" 1*WSP "NEWSGROUPS" [1*WSP 1680 wildmat] 1681 *WSP CRLF 1682 list-overview-fmt-command = "LIST" 1*WSP "OVERVIEW.FMT" *WSP 1683 CRLF 1684 list-subscriptions-command = "LIST" 1*WSP "SUBSCRIPTIONS" *WSP 1685 CRLF 1686 listgroup-command = "LISTGROUP" [1*WSP newsgroup] *WSP CRLF 1687 mode-reader-command = "MODE" 1*WSP "READER" *WSP CRLF 1688 msg-id = 1689 newgroups-command = "NEWGROUPS" 1*WSP date 1*WSP time [1*WSP 1690 "GMT"/"UTC"] *WSP CRLF 1692 newnews-command = "NEWNEWS" 1*WSP newsgroup *("," newsgroup) 1693 1*WSP date 1*WSP time [1*WSP "GMT"/"UTC"] 1694 *WSP CRLF 1695 newsgroup = parameter 1696 next-command = "NEXT" *WSP CRLF 1697 over-command = "OVER" [1*WSP range] *WSP CRLF 1698 parameter = 1*(%x21-FF) ; generic command parameter 1699 pat-command = "PAT" 1*WSP header 1*WSP (range / msg-id) 1700 *(1*WSP wildmat) *WSP CRLF 1701 post-command = "POST" *WSP CRLF 1702 quit-command = "QUIT" *WSP CRLF 1703 range = article-number ["-" [article-number]] 1704 SP = %x20 1705 stat-command = "STAT" [1*WSP (msg-id / article-number)] *WSP 1706 CRLF 1707 time = 6DIGIT 1708 UTF-8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4 / UTF8-5 / UTF8-6 1709 UTF8-1 = %x80-BF 1710 UTF8-2 = %xC0-DF UTF8-1 1711 UTF8-3 = %xE0-EF 2UTF8-1 1712 UTF8-4 = %xF0-F7 3UTF8-1 1713 UTF8-5 = %xF8-FB 4UTF8-1 1714 UTF8-6 = %xFC-FD 5UTF8-1 1715 wildmat = 1*("!" / "*" / "?" / wildmat-exact / wildmat-set / 1716 "\" (%x22-7F / UTF-8-non-ascii)) 1717 wildmat-exact = %x22-29 / %x2B-3E / %x40-5A / %x5D-7F / UTF-8- 1718 non-ascii ; exclude space ! * ? [ \ 1719 wildmat-non-hyphen = %x21-2C / %x2E-7F / UTF-8-non-ascii ; 1720 exclude space - 1721 wildmat-set = "[" ["^"] ["]" / "-"] *(wildmat-non-hyphen ["-" 1722 WSP = SP / HT 1724 14. Security Considerations 1725 There is a serious need for good text to put in this section. 1726 Here is an attempt: 1728 The nature of network news over its history has been the 1729 sharing of information, seemingly without restriction. While 1730 this was reasonable when NNTP was first specified, the lack of 1731 a mechanism for restricting access to network news may no 1732 longer be appropriate. This specification has some provisions 1733 in it which make it possible to add authentication and 1734 identification mechanisms, but none are included in this 1735 specification. It is expected that those mechanisms will be 1736 defined as specific extensions using the extension mechanism 1737 specified in this document. 1739 15. Notes 1741 UNIX is a registered trademark of the X/Open Consortium. 1743 16. References 1745 [1] Kantor, B and P. Lapsley, "Network News Transfer Protocol", 1746 RFC-977, U.C. San Diego and U.C. Berkeley. 1748 [2] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 1749 RFC 2278, Alis Technologies. 1751 [3] Coded Character Set-7-bit American Standard Code for 1752 Information Interchange, ANSI x3.4-1986. 1754 [4] Bradner, Scott, "Key words for use in RFCs to Indicate 1755 Requirement Levels", RFC-2119, Harvard University. 1757 [5] Salz, Rich, Manual Page for wildmat(3) from the INN 1.4 1758 distribution, UUNET Technologies, Revision 1.10, April, 1992. 1760 [6] Horton, M.R. and R. Adams, "Standard for interchange of 1761 USENET messages", RFC-1036, AT&T Bell Laboratories and Center 1762 for Seismic Studies, December, 1987. 1764 [7] Robertson, Rob, "FAQ: Overview database / NOV General 1765 Information", ftp://ftp.uu.net/networking/news/nntp/inn/faq- 1766 nov.Z, January, 1995. 1768 [8] Mills, David L., "Network Time Protocol (Version 3), 1769 Specification, Implementation and Analysis", RFC-1305, 1770 University of Delaware, March 1992. 1772 [9] Crocker, D. and Overell, P., "Augmented BNF for Syntax 1773 Specifications: ABNF", RFC-2234, Internet Mail Consortium and 1774 Demon Internet, Ltd. 1776 17. Acknowledgments 1778 The author acknowledges the original authors of NNTP as 1779 documented in RFC 977: Brian Kantor and Phil Lapsey. 1781 The author gratefully acknowledges the work of the NNTP 1782 committee chaired by Eliot Lear. The organization of this 1783 document was influenced by the last available draft from this 1784 working group. A special thanks to Eliot for generously 1785 providing the original machine readable sources for that 1786 document. 1788 The author gratefully acknowledges the work of the Marshall 1789 Rose & John G. Meyers in RFC 1939 and the work of the DRUMS 1790 working group, specifically RFC 1869, which is the basis of 1791 the NNTP extensions mechanism detailed in this document. 1793 The author gratefully acknowledges the comments and additional 1794 information provided by the following individuals in preparing 1795 one of the progenitors of this document: 1797 . Wayne Davison 1798 . Clive D.W. Feather 1799 . Chris Lewis 1800 . Tom Limoncelli 1801 . Eric Schnoebelen 1802 . Rich Salz 1804 This work was precipitated by the work of various newsreader 1805 authors and newsserver authors, which includes those listed 1806 below: 1808 . Rick Adams -- Original author of the NNTP extensions to the RN 1809 newsreader and last maintainer of Bnews 1810 . Stan Barber -- Original author of the NNTP extensions to the 1811 newsreaders that are part of Bnews. 1812 . Geoff Collyer -- Original author of the OVERVIEW database 1813 proposal and one of the original authors of CNEWS 1814 . Dan Curry -- Original author of the xvnews newsreader 1815 . Wayne Davision"Author of the first threading extensions to the 1816 RN newsreader (commonly called TRN). 1817 . Geoff Huston -- Original author of ANU NEWS 1818 . Phil Lapsey -- Original author of the UNIX reference 1819 implementation 1820 . Ian Lea -- Maintainer of the TIN newsreader 1821 . Rich Salz -- Original author of INN 1822 . Henry Spencer -- One of the original authors of CNEWS 1823 . Kim Storm -- Original author of the NN newsreader 1825 18. Author's Address 1827 Stan Barber 1828 P.O. Box 300481 1829 Houston, Texas, 77230 1830 Email: 1832 This document expires June 7, 1999.