idnits 2.17.1 draft-ietf-nntpext-base-20.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 814 has weird spacing: '...abc,def the t...' == Line 2118 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 (October 16, 2003) is 7498 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 3861, but not defined == Missing Reference: 'S' is mentioned on line 3862, but not defined -- Looks like a reference, but probably isn't: '1' on line 2834 == Missing Reference: 'GMT' is mentioned on line 2242, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'ANSI1986' ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 977 (Obsoleted by RFC 3977) -- Obsolete informational reference (is this intentional?): RFC 1036 (Obsoleted by RFC 5536, RFC 5537) -- Obsolete informational reference (is this intentional?): RFC 1305 (Obsoleted by RFC 5905) -- 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) -- Obsolete informational reference (is this intentional?): RFC 2822 (Obsoleted by RFC 5322) Summary: 5 errors (**), 0 flaws (~~), 10 warnings (==), 10 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: April 15, 2004 October 16, 2003 6 Network News Transport Protocol 7 draft-ietf-nntpext-base-20 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 April 15, 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 20. 51 Author's Note 53 This draft is written in XML using an NNTP-specific DTD. Custom 54 software is used to convert this to RFC 2629 [RFC2629] format, and 55 then the public "xml2rfc" package to further reduce this to text, 56 nroff source, and HTML. 58 No perl was used in producing this draft. 60 Rights 62 UNIX is a registered trademark of the X/Open Company Ltd. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . 5 67 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . 6 68 3. Basic Concepts . . . . . . . . . . . . . . . . . . . . . 8 69 3.1 Commands and Responses . . . . . . . . . . . . . . . . . 8 70 3.2 Response Codes . . . . . . . . . . . . . . . . . . . . . 10 71 3.2.1 Generic Response Codes . . . . . . . . . . . . . . . . . 11 72 3.2.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . 13 73 3.3 Pipelining . . . . . . . . . . . . . . . . . . . . . . . 15 74 3.3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . 15 75 3.4 Articles . . . . . . . . . . . . . . . . . . . . . . . . 16 76 4. The WILDMAT format . . . . . . . . . . . . . . . . . . . 18 77 4.1 Wildmat syntax . . . . . . . . . . . . . . . . . . . . . 18 78 4.2 Wildmat semantics . . . . . . . . . . . . . . . . . . . 18 79 4.3 Extensions . . . . . . . . . . . . . . . . . . . . . . . 19 80 4.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . 19 81 5. Session administration commands . . . . . . . . . . . . 21 82 5.1 Initial Connection . . . . . . . . . . . . . . . . . . . 21 83 5.2 MODE READER . . . . . . . . . . . . . . . . . . . . . . 22 84 5.3 LIST EXTENSIONS . . . . . . . . . . . . . . . . . . . . 24 85 5.4 QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . 27 86 6. Article posting and retrieval . . . . . . . . . . . . . 28 87 6.1 Group and article selection . . . . . . . . . . . . . . 28 88 6.1.1 GROUP . . . . . . . . . . . . . . . . . . . . . . . . . 28 89 6.1.2 LAST . . . . . . . . . . . . . . . . . . . . . . . . . . 31 90 6.1.3 NEXT . . . . . . . . . . . . . . . . . . . . . . . . . . 32 91 6.2 Retrieval of articles and article sections . . . . . . . 34 92 6.2.1 ARTICLE . . . . . . . . . . . . . . . . . . . . . . . . 34 93 6.2.2 HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 37 94 6.2.3 BODY . . . . . . . . . . . . . . . . . . . . . . . . . . 39 95 6.2.4 STAT . . . . . . . . . . . . . . . . . . . . . . . . . . 41 96 6.3 Article posting . . . . . . . . . . . . . . . . . . . . 43 97 6.3.1 POST . . . . . . . . . . . . . . . . . . . . . . . . . . 43 98 6.3.2 IHAVE . . . . . . . . . . . . . . . . . . . . . . . . . 45 99 7. Information commands . . . . . . . . . . . . . . . . . . 49 100 7.1 DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 49 101 7.2 HELP . . . . . . . . . . . . . . . . . . . . . . . . . . 49 102 7.3 NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . 50 103 7.4 NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . 52 104 7.5 Time . . . . . . . . . . . . . . . . . . . . . . . . . . 53 105 7.5.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . 53 106 7.6 The LIST commands . . . . . . . . . . . . . . . . . . . 54 107 7.6.1 LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . . 54 108 7.6.2 LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . . 56 109 7.6.3 LIST DISTRIBUTIONS . . . . . . . . . . . . . . . . . . . 57 110 7.6.4 LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . . 58 111 7.6.5 LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . . 60 112 8. Framework for NNTP extensions . . . . . . . . . . . . . 62 113 8.1 Initial IANA registry . . . . . . . . . . . . . . . . . 64 114 8.2 Standard extensions . . . . . . . . . . . . . . . . . . 64 115 8.3 The LISTGROUP extension . . . . . . . . . . . . . . . . 64 116 8.3.1 LISTGROUP . . . . . . . . . . . . . . . . . . . . . . . 64 117 8.4 Article metadata . . . . . . . . . . . . . . . . . . . . 66 118 8.4.1 The :bytes metadata item . . . . . . . . . . . . . . . . 67 119 8.4.2 The :lines metadata item . . . . . . . . . . . . . . . . 67 120 8.5 The OVER extension . . . . . . . . . . . . . . . . . . . 67 121 8.5.1 OVER . . . . . . . . . . . . . . . . . . . . . . . . . . 68 122 8.5.2 LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . 72 123 8.6 The HDR extension . . . . . . . . . . . . . . . . . . . 74 124 8.6.1 HDR . . . . . . . . . . . . . . . . . . . . . . . . . . 74 125 8.6.2 LIST HEADERS . . . . . . . . . . . . . . . . . . . . . . 78 126 9. Augmented BNF Syntax for NNTP . . . . . . . . . . . . . 81 127 9.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . 81 128 9.2 Responses . . . . . . . . . . . . . . . . . . . . . . . 83 129 9.3 Articles . . . . . . . . . . . . . . . . . . . . . . . . 83 130 9.4 General non-terminals . . . . . . . . . . . . . . . . . 83 131 10. IANA Considerations . . . . . . . . . . . . . . . . . . 85 132 11. Security Considerations . . . . . . . . . . . . . . . . 86 133 11.1 Personal and Proprietary Information . . . . . . . . . . 86 134 11.2 Abuse of Server Log Information . . . . . . . . . . . . 86 135 11.3 Weak Authentication and Access Control . . . . . . . . . 86 136 11.4 DNS Spoofing . . . . . . . . . . . . . . . . . . . . . . 87 137 11.5 UTF-8 issues . . . . . . . . . . . . . . . . . . . . . . 87 138 11.6 Caching of LIST EXTENSIONS results . . . . . . . . . . . 88 139 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . 90 140 Normative References . . . . . . . . . . . . . . . . . . 92 141 Informative References . . . . . . . . . . . . . . . . . 93 142 Author's Address . . . . . . . . . . . . . . . . . . . . 93 143 A. Future Directions . . . . . . . . . . . . . . . . . . . 94 144 B. Interaction with other specifications . . . . . . . . . 95 145 B.1 Header folding . . . . . . . . . . . . . . . . . . . . . 95 146 B.2 Message-IDs . . . . . . . . . . . . . . . . . . . . . . 95 147 B.3 Article posting . . . . . . . . . . . . . . . . . . . . 96 148 C. Summary of Response Codes . . . . . . . . . . . . . . . 98 149 D. Formal specification of the standard extensions . . . . 103 150 D.1 The LISTGROUP extension . . . . . . . . . . . . . . . . 103 151 D.2 The OVER extension . . . . . . . . . . . . . . . . . . . 103 152 D.3 The HDR extension . . . . . . . . . . . . . . . . . . . 104 153 Intellectual Property and Copyright Statements . . . . . 106 155 1. Introduction 157 This document specifies the Network News Transport Protocol (NNTP), 158 which is used for the distribution, inquiry, retrieval, and posting 159 of Netnews articles using a reliable stream-based mechanism. For news 160 reading clients, NNTP enables retrieval of news articles that are 161 stored in a central database, giving subscribers the ability to 162 select only those articles they wish to read. 164 The Netnews model provides for indexing, cross-referencing, and 165 expiration of aged messages. For server-to-server interaction, NNTP 166 is designed for efficient transmission of Netnews articles over a 167 reliable full duplex communication channel. 169 Every attempt is made to ensure that the protocol specification in 170 this document is compatible with the version specified in RFC 977 171 [RFC977]. However, this version does not support the ill-defined 172 SLAVE command and permits four digit years to be specified in the 173 NEWNEWS and NEWGROUPS commands. It changes the default character set 174 to UTF-8 [RFC2279] instead of US-ASCII [ANSI1986]. It now requires 175 all articles to have a message-id, eliminating the "<0>" placeholder 176 used in RFC 977. It also extends the newsgroup name matching 177 capabilities already documented in RFC 977. 179 Generally, new functionality is made available using new commands. A 180 number of such commands (including some commands taken from RFC 2980 181 [RFC2980]) are now mandatory. Part of the new functionality involves 182 a mechanism to discover what new functionality is available to 183 clients from a server. This mechanism can also be used to add more 184 functionality as needs merit 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 argument is optional; 210 ellipsis... indicates that the argument 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 arguments (exactly one must be provided). 215 The name "message-id" for a command or response argument 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 argument indicates that it is a wildmat as 220 defined in Section 4. If the argument 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 Terms which might be read as specifying details of a client or server 247 implementation, such as "database", are used simply to ease 248 description. Providing that implementations conform to the protocol 249 and format specifications in this document, no specific technique is 250 mandated. 252 3. Basic Concepts 254 3.1 Commands and Responses 256 NNTP operates over any reliable data stream 8-bit-wide channel. 257 Initially, the server host starts the NNTP service by listening on a 258 TCP port; when running over TCP/IP, the official port for the NNTP 259 service is 119. When a client host wishes to make use of the service, 260 it MUST establish a TCP connection with the server host by connecting 261 to that host on the same port on which the server is listening. When 262 the connection is established, the NNTP server host MUST send a 263 greeting. The client host and server host then exchange commands and 264 responses (respectively) until the connection is closed or aborted. 266 The character set for all NNTP commands is UTF-8 [RFC2279]. Commands 267 in NNTP MUST consist of a keyword, which MAY be followed by one or 268 more arguments. A CRLF pair MUST terminate all commands. Multiple 269 commands MUST NOT be on the same line. Keywords MUST consist of 270 printable US-ASCII characters. Unless otherwise noted elsewhere in 271 this document, arguments SHOULD consist of printable US-ASCII 272 characters. Keywords and arguments MUST be each separated by one or 273 more space or TAB characters. Keywords MUST be at least three 274 characters and MUST NOT exceed 12 characters. Command lines MUST NOT 275 exceed 512 octets, which includes the terminating CRLF pair. The 276 arguments MUST NOT exceed 497 octets. A server MAY relax these limits 277 for commands defined in an extension. 279 Where this specification permits UTF-8 characters outside the range 280 U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark 281 (U+FEFF, encoding %xEF.BB.BF), and MUST use the Word Joiner (U+2060, 282 encoding %xE2.91.A0) for the meaning Zero Width No-Break Space, in 283 command lines and the initial lines of responses, and SHOULD apply 284 these same principles throughout. 286 Commands may have variants, using a second keyword immediately after 287 the first to indicate which variant is required. The only such 288 commands in this specification are LIST and MODE. Note that such 289 variants are sometimes referred to as if they were commands in their 290 own right: "the LIST ACTIVE" command should be read as shorthand for 291 "the ACTIVE variant of the LIST command". 293 Keywords are case-insensitive; the case of keywords for commands MUST 294 be ignored by the server. Command and response arguments are case or 295 language specific only when stated, either in this document or in 296 other relevant specifications. 298 An NNTP server MUST implement all the commands in this specification 299 except for those marked as optional and those in extensions. 301 Each response MUST start with a three-digit response code that is 302 sufficient to distinguish all responses. Certain valid responses are 303 defined to be multi-line; for all others, the response is contained 304 in a single line. The first or only line of the response MUST NOT 305 exceed 512 octets, which includes the response code and the 306 terminating CRLF pair; an extension MAY specify a greater maximum for 307 commands that it defines, but not for any other command. 309 All multi-line responses MUST adhere to the following format: 311 1. The response consists of a sequence of one or more "lines", each 312 being a stream of octets ending with a CRLF pair. Apart from 313 those line endings, the stream MUST NOT include the octets NUL, 314 LF, or CR. 316 2. The first such line contains the response code as with a single 317 line response. 319 3. If any subsequent line begins with the "termination octet" ("." 320 or %x2E), that line MUST be "byte-stuffed" by pre-pending an 321 additional termination octet to that line of the response. 323 4. The lines of the response MUST be followed by a terminating line 324 consisting of a single termination octet followed by a CRLF pair 325 in the normal way. Thus a multi-line response is always 326 terminated with the five octets CRLF "." CRLF (%x0D.0A.2E.0D.0A). 328 5. When interpreting a multi-line response, the "byte stuffing" MUST 329 be undone; i.e. the client MUST ensure that, in any line 330 beginning with the termination octet followed by octets other 331 than a CRLF pair, that initial termination octet is disregarded. 333 6. Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT 334 be considered part of the multi-line response; i.e. the client 335 MUST ensure that any line beginning with the termination octet 336 followed immediately by a CRLF pair is disregarded; (the first 337 CRLF pair of the terminating CRLF "." CRLF is, of course, part of 338 the last line of the response). 340 Note that texts using an encoding (such as UTF-16 or UTF-32) that may 341 contain the octets NUL, LF, or CR other than a CRLF pair cannot be 342 reliably conveyed in the above format. However, except when stated 343 otherwise, this specification does not require the content to be 344 UTF-8 and it is possible for octets above and below 128 to be mixed 345 arbitrarily. 347 This document does not place any limit on the length of a subsequent 348 line in a multi-line response. However, the standards that define the 349 format of articles may do so. 351 An NNTP server MAY have an inactivity autologout timer. Such a timer 352 SHOULD be of at least three minutes duration, with the exception that 353 there MAY be a shorter limit on how long the server is willing to 354 wait for the first command from the client. The receipt of any 355 command from the client during the timer interval SHOULD suffice to 356 reset the autologout timer. Similarly, the receipt of any significant 357 amount of data from the client while in the midst of sending a 358 multi-line message to the server (such as during a POST or IHAVE 359 command) SHOULD suffice to reset the autologout timer. When the timer 360 expires, the server SHOULD close the TCP connection without sending 361 any response to the client. 363 3.2 Response Codes 365 Each response MUST begin with a three-digit status indicator. These 366 are status reports from the server and indicate the response to the 367 last command received from the client. 369 The first digit of the response broadly indicates the success, 370 failure, or progress of the previous command: 372 1xx - Informative message. 373 2xx - Command completed OK. 374 3xx - Command OK so far; send the rest of it. 375 4xx - Command was syntactically correct but failed for some 376 reason. 377 5xx - Command unknown, unsupported, unavailable, or syntax error. 379 The next digit in the code indicates the function response category: 381 x0x - Connection, setup, and miscellaneous messages 382 x1x - Newsgroup selection 383 x2x - Article selection 384 x3x - Distribution functions 385 x4x - Posting 386 x8x - Reserved for authentication and privacy extensions 387 x9x - Reserved for private use (non-standard extensions) 389 Certain responses contain arguments such as numbers and names in 390 addition to the status indicator. In those cases, to simplify 391 interpretation by the client the number and type of such arguments is 392 fixed for each response code, as is whether or not the code 393 introduces a multi-line response. Any extension MUST follow this 394 principle as well, but note that, for historical reasons, the 211 395 response code is an exception to this. In all other cases, the client 396 MUST only use the status indicator itself to determine the nature of 397 the response. The exact response codes that can be returned by any 398 given command are detailed in the description of that command. 400 Arguments MUST be separated from the numeric status indicator and 401 from each other by a single space. All numeric arguments MUST be in 402 base 10 (decimal) format, and MAY have leading zeros. String 403 arguments MUST contain at least one character and MUST NOT contain 404 TAB, LF, CR, or space. The server MAY add any text after the response 405 code or last argument as appropriate, and the client MUST NOT make 406 decisions based on this text. Such text MUST be separated from the 407 numeric status indicator or the last argument by at least one space. 409 The server MUST respond to any command with the appropriate generic 410 response (given in Section 3.2.1) if it represents the situation. 411 Otherwise, each recognized command MUST return one of the response 412 codes specifically listed in its description or in an extension. A 413 server MAY provide extensions to this specification, including new 414 commands, new variants or features of existing commands, and other 415 ways of changing the internal state of the server. However, the 416 server MUST NOT produce any other responses to a client that does not 417 invoke any of the additional features. (Therefore a client that 418 restricts itself to this specification will only receive the 419 responses that are listed.) 421 If a client receives an unexpected response, it SHOULD use the first 422 digit of the response to determine the result. For example, an 423 unexpected 2xx should be taken as success and an unexpected 4xx or 424 5xx as failure. 426 Response codes not specified in this document MAY be used for any 427 installation-specific additional commands also not specified. These 428 SHOULD be chosen to fit the pattern of x9x specified above. 430 Neither this document nor any extension registered with IANA (see 431 Section 8) will specify any response codes of the x9x pattern. 432 (Implementers of extensions are accordingly cautioned not to use such 433 responses for extensions that may subsequently be submitted for 434 registration.) 436 3.2.1 Generic Response Codes 438 The server MUST respond to any command with the appropriate one of 439 the following generic responses if it represents the situation. 441 If the command is not recognized, or it is an optional command or 442 extension that is not implemented by the server, the response code 443 500 MUST be returned. 445 If there is a syntax error in the arguments of a recognized command, 446 including the case where more arguments are provided than the command 447 specifies or the command line is longer than the server accepts, the 448 response code 501 MUST be returned. The line MUST NOT be truncated or 449 split and then interpreted. Note that where a command has variants 450 depending on a second keyword (e.g. LIST ACTIVE and LIST NEWSGROUPS), 451 then 501 MUST be used when the base command is implemented but the 452 requested variant is not, and 500 MUST be used only when the base 453 command itself is not implemented. 455 If the server experiences an internal fault or problem that means it 456 is unable to carry out the command (for example, a necessary file is 457 missing or a necessary service could not be contacted), the response 458 code 403 MUST be returned. If the server recognises the command but 459 does not provide an optional feature (for example because it does not 460 store the required information), or only handles a subset of 461 legitimate cases (see the HDR command (Section 8.6.1) for an 462 example), the response code 503 MUST be returned. Note that where a 463 command is optional (e.g. LIST ACTIVE.TIMES) and is not provided by a 464 server, this MAY be treated as an unimplemented command (response 465 code 500 or 501 as appropriate) or as a working command where the 466 information is not available (response code 503). 468 If the client is not authorized to use the specified facility when 469 the server is in its current state, then the appropriate one of the 470 following response codes MUST be used. 472 502: it is necessary to terminate the connection and start a new one 473 with the appropriate authority before the command can be used. 474 Note that the server MUST NOT close the TCP connection immediately 475 after a 502 response except at the initial connection (Section 476 5.1) and with the MODE READER (Section 5.2) command. See also the 477 latter command for historical usage of this response. 479 480: the client must authenticate itself to the server (that is, 480 provide information as to the identity of the client) before the 481 facility can be used. This will involve the use of an 482 authentication extension. 484 483: the client must negotiate appropriate privacy protection on the 485 connection. This will involve the use of a privacy extension. 487 401: the client must change the state of the connection in some other 488 manner. The first argument of the response MUST be the 489 extension-label (see Section 8) of the extension (which may be a 490 private extension) that provides the necessary mechanism, or 491 "MODE-READER" if it is necessary to use the MODE READER (Section 492 5.2) command. 494 If the server has to terminate the connection for some reason, it 495 MUST give a 400 response code to the next command and then 496 immediately close the TCP connection. 498 The client MUST be prepared to receive any of these responses for any 499 command (except, of course, that the server MUST NOT generate a 500 500 response code for mandatory commands). 502 3.2.1.1 Examples 504 Example of an unknown command: 506 [C] MAIL 507 [S] 500 Unknown command 509 Example of an unsupported extension: 511 [C] LIST EXTENSIONS 512 [S] 202 Extensions supported: 513 [S] LISTGROUP 514 [S] . 515 [C] OVER 516 [S] 500 Unknown command 518 Example of an unsupported variant: 520 [C] MODE POSTER 521 [S] 501 Unknown MODE option 523 Example of a syntax error: 525 [C] ARTICLE a.message.id@no.angle.brackets 526 [S] 501 Syntax error 528 Example of an overlong command line: 530 [C] HEAD 53 54 55 531 [S] 501 Too many arguments 533 Example of a bad wildmat: 535 [C] LIST ACTIVE u[ks].* 536 [S] 501 Syntax error 538 Example of an attempt to access a facility not available to this 539 connection: 541 [C] MODE READER 543 [S] 200 Reader mode, posting permitted 544 [C] IHAVE 545 [S] 502 Permission denied 547 Example of an attempt to access a facility requiring authentication: 549 [C] GROUP secret.group 550 [S] 480 Permission denied 552 followed by a successful attempt following such authentication: 554 [C] XSECRET fred flintstone 555 [S] 290 Password for fred accepted 556 [C] GROUP secret.group 557 [S] 211 5 1 20 secret.group selected 559 Example of an attempt to access a facility requiring privacy: 561 [C] GROUP secret.group 562 [S] 483 Secure connection required 563 [C] XENCRYPT 564 [Client and server negotiate encryption on the link] 565 [S] 283 Encrypted link established 566 [C] GROUP secret.group 567 [S] 211 5 1 20 secret.group selected 569 Example of a need to change mode before using a facility: 571 [C] GROUP binary.group 572 [S] 401 XHOST Not on this virtual host 573 [C] XHOST binary.news.example.org 574 [S] 290 binary.news.example.org virtual host selected 575 [C] GROUP binary.group 576 [S] 211 5 1 77 binary.group selected 578 Example of a temporary failure: 580 [C] GROUP archive.local 581 [S] 403 Archive server temporarily offline 583 Example of the server needing to close down immediately: 585 [C] ARTICLE 123 586 [S] 400 Power supply failed, running on UPS 587 [Server closes connection.] 589 3.3 Pipelining 591 NNTP is designed to operate over a reliable bi-directional connection 592 such as TCP. Therefore, if a command does not depend on the response 593 to the previous one, it should not matter if it is sent before that 594 response is received. Doing this is called "pipelining". However, 595 certain server implementations throw away all text received from the 596 client following certain commands before sending their response. If 597 this happens, pipelining will be affected because one or more 598 commands will have been ignored or misinterpreted, and the client 599 will be matching the wrong responses to each command. Since there are 600 significant benefits to pipelining, but also circumstances where it 601 is reasonable or common for servers to behave in the above manner, 602 this document puts certain requirements on both clients and servers. 604 Except where stated otherwise, a client MAY use pipelining. That is, 605 it may send a command before receiving the response for the previous 606 command. The server MUST allow pipelining and MUST NOT throw away any 607 text received after a command. Irrespective of whether or not 608 pipelining is used, the server MUST process commands in the order 609 they are sent. 611 If the specific description of a command says it "MUST NOT be 612 pipelined", that command MUST end any pipeline of commands. That is, 613 the client MUST NOT send any following command until receiving the 614 CRLF at the end of the response from the command. The server MAY 615 ignore any data received after the command and before the CRLF at the 616 end of the response is sent to the client. 618 The initial connection must not be part of a pipeline; that is, the 619 client MUST NOT send any command until receiving the CRLF at the end 620 of the greeting. 622 If the client uses blocking system calls to send commands, it MUST 623 ensure that the amount of text sent in pipelining does not cause a 624 deadlock between transmission and reception. The amount of text 625 involved will depend on window sizes in the transmission layer, and 626 is typically 4k octets for TCP. 628 3.3.1 Examples 630 Example of correct use of pipelining: 632 [C] GROUP misc.test 633 [C] STAT 634 [C] NEXT 635 [S] 211 1234 3000234 3002322 misc.test 636 [S] 223 3000234 <45223423@example.com> retrieved 638 [S] 223 3000237 <668929@example.org> retrieved 640 Example of incorrect use of pipelining (the MODE READER command may 641 not be pipelined): 643 [C] GROUP misc.test 644 [C] MODE READER 645 [C] DATE 646 [C] NEXT 647 [S] 211 1234 3000234 3002322 misc.test 648 [S] 200 Server ready, posting allowed 649 [S] 223 3000237 <668929@example.org> retrieved 651 The DATE command has been thrown away by the server and so there is 652 no 111 response to match it. 654 3.4 Articles 656 NNTP is intended to transfer articles between clients and servers. 657 For the purposes of this specification, articles are required to 658 conform to the rules in this section and clients and servers MUST 659 correctly process any article received from the other that does so. 660 Note that this requirement applies only to the contents of 661 communications over NNTP; it does not prevent the client or server 662 from subsequently rejecting an article for reasons of local policy. 663 Also see Appendix B for further restrictions on the format of 664 articles in some uses of NNTP. 666 An article consists of two parts: the headers and the body. They are 667 separated by a single empty line, or in other words by two 668 consecutive CRLF pairs (if there is more than one empty line, the 669 second and subsequent ones are part of the body). In order to meet 670 the general requirements of NNTP, an article MUST NOT include the 671 octet NUL, MUST NOT contain the octets LF and CR other than as part 672 of a CRLF pair, and MUST end with a CRLF pair. This specification 673 puts no further restrictions on the body; in particular, it MAY be 674 empty. 676 The headers of an article consist of one or more header lines. Each 677 header line consists of a header name, a colon, a space, the header 678 content, and a CRLF in that order. The name consists of one or more 679 printable US-ASCII characters other than colon and, for the purposes 680 of this specification, is not case sensitive. There MAY be more than 681 one header line with the same name. The content MUST NOT contain CRLF 682 but is otherwise unrestricted; in particular, it MAY be empty. A 683 header may be "folded"; that is, a CRLF pair may be placed before any 684 TAB or space in the line; there MUST still be some other octet 685 between any two CRLF pairs in a header line. (Note that folding means 686 that the header line occupies more than one line when displayed or 687 transmitted; nevertheless it is still referred to as "a" header 688 line.) The presence or absence of folding does not affect the meaning 689 of the header line; that is, the CRLF pairs introduced by folding are 690 not considered part of the header value. Header lines SHOULD NOT be 691 folded before the space after the colon that follows the header name, 692 and should include at least one octet other than %x09 or %x20 between 693 CRLF pairs. However, if an article has been received from elsewhere 694 with one of these, clients and servers MAY transfer it to the other 695 without re-folding it. 697 Each article MUST have a unique message-id; two articles offered by 698 an NNTP server MUST NOT have the same message-id. For the purposes of 699 this specification, message-ids are opaque strings that MUST meet the 700 following requirements: 702 o A message-id MUST begin with "<" and end with ">", and MUST NOT 703 contain the latter except at the end. 705 o A message-id MUST be between 3 and 250 octets in length. 707 o A message-id MUST NOT contain octets other than printable US-ASCII 708 characters. 710 Two message-ids are the same if and only if they consist of the same 711 sequence of octets. 713 This specification does not describe how the message-id of an article 714 is determined. If the server does not have any way to determine a 715 message-id from the article itself, it MUST synthesise one (this 716 specification does not require the article to be changed as a 717 result). 719 4. The WILDMAT format 721 The WILDMAT format described here is based on the version first 722 developed by Rich Salz [SALZ1992], which in turn was derived from the 723 format used in the UNIX "find" command to articulate file names. It 724 was developed to provide a uniform mechanism for matching patterns in 725 the same manner that the UNIX shell matches filenames. 727 4.1 Wildmat syntax 729 A wildmat is described by the following ABNF [RFC2234] syntax (note 730 that this syntax contains ambiguities and special cases described at 731 the end): 733 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 735 wildmat-pattern = 1*wildmat-item 737 wildmat-item = wildmat-exact / wildmat-wild 739 wildmat-exact = %x21-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 740 UTF8-non-ascii ; exclude * , ? [ \ ] 742 wildmat-wild = "*" / "?" 744 UTF8-non-ascii is defined in Section 9. 746 This syntax must be interpreted subject to the following rule: 748 Where a wildmat-pattern is not immediately preceded by "!", it shall 749 not begin with a "!". 751 Note: the characters \ , [ and ] are not allowed in wildmats, while * 752 and ? are always wildcards. This should not be a problem since these 753 characters cannot occur in newsgroup names, which is the only current 754 use of wildmats. Backslash is commonly used to suppress the special 755 meaning of characters while brackets are used to introduce sets. 756 However, these usages are not universal and interpretation of these 757 characters in the context of UTF-8 strings is both potentially 758 complex and differs from existing practice, so they were omitted from 759 this specification. A future extension to this specification may 760 provide semantics for these characters. 762 4.2 Wildmat semantics 764 A wildmat is tested against a string, and either matches or does not 765 match. To do this, each constituent wildmat-pattern is matched 766 against the string and the rightmost pattern that matches is 767 identified. If that wildmat-pattern is not preceded with "!", the 768 whole wildmat matches. If it is preceded by "!", or if no 769 wildmat-pattern matches, the whole wildmat does not match. 771 For example, consider the wildmat "a*,!*b,*c*": 773 the string "aaa" matches because the rightmost match is with "a*" 775 the string "abb" does not match because the rightmost match is 776 with "*b" 778 the string "ccb" matches because the rightmost match is with "*c*" 780 the string "xxx" does not match because no wildmat-pattern matches 782 A wildmat-pattern matches a string if the string can be broken into 783 components, each of which matches the corresponding wildmat-item in 784 the pattern; the matches must be in the same order, and the whole 785 string must be used in the match. The pattern is "anchored"; that is, 786 the first and last characters in the string must match the first and 787 last item respectively (unless that item is an asterisk matching zero 788 characters). 790 A wildmat-exact matches the same character (which may be more than 791 one octet in UTF-8). 793 "?" matches exactly one character (which may be more than one octet). 795 "*" matches zero or more characters. It can match an empty string, 796 but it cannot match a subsequence of a UTF-8 sequence that is not 797 aligned to the character boundaries. 799 4.3 Extensions 801 An NNTP server or extension MAY extend the syntax or semantics of 802 wildmats provided that all wildmats that meet the requirements of 803 Section 4.1 have the meaning ascribed to them by Section 4.2. Future 804 editions of this document may also extend wildmats. 806 4.4 Examples 808 In these examples, $ and @ are used to represent the two octets %xC2 809 and %xA3 respectively; $@ is thus the UTF-8 encoding for the pound 810 sterling symbol, shown as # in the descriptions. 812 Wildmat Description of strings that match 813 abc the one string "abc" 814 abc,def the two strings "abc" and "def" 815 $@ the one character string "#" 816 a* any string that begins with "a" 817 a*b any string that begins with "a" and ends with "b" 818 a*,*b any string that begins with "a" or ends with "b" 819 a*,!*b any string that begins with "a" and does not end with 820 "b" 821 a*,!*b,c* any string that begins with "a" and does not end with 822 "b", and any string that begins with "c" no matter 823 what it ends with 824 a*,c*,!*b any string that begins with "a" or "c" and does not 825 end with "b" 826 ?a* any string with "a" as its second character 827 ??a* any string with "a" as its third character 828 *a? any string with "a" as its penultimate character 829 *a?? any string with "a" as its antepenultimate character 831 5. Session administration commands 833 5.1 Initial Connection 835 5.1.1 Usage 837 Responses 838 200 Service available, posting allowed 839 201 Service available, posting prohibited 840 400 Service temporarily unavailable [1] 841 502 Service permanently unavailable [1] 843 These are the only valid response codes for the initial greeting; 844 the server MUST not return any other generic response code. 846 [1] Following a 400 or 502 response the server MUST immediately close 847 the connection. 849 5.1.2 Description 851 There is no command presented by the client upon initial connection 852 to the server. The server MUST present an appropriate response code 853 as a greeting to the client. This response informs the client whether 854 service is available and whether the client is permitted to post. 856 If the server will accept further commands from the client including 857 POST, the server MUST present a 200 greeting code. If the server will 858 accept further commands from the client, but it is not authorized to 859 post articles using the POST command, the server MUST present a 201 860 greeting code. 862 Otherwise the server MUST present a 400 or 502 greeting code and then 863 immediately close the connection. 502 MUST be used if the client is 864 not permitted under any circumstances to interact with the server and 865 400 otherwise. 867 5.1.3 Examples 869 Example of a normal connection from an authorized client which then 870 terminates the session (see Section 5.4): 872 [Initial TCP connection setup completed.] 873 [S] 200 NNTP Service Ready, posting permitted 874 [C] QUIT 875 [S] 205 NNTP Service exits normally 876 [Server closes connection.] 878 Example of a normal connection from an authorized client that is not 879 permitted to post; it also immediately terminates the session: 881 [Initial TCP connection setup completed.] 882 [S] 201 NNTP Service Ready, posting prohibited 883 [C] QUIT 884 [S] 205 NNTP Service exits normally 885 [Server closes connection.] 887 Example of a normal connection from an unauthorized client: 889 [Initial TCP connection setup completed.] 890 [S] 502 NNTP Service permanently unavailable 891 [Server closes connection.] 893 Example of a connection from a client where the server is unable to 894 provide service: 896 [Initial TCP connection setup completed.] 897 [S] 400 NNTP Service temporarily unavailable 898 [Server closes connection.] 900 5.2 MODE READER 902 5.2.1 Usage 904 This command MUST NOT be pipelined. 906 Syntax 907 MODE READER 909 Responses 910 200 Posting allowed 911 201 Posting prohibited 912 400 Service temporarily unavailable [1] 913 502 Service permanently unavailable [1] 915 [1] Following a 400 or 502 response the server MUST immediately close 916 the connection. 918 5.2.2 Description 920 MODE READER SHOULD be sent by any client that intends to use any 921 command in this specification (including Section 8) other than IHAVE, 922 HEAD, STAT, LIST ACTIVE, or LIST EXTENSIONS; other extensions MAY 923 also require MODE READER to be used. Servers MAY require that this 924 command be issued before any commands other than the above are sent 925 and MAY reject such commands until after a MODE READER command has 926 been sent. Such rejections SHOULD use response code 401 with argument 927 "MODE-READER", but for historical reasons response code 502 MAY be 928 used, even though this situation does not meet the conditions for 929 that response. 931 Once MODE READER is sent, IHAVE (and any related extensions) MAY no 932 longer be permitted, even if it were permitted before the MODE READER 933 command. The results of LIST EXTENSIONS MAY be different following a 934 MODE READER command than prior to the issuing of that command. 936 The server MUST return a response using the same codes as the initial 937 greeting (as described in Section 5.1.1) to indicate its ability to 938 provide reading service to the client. Note that the response need 939 not be the same as the one presented during the initial greeting. 941 Servers are encouraged to not require this command even though 942 clients SHOULD send it when appropriate. It is present to support 943 some news architectures that switch between modes based on whether a 944 given connection is a peer-to-peer connection with another server or 945 a news reading client. 947 5.2.3 Examples 949 Example of use of the MODE READER command by an authorized client 950 which then terminates the session (see Section 5.4): 952 [C] MODE READER 953 [S] 200 NNTP Service Ready, posting permitted 954 [C] QUIT 955 [S] 205 NNTP Service exits normally 956 [Server closes connection.] 958 Example of use of the MODE READER command by an authorized client 959 that is not permitted to post; it also immediately terminates the 960 session: 962 [C] MODE READER 963 [S] 201 NNTP Service Ready, posting prohibited 964 [C] QUIT 965 [S] 205 NNTP Service exits normally 966 [Server closes connection.] 968 Example of use of MODE READER by a client not authorized to receive 969 service from the server as a news reader: 971 [C] MODE READER 973 [S] 502 NNTP Service permanently unavailable 974 [Server closes connection.] 976 Example of a connection from any client where the server is 977 temporarily unable to provide news reader service: 979 [C] MODE READER 980 [S] 400 NNTP Service temporarily unavailable 981 [Server closes connection.] 983 Example of a facility that requires MODE READER before use, using the 984 preferred response: 986 [C] GROUP misc.test 987 [S] 401 MODE-READER currently in peering mode 988 [C] MODE READER 989 [S] 200 NNTP Service Ready, posting permitted 990 [C] GROUP misc.test 991 [S] 211 1234 3000234 3002322 misc.test 993 Example of a facility that requires MODE READER before use, using the 994 historical but deprecated response: 996 [C] GROUP misc.test 997 [S] 502 Not available in peering mode 998 [C] MODE READER 999 [S] 200 NNTP Service Ready, posting permitted 1000 [C] GROUP misc.test 1001 [S] 211 1234 3000234 3002322 misc.test 1003 Example of a facility that cannot be used after MODE READER: 1005 [C] IHAVE 1006 [S] 435 Duplicate 1007 [C] MODE READER 1008 [S] 200 Reader mode, posting permitted 1009 [C] IHAVE 1010 [S] 502 Permission denied 1012 5.3 LIST EXTENSIONS 1014 5.3.1 Usage 1016 This command is optional. 1018 Syntax 1019 LIST EXTENSIONS 1021 Responses 1022 202 Extension list follows (multiline) 1023 402 Server has no extensions 1025 5.3.2 Description 1027 The LIST EXTENSIONS command allows a client to determine which 1028 extensions are supported by the server at any given time. See Section 1029 8 for further discussion of extensions. 1031 This command MUST be implemented by any server that implements any 1032 extensions defined in this document or any other extension in the 1033 IANA registry, and is optional otherwise. 1035 This command MAY be issued at anytime during a session. It is not 1036 required that the client issues this command before attempting to 1037 make use of any extension. The response generated by this command MAY 1038 change during a session because of other state information (which in 1039 turn may be changed by the effects of other commands). An NNTP client 1040 is only able to get the current and correct information concerning 1041 available extensions at any point during a session by issuing a LIST 1042 EXTENSIONS command at that point of that session and processing the 1043 response, and the server MUST ensure that those extensions currently 1044 listed in the returned information are available. Therefore, if an 1045 extension (including those in Section 8) is only available before or 1046 after a MODE READER command, the LIST EXTENSIONS command MUST only 1047 include the extension in that situation. Similarly, if only some of 1048 the commands in an extension will be available, or if the behaviour 1049 of the extension will change in some other manner, before or after a 1050 MODE READER command, this MUST be indicated by different arguments to 1051 the extension-label in the results of LIST EXTENSIONS in each 1052 situation. 1054 While some extensions are likely to be always available or never 1055 available, others will "appear" and "disappear" depending on server 1056 state changes within the session or external events between sessions. 1057 An NNTP client may cache the results of this command, but MUST NOT 1058 rely on the correctness of any cached results, whether from earlier 1059 in this session or from a previous session, MUST cope gracefully with 1060 the cached status being out of date, and SHOULD (if caching results) 1061 provide a way to force the cached information to be refreshed. 1062 Furthermore, a client MUST NOT use cached results in relation to 1063 security, privacy, and authentication extensions. See Section 11.6 1064 for further discussion of this topic. 1066 The list of extensions is returned as a multi-line response following 1067 the 202 response code. Each extension is listed on a separate line; 1068 the line MUST begin with an extension-label and optionally one or 1069 more arguments (separated by single spaces). The extension-label and 1070 the meaning of the arguments are specified as part of the definition 1071 of the extension. The extension-label is a string of 1 to 12 US-ASCII 1072 letters and MUST be in uppercase. Arguments are strings of 1 or more 1073 printable UTF-8 characters (that is, either printable US-ASCII 1074 characters or any UTF-8 sequence outside the US-ASCII range, but not 1075 space or TAB). 1077 The server MUST NOT list the same extension twice in the response, 1078 and MUST list all supported extensions. The order in which the 1079 extensions are listed is not significant. The server need not even 1080 consistently return the same order. If the server does not support 1081 any extensions, it MUST return an empty list. The 402 response code 1082 is documented for historic reasons only; clients SHOULD handle it 1083 gracefully, but servers MUST NOT generate it. 1085 Following a generic failure response, such as 403, an extension might 1086 still be available, and the client MAY attempt to use it. 1088 5.3.3 Examples 1090 Example of a successful response: 1092 [C] LIST EXTENSIONS 1093 [S] 202 Extensions supported: 1094 [S] OVER 1095 [S] HDR 1096 [S] LISTGROUP 1097 [S] . 1099 The particular extensions shown here are simply examples of what 1100 might be defined in other places, and no particular meaning should be 1101 attributed to them. 1103 Example where no extensions are available: 1105 [C] LIST EXTENSIONS 1106 [S] 202 Extensions supported: 1107 [S] . 1109 Example from a non-conforming server which indicates "no extensions 1110 available" using the 402 response code: 1112 [C] LIST EXTENSIONS 1113 [S] 402 Server has no extensions 1115 5.4 QUIT 1117 5.4.1 Usage 1119 Syntax 1120 QUIT 1122 Responses 1123 205 Connection closing 1125 5.4.2 Description 1127 The client uses the QUIT command to terminate the session. The server 1128 MUST acknowledge the QUIT command and then close the connection to 1129 the client. This is the preferred method for a client to indicate 1130 that it has finished all its transactions with the NNTP server. 1132 If a client simply disconnects (or the connection times out or some 1133 other fault occurs), the server MUST gracefully cease its attempts to 1134 service the client, disconnecting from its end if necessary. 1136 5.4.3 Examples 1138 [C] QUIT 1139 [S] 205 closing connection 1140 [Server closes connection.] 1142 6. Article posting and retrieval 1144 News reading clients have available a variety of mechanisms to 1145 retrieve articles via NNTP. The news articles are stored and indexed 1146 using three types of keys. One key is the message-id of an article. 1147 Another key is composed of the newsgroup name and the article number 1148 within that newsgroup. That key MUST be unique to a particular server 1149 (there will be only one article with that number within a particular 1150 newsgroup), but is not required to be globally unique. Additionally, 1151 because the same article can be cross-posted to multiple newsgroups, 1152 there may be multiple keys that point to the same article on the same 1153 server. The final key is the arrival timestamp, giving the time that 1154 the article arrived at the server. 1156 The server MUST ensure that article numbers are issued in order of 1157 arrival timestamp; that is, articles arriving later MUST have higher 1158 numbers than those that arrive earlier. The server SHOULD allocate 1159 the next sequential unused number to each new article. 1161 Article numbers MUST lie between 1 and 4,294,967,295 inclusive. The 1162 client and server SHOULD NOT use leading zeroes in specifying article 1163 numbers, and MUST NOT use more than 16 digits. In some situations, 1164 the value zero replaces an article number to show some special 1165 situation. 1167 6.1 Group and article selection 1169 The following commands are used to set the "current selected 1170 newsgroup" and the "current article number", which are used by 1171 various commands. At the start of an NNTP session, both of these 1172 values are set to the special value "invalid". 1174 6.1.1 GROUP 1176 6.1.1.1 Usage 1178 Syntax 1179 GROUP group 1181 Responses 1182 211 number low high group Group successfully selected 1183 411 No such newsgroup 1185 Parameters 1186 group = name of newsgroup 1187 number = estimated number of articles in the group 1188 low = reported low water mark 1189 high = reported high water mark 1191 6.1.1.2 Description 1193 The required argument is the name of the newsgroup to be selected 1194 (e.g. "news.software.b"). A list of valid newsgroups may be obtained 1195 by using the LIST ACTIVE command (see Section 7.6.1). 1197 The successful selection response will return the article numbers of 1198 the first and last articles in the group at the moment of selection 1199 (these numbers are referred to as the "reported low water mark" and 1200 the "reported high water mark"), and an estimate of the number of 1201 articles in the group currently available. 1203 If the group is not empty, the estimate MUST be at least the actual 1204 number of articles available, and MUST be no greater than one more 1205 than the difference between the reported low and high water marks. 1206 (Some implementations will actually count the number of articles 1207 currently stored. Others will just subtract the low water mark from 1208 the high water mark and add one to get an estimate.) 1210 If the group is empty, one of the following three situations will 1211 occur. Clients MUST accept all three cases; servers MUST NOT 1212 represent an empty group in any other way. 1214 o The high water mark will be one less than the low water mark, and 1215 the estimated article count will be zero. Servers SHOULD use this 1216 method to show an empty group. This is the only time that the high 1217 water mark can be less than the low water mark. 1219 o All three numbers will be zero. 1221 o The high water mark is greater than or equal to the low water 1222 mark. The estimated article count might be zero or non-zero; if 1223 non-zero, the same requirements apply as for a non-empty group. 1225 The set of articles in a group may change after the GROUP command is 1226 carried out. That is: 1228 o articles may be removed from the group 1230 o articles may be reinstated in the group with the same article 1231 number, but those articles MUST have numbers no less than the 1232 reported low water mark (note that this is a reinstatement of the 1233 previous article, not a new article reusing the number) 1235 o new articles may be added with article numbers greater than the 1236 reported high water mark (if an article that was the one with the 1237 highest number has been removed, the next new article will not 1238 have the number one greater than the reported high water mark) 1240 Except when the group is empty and all three numbers are zero, 1241 whenever a subsequent GROUP command for the same newsgroup is issued, 1242 either by the same client or a different client, the reported low 1243 water mark in the response MUST be no less than that in any previous 1244 response for that newsgroup sent to any client. The client may make 1245 use of the low water mark to remove all remembered information about 1246 articles with lower numbers, as these will never recur. This includes 1247 the situation when the high water mark is one less than the low water 1248 mark. No similar assumption can be made about the high water mark, as 1249 this can decrease if an article is removed, and then increase again 1250 if it is reinstated or if new articles arrive. 1252 When a valid group is selected by means of this command, the current 1253 selected newsgroup MUST be set to that group and the current article 1254 number MUST be set to the first article in the group. If an empty 1255 newsgroup is selected, the current article pointer is made invalid. 1256 If an invalid group is specified, the current selected newsgroup and 1257 current article number MUST NOT be changed. 1259 The GROUP command (or the LISTGROUP command, if implemented) MUST be 1260 used by a client and a successful response received before any other 1261 command is used that depends on the value of the current selected 1262 newsgroup or current article number. 1264 If the group specified is not available on the server, a 411 response 1265 MUST be returned. 1267 6.1.1.3 Examples 1269 Example for a group known to the server: 1271 [C] GROUP misc.test 1272 [S] 211 1234 3000234 3002322 misc.test 1274 Example for a group unknown to the server: 1276 [C] GROUP example.is.sob.bradner.or.barber 1277 [S] 411 example.is.sob.bradner.or.barber is unknown 1279 Example of an empty group using the preferred response: 1281 [C] GROUP example.currently.empty.newsgroup 1282 [S] 211 0 4000 3999 example.currently.empty.newsgroup 1284 Example of an empty group using an alternative response: 1286 [C] GROUP example.currently.empty.newsgroup 1287 [S] 211 0 0 0 example.currently.empty.newsgroup 1289 Example of an empty group using a different alternative response: 1291 [C] GROUP example.currently.empty.newsgroup 1292 [S] 211 0 4000 4321 example.currently.empty.newsgroup 1294 6.1.2 LAST 1296 6.1.2.1 Usage 1298 Syntax 1299 LAST 1301 Responses 1302 223 n message-id Article found 1303 412 No newsgroup selected 1304 420 Current article number is invalid 1305 422 No previous article in this group 1307 Parameters 1308 n = article number 1309 message-id = article message-id 1311 6.1.2.2 Description 1313 If the current selected newsgroup is valid, the current article 1314 number MUST be set to the previous article in that newsgroup (that 1315 is, the highest existing article number less than the current article 1316 number). If successful, a response indicating the new current article 1317 number and the message-id of that article MUST be returned. No 1318 article text is sent in response to this command. 1320 There MAY be no previous article in the group, although the current 1321 article number is not the reported low water mark. There MUST NOT be 1322 a previous article when the current article number is the reported 1323 low water mark. 1325 Because articles can be removed and added, the results of multiple 1326 LAST and NEXT commands MAY not be consistent over the life of a 1327 particular NNTP session. 1329 If the current article number is already the first article of the 1330 newsgroup, a 422 response MUST be returned. If the current article 1331 number is invalid, a 420 response MUST be returned. If the current 1332 selected newsgroup is invalid, a 412 response MUST be returned. In 1333 all three cases the current selected newsgroup and current article 1334 number MUST NOT be altered. 1336 6.1.2.3 Examples 1338 Example of a successful article retrieval using LAST: 1340 [C] GROUP misc.test 1341 [S] 211 1234 3000234 3002322 misc.test 1342 [C] NEXT 1343 [S] 223 3000237 <668929@example.org> retrieved 1344 [C] LAST 1345 [S] 223 3000234 <45223423@example.com> 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] LAST 1352 [S] 412 no newsgroup selected 1354 Example of an attempt to retrieve an article using the LAST command 1355 when the current article number is that of the first article in the 1356 group: 1358 [C] GROUP misc.test 1359 [S] 211 1234 3000234 3002322 misc.test 1360 [C] LAST 1361 [S] 422 No previous article to retrieve 1363 Example of an attempt to retrieve an article using the LAST command 1364 when the current selected newsgroup is empty: 1366 [C] GROUP example.empty.newsgroup 1367 [S] 211 0 0 0 example.empty.newsgroup 1368 [C] LAST 1369 [S] 420 No current article selected 1371 6.1.3 NEXT 1373 6.1.3.1 Usage 1375 Syntax 1376 NEXT 1378 Responses 1379 223 n message-id Article found 1380 412 No newsgroup selected 1381 420 Current article number is invalid 1382 421 No next article in this group 1384 Parameters 1385 n = article number 1386 message-id = article message-id 1388 6.1.3.2 Description 1390 If the current selected newsgroup is valid, the current article 1391 number MUST be set to the next article in that newsgroup (that is, 1392 the lowest existing article number greater than the current article 1393 number). If successful, a response indicating the new current article 1394 number and the message-id of that article MUST be returned. No 1395 article text is sent in response to this command. 1397 If the current article number is already the last article of the 1398 newsgroup, a 421 response MUST be returned. In all other aspects 1399 (apart, of course, from the lack of 422 response) this command is 1400 identical to the LAST command (Section 6.1.2). 1402 6.1.3.3 Examples 1404 Example of a successful article retrieval using NEXT: 1406 [C] GROUP misc.test 1407 [S] 211 1234 3000234 3002322 misc.test 1408 [C] NEXT 1409 [S] 223 3000237 <668929@example.org> retrieved 1411 Example of an attempt to retrieve an article without having selected 1412 a group (via the GROUP command) first: 1414 [Assumes current selected newsgroup is invalid.] 1415 [C] NEXT 1416 [S] 412 no newsgroup selected 1418 Example of an attempt to retrieve an article using the NEXT command 1419 when the current article number is that of the last article in the 1420 group: 1422 [C] GROUP misc.test 1423 [S] 211 1234 3000234 3002322 misc.test 1424 [C] STAT 3002322 1425 [S] 223 3002322 <411@example.net> retrieved 1426 [C] NEXT 1427 [S] 421 No next article to retrieve 1429 Example of an attempt to retrieve an article using the NEXT command 1430 when the current selected newsgroup is empty: 1432 [C] GROUP example.empty.newsgroup 1433 [S] 211 0 0 0 example.empty.newsgroup 1434 [C] NEXT 1435 [S] 420 No current article selected 1437 6.2 Retrieval of articles and article sections 1439 The ARTICLE, BODY, HEAD, and STAT commands are very similar. They 1440 differ only in the parts of the article that are presented to the 1441 client and in the successful response code. The ARTICLE command is 1442 described here in full, while the other commands are described in 1443 terms of the differences. As specified in Section 3.4, an article 1444 consists of two parts: the article headers and the article body. When 1445 responding to one of these commands, the server MUST present the 1446 entire article or appropriate part and MUST NOT attempt to alter or 1447 translate it in any way. 1449 6.2.1 ARTICLE 1451 6.2.1.1 Usage 1453 Syntax 1454 ARTICLE message-id 1455 ARTICLE number 1456 ARTICLE 1458 Responses 1460 First form (message-id specified) 1461 220 0 message-id Article follows (multiline) 1462 430 No article with that message-id 1464 Second form (article number specified) 1465 220 n message-id Article follows (multiline) 1466 412 No newsgroup selected 1467 423 No articles in that range 1469 Third form (current article number used) 1470 220 n message-id Article follows (multiline) 1471 412 No newsgroup selected 1472 420 Current article number is invalid 1474 Parameters 1475 number = Requested article number 1476 n = Returned article number 1477 message-id = Article message-id 1479 6.2.1.2 Description 1481 The ARTICLE command selects an article based on the arguments and 1482 presents the entire article (that is, the headers, an empty line, and 1483 the body in that order). The command has three forms. 1485 In the first form, a message-id is specified and the server presents 1486 the article with that message-id. In this case, the server MUST NOT 1487 alter the current selected newsgroup or current article number. This 1488 is both to facilitate the presentation of articles that may be 1489 referenced within another article being read, and because of the 1490 semantic difficulties of determining the proper sequence and 1491 membership of an article that may have been crossposted to more than 1492 one newsgroup. 1494 In the response, the article number is replaced with zero (that is, 1495 the server is not required to determine whether the article is in the 1496 current selected newsgroup or what article number(s) it has). 1498 In the second form, an article number is specified. If there is an 1499 article with that number in the current selected newsgroup, the 1500 server MUST set the current article number to that number. 1502 In the third form, the article indicated by the current article 1503 number in the current selected newsgroup is used. 1505 Note that a previously valid article number MAY become invalid if the 1506 article has been removed. A previously invalid article number MAY 1507 become valid if the article has been reinstated, but such an article 1508 number MUST be no less than the reported low water mark for that 1509 group. 1511 The server MUST NOT change the current selected newsgroup as a result 1512 of this command. The server MUST NOT change the current article 1513 number except when an article number argument was provided and the 1514 article exists; in particular, it MUST NOT change it following an 1515 unsuccessful response. 1517 Since the message-id is unique for each article, it may be used by a 1518 client to skip duplicate displays of articles that have been posted 1519 more than once, or to more than one newsgroup. 1521 The article is returned as a multi-line response following the 220 1522 response code. 1524 If the argument is a message-id and no such article exists, a 430 1525 response MUST be returned. If the argument is a number or is omitted 1526 and the current selected newsgroup is invalid, a 412 response MUST be 1527 returned. If the argument is a number and that article does not exist 1528 in the current selected newsgroup, a 423 response MUST be returned. 1529 If the argument is omitted and the current article number is invalid, 1530 a 420 response MUST be returned. 1532 6.2.1.3 Examples 1534 Example of a successful retrieval of an article (using no article 1535 number): 1537 [C] GROUP misc.test 1538 [S] 211 1234 3000234 3002322 misc.test 1539 [C] ARTICLE 1540 [S] 220 3000234 <45223423@example.com> 1541 [S] Path: pathost!demo!whitehouse!not-for-mail 1542 [S] From: "Demo User" 1543 [S] Newsgroups: misc.test 1544 [S] Subject: I am just a test article 1545 [S] Date: 6 Oct 1998 04:38:40 -0500 1546 [S] Organization: An Example Net, Uncertain, Texas 1547 [S] Message-ID: <411@example.net> 1548 [S] 1549 [S] This is just a test article. 1550 [S] . 1552 Example of a successful retrieval of an article by message-id: 1554 [C] ARTICLE <45223423@example.com> 1555 [S] 220 0 <45223423@example.com> 1556 [S] Path: pathost!demo!whitehouse!not-for-mail 1557 [S] From: "Demo User" 1558 [S] Newsgroups: misc.test 1559 [S] Subject: I am just a test article 1560 [S] Date: 6 Oct 1998 04:38:40 -0500 1561 [S] Organization: An Example Net, Uncertain, Texas 1562 [S] Message-ID: <411@example.net> 1563 [S] 1564 [S] This is just a test article. 1565 [S] . 1567 Example of an unsuccessful retrieval of an article by message-id: 1569 [C] ARTICLE 1570 [S] 430 No Such Article Found 1572 Example of an unsuccessful retrieval of an article by number: 1574 [C] GROUP misc.test 1576 [S] 211 1234 3000234 3002322 news.groups 1577 [C] ARTICLE 300256 1578 [S] 423 No such article number in this group 1580 Example of an unsuccessful retrieval of an article by number because 1581 no newsgroup was selected first: 1583 [Assumes current selected newsgroup is invalid.] 1584 [C] ARTICLE 300256 1585 [S] 412 No newsgroup selected 1587 Example of an attempt to retrieve an article when the current 1588 selected newsgroup is empty: 1590 [C] GROUP example.empty.newsgroup 1591 [S] 211 0 0 0 example.empty.newsgroup 1592 [C] ARTICLE 1593 [S] 420 No current article selected 1595 6.2.2 HEAD 1597 6.2.2.1 Usage 1599 Syntax 1600 HEAD message-id 1601 HEAD number 1602 HEAD 1604 Responses 1606 First form (message-id specified) 1607 221 0 message-id Headers follow (multiline) 1608 430 No article with that message-id 1610 Second form (article number specified) 1611 221 n message-id Headers follow (multiline) 1612 412 No newsgroup selected 1613 423 No articles in that range 1615 Third form (current article number used) 1616 221 n message-id Headers follow (multiline) 1617 412 No newsgroup selected 1618 420 Current article number is invalid 1620 Parameters 1621 number = Requested article number 1622 n = Returned article number 1623 message-id = Article message-id 1625 6.2.2.2 Description 1627 The HEAD command behaves identically to the ARTICLE command except 1628 that, if the article exists, the response code is 221 instead of 220 1629 and only the headers are presented (the empty line separating the 1630 headers and body MUST NOT be included). 1632 6.2.2.3 Examples 1634 Example of a successful retrieval of the headers of an article (using 1635 no article number): 1637 [C] GROUP misc.test 1638 [S] 211 1234 3000234 3002322 misc.test 1639 [C] HEAD 1640 [S] 221 3000234 <45223423@example.com> 1641 [S] Path: pathost!demo!whitehouse!not-for-mail 1642 [S] From: "Demo User" 1643 [S] Newsgroups: misc.test 1644 [S] Subject: I am just a test article 1645 [S] Date: 6 Oct 1998 04:38:40 -0500 1646 [S] Organization: An Example Net, Uncertain, Texas 1647 [S] Message-ID: <411@example.net> 1648 [S] . 1650 Example of a successful retrieval of the headers of an article by 1651 message-id: 1653 [C] HEAD <45223423@example.com> 1654 [S] 221 0 <45223423@example.com> 1655 [S] Path: pathost!demo!whitehouse!not-for-mail 1656 [S] From: "Demo User" 1657 [S] Newsgroups: misc.test 1658 [S] Subject: I am just a test article 1659 [S] Date: 6 Oct 1998 04:38:40 -0500 1660 [S] Organization: An Example Net, Uncertain, Texas 1661 [S] Message-ID: <411@example.net> 1662 [S] . 1664 Example of an unsuccessful retrieval of the headers of an article by 1665 message-id: 1667 [C] HEAD 1668 [S] 430 No Such Article Found 1670 Example of an unsuccessful retrieval of the headers of an article by 1671 number: 1673 [C] GROUP misc.test 1674 [S] 211 1234 3000234 3002322 misc.test 1675 [C] HEAD 300256 1676 [S] 423 No such article number in this group 1678 Example of an unsuccessful retrieval the headers of an article by 1679 number because no newsgroup was selected first: 1681 [Assumes current selected newsgroup is invalid.] 1682 [C] HEAD 300256 1683 [S] 412 No newsgroup selected 1685 Example of an attempt to retrieve the headers of an article when the 1686 current selected newsgroup is empty: 1688 [C] GROUP example.empty.newsgroup 1689 [S] 211 0 0 0 example.empty.newsgroup 1690 [C] HEAD 1691 [S] 420 No current article selected 1693 6.2.3 BODY 1695 6.2.3.1 Usage 1697 Syntax 1698 BODY message-id 1699 BODY number 1700 BODY 1702 Responses 1704 First form (message-id specified) 1705 222 0 message-id Body follows (multiline) 1706 430 No article with that message-id 1708 Second form (article number specified) 1709 222 n message-id Body follows (multiline) 1710 412 No newsgroup selected 1711 423 No articles in that range 1713 Third form (current article number used) 1714 222 n message-id Body follows (multiline) 1715 412 No newsgroup selected 1716 420 Current article number is invalid 1718 Parameters 1719 number = Requested article number 1720 n = Returned article number 1721 message-id = Article message-id 1723 6.2.3.2 Description 1725 The BODY command behaves identically to the ARTICLE command except 1726 that, if the article exists, the response code is 222 instead of 220 1727 and only the body is presented (the empty line separating the headers 1728 and body MUST NOT be included). 1730 6.2.3.3 Examples 1732 Example of a successful retrieval of the body of an article (using no 1733 article number): 1735 [C] GROUP misc.test 1736 [S] 211 1234 3000234 3002322 misc.test 1737 [C] BODY 1738 [S] 222 3000234 <45223423@example.com> 1739 [S] This is just a test article. 1740 [S] . 1742 Example of a successful retrieval of the body of an article by 1743 message-id: 1745 [C] BODY <45223423@example.com> 1746 [S] 222 0 <45223423@example.com> 1747 [S] This is just a test article. 1748 [S] . 1750 Example of an unsuccessful retrieval of the body of an article by 1751 message-id: 1753 [C] BODY 1754 [S] 430 No Such Article Found 1756 Example of an unsuccessful retrieval of the body of an article by 1757 number: 1759 [C] GROUP misc.test 1761 [S] 211 1234 3000234 3002322 misc.test 1762 [C] BODY 300256 1763 [S] 423 No such article number in this group 1765 Example of an unsuccessful retrieval of the body of an article by 1766 number because no newsgroup was selected first: 1768 [Assumes current selected newsgroup is invalid.] 1769 [C] BODY 300256 1770 [S] 412 No newsgroup selected 1772 Example of an attempt to retrieve the body of an article when the 1773 current selected newsgroup is empty: 1775 [C] GROUP example.empty.newsgroup 1776 [S] 211 0 0 0 example.empty.newsgroup 1777 [C] BODY 1778 [S] 420 No current article selected 1780 6.2.4 STAT 1782 6.2.4.1 Usage 1784 Syntax 1785 STAT message-id 1786 STAT number 1787 STAT 1789 Responses 1791 First form (message-id specified) 1792 223 0 message-id Article exists 1793 430 No article with that message-id 1795 Second form (article number specified) 1796 223 n message-id Article exists 1797 412 No newsgroup selected 1798 423 No articles in that range 1800 Third form (current article number used) 1801 223 n message-id Article exists 1802 412 No newsgroup selected 1803 420 Current article number is invalid 1805 Parameters 1806 number = Requested article number 1807 n = Returned article number 1808 message-id = Article message-id 1810 6.2.4.2 Description 1812 The STAT command behaves identically to the ARTICLE command except 1813 that, if the article exists, it is NOT presented to the client and 1814 the response code is 223 instead of 220. Note that the response is 1815 NOT multi-line. 1817 This command allows the client to determine whether an article 1818 exists, and in the second and third forms what its message-id is, 1819 without having to process an arbitrary amount of text. 1821 6.2.4.3 Examples 1823 Example of STAT on an existing article (using no article number): 1825 [C] GROUP misc.test 1826 [S] 211 1234 3000234 3002322 misc.test 1827 [C] STAT 1828 [S] 223 3000234 <45223423@example.com> 1830 Example of a STAT of an existing article by message-id: 1832 [C] STAT <45223423@example.com> 1833 [S] 223 0 <45223423@example.com> 1835 Example of an STAT of an article not on the server by message-id: 1837 [C] STAT 1838 [S] 430 No Such Article Found 1840 Example of STAT of an article not in the server by number: 1842 [C] GROUP misc.test 1843 [S] 211 1234 3000234 3002322 misc.test 1844 [C] STAT 300256 1845 [S] 423 No such article number in this group 1847 Example of STAT of an article by number when no newsgroup was 1848 selected first: 1850 [Assumes current selected newsgroup is invalid.] 1851 [C] STAT 300256 1853 [S] 412 No newsgroup selected 1855 Example of STAT of an article when the current selected newsgroup is 1856 empty: 1858 [C] GROUP example.empty.newsgroup 1859 [S] 211 0 0 0 example.empty.newsgroup 1860 [C] STAT 1861 [S] 420 No current article selected 1863 6.3 Article posting 1865 Article posting is done in one of two modes: individual article 1866 posting from news reading clients using POST, and article transfer 1867 from other news servers using IHAVE. 1869 6.3.1 POST 1871 6.3.1.1 Usage 1873 This command MUST NOT be pipelined. 1875 Syntax 1876 POST 1878 Responses 1880 Initial responses 1881 340 Send article to be posted 1882 440 Posting not permitted 1884 Subsequent responses 1885 240 Article received OK 1886 441 Posting failed 1888 6.3.1.2 Description 1890 If posting is allowed, a 340 response MUST be returned to indicate 1891 that the article to be posted should be sent. If posting is 1892 prohibited for some installation-dependent reason, a 440 response 1893 MUST be returned. 1895 If posting is permitted, the article MUST be in the format specified 1896 in Section 3.4 and MUST be sent by the client to the server in the 1897 manner specified in (Section 3.1) for multi-line responses (except 1898 that there is no initial line containing a response code). Thus a 1899 single dot (".") on a line indicates the end of the text, and lines 1900 starting with a dot in the original text have that dot doubled during 1901 transmission. 1903 Following the presentation of the termination sequence by the client, 1904 the server MUST return a response indicating success or failure of 1905 the article transfer. Note that response codes 340 and 440 are used 1906 in direct response to the POST command. Others are returned following 1907 the sending of the article. 1909 A response of 240 SHOULD indicate that, barring unforseen server 1910 errors, the posted article will be made available on the server and/ 1911 or transferred to other servers as appropriate, possibly following 1912 further processing. In other words, articles not wanted by the server 1913 SHOULD be rejected with a 441 response and not accepted and silently 1914 discarded. However, the client SHOULD NOT assume that the article has 1915 been successfully transferred unless it receives an affirmative 1916 response from the server, and SHOULD NOT assume that it is being made 1917 available to other clients without explicitly checking (for example 1918 using the STAT command). 1920 If the session is interrupted before the response is received, it is 1921 possible that an affirmative response was sent but has been lost. 1922 Therefore, in any subsequent session, the client SHOULD either check 1923 whether the article was successfully posted before resending or 1924 ensure that the server will allocate the same message-id to the new 1925 attempt (see Appendix B.2) - the latter approach is preferred since 1926 the article might not have been made available for reading yet (for 1927 example, it may have to go through a moderation process). 1929 6.3.1.3 Examples 1931 Example of a successful posting: 1933 [C] POST 1934 [S] 340 Input article; end with . 1935 [C] From: "Demo User" 1936 [C] Newsgroups: misc.test 1937 [C] Subject: I am just a test article 1938 [C] Organization: An Example Net 1939 [C] 1940 [C] This is just a test article. 1941 [C] . 1942 [S] 240 Article received OK 1944 Example of an unsuccessful posting: 1946 [C] POST 1948 [S] 340 Input article; end with . 1949 [C] From: "Demo User" 1950 [C] Newsgroups: misc.test 1951 [C] Subject: I am just a test article 1952 [C] Organization: An Example Net 1953 [C] 1954 [C] This is just a test article. 1955 [C] . 1956 [S] 441 Posting failed 1958 Example of an attempt to post when posting is not allowed: 1960 [C] MODE READER 1961 [S] 201 NNTP Service Ready, posting prohibited 1962 [C] POST 1963 [S] 440 Posting not permitted 1965 6.3.2 IHAVE 1967 6.3.2.1 Usage 1969 This command MUST NOT be pipelined. 1971 Syntax 1972 IHAVE message-id 1974 Responses 1976 Initial responses 1977 335 Send article to be transferred 1978 435 Article not wanted 1979 436 Transfer not possible; try again later 1981 Subsequent responses 1982 235 Article transferred OK 1983 436 Transfer failed; try again later 1984 437 Transfer rejected; do not retry 1986 Parameters 1987 message-id = Article message-id 1989 6.3.2.2 Description 1991 The IHAVE command informs the server that the client has an article 1992 with the specified message-id. If the server desires a copy of that 1993 article a 335 response MUST be returned, instructing the client to 1994 send the entire article. If the server does not want the article (if, 1995 for example, the server already has a copy of it), a 435 response 1996 MUST be returned, indicating that the article is not wanted. Finally, 1997 if the article isn't wanted immediately but the client should retry 1998 later if possible (if, for example, another client is in the process 1999 of sending the same article to the server), a 436 response MUST be 2000 returned. 2002 If transmission of the article is requested, the client MUST send the 2003 entire article, including headers and body, in the format defined 2004 above (Section 3.1) for multi-line responses (except that there is no 2005 initial line containing a response code). Thus a single dot (".") on 2006 a line indicates the end of the text, and lines starting with a dot 2007 in the original text have that dot doubled during transmission. The 2008 server MUST return either a 235 response, indicating that the article 2009 was successfully transferred, a 436 response, indicating that the 2010 transfer failed but should be tried again later, or a 437 response, 2011 indicating that the article was rejected. 2013 This function differs from the POST command in that it is intended 2014 for use in transferring already-posted articles between hosts. It 2015 SHOULD NOT be used when the client is a personal news reading 2016 program, since use of this command indicates that the article has 2017 already been posted at another site and is simply being forwarded 2018 from another host. However, despite this, the server MAY elect not to 2019 post or forward the article if, after further examination of the 2020 article, it deems it inappropriate to do so. Reasons for such 2021 subsequent rejection of an article may include such problems as 2022 inappropriate newsgroups or distributions, disc space limitations, 2023 article lengths, garbled headers, and the like. These are typically 2024 restrictions enforced by the server host's news software and not 2025 necessarily the NNTP server itself. 2027 The client SHOULD NOT assume that the article has been successfully 2028 transferred unless it receives an affirmative response from the 2029 server. A lack of response (such as a dropped network connection or a 2030 network timeout) SHOULD be treated the same as a 436 response. 2032 Because some news server software may not be able immediately to 2033 determine whether or not an article is suitable for posting or 2034 forwarding, an NNTP server MAY acknowledge the successful transfer of 2035 the article (with a 235 response) but later silently discard it. 2037 6.3.2.3 Examples 2039 Example of successfully sending an article to another site: 2041 [C] IHAVE 2043 [S] 335 Send it; end with . 2044 [C] Path: pathost!demo!somewhere!not-for-mail 2045 [C] From: "Demo User" 2046 [C] Newsgroups: misc.test 2047 [C] Subject: I am just a test article 2048 [C] Date: 6 Oct 1998 04:38:40 -0500 2049 [C] Organization: An Example Com, San Jose, CA 2050 [C] Message-ID: 2051 [C] 2052 [C] This is just a test article. 2053 [C] . 2054 [S] 235 Article transferred OK 2056 Example of sending an article to another site that rejects it. Note 2057 that the message-id in the IHAVE command is not the same as the one 2058 in the article headers; while this is bad practice and SHOULD NOT be 2059 done, it is not forbidden. 2061 [C] IHAVE 2062 [S] 335 Send it; end with . 2063 [C] Path: pathost!demo!somewhere!not-for-mail 2064 [C] From: "Demo User" 2065 [C] Newsgroups: misc.test 2066 [C] Subject: I am just a test article 2067 [C] Date: 6 Oct 1998 04:38:40 -0500 2068 [C] Organization: An Example Com, San Jose, CA 2069 [C] Message-ID: 2070 [C] 2071 [C] This is just a test article. 2072 [C] . 2073 [S] 437 Article rejected; don't send again 2075 Example of sending an article to another site where the transfer 2076 fails: 2078 [C] IHAVE 2079 [S] 335 Send it; end with . 2080 [C] Path: pathost!demo!somewhere!not-for-mail 2081 [C] From: "Demo User" 2082 [C] Newsgroups: misc.test 2083 [C] Subject: I am just a test article 2084 [C] Date: 6 Oct 1998 04:38:40 -0500 2085 [C] Organization: An Example Com, San Jose, CA 2086 [C] Message-ID: 2087 [C] 2088 [C] This is just a test article. 2089 [C] . 2090 [S] 436 Transfer failed 2092 Example of sending an article to a site that already has it: 2094 [C] IHAVE 2095 [S] 435 Duplicate 2097 Example of sending an article to a site that requests the article be 2098 tried again later: 2100 [C] IHAVE 2101 [S] 436 Retry later 2103 7. Information commands 2105 This section lists other commands that may be used at any time 2106 between the beginning of a session and its termination. Using these 2107 commands does not alter any state information, but the response 2108 generated from their use may provide useful information to clients. 2110 7.1 DATE 2112 7.1.1 Usage 2114 Syntax 2115 DATE 2117 Responses 2118 111 yyyymmddhhmmss server date and time 2120 Parameters 2121 yyyymmddHHmmss = Current UTC date and time on server 2123 7.1.2 Description 2125 This command exists to help clients find out the current Coordinated 2126 Universal Time [TF.686-1] from the server's perspective. This command 2127 SHOULD NOT be used as a substitute for NTP [RFC1305] but to provide 2128 information that might be useful when using the NEWNEWS command (see 2129 Section 7.4). A system providing NNTP service SHOULD keep the system 2130 clock as accurate as possible, either with NTP or by some other 2131 method. 2133 The server MUST return a 111 response specifying the date and time on 2134 the server in the form yyyymmddhhmmss. This date and time is in 2135 Coordinated Universal Time. 2137 7.1.3 Examples 2139 [C] DATE 2140 [S] 111 19990623135624 2142 7.2 HELP 2144 7.2.1 Usage 2145 Syntax 2146 HELP 2148 Responses 2149 100 Help text follows (multiline) 2151 7.2.2 Description 2153 This command provides a short summary of commands that are understood 2154 by this implementation of the server. The help text will be presented 2155 as a multiline response following the 100 response code. 2157 This text is not guaranteed to be in any particular format and MUST 2158 NOT be used by clients as a replacement for the LIST EXTENSIONS 2159 command described in Section 5.3 2161 7.2.3 Examples 2163 [C] HELP 2164 [S] 100 Help text follows 2165 [S] This is some help text. There is no specific 2166 [S] formatting requirement for this test, though 2167 [S] it is customary for it to list the valid commands 2168 [S] and give a brief definition of what they do 2169 [S] . 2171 7.3 NEWGROUPS 2173 7.3.1 Usage 2175 Syntax 2176 NEWGROUPS date time [GMT] 2178 Responses 2179 231 List of new newsgroups follows (multiline) 2181 Parameters 2182 date = Date in yymmdd or yyyymmdd format 2183 time = Time in hhmmss format 2185 7.3.2 Description 2187 This command returns a list of newsgroups created on the server since 2188 the specified date and time. The results are in the same format as 2189 the LIST ACTIVE command (see Section 7.6.1). However, they MAY 2190 include groups not available on the server (and so not returned by 2191 LIST ACTIVE) and MAY omit groups for which the creation date is not 2192 available. The results SHOULD be consistent with those of the LIST 2193 ACTIVE.TIMES command (Section 7.6.2), except that if the specified 2194 date and time is earlier than the oldest entry in the latter then the 2195 results of this command may include extra groups. 2197 The date is specified as 6 or 8 digits in the format [xx]yymmdd, 2198 where xx is the first two digits of the year (19-99), yy is the last 2199 two digits of the year (00-99), mm is the month (01-12), and dd is 2200 the day of the month (01-31). Clients SHOULD specify all four digits 2201 of the year. If the first two digits of the year are not specified 2202 (this is supported only for backwards compatibility), the year is to 2203 be taken from the current century if yy is smaller than or equal to 2204 the current year, otherwise the year is from the previous century. 2206 The time is specified as 6 digits in the format hhmmss, where hh is 2207 the hours in the 24-hour clock (00-23), mm is the minutes (00-59), 2208 and ss is the seconds (00-60, to allow for leap seconds). The token 2209 "GMT" specifies that the date and time are given in Coordinated 2210 Universal Time [TF.686-1]; if it is omitted then the date and time 2211 are specified in the server's local timezone. Note that there is no 2212 way using the protocol specified in this document to establish the 2213 server's local timezone. 2215 Note that an empty list is a possible valid response and indicates 2216 that there are no new newsgroups since that date-time. 2218 Clients SHOULD make all queries using Coordinated Universal Time 2219 (i.e. by including the "GMT" argument) when possible. 2221 7.3.3 Examples 2223 Example where there are new groups: 2225 [C] NEWGROUPS 19990624 000000 GMT 2226 [S] 231 list of new newsgroups follows 2227 [S] alt.fc-writers.recovery 4 1 y 2228 [S] tx.natives.recovery 89 56 y 2229 [S] . 2231 Example where there are no new groups: 2233 [C] NEWGROUPS 19990624 000000 GMT 2234 [S] 231 list of new newsgroups follows 2235 [S] . 2237 7.4 NEWNEWS 2239 7.4.1 Usage 2241 Syntax 2242 NEWNEWS wildmat date time [GMT] 2244 Responses 2245 230 List of new articles follows (multiline) 2247 Parameters 2248 wildmat = Newsgroups of interest 2249 date = Date in yymmdd or yyyymmdd format 2250 time = Time in hhmmss format 2252 7.4.2 Description 2254 This command returns a list of message-ids of articles posted or 2255 received on the server, in the newsgroups whose names match the 2256 wildmat, since the specified date and time. One message-id is sent on 2257 each line; the order of the response has no specific significance and 2258 may vary from response to response in the same session. A message-id 2259 MAY appear more than once; if it does so, it has the same meaning as 2260 if it appeared only once. 2262 Date and time are in the same format as the NEWGROUPS command (see 2263 Section 7.3). 2265 Note that an empty list is a possible valid response and indicates 2266 that there is currently no new news in the relevant groups. 2268 Clients SHOULD make all queries in Coordinated Universal Time (i.e. 2269 by using the "GMT" argument) when possible. 2271 7.4.3 Examples 2273 Example where there are new articles: 2275 [C] NEWNEWS news.*,sci.* 19990624 000000 GMT 2276 [S] 230 list of new articles by message-id follows 2277 [S] 2278 [S] 2279 [S] . 2281 Example where there are no new articles: 2283 [C] NEWNEWS alt.* 19990624 000000 GMT 2285 [S] 230 list of new articles by message-id follows 2286 [S] . 2288 7.5 Time 2290 As described in Section 6, each article has an arrival timestamp. 2291 Each newsgroup also has a creation timestamp. These timestamps are 2292 used by the NEWNEWS and NEWGROUP commands to construct their 2293 reponses. 2295 The DATE command MUST return a timestamp from the same clock as is 2296 used for determining article arrival and group creation times. This 2297 clock SHOULD be monotonic, and adjustments SHOULD be made by running 2298 it fast or slow compared to "real" time rather than by making sudden 2299 jumps. 2301 Clients can ensure that they do not have gaps in lists of articles or 2302 groups by using the DATE command in the following manner: 2304 First session: 2305 Issue DATE command and record result 2306 Issue NEWNEWS command using a previously chosen timestamp 2308 Subsequent sessions: 2309 Issue DATE command and hold result in temporary storage 2310 Issue NEWNEWS command using timestamp saved from previous session 2311 Overwrite saved timestamp with that currently in temporary storage 2313 In order to allow for minor errors, clients MAY want to adjust the 2314 timestamp back by two or three minutes before using it in NEWNEWS. 2316 7.5.1 Examples 2318 First session: 2320 [C] DATE 2321 [S] 111 20010203112233 2322 [C] NEWNEWS local.chat 20001231 235959 GMT 2323 [S] 230 list follows 2324 [S] 2325 [S] 2326 [S] 2327 [S] . 2329 Second session (the client has subtracted 3 minutes from the 2330 timestamp returned previously): 2332 [C] DATE 2333 [S] 111 20010204003344 2334 [C] NEWNEWS local.chat 20010203 111933 GMT 2335 [S] 230 list follows 2336 [S] 2337 [S] 2338 [S] 2339 [S] . 2341 Note how arrived in the 3 minute gap and so 2342 is listed in both responses. 2344 7.6 The LIST commands 2346 7.6.1 LIST ACTIVE 2348 7.6.1.1 Usage 2350 Syntax 2351 LIST ACTIVE [wildmat] 2353 Responses 2354 215 Information follows (multiline) 2356 Parameters 2357 wildmat = groups of interest 2359 7.6.1.2 Description 2361 The LIST ACTIVE command with no arguments returns a list of valid 2362 newsgroups and associated information. The server MUST include every 2363 group that the client is permitted to select with the GROUP (Section 2364 6.1.1) command. Each newsgroup is sent as a line of text in the 2365 following format: 2367 group high low status 2369 where: 2371 "group" is the name of the newsgroup; 2373 "high" is the reported high water mark for the group; 2375 "low" is the reported low water mark for the group; 2376 "status" is the current status of the group on this server. 2378 Each field in the line is separated from its neighboring fields by 2379 one or more spaces. Note that an empty list is a possible valid 2380 response, and indicates that there are currently no valid newsgroups. 2382 The reported high and low water marks are as described in the GROUP 2383 command (see Section 6.1.1). 2385 The status field is typically one of: 2387 "y" posting is permitted 2389 "n" posting is not permitted 2391 "m" postings will be forwarded to the newsgroup moderator 2393 The server SHOULD use these values when these meanings are required 2394 and MUST NOT use them with any other meaning. Other values for the 2395 status may exist; the definition of these other values and the 2396 circumstances under which they are returned may be specified in an 2397 extension or may be private to the server. A client SHOULD treat an 2398 unrecognised status as giving no information. 2400 The status of a newsgroup only indicates how posts to that newsgroup 2401 are normally processed and is not necessarily customised to the 2402 specific client. For example, if the current client is forbidden from 2403 posting, then this will apply equally to groups with status "y". 2404 Conversely, a client with special privileges (not defined by this 2405 specification) might be able to post to a group with status "n". 2407 If the optional wildmat argument is specified, the response is 2408 limited to only the groups (if any) whose names match the wildmat. If 2409 no wildmat is specified, the keyword ACTIVE MAY be omitted without 2410 altering the effect of the command. 2412 7.6.1.3 Examples 2414 Example of LIST ACTIVE returning a list of newsgroups: 2416 [C] LIST ACTIVE 2417 [S] 215 list of newsgroups follows 2418 [S] misc.test 3002322 3000234 y 2419 [S] comp.risks 442001 441099 m 2420 [S] alt.fc-writers.recovery 4 1 y 2421 [S] tx.natives.recovery 89 56 y 2422 [S] tx.natives.recovery.d 11 9 n 2423 [S] . 2425 Example of LIST ACTIVE omitting the second keyword and returning no 2426 newsgroups: 2428 [C] LIST 2429 [S] 215 list of newsgroups follows 2430 [S] . 2432 Example of LIST ACTIVE with a wildmat: 2434 [C] LIST ACTIVE *.recovery 2435 [S] 215 list of newsgroups follows 2436 [S] alt.fc-writers.recovery 4 1 y 2437 [S] tx.natives.recovery 89 56 y 2438 [S] . 2440 7.6.2 LIST ACTIVE.TIMES 2442 7.6.2.1 Usage 2444 This command is optional. 2446 Syntax 2447 LIST ACTIVE.TIMES [wildmat] 2449 Responses 2450 215 Information follows (multiline) 2452 Parameters 2453 wildmat = groups of interest 2455 7.6.2.2 Description 2457 The active.times list is maintained by some news transport systems to 2458 contain information about who created a particular newsgroup and 2459 when. Each line of this list consists of three fields separated from 2460 each other by one or more spaces. The first field is the name of the 2461 newsgroup. The second is the time when this group was created on this 2462 news server, measured in seconds since the start of January 1, 1970. 2463 The third is plain text intended to describe the entity that created 2464 the newsgroup; it is often a mailbox as defined in RFC 2822 2465 [RFC2822]. 2467 The list MAY omit newsgroups for which the information is unavailable 2468 and MAY include groups not available on the server; in particular, it 2469 MAY omit all groups created before the date and time of the oldest 2470 entry. The client MUST NOT assume that the list is complete or that 2471 it matches the list returned by LIST ACTIVE. The NEWGROUPS command 2472 (Section 7.3) may provide a better way to access this information and 2473 the results of the two commands SHOULD be consistent (subject to the 2474 caveats in the description of that command). 2476 If the information is available, it is returned as a multi-line 2477 response following the 215 response code. 2479 If the optional wildmat argument is specified, the response is 2480 limited to only the groups (if any) whose names match the wildmat and 2481 for which the information is available. Note that an empty list is a 2482 possible valid response (whether or not a wildmat is specified) and 2483 indicates that there are no such groups. 2485 7.6.2.3 Examples 2487 Example of LIST ACTIVE.TIMES returning a list of newsgroups: 2489 [C] LIST ACTIVE.TIMES 2490 [S] 215 information follows 2491 [S] misc.test 930445408 2492 [S] alt.rfc-writers.recovery 930562309 2493 [S] tx.natives.recovery 930678923 2494 [S] . 2496 Example of LIST ACTIVE.TIMES returning an error where the command is 2497 recognised but the software does not maintain this information: 2499 [C] LIST ACTIVE.TIMES 2500 [S] 503 program error, function not performed 2502 Example of LIST ACTIVE.TIMES sent to a server that does not recognize 2503 this command: 2505 [C] LIST ACTIVE.TIMES 2506 [S] 501 Syntax Error 2508 7.6.3 LIST DISTRIBUTIONS 2510 7.6.3.1 Usage 2512 This command is optional. 2514 Syntax 2515 LIST DISTRIBUTIONS 2517 Responses 2518 215 Information follows (multiline) 2520 7.6.3.2 Description 2522 The distributions list is maintained by some news transport systems 2523 to contain information about valid values for the content of the 2524 Distribution header in a news article and about what the various 2525 values mean. Each line of this list consists of two fields separated 2526 from each other by one or more spaces. The first field is a value and 2527 the second is a short explanation of the meaning of that value. 2529 If the information is available, it is returned as a multi-line 2530 response following the 215 response code. 2532 7.6.3.3 Examples 2534 Example of LIST DISTRIBUTIONS returning a list of distributions: 2536 [C] LIST DISTRIBUTIONS 2537 [S] 215 information follows 2538 [S] usa United States of America 2539 [S] na North America 2540 [S] world All over the World 2541 [S] . 2543 Example of LIST DISTRIBUTIONS returning an error where the command is 2544 recognised but the software does not maintain this information: 2546 [C] LIST DISTRIBUTIONS 2547 [S] 503 program error, function not performed 2549 Example of LIST DISTRIBUTIONS sent to a server that does not 2550 recognize this command: 2552 [C] LIST DISTRIBUTIONS 2553 [S] 501 Syntax Error 2555 7.6.4 LIST DISTRIB.PATS 2557 7.6.4.1 Usage 2559 This command is optional. 2561 Syntax 2562 LIST DISTRIB.PATS 2564 Responses 2565 215 Information follows (multiline) 2567 7.6.4.2 Description 2569 The distrib.pats list is maintained by some news transport systems to 2570 choose a value for the content of the Distribution header of a news 2571 article being posted. Each line of this list consists of three fields 2572 separated from each other by a colon (":"). The first field is a 2573 weight, the second field is a wildmat (which may be a simple group 2574 name), and the third field is a value for the Distribution header 2575 content. 2577 The client MAY use this information to construct an appropriate 2578 Distribution header given the name of a newsgroup. To do so, it 2579 should determine the lines whose second field matches the newsgroup 2580 name, select from among them the line with the highest weight (with 0 2581 being the lowest), and use the value of the third field to construct 2582 the Distribution header. 2584 If the information is available, it is returned as a multi-line 2585 response following the 215 response code. 2587 7.6.4.3 Examples 2589 Example of LIST DISTRIB.PATS returning a list of newsgroups: 2591 [C] LIST DISTRIB.PATS 2592 [S] 215 information follows 2593 [S] 10:local.*:local 2594 [S] 5:*:world 2595 [S] 20:local.here.*:thissite 2596 [S] . 2598 Example of LIST DISTRIB.PATS returning an error where the command is 2599 recognised but the software does not maintain this information: 2601 [C] LIST DISTRIB.PATS 2602 [S] 503 program error, function not performed 2604 Example of LIST DISTRIB.PATS sent to a server that does not recognize 2605 this command: 2607 [C] LIST DISTRIB.PATS 2609 [S] 501 Syntax Error 2611 7.6.5 LIST NEWSGROUPS 2613 7.6.5.1 Usage 2615 This command is optional. 2617 Syntax 2618 LIST NEWSGROUPS [wildmat] 2620 Responses 2621 215 Information follows (multiline) 2623 Parameters 2624 wildmat = groups of interest 2626 7.6.5.2 Description 2628 The newsgroups list is maintained by some news transport systems to 2629 contain the name of each newsgroup that is available on the server 2630 and a short description about the purpose of the group. Each line of 2631 this list consists of two fields separated from each other by one or 2632 more space or TAB characters (usual practice is a single TAB). The 2633 first field is the name of the newsgroup and the second is a short 2634 description of the group. 2636 The list MAY omit newsgroups for which the information is unavailable 2637 and MAY include groups not available on the server. The client MUST 2638 NOT assume that the list is complete or that it matches the list 2639 returned by LIST ACTIVE. 2641 If the information is available, it is returned as a multi-line 2642 response following the 215 response code. 2644 If the optional wildmat argument is specified, the response is 2645 limited to only the groups (if any) whose names match the wildmat and 2646 for which the information is available. Note that an empty list is a 2647 possible valid response (whether or not a wildmat is specified) and 2648 indicates that there are no such groups. 2650 7.6.5.3 Examples 2652 Example of LIST NEWSGROUPS returning a list of newsgroups: 2654 [C] LIST NEWSGROUPS 2656 [S] 215 information follows 2657 [S] misc.test General Usenet testing 2658 [S] alt.rfc-writers.recovery RFC Writers Recovery 2659 [S] tx.natives.recovery Texas Natives Recovery 2660 [S] . 2662 Example of LIST NEWSGROUPS returning an error where the command is 2663 recognised but the software does not maintain this information: 2665 [C] LIST NEWSGROUPS 2666 [S] 503 program error, function not performed 2668 Example of LIST NEWSGROUPS sent to a server that does not recognize 2669 this command: 2671 [C] LIST NEWSGROUPS 2672 [S] 501 Syntax error 2674 8. Framework for NNTP extensions 2676 Although NNTP is widely and robustly deployed, some parts of the 2677 Internet community might wish to extend the NNTP service. This 2678 document defines a means whereby an extended NNTP client can query 2679 the server to determine the service extensions that it supports. 2681 It must be emphasized that any extension to the NNTP service should 2682 not be considered lightly. NNTP's strength comes primarily from its 2683 simplicity. Experience with many protocols has shown that: 2685 Protocols with few options tend towards ubiquity, whilst protocols 2686 with many options tend towards obscurity. 2688 This means that each and every extension, regardless of its benefits, 2689 must be carefully scrutinized with respect to its implementation, 2690 deployment, and interoperability costs. In many cases, the cost of 2691 extending the NNTP service will likely outweigh the benefit. 2693 Given this environment, the framework for extensions described in 2694 this document consists of: 2696 o a mechanism for clients to determine a server's available 2697 extensions 2699 o a registry of NNTP service extensions 2701 The LIST EXTENSIONS command is described in this document (see 2702 Section 5.3) and is the mechanism for clients to use to determine 2703 what extensions are available. Except where stated otherwise, the 2704 commands in this document are understood (even if not supported) by 2705 all servers and are not described in the list of features returned by 2706 the LIST EXTENSIONS command. 2708 The IANA shall maintain a registry of NNTP service extensions. 2710 An extension is identified by a unique extension-label, which is a 2711 string of 1 to 12 uppercase US-ASCII letters. The extension-label 2712 will often be the name of a new command that the extension adds. 2713 However this is not a requirement: an extension might not add any new 2714 commands or keywords. 2716 An extension is either a private extension or else it is included in 2717 the IANA registry and is defined in an RFC. Such RFCs either must be 2718 on the standards track or must define an IESG-approved experimental 2719 protocol. 2721 The definition of an extension must include: 2723 o a descriptive name for the extension; 2725 o the extension-label (which is returned by LIST EXTENSIONS to 2726 indicate to the client that the server supports this particular 2727 extension) - the extension-label of a registered extension MUST 2728 NOT begin with "X"; 2730 o the syntax, values, and meanings of any arguments following the 2731 extension-label in the output of LIST EXTENSIONS; 2733 o any new NNTP commands associated with the extension - the names of 2734 commands associated with registered extensions MUST NOT begin with 2735 "X"; 2737 o the syntax and possible values of arguments associated with the 2738 new NNTP commands; 2740 o the response codes and possible values of arguments for the 2741 responses of the new NNTP commands; 2743 o any new arguments the extension associates with any other 2744 pre-existing NNTP commands; 2746 o how support for the extension affects the behavior of a server and 2747 NNTP client; 2749 o any increase in the maximum length of commands and initial 2750 response lines over the value specified in this document; 2752 o a specific statement about the effect on pipelining this extension 2753 may have (if any); 2755 o a specific statement about the circumstances when use of this 2756 extension can alter the output from LIST EXTENSIONS; 2758 o the circumstances under which the extension can cause any 2759 pre-existing command to produce a 401, 480, or 483 response; 2761 o whether the extension can be used before or after the MODE READER 2762 command, and what changes (if any) the latter has on the 2763 extension. 2765 A private extension need not be included in the output of LIST 2766 EXTENSIONS. A server MAY provide additional keywords - either for new 2767 commands or new variants of existing commands - as part of a private 2768 extension. To avoid the risk of a clash with a future registered 2769 extension, the names of private extensions and commands defined by 2770 them SHOULD begin with "X". 2772 A server MUST NOT send different response codes to basic NNTP 2773 commands documented here or commands documented in registered 2774 extensions in response to the availability or use of a private 2775 extension. 2777 8.1 Initial IANA registry 2779 The IANA's initial registry of NNTP service extensions consists of 2780 these entries: 2782 +-------------------------+--------------+--------------------------+ 2783 | Extension | Label | Added behaviour | 2784 +-------------------------+--------------+--------------------------+ 2785 | Specific article | LISTGROUP | Defined in this document | 2786 | numbers | | | 2787 | | | | 2788 | Overview support | OVER | Defined in this document | 2789 | | | | 2790 | Batched header | HDR | Defined in this document | 2791 | retrieval | | | 2792 +-------------------------+--------------+--------------------------+ 2794 8.2 Standard extensions 2796 Each of the following sections describes an extension that a server 2797 MAY provide. If the server provides the extension, it MUST include 2798 the appropriate extension label in the response to LIST EXTENSIONS. 2799 If it does not provide it, it MUST NOT include the appropriate 2800 extension label. The descriptions of facilities in each section are 2801 written as if the extension is provided. If it is not provided, the 2802 entire section should be ignored. 2804 The formal definitions of these extensions are provided in Appendix 2805 D. 2807 If the server provides an extension, it MUST implement all of the 2808 commands in the specification of the extension except for those 2809 marked as optional. If it does not provide an extension, it MUST NOT 2810 implement any of the commands in the specification of that extension. 2812 8.3 The LISTGROUP extension 2814 This extension provides one command and has the extension label 2815 LISTGROUP. 2817 8.3.1 LISTGROUP 2818 8.3.1.1 Usage 2820 Syntax 2821 LISTGROUP [group] 2823 Responses 2824 211 number low high group Article numbers follow (multiline) 2825 411 No such newsgroup 2826 412 No newsgroup selected [1] 2828 Parameters 2829 group = name of newsgroup 2830 number = estimated number of articles in the group 2831 low = reported low water mark 2832 high = reported high water mark 2834 [1] The 412 response can only occur if no group has been specified. 2836 8.3.1.2 Description 2838 The LISTGROUP command is used to get a listing of all the article 2839 numbers in a particular newsgroup. 2841 The optional argument is the name of the newsgroup to be selected 2842 (e.g. "news.software.misc"). A list of valid newsgroups may be 2843 obtained from the LIST ACTIVE command. If no group is specified, the 2844 current selected newsgroup is used. 2846 The list of article numbers is returned as a multi-line response 2847 following the 211 response code (the arguments on the initial 2848 response line are the same as for the GROUP command (see Section 2849 6.1.1). The list contains one number per line, is in numerical order, 2850 and lists precisely those articles that exist in the group. 2852 When a valid group is selected by means of this command, the current 2853 selected newsgroup MUST be set to that group and the current article 2854 number MUST be set to the first article in the group. If an empty 2855 newsgroup is selected, the current article pointer is made invalid. 2856 If an invalid group is specified, the current selected newsgroup and 2857 current article number MUST NOT be changed. 2859 The LISTGROUP command MAY be used by a client as a replacement for 2860 the GROUP command in establishing a valid current selected newsgroup 2861 and current article number. 2863 If the group specified is not available on the server, a 411 response 2864 MUST be returned. If no group is specified and the current selected 2865 newsgroup is invalid, a 412 response MUST be returned. 2867 8.3.1.3 Examples 2869 Example of LISTGROUP on an empty group: 2871 [C] LISTGROUP example.empty.newsgroup 2872 [S] 211 0 0 0 example.empty.newsgroup list follows 2873 [S] . 2875 Example of LISTGROUP on a valid current selected newsgroup: 2877 [C] GROUP misc.test 2878 [S] 211 2000 3000234 3002322 misc.test 2879 [C] LISTGROUP 2880 [S] 211 2000 3000234 3002322 misc.test list follows 2881 [S] 3000234 2882 [S] 3000237 2883 [S] 3000238 2884 [S] 3000239 2885 [S] 3002322 2886 [S] . 2888 Example of LISTGROUP failing because no group has been selected: 2890 [Assumes current selected newsgroup is invalid.] 2891 [C] LISTGROUP 2892 [S] 412 no current group 2893 [C] GROUP example.is.sob.bradner.or.barber 2894 [S] 411 no such group 2895 [C] LISTGROUP 2896 [S] 412 no current group 2898 8.4 Article metadata 2900 The OVER and HDR extensions refer to the concept of "article 2901 metadata". This is data about articles that does not occur within the 2902 article itself. Each metadata item has a name which MUST begin with a 2903 colon (and which MUST NOT contain a colon elsewhere within it). 2905 When generating a metadata item, the server MUST compute it for 2906 itself and MUST NOT trust any related value provided in the article. 2907 (In particular, a Lines or Bytes header in the article MUST NOT be 2908 assumed to specify the correct number of lines or bytes in the 2909 article.) 2911 This specification defines two metadata items: ":bytes" and ":lines". 2913 Other metadata items may be defined by extensions. The names of 2914 metadata items defined by registered extensions MUST NOT begin with 2915 ":x-". To avoid the risk of a clash with a future registered 2916 extension, the names of metadata items defined by private extensions 2917 SHOULD begin with ":x-". 2919 8.4.1 The :bytes metadata item 2921 The :bytes metadata item for an article is a decimal integer. It MUST 2922 equal the number of octets in the entire article - headers, body, and 2923 separating empty line - except that each CRLF pair MAY (but SHOULD 2924 NOT) be counted as a single octet. 2926 8.4.2 The :lines metadata item 2928 The :lines metadata item for an article is a decimal integer. It MUST 2929 equal the number of lines in the article body (excluding the empty 2930 line separating headers and body); equivalently, it is two less than 2931 the number of CRLF pairs that the BODY command would return for that 2932 article (the extra two are those following the response code and the 2933 termination octet). 2935 8.5 The OVER extension 2937 This extension provides two commands, OVER and LIST OVERVIEW.FMT. The 2938 label for this extension is OVER. 2940 The OVER extension provides access to the "overview database", which 2941 is a database of headers extracted from incoming articles. Only 2942 certain headers are included in the database. The database also 2943 includes some article metadata. The information stored in the 2944 database may change over time. If the database records the content or 2945 absence of a given field (that is, a header or metadata item) for all 2946 articles, it is said to be "consistent" for that field. If it records 2947 the content of a header for some articles but not for others that 2948 nevertheless included that header, or records a metadata item for 2949 some articles but not others to which that item applies, it is said 2950 to be "inconsistent" for that field. 2952 The LIST OVERVIEW.FMT command SHOULD list all the fields for which 2953 the database is consistent at that moment. It MAY omit such fields 2954 (for example if it is not known whether the database is consistent or 2955 inconsistent). It MUST NOT include fields for which the database is 2956 inconsistent or which are not stored in the database. Therefore if a 2957 header appears in the LIST OVERVIEW.FMT output but not the OVER 2958 output for a given article, that header does not appear in the 2959 article, and similarly for metadata items. 2961 These rules assume the fields being stored in the database remain 2962 constant for long periods of time, with the database therefore being 2963 consistent. When the set of fields to be stored is changed, it will 2964 be inconsistent until either the database is rebuilt or the only 2965 articles remaining are those received since the change. Therefore the 2966 output from LIST OVERVIEW.FMT needs to be altered twice: before any 2967 fields stop being stored, they MUST be removed from the output, then 2968 when the database is once more known to be consistent, the new fields 2969 SHOULD be added to the output. 2971 This extension is based on the Overview/NOV database [ROBE1995] 2972 developed by Geoff Collyer. 2974 8.5.1 OVER 2976 8.5.1.1 Usage 2978 Syntax 2979 OVER message-id 2980 OVER range 2981 OVER 2983 Responses 2985 First form (message-id specified) 2986 224 Overview information follows (multiline) 2987 430 No article with that message-id 2989 Second form (range specified) 2990 224 Overview information follows (multiline) 2991 412 No newsgroup selected 2992 423 No articles in that range 2994 Third form (current article number used) 2995 224 Overview information follows (multiline) 2996 412 No newsgroup selected 2997 420 Current article number is invalid 2999 Parameters 3000 range = number(s) of articles 3001 message-id = message-id of article 3003 8.5.1.2 Description 3005 The OVER command returns the contents of the headers and metadata in 3006 the database for an article specified by message-id, or from a 3007 specified article or range of articles in the current selected 3008 newsgroup. 3010 The message-id argument indicates a specific article. The range 3011 argument may be any of the following: 3013 o an article number 3015 o an article number followed by a dash to indicate all following 3017 o an article number followed by a dash followed by another article 3018 number 3020 If neither is specified, the current article number is used. 3022 If the information is available, it is returned as a multi-line 3023 response following the 224 response code and contains one line per 3024 article, sorted in numerical order of article number (note that 3025 unless the argument is a range including a dash, there will only be 3026 one line but it will still be in multi-line format). Each line 3027 consists of a number of fields separated by a TAB. A field may be 3028 empty (in which case there will be two adjacent TABs), and a sequence 3029 of trailing TABs may be omitted. 3031 The first 8 fields MUST be the following, in order: 3033 "0" (first form) or article number (second form) 3034 Subject header content 3035 From header content 3036 Date header content 3037 Message-ID header content 3038 References header content 3039 :bytes metadata item 3040 :lines metadata item 3042 If the article is specified by message-id rather than by article 3043 range, the article number is given as "0". 3045 Any subsequent fields are the contents of the other headers and 3046 metadata held in the database. 3048 For the five mandatory headers, the content of each field MUST be 3049 based on the content of the header (that is, with the header name and 3050 following colon and space removed). If the article does not contain 3051 that header, or if the content is empty, the field MUST be empty. For 3052 the two mandatory metadata items, the content of the field MUST be 3053 just the value, with no other text. 3055 For all subsequent fields that contain headers, the content MUST be 3056 the entire header line other than the trailing CRLF. For all 3057 subsequent fields that contain metadata, the field consists of the 3058 metadata name, a single space, and then the value. 3060 For all fields, the value is processed by first removing all CRLF 3061 pairs (that is, undoing any folding and removing the terminating 3062 CRLF) and then replacing each TAB with a single space. If there is no 3063 such header in the article, or no such metadata item, or no header or 3064 item stored in the database for that article, the corresponding field 3065 MUST be empty. 3067 Note that, after unfolding, the characters NUL, LF, and CR cannot 3068 occur in the header of an article offered by a conformant server. 3069 Nevertheless, servers SHOULD check for these characters and replace 3070 each one by a single space (so that, for example, CR LF LF TAB will 3071 become two spaces, since the CR and first LF will be removed by the 3072 unfolding process). This will encourage robustness in the face of 3073 non-conforming data; it is also possible that future versions of this 3074 specification may permit these characters to appear in articles. 3076 The server SHOULD NOT produce output for articles that no longer 3077 exist. 3079 If the argument is a message-id and no such article exists, a 430 3080 response MUST be returned. If the argument is a range or is omitted 3081 and the current selected newsgroup is invalid, a 412 response MUST be 3082 returned. If the argument is a range and no articles in that number 3083 range exist in the current selected newsgroup, a 423 response MUST be 3084 returned. If the argument is omitted and the current article number 3085 is invalid, a 420 response MUST be returned. 3087 8.5.1.3 Examples 3089 In the first three examples, TAB has been replaced by vertical bar 3090 and some lines have been folded for readability. 3092 Example of a successful retrieval of overview information for an 3093 article (using no article number): 3095 [C] GROUP misc.test 3096 [S] 211 1234 3000234 3002322 misc.test 3097 [C] OVER 3098 [S] 224 Overview information follows 3099 [S] 300234|I am just a test article|"Demo User" 3100 |6 Oct 1998 04:38:40 -0500| 3101 <45223423@example.com>|<45454@example.net>|1234| 3102 17|Xref: news.example.com misc.test:3000363 3103 [S] . 3105 Example of a successful retrieval of overview information for an 3106 article by message-id: 3108 [C] OVER <45223423@example.com> 3109 [S] 224 Overview information follows 3110 [S] 0|I am just a test article|"Demo User" 3111 |6 Oct 1998 04:38:40 -0500| 3112 <45223423@example.com>|<45454@example.net>|1234| 3113 17|Xref: news.example.com misc.test:3000363 3114 [S] . 3116 Note that the article number has been replaced by "0". 3118 Example of a successful retrieval of overview information for a range 3119 of articles: 3121 [C] GROUP misc.test 3122 [S] 211 1234 3000234 3002322 misc.test 3123 [C] OVER 3000234-3000240 3124 [S] 224 Overview information follows 3125 [S] 300234|I am just a test article|"Demo User" 3126 |6 Oct 1998 04:38:40 -0500| 3127 <45223423@example.com>|<45454@example.net>|1234| 3128 17|Xref: news.example.com misc.test:3000363 3129 [S] 3000235|Another test article|nobody@nowhere.to 3130 (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>|| 3131 4818|37||Distribution: fi 3132 [S] 3000238|Re: I am just a test article|somebody@elsewhere.to| 3133 7 Oct 1998 11:38:40 +1200|| 3134 <45223423@to.to>|9234|51 3135 [S] . 3137 Note the missing "References" and Xref headers in the second line, 3138 the missing trailing field(s) in the first and last lines, and that 3139 there are only results for those articles that still exist. 3141 Example of an unsuccessful retrieval of overview information on an 3142 article by number: 3144 [C] GROUP misc.test 3145 [S] 211 1234 3000234 3002322 misc.test 3146 [C] OVER 300256 3147 [S] 420 No such article in this group 3149 Example of an unsuccessful retrieval of overview information by 3150 number because no newsgroup was selected first: 3152 [Assumes current selected newsgroup is invalid.] 3154 [C] OVER 3155 [S] 412 No newsgroup selected 3157 Example of an attempt to retrieve information when the current 3158 selected newsgroup is empty: 3160 [C] GROUP example.empty.newsgroup 3161 [S] 211 0 0 0 example.empty.newsgroup 3162 [C] OVER 3163 [S] 420 No current article selected 3165 8.5.2 LIST OVERVIEW.FMT 3167 8.5.2.1 Usage 3169 This command is optional. 3171 Syntax 3172 LIST OVERVIEW.FMT 3174 Responses 3175 215 Information follows (multiline) 3177 8.5.2.2 Description 3179 The LIST OVERVIEW.FMT command returns a description of the fields in 3180 the database for which it is consistent (as described above). 3182 If the information is available, it is returned as a multi-line 3183 response following the 215 response code. The information contains 3184 one line per field in the order they are returned by the OVER 3185 command; the first 7 lines MUST be exactly: 3187 Subject: 3188 From: 3189 Date: 3190 Message-ID: 3191 References: 3192 :bytes 3193 :lines 3195 except that, for compatibility with existing implementations, the 3196 last two lines MAY instead be: 3198 Bytes: 3199 Lines: 3201 even though they refer to metadata, not headers. 3203 All subsequent lines MUST consist of either a header name followed by 3204 ":full", or the name of a piece of metadata. 3206 There are no leading or trailing spaces in the output. 3208 Note that the 7 fixed lines describe the 2nd to 8th fields of the 3209 OVER output. The "full" suffix is a reminder that the corresponding 3210 fields include the header name. 3212 This command MAY generate different results if used more than once in 3213 a session. 3215 8.5.2.3 Examples 3217 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3218 output above, using the preferred format: 3220 [C] LIST OVERVIEW.FMT 3221 [S] 215 Order of fields in overview database. 3222 [S] Subject: 3223 [S] From: 3224 [S] Date: 3225 [S] Message-ID: 3226 [S] References: 3227 [S] :bytes 3228 [S] :lines 3229 [S] Xref:full 3230 [S] Distribution:full 3231 [S] . 3233 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3234 output above, using the alternative format: 3236 [C] LIST OVERVIEW.FMT 3237 [S] 215 Order of fields in overview database. 3238 [S] Subject: 3239 [S] From: 3240 [S] Date: 3241 [S] Message-ID: 3242 [S] References: 3243 [S] Bytes: 3244 [S] Lines: 3245 [S] Xref:full 3246 [S] Distribution:full 3247 [S] . 3249 Example of LIST OVERVIEW.FMT returning an error where the command is 3250 recognised but the software does not maintain this information: 3252 [C] LIST OVERVIEW.FMT 3253 [S] 503 overview.fmt not available 3255 8.6 The HDR extension 3257 This extension provides two new commands: HDR and LIST HEADERS. The 3258 label for this extension is HDR. 3260 The HDR extension provides access to specific headers and metadata 3261 items (collectively "fields") of articles or groups of articles. In 3262 the case of headers, an implementation MAY restrict the use of this 3263 extension to a specific list of headers or MAY allow it to be used 3264 with any header. In the latter case it MUST use the argument "ALL" 3265 following the extension label in the output of LIST EXTENSIONS; in 3266 the former case it MUST NOT use any argument. 3268 The HDR command may take information from a database rather than 3269 directly from the articles. If so, the same issues of consistency and 3270 inconsistency apply as with the OVER extension (Section 8.5) and the 3271 LIST HEADERS command SHOULD take the same approach as the LIST 3272 OVERVIEW.FMT command in resolving them. 3274 8.6.1 HDR 3276 8.6.1.1 Usage 3278 Syntax 3279 HDR header message-id 3280 HDR header range 3281 HDR header 3283 Responses 3285 First form (message-id specified) 3286 225 Headers follow (multiline) 3287 430 No article with that message-id 3289 Second form (range specified) 3290 225 Headers follow (multiline) 3291 412 No newsgroup selected 3292 423 No articles in that range 3294 Third form (current article number used) 3295 225 Headers follow (multiline) 3296 412 No newsgroup selected 3297 420 Current article number is invalid 3299 Parameters 3300 header = name of header, without the colon 3301 range = number(s) of articles 3302 message-id = message-id of article 3304 8.6.1.2 Description 3306 The HDR command retrieves specific headers from an article specified 3307 by message-id, or from a specified article or range of articles in 3308 the current selected newsgroup. It can also return certain metadata 3309 about the article or articles. 3311 The required header argument is the name of a header (e.g. "subject") 3312 in an article, or the name of a metadata item, and is 3313 case-insensitive. Names of metadata items always begin with a colon. 3314 Except where stated otherwise, metadata items are treated as if they 3315 were header contents, and references to headers in this description 3316 apply equally to metadata items. 3318 The message-id argument indicates a specific article. The range 3319 argument may be any of the following: 3321 o an article number 3323 o an article number followed by a dash to indicate all following 3325 o an article number followed by a dash followed by another article 3326 number 3328 If neither is specified, the current article number is used. 3330 If the information is available, it is returned as a multi-line 3331 response following the 225 response code and contains one line for 3332 each article where the relevant header line or metadata item exists 3333 (note that unless the argument is a range including a dash, there 3334 will be at most one line but it will still be in multi-line format). 3335 The line consists of the article number, a space, and then the 3336 contents of the header (without the header name or the colon and 3337 space that follow it) or metadata item. If the article is specified 3338 by message-id, the article number is given as "0". 3340 Header contents are modified as follows: all CRLF pairs are removed, 3341 and then each TAB is replaced with a single space (note that this is 3342 the same transformation as is performed by the OVER extension 3343 (Section 8.5.1.2), and the same comment concerning NUL, CR, and LF 3344 applies). 3346 The header content is in all cases taken from the article. This means 3347 that, for example, a request for the header "Lines" returns the 3348 contents of the "Lines" header of the specified articles, if any, not 3349 the line count metadata or any other server-generated value. If the 3350 header occurs in a given article multiple times, only the content of 3351 the first occurrence is returned by HDR. 3353 If the requested header is not present in the article or if it is 3354 present but empty, a line for that article is included in the output 3355 but the header content portion of the line is empty (the space after 3356 the article number MAY be retained or omitted). If any article number 3357 in the provided range does not exist in the group, no line for that 3358 article number is included in the output. 3360 If the second argument is a message-id and no such article exists, a 3361 430 response MUST be returned. If the second argument is a range or 3362 is omitted and the current selected newsgroup is invalid, a 412 3363 response MUST be returned. If the second argument is a range and no 3364 articles in that number range exist in the current selected 3365 newsgroup, a 423 response MUST be returned. If the second argument is 3366 omitted and the current article number is invalid, a 420 response 3367 MUST be returned. 3369 A server MAY only allow HDR commands for a limited set of headers and 3370 metadata items. If so, it MUST respond with the generic 503 response 3371 to attempts to request other headers, rather than returning erroneous 3372 results such as a successful empty response. 3374 If HDR uses a separate database and it is inconsistent for the 3375 requested header or metadata item, the server MAY return what results 3376 it can or it MAY respond with the generic 503 response; in the latter 3377 case, the field MUST NOT appear in the output from LIST HEADERS. 3379 8.6.1.3 Examples 3381 Example of a successful retrieval of subject lines from a range of 3382 articles (3000235 has no Subject header, and 3000236 is missing): 3384 [C] GROUP misc.test 3385 [S] 211 1234 3000234 3002322 misc.test 3386 [C] HDR Subject 3000234-300238 3387 [S] 225 Headers follow 3388 [S] 3000234 I am just a test article 3390 [S] 3000235 3391 [S] 3000237 Re: I am just a test article 3392 [S] 3000238 Ditto 3393 [S] . 3395 Example of a successful retrieval of line counts from a range of 3396 articles: 3398 [C] GROUP misc.test 3399 [S] 211 1234 3000234 3002322 misc.test 3400 [C] HDR :lines 3000234-300238 3401 [S] 225 Headers follow 3402 [S] 3000234 42 3403 [S] 3000235 5 3404 [S] 3000237 11 3405 [S] 3000238 2378 3406 [S] . 3408 Example of a successful retrieval of the subject line from an article 3409 by message-id: 3411 [C] GROUP misc.test 3412 [S] 211 1234 3000234 3002322 misc.test 3413 [C] HDR subject 3414 [S] 225 Header information follows 3415 [S] 0 I am just a test article 3416 [S] . 3418 Example of a successful retrieval of the subject line from the 3419 current article: 3421 [C] GROUP misc.test 3422 [S] 211 1234 3000234 3002322 misc.test 3423 [C] HDR subject 3424 [S] 225 Header information follows 3425 [S] 3000234 I am just a test article 3426 [S] . 3428 Example of an unsuccessful retrieval of a header from an article by 3429 message-id: 3431 [C] HDR subject 3432 [S] 430 No Such Article Found 3434 Example of an unsuccessful retrieval of headers from articles by 3435 number because no newsgroup was selected first: 3437 [Assumes current selected newsgroup is invalid.] 3439 [C] HDR subject 300256- 3440 [S] 412 No newsgroup selected 3442 Example of an unsuccessful retrieval of headers because the current 3443 selected newsgroup is empty: 3445 [C] GROUP example.empty.newsgroup 3446 [S] 211 0 0 0 example.empty.newsgroup 3447 [C] HDR subject 1- 3448 [S] 423 No articles in that range 3450 Example of an unsuccessful retrieval of headers because the server 3451 does not allow HDR commands for that header: 3453 [C] GROUP misc.test 3454 [S] 211 1234 3000234 3002322 misc.test 3455 [C] HDR Content-Type 3000234-300238 3456 [S] 503 HDR not permitted on Content-Type 3458 8.6.2 LIST HEADERS 3460 8.6.2.1 Usage 3462 Syntax 3463 LIST HEADERS 3465 Responses 3466 215 Header and metadata list follows (multiline) 3468 8.6.2.2 Description 3470 The LIST HEADERS command returns a list of headers and metadata items 3471 that may be retrieved using the HDR command. 3473 The information is returned as a multi-line response following the 3474 215 response code and contains one line for each header or metadata 3475 item name (excluding the colon in the former case). If the 3476 implementation allows any header to be retrieved (also indicated by 3477 the "ALL" argument to the extension label) it MUST NOT include any 3478 header names in the list but MUST include the special entry ":" (a 3479 single colon on its own); it MUST still list any metadata items that 3480 are available. The order of items in the list is not significant; the 3481 server need not even consistently return the same order. The list MAY 3482 be empty (though in this circumstance there is little point in 3483 providing the extension). 3485 An implementation that also supports the OVER extension SHOULD at 3486 least permit all the headers and metadata items listed in the output 3487 from the LIST OVERVIEW.FMT command. 3489 8.6.2.3 Examples 3491 Example of an implementation providing access to only a few headers: 3493 [C] LIST EXTENSIONS 3494 [S] 202 extensions supported: 3495 [S] HDR 3496 [S] . 3497 [C] LIST HEADERS 3498 [S] 215 headers supported: 3499 [S] Subject 3500 [S] Message-ID 3501 [S] Xref 3502 [S] . 3504 Example of an implementation providing access to the same fields as 3505 the first example in Section 8.5.2.3: 3507 [C] LIST EXTENSIONS 3508 [S] 202 extensions supported: 3509 [S] OVER 3510 [S] HDR 3511 [S] . 3512 [C] LIST HEADERS 3513 [S] 215 headers and metadata items supported: 3514 [S] Date 3515 [S] Distribution 3516 [S] From 3517 [S] Message-ID 3518 [S] References 3519 [S] Subject 3520 [S] Xref 3521 [S] :bytes 3522 [S] :lines 3523 [S] . 3525 Example of an implementation providing access to all headers: 3527 [C] LIST EXTENSIONS 3528 [S] 202 extensions supported: 3529 [S] HDR ALL 3530 [S] . 3531 [C] LIST HEADERS 3532 [S] 215 metadata items supported: 3534 [S] : 3535 [S] :lines 3536 [S] :bytes 3537 [S] :x-article-number 3538 [S] . 3540 9. Augmented BNF Syntax for NNTP 3542 Each of the following sections describes the syntax of a major 3543 element of NNTP. This syntax extends and refines the descriptions 3544 elsewhere in this specification, and should be given precedence when 3545 resolving apparent conflicts. Note that ABNF [RFC2234] strings are 3546 case insensitive. Non-terminals used in several places are defined in 3547 a separate section at the end. 3549 9.1 Commands 3551 This syntax defines the non-terminal "command-line", which 3552 represents what is sent from the client to the server. 3554 command-line = command EOL 3555 command = article-command / 3556 body-command / 3557 date-command / 3558 group-command / 3559 hdr-command / 3560 head-command / 3561 help-command / 3562 ihave-command / 3563 last-command / 3564 list-active-command / 3565 list-active-times-command / 3566 list-distrib-pats-command / 3567 list-distributions-command / 3568 list-extensions-command / 3569 list-headers-command / 3570 list-newsgroups-command / 3571 list-overview-fmt-command / 3572 listgroup-command / 3573 mode-reader-command / 3574 newgroups-command / 3575 newnews-command / 3576 next-command / 3577 over-command / 3578 post-command / 3579 quit-command / 3580 stat-command / 3581 x-command 3583 article-command = "ARTICLE" [article-ref] 3584 body-command = "BODY" [article-ref] 3585 date-command = "DATE" 3586 group-command = "GROUP" WS newsgroup-name 3587 hdr-command = "HDR" WS header-meta-name [range-ref] 3588 head-command = "HEAD" [article-ref] 3589 help-command = "HELP" 3590 ihave-command = "IHAVE" WS message-id 3591 last-command = "LAST" 3592 list-active-command = "LIST" [WS "ACTIVE" [WS wildmat]] 3593 list-active-times-command = "LIST" WS "ACTIVE.TIMES" [WS wildmat] 3594 list-distrib-pats-command = "LIST" WS "DISTRIB.PATS" 3595 list-distributions-command = "LIST" WS "DISTRIBUTIONS" 3596 list-extensions-command = "LIST" WS "EXTENSIONS" 3597 list-headers-command = "LIST" WS "HEADERS" 3598 list-newsgroups-command = "LIST" WS "NEWSGROUPS" [WS wildmat] 3599 list-overview-fmt-command = "LIST" WS "OVERVIEW.FMT" 3600 listgroup-command = "LISTGROUP" [WS newsgroup-name] 3601 mode-reader-command = "MODE" WS "READER" 3602 newgroups-command = "NEWGROUPS" WS date-time 3603 newnews-command = "NEWNEWS" WS wildmat WS date-time 3604 next-command = "NEXT" 3605 over-command = "OVER" [WS range-ref] 3606 post-command = "POST" 3607 quit-command = "QUIT" 3608 stat-command = "STAT" [article-ref] 3609 x-command = x-command-name *(WS x-argument) 3610 ; Each extension command is specified fully elsewhere 3612 article-ref = WS (article-number / message-id) 3613 article-number = 1*16DIGIT 3614 date = [2DIGIT] 6DIGIT 3615 date-time = date WS time [WS "GMT"] 3616 header-meta-name = header-name / metadata-name 3617 metadata-name = ":" 1*A-NOTCOLON 3618 newsgroup-name = 1*wildmat-exact 3619 range = article-number ["-" [article-number]] 3620 range-ref = WS (range / message-id) 3621 time = 6DIGIT 3622 x-command-name = 3*12A-CHAR 3623 x-argument = 1*P-CHAR 3625 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 3626 wildmat-pattern = 1*wildmat-item 3627 wildmat-item = wildmat-exact / wildmat-wild 3628 wildmat-exact = %x21-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 3629 UTF8-non-ascii ; exclude * , ? [ \ ] 3630 wildmat-wild = "*" / "?" 3632 9.2 Responses 3634 This syntax defines the non-terminal "response", which represents 3635 what is sent from the server to the client in response to a command. 3637 response = simple-response / multiline-response 3638 multiline-response = simple-response *content-line termination 3639 termination = "." CRLF 3640 content-line = [content-text] CRLF 3641 content-text = (".." / B-NONDOT) *B-CHAR 3643 simple-response = 3DIGIT arguments [ SP trailing-comment ] CRLF 3644 trailing-comment = *U-CHAR 3645 arguments = *( SP argument ) ; How many depends on the response 3646 argument = 1*A-CHAR 3648 9.3 Articles 3650 This syntax defines the non-terminal "article", which represents the 3651 format of an article as described in Section 3.4. 3653 article = 1*header CRLF body 3654 header = header-name ":" [CRLF] SP header-content CRLF 3655 header-content = *( P-CHAR / [CRLF] WS ) 3656 body = *(*B-CHAR CRLF) 3658 9.4 General non-terminals 3660 header-name = 1*A-NOTCOLON 3661 message-id = "<" 1*248A-NOTGT ">" 3663 ; Assorted special character sets 3664 ; A- means based on ASCII, excluding controls and SP 3665 ; P- means based on UTF-8, excluding controls and SP 3666 ; U- means based on UTF-8, excluding NUL CR and LF 3667 ; B- means based on bytes, excluding NUL CR and LF 3668 A-CHAR = %x21-7E 3669 A-NOTCOLON = %x21-39 / %x3B-7E ; exclude ":" 3670 A-NOTGT = %x21-3D / %x3F-7E ; exclude ">" 3671 P-CHAR = A-CHAR / UTF8-non-ascii 3672 U-CHAR = %x01-09 / %x0B-0C / %x0E-7F / UTF8-non-ascii 3673 B-CHAR = %x01-09 / %x0B-0C / %x0E-FF 3674 B-NONDOT = %x01-09 / %x0B-0C / %x0E-2D / %x2F-FF ; exclude "." 3676 CR = %x0D 3677 CRLF = CR LF 3678 DIGIT = %x30-39 3679 EOL = *(SP / HT) CRLF 3680 HT = %x09 3681 LF = %x0A 3682 SP = %x20 3683 UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4 3684 UTF8-2 = %xC2-DF UTF8-tail 3685 UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail / 3686 %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail 3687 UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail / 3688 %xF4 %x80-8F 2UTF8-tail 3689 UTF8-tail = %x80-BF 3690 WS = 1*(SP / HT) 3692 10. IANA Considerations 3694 This specification requires IANA to keep a registry of 3695 extension-labels. The initial contents of this registry are specified 3696 in Section 8.1. As described in Section 8, names beginning with X are 3697 reserved for private use while all other names are to be associated 3698 with a specification in an RFC on the standards-track or defining an 3699 IESG-approved experimental protocol. 3701 11. Security Considerations 3703 This section is meant to inform application developers, information 3704 providers, and users of the security limitations in NNTP as described 3705 by this document. The discussion does not include definitive 3706 solutions to the problems revealed, though it does make some 3707 suggestions for reducing security risks. 3709 11.1 Personal and Proprietary Information 3711 NNTP, because it was created to distribute network news articles, 3712 will forward whatever information is stored in those articles. 3713 Specification of that information is outside this scope of this 3714 document, but it is likely that some personal and/or proprietary 3715 information is available in some of those articles. It is very 3716 important that designers and implementers provide informative 3717 warnings to users so personal and/or proprietary information in 3718 material that is added automatically to articles (e.g. in headers) is 3719 not disclosed inadvertently. Additionally, effective and easily 3720 understood mechanisms to manage the distribution of news articles 3721 SHOULD be provided to NNTP Server administrators, so that they are 3722 able to report with confidence the likely spread of any particular 3723 set of news articles. 3725 11.2 Abuse of Server Log Information 3727 A server is in the position to save session data about a user's 3728 requests that might identify their reading patterns or subjects of 3729 interest. This information is clearly confidential in nature and its 3730 handling can be constrained by law in certain countries. People using 3731 the NNTP protocol to provide data are responsible for ensuring that 3732 such material is not distributed without the permission of any 3733 individuals that are identifiable by the published results. 3735 11.3 Weak Authentication and Access Control 3737 There is no user-based or token-based authentication in the basic 3738 NNTP specification. Access is normally controlled by server 3739 configuration files. Those files specify access by using domain names 3740 or IP addresses. However, this specification does permit the creation 3741 of extensions to the NNTP protocol itself for such purposes. While 3742 including such mechanisms is optional, doing so is strongly 3743 encouraged. 3745 Other mechanisms are also available. For example, a proxy server 3746 could be put in place that requires authentication before connecting 3747 via the proxy to the NNTP server. 3749 11.4 DNS Spoofing 3751 Many existing NNTP implementations authorize incoming connections by 3752 checking the IP address of that connection against the IP addresses 3753 obtained via DNS lookups of lists of domain names given in local 3754 configuration files. Servers that use this type of authentication, 3755 and clients that find a server by doing a DNS lookup of the server 3756 name, rely very heavily on the Domain Name Service, and are thus 3757 generally prone to security attacks based on the deliberate 3758 misassociation of IP addresses and DNS names. Clients and servers 3759 need to be cautious in assuming the continuing validity of an IP 3760 number/DNS name association. 3762 In particular, NNTP clients and servers SHOULD rely on their name 3763 resolver for confirmation of an IP number/DNS name association, 3764 rather than caching the result of previous host name lookups. Many 3765 platforms already can cache host name lookups locally when 3766 appropriate, and they SHOULD be configured to do so. It is proper for 3767 these lookups to be cached, however, only when the TTL (Time To Live) 3768 information reported by the name server makes it likely that the 3769 cached information will remain useful. 3771 If NNTP clients or servers cache the results of host name lookups in 3772 order to achieve a performance improvement, they MUST observe the TTL 3773 information reported by DNS. If NNTP clients or servers do not 3774 observe this rule, they could be spoofed when a previously accessed 3775 server's IP address changes. As network renumbering is expected to 3776 become increasingly common, the possibility of this form of attack 3777 will grow. Observing this requirement thus reduces this potential 3778 security vulnerability. 3780 This requirement also improves the load-balancing behavior of clients 3781 for replicated servers using the same DNS name and reduces the 3782 likelihood of a user's experiencing failure in accessing sites that 3783 use that strategy. 3785 11.5 UTF-8 issues 3787 UTF-8 [RFC2279] permits only certain sequences of octets and 3788 designates others as either malformed or "illegal". The Unicode 3789 standard identifies a number of security issues related to illegal 3790 sequences and forbids their generation by conforming implementations. 3792 Implementations of this specification MUST NOT generate malformed or 3793 illegal sequences and SHOULD detect them and take some appropriate 3794 action. This could include: 3796 o generating a 501 response code. 3798 o replacing such sequences by the sequence %xEF.BF.BD, which encodes 3799 the "replacement character" U+FFFD; 3801 o closing the connection; 3803 o replacing such sequences by a "guessed" valid sequence (based on 3804 properties of the UTF-8 encoding); 3806 In the last case, the implementation MUST ensure that any replacement 3807 cannot be used to bypass validity or security checks. For example, 3808 the illegal sequence %xC0.A0 is an over-long encoding for space 3809 (%x20). If it is replaced by the latter in a command line, this needs 3810 to happen before the command line is parsed into individual 3811 arguments. If the replacement came after parsing, it would be 3812 possible to generate an argument with an embedded space, which is 3813 forbidden. Use of the "replacement character" does not have this 3814 problem, since it is permitted wherever non-US-ASCII characters are. 3815 Implementations SHOULD use one of the first two solutions where the 3816 general structure of the NNTP stream remains intact, and close the 3817 connection if it is no longer possible to parse it sensibly. 3819 11.6 Caching of LIST EXTENSIONS results 3821 The LIST EXTENSIONS command provides information about the extensions 3822 currently available from the server. Whenever there is a relevant 3823 change to the server state, the results of this command are required 3824 to change accordingly. 3826 In most situations the results from this command in a given server 3827 state will not change from session to session; a given extension will 3828 be installed permanently on a server. Some clients may therefore wish 3829 to remember which extensions a server supports to avoid the delay of 3830 an additional command and response, particularly if they open 3831 multiple connections in the same session. 3833 However, information about extensions related to security and privacy 3834 MUST NOT be cached, since this could allow a variety of attacks. 3836 For example, consider a server which permits the use of cleartext 3837 passwords on links that are encrypted but not otherwise: 3839 [Initial TCP connection setup completed.] 3840 [S] 200 NNTP Service Ready, posting permitted 3841 [C] LIST EXTENSIONS 3842 [S] 202 Extensions supported: 3843 [S] XENCRYPT 3844 [S] . 3845 [C] XENCRYPT 3847 [Client and server negotiate encryption on the link] 3848 [S] 283 Encrypted link established 3849 [C] LIST EXTENSIONS 3850 [S] 202 Extensions supported: 3851 [S] XSECRET 3852 [S] . 3853 [C] XSECRET fred flintstone 3854 [S] 290 Password for fred accepted 3856 If the client caches the last LIST EXTENSIONS result, then on the 3857 next session it will attempt to use XSECRET on an unencrypted link: 3859 [Initial TCP connection setup completed.] 3860 [S] 200 NNTP Service Ready, posting permitted 3861 [C] XSECRET fred flintstone 3862 [S] 483 Only permitted on secure links 3864 exposing the password to any eavesdropper. While the primary cause of 3865 this is passing a secret without first checking the security of the 3866 link, caching of LIST EXTENSIONS results can increase the risk. 3868 Any security extension should include requirements to check the 3869 security state of the link in a manner appropriate to that extension. 3871 Caching should normally only be considered for anonymous clients that 3872 do not use any security or privacy extensions and for which the time 3873 required for an additional command and response is a noticable issue. 3875 12. Acknowledgments 3877 The author acknowledges the original authors of NNTP as documented in 3878 RFC 977 [RFC977]: Brian Kantor and Phil Lapsey. 3880 The author gratefully acknowledges the work of the NNTP committee 3881 chaired by Eliot Lear. The organization of this document was 3882 influenced by the last available draft from this working group. A 3883 special thanks to Eliot for generously providing the original 3884 machine-readable sources for that document. 3886 The author gratefully acknowledges the work of the DRUMS working 3887 group, specifically RFC 1869 [RFC1869], which is the basis of the 3888 NNTP extensions mechanism detailed in this document. 3890 The author gratefully acknowledges the authors of RFC 2616 [RFC2616] 3891 for providing specific and relevant examples of security issues that 3892 should be considered for HTTP. Since many of the same considerations 3893 exist for NNTP, those examples that are relevant have been included 3894 here with some minor rewrites. 3896 The author gratefully acknowledges the comments and additional 3897 information provided by the following individuals in preparing one or 3898 more of the progenitors of this document: 3900 Russ Allbery 3901 Wayne Davison 3902 Chris Lewis 3903 Tom Limoncelli 3904 Eric Schnoebelen 3905 Rich Salz 3907 This work was motivated by the work of various news reader authors 3908 and news server authors, which includes those listed below: 3910 Rick Adams 3911 Original author of the NNTP extensions to the RN news reader and 3912 last maintainer of Bnews 3914 Stan Barber 3915 Original author of the NNTP extensions to the news readers that 3916 are part of Bnews 3918 Geoff Collyer 3919 Original author of the OVERVIEW database proposal and one of the 3920 original authors of CNEWS 3922 Dan Curry 3923 Original author of the xvnews news reader 3925 Wayne Davison 3926 Author of the first threading extensions to the RN news reader 3927 (commonly called TRN) 3929 Geoff Huston 3930 Original author of ANU NEWS 3932 Phil Lapsey 3933 Original author of the UNIX reference implementation for NNTP 3935 Iain Lea 3936 Original maintainer of the TIN news reader 3938 Chris Lewis 3939 First known implementer of the AUTHINFO GENERIC extension 3941 Rich Salz 3942 Original author of INN 3944 Henry Spencer 3945 One of the original authors of CNEWS 3947 Kim Storm 3948 Original author of the NN news reader 3950 Finally, the present author gratefully acknowledges the vast amount 3951 of work put into previous drafts by the previous author: 3953 Stan Barber 3955 Normative References 3957 [ANSI1986] 3958 American National Standards Institute, "Coded Character 3959 Set - 7-bit American Standard Code for Information 3960 Interchange", ANSI X3.4, 1986. 3962 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3963 Requirement Levels", BCP 14, RFC 2119, March 1997. 3965 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3966 Specifications: ABNF", RFC 2234, November 1997. 3968 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 3969 10646", RFC 2279, January 1998. 3971 [RFC977] Kantor, B. and P. Lapsley, "Network News Transfer 3972 Protocol", RFC 977, February 1986. 3974 [TF.686-1] 3975 International Telecommunications Union - Radio, "Glossary, 3976 ITU-R Recommendation TF.686-1", ITU-R Recommendation 3977 TF.686-1, October 1997. 3979 Informative References 3981 [RFC1036] Horton, M. and R. Adams, "Standard for interchange of 3982 USENET messages", RFC 1036, December 1987. 3984 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 3985 Specification, Implementation", RFC 1305, March 1992. 3987 [RFC1869] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D. 3988 Crocker, "SMTP Service Extensions", STD 10, RFC 1869, 3989 November 1995. 3991 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 3992 Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext 3993 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3995 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 3996 June 1999. 3998 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 3999 2001. 4001 [RFC2980] Barber, S., "Common NNTP Extensions", RFC 2980, October 4002 2000. 4004 [ROBE1995] 4005 Robertson, R., "FAQ: Overview database / NOV General 4006 Information", January 1995. 4008 [SALZ1992] 4009 Salz, R., "Manual Page for wildmat(3) from the INN 1.4 4010 distribution, Revision 1.10", April 1992. 4012 Author's Address 4014 Clive D.W. Feather 4015 Thus plc 4016 322 Regents Park Road 4017 London N3 2QQ 4018 GB 4020 Phone: +44 20 8495 6138 4021 Fax: +44 870 051 9937 4022 EMail: clive@demon.net 4023 URI: http://www.davros.org/ 4025 Appendix A. Future Directions 4027 It has been proposed that the response code range 6xx is used for 4028 multiline responses. While existing commands and extensions do not 4029 use this, it would at least limit the problem clients would face in 4030 dealing with an unknown response. 4032 Appendix B. Interaction with other specifications 4034 NNTP is most often used for transferring articles that conform to RFC 4035 1036 [RFC1036] (such articles are called "Usenet articles" here). It 4036 is also sometimes used for transferring email messages that conform 4037 to RFC 2822 [RFC2822] (such articles are called "email articles" 4038 here). In this situation, articles must conform both to this 4039 specification and to that other one; this appendix describes some 4040 relevant issues. 4042 B.1 Header folding 4044 NNTP allows a header line to be folded (by inserting a CRLF pair) 4045 before any space or TAB character. 4047 Both email and Usenet articles are required to have at least one 4048 octet other than space or TAB on each header line. Thus folding can 4049 only happen at one point in each sequence of consecutive spaces or 4050 TABs. Usenet articles are further required to have the header name, 4051 colon, and following space all on the first line; folding may only 4052 happen beyond that space. Finally, some non-conforming software will 4053 remove trailing spaces and TABs from a line. Therefore it might be 4054 inadvisable to fold a header after a space or TAB. 4056 For maximum safety, header lines SHOULD conform to the following 4057 syntax rather than that in Section 9.3. 4059 header = header-name ":" SP [header-content] CRLF 4060 header-content = [WS] 1*P-CHAR *( [CRLF] WS 1*P-CHAR ) 4062 B.2 Message-IDs 4064 Every article handled by an NNTP server MUST have a unique 4065 message-id. For the purposes of this specification, a message-id is 4066 an arbitrary opaque string that is merely needs to meet certain 4067 syntactic requirements and is just a way to refer to the article. 4069 Because there is a significant risk of old articles being reinjected 4070 into the global Usenet system, RFC 1036 [RFC1036] requires that 4071 message-ids are globally unique for all time. 4073 This specification states that message-ids are the same if and only 4074 if they consist of the same sequence of octets. Other specifications 4075 may define two different sequences as being equal because they are 4076 putting an interpretation on particular characters. RFC 2822 4077 [RFC2822] has a concept of "quoted" and "escaped" characters. It 4078 therefore considers the three messages-ids: 4080 4081 <"abcd"@example.com> 4082 <"ab\cd"@example.com> 4084 as being identical. Therefore an NNTP implementation handing email 4085 articles must ensure that only one of these three appears in the 4086 protocol and the other two are converted to it as and when necessary, 4087 such as when a client checks the results of a NEWNEWS command against 4088 an internal database of message-ids. 4090 This specification does not describe how the message-id of an article 4091 is determined; it may be deduced from the contents of the article or 4092 derived from some external source. If the server is also conforming 4093 to another specification that contains a definition of message-id 4094 compatible with this one, the server SHOULD use those message-ids. A 4095 common approach, and one that SHOULD be used for email and Usenet 4096 articles, is to extract the message-id from the contents of a header 4097 with name "Message-ID". This may not be as simple as copying the 4098 entire header contents; it may be necessary to strip off comments and 4099 undo quoting, or to reduce "equivalent" message-ids to a canonical 4100 form. 4102 If an article is obtained though the IHAVE command, there will be a 4103 message-id provided with the command. The server MAY either use it or 4104 determine one from the article contents. However, whichever it does 4105 it SHOULD ensure that, if the IHAVE command is repeated with the same 4106 argument and article, it will be recognised as a duplicate. 4108 If an article does not contain a message-id that the server can 4109 identify, it MUST synthesise one. This could, for example, be a 4110 simple sequence number or based on the date and time that the article 4111 arrived. When handling email or Usenet articles, a Message-ID header 4112 SHOULD be added to ensure global consistency and uniqueness. 4114 B.3 Article posting 4116 As far as NNTP is concerned, the POST and IHAVE commands provide the 4117 same basic facilities in a slightly different way. However they have 4118 rather different intentions. 4120 The IHAVE command is intended for transmitting conforming articles 4121 between a system of NNTP servers, with all articles perhaps also 4122 conforming to another specification (e.g. all articles are Usenet 4123 articles). It is expected that the client will have already done any 4124 necessary validation (or has in turn obtained the article from a 4125 third party which has done so); therefore the contents SHOULD be left 4126 unchanged. 4128 In contrast, the POST command is intended for use when an end-user is 4129 injecting a newly-created article into a such a system. The article 4130 being transferred might not be a conforming email or Usenet article, 4131 and the server is expected to validate it and, if necessary, convert 4132 it to the right form for onward distribution. It is often the case 4133 that this is done by a separate piece of software on the server 4134 installation. If so, the NNTP server SHOULD pass the incoming article 4135 to that software unaltered, making no attempt to filter characters, 4136 fold or limit lines, or otherwise process the incoming text. 4138 The POST command can fail in various ways and clients should be 4139 prepared to re-send an article. When doing so, however, it is often 4140 important to ensure - as far as possible - that the same message-id 4141 is allocated to both attempts so that the server, or other servers, 4142 can recognise the two articles as being duplicates. In the case of 4143 email or Usenet articles, therefore, the posted article SHOULD 4144 contain a header with name "Message-ID" and the contents of this 4145 header SHOULD be identical on each attempt. The server SHOULD ensure 4146 that two POSTed articles with the same contents for this header are 4147 recognised as identical and the same message-id allocated, whether or 4148 not those contents are suitable for use as the message-id. 4150 Appendix C. Summary of Response Codes 4152 This section contains a list of every response code defined in this 4153 document, whether it is multi-line, which commands can generate it, 4154 what arguments it has, and what its meaning is. 4156 Response code 100 (multi-line) 4157 Generated by: HELP 4158 Meaning: help text follows. 4160 Response code 111 4161 Generated by: DATE 4162 1 argument: yyyymmddhhmmss 4163 Meaning: server date and time. 4165 Response code 200 4166 Generated by: initial connection, MODE READER 4167 Meaning: service available, posting allowed. 4169 Response code 201 4170 Generated by: initial connection, MODE READER 4171 Meaning: service available, posting prohibited. 4173 Response code 202 (multi-line) 4174 Generated by: LIST EXTENSIONS 4175 Meaning: extension list follows. 4177 Response code 205 4178 Generated by: QUIT 4179 Meaning: connection closing (the server immediately closes the 4180 connection). 4182 Response code 211 4183 The 211 response code has two completely different forms depending 4184 on which command generated it: 4186 Generated by: GROUP 4187 4 arguments: number low high group 4188 Meaning: group selected. 4190 (multi-line) 4191 Generated by: LISTGROUP 4192 Meaning: article numbers follow. 4194 Response code 215 (multi-line) 4195 Generated by: LIST ACTIVE, LIST ACTIVE.TIMES, LIST DISTRIB.PATS, 4196 LIST DISTRIBUTIONS, LIST HEADERS, LIST NEWSGROUPS, 4197 LIST OVERVIEW.FMT 4198 Meaning: information follows. 4200 Response code 220 (multi-line) 4201 Generated by: ARTICLE 4202 2 arguments: n message-id 4203 Meaning: article follows. 4205 Response code 221 (multi-line) 4206 Generated by: HEAD 4207 2 arguments: n message-id 4208 Meaning: article headers follow. 4210 Response code 222 (multi-line) 4211 Generated by: BODY 4212 2 arguments: n message-id 4213 Meaning: article body follows. 4215 Response code 223 4216 Generated by: LAST, NEXT, STAT 4217 2 arguments: n message-id 4218 Meaning: article exists and selected. 4220 Response code 224 (multi-line) 4221 Generated by: OVER 4222 Meaning: overview information follows. 4224 Response code 225 (multi-line) 4225 Generated by: HDR 4226 Meaning: headers follow. 4228 Response code 230 (multi-line) 4229 Generated by: NEWNEWS 4230 Meaning: list of new articles follows. 4232 Response code 231 (multi-line) 4233 Generated by: NEWGROUPS 4234 Meaning: list of new newsgroups follows. 4236 Response code 235 4237 Generated by: IHAVE (second stage) 4238 Meaning: article transferred OK. 4240 Response code 240 4241 Generated by: POST (second stage) 4242 Meaning: article received OK. 4244 Response code 335 4245 Generated by: IHAVE (first stage) 4246 Meaning: send article to be transferred. 4248 Response code 340 4249 Generated by: POST (first stage) 4250 Meaning: send article to be posted. 4252 Response code 400 4253 Generic response and generated by initial connection 4254 Meaning: service not available or no longer available (the server 4255 immediately closes the connection). 4257 Response code 401 4258 Generic response 4259 1 argument: extension-label 4260 Meaning: the server is in the wrong mode; the indicated extension 4261 should be used to change the mode. 4263 Response code 402 4264 Generated by: LIST EXTENSIONS 4265 Meaning: server has no extensions. 4267 Response code 403 4268 Generic response 4269 Meaning: internal fault or problem preventing action being taken. 4271 Response code 411 4272 Generated by: GROUP, LISTGROUP 4273 Meaning: no such newsgroup. 4275 Response code 412 4276 Generated by: ARTICLE, BODY, HDR, HEAD, LAST, LISTGROUP, NEXT, 4277 OVER, STAT 4278 Meaning: no newsgroup selected. 4280 Response code 420 4281 Generated by: ARTICLE, BODY, HDR, HEAD, LAST, NEXT, OVER, STAT 4282 Meaning: current article number is invalid. 4284 Response code 421 4285 Generated by: NEXT 4286 Meaning: no next article in this group. 4288 Response code 422 4289 Generated by: LAST 4290 Meaning: no previous article in this group. 4292 Response code 423 4293 Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT 4294 Meaning: no articles in that range. 4296 Response code 430 4297 Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT 4298 Meaning: no article with that message-id. 4300 Response code 435 4301 Generated by: IHAVE (first stage) 4302 Meaning: article not wanted. 4304 Response code 436 4305 Generated by: IHAVE (either stage) 4306 Meaning: transfer not possible (first stage) or failed (second 4307 stage); try again later. 4309 Response code 437 4310 Generated by: IHAVE (second stage) 4311 Meaning: transfer rejected; do not retry. 4313 Response code 440 4314 Generated by: POST (first stage) 4315 Meaning: posting not permitted. 4317 Response code 441 4318 Generated by: POST (second stage) 4319 Meaning: posting failed. 4321 Response code 480 4322 Generic response 4323 Meaning: command unavailable until the client has authenticated 4324 itself. 4326 Response code 483 4327 Generic response 4328 Meaning: command unavailable until suitable privacy has been 4329 arranged. 4331 Response code 500 4332 Generic response 4333 Meaning: unknown command. 4335 Response code 501 4336 Generic response 4337 Meaning: syntax error in command. 4339 Response code 502 4340 Generic response and generated by initial connection 4341 Meaning for the initial connection and the MODE READER command: 4342 service permanently unavailable (the server immediately closes the 4343 connection). 4344 Meaning for all other commands: command not permitted (and there 4345 is no way for the client to change this). 4347 Response code 503 4348 Generic response 4349 Meaning: feature not supported. 4351 Appendix D. Formal specification of the standard extensions 4353 This section gives a formal definition of each of the extensions in 4354 Section 8.2 as required by Section 8 for the IANA registry. 4356 D.1 The LISTGROUP extension 4358 o This extension provides information about specific article 4359 numbers. 4361 o The extension-label is "LISTGROUP". 4363 o The extension-label has no arguments. 4365 o The extension defines one new command: LISTGROUP, whose behaviour, 4366 arguments, and responses are defined in Section 8.3. 4368 o The extension does not associate any new responses with 4369 pre-existing NNTP commands. 4371 o The extension does not affect the behaviour of a server or client 4372 other than via the new command. 4374 o The extension does not affect the maximum length of commands and 4375 initial response lines. 4377 o The extension does not alter pipelining, and the LISTGROUP command 4378 can be pipelined. 4380 o Use of this extension does not alter the output from LIST 4381 EXTENSIONS. 4383 o The extension does not cause any pre-existing command to produce a 4384 401, 480, or 483 response. 4386 o The LISTGROUP command can only be used after the MODE READER 4387 command. 4389 D.2 The OVER extension 4391 o This extension provides support for an overview of newsgroups. 4393 o The extension-label is "OVER". 4395 o The extension-label has no arguments. 4397 o The extension defines two new commands: OVER and LIST 4398 OVERVIEW.FMT, whose behaviour, arguments, and responses are 4399 defined in Section 8.5. 4401 o The extension does not associate any new responses with 4402 pre-existing NNTP commands. 4404 o The extension requires the server to maintain an overview database 4405 and article metadata, as described in Section 8.4. 4407 o The extension does not affect the maximum length of commands and 4408 initial response lines. 4410 o The extension does not alter pipelining, and the OVER and LIST 4411 OVERVIEW.FMT commands can be pipelined. 4413 o Use of this extension does not alter the output from LIST 4414 EXTENSIONS. 4416 o The extension does not cause any pre-existing command to produce a 4417 401, 480, or 483 response. 4419 o The OVER and LIST OVERVIEW.FMT commands can only be used after the 4420 MODE READER command. 4422 D.3 The HDR extension 4424 o This extension provides batched header retrieval. 4426 o The extension-label is "HDR". 4428 o The extension-label has the optional argument "ALL", indicating it 4429 may be used with any header or metadata item. 4431 o The extension defines two new commands: HDR and LIST HEADERS, 4432 whose behaviour, arguments, and responses are defined in Section 4433 8.6. 4435 o The extension does not associate any new responses with 4436 pre-existing NNTP commands. 4438 o The extension requires the server to maintain article metadata, as 4439 described in Section 8.4. 4441 o The extension does not affect the maximum length of commands and 4442 initial response lines. 4444 o The extension does not alter pipelining, and the HDR and LIST 4445 HEADERS commands can be pipelined. 4447 o Use of this extension does not alter the output from LIST 4448 EXTENSIONS. 4450 o The extension does not cause any pre-existing command to produce a 4451 401, 480, or 483 response. 4453 o The HDR and LIST HEADERS commands can only be used after the MODE 4454 READER command. 4456 Intellectual Property Statement 4458 The IETF takes no position regarding the validity or scope of any 4459 intellectual property or other rights that might be claimed to 4460 pertain to the implementation or use of the technology described in 4461 this document or the extent to which any license under such rights 4462 might or might not be available; neither does it represent that it 4463 has made any effort to identify any such rights. Information on the 4464 IETF's procedures with respect to rights in standards-track and 4465 standards-related documentation can be found in BCP-11. Copies of 4466 claims of rights made available for publication and any assurances of 4467 licenses to be made available, or the result of an attempt made to 4468 obtain a general license or permission for the use of such 4469 proprietary rights by implementors or users of this specification can 4470 be obtained from the IETF Secretariat. 4472 The IETF invites any interested party to bring to its attention any 4473 copyrights, patents or patent applications, or other proprietary 4474 rights which may cover technology that may be required to practice 4475 this standard. Please address the information to the IETF Executive 4476 Director. 4478 Full Copyright Statement 4480 Copyright (C) The Internet Society (2003). All Rights Reserved. 4482 This document and translations of it may be copied and furnished to 4483 others, and derivative works that comment on or otherwise explain it 4484 or assist in its implementation may be prepared, copied, published 4485 and distributed, in whole or in part, without restriction of any 4486 kind, provided that the above copyright notice and this paragraph are 4487 included on all such copies and derivative works. However, this 4488 document itself may not be modified in any way, such as by removing 4489 the copyright notice or references to the Internet Society or other 4490 Internet organizations, except as needed for the purpose of 4491 developing Internet standards in which case the procedures for 4492 copyrights defined in the Internet Standards process must be 4493 followed, or as required to translate it into languages other than 4494 English. 4496 The limited permissions granted above are perpetual and will not be 4497 revoked by the Internet Society or its successors or assignees. 4499 This document and the information contained herein is provided on an 4500 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4501 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4502 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4503 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4504 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4506 Acknowledgment 4508 Funding for the RFC Editor function is currently provided by the 4509 Internet Society.