idnits 2.17.1 draft-ietf-nntpext-base-19.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC2629]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 38 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 212 has weird spacing: '...cal|bar indic...' == Line 795 has weird spacing: '...abc,def the t...' == Line 2041 has weird spacing: '...dhhmmss serv...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: These are the only valid response codes for the initial greeting; the server MUST not return any other generic response code. -- 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 1, 2003) is 7566 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: 'C' is mentioned on line 3422, but not defined == Missing Reference: 'S' is mentioned on line 3428, but not defined -- Looks like a reference, but probably isn't: '1' on line 2901 == Missing Reference: 'GMT' is mentioned on line 2165, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'ANSI1986' ** Obsolete normative reference: RFC 1305 (Obsoleted by RFC 5905) ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 2822 (Obsoleted by RFC 5322) ** Obsolete normative reference: RFC 977 (Obsoleted by RFC 3977) -- Possible downref: Non-RFC (?) normative reference: ref. 'ROBE1995' -- Obsolete informational reference (is this intentional?): RFC 1036 (Obsoleted by RFC 5536, RFC 5537) -- Obsolete informational reference (is this intentional?): RFC 1869 (Obsoleted by RFC 2821) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2629 (Obsoleted by RFC 7749) Summary: 7 errors (**), 0 flaws (~~), 10 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NNTP C. Feather 3 Internet-Draft Thus plc 4 Expires: January 30, 2004 August 1, 2003 6 Network News Transport Protocol 7 draft-ietf-nntpext-base-19 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that other 16 groups may also distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 The list of current Internet-Drafts can be accessed at http:// 24 www.ietf.org/ietf/1id-abstracts.txt. 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 This Internet-Draft will expire on January 30, 2004. 31 Copyright Notice 33 Copyright (C) The Internet Society (2003). All Rights Reserved. 35 Abstract 37 The Network News Transport Protocol (NNTP) has been in use in the 38 Internet for a decade and remains one of the most popular protocols 39 (by volume) in use today. This document is a replacement for RFC 977 40 and officially updates the protocol specification. It clarifies some 41 vagueness in RFC 977, includes some new base functionality and 42 provides a specific mechanism to add standardized extensions to NNTP. 44 Administration 46 This document is a product of the NNTP Working Group, chaired by Russ 47 Allbery and Ned Freed. 49 This is draft 19. 51 Outstanding issues 53 OUTSTANDING ISSUE 55 Outstanding substantive (as opposed to editorial) issues in the 56 text are shown thus. 58 Author's Note 60 This draft is written in XML using an NNTP-specific DTD. Custom 61 software is used to convert this to RFC 2629 [RFC2629] format, and 62 then the public "xml2rfc" package to further reduce this to text, 63 nroff source, and HTML. 65 No perl was used in producing this draft. 67 Rights 69 UNIX is a registered trademark of the X/Open Company Ltd. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 5 74 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . 6 75 3. Basic Concepts . . . . . . . . . . . . . . . . . . . . . . 7 76 3.1 Commands and Responses . . . . . . . . . . . . . . . . . . 7 77 3.2 Response Codes . . . . . . . . . . . . . . . . . . . . . . 9 78 3.2.1 Generic Response Codes . . . . . . . . . . . . . . . . . . 10 79 3.2.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 12 80 3.3 Pipelining . . . . . . . . . . . . . . . . . . . . . . . . 13 81 3.3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 14 82 3.4 Articles . . . . . . . . . . . . . . . . . . . . . . . . . 15 83 4. The WILDMAT format . . . . . . . . . . . . . . . . . . . . 17 84 4.1 Wildmat syntax . . . . . . . . . . . . . . . . . . . . . . 17 85 4.2 Wildmat semantics . . . . . . . . . . . . . . . . . . . . 17 86 4.3 Extensions . . . . . . . . . . . . . . . . . . . . . . . . 18 87 4.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 19 88 5. Session administration commands . . . . . . . . . . . . . 20 89 5.1 Initial Connection . . . . . . . . . . . . . . . . . . . . 20 90 5.2 MODE READER . . . . . . . . . . . . . . . . . . . . . . . 21 91 5.3 LIST EXTENSIONS . . . . . . . . . . . . . . . . . . . . . 23 92 5.4 QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 93 6. Article posting and retrieval . . . . . . . . . . . . . . 26 94 6.1 Group and article selection . . . . . . . . . . . . . . . 26 95 6.1.1 GROUP . . . . . . . . . . . . . . . . . . . . . . . . . . 26 96 6.1.2 LAST . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 97 6.1.3 NEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 98 6.2 Retrieval of articles and article sections . . . . . . . . 32 99 6.2.1 ARTICLE . . . . . . . . . . . . . . . . . . . . . . . . . 32 100 6.2.2 HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 101 6.2.3 BODY . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 102 6.2.4 STAT . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 103 6.3 Article posting . . . . . . . . . . . . . . . . . . . . . 41 104 6.3.1 POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 105 6.3.2 IHAVE . . . . . . . . . . . . . . . . . . . . . . . . . . 43 106 7. Information commands . . . . . . . . . . . . . . . . . . . 46 107 7.1 DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 108 7.2 HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 109 7.3 NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 47 110 7.4 NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 49 111 7.5 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 112 7.5.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 50 113 7.6 The LIST commands . . . . . . . . . . . . . . . . . . . . 51 114 7.6.1 LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . . . 51 115 7.6.2 LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . . . 53 116 7.6.3 LIST DISTRIBUTIONS . . . . . . . . . . . . . . . . . . . . 54 117 7.6.4 LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . . . 55 118 7.6.5 LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . . . 57 119 8. Framework for NNTP extensions . . . . . . . . . . . . . . 59 120 8.1 Initial IANA registry . . . . . . . . . . . . . . . . . . 61 121 8.2 Standard extensions . . . . . . . . . . . . . . . . . . . 61 122 8.3 The LISTGROUP extension . . . . . . . . . . . . . . . . . 61 123 8.3.1 LISTGROUP . . . . . . . . . . . . . . . . . . . . . . . . 61 124 8.4 Article metadata . . . . . . . . . . . . . . . . . . . . . 63 125 8.4.1 The :bytes metadata item . . . . . . . . . . . . . . . . . 63 126 8.4.2 The :lines metadata item . . . . . . . . . . . . . . . . . 63 127 8.5 The OVER extension . . . . . . . . . . . . . . . . . . . . 64 128 8.5.1 OVER . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 129 8.5.2 LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 68 130 8.6 The HDR extension . . . . . . . . . . . . . . . . . . . . 70 131 8.6.1 HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 132 8.6.2 LIST HEADERS . . . . . . . . . . . . . . . . . . . . . . . 74 133 9. Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . 77 134 9.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . 77 135 9.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . 79 136 9.3 Articles . . . . . . . . . . . . . . . . . . . . . . . . . 79 137 9.4 General non-terminals . . . . . . . . . . . . . . . . . . 79 138 10. IANA Considerations . . . . . . . . . . . . . . . . . . . 81 139 11. Security Considerations . . . . . . . . . . . . . . . . . 82 140 11.1 Personal and Proprietary Information . . . . . . . . . . . 82 141 11.2 Abuse of Server Log Information . . . . . . . . . . . . . 82 142 11.3 Weak Authentication and Access Control . . . . . . . . . . 82 143 11.4 DNS Spoofing . . . . . . . . . . . . . . . . . . . . . . . 83 144 11.5 UTF-8 issues . . . . . . . . . . . . . . . . . . . . . . . 83 145 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 85 146 Normative References . . . . . . . . . . . . . . . . . . . 87 147 Informative References . . . . . . . . . . . . . . . . . . 88 148 Author's Address . . . . . . . . . . . . . . . . . . . . . 88 149 A. Future Directions . . . . . . . . . . . . . . . . . . . . 89 150 B. Interaction with other specifications . . . . . . . . . . 90 151 B.1 Header folding . . . . . . . . . . . . . . . . . . . . . . 90 152 B.2 Message-IDs . . . . . . . . . . . . . . . . . . . . . . . 90 153 B.3 Article posting . . . . . . . . . . . . . . . . . . . . . 91 154 Intellectual Property and Copyright Statements . . . . . . 93 156 1. Introduction 158 This document specifies the Network News Transport Protocol (NNTP), 159 which is used for the distribution, inquiry, retrieval, and posting 160 of Netnews articles using a reliable stream-based mechanism. For news 161 reading clients, NNTP enables retrieval of news articles that are 162 stored in a central database, giving subscribers the ability to 163 select only those articles they wish to read. 165 The Netnews model provides for indexing, cross-referencing, and 166 expiration of aged messages. For server-to-server interaction, NNTP 167 is designed for efficient transmission of Netnews articles over a 168 reliable full duplex communication channel. 170 Every attempt is made to ensure that the protocol specification in 171 this document is compatible with the version specified in RFC 977 172 [RFC977]. However, this version does not support the ill-defined 173 SLAVE command and permits four digit years to be specified in the 174 NEWNEWS and NEWGROUPS commands. It changes the default character set 175 to UTF-8 [RFC2279] instead of US-ASCII [ANSI1986]. It now requires 176 all articles to have a message-id, eliminating the "<0>" placeholder 177 used in RFC 977. It also extends the newsgroup name matching 178 capabilities already documented in RFC 977. 180 Generally, new functionality is made available using new commands. 181 Part of that new functionality involves a mechanism to discover what 182 new functionality is available to clients from a server. This 183 mechanism can also be used to add more functionality as needs merit 184 such additions. 186 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 187 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 188 document are to be interpreted as described in RFC 2119 [RFC2119]. 190 An implementation is not compliant if it fails to satisfy one or more 191 of the MUST requirements for this protocol. An implementation that 192 satisfies all the MUST and all the SHOULD requirements for its 193 protocols is said to be "unconditionally compliant"; one that 194 satisfies all the MUST requirements but not all the SHOULD 195 requirements for NNTP is said to be "conditionally compliant". 197 For the remainder of this document, the term "client" or "client 198 host" refers to a host making use of the NNTP service, while the term 199 "server" or "server host" refers to a host that offers the NNTP 200 service. 202 2. Notation 204 The following notational conventions are used in this document. 206 UPPERCASE indicates literal text to be included in the 207 command; 208 lowercase indicates a token described elsewhere; 209 [brackets] indicate that the parameter is optional; 210 ellipsis... indicates that the parameter may be repeated any 211 number of times (it must occur at least once); 212 vertical|bar indicates a choice of two mutually exclusive 213 parameters (exactly one must be provided). 215 The name "message-id" for a command or response parameter indicates 216 that it is the message-id of an article as described in Section 3.4, 217 including the angle brackets. 219 The name "wildmat" for a parameter indicates that it is a wildmat as 220 defined in Section 4. If the parameter does not meet the requirements 221 of that section (for example, if it does not fit the grammar of 222 Section 4.1) the NNTP server MAY place some interpretation on it (not 223 specified by this document) or otherwise MUST treat it as a syntax 224 error. 226 Responses for each command will be described in tables listing the 227 required format of a response followed by the meaning that should be 228 ascribed to that response. 230 The terms "NUL", "TAB", "LF", "CR, and "space" refer to the octets 231 with those codes in US-ASCII [ANSI1986] (that is, %x00, %x09, %x0A, 232 %x0D, and %x20 respectively), as do quoted characters (so "." and "<" 233 refer to %x2E and %x3C). The term "CRLF" or "CRLF pair" means the 234 sequence CR immediately followed by LF (that is, %x0D.0A). A 235 "printable US-ASCII character" is an octet in the range %x21-7E. 237 Examples in this document are not normative but serve to illustrate 238 usages, arguments, and responses. In the examples, a "[C]" will be 239 used to represent the client host and a "[S]" will be used to 240 represent the server host. Most of the examples do not rely on a 241 particular server state. In some cases, however, they do assume that 242 the current selected newsgroup (see the GROUP command (Section 243 6.1.1)) is invalid; when so, this is indicated at the start of the 244 example. 246 3. Basic Concepts 248 3.1 Commands and Responses 250 NNTP operates over any reliable data stream 8-bit-wide channel. 251 Initially, the server host starts the NNTP service by listening on a 252 TCP port; when running over TCP/IP, the official port for the NNTP 253 service is 119. When a client host wishes to make use of the service, 254 it MUST establish a TCP connection with the server host by connecting 255 to that host on the same port on which the server is listening. When 256 the connection is established, the NNTP server host MUST send a 257 greeting. The client host and server host then exchange commands and 258 responses (respectively) until the connection is closed or aborted. 260 The character set for all NNTP commands is UTF-8 [RFC2279]. Commands 261 in NNTP MUST consist of a keyword, which MAY be followed by one or 262 more arguments. A CRLF pair MUST terminate all commands. Multiple 263 commands MUST NOT be on the same line. Keywords MUST consist of 264 printable US-ASCII characters. Unless otherwise noted elsewhere in 265 this document, arguments SHOULD consist of printable US-ASCII 266 characters. Keywords and arguments MUST be each separated by one or 267 more space or TAB characters. Keywords MUST be at least three 268 characters and MUST NOT exceed 12 characters. Command lines MUST NOT 269 exceed 512 octets, which includes the terminating CRLF pair. The 270 arguments MUST NOT exceed 497 octets. A server MAY relax these limits 271 for commands defined in an extension. 273 Where this specification permits UTF-8 characters outside the range 274 U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark 275 (U+FEFF, encoding %xEF.BB.BF), and MUST use the Word Joiner (U+2060, 276 encoding %xE2.91.A0) for the meaning Zero Width No-Break Space, in 277 command lines and the initial lines of responses, and SHOULD apply 278 these same principles throughout. 280 Commands may have variants, using a second keyword immediately after 281 the first to indicate which variant is required. The only such 282 commands in this specification are LIST and MODE. 284 Keywords are case-insensitive; the case of keywords for commands MUST 285 be ignored by the server. Command and response parameters are case or 286 language specific only when stated, either in this document or in 287 other relevant specifications. 289 An NNTP server MUST implement all the commands in this specification 290 except for those marked as optional and those in extensions. 292 Each response MUST start with a three-digit response code that is 293 sufficient to distinguish all responses. Certain valid responses are 294 defined to be multi-line; for all others, the response is contained 295 in a single line. The first or only line of the response MUST NOT 296 exceed 512 octets, which includes the response code and the 297 terminating CRLF pair; an extension MAY specify a greater maximum for 298 commands that it defines, but not for any other command. 300 All multi-line responses MUST adhere to the following format: 302 1. The response consists of a sequence of one or more "lines", each 303 being a stream of octets ending with a CRLF pair. Apart from 304 those line endings, the stream MUST NOT include the octets NUL, 305 LF, or CR. 307 2. The first such line contains the response code as with a single 308 line response. 310 3. If any subsequent line begins with the "termination octet" ("." 311 or %x2E), that line MUST be "byte-stuffed" by pre-pending an 312 additional termination octet to that line of the response. 314 4. The lines of the response MUST be followed by a terminating line 315 consisting of a single termination octet followed by a CRLF pair 316 in the normal way. Thus a multi-line response is always 317 terminated with the five octets CRLF "." CRLF (%x0D.0A.2E.0D.0A). 319 5. When interpreting a multi-line response, the "byte stuffing" MUST 320 be undone; i.e. the client MUST ensure that, in any line 321 beginning with the termination octet followed by octets other 322 than a CRLF pair, that initial termination octet is disregarded. 324 6. Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT 325 be considered part of the multi-line response; i.e. the client 326 MUST ensure that any line beginning with the termination octet 327 followed immediately by a CRLF pair is disregarded; (the first 328 CRLF pair of the terminating CRLF "." CRLF is, of course, part of 329 the last line of the response). 331 Note that texts using an encoding (such as UTF-16 or UTF-32) that may 332 contain the octets NUL, LF, or CR other than a CRLF pair cannot be 333 reliably conveyed in the above format. However, except when stated 334 otherwise, this specification does not require the content to be 335 UTF-8 and it is possible for octets above and below 128 to be mixed 336 arbitrarily. 338 This document does not place any limit on the length of a subsequent 339 line in a multi-line response. However, the standards that define the 340 format of articles may do so. 342 An NNTP server MAY have an inactivity autologout timer. Such a timer 343 SHOULD be of at least three minutes duration, with the exception that 344 there MAY be a shorter limit on how long the server is willing to 345 wait for the first command from the client. The receipt of any 346 command from the client during the timer interval SHOULD suffice to 347 reset the autologout timer. Similarly, the receipt of any significant 348 amount of data from the client while in the midst of sending a 349 multi-line message to the server (such as during a POST or IHAVE 350 command) SHOULD suffice to reset the autologout timer. When the timer 351 expires, the server SHOULD close the TCP connection without sending 352 any response to the client. 354 3.2 Response Codes 356 Each response MUST begin with a three-digit status indicator. These 357 are status reports from the server and indicate the response to the 358 last command received from the client. 360 The first digit of the response broadly indicates the success, 361 failure, or progress of the previous command. 363 1xx - Informative message. 364 2xx - Command completed OK. 365 3xx - Command OK so far; send the rest of it. 366 4xx - Command was correct, but couldn't be performed for some 367 reason. 368 5xx - Command unimplemented, or incorrect, or a serious program 369 error occurred. 371 The next digit in the code indicates the function response category. 373 x0x - Connection, setup, and miscellaneous messages 374 x1x - Newsgroup selection 375 x2x - Article selection 376 x3x - Distribution functions 377 x4x - Posting 378 x8x - Reserved for authentication and authorization extensions 379 x9x - Reserved for private use (non-standard extensions) 381 Certain responses contain parameters such as numbers and names in 382 addition to the status indicator. In those cases, to simplify 383 interpretation by the client the number and type of such parameters 384 is fixed for each response code, as is whether or not the code 385 introduces a multi-line response. Any extension MUST follow this 386 principle as well, but note that, for historical reasons, the 211 387 response code is an exception to this. In all other cases, the client 388 MUST only use the status indicator itself to determine the nature of 389 the response. The exact response codes that can be returned by any 390 given command are detailed in the description of that command. 392 Parameters MUST be separated from the numeric status indicator and 393 from each other by a single space. All numeric parameters MUST be in 394 base 10 (decimal) format, and MAY have leading zeros. String 395 parameters MUST contain at least one character and MUST NOT contain 396 TAB, LF, CR, or space. The server MAY add any text after the response 397 code or last parameter as appropriate, and the client MUST NOT make 398 decisions based on this text. Such text MUST be separated from the 399 numeric status indicator or the last parameter by at least one space. 401 The server MUST respond to any command with the appropriate generic 402 response (given in Section 3.2.1) if it represents the situation. 403 Otherwise, each recognized command MUST return one of the response 404 codes specifically listed in its description or in an extension. A 405 server MAY provide extensions to this specification, including new 406 commands, new variants or features of existing commands, and other 407 ways of changing the internal state of the server. However, the 408 server MUST NOT produce any other responses to a client that does not 409 invoke any of the additional features. (Therefore a client that 410 restricts itself to this specification will only receive the 411 responses that are listed.) 413 If a client receives an unexpected response, it SHOULD use the first 414 digit of the response to determine the result. For example, an 415 unexpected 2xx should be taken as success and an unexpected 4xx or 416 5xx as failure. 418 Response codes not specified in this document MAY be used for any 419 installation-specific additional commands also not specified. These 420 SHOULD be chosen to fit the pattern of x9x specified above. 422 Neither this document nor any extension registered with IANA (see 423 Section 8) will specify any response codes of the x9x pattern. 424 (Implementers of extensions are accordingly cautioned not to use such 425 responses for extensions that may subsequently be submitted for 426 registration.) 428 3.2.1 Generic Response Codes 430 The server MUST respond to any command with the appropriate one of 431 the following generic responses if it represents the situation. 433 If the command is not recognized, or it is an optional command or 434 extension that is not implemented by the server, the response code 435 500 MUST be returned. 437 If there is a syntax error in the arguments of a recognized command, 438 including the case where more arguments are provided than the command 439 specifies or the command line is longer than the server accepts, the 440 response code 501 MUST be returned. The line MUST NOT be truncated or 441 split and then interpreted. Note that where a command has variants 442 depending on a second keyword (e.g. LIST ACTIVE and LIST NEWSGROUPS), 443 then 501 MUST be used when the requested variant is not implemented 444 but the base command is. 446 If the server experiences an internal fault or problem that means it 447 is unable to carry out the command (for example, a necessary file is 448 missing or a necessary service could not be contacted), the response 449 code 403 MUST be returned. If the server recognises the command but 450 does not provide an optional feature (for example because it does not 451 store the required information), or only handles a subset of 452 legitimate cases (see the HDR command (Section 8.6.1) for an 453 example), the response code 503 MUST be returned. Note that where a 454 command is optional (e.g. LIST ACTIVE.TIMES) and is not provided by a 455 server, this MAY be treated as an unimplemented command (response 456 code 500 or 501) or as a working command where the information is not 457 available (response code 503). 459 If the client is not authorized to use the specified facility when 460 the server is in its current state, then either the response code 480 461 or the response code 502 MUST be returned. The response code 480 462 SHOULD be used if a different command (for example, an extension used 463 to present credentials) might change the server state so that the 464 command is permitted. The response code 502 SHOULD be used if the 465 server wishes to indicate that it is necessary to terminate the 466 connection and start a new one with the appropriate authority before 467 the command can be used. Since it is not always possible to clearly 468 distinguish these two cases, a server MAY issue either of these 469 response codes for either case. (Note that the server MUST NOT close 470 the TCP connection immediately after a 502 response except at the 471 initial connection (Section 5.1) and with the MODE READER (Section 472 5.2) command.) 474 OUTSTANDING ISSUE 476 This isn't a complete solution to the 480 issue; what about the 477 TLS extension, which uses 483 to mean "you need encryption". 478 Should 480 be used for other than "you need authentication"? What 479 code should be used to mean "can't do AUTH until after MODE 480 READER"? 482 Do we need a more generic mechanism for "you must invoke extension 483 X to do Y"? 485 The best proposal made so far is that all 48x codes, if returned 486 from an existing command, mean "unavailable unless some 487 authentication or privacy extension is invoked". Does this tie in 488 with the issue of permitting existing commands not listed in an 489 extension? 491 I asked if anyone used 48x with *existing commands* to mean other 492 than "you are missing a privacy or authentication extension". 493 Effectively the answer is "no". 495 If the server has to terminate the connection for some reason, it 496 MUST give a 400 response code to the next command and then 497 immediately close the TCP connection. 499 With the exception of mandatory commands and the 500 response, the 500 client MUST be prepared to receive any of these responses for any 501 command. 503 3.2.1.1 Examples 505 Example of an unknown command: 507 [C] MAIL 508 [S] 500 Unknown command 510 Example of an unsupported extension: 512 [C] LIST EXTENSIONS 513 [S] 202 Extensions supported: 514 [S] LISTGROUP 515 [S] . 516 [C] OVER 517 [S] 500 Unknown command 519 Example of an unsupported variant: 521 [C] MODE POSTER 522 [S] 501 Unknown MODE option 524 Example of a syntax error: 526 [C] ARTICLE a.message.id@no.angle.brackets 527 [S] 501 Syntax error 529 Example of an overlong command line: 531 [C] HEAD 53 54 55 532 [S] 501 Too many arguments 534 Example of a bad wildmat: 536 [C] LIST ACTIVE u[ks].* 537 [S] 501 Syntax error 539 Example of an attempt to access a restricted facility: 541 [C] GROUP secret.group 542 [S] 480 Permission denied 544 followed by a successful attempt following authentication: 546 [C] XSECRET fred flintstone 547 [S] 290 Password for fred accepted. 548 [C] GROUP secret.group 549 [S] 211 5 1 20 secret.group selected 551 Example of an attempt to access a facility not available to this 552 connection: 554 [C] MODE READER 555 [S] 200 Reader mode, posting permitted 556 [C] IHAVE 557 [S] 502 Permission denied 559 Example of a temporary failure: 561 [C] GROUP archive.local 562 [S] 403 Archive server temporarily offline 564 Example of the server needing to close down immediately: 566 [C] ARTICLE 123 567 [S] 400 Power supply failed, running on UPS 568 [Server closes connection.] 570 3.3 Pipelining 572 NNTP is designed to operate over a reliable bi-directional connection 573 such as TCP. Therefore, if a command does not depend on the response 574 to the previous one, it should not matter if it is sent before that 575 response is received. Doing this is called "pipelining". However, 576 certain server implementations throw away all text received from the 577 client following certain commands before sending their response. If 578 this happens, pipelining will be affected because one or more 579 commands will have been ignored or misinterpreted, and the client 580 will be matching the wrong responses to each command. Since there are 581 significant benefits to pipelining, but also circumstances where it 582 is reasonable or common for servers to behave in the above manner, 583 this document puts certain requirements on both clients and servers. 585 Except where stated otherwise, a client MAY use pipelining. That is, 586 it may send a command before receiving the response for the previous 587 command. The server MUST allow pipelining and MUST NOT throw away any 588 text received after a command. Irrespective of whether or not 589 pipelining is used, the server MUST process commands in the order 590 they are sent. 592 If the specific description of a command says it "MUST NOT be 593 pipelined", that command MUST end any pipeline of commands. That is, 594 the client MUST NOT send any following command until receiving the 595 CRLF at the end of the response from the command. The server MAY 596 ignore any data received after the command and before the CRLF at the 597 end of the response is sent to the client. 599 The initial connection must not be part of a pipeline; that is, the 600 client MUST NOT send any command until receiving the CRLF at the end 601 of the greeting. 603 If the client uses blocking system calls to send commands, it MUST 604 ensure that the amount of text sent in pipelining does not cause a 605 deadlock between transmission and reception. The amount of text 606 involved will depend on window sizes in the transmission layer, and 607 is typically 4k octets for TCP. 609 3.3.1 Examples 611 Example of correct use of pipelining: 613 [C] GROUP misc.test 614 [C] STAT 615 [C] NEXT 616 [S] 211 1234 3000234 3002322 misc.test 617 [S] 223 3000234 <45223423@example.com> retrieved 618 [S] 223 3000237 <668929@example.org> retrieved 620 Example of incorrect use of pipelining (the MODE READER command may 621 not be pipelined): 623 [C] GROUP misc.test 624 [C] MODE READER 625 [C] DATE 626 [C] NEXT 627 [S] 211 1234 3000234 3002322 misc.test 628 [S] 200 Server ready, posting allowed 630 [S] 223 3000237 <668929@example.org> retrieved 632 The DATE command has been thrown away by the server and so there is 633 no 111 response to match it. 635 3.4 Articles 637 NNTP is intended to transfer articles between clients and servers. 638 For the purposes of this specification, articles are required to 639 conform to the rules in this section and clients and servers MUST 640 correctly process any article received from the other that does so. 641 Note that this requirement applies only to the contents of 642 communications over NNTP; it does not prevent the client or server 643 from subsequently rejecting an article for reasons of local policy. 644 Also see Appendix B for further restrictions on the format of 645 articles in some uses of NNTP. 647 An article consists of two parts: the headers and the body. They are 648 separated by a single empty line, or in other words by two 649 consecutive CRLF pairs (if there is more than one empty line, the 650 second and subsequent ones are part of the body). In order to meet 651 the general requirements of NNTP, an article MUST NOT include the 652 octet NUL, MUST NOT contain the octets LF and CR other than as part 653 of a CRLF pair, and MUST end with a CRLF pair. This specification 654 puts no further restrictions on the body; in particular, it MAY be 655 empty. 657 The headers of an article consist of one or more header lines. Each 658 header line consists of a header name, a colon, a space, the header 659 content, and a CRLF in that order. The name consists of one or more 660 printable US-ASCII characters other than colon and, for the purposes 661 of this specification, is not case sensitive. There MAY be more than 662 one header line with the same name. The content MUST NOT contain CRLF 663 but is otherwise unrestricted; in particular, it MAY be empty. A 664 header may be "folded"; that is, a CRLF pair may be placed before any 665 TAB or space in the line; there MUST still be some other octet 666 between any two CRLF pairs in a header line. (Note that folding means 667 that the header line occupies more than one line when displayed or 668 transmitted; nevertheless it is still referred to as "a" header 669 line.) The presence or absence of folding does not affect the meaning 670 of the header line; that is, the CRLF pairs introduced by folding are 671 not considered part of the header value. Header lines SHOULD NOT be 672 folded before the space after the colon that follows the header name, 673 and should include at least one octet other than %x09 or %x20 between 674 CRLF pairs. However, if an article has been received from elsewhere 675 with one of these, clients and servers MAY transfer it to the other 676 without re-folding it. 678 Each article MUST have a unique message-id; two articles offered by 679 an NNTP server MUST NOT have the same message-id. For the purposes of 680 this specification, message-ids are opaque strings that MUST meet the 681 following requirements: 683 o A message-id MUST begin with "<" and end with ">", and MUST NOT 684 contain the latter except at the end. 686 o A message-id MUST be between 3 and 250 octets in length. 688 o A message-id MUST NOT contain octets other than printable US-ASCII 689 characters. 691 Two message-ids are the same if and only if they consist of the same 692 sequence of octets. 694 This specification does not describe how the message-id of an article 695 is determined. If the server does not have any way to determine a 696 message-id from the article itself, it MUST synthesise one (this 697 specification does not require the article to be changed as a 698 result). 700 4. The WILDMAT format 702 The WILDMAT format described here is based on the version first 703 developed by Rich Salz [SALZ1992], which in turn was derived from the 704 format used in the UNIX "find" command to articulate file names. It 705 was developed to provide a uniform mechanism for matching patterns in 706 the same manner that the UNIX shell matches filenames. 708 4.1 Wildmat syntax 710 A wildmat is described by the following ABNF [RFC2234] syntax (note 711 that this syntax contains ambiguities and special cases described at 712 the end): 714 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 716 wildmat-pattern = 1*wildmat-item 718 wildmat-item = wildmat-exact / wildmat-wild 720 wildmat-exact = %x21-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 721 UTF8-non-ascii ; exclude * , ? [ \ ] 723 wildmat-wild = "*" / "?" 725 UTF8-non-ascii is defined in Section 9. 727 This syntax must be interpreted subject to the following rule: 729 Where a wildmat-pattern is not immediately preceded by "!", it shall 730 not begin with a "!". 732 Note: the characters \ , [ and ] are not allowed in wildmats, while * 733 and ? are always wildcards. This should not be a problem since these 734 characters cannot occur in newsgroup names, which is the only current 735 use of wildmats. Backslash is commonly used to suppress the special 736 meaning of characters while brackets are used to introduce sets. 737 However, these usages are not universal and interpretation of these 738 characters in the context of UTF-8 strings is both potentially 739 complex and differs from existing practice, so they were omitted from 740 this specification. A future extension to this specification may 741 provide semantics for these characters. 743 4.2 Wildmat semantics 745 A wildmat is tested against a string, and either matches or does not 746 match. To do this, each constituent wildmat-pattern is matched 747 against the string and the rightmost pattern that matches is 748 identified. If that wildmat-pattern is not preceded with "!", the 749 whole wildmat matches. If it is preceded by "!", or if no 750 wildmat-pattern matches, the whole wildmat does not match. 752 For example, consider the wildmat "a*,!*b,*c*": 754 the string "aaa" matches because the rightmost match is with "a*" 756 the string "abb" does not match because the rightmost match is 757 with "*b" 759 the string "ccb" matches because the rightmost match is with "*c*" 761 the string "xxx" does not match because no wildmat-pattern matches 763 A wildmat-pattern matches a string if the string can be broken into 764 components, each of which matches the corresponding wildmat-item in 765 the pattern; the matches must be in the same order, and the whole 766 string must be used in the match. The pattern is "anchored"; that is, 767 the first and last characters in the string must match the first and 768 last item respectively (unless that item is an asterisk matching zero 769 characters). 771 A wildmat-exact matches the same character (which may be more than 772 one octet in UTF-8). 774 "?" matches exactly one character (which may be more than one octet). 776 "*" matches zero or more characters. It can match an empty string, 777 but it cannot match a subsequence of a UTF-8 sequence that is not 778 aligned to the character boundaries. 780 4.3 Extensions 782 An NNTP server or extension MAY extend the syntax or semantics of 783 wildmats provided that all wildmats that meet the requirements of 784 Section 4.1 have the meaning ascribed to them by Section 4.2. Future 785 editions of this document may also extend wildmats. 787 4.4 Examples 789 In these examples, $ and @ are used to represent the two octets %xC2 790 and %xA3 respectively; $@ is thus the UTF-8 encoding for the pound 791 sterling symbol, shown as # in the descriptions. 793 Wildmat Description of strings that match 794 abc the one string "abc" 795 abc,def the two strings "abc" and "def" 796 $@ the one character string "#" 797 a* any string that begins with "a" 798 a*b any string that begins with "a" and ends with "b" 799 a*,*b any string that begins with "a" or ends with "b" 800 a*,!*b any string that begins with "a" and does not end with 801 "b" 802 a*,!*b,c* any string that begins with "a" and does not end with 803 "b", and any string that begins with "c" no matter 804 what it ends with 805 a*,c*,!*b any string that begins with "a" or "c" and does not 806 end with "b" 807 ?a* any string with "a" as its second character 808 ??a* any string with "a" as its third character 809 *a? any string with "a" as its penultimate character 810 *a?? any string with "a" as its antepenultimate character 812 5. Session administration commands 814 5.1 Initial Connection 816 5.1.1 Usage 818 Responses 819 200 Service available, posting allowed 820 201 Service available, posting prohibited 821 400 Service temporarily unavailable [1] 822 502 Service permanently unavailable [1] 824 These are the only valid response codes for the initial greeting; 825 the server MUST not return any other generic response code. 827 [1] Following a 400 or 502 response the server MUST immediately close 828 the connection. 830 5.1.2 Description 832 There is no command presented by the client upon initial connection 833 to the server. The server MUST present an appropriate response code 834 as a greeting to the client. This response informs the client whether 835 service is available and whether the client is permitted to post. 837 If the server will accept further commands from the client including 838 POST, the server MUST present a 200 greeting code. If the server will 839 accept further commands from the client, but it is not authorized to 840 post articles using the POST command, the server MUST present a 201 841 greeting code. 843 Otherwise the server MUST present a 400 or 502 greeting code and then 844 immediately close the connection. 502 MUST be used if the client is 845 not permitted under any circumstances to interact with the server and 846 400 otherwise. 848 5.1.3 Examples 850 Example of a normal connection from an authorized client which then 851 terminates the session (see Section 5.4): 853 [Initial TCP connection setup completed.] 854 [S] 200 NNTP Service Ready, posting permitted 855 [C] QUIT 856 [S] 205 NNTP Service exits normally 857 [Server closes connection.] 859 Example of a normal connection from an authorized client that is not 860 permitted to post; it also immediately terminates the session: 862 [Initial TCP connection setup completed.] 863 [S] 201 NNTP Service Ready, posting prohibited 864 [C] QUIT 865 [S] 205 NNTP Service exits normally 866 [Server closes connection.] 868 Example of a normal connection from an unauthorized client: 870 [Initial TCP connection setup completed.] 871 [S] 502 NNTP Service permanently unavailable 872 [Server closes connection.] 874 Example of a connection from a client where the server is unable to 875 provide service: 877 [Initial TCP connection setup completed.] 878 [S] 400 NNTP Service temporarily unavailable 879 [Server closes connection.] 881 5.2 MODE READER 883 5.2.1 Usage 885 This command MUST NOT be pipelined. 887 Syntax 888 MODE READER 890 Responses 891 200 Posting allowed 892 201 Posting prohibited 893 400 Service temporarily unavailable [1] 894 502 Service permanently unavailable [1] 896 [1] Following a 400 or 502 response the server MUST immediately close 897 the connection. 899 5.2.2 Description 901 MODE READER SHOULD be sent by any client that intends to use any 902 command other than IHAVE, HEAD, STAT, LIST ACTIVE, LIST EXTENSIONS, 903 or a command advertised by the server as available via LIST 904 EXTENSIONS. 906 Servers MAY require that this command be issued before any commands 907 other than the above are sent and MAY reject such commands until 908 after a MODE READER command has been sent. Where an extension is only 909 available after a MODE READER command, or where the effects of the 910 extension will change, the LIST EXTENSIONS command MUST produce 911 different results that indicate the change. 913 The server MUST return a response using the same codes as the initial 914 greeting (as described in Section 5.1.1) to indicate its ability to 915 provide reading service to the client. Note that the response need 916 not be the same as the one presented during the initial greeting. 918 Once MODE READER is sent, IHAVE (and any extensions intended for 919 peer-to-peer article transfer) MAY no longer be permitted, even if it 920 were permitted before the MODE READER command. The results of LIST 921 EXTENSIONS MAY be different following a MODE READER command than 922 prior to the issuing of that command. 924 Servers are encouraged to not require this command even though 925 clients SHOULD send it when appropriate. It is present to support 926 some news architectures that switch between modes based on whether a 927 given connection is a peer-to-peer connection with another server or 928 a news reading client. 930 5.2.3 Examples 932 Example of use of the MODE READER command by an authorized client 933 which then terminates the session (see Section 5.4): 935 [C] MODE READER 936 [S] 200 NNTP Service Ready, posting permitted 937 [C] QUIT 938 [S] 205 NNTP Service exits normally 939 [Server closes connection.] 941 Example of use of the MODE READER command by an authorized client 942 that is not permitted to post; it also immediately terminates the 943 session: 945 [C] MODE READER 946 [S] 201 NNTP Service Ready, posting prohibited 947 [C] QUIT 948 [S] 205 NNTP Service exits normally 949 [Server closes connection.] 951 Example of use of MODE READER by a client not authorized to receive 952 service from the server as a news reader: 954 [C] MODE READER 955 [S] 502 NNTP Service permanently unavailable 956 [Server closes connection.] 958 Example of a connection from any client where the server is 959 temporarily unable to provide news reader service: 961 [C] MODE READER 962 [S] 400 NNTP Service temporarily unavailable 963 [Server closes connection.] 965 5.3 LIST EXTENSIONS 967 5.3.1 Usage 969 This command is optional. 971 This command MUST NOT be pipelined. 973 Syntax 974 LIST EXTENSIONS 976 Responses 977 202 Extension list follows (multiline) 978 402 Server has no extensions 980 5.3.2 Description 982 The LIST EXTENSIONS command allows a client to determine which 983 extensions are supported by the server at any given time. See Section 984 8 for further discussion of extensions. 986 This command MUST be implemented by any server that implements any 987 extensions defined in this document or any other extension in the 988 IANA registry, and is optional otherwise. 990 This command MAY be issued at anytime during a session. It is not 991 required that the client issues this command before attempting to 992 make use of any extension. The response generated by this command MAY 993 change during a session because of other state information (which in 994 turn may be changed by the effects of other commands). An NNTP client 995 MUST NOT cache (for use in another session) any information returned 996 if the LIST EXTENSIONS command succeeds. That is, an NNTP client is 997 only able to get the current and correct information concerning 998 available extensions at any point during a session by issuing a LIST 999 EXTENSIONS command at that point of that session and processing the 1000 response. 1002 The list of extensions is returned as a multi-line response following 1003 the 202 response code. Each extension is listed on a separate line; 1004 the line MUST begin with an extension-label and optionally one or 1005 more parameters (separated by single spaces). The extension-label and 1006 the meaning of the parameters are specified as part of the definition 1007 of the extension. The extension-label is a string of 1 to 12 US-ASCII 1008 letters and MUST be in uppercase. Parameters are strings of 1 or more 1009 printable UTF-8 characters (that is, either printable US-ASCII 1010 characters or any UTF-8 sequence outside the US-ASCII range, but not 1011 space or TAB). 1013 The server MUST NOT list the same extension twice in the response, 1014 and MUST list all supported extensions. The order in which the 1015 extensions are listed is not significant. The server need not even 1016 consistently return the same order. If the server does not support 1017 any extensions, it MUST return an empty list. The 402 response code 1018 is documented for historic reasons only; clients SHOULD handle it 1019 gracefully, but servers MUST NOT generate it. 1021 Following a generic failure response, such as 403, an extension might 1022 still be available, and the client MAY attempt to use it. 1024 5.3.3 Examples 1026 Example of a successful response: 1028 [C] LIST EXTENSIONS 1029 [S] 202 Extensions supported: 1030 [S] OVER 1031 [S] HDR 1032 [S] LISTGROUP 1033 [S] . 1035 The particular extensions shown here are simply examples of what 1036 might be defined in other places, and no particular meaning should be 1037 attributed to them. 1039 Example where no extensions are available: 1041 [C] LIST EXTENSIONS 1042 [S] 202 Extensions supported: 1043 [S] . 1045 Example from a non-conforming server which indicates "no extensions 1046 available" using the 402 response code: 1048 [C] LIST EXTENSIONS 1049 [S] 402 Server has no extensions 1051 5.4 QUIT 1053 5.4.1 Usage 1055 Syntax 1056 QUIT 1058 Responses 1059 205 Connection closing 1061 5.4.2 Description 1063 The client uses the QUIT command to terminate the session. The server 1064 MUST acknowledge the QUIT command and then close the connection to 1065 the client. This is the preferred method for a client to indicate 1066 that it has finished all its transactions with the NNTP server. 1068 If a client simply disconnects (or the connection times out or some 1069 other fault occurs), the server MUST gracefully cease its attempts to 1070 service the client, disconnecting from its end if necessary. 1072 5.4.3 Examples 1074 [C] QUIT 1075 [S] 205 closing connection 1076 [Server closes connection.] 1078 6. Article posting and retrieval 1080 News reading clients have available a variety of mechanisms to 1081 retrieve articles via NNTP. The news articles are stored and indexed 1082 using three types of keys. One key is the message-id of an article. 1083 Another key is composed of the newsgroup name and the article number 1084 within that newsgroup. That key MUST be unique to a particular server 1085 (there will be only one article with that number within a particular 1086 newsgroup), but is not required to be globally unique. Additionally, 1087 because the same article can be cross-posted to multiple newsgroups, 1088 there may be multiple keys that point to the same article on the same 1089 server. The final key is the arrival timestamp, giving the time that 1090 the article arrived at the server. 1092 The server MUST ensure that article numbers are issued in order of 1093 arrival timestamp; that is, articles arriving later MUST have higher 1094 numbers than those that arrive earlier. The server SHOULD allocate 1095 the next sequential unused number to each new article. 1097 Article numbers MUST lie between 1 and 4,294,967,295 inclusive. The 1098 client and server SHOULD NOT use leading zeroes in specifying article 1099 numbers, and MUST NOT use more than 16 digits. In some situations, 1100 the value zero replaces an article number to show some special 1101 situation. 1103 6.1 Group and article selection 1105 The following commands are used to set the "current selected 1106 newsgroup" and the "current article number", which are used by 1107 various commands. At the start of an NNTP session, both of these 1108 values are set to the special value "invalid". 1110 6.1.1 GROUP 1112 6.1.1.1 Usage 1114 Syntax 1115 GROUP group 1117 Responses 1118 211 number low high group Group successfully selected 1119 411 No such newsgroup 1121 Parameters 1122 group = name of newsgroup 1123 number = estimated number of articles in the group 1124 low = reported low water mark 1125 high = reported high water mark 1127 6.1.1.2 Description 1129 The required parameter is the name of the newsgroup to be selected 1130 (e.g. "news.software.b"). A list of valid newsgroups may be obtained 1131 by using the LIST ACTIVE command (see Section 7.6.1). 1133 The successful selection response will return the article numbers of 1134 the first and last articles in the group at the moment of selection 1135 (these numbers are referred to as the "reported low water mark" and 1136 the "reported high water mark"), and an estimate of the number of 1137 articles in the group currently available. 1139 If the group is not empty, the estimate MUST be at least the actual 1140 number of articles available, and MUST be no greater than one more 1141 than the difference between the reported low and high water marks. 1142 (Some implementations will actually count the number of articles 1143 currently stored. Others will just subtract the low water mark from 1144 the high water mark and add one to get an estimate.) 1146 If the group is empty, one of the following three situations will 1147 occur. Clients MUST accept all three cases; servers MUST NOT 1148 represent an empty group in any other way. 1150 o The high water mark will be one less than the low water mark, and 1151 the estimated article count will be zero. Servers SHOULD use this 1152 method to show an empty group. This is the only time that the high 1153 water mark can be less than the low water mark. 1155 o All three numbers will be zero. 1157 o The high water mark is greater than or equal to the low water 1158 mark. The estimated article count might be zero or non-zero; if 1159 non-zero, the same requirements apply as for a non-empty group. 1161 The set of articles in a group may change after the GROUP command is 1162 carried out. That is: 1164 o articles may be removed from the group 1166 o articles may be reinstated in the group with the same article 1167 number, but those articles MUST have numbers no less than the 1168 reported low water mark (note that this is a reinstatement of the 1169 previous article, not a new article reusing the number) 1171 o new articles may be added with article numbers greater than the 1172 reported high water mark (if an article that was the one with the 1173 highest number has been removed, the next new article will not 1174 have the number one greater than the reported high water mark) 1176 Except when the group is empty and all three numbers are zero, 1177 whenever a subsequent GROUP command for the same newsgroup is issued, 1178 either by the same client or a different client, the reported low 1179 water mark in the response MUST be no less than that in any previous 1180 response for that newsgroup sent to any client. The client may make 1181 use of the low water mark to remove all remembered information about 1182 articles with lower numbers, as these will never recur. This includes 1183 the situation when the high water mark is one less than the low water 1184 mark. No similar assumption can be made about the high water mark, as 1185 this can decrease if an article is removed, and then increase again 1186 if it is reinstated or if new articles arrive. 1188 When a valid group is selected by means of this command, the current 1189 selected newsgroup MUST be set to that group and the current article 1190 number MUST be set to the first article in the group. If an empty 1191 newsgroup is selected, the current article pointer is made invalid. 1192 If an invalid group is specified, the current selected newsgroup and 1193 current article number MUST NOT be changed. 1195 The GROUP command (or the LISTGROUP command, if implemented) MUST be 1196 used by a client and a successful response received before any other 1197 command is used that depends on the value of the current selected 1198 newsgroup or current article number. 1200 If the group specified is not available on the server, a 411 response 1201 MUST be returned. 1203 6.1.1.3 Examples 1205 Example for a group known to the server: 1207 [C] GROUP misc.test 1208 [S] 211 1234 3000234 3002322 misc.test 1210 Example for a group unknown to the server: 1212 [C] GROUP example.is.sob.bradner.or.barber 1213 [S] 411 example.is.sob.bradner.or.barber is unknown 1215 Example of an empty group using the preferred response: 1217 [C] GROUP example.currently.empty.newsgroup 1218 [S] 211 0 4000 3999 example.currently.empty.newsgroup 1220 Example of an empty group using an alternative response: 1222 [C] GROUP example.currently.empty.newsgroup 1223 [S] 211 0 0 0 example.currently.empty.newsgroup 1225 Example of an empty group using a different alternative response: 1227 [C] GROUP example.currently.empty.newsgroup 1228 [S] 211 0 4000 4321 example.currently.empty.newsgroup 1230 6.1.2 LAST 1232 6.1.2.1 Usage 1234 Syntax 1235 LAST 1237 Responses 1238 223 n message-id Article found 1239 412 No newsgroup selected 1240 420 Current article number is invalid 1241 422 No previous article in this group 1243 Parameters 1244 n = article number 1245 message-id = article message-id 1247 6.1.2.2 Description 1249 If the current selected newsgroup is valid, the current article 1250 number MUST be set to the previous article in that newsgroup (that 1251 is, the highest existing article number less than the current article 1252 number). If successful, a response indicating the new current article 1253 number and the message-id of that article MUST be returned. No 1254 article text is sent in response to this command. 1256 There MAY be no previous article in the group, although the current 1257 article number is not the reported low water mark. There MUST NOT be 1258 a previous article when the current article number is the reported 1259 low water mark. 1261 Because articles can be removed and added, the results of multiple 1262 LAST and NEXT commands MAY not be consistent over the life of a 1263 particular NNTP session. 1265 If the current article number is already the first article of the 1266 newsgroup, a 422 response MUST be returned. If the current article 1267 number is invalid, a 420 response MUST be returned. If the current 1268 selected newsgroup is invalid, a 412 response MUST be returned. In 1269 all three cases the current selected newsgroup and current article 1270 number MUST NOT be altered. 1272 6.1.2.3 Examples 1274 Example of a successful article retrieval using LAST: 1276 [C] GROUP misc.test 1277 [S] 211 1234 3000234 3002322 misc.test 1278 [C] NEXT 1279 [S] 223 3000237 <668929@example.org> retrieved 1280 [C] LAST 1281 [S] 223 3000234 <45223423@example.com> retrieved 1283 Example of an attempt to retrieve an article without having selected 1284 a group (via the GROUP command) first: 1286 [Assumes current selected newsgroup is invalid.] 1287 [C] LAST 1288 [S] 412 no newsgroup selected 1290 Example of an attempt to retrieve an article using the LAST command 1291 when the current article number is that of the first article in the 1292 group: 1294 [C] GROUP misc.test 1295 [S] 211 1234 3000234 3002322 misc.test 1296 [C] LAST 1297 [S] 422 No previous article to retrieve 1299 Example of an attempt to retrieve an article using the LAST command 1300 when the current selected newsgroup is empty: 1302 [C] GROUP example.empty.newsgroup 1303 [S] 211 0 0 0 example.empty.newsgroup 1304 [C] LAST 1305 [S] 420 No current article selected 1307 6.1.3 NEXT 1309 6.1.3.1 Usage 1311 Syntax 1312 NEXT 1314 Responses 1315 223 n message-id Article found 1316 412 No newsgroup selected 1317 420 Current article number is invalid 1318 421 No next article in this group 1320 Parameters 1321 n = article number 1322 message-id = article message-id 1324 6.1.3.2 Description 1326 If the current selected newsgroup is valid, the current article 1327 number MUST be set to the next article in that newsgroup (that is, 1328 the lowest existing article number greater than the current article 1329 number). If successful, a response indicating the new current article 1330 number and the message-id of that article MUST be returned. No 1331 article text is sent in response to this command. 1333 If the current article number is already the last article of the 1334 newsgroup, a 421 response MUST be returned. In all other aspects 1335 (apart, of course, from the lack of 422 response) this command is 1336 identical to the LAST command (Section 6.1.2). 1338 6.1.3.3 Examples 1340 Example of a successful article retrieval using NEXT: 1342 [C] GROUP misc.test 1343 [S] 211 1234 3000234 3002322 misc.test 1344 [C] NEXT 1345 [S] 223 3000237 <668929@example.org> retrieved 1347 Example of an attempt to retrieve an article without having selected 1348 a group (via the GROUP command) first: 1350 [Assumes current selected newsgroup is invalid.] 1351 [C] NEXT 1352 [S] 412 no newsgroup selected 1354 Example of an attempt to retrieve an article using the NEXT command 1355 when the current article number is that of the last article in the 1356 group: 1358 [C] GROUP misc.test 1359 [S] 211 1234 3000234 3002322 misc.test 1360 [C] STAT 3002322 1361 [S] 223 3002322 <411@example.net> retrieved 1362 [C] NEXT 1363 [S] 421 No next article to retrieve 1365 Example of an attempt to retrieve an article using the NEXT command 1366 when the current selected newsgroup is empty: 1368 [C] GROUP example.empty.newsgroup 1369 [S] 211 0 0 0 example.empty.newsgroup 1370 [C] NEXT 1371 [S] 420 No current article selected 1373 6.2 Retrieval of articles and article sections 1375 The ARTICLE, BODY, HEAD, and STAT commands are very similar. They 1376 differ only in the parts of the article that are presented to the 1377 client and in the successful response code. The ARTICLE command is 1378 described here in full, while the other commands are described in 1379 terms of the differences. As specified in Section 3.4, an article 1380 consists of two parts: the article headers and the article body. When 1381 responding to one of these commands, the server MUST present the 1382 entire article or appropriate part and MUST NOT attempt to alter or 1383 translate it in any way. 1385 6.2.1 ARTICLE 1387 6.2.1.1 Usage 1389 Syntax 1390 ARTICLE message-id 1391 ARTICLE [number] 1393 Responses 1395 First form (message-id specified) 1396 220 0 message-id Article follows (multiline) 1397 430 No article found with that message-id 1399 Second form (optional article number specified) 1400 220 n message-id Article follows (multiline) 1401 412 No newsgroup selected 1402 420 Current article number is invalid [1] 1403 423 No such article in this newsgroup 1405 Parameters 1406 number = Requested article number 1407 n = Returned article number 1408 message-id = Article message-id 1410 [1] The 420 response can only occur if no article number has been 1411 specified. 1413 6.2.1.2 Description 1415 The ARTICLE command selects an article based on the arguments and 1416 presents the entire article (that is, the headers, an empty line, and 1417 the body in that order). The command has two forms. 1419 In the first form, a message-id is specified and the server presents 1420 the article with that message-id. In this case, the server MUST NOT 1421 alter the current selected newsgroup or current article number. This 1422 is both to facilitate the presentation of articles that may be 1423 referenced within another article being read, and because of the 1424 semantic difficulties of determining the proper sequence and 1425 membership of an article that may have been crossposted to more than 1426 one newsgroup. 1428 In the response, the article number is replaced with zero (that is, 1429 the server is not required to determine whether the article is in the 1430 current group or what article number(s) it has). 1432 In the second form, an article number may be specified. If so, and if 1433 there is an article with that number in the currently selected 1434 newsgroup, the server MUST set the current article number to that 1435 number. 1437 Then, whether or not a number was specified, the article indicated by 1438 the current article number is presented to the client. 1440 Note that a previously valid article number MAY become invalid if the 1441 article has been removed. A previously invalid article number MAY 1442 become valid if the article has been reinstated, but such an article 1443 number MUST be no less than the reported low water mark for that 1444 group. 1446 The server MUST NOT change the current selected newsgroup as a result 1447 of this command. The server MUST NOT change the current article 1448 number except when an article number argument was provided and the 1449 article exists; in particular, it MUST NOT change it following an 1450 unsuccessful response. 1452 Since the message-id is unique for each article, it may be used by a 1453 client to skip duplicate displays of articles that have been posted 1454 more than once, or to more than one newsgroup. 1456 The article is returned as a multi-line response following the 220 1457 response code. 1459 If the argument is a message-id and no such article exists, a 430 1460 response MUST be returned. If the current article number is invalid, 1461 a 420 response MUST be returned. If there is no article with the 1462 specified number, a 423 response MUST be returned. If the current 1463 selected newsgroup is invalid, a 412 response MUST be returned. 1465 6.2.1.3 Examples 1467 Example of a successful retrieval of an article (using no article 1468 number): 1470 [C] GROUP misc.test 1471 [S] 211 1234 3000234 3002322 misc.test 1472 [C] ARTICLE 1473 [S] 220 3000234 <45223423@example.com> 1474 [S] Path: pathost!demo!whitehouse!not-for-mail 1475 [S] From: "Demo User" 1476 [S] Newsgroups: misc.test 1477 [S] Subject: I am just a test article 1478 [S] Date: 6 Oct 1998 04:38:40 -0500 1479 [S] Organization: An Example Net, Uncertain, Texas 1480 [S] Message-ID: <411@example.net> 1481 [S] 1482 [S] This is just a test article. 1483 [S] . 1485 Example of a successful retrieval of an article by message-id: 1487 [C] ARTICLE <45223423@example.com> 1488 [S] 220 0 <45223423@example.com> 1489 [S] Path: pathost!demo!whitehouse!not-for-mail 1490 [S] From: "Demo User" 1491 [S] Newsgroups: misc.test 1492 [S] Subject: I am just a test article 1493 [S] Date: 6 Oct 1998 04:38:40 -0500 1494 [S] Organization: An Example Net, Uncertain, Texas 1495 [S] Message-ID: <411@example.net> 1496 [S] 1497 [S] This is just a test article. 1498 [S] . 1500 Example of an unsuccessful retrieval of an article by message-id: 1502 [C] ARTICLE 1503 [S] 430 No Such Article Found 1505 Example of an unsuccessful retrieval of an article by number: 1507 [C] GROUP misc.test 1508 [S] 211 1234 3000234 3002322 news.groups 1510 [C] ARTICLE 300256 1511 [S] 423 No such article number in this group 1513 Example of an unsuccessful retrieval of an article by number because 1514 no newsgroup was selected first: 1516 [Assumes current selected newsgroup is invalid.] 1517 [C] ARTICLE 300256 1518 [S] 412 No newsgroup selected 1520 Example of an attempt to retrieve an article when the current 1521 selected newsgroup is empty: 1523 [C] GROUP example.empty.newsgroup 1524 [S] 211 0 0 0 example.empty.newsgroup 1525 [C] ARTICLE 1526 [S] 420 No current article selected 1528 6.2.2 HEAD 1530 6.2.2.1 Usage 1532 Syntax 1533 HEAD message-id 1534 HEAD [number] 1536 Responses 1538 First form (message-id specified) 1539 221 0 message-id Headers follow (multiline) 1540 430 No article found with that message-id 1542 Second form (optional article number specified) 1543 221 n message-id Headers follow (multiline) 1544 412 No newsgroup selected 1545 420 Current article number is invalid [1] 1546 423 No such article in this newsgroup 1548 Parameters 1549 number = Requested article number 1550 n = Returned article number 1551 message-id = Article message-id 1553 [1] The 420 response can only occur if no article number has been 1554 specified. 1556 6.2.2.2 Description 1558 The HEAD command behaves identically to the ARTICLE command except 1559 that, if the article exists, the response code is 221 instead of 220 1560 and only the headers are presented (the empty line separating the 1561 headers and body MUST NOT be included). 1563 6.2.2.3 Examples 1565 Example of a successful retrieval of the headers of an article (using 1566 no article number): 1568 [C] GROUP misc.test 1569 [S] 211 1234 3000234 3002322 misc.test 1570 [C] HEAD 1571 [S] 221 3000234 <45223423@example.com> 1572 [S] Path: pathost!demo!whitehouse!not-for-mail 1573 [S] From: "Demo User" 1574 [S] Newsgroups: misc.test 1575 [S] Subject: I am just a test article 1576 [S] Date: 6 Oct 1998 04:38:40 -0500 1577 [S] Organization: An Example Net, Uncertain, Texas 1578 [S] Message-ID: <411@example.net> 1579 [S] . 1581 Example of a successful retrieval of the headers of an article by 1582 message-id: 1584 [C] HEAD <45223423@example.com> 1585 [S] 221 0 <45223423@example.com> 1586 [S] Path: pathost!demo!whitehouse!not-for-mail 1587 [S] From: "Demo User" 1588 [S] Newsgroups: misc.test 1589 [S] Subject: I am just a test article 1590 [S] Date: 6 Oct 1998 04:38:40 -0500 1591 [S] Organization: An Example Net, Uncertain, Texas 1592 [S] Message-ID: <411@example.net> 1593 [S] . 1595 Example of an unsuccessful retrieval of the headers of an article by 1596 message-id: 1598 [C] HEAD 1599 [S] 430 No Such Article Found 1601 Example of an unsuccessful retrieval of the headers of an article by 1602 number: 1604 [C] GROUP misc.test 1605 [S] 211 1234 3000234 3002322 misc.test 1606 [C] HEAD 300256 1607 [S] 423 No such article number in this group 1609 Example of an unsuccessful retrieval the headers of an article by 1610 number because no newsgroup was selected first: 1612 [Assumes current selected newsgroup is invalid.] 1613 [C] HEAD 300256 1614 [S] 412 No newsgroup selected 1616 Example of an attempt to retrieve the headers of an article when the 1617 current selected newsgroup is empty: 1619 [C] GROUP example.empty.newsgroup 1620 [S] 211 0 0 0 example.empty.newsgroup 1621 [C] HEAD 1622 [S] 420 No current article selected 1624 6.2.3 BODY 1626 6.2.3.1 Usage 1628 Syntax 1629 BODY message-id 1630 BODY [number] 1632 Responses 1634 First form (message-id specified) 1635 222 0 message-id Body follows (multiline) 1636 430 No article found with that message-id 1638 Second form (optional article number specified) 1639 222 n message-id Body follows (multiline) 1640 412 No newsgroup selected 1641 420 Current article number is invalid [1] 1642 423 No such article in this newsgroup 1644 Parameters 1645 number = Requested article number 1646 n = Returned article number 1647 message-id = Article message-id 1649 [1] The 420 response can only occur if no article number has been 1650 specified. 1652 6.2.3.2 Description 1654 The BODY command behaves identically to the ARTICLE command except 1655 that, if the article exists, the response code is 222 instead of 220 1656 and only the body is presented (the empty line separating the headers 1657 and body MUST NOT be included). 1659 6.2.3.3 Examples 1661 Example of a successful retrieval of the body of an article (using no 1662 article number): 1664 [C] GROUP misc.test 1665 [S] 211 1234 3000234 3002322 misc.test 1666 [C] BODY 1667 [S] 222 3000234 <45223423@example.com> 1668 [S] This is just a test article. 1669 [S] . 1671 Example of a successful retrieval of the body of an article by 1672 message-id: 1674 [C] BODY <45223423@example.com> 1675 [S] 222 0 <45223423@example.com> 1676 [S] This is just a test article. 1677 [S] . 1679 Example of an unsuccessful retrieval of the body of an article by 1680 message-id: 1682 [C] BODY 1683 [S] 430 No Such Article Found 1685 Example of an unsuccessful retrieval of the body of an article by 1686 number: 1688 [C] GROUP misc.test 1689 [S] 211 1234 3000234 3002322 misc.test 1690 [C] BODY 300256 1691 [S] 423 No such article number in this group 1693 Example of an unsuccessful retrieval of the body of an article by 1694 number because no newsgroup was selected first: 1696 [Assumes current selected newsgroup is invalid.] 1697 [C] BODY 300256 1698 [S] 412 No newsgroup selected 1700 Example of an attempt to retrieve the body of an article when the 1701 current selected newsgroup is empty: 1703 [C] GROUP example.empty.newsgroup 1704 [S] 211 0 0 0 example.empty.newsgroup 1705 [C] BODY 1706 [S] 420 No current article selected 1708 6.2.4 STAT 1710 6.2.4.1 Usage 1712 Syntax 1713 STAT message-id 1714 STAT [number] 1716 Responses 1718 First form (message-id specified) 1719 223 0 message-id Article exists 1720 430 No article found with that message-id 1722 Second form (optional article number specified) 1723 223 n message-id Article exists 1724 412 No newsgroup selected 1725 420 Current article number is invalid [1] 1726 423 No such article in this newsgroup 1728 Parameters 1729 number = Requested article number 1730 n = Returned article number 1731 message-id = Article message-id 1733 [1] The 420 response can only occur if no article number has been 1734 specified. 1736 6.2.4.2 Description 1738 The STAT command behaves identically to the ARTICLE command except 1739 that, if the article exists, it is NOT presented to the client and 1740 the response code is 223 instead of 220. Note that the response is 1741 NOT multi-line. 1743 This command allows the client to determine whether an article 1744 exists, and in the second form what its message-id is, without having 1745 to process an arbitrary amount of text. 1747 6.2.4.3 Examples 1749 Example of STAT on an existing article (using no article number): 1751 [C] GROUP misc.test 1752 [S] 211 1234 3000234 3002322 misc.test 1753 [C] STAT 1754 [S] 223 3000234 <45223423@example.com> 1756 Example of a STAT of an existing article by message-id: 1758 [C] STAT <45223423@example.com> 1759 [S] 223 0 <45223423@example.com> 1761 Example of an STAT of an article not on the server by message-id: 1763 [C] STAT 1764 [S] 430 No Such Article Found 1766 Example of STAT of an article not in the server by number: 1768 [C] GROUP misc.test 1769 [S] 211 1234 3000234 3002322 misc.test 1770 [C] STAT 300256 1771 [S] 423 No such article number in this group 1773 Example of STAT of an article by number when no newsgroup was 1774 selected first: 1776 [Assumes current selected newsgroup is invalid.] 1777 [C] STAT 300256 1778 [S] 412 No newsgroup selected 1780 Example of STAT of an article when the current selected newsgroup is 1781 empty: 1783 [C] GROUP example.empty.newsgroup 1784 [S] 211 0 0 0 example.empty.newsgroup 1785 [C] STAT 1786 [S] 420 No current article selected 1788 6.3 Article posting 1790 Article posting is done in one of two modes: individual article 1791 posting from news reading clients using POST, and article transfer 1792 from other news servers using IHAVE. 1794 6.3.1 POST 1796 6.3.1.1 Usage 1798 This command MUST NOT be pipelined. 1800 Syntax 1801 POST 1803 Responses 1805 Initial responses 1806 340 Send article to be posted 1807 440 Posting not permitted 1809 Subsequent responses 1810 240 Article received OK 1811 441 Posting failed 1813 6.3.1.2 Description 1815 If posting is allowed, a 340 response MUST be returned to indicate 1816 that the article to be posted should be sent. If posting is 1817 prohibited for some installation-dependent reason, a 440 response 1818 MUST be returned. 1820 If posting is permitted, the article MUST be in the format specified 1821 in Section 3.4 and MUST be sent by the client to the server in the 1822 manner specified in (Section 3.1) for multi-line responses (except 1823 that there is no initial line containing a response code). Thus a 1824 single dot (".") on a line indicates the end of the text, and lines 1825 starting with a dot in the original text have that dot doubled during 1826 transmission. 1828 Following the presentation of the termination sequence by the client, 1829 the server MUST return a response indicating success or failure of 1830 the article transfer. Note that response codes 340 and 440 are used 1831 in direct response to the POST command. Others are returned following 1832 the sending of the article. 1834 A response of 240 SHOULD indicate that, barring unforseen server 1835 errors, the posted article will be made available on the server and/ 1836 or transferred to other servers as appropriate, possibly following 1837 further processing. In other words, articles not wanted by the server 1838 SHOULD be rejected with a 441 response and not accepted and silently 1839 discarded. However, the client SHOULD NOT assume that the article has 1840 been successfully transferred unless it receives an affirmative 1841 response from the server, and SHOULD NOT assume that it is being made 1842 available to other clients without explicitly checking (for example 1843 using the STAT command). 1845 If the session is interrupted before the response is received, it is 1846 possible that an affirmative response was sent but has been lost. 1847 Therefore, in any subsequent session, the client SHOULD either check 1848 whether the article was successfully posted before resending or 1849 ensure that the server will allocate the same message-id to the new 1850 attempt (see Appendix B.2) - the latter approach is preferred since 1851 the article might not have been made available for reading yet (for 1852 example, it may have to go through a moderation process). 1854 6.3.1.3 Examples 1856 Example of a successful posting: 1858 [C] POST 1859 [S] 340 Input article; end with . 1860 [C] From: "Demo User" 1861 [C] Newsgroups: misc.test 1862 [C] Subject: I am just a test article 1863 [C] Organization: An Example Net 1864 [C] 1865 [C] This is just a test article. 1866 [C] . 1867 [S] 240 Article received OK 1869 Example of an unsuccessful posting: 1871 [C] POST 1872 [S] 340 Input article; end with . 1873 [C] From: "Demo User" 1874 [C] Newsgroups: misc.test 1875 [C] Subject: I am just a test article 1876 [C] Organization: An Example Net 1877 [C] 1878 [C] This is just a test article. 1879 [C] . 1880 [S] 441 Posting failed 1882 Example of an attempt to post when posting is not allowed: 1884 [C] MODE READER 1885 [S] 201 NNTP Service Ready, posting prohibited 1886 [C] POST 1887 [S] 440 Posting not permitted 1889 6.3.2 IHAVE 1891 6.3.2.1 Usage 1893 This command MUST NOT be pipelined. 1895 Syntax 1896 IHAVE message-id 1898 Responses 1900 Initial responses 1901 335 Send article to be transferred 1902 435 Article not wanted 1903 436 Transfer not possible; try again later 1905 Subsequent responses 1906 235 Article transferred OK 1907 436 Transfer failed; try again later 1908 437 Transfer rejected; do not retry 1910 Parameters 1911 message-id = Article message-id 1913 6.3.2.2 Description 1915 The IHAVE command informs the server that the client has an article 1916 with the specified message-id. If the server desires a copy of that 1917 article a 335 response MUST be returned, instructing the client to 1918 send the entire article. If the server does not want the article (if, 1919 for example, the server already has a copy of it), a 435 response 1920 MUST be returned, indicating that the article is not wanted. Finally, 1921 if the article isn't wanted immediately but the client should retry 1922 later if possible (if, for example, another client is in the process 1923 of sending the same article to the server), a 436 response MUST be 1924 returned. 1926 If transmission of the article is requested, the client MUST send the 1927 entire article, including headers and body, in the format defined 1928 above (Section 3.1) for multi-line responses (except that there is no 1929 initial line containing a response code). Thus a single dot (".") on 1930 a line indicates the end of the text, and lines starting with a dot 1931 in the original text have that dot doubled during transmission. The 1932 server MUST return either a 235 response, indicating that the article 1933 was successfully transferred, a 436 response, indicating that the 1934 transfer failed but should be tried again later, or a 437 response, 1935 indicating that the article was rejected. 1937 This function differs from the POST command in that it is intended 1938 for use in transferring already-posted articles between hosts. It 1939 SHOULD NOT be used when the client is a personal news reading 1940 program, since use of this command indicates that the article has 1941 already been posted at another site and is simply being forwarded 1942 from another host. However, despite this, the server MAY elect not to 1943 post or forward the article if, after further examination of the 1944 article, it deems it inappropriate to do so. Reasons for such 1945 subsequent rejection of an article may include such problems as 1946 inappropriate newsgroups or distributions, disc space limitations, 1947 article lengths, garbled headers, and the like. These are typically 1948 restrictions enforced by the server host's news software and not 1949 necessarily the NNTP server itself. 1951 The client SHOULD NOT assume that the article has been successfully 1952 transferred unless it receives an affirmative response from the 1953 server. A lack of response (such as a dropped network connection or a 1954 network timeout) SHOULD be treated the same as a 436 response. 1956 Because some news server software may not be able immediately to 1957 determine whether or not an article is suitable for posting or 1958 forwarding, an NNTP server MAY acknowledge the successful transfer of 1959 the article (with a 235 response) but later silently discard it. 1961 6.3.2.3 Examples 1963 Example of successfully sending an article to another site: 1965 [C] IHAVE 1966 [S] 335 Send it; end with . 1967 [C] Path: pathost!demo!somewhere!not-for-mail 1968 [C] From: "Demo User" 1969 [C] Newsgroups: misc.test 1970 [C] Subject: I am just a test article 1971 [C] Date: 6 Oct 1998 04:38:40 -0500 1972 [C] Organization: An Example Com, San Jose, CA 1973 [C] Message-ID: 1974 [C] 1975 [C] This is just a test article. 1976 [C] . 1977 [S] 235 Article transferred OK 1979 Example of sending an article to another site that rejects it. Note 1980 that the message-id in the IHAVE command is not the same as the one 1981 in the article headers; while this is bad practice and SHOULD NOT be 1982 done, it is not forbidden. 1984 [C] IHAVE 1985 [S] 335 Send it; end with . 1986 [C] Path: pathost!demo!somewhere!not-for-mail 1987 [C] From: "Demo User" 1988 [C] Newsgroups: misc.test 1989 [C] Subject: I am just a test article 1990 [C] Date: 6 Oct 1998 04:38:40 -0500 1991 [C] Organization: An Example Com, San Jose, CA 1992 [C] Message-ID: 1993 [C] 1994 [C] This is just a test article. 1995 [C] . 1996 [S] 437 Article rejected; don't send again 1998 Example of sending an article to another site where the transfer 1999 fails: 2001 [C] IHAVE 2002 [S] 335 Send it; end with . 2003 [C] Path: pathost!demo!somewhere!not-for-mail 2004 [C] From: "Demo User" 2005 [C] Newsgroups: misc.test 2006 [C] Subject: I am just a test article 2007 [C] Date: 6 Oct 1998 04:38:40 -0500 2008 [C] Organization: An Example Com, San Jose, CA 2009 [C] Message-ID: 2010 [C] 2011 [C] This is just a test article. 2012 [C] . 2013 [S] 436 Transfer failed 2015 Example of sending an article to a site that already has it: 2017 [C] IHAVE 2018 [S] 435 Duplicate 2020 Example of sending an article to a site that requests the article be 2021 tried again later: 2023 [C] IHAVE 2024 [S] 436 Retry later 2026 7. Information commands 2028 This section lists other commands that may be used at any time 2029 between the beginning of a session and its termination. Using these 2030 commands does not alter any state information, but the response 2031 generated from their use may provide useful information to clients. 2033 7.1 DATE 2035 7.1.1 Usage 2037 Syntax 2038 DATE 2040 Responses 2041 111 yyyymmddhhmmss server date and time 2043 Parameters 2044 yyyymmddHHmmss = Current UTC date and time on server 2046 7.1.2 Description 2048 This command exists to help clients find out the current Coordinated 2049 Universal Time [TF.686-1] from the server's perspective. This command 2050 SHOULD NOT be used as a substitute for NTP [RFC1305] but to provide 2051 information that might be useful when using the NEWNEWS command (see 2052 Section 7.4). A system providing NNTP service SHOULD keep the system 2053 clock as accurate as possible, either with NTP or by some other 2054 method. 2056 The server MUST return a 111 response specifying the date and time on 2057 the server in the form yyyymmddhhmmss. This date and time is in 2058 Coordinated Universal Time. 2060 7.1.3 Examples 2062 [C] DATE 2063 [S] 111 19990623135624 2065 7.2 HELP 2067 7.2.1 Usage 2068 Syntax 2069 HELP 2071 Responses 2072 100 Help text follows (multiline) 2074 7.2.2 Description 2076 This command provides a short summary of commands that are understood 2077 by this implementation of the server. The help text will be presented 2078 as a multiline response following the 100 response code. 2080 This text is not guaranteed to be in any particular format and MUST 2081 NOT be used by clients as a replacement for the LIST EXTENSIONS 2082 command described in Section 5.3 2084 7.2.3 Examples 2086 [C] HELP 2087 [S] 100 Help text follows 2088 [S] This is some help text. There is no specific 2089 [S] formatting requirement for this test, though 2090 [S] it is customary for it to list the valid commands 2091 [S] and give a brief definition of what they do 2092 [S] . 2094 7.3 NEWGROUPS 2096 7.3.1 Usage 2098 Syntax 2099 NEWGROUPS date time [GMT] 2101 Responses 2102 231 List of new newsgroups follows (multiline) 2104 Parameters 2105 date = Date in yymmdd or yyyymmdd format 2106 time = Time in hhmmss format 2108 7.3.2 Description 2110 This command returns a list of newsgroups created on the server since 2111 the specified date and time. The results are in the same format as 2112 the LIST ACTIVE command (see Section 7.6.1). However, they MAY 2113 include groups not available on the server (and so not returned by 2114 LIST ACTIVE) and MAY omit groups for which the creation date is not 2115 available. The results SHOULD be consistent with those of the LIST 2116 ACTIVE.TIMES command (Section 7.6.2), except that if the specified 2117 date and time is earlier than the oldest entry in the latter then the 2118 results of this command may include extra groups. 2120 The date is specified as 6 or 8 digits in the format [xx]yymmdd, 2121 where xx is the first two digits of the year (19-99), yy is the last 2122 two digits of the year (00-99), mm is the month (01-12), and dd is 2123 the day of the month (01-31). Clients SHOULD specify all four digits 2124 of the year. If the first two digits of the year are not specified 2125 (this is supported only for backwards compatibility), the year is to 2126 be taken from the current century if yy is smaller than or equal to 2127 the current year, otherwise the year is from the previous century. 2129 The time is specified as 6 digits in the format hhmmss, where hh is 2130 the hours in the 24-hour clock (00-23), mm is the minutes (00-59), 2131 and ss is the seconds (00-60, to allow for leap seconds). The token 2132 "GMT" specifies that the date and time are given in Coordinated 2133 Universal Time [TF.686-1]; if it is omitted then the date and time 2134 are specified in the server's local timezone. Note that there is no 2135 way using the protocol specified in this document to establish the 2136 server's local timezone. 2138 Note that an empty list is a possible valid response and indicates 2139 that there are no new newsgroups since that date-time. 2141 Clients SHOULD make all queries using Coordinated Universal Time 2142 (i.e. by including the "GMT" parameter) when possible. 2144 7.3.3 Examples 2146 Example where there are new groups: 2148 [C] NEWGROUPS 19990624 000000 GMT 2149 [S] 231 list of new newsgroups follows 2150 [S] alt.fc-writers.recovery 4 1 y 2151 [S] tx.natives.recovery 89 56 y 2152 [S] . 2154 Example where there are no new groups: 2156 [C] NEWGROUPS 19990624 000000 GMT 2157 [S] 231 list of new newsgroups follows 2158 [S] . 2160 7.4 NEWNEWS 2162 7.4.1 Usage 2164 Syntax 2165 NEWNEWS wildmat date time [GMT] 2167 Responses 2168 230 List of new articles follows (multiline) 2170 Parameters 2171 wildmat = Newsgroups of interest 2172 date = Date in yymmdd or yyyymmdd format 2173 time = Time in hhmmss format 2175 7.4.2 Description 2177 This command returns a list of message-ids of articles posted or 2178 received on the server, in the newsgroups whose names match the 2179 wildmat, since the specified date and time. One message-id is sent on 2180 each line; the order of the response has no specific significance and 2181 may vary from response to response in the same session. A message-id 2182 MAY appear more than once; if it does so, it has the same meaning as 2183 if it appeared only once. 2185 Date and time are in the same format as the NEWGROUPS command (see 2186 Section 7.3). 2188 Note that an empty list is a possible valid response and indicates 2189 that there is currently no new news in the relevant groups. 2191 Clients SHOULD make all queries in Coordinated Universal Time (i.e. 2192 by using the "GMT" parameter) when possible. 2194 7.4.3 Examples 2196 Example where there are new articles: 2198 [C] NEWNEWS news.*,sci.* 19990624 000000 GMT 2199 [S] 230 list of new articles by message-id follows 2200 [S] 2201 [S] 2202 [S] . 2204 Example where there are no new articles: 2206 [C] NEWNEWS alt.* 19990624 000000 GMT 2208 [S] 230 list of new articles by message-id follows 2209 [S] . 2211 7.5 Time 2213 As described in Section 6, each article has an arrival timestamp. 2214 Each newsgroup also has a creation timestamp. These timestamps are 2215 used by the NEWNEWS and NEWGROUP commands to construct their 2216 reponses. 2218 The DATE command MUST return a timestamp from the same clock as is 2219 used for determining article arrival and group creation times. This 2220 clock SHOULD be monotonic, and adjustments SHOULD be made by running 2221 it fast or slow compared to "real" time rather than by making sudden 2222 jumps. 2224 Clients can ensure that they do not have gaps in lists of articles or 2225 groups by using the DATE command in the following manner: 2227 First session: 2228 Issue DATE command and record result 2229 Issue NEWNEWS command using a previously chosen timestamp 2231 Subsequent sessions: 2232 Issue DATE command and hold result in temporary storage 2233 Issue NEWNEWS command using timestamp saved from previous session 2234 Overwrite saved timestamp with that currently in temporary storage 2236 In order to allow for minor errors, clients MAY want to adjust the 2237 timestamp back by two or three minutes before using it in NEWNEWS. 2239 7.5.1 Examples 2241 First session: 2243 [C] DATE 2244 [S] 111 20010203112233 2245 [C] NEWNEWS local.chat 20001231 235959 GMT 2246 [S] 230 list follows 2247 [S] 2248 [S] 2249 [S] 2250 [S] . 2252 Second session (the client has subtracted 3 minutes from the 2253 timestamp returned previously): 2255 [C] DATE 2256 [S] 111 20010204003344 2257 [C] NEWNEWS local.chat 20010203 111933 GMT 2258 [S] 230 list follows 2259 [S] 2260 [S] 2261 [S] 2262 [S] . 2264 Note how arrived in the 3 minute gap and so 2265 is listed in both responses. 2267 7.6 The LIST commands 2269 7.6.1 LIST ACTIVE 2271 7.6.1.1 Usage 2273 Syntax 2274 LIST ACTIVE [wildmat] 2276 Responses 2277 215 Information follows (multiline) 2279 Parameters 2280 wildmat = groups of interest 2282 7.6.1.2 Description 2284 The LIST ACTIVE command with no parameters returns a list of valid 2285 newsgroups and associated information. The server MUST include every 2286 group that the client is permitted to select with the GROUP (Section 2287 6.1.1) command. Each newsgroup is sent as a line of text in the 2288 following format: 2290 group high low status 2292 where: 2294 "group" is the name of the newsgroup; 2296 "high" is the reported high water mark for the group; 2298 "low" is the reported low water mark for the group; 2299 "status" is the current status of the group on this server. 2301 Each field in the line is separated from its neighboring fields by 2302 one or more spaces. Note that an empty list is a possible valid 2303 response, and indicates that there are currently no valid newsgroups. 2305 The reported high and low water marks are as described in the GROUP 2306 command (see Section 6.1.1). 2308 The status field is typically one of: 2310 "y" posting is permitted 2312 "n" posting is not permitted 2314 "m" postings will be forwarded to the newsgroup moderator 2316 The server SHOULD use these values when these meanings are required 2317 and MUST NOT use them with any other meaning. Other values for the 2318 status may exist; the definition of these other values and the 2319 circumstances under which they are returned may be specified in an 2320 extension or may be private to the server. A client SHOULD treat an 2321 unrecognised status as giving no information. 2323 The status of a newsgroup only indicates how posts to that newsgroup 2324 are normally processed and is not necessarily customised to the 2325 specific client. For example, if the current client is forbidden from 2326 posting, then this will apply equally to groups with status "y". 2327 Conversely, a client with special privileges (not defined by this 2328 specification) might be able to post to a group with status "n". 2330 If the optional wildmat parameter is specified, the response is 2331 limited to only the groups (if any) whose names match the wildmat. If 2332 no wildmat is specified, the keyword ACTIVE MAY be omitted without 2333 altering the effect of the command. 2335 7.6.1.3 Examples 2337 Example of LIST ACTIVE returning a list of newsgroups: 2339 [C] LIST ACTIVE 2340 [S] 215 list of newsgroups follows 2341 [S] misc.test 3002322 3000234 y 2342 [S] comp.risks 442001 441099 m 2343 [S] alt.fc-writers.recovery 4 1 y 2344 [S] tx.natives.recovery 89 56 y 2345 [S] tx.natives.recovery.d 11 9 n 2346 [S] . 2348 Example of LIST ACTIVE omitting the second keyword and returning no 2349 newsgroups: 2351 [C] LIST 2352 [S] 215 list of newsgroups follows 2353 [S] . 2355 Example of LIST ACTIVE with a wildmat: 2357 [C] LIST ACTIVE *.recovery 2358 [S] 215 list of newsgroups follows 2359 [S] alt.fc-writers.recovery 4 1 y 2360 [S] tx.natives.recovery 89 56 y 2361 [S] . 2363 7.6.2 LIST ACTIVE.TIMES 2365 7.6.2.1 Usage 2367 This command is optional. 2369 Syntax 2370 LIST ACTIVE.TIMES [wildmat] 2372 Responses 2373 215 Information follows (multiline) 2375 Parameters 2376 wildmat = groups of interest 2378 7.6.2.2 Description 2380 The active.times list is maintained by some news transport systems to 2381 contain information about who created a particular newsgroup and 2382 when. Each line of this list consists of three fields separated from 2383 each other by one or more spaces. The first field is the name of the 2384 newsgroup. The second is the time when this group was created on this 2385 news server, measured in seconds since the start of January 1, 1970. 2386 The third is plain text intended to describe the entity that created 2387 the newsgroup; it is often a mailbox as defined in RFC 2822 2388 [RFC2822]. 2390 The list MAY omit newsgroups for which the information is unavailable 2391 and MAY include groups not available on the server; in particular, it 2392 MAY omit all groups created before the date and time of the oldest 2393 entry. The client MUST NOT assume that the list is complete or that 2394 it matches the list returned by LIST ACTIVE. The NEWGROUPS command 2395 (Section 7.3) may provide a better way to access this information and 2396 the results of the two commands SHOULD be consistent (subject to the 2397 caveats in the description of that command). 2399 If the information is available, it is returned as a multi-line 2400 response following the 215 response code. 2402 If the optional wildmat parameter is specified, the response is 2403 limited to only the groups (if any) whose names match the wildmat and 2404 for which the information is available. Note that an empty list is a 2405 possible valid response (whether or not a wildmat is specified) and 2406 indicates that there are no such groups. 2408 7.6.2.3 Examples 2410 Example of LIST ACTIVE.TIMES returning a list of newsgroups: 2412 [C] LIST ACTIVE.TIMES 2413 [S] 215 information follows 2414 [S] misc.test 930445408 2415 [S] alt.rfc-writers.recovery 930562309 2416 [S] tx.natives.recovery 930678923 2417 [S] . 2419 Example of LIST ACTIVE.TIMES returning an error where the command is 2420 recognised but the software does not maintain this information: 2422 [C] LIST ACTIVE.TIMES 2423 [S] 503 program error, function not performed 2425 Example of LIST ACTIVE.TIMES sent to a server that does not recognize 2426 this command: 2428 [C] LIST ACTIVE.TIMES 2429 [S] 501 Syntax Error 2431 7.6.3 LIST DISTRIBUTIONS 2433 7.6.3.1 Usage 2435 This command is optional. 2437 Syntax 2438 LIST DISTRIBUTIONS 2440 Responses 2441 215 Information follows (multiline) 2443 7.6.3.2 Description 2445 The distributions list is maintained by some news transport systems 2446 to contain information about valid values for the content of the 2447 Distribution header in a news article and about what the various 2448 values mean. Each line of this list consists of two fields separated 2449 from each other by one or more spaces. The first field is a value and 2450 the second is a short explanation of the meaning of that value. 2452 If the information is available, it is returned as a multi-line 2453 response following the 215 response code. 2455 7.6.3.3 Examples 2457 Example of LIST DISTRIBUTIONS returning a list of distributions: 2459 [C] LIST DISTRIBUTIONS 2460 [S] 215 information follows 2461 [S] usa United States of America 2462 [S] na North America 2463 [S] world All over the World 2464 [S] . 2466 Example of LIST DISTRIBUTIONS returning an error where the command is 2467 recognised but the software does not maintain this information: 2469 [C] LIST DISTRIBUTIONS 2470 [S] 503 program error, function not performed 2472 Example of LIST DISTRIBUTIONS sent to a server that does not 2473 recognize this command: 2475 [C] LIST DISTRIBUTIONS 2476 [S] 501 Syntax Error 2478 7.6.4 LIST DISTRIB.PATS 2480 7.6.4.1 Usage 2482 This command is optional. 2484 Syntax 2485 LIST DISTRIB.PATS 2487 Responses 2488 215 Information follows (multiline) 2490 7.6.4.2 Description 2492 The distrib.pats list is maintained by some news transport systems to 2493 choose a value for the content of the Distribution header of a news 2494 article being posted. Each line of this list consists of three fields 2495 separated from each other by a colon (":"). The first field is a 2496 weight, the second field is a wildmat (which may be a simple group 2497 name), and the third field is a value for the Distribution header 2498 content. 2500 The client MAY use this information to construct an appropriate 2501 Distribution header given the name of a newsgroup. To do so, it 2502 should determine the lines whose second field matches the newsgroup 2503 name, select from among them the line with the highest weight (with 0 2504 being the lowest), and use the value of the third field to construct 2505 the Distribution header. 2507 If the information is available, it is returned as a multi-line 2508 response following the 215 response code. 2510 7.6.4.3 Examples 2512 Example of LIST DISTRIB.PATS returning a list of newsgroups: 2514 [C] LIST DISTRIB.PATS 2515 [S] 215 information follows 2516 [S] 10:local.*:local 2517 [S] 5:*:world 2518 [S] 20:local.here.*:thissite 2519 [S] . 2521 Example of LIST DISTRIB.PATS returning an error where the command is 2522 recognised but the software does not maintain this information: 2524 [C] LIST DISTRIB.PATS 2525 [S] 503 program error, function not performed 2527 Example of LIST DISTRIB.PATS sent to a server that does not recognize 2528 this command: 2530 [C] LIST DISTRIB.PATS 2532 [S] 501 Syntax Error 2534 7.6.5 LIST NEWSGROUPS 2536 7.6.5.1 Usage 2538 This command is optional. 2540 Syntax 2541 LIST NEWSGROUPS [wildmat] 2543 Responses 2544 215 Information follows (multiline) 2546 Parameters 2547 wildmat = groups of interest 2549 7.6.5.2 Description 2551 The newsgroups list is maintained by some news transport systems to 2552 contain the name of each newsgroup that is available on the server 2553 and a short description about the purpose of the group. Each line of 2554 this list consists of two fields separated from each other by one or 2555 more space or TAB characters (usual practice is a single TAB). The 2556 first field is the name of the newsgroup and the second is a short 2557 description of the group. 2559 The list MAY omit newsgroups for which the information is unavailable 2560 and MAY include groups not available on the server. The client MUST 2561 NOT assume that the list is complete or that it matches the list 2562 returned by LIST ACTIVE. 2564 If the information is available, it is returned as a multi-line 2565 response following the 215 response code. 2567 If the optional wildmat parameter is specified, the response is 2568 limited to only the groups (if any) whose names match the wildmat and 2569 for which the information is available. Note that an empty list is a 2570 possible valid response (whether or not a wildmat is specified) and 2571 indicates that there are no such groups. 2573 7.6.5.3 Examples 2575 Example of LIST NEWSGROUPS returning a list of newsgroups: 2577 [C] LIST NEWSGROUPS 2579 [S] 215 information follows 2580 [S] misc.test General Usenet testing 2581 [S] alt.rfc-writers.recovery RFC Writers Recovery 2582 [S] tx.natives.recovery Texas Natives Recovery 2583 [S] . 2585 Example of LIST NEWSGROUPS returning an error where the command is 2586 recognised but the software does not maintain this information: 2588 [C] LIST NEWSGROUPS 2589 [S] 503 program error, function not performed 2591 Example of LIST NEWSGROUPS sent to a server that does not recognize 2592 this command: 2594 [C] LIST NEWSGROUPS 2595 [S] 501 Syntax error 2597 8. Framework for NNTP extensions 2599 Although NNTP is widely and robustly deployed, some parts of the 2600 Internet community might wish to extend the NNTP service. This 2601 document defines a means whereby an extended NNTP client can query 2602 the server to determine the service extensions that it supports. 2604 It must be emphasized that any extension to the NNTP service should 2605 not be considered lightly. NNTP's strength comes primarily from its 2606 simplicity. Experience with many protocols has shown that: 2608 Protocols with few options tend towards ubiquity, whilst protocols 2609 with many options tend towards obscurity. 2611 This means that each and every extension, regardless of its benefits, 2612 must be carefully scrutinized with respect to its implementation, 2613 deployment, and interoperability costs. In many cases, the cost of 2614 extending the NNTP service will likely outweigh the benefit. 2616 Given this environment, the framework for extensions described in 2617 this document consists of: 2619 o a mechanism for clients to determine a server's available 2620 extensions 2622 o a registry of NNTP service extensions 2624 The LIST EXTENSIONS command is described in this document (see 2625 Section 5.3) and is the mechanism for clients to use to determine 2626 what extensions are available. Except where stated otherwise, the 2627 commands in this document are understood (even if not supported) by 2628 all servers and are not described in the list of features returned by 2629 the LIST EXTENSIONS command. 2631 The IANA shall maintain a registry of NNTP service extensions. 2633 An extension is identified by a unique extension-label, which is a 2634 string of 1 to 12 uppercase US-ASCII letters. The extension-label 2635 will often be the name of a new command that the extension adds. 2636 However this is not a requirement: an extension might not add any new 2637 commands or keywords. 2639 An extension is either a private extension or else it is included in 2640 the IANA registry and is defined in an RFC. Such RFCs either must be 2641 on the standards-track or must define an IESG-approved experimental 2642 protocol. 2644 The definition of an extension must include: 2646 o a descriptive name for the extension 2648 o the extension-label (which is returned by LIST EXTENSIONS to 2649 indicate to the client that the server supports this particular 2650 extension) - the extension-label of a registered extension MUST 2651 NOT begin with "X"; 2653 o the syntax, values, and meanings of any parameters following the 2654 extension-label in the output of LIST EXTENSIONS 2656 o any new NNTP commands associated with the extension - the names of 2657 commands associated with registered extensions MUST NOT begin with 2658 "X"; 2660 o the syntax and possible values of parameters associated with the 2661 new NNTP commands 2663 o the response codes and possible values of parameters for the 2664 responses of the new NNTP commands 2666 o any new parameters the extension associates with any other 2667 pre-existing NNTP commands 2669 o how support for the extension affects the behavior of a server and 2670 NNTP client 2672 o any increase in the maximum length of commands and initial 2673 response lines over the value specified in this document 2675 o a specific statement about the effect on pipelining this extension 2676 may have (if any) 2678 A private extension need not be included in the output of LIST 2679 EXTENSIONS. A server MAY provide additional keywords - either for new 2680 commands or new variants of existing commands - as part of a private 2681 extension. To avoid the risk of a clash with a future registered 2682 extension, the names of private extensions and commands defined by 2683 them SHOULD begin with "X". 2685 A server MUST NOT send different response codes to basic NNTP 2686 commands documented here or commands documented in registered 2687 extensions in response to the availability or use of a private 2688 extension. 2690 8.1 Initial IANA registry 2692 The IANA's initial registry of NNTP service extensions consists of 2693 these entries: 2695 Extension Label Added behavior 2696 Specific article numbers LISTGROUP Defined in this document 2697 Overview support OVER Defined in this document 2698 Batched header retrieval HDR Defined in this document 2700 8.2 Standard extensions 2702 Each of the following sections describes an extension that a server 2703 MAY provide. If the server provides the extension, it MUST include 2704 the appropriate extension label in the response to LIST EXTENSIONS. 2705 If it does not provide it, it MUST NOT include the appropriate 2706 extension label. The descriptions of facilities in each section are 2707 written as if the extension is provided. If it is not provided, the 2708 entire section should be ignored. 2710 If the server provides an extension, it MUST implement all of the 2711 commands in the specification of the extension except for those 2712 marked as optional. If it does not provide an extension, it MUST NOT 2713 implement any of the commands in the specification of that extension. 2715 8.3 The LISTGROUP extension 2717 This extension provides one command and has the extension label 2718 LISTGROUP. 2720 8.3.1 LISTGROUP 2722 8.3.1.1 Usage 2724 Syntax 2725 LISTGROUP [group] 2727 Responses 2728 211 number low high group Article numbers follow (multiline) 2729 411 No such newsgroup 2730 412 No newsgroup selected [1] 2732 Parameters 2733 group = name of newsgroup 2734 number = estimated number of articles in the group 2735 low = reported low water mark 2736 high = reported high water mark 2738 [1] The 412 response can only occur if no group has been specified. 2740 8.3.1.2 Description 2742 The LISTGROUP command is used to get a listing of all the article 2743 numbers in a particular newsgroup. 2745 The optional parameter is the name of the newsgroup to be selected 2746 (e.g. "news.software.misc"). A list of valid newsgroups may be 2747 obtained from the LIST ACTIVE command. If no group is specified, the 2748 current selected newsgroup is used. 2750 The list of article numbers is returned as a multi-line response 2751 following the 211 response code (the parameters on the initial 2752 response line are the same as for the GROUP command (see Section 2753 6.1.1). The list contains one number per line, is in numerical order, 2754 and lists precisely those articles that exist in the group. 2756 When a valid group is selected by means of this command, the current 2757 selected newsgroup MUST be set to that group and the current article 2758 number MUST be set to the first article in the group. If an empty 2759 newsgroup is selected, the current article pointer is made invalid. 2760 If an invalid group is specified, the current selected newsgroup and 2761 current article number MUST NOT be changed. 2763 The LISTGROUP command MAY be used by a client as a replacement for 2764 the GROUP command in establishing a valid current selected newsgroup 2765 and current article number. 2767 If the group specified is not available on the server, a 411 response 2768 MUST be returned. If no group is specified and the current selected 2769 newsgroup is invalid, a 412 response MUST be returned. 2771 8.3.1.3 Examples 2773 Example of LISTGROUP on an empty group: 2775 [C] LISTGROUP example.empty.newsgroup 2776 [S] 211 0 0 0 example.empty.newsgroup list follows 2777 [S] . 2779 Example of LISTGROUP on a valid current selected newsgroup: 2781 [C] GROUP misc.test 2782 [S] 211 2000 3000234 3002322 misc.test 2783 [C] LISTGROUP 2784 [S] 211 2000 3000234 3002322 misc.test list follows 2786 [S] 3000234 2787 [S] 3000237 2788 [S] 3000238 2789 [S] 3000239 2790 [S] 3002322 2791 [S] . 2793 Example of LISTGROUP failing because no group has been selected: 2795 [Assumes current selected newsgroup is invalid.] 2796 [C] LISTGROUP 2797 [S] 412 no current group 2798 [C] GROUP example.is.sob.bradner.or.barber 2799 [S] 411 no such group 2800 [C] LISTGROUP 2801 [S] 412 no current group 2803 8.4 Article metadata 2805 The OVER and HDR extensions refer to the concept of "article 2806 metadata". This is data about articles that does not occur within the 2807 article itself. Each metadata item has a name which MUST begin with a 2808 colon (and which MUST NOT contain a colon elsewhere within it). 2810 When generating a metadata item, the server MUST compute it for 2811 itself and MUST NOT trust any related value provided in the article. 2812 (In particular, a Lines or Bytes header in the article MUST NOT be 2813 assumed to specify the correct number of lines or bytes in the 2814 article.) 2816 This specification defines two metadata items: ":bytes" and ":lines". 2817 Other metadata items may be defined by extensions. The names of 2818 metadata items defined by registered extensions MUST NOT begin with 2819 ":x-". To avoid the risk of a clash with a future registered 2820 extension, the names of metadata items defined by private extensions 2821 SHOULD begin with ":x-". 2823 8.4.1 The :bytes metadata item 2825 The :bytes metadata item for an article is a decimal integer. It MUST 2826 equal the number of octets in the entire article - headers, body, and 2827 separating empty line - except that each CRLF pair MAY (but SHOULD 2828 NOT) be counted as a single octet. 2830 8.4.2 The :lines metadata item 2832 The :lines metadata item for an article is a decimal integer. It MUST 2833 equal the number of lines in the article body (excluding the empty 2834 line separating headers and body); equivalently, it is two less than 2835 the number of CRLF pairs that the BODY command would return for that 2836 article (the extra two are those following the response code and the 2837 termination octet). 2839 8.5 The OVER extension 2841 This extension provides two commands, OVER and LIST OVERVIEW.FMT. The 2842 label for this extension is OVER. 2844 The OVER extension provides access to the "overview database", which 2845 is a database of headers extracted from incoming articles. Only 2846 certain headers are included in the database. The database also 2847 includes some article metadata. The information stored in the 2848 database may change over time. If the database records the content or 2849 absence of a given field (that is, a header or metadata item) for all 2850 articles, it is said to be "consistent" for that field. If it records 2851 the content of a header for some articles but not for others that 2852 nevertheless included that header, or records a metadata item for 2853 some articles but not others to which that item applies, it is said 2854 to be "inconsistent" for that field. 2856 The LIST OVERVIEW.FMT command SHOULD list all the fields for which 2857 the database is consistent at that moment. It MAY omit such fields 2858 (for example if it is not known whether the database is consistent or 2859 inconsistent). It MUST NOT include fields for which the database is 2860 inconsistent or which are not stored in the database. Therefore if a 2861 header appears in the LIST OVERVIEW.FMT output but not the OVER 2862 output for a given article, that header does not appear in the 2863 article, and similarly for metadata items. 2865 These rules assume the fields being stored in the database remain 2866 constant for long periods of time, with the database therefore being 2867 consistent. When the set of fields to be stored is changed, it will 2868 be inconsistent until either the database is rebuilt or the only 2869 articles remaining are those received during the change. Therefore 2870 the output from LIST OVERVIEW.FMT needs to be altered twice: before 2871 any fields stop being stored, they MUST be removed from the output, 2872 then when the database is once more known to be consistent, the new 2873 fields SHOULD be added to the output. 2875 This extension is based on the Overview/NOV database [ROBE1995] 2876 developed by Geoff Collyer. 2878 8.5.1 OVER 2879 8.5.1.1 Usage 2881 Syntax 2882 OVER message-id 2883 OVER [range] 2885 Responses 2887 First form (message-id specified) 2888 224 Overview information follows (multiline) 2889 430 No article found with that message-id 2891 Second form (optional range specified) 2892 224 Overview information follows (multiline) 2893 412 No newsgroup selected 2894 420 Current article number is invalid [1] 2895 423 No articles in that range 2897 Parameters 2898 message-id = Article message-id 2899 range = Article(s) to return information for 2901 [1] The 420 response can only occur if no article number has been 2902 specified. 2904 8.5.1.2 Description 2906 The OVER command returns the contents of the headers and metadata in 2907 the database for the article(s) specified. 2909 In the first form the article is specified by message-id. In the 2910 second form articles in the current selected newsgroup are specified 2911 using the optional range argument, which may be any of the following: 2913 o an article number 2915 o an article number followed by a dash to indicate all following 2917 o an article number followed by a dash followed by another article 2918 number 2920 If no argument is specified, then the current article number is used. 2922 If the information is available, it is returned as a multi-line 2923 response following the 224 response code. If the argument is a 2924 message-id and no such article exists, a 430 response MUST be 2925 returned. If the current selected newsgroup is invalid, a 412 2926 response MUST be returned. If there are no articles in the range 2927 specified, a 423 response MUST be returned. If OVER is sent without 2928 any arguments and the current article number is invalid, a 420 2929 response MUST be returned. 2931 For a successful response, the output consists of one line per 2932 article, sorted in numerical order of article number (note that 2933 unless the argument is a range including a dash, there will only be 2934 one line but it will still be in multi-line format). Each line 2935 consists of a number of fields separated by a TAB. A field may be 2936 empty (in which case there will be two adjacent TABs), and a sequence 2937 of trailing TABs may be omitted. 2939 The first 8 fields MUST be the following, in order: 2941 "0" (first form) or article number (second form) 2942 Subject header content 2943 From header content 2944 Date header content 2945 Message-ID header content 2946 References header content 2947 :bytes metadata item 2948 :lines metadata item 2950 If the article is specified by message-id rather than by article 2951 range, the article number is given as "0". 2953 Any subsequent fields are the contents of the other headers and 2954 metadata held in the database. 2956 For the five mandatory headers, the content of each field MUST be 2957 based on the content of the header (that is, with the header name and 2958 following colon and space removed). If the article does not contain 2959 that header, or if the content is empty, the field MUST be empty. For 2960 the two mandatory metadata items, the content of the field MUST be 2961 just the value, with no other text. 2963 For all subsequent fields that contain headers, the content MUST be 2964 the entire header line other than the trailing CRLF. For all 2965 subsequent fields that contain metadata, the field consists of the 2966 metadata name, a single space, and then the value. 2968 For all fields, the value is processed by first removing all CRLF 2969 pairs (that is, undoing any folding and removing the terminating 2970 CRLF) and then replacing each TAB with a single space. If there is no 2971 such header in the article, or no such metadata item, or no header or 2972 item stored in the database for that article, the corresponding field 2973 MUST be empty. 2975 Note that, after unfolding, the characters NUL, LF, and CR cannot 2976 occur in the header of an article offered by a conformant server. 2977 Nevertheless, servers SHOULD check for these characters and replace 2978 each one by a single space (so that, for example, CR LF LF TAB will 2979 become two spaces, since the CR and first LF will be removed by the 2980 unfolding process). This will encourage robustness in the face of 2981 non-conforming data; it is also possible that future versions of this 2982 specification may permit these characters to appear in articles. 2984 The server SHOULD NOT produce output for articles that no longer 2985 exist. 2987 8.5.1.3 Examples 2989 In the first three examples, TAB has been replaced by vertical bar 2990 and some lines have been folded for readability. 2992 Example of a successful retrieval of overview information for an 2993 article (using no article number): 2995 [C] GROUP misc.test 2996 [S] 211 1234 3000234 3002322 misc.test 2997 [C] OVER 2998 [S] 224 Overview information follows 2999 [S] 300234|I am just a test article|"Demo User" 3000 |6 Oct 1998 04:38:40 -0500| 3001 <45223423@example.com>|<45454@example.net>|1234| 3002 17|Xref: news.example.com misc.test:3000363 3003 [S] . 3005 Example of a successful retrieval of overview information for an 3006 article by message-id: 3008 [C] OVER <45223423@example.com> 3009 [S] 224 Overview information follows 3010 [S] 0|I am just a test article|"Demo User" 3011 |6 Oct 1998 04:38:40 -0500| 3012 <45223423@example.com>|<45454@example.net>|1234| 3013 17|Xref: news.example.com misc.test:3000363 3014 [S] . 3016 Note that the article number has been replaced by "0". 3018 Example of a successful retrieval of overview information for a range 3019 of articles: 3021 [C] GROUP misc.test 3022 [S] 211 1234 3000234 3002322 misc.test 3024 [C] OVER 3000234-3000240 3025 [S] 224 Overview information follows 3026 [S] 300234|I am just a test article|"Demo User" 3027 |6 Oct 1998 04:38:40 -0500| 3028 <45223423@example.com>|<45454@example.net>|1234| 3029 17|Xref: news.example.com misc.test:3000363 3030 [S] 3000235|Another test article|nobody@nowhere.to 3031 (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>|| 3032 4818|37||Distribution: fi 3033 [S] 3000238|Re: I am just a test article|somebody@elsewhere.to| 3034 7 Oct 1998 11:38:40 +1200|| 3035 <45223423@to.to>|9234|51 3036 [S] . 3038 Note the missing "References" and Xref headers in the second line, 3039 the missing trailing field(s) in the first and last lines, and that 3040 there are only results for those articles that still exist. 3042 Example of an unsuccessful retrieval of overview information on an 3043 article by number: 3045 [C] GROUP misc.test 3046 [S] 211 1234 3000234 3002322 misc.test 3047 [C] OVER 300256 3048 [S] 420 No such article in this group 3050 Example of an unsuccessful retrieval of overview information by 3051 number because no newsgroup was selected first: 3053 [Assumes current selected newsgroup is invalid.] 3054 [C] OVER 3055 [S] 412 No newsgroup selected 3057 Example of an attempt to retrieve information when the current 3058 selected newsgroup is empty: 3060 [C] GROUP example.empty.newsgroup 3061 [S] 211 0 0 0 example.empty.newsgroup 3062 [C] OVER 3063 [S] 420 No current article selected 3065 8.5.2 LIST OVERVIEW.FMT 3067 8.5.2.1 Usage 3068 This command is optional. 3070 Syntax 3071 LIST OVERVIEW.FMT 3073 Responses 3074 215 Information follows (multiline) 3076 8.5.2.2 Description 3078 The LIST OVERVIEW.FMT command returns a description of the fields in 3079 the database for which it is consistent (as described above). 3081 If the information is available, it is returned as a multi-line 3082 response following the 215 response code. The information contains 3083 one line per field in the order they are returned by the OVER 3084 command; the first 7 lines MUST be exactly: 3086 Subject: 3087 From: 3088 Date: 3089 Message-ID: 3090 References: 3091 :bytes 3092 :lines 3094 except that, for compatibility with existing implementations, the 3095 last two lines MAY instead be: 3097 Bytes: 3098 Lines: 3100 even though they refer to metadata, not headers. 3102 All subsequent lines MUST consist of either a header name followed by 3103 ":full", or the name of a piece of metadata. 3105 There are no leading or trailing spaces in the output. 3107 Note that the 7 fixed lines describe the 2nd to 8th fields of the 3108 OVER output. The "full" suffix is a reminder that the corresponding 3109 fields include the header name. 3111 This command MAY generate different results if used more than once in 3112 a session. 3114 8.5.2.3 Examples 3116 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3117 output above, using the preferred format: 3119 [C] LIST OVERVIEW.FMT 3120 [S] 215 Order of fields in overview database. 3121 [S] Subject: 3122 [S] From: 3123 [S] Date: 3124 [S] Message-ID: 3125 [S] References: 3126 [S] :bytes 3127 [S] :lines 3128 [S] Xref:full 3129 [S] Distribution:full 3130 [S] . 3132 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3133 output above, using the alternative format: 3135 [C] LIST OVERVIEW.FMT 3136 [S] 215 Order of fields in overview database. 3137 [S] Subject: 3138 [S] From: 3139 [S] Date: 3140 [S] Message-ID: 3141 [S] References: 3142 [S] Bytes: 3143 [S] Lines: 3144 [S] Xref:full 3145 [S] Distribution:full 3146 [S] . 3148 Example of LIST OVERVIEW.FMT returning an error: 3150 [C] LIST OVERVIEW.FMT 3151 [S] 503 overview.fmt not available 3153 8.6 The HDR extension 3155 This extension provides two new commands: HDR and LIST HEADERS. The 3156 label for this extension is HDR. 3158 The HDR extension provides access to specific headers and metadata 3159 items (collectively "fields") of articles or groups of articles. In 3160 the case of headers, an implementation MAY restrict the use of this 3161 extension to a specific list of headers or MAY allow it to be used 3162 with any header. In the latter case it MUST use the parameter "ALL" 3163 following the extension label in the output of LIST EXTENSIONS; in 3164 the former case it MUST NOT use any parameter. 3166 8.6.1 HDR 3168 8.6.1.1 Usage 3170 Syntax 3171 HDR header range 3172 HDR header message-id 3173 HDR header 3175 Responses 3177 First form (range specified) 3178 225 Headers follow (multiline) 3179 412 No newsgroup selected 3180 423 No articles in that range 3182 Second form (message-id specified) 3183 225 Headers follow (multiline) 3184 430 No article with that message-id 3186 Third form (current article number used) 3187 225 Headers follow (multiline) 3188 412 No newsgroup selected 3189 420 Current article number is invalid 3191 Parameters 3192 header = name of header, without the colon 3193 range = number(s) of articles 3194 message-id = message-id of article 3196 8.6.1.2 Description 3198 The HDR command retrieves specific headers from an article or 3199 specified range of articles in the current selected newsgroup, or 3200 from an article specified by message-id. It can also return certain 3201 metadata about the article or articles. 3203 The required header parameter is the name of a header (e.g. 3204 "subject") in an article, or the name of a metadata item, and is 3205 case-insensitive. Names of metadata items always begin with a colon. 3206 Except where stated otherwise, metadata items are treated as if they 3207 were header contents, and references to headers in this description 3208 apply equally to metadata items. 3210 The range parameter may be any of the following: 3212 o an article number 3214 o an article number followed by a dash to indicate all following 3216 o an article number followed by a dash followed by another article 3217 number 3219 The message-id argument indicates a specific article. As shown by the 3220 syntax, the range and message-id arguments are mutually exclusive; if 3221 neither is specified, the current article number is used. 3223 If the information is available, it is returned as a multi-line 3224 response following the 225 response code and contains one line for 3225 each article where the relevant header line or metadata item exists. 3226 The line consists of the article number, a space, and then the 3227 contents of the header (without the header name or the colon and 3228 space that follow it) or metadata item. If the article is specified 3229 by message-id rather than by article range, the article number is 3230 given as "0". 3232 Header contents are modified as follows: all CRLF pairs are removed, 3233 and then each TAB is replaced with a single space (note that this is 3234 the same transformation as is performed by the OVER extension 3235 (Section 8.5.1.2), and the same comment concerning NUL, CR, and LF 3236 applies). 3238 The header content is in all cases taken from the article. This means 3239 that, for example, a request for the header "Lines" returns the 3240 contents of the "Lines" header of the specified articles, if any, not 3241 the line count metadata or any other server-generated value. If the 3242 header occurs in a given article multiple times, only the content of 3243 the first occurrence is returned by HDR. 3245 If the requested header is not present in the article or if it is 3246 present but empty, a line for that article is included in the output 3247 but the header content portion of the line is empty (the space after 3248 the article number MAY be retained or omitted). If any article number 3249 in the provided range does not exist in the group, no line for that 3250 article number is included in the output. 3252 If the optional argument is a message-id and no such article exists, 3253 a 430 response MUST be returned. If the optional argument is not a 3254 message-id and the current selected newsgroup is invalid, a 412 3255 response MUST be returned. If the optional argument is an article 3256 number or number range and no article with that number or in that 3257 number range exists in the current selected newsgroup, a 423 response 3258 MUST be returned. If HDR is sent without any arguments and the 3259 current article number is invalid, a 420 response MUST be returned. 3261 A server MAY only allow HDR commands for a limited set of headers and 3262 metadata items. If so, it MUST respond with a 503 response to 3263 attempts to request other headers, rather than returning erroneous 3264 results such as a successful empty response. 3266 8.6.1.3 Examples 3268 Example of a successful retrieval of subject lines from a range of 3269 articles (3000235 has no Subject header, and 3000236 is missing): 3271 [C] GROUP misc.test 3272 [S] 211 1234 3000234 3002322 misc.test 3273 [C] HDR Subject 3000234-300238 3274 [S] 225 Headers follow 3275 [S] 3000234 I am just a test article 3276 [S] 3000235 3277 [S] 3000237 Re: I am just a test article 3278 [S] 3000238 Ditto 3279 [S] . 3281 Example of a successful retrieval of line counts from a range of 3282 articles: 3284 [C] GROUP misc.test 3285 [S] 211 1234 3000234 3002322 misc.test 3286 [C] HDR :lines 3000234-300238 3287 [S] 225 Headers follow 3288 [S] 3000234 42 3289 [S] 3000235 5 3290 [S] 3000237 11 3291 [S] 3000238 2378 3292 [S] . 3294 Example of a successful retrieval of the subject line from an article 3295 by message-id: 3297 [C] GROUP misc.test 3298 [S] 211 1234 3000234 3002322 misc.test 3299 [C] HDR subject 3300 [S] 225 Header information follows 3301 [S] 0 I am just a test article 3302 [S] . 3304 Example of a successful retrieval of the subject line from the 3305 current article: 3307 [C] GROUP misc.test 3308 [S] 211 1234 3000234 3002322 misc.test 3309 [C] HDR subject 3310 [S] 225 Header information follows 3311 [S] 3000234 I am just a test article 3312 [S] . 3314 Example of an unsuccessful retrieval of a header from an article by 3315 message-id: 3317 [C] HDR subject 3318 [S] 430 No Such Article Found 3320 Example of an unsuccessful retrieval of headers from articles by 3321 number because no newsgroup was selected first: 3323 [Assumes current selected newsgroup is invalid.] 3324 [C] HDR subject 300256- 3325 [S] 412 No newsgroup selected 3327 Example of an unsuccessful retrieval of headers because the current 3328 selected newsgroup is empty: 3330 [C] GROUP example.empty.newsgroup 3331 [S] 211 0 0 0 example.empty.newsgroup 3332 [C] HDR subject 1- 3333 [S] 423 No articles in that range 3335 Example of an unsuccessful retrieval of headers because the server 3336 does not allow HDR commands for that header: 3338 [C] GROUP misc.test 3339 [S] 211 1234 3000234 3002322 misc.test 3340 [C] HDR Content-Type 3000234-300238 3341 [S] 503 HDR not permitted on Content-Type 3343 8.6.2 LIST HEADERS 3345 8.6.2.1 Usage 3347 Syntax 3348 LIST HEADERS 3350 Responses 3351 215 Header and metadata list follows (multiline) 3353 8.6.2.2 Description 3355 The LIST HEADERS command returns a list of headers and metadata items 3356 that may be retrieved using the HDR command. 3358 The information is returned as a multi-line response following the 3359 215 response code and contains one line for each header or metadata 3360 item name (excluding the colon in the former case). If the 3361 implementation allows any header to be retrieved (also indicated by 3362 the "ALL" parameter to the extension label) it MUST NOT include any 3363 header names in the list but MUST include the special entry ":" (a 3364 single colon on its own); it MUST still list any metadata items that 3365 are available. The order of items in the list is not significant; the 3366 server need not even consistently return the same order. The list MAY 3367 be empty (though in this circumstance there is little point in 3368 providing the extension). 3370 If the list of available fields is not the same for all articles (for 3371 example, because the HDR command uses the same database as the OVER 3372 command and the set of fields being stored has recently changed), 3373 then the response should indicate the situation for a newly-arrived 3374 article. 3376 An implementation that also supports the OVER extension SHOULD at 3377 least permit all the headers and metadata items listed in the output 3378 from the LIST OVERVIEW.FMT command. 3380 8.6.2.3 Examples 3382 Example of an implementation providing access to only a few headers: 3384 [C] LIST EXTENSIONS 3385 [S] 202 extensions supported: 3386 [S] HDR 3387 [S] . 3388 [C] LIST HEADERS 3389 [S] 215 headers supported: 3390 [S] Subject 3391 [S] Message-ID 3392 [S] Xref 3393 [S] . 3395 Example of an implementation providing access to the same fields as 3396 the first example in Section 8.5.2.3: 3398 [C] LIST EXTENSIONS 3399 [S] 202 extensions supported: 3400 [S] OVER 3401 [S] HDR 3402 [S] . 3403 [C] LIST HEADERS 3404 [S] 215 headers and metadata items supported: 3405 [S] Date 3406 [S] Distribution 3407 [S] From 3408 [S] Message-ID 3409 [S] References 3410 [S] Subject 3411 [S] Xref 3412 [S] :bytes 3413 [S] :lines 3414 [S] . 3416 Example of an implementation providing access to all headers: 3418 [C] LIST EXTENSIONS 3419 [S] 202 extensions supported: 3420 [S] HDR ALL 3421 [S] . 3422 [C] LIST HEADERS 3423 [S] 215 metadata items supported: 3424 [S] : 3425 [S] :bytes 3426 [S] :lines 3427 [S] :article-number 3428 [S] . 3430 9. Augmented BNF Syntax for NNTP 3432 Each of the following sections describes the syntax of a major 3433 element of NNTP. This syntax extends and refines the descriptions 3434 elsewhere in this specification, and should be given precedence when 3435 resolving apparent conflicts. Note that ABNF [RFC2234] strings are 3436 case insensitive. Non-terminals used in several places are defined in 3437 a separate section at the end. 3439 9.1 Commands 3441 This syntax defines the non-terminal "command-line", which 3442 represents what is sent from the client to the server. 3444 command-line = command EOL 3445 command = article-command / 3446 body-command / 3447 date-command / 3448 group-command / 3449 hdr-command / 3450 head-command / 3451 help-command / 3452 ihave-command / 3453 last-command / 3454 list-active-command / 3455 list-active-times-command / 3456 list-distrib-pats-command / 3457 list-distributions-command / 3458 list-extensions-command / 3459 list-newsgroups-command / 3460 list-overview-fmt-command / 3461 listgroup-command / 3462 mode-reader-command / 3463 newgroups-command / 3464 newnews-command / 3465 next-command / 3466 over-command / 3467 post-command / 3468 quit-command / 3469 stat-command / 3470 x-command 3472 article-command = "ARTICLE" [article-ref] 3473 body-command = "BODY" [article-ref] 3474 date-command = "DATE" 3475 group-command = "GROUP" WS newsgroup-name 3476 hdr-command = "HDR" WS header-meta-name [range-ref] 3477 head-command = "HEAD" [article-ref] 3478 help-command = "HELP" 3479 ihave-command = "IHAVE" WS message-id 3480 last-command = "LAST" 3481 list-active-command = "LIST" [WS "ACTIVE" [WS wildmat]] 3482 list-active-times-command = "LIST" WS "ACTIVE.TIMES" [WS wildmat] 3483 list-distrib-pats-command = "LIST" WS "DISTRIB.PATS" 3484 list-distributions-command = "LIST" WS "DISTRIBUTIONS" 3485 list-extensions-command = "LIST" WS "EXTENSIONS" 3486 list-newsgroups-command = "LIST" WS "NEWSGROUPS" [WS wildmat] 3487 list-overview-fmt-command = "LIST" WS "OVERVIEW.FMT" 3488 listgroup-command = "LISTGROUP" [WS newsgroup-name] 3489 mode-reader-command = "MODE" WS "READER" 3490 newgroups-command = "NEWGROUPS" WS date-time 3491 newnews-command = "NEWNEWS" WS wildmat WS date-time 3492 next-command = "NEXT" 3493 over-command = "OVER" [WS range] 3494 post-command = "POST" 3495 quit-command = "QUIT" 3496 stat-command = "STAT" [article-ref] 3497 x-command = x-command-name *(WS x-argument) 3498 ; Each extension command is specified fully elsewhere 3500 article-ref = WS (article-number / message-id) 3501 article-number = 1*16DIGIT 3502 date = [2DIGIT] 6DIGIT 3503 date-time = date WS time [WS "GMT"] 3504 header-meta-name = header-name / metadata-name 3505 metadata-name = ":" 1*A-NOTCOLON 3506 newsgroup-name = 1*wildmat-exact 3507 range = article-number ["-" [article-number]] 3508 range-ref = WS (range / message-id) 3509 time = 6DIGIT 3510 x-command-name = 3*12A-CHAR 3511 x-argument = 1*P-CHAR 3513 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 3514 wildmat-pattern = 1*wildmat-item 3515 wildmat-item = wildmat-exact / wildmat-wild 3516 wildmat-exact = %x21-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 3517 UTF8-non-ascii ; exclude * , ? [ \ ] 3518 wildmat-wild = "*" / "?" 3520 9.2 Responses 3522 This syntax defines the non-terminal "response", which represents 3523 what is sent from the server to the client in response to a command. 3525 response = simple-response / multiline-response 3526 multiline-response = simple-response *content-line termination 3527 termination = "." CRLF 3528 content-line = [content-text] CRLF 3529 content-text = (".." / B-NONDOT) *B-CHAR 3531 simple-response = 3DIGIT parameters [ SP trailing-comment ] CRLF 3532 trailing-comment = *U-CHAR 3533 parameters = *( SP parameter ) ; How many depends on the response 3534 parameter = 1*A-CHAR 3536 9.3 Articles 3538 This syntax defines the non-terminal "article", which represents the 3539 format of an article as described in Section 3.4. 3541 article = 1*header CRLF body 3542 header = header-name ":" [CRLF] SP header-content CRLF 3543 header-content = *( P-CHAR / [CRLF] WS ) 3544 body = *(*B-CHAR CRLF) 3546 9.4 General non-terminals 3547 header-name = 1*A-NOTCOLON 3548 message-id = "<" 1*248A-NOTGT ">" 3550 ; Assorted special character sets 3551 ; A- means based on ASCII, excluding controls and SP 3552 ; P- means based on UTF-8, excluding controls and SP 3553 ; U- means based on UTF-8, excluding NUL CR and LF 3554 ; B- means based on bytes, excluding NUL CR and LF 3555 A-CHAR = %x21-7E 3556 A-NOTCOLON = %x21-39 / %x3B-7E ; exclude ":" 3557 A-NOTGT = %x21-3D / %x3F-7E ; exclude ">" 3558 P-CHAR = A-CHAR / UTF8-non-ascii 3559 U-CHAR = %x01-09 / %x0B-0C / %x0E-7F / UTF8-non-ascii 3560 B-CHAR = %x01-09 / %x0B-0C / %x0E-FF 3561 B-NONDOT = %x01-09 / %x0B-0C / %x0E-2D / %x2F-FF ; exclude "." 3563 CR = %x0D 3564 CRLF = CR LF 3565 DIGIT = %x30-39 3566 EOL = *(SP / HT) CRLF 3567 HT = %x09 3568 LF = %x0A 3569 SP = %x20 3570 UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4 3571 UTF8-2 = %xC2-DF UTF8-tail 3572 UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail / 3573 %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail 3574 UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail / 3575 %xF4 %x80-8F 2UTF8-tail 3576 UTF8-tail = %x80-BF 3577 WS = 1*(SP / HT) 3579 OUTSTANDING ISSUE 3581 When draft-yergeau-rfc2279bis-04.txt replaces 2279, need to update 3582 references. 3584 10. IANA Considerations 3586 This specification requires IANA to keep a registry of 3587 extension-labels. The initial contents of this registry are specified 3588 in Section 8.1. As described in Section 8, names beginning with X are 3589 reserved for private use while all other names are to be associated 3590 with a specification in an RFC on the standards-track or defining an 3591 IESG-approved experimental protocol. 3593 11. Security Considerations 3595 This section is meant to inform application developers, information 3596 providers, and users of the security limitations in NNTP as described 3597 by this document. The discussion does not include definitive 3598 solutions to the problems revealed, though it does make some 3599 suggestions for reducing security risks. 3601 11.1 Personal and Proprietary Information 3603 NNTP, because it was created to distribute network news articles, 3604 will forward whatever information is stored in those articles. 3605 Specification of that information is outside this scope of this 3606 document, but it is likely that some personal and/or proprietary 3607 information is available in some of those articles. It is very 3608 important that designers and implementers provide informative 3609 warnings to users so personal and/or proprietary information in 3610 material that is added automatically to articles (e.g. in headers) is 3611 not disclosed inadvertently. Additionally, effective and easily 3612 understood mechanisms to manage the distribution of news articles 3613 SHOULD be provided to NNTP Server administrators, so that they are 3614 able to report with confidence the likely spread of any particular 3615 set of news articles. 3617 11.2 Abuse of Server Log Information 3619 A server is in the position to save session data about a user's 3620 requests that might identify their reading patterns or subjects of 3621 interest. This information is clearly confidential in nature and its 3622 handling can be constrained by law in certain countries. People using 3623 the NNTP protocol to provide data are responsible for ensuring that 3624 such material is not distributed without the permission of any 3625 individuals that are identifiable by the published results. 3627 11.3 Weak Authentication and Access Control 3629 There is no user-based or token-based authentication in the basic 3630 NNTP specification. Access is normally controlled by server 3631 configuration files. Those files specify access by using domain names 3632 or IP addresses. However, this specification does permit the creation 3633 of extensions to the NNTP protocol itself for such purposes. While 3634 including such mechanisms is optional, doing so is strongly 3635 encouraged. 3637 Other mechanisms are also available. For example, a proxy server 3638 could be put in place that requires authentication before connecting 3639 via the proxy to the NNTP server. 3641 11.4 DNS Spoofing 3643 Many existing NNTP implementations authorize incoming connections by 3644 checking the IP address of that connection against the IP addresses 3645 obtained via DNS lookups of lists of domain names given in local 3646 configuration files. Servers that use this type of authentication, 3647 and clients that find a server by doing a DNS lookup of the server 3648 name, rely very heavily on the Domain Name Service, and are thus 3649 generally prone to security attacks based on the deliberate 3650 misassociation of IP addresses and DNS names. Clients and servers 3651 need to be cautious in assuming the continuing validity of an IP 3652 number/DNS name association. 3654 In particular, NNTP clients and servers SHOULD rely on their name 3655 resolver for confirmation of an IP number/DNS name association, 3656 rather than caching the result of previous host name lookups. Many 3657 platforms already can cache host name lookups locally when 3658 appropriate, and they SHOULD be configured to do so. It is proper for 3659 these lookups to be cached, however, only when the TTL (Time To Live) 3660 information reported by the name server makes it likely that the 3661 cached information will remain useful. 3663 If NNTP clients or servers cache the results of host name lookups in 3664 order to achieve a performance improvement, they MUST observe the TTL 3665 information reported by DNS. If NNTP clients or servers do not 3666 observe this rule, they could be spoofed when a previously accessed 3667 server's IP address changes. As network renumbering is expected to 3668 become increasingly common, the possibility of this form of attack 3669 will grow. Observing this requirement thus reduces this potential 3670 security vulnerability. 3672 This requirement also improves the load-balancing behavior of clients 3673 for replicated servers using the same DNS name and reduces the 3674 likelihood of a user's experiencing failure in accessing sites that 3675 use that strategy. 3677 11.5 UTF-8 issues 3679 UTF-8 [RFC2279] permits only certain sequences of octets and 3680 designates others as either malformed or "illegal". The Unicode 3681 standard identifies a number of security issues related to illegal 3682 sequences and forbids their generation by conforming implementations. 3684 Implementations of this specification MUST NOT generate malformed or 3685 illegal sequences and SHOULD detect them and take some appropriate 3686 action. This could include: 3688 o replacing such sequences by a "guessed" valid sequence (based on 3689 properties of the UTF-8 encoding); 3691 o replacing such sequences by the sequence %xEF.BF.BD, which encodes 3692 the "replacement character" U+FFFD; 3694 o closing the connection; 3696 o generating a 501 response code. 3698 In the first case, the implementation MUST ensure that any 3699 replacement cannot be used to bypass validity or security checks. For 3700 example, the illegal sequence %xC0.A0 is an over-long encoding for 3701 space (%x20). If it is replaced by the latter in a command line, this 3702 needs to happen before the command line is parsed into individual 3703 arguments. If the replacement came after parsing, it would be 3704 possible to generate an argument with an embedded space, which is 3705 forbidden. Use of the "replacement character" does not have this 3706 problem, since it is permitted wherever non-US-ASCII characters are. 3708 OUTSTANDING ISSUE 3710 Yergeau says that you MUST detect illegal sequences. He also 3711 rejects the first bullet point and consequent text; I'm discussing 3712 it with him now. 3714 12. Acknowledgments 3716 The author acknowledges the original authors of NNTP as documented in 3717 RFC 977 [RFC977]: Brian Kantor and Phil Lapsey. 3719 The author gratefully acknowledges the work of the NNTP committee 3720 chaired by Eliot Lear. The organization of this document was 3721 influenced by the last available draft from this working group. A 3722 special thanks to Eliot for generously providing the original 3723 machine-readable sources for that document. 3725 The author gratefully acknowledges the work of the DRUMS working 3726 group, specifically RFC 1869 [RFC1869], which is the basis of the 3727 NNTP extensions mechanism detailed in this document. 3729 The author gratefully acknowledges the authors of RFC 2616 [RFC2616] 3730 for providing specific and relevant examples of security issues that 3731 should be considered for HTTP. Since many of the same considerations 3732 exist for NNTP, those examples that are relevant have been included 3733 here with some minor rewrites. 3735 The author gratefully acknowledges the comments and additional 3736 information provided by the following individuals in preparing one or 3737 more of the progenitors of this document: 3739 Russ Allbery 3740 Wayne Davison 3741 Chris Lewis 3742 Tom Limoncelli 3743 Eric Schnoebelen 3744 Rich Salz 3746 This work was motivated by the work of various news reader authors 3747 and news server authors, which includes those listed below: 3749 Rick Adams 3750 Original author of the NNTP extensions to the RN news reader and 3751 last maintainer of Bnews 3753 Stan Barber 3754 Original author of the NNTP extensions to the news readers that 3755 are part of Bnews 3757 Geoff Collyer 3758 Original author of the OVERVIEW database proposal and one of the 3759 original authors of CNEWS 3761 Dan Curry 3762 Original author of the xvnews news reader 3764 Wayne Davison 3765 Author of the first threading extensions to the RN news reader 3766 (commonly called TRN) 3768 Geoff Huston 3769 Original author of ANU NEWS 3771 Phil Lapsey 3772 Original author of the UNIX reference implementation for NNTP 3774 Iain Lea 3775 Original maintainer of the TIN news reader 3777 Chris Lewis 3778 First known implementer of the AUTHINFO GENERIC extension 3780 Rich Salz 3781 Original author of INN 3783 Henry Spencer 3784 One of the original authors of CNEWS 3786 Kim Storm 3787 Original author of the NN news reader 3789 Finally, the present author gratefully acknowledges the vast amount 3790 of work put into previous drafts by the previous author: 3792 Stan Barber 3794 Normative References 3796 [ANSI1986] 3797 American National Standards Institute, "Coded Character 3798 Set - 7-bit American Standard Code for Information 3799 Interchange", ANSI X3.4, 1986. 3801 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 3802 Specification, Implementation", RFC 1305, March 1992. 3804 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3805 Requirement Levels", BCP 14, RFC 2119, March 1997. 3807 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3808 Specifications: ABNF", RFC 2234, November 1997. 3810 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 3811 10646", RFC 2279, January 1998. 3813 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 3814 2001. 3816 [RFC977] Kantor, B. and P. Lapsley, "Network News Transfer 3817 Protocol", RFC 977, February 1986. 3819 [ROBE1995] 3820 Robertson, R., "FAQ: Overview database / NOV General 3821 Information", January 1995. 3823 [TF.686-1] 3824 International Telecommunications Union - Radio, "Glossary, 3825 ITU-R Recommendation TF.686-1", ITU-R Recommendation 3826 TF.686-1, October 1997. 3828 Informative References 3830 [RFC1036] Horton, M. and R. Adams, "Standard for interchange of 3831 USENET messages", RFC 1036, December 1987. 3833 [RFC1869] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D. 3834 Crocker, "SMTP Service Extensions", STD 10, RFC 1869, 3835 November 1995. 3837 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 3838 Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext 3839 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3841 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 3842 June 1999. 3844 [SALZ1992] 3845 Salz, R., "Manual Page for wildmat(3) from the INN 1.4 3846 distribution, Revision 1.10", April 1992. 3848 Author's Address 3850 Clive D.W. Feather 3851 Thus plc 3852 322 Regents Park Road 3853 London N3 2QQ 3854 GB 3856 Phone: +44 20 8495 6138 3857 Fax: +44 870 051 9937 3858 URI: http://www.davros.org/ 3860 Appendix A. Future Directions 3862 It has been proposed that the response code range 6xx is used for 3863 multiline responses. While existing commands and extensions do not 3864 use this, it would at least limit the problem clients would face in 3865 dealing with an unknown response. 3867 Appendix B. Interaction with other specifications 3869 NNTP is most often used for transferring articles that conform to RFC 3870 1036 [RFC1036] (such articles are called "Usenet articles" here). It 3871 is also sometimes used for transferring email messages that conform 3872 to RFC 2822 [RFC2822] (such articles are called "email articles" 3873 here). In this situation, articles must conform both to this 3874 specification and to that other one; this appendix describes some 3875 relevant issues. 3877 B.1 Header folding 3879 NNTP allows a header line to be folded (by inserting a CRLF pair) 3880 before any space or TAB character. 3882 Both email and Usenet articles are required to have at least one 3883 octet other than space or TAB on each header line. Thus folding can 3884 only happen at one point in each sequence of consecutive spaces or 3885 TABs. Usenet articles are further required to have the header name, 3886 colon, and following space all on the first line; folding may only 3887 happen beyond that space. Finally, some non-conforming software will 3888 remove trailing spaces and TABs from a line. Therefore it might be 3889 inadvisable to fold a header after a space or TAB. 3891 For maximum safety, header lines SHOULD conform to the following 3892 syntax rather than that in Section 9.3. 3894 header = header-name ":" SP [header-content] CRLF 3895 header-content = [WS] 1*P-CHAR *( [CRLF] WS 1*P-CHAR ) 3897 B.2 Message-IDs 3899 Every article handled by an NNTP server MUST have a unique 3900 message-id. For the purposes of this specification, a message-id is 3901 an arbitrary opaque string that is merely needs to meet certain 3902 syntactic requirements and is just a way to refer to the article. 3904 Because there is a significant risk of old articles being reinjected 3905 into the global Usenet system, RFC 1036 [RFC1036] requires that 3906 message-ids are globally unique for all time. 3908 This specification states that message-ids are the same if and only 3909 if they consist of the same sequence of octets. Other specifications 3910 may define two different sequences as being equal because they are 3911 putting an interpretation on particular characters. RFC 2822 3912 [RFC2822] has a concept of "quoted" and "escaped" characters. It 3913 therefore considers the three messages-ids: 3915 3916 <"abcd"@example.com> 3917 <"ab\cd"@example.com> 3919 as being identical. Therefore an NNTP implementation handing email 3920 articles must ensure that only one of these three appears in the 3921 protocol and the other two are converted to it as and when necessary, 3922 such as when a client checks the results of a NEWNEWS command against 3923 an internal database of message-ids. 3925 This specification does not describe how the message-id of an article 3926 is determined; it may be deduced from the contents of the article or 3927 derived from some external source. If the server is also conforming 3928 to another specification that contains a definition of message-id 3929 compatible with this one, the server SHOULD use those message-ids. A 3930 common approach, and one that SHOULD be used for email and Usenet 3931 articles, is to extract the message-id from the contents of a header 3932 with name "Message-ID". This may not be as simple as copying the 3933 entire header contents; it may be necessary to strip off comments and 3934 undo quoting, or to reduce "equivalent" message-ids to a canonical 3935 form. 3937 If an article is obtained though the IHAVE command, there will be a 3938 message-id provided with the command. The server MAY either use it or 3939 determine one from the article contents. However, whichever it does 3940 it SHOULD ensure that, if the IHAVE command is repeated with the same 3941 argument and article, it will be recognised as a duplicate. 3943 If an article does not contain a message-id that the server can 3944 identify, it MUST synthesise one. This could, for example, be a 3945 simple sequence number or based on the date and time that the article 3946 arrived. When handling email or Usenet articles, a Message-ID header 3947 SHOULD be added to ensure global consistency and uniqueness. 3949 B.3 Article posting 3951 As far as NNTP is concerned, the POST and IHAVE commands provide the 3952 same basic facilities in a slightly different way. However they have 3953 rather different intentions. 3955 The IHAVE command is intended for transmitting conforming articles 3956 between a system of NNTP servers, with all articles perhaps also 3957 conforming to another specification (e.g. all articles are Usenet 3958 articles). It is expected that the client will have already done any 3959 necessary validation (or has in turn obtained the article from a 3960 third party which has done so); therefore the contents SHOULD be left 3961 unchanged. 3963 In contrast, the POST command is intended for use when an end-user is 3964 injecting a newly-created article into a such a system. The article 3965 being transferred might not be a conforming email or Usenet article, 3966 and the server is expected to validate it and, if necessary, convert 3967 it to the right form for onward distribution. It is often the case 3968 that this is done by a separate piece of software on the server 3969 installation. If so, the NNTP server SHOULD pass the incoming article 3970 to that software unaltered, making no attempt to filter characters, 3971 fold or limit lines, or otherwise process the incoming text. 3973 The POST command can fail in various ways and clients should be 3974 prepared to re-send an article. When doing so, however, it is often 3975 important to ensure - as far as possible - that the same message-id 3976 is allocated to both attempts so that the server, or other servers, 3977 can recognise the two articles as being duplicates. In the case of 3978 email or Usenet articles, therefore, the posted article SHOULD 3979 contain a header with name "Message-ID" and the contents of this 3980 header SHOULD be identical on each attempt. The server SHOULD ensure 3981 that two POSTed articles with the same contents for this header are 3982 recognised as identical and the same message-id allocated, whether or 3983 not those contents are suitable for use as the message-id. 3985 Intellectual Property Statement 3987 The IETF takes no position regarding the validity or scope of any 3988 intellectual property or other rights that might be claimed to 3989 pertain to the implementation or use of the technology described in 3990 this document or the extent to which any license under such rights 3991 might or might not be available; neither does it represent that it 3992 has made any effort to identify any such rights. Information on the 3993 IETF's procedures with respect to rights in standards-track and 3994 standards-related documentation can be found in BCP-11. Copies of 3995 claims of rights made available for publication and any assurances of 3996 licenses to be made available, or the result of an attempt made to 3997 obtain a general license or permission for the use of such 3998 proprietary rights by implementors or users of this specification can 3999 be obtained from the IETF Secretariat. 4001 The IETF invites any interested party to bring to its attention any 4002 copyrights, patents or patent applications, or other proprietary 4003 rights which may cover technology that may be required to practice 4004 this standard. Please address the information to the IETF Executive 4005 Director. 4007 Full Copyright Statement 4009 Copyright (C) The Internet Society (2003). All Rights Reserved. 4011 This document and translations of it may be copied and furnished to 4012 others, and derivative works that comment on or otherwise explain it 4013 or assist in its implementation may be prepared, copied, published 4014 and distributed, in whole or in part, without restriction of any 4015 kind, provided that the above copyright notice and this paragraph are 4016 included on all such copies and derivative works. However, this 4017 document itself may not be modified in any way, such as by removing 4018 the copyright notice or references to the Internet Society or other 4019 Internet organizations, except as needed for the purpose of 4020 developing Internet standards in which case the procedures for 4021 copyrights defined in the Internet Standards process must be 4022 followed, or as required to translate it into languages other than 4023 English. 4025 The limited permissions granted above are perpetual and will not be 4026 revoked by the Internet Society or its successors or assignees. 4028 This document and the information contained herein is provided on an 4029 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4030 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4031 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4032 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4033 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4035 Acknowledgement 4037 Funding for the RFC Editor function is currently provided by the 4038 Internet Society.