idnits 2.17.1 draft-ietf-nntpext-base-26.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 5617. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 5594. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 5601. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 5607. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to 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 51 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 222 has weird spacing: '...cal|bar indic...' == Line 1217 has weird spacing: '...abc,def the t...' == Line 1334 has weird spacing: '...keyword addi...' == Line 1631 has weird spacing: '... group nam...' == Line 1632 has weird spacing: '... number esti...' == (9 more instances...) -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: A private extension MAY or MAY NOT be included in the capabilities list. If it is, the capability label MUST begin with "X". A server MAY provide additional keywords - for new commands and also for new variants of existing commands - as part of a private extension. To avoid the risk of a clash with a future registered extension, these keywords SHOULD begin with "X". == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: A mode-switching server has two modes: o Transit mode, which applies after the initial connection: * it MUST advertise the MODE-READER capability; * it MUST NOT advertise the READER capability. However, the server MAY cease to advertise the MODE-READER capability after the client uses any command except CAPABILITIES. o Reading mode, after a successful MODE READER (Section 5.3) command: * it MUST NOT advertise the MODE-READER capability; * it MUST advertise the READER capability; * it MAY NOT advertise the IHAVE capability even if it was advertising it in transit mode. == 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: [1] These are the only valid response codes for the initial greeting; the server MUST not return any other generic response code. [2] Following a 400 or 502 response the server MUST immediately close the connection. -- 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 (May 20, 2005) is 6916 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 4878, but not defined == Missing Reference: 'S' is mentioned on line 4879, but not defined -- Looks like a reference, but probably isn't: '1' on line 3057 -- Looks like a reference, but probably isn't: '2' on line 1252 == Missing Reference: 'GMT' is mentioned on line 2929, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'ANSI1986' ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 3548 (Obsoleted by RFC 4648) ** Obsolete normative reference: RFC 977 (Obsoleted by RFC 3977) == Outdated reference: A later version (-10) exists of draft-ietf-nntpext-authinfo-06 == Outdated reference: A later version (-06) exists of draft-ietf-nntpext-streaming-03 == Outdated reference: A later version (-09) exists of draft-ietf-nntpext-tls-nntp-04 -- 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: 7 errors (**), 0 flaws (~~), 18 warnings (==), 17 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: November 21, 2005 May 20, 2005 6 Network News Transfer Protocol 7 draft-ietf-nntpext-base-26 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patent or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on November 21, 2005. 34 Copyright Notice 36 Copyright (C) The Internet Society (2005). 38 Abstract 40 The Network News Transfer Protocol (NNTP) has been in use in the 41 Internet for a decade and remains one of the most popular protocols 42 (by volume) in use today. This document is a replacement for RFC 977 43 and officially updates the protocol specification. It clarifies some 44 vagueness in RFC 977, includes some new base functionality, and 45 provides a specific mechanism to add standardized extensions to NNTP. 47 Administration 48 This document is a product of the NNTP Working Group, chaired by Russ 49 Allbery and Ned Freed. 51 Author's Note 53 This document 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 document. 60 Rights 62 UNIX is a registered trademark of The Open Group. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 67 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 3. Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . 9 69 3.1. Commands and Responses . . . . . . . . . . . . . . . . . 9 70 3.1.1. Multi-line data blocks . . . . . . . . . . . . . . . 10 71 3.2. Response Codes . . . . . . . . . . . . . . . . . . . . . 11 72 3.2.1. Generic Response Codes . . . . . . . . . . . . . . . 13 73 3.2.1.1. Examples . . . . . . . . . . . . . . . . . . . . 14 74 3.3. Capabilities and Extensions . . . . . . . . . . . . . . . 16 75 3.3.1. Capability descriptions . . . . . . . . . . . . . . . 17 76 3.3.2. Standard capabilities . . . . . . . . . . . . . . . . 17 77 3.3.3. Extensions . . . . . . . . . . . . . . . . . . . . . 19 78 3.3.4. Initial IANA register . . . . . . . . . . . . . . . . 20 79 3.4. Mandatory and Optional Commands . . . . . . . . . . . . . 22 80 3.4.1. Reading and Transit Servers . . . . . . . . . . . . . 22 81 3.4.2. Mode switching . . . . . . . . . . . . . . . . . . . 23 82 3.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 24 83 3.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 25 84 3.6. Articles . . . . . . . . . . . . . . . . . . . . . . . . 25 85 4. The WILDMAT format . . . . . . . . . . . . . . . . . . . . . 28 86 4.1. Wildmat syntax . . . . . . . . . . . . . . . . . . . . . 28 87 4.2. Wildmat semantics . . . . . . . . . . . . . . . . . . . . 28 88 4.3. Extensions . . . . . . . . . . . . . . . . . . . . . . . 29 89 4.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 30 90 5. Session administration commands . . . . . . . . . . . . . . . 31 91 5.1. Initial Connection . . . . . . . . . . . . . . . . . . . 31 92 5.2. CAPABILITIES . . . . . . . . . . . . . . . . . . . . . . 32 93 5.3. MODE READER . . . . . . . . . . . . . . . . . . . . . . . 35 94 5.4. QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . 37 95 6. Article posting and retrieval . . . . . . . . . . . . . . . . 38 96 6.1. Group and article selection . . . . . . . . . . . . . . . 38 97 6.1.1. GROUP . . . . . . . . . . . . . . . . . . . . . . . . 39 98 6.1.2. LISTGROUP . . . . . . . . . . . . . . . . . . . . . . 42 99 6.1.3. LAST . . . . . . . . . . . . . . . . . . . . . . . . 44 100 6.1.4. NEXT . . . . . . . . . . . . . . . . . . . . . . . . 46 101 6.2. Retrieval of articles and article sections . . . . . . . 47 102 6.2.1. ARTICLE . . . . . . . . . . . . . . . . . . . . . . . 48 103 6.2.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 51 104 6.2.3. BODY . . . . . . . . . . . . . . . . . . . . . . . . 53 105 6.2.4. STAT . . . . . . . . . . . . . . . . . . . . . . . . 55 106 6.3. Article posting . . . . . . . . . . . . . . . . . . . . . 58 107 6.3.1. POST . . . . . . . . . . . . . . . . . . . . . . . . 58 108 6.3.2. IHAVE . . . . . . . . . . . . . . . . . . . . . . . . 60 109 7. Information commands . . . . . . . . . . . . . . . . . . . . 64 110 7.1. DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 64 111 7.2. HELP . . . . . . . . . . . . . . . . . . . . . . . . . . 65 112 7.3. NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 65 113 7.4. NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 67 114 7.5. Time . . . . . . . . . . . . . . . . . . . . . . . . . . 68 115 7.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 68 116 7.6. The LIST commands . . . . . . . . . . . . . . . . . . . . 69 117 7.6.1. LIST . . . . . . . . . . . . . . . . . . . . . . . . 69 118 7.6.2. Standard LIST keywords . . . . . . . . . . . . . . . 72 119 7.6.3. LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . 73 120 7.6.4. LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . 74 121 7.6.5. LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . 75 122 7.6.6. LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . 75 123 8. Article field access commands . . . . . . . . . . . . . . . . 77 124 8.1. Article metadata . . . . . . . . . . . . . . . . . . . . 77 125 8.1.1. The :bytes metadata item . . . . . . . . . . . . . . 77 126 8.1.2. The :lines metadata item . . . . . . . . . . . . . . 78 127 8.2. Database consistency . . . . . . . . . . . . . . . . . . 78 128 8.3. OVER . . . . . . . . . . . . . . . . . . . . . . . . . . 79 129 8.4. LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 83 130 8.5. HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 131 8.6. LIST HEADERS . . . . . . . . . . . . . . . . . . . . . . 90 132 9. Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . . . 93 133 9.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 93 134 9.2. Commands . . . . . . . . . . . . . . . . . . . . . . . . 93 135 9.3. Command continuation . . . . . . . . . . . . . . . . . . 95 136 9.4. Responses . . . . . . . . . . . . . . . . . . . . . . . . 95 137 9.4.1. Generic responses . . . . . . . . . . . . . . . . . . 95 138 9.4.2. Initial response line contents . . . . . . . . . . . 96 139 9.4.3. Multi-line response contents . . . . . . . . . . . . 97 140 9.5. Capability lines . . . . . . . . . . . . . . . . . . . . 98 141 9.6. LIST variants . . . . . . . . . . . . . . . . . . . . . . 99 142 9.7. Articles . . . . . . . . . . . . . . . . . . . . . . . . 100 143 9.8. General non-terminals . . . . . . . . . . . . . . . . . . 100 144 9.9. Extensions and Validation . . . . . . . . . . . . . . . . 102 145 10. Internationalisation Considerations . . . . . . . . . . . . . 104 146 10.1. Introduction and historical situation . . . . . . . . . . 104 147 10.2. This specification . . . . . . . . . . . . . . . . . . . 104 148 10.3. Outstanding issues . . . . . . . . . . . . . . . . . . . 106 149 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 107 150 12. Security Considerations . . . . . . . . . . . . . . . . . . . 108 151 12.1. Personal and Proprietary Information . . . . . . . . . . 108 152 12.2. Abuse of Server Log Information . . . . . . . . . . . . . 108 153 12.3. Weak Authentication and Access Control . . . . . . . . . 108 154 12.4. DNS Spoofing . . . . . . . . . . . . . . . . . . . . . . 109 155 12.5. UTF-8 issues . . . . . . . . . . . . . . . . . . . . . . 109 156 12.6. Caching of capability lists . . . . . . . . . . . . . . . 110 157 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 112 158 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 115 159 14.1. Normative References . . . . . . . . . . . . . . . . . . 115 160 14.2. Informative References . . . . . . . . . . . . . . . . . 115 161 A. Interaction with other specifications . . . . . . . . . . . . 117 162 A.1. Header folding . . . . . . . . . . . . . . . . . . . . . 117 163 A.2. Message-IDs . . . . . . . . . . . . . . . . . . . . . . . 117 164 A.3. Article posting . . . . . . . . . . . . . . . . . . . . . 118 165 B. Summary of Commands . . . . . . . . . . . . . . . . . . . . . 120 166 C. Summary of Response Codes . . . . . . . . . . . . . . . . . . 122 167 D. Changes from RFC 977 . . . . . . . . . . . . . . . . . . . . 127 168 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 129 169 Intellectual Property and Copyright Statements . . . . . . . . . 130 171 1. Introduction 173 This document specifies the Network News Transfer Protocol (NNTP), 174 which is used for the distribution, inquiry, retrieval, and posting 175 of Netnews articles using a reliable stream-based mechanism. For 176 news reading clients, NNTP enables retrieval of news articles that 177 are stored in a central database, giving subscribers the ability to 178 select only those articles they wish to read. 180 The Netnews model provides for indexing, cross-referencing, and 181 expiration of aged messages. NNTP is designed for efficient 182 transmission of Netnews articles over a reliable full duplex 183 communication channel. 185 While the protocol specification in this document is largely 186 compatible with the version specified in RFC 977 [RFC977], there are 187 a number of changes which are summarised in Appendix D. In 188 particular: 189 o the default character set is changed from US-ASCII [ANSI1986] to 190 UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8); 191 o a number of commands that were optional in RFC 977 or have been 192 taken from RFC 2980 [RFC2980] are now mandatory; 193 o a CAPABILITIES command has been added to allow clients to 194 determine what functionality is available from a server. 196 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 197 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 198 document are to be interpreted as described in RFC 2119 [RFC2119]. 200 An implementation is not compliant if it fails to satisfy one or more 201 of the MUST requirements for this protocol. An implementation that 202 satisfies all the MUST and all the SHOULD requirements for its 203 protocols is said to be "unconditionally compliant"; one that 204 satisfies all the MUST requirements but not all the SHOULD 205 requirements for NNTP is said to be "conditionally compliant". 207 For the remainder of this document, the term "client" or "client 208 host" refers to a host making use of the NNTP service, while the term 209 "server" or "server host" refers to a host that offers the NNTP 210 service. 212 2. Notation 214 The following notational conventions are used in this document. 216 UPPERCASE indicates literal text to be included in the 217 command; 218 lowercase indicates a token described elsewhere; 219 [brackets] indicate that the argument is optional; 220 ellipsis... indicates that the argument may be repeated any 221 number of times (it must occur at least once); 222 vertical|bar indicates a choice of two mutually exclusive 223 arguments (exactly one must be provided). 225 The name "message-id" for a command or response argument indicates 226 that it is the message-id of an article as described in Section 3.6, 227 including the angle brackets. 229 The name "wildmat" for an argument indicates that it is a wildmat as 230 defined in Section 4. If the argument does not meet the requirements 231 of that section (for example, if it does not fit the grammar of 232 Section 4.1) the NNTP server MAY place some interpretation on it (not 233 specified by this document) or otherwise MUST treat it as a syntax 234 error. 236 Responses for each command will be described in tables listing the 237 required format of a response followed by the meaning that should be 238 ascribed to that response. 240 The terms "NUL", "TAB", "LF", "CR, and "space" refer to the octets 241 %x00, %x09, %x0A, %x0D, and %x20 respectively (that is, the octets 242 with those codes in US-ASCII [ANSI1986] and thus UTF-8 [RFC3629]). 243 The term "CRLF" or "CRLF pair" means the sequence CR immediately 244 followed by LF (that is, %x0D.0A). A "printable US-ASCII character" 245 is an octet in the range %x21-7E. Quoted characters refer to the 246 octets with those codes in US-ASCII (so "." and "<" refer to %x2E and 247 %x3C) and will always be printable US-ASCII characters; similarly, 248 "digit" refers to the octets %x30-39. 250 A "keyword" MUST consist only of US-ASCII letters, digits, and the 251 characters dot (".") and dash ("-"), and MUST begin with a letter. 252 Keywords MUST be at least three characters and MUST NOT exceed 12 253 characters. 255 Examples in this document are not normative but serve to illustrate 256 usages, arguments, and responses. In the examples, a "[C]" will be 257 used to represent the client host and a "[S]" will be used to 258 represent the server host. Most of the examples do not rely on a 259 particular server state. In some cases, however, they do assume that 260 the currently selected newsgroup (see the GROUP command 261 (Section 6.1.1)) is invalid; when so, this is indicated at the start 262 of the example. Examples may use commands or other keywords not 263 defined in this specification (such as an XENCRYPT command). These 264 will be used to illustrate some point and do not imply that any such 265 command is defined elsewhere or needs to exist in any particular 266 implementation. 268 Terms which might be read as specifying details of a client or server 269 implementation, such as "database", are used simply to ease 270 description. Providing that implementations conform to the protocol 271 and format specifications in this document, no specific technique is 272 mandated. 274 3. Basic Concepts 276 3.1. Commands and Responses 278 NNTP operates over any reliable bidirectional 8-bit-wide data stream 279 channel. When the connection is established, the NNTP server host 280 MUST send a greeting. The client host and server host then exchange 281 commands and responses (respectively) until the connection is closed 282 or aborted. If the connection used is TCP, then the server host 283 starts the NNTP service by listening on a TCP port. When a client 284 host wishes to make use of the service, it MUST establish a TCP 285 connection with the server host by connecting to that host on the 286 same port on which the server is listening. 288 The character set for all NNTP commands is UTF-8 [RFC3629]. Commands 289 in NNTP MUST consist of a keyword, which MAY be followed by one or 290 more arguments. A CRLF pair MUST terminate all commands. Multiple 291 commands MUST NOT be on the same line. Unless otherwise noted 292 elsewhere in this document, arguments SHOULD consist of printable US- 293 ASCII characters. Keywords and arguments MUST be each separated by 294 one or more space or TAB characters. Command lines MUST NOT exceed 295 512 octets, which includes the terminating CRLF pair. The arguments 296 MUST NOT exceed 497 octets. A server MAY relax these limits for 297 commands defined in an extension. 299 Where this specification permits UTF-8 characters outside the range 300 U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark 301 (U+FEFF, encoding %xEF.BB.BF), and MUST use the Word Joiner (U+2060, 302 encoding %xE2.91.A0) for the meaning Zero Width No-Break Space, in 303 command lines and the initial lines of responses, and SHOULD apply 304 these same principles throughout. 306 The term "character" means a single Unicode code point and 307 implementations are not required to carry out normalisation. Thus 308 U+0084 (A-dieresis) is one character while U+0041 U+0308 (A composed 309 with dieresis) is two; the two need not be treated as equivalent. 311 Commands may have variants, using a second keyword immediately after 312 the first to indicate which variant is required. The only such 313 commands in this specification are LIST and MODE. Note that such 314 variants are sometimes referred to as if they were commands in their 315 own right: "the LIST ACTIVE" command should be read as shorthand for 316 "the ACTIVE variant of the LIST command". 318 Keywords are case-insensitive; the case of keywords for commands MUST 319 be ignored by the server. Command and response arguments are case- 320 or language-specific only when stated, either in this document or in 321 other relevant specifications. 323 In some cases a command involves more data than just a single line. 324 The further data may be sent either immediately after the command 325 line (there are no instances of this in this specification, but there 326 are in extensions such as [NNTP-STREAM]) or following a request from 327 the server (indicated by a 3xx response). 329 Each response MUST start with a three-digit response code that is 330 sufficient to distinguish all responses. Certain valid responses are 331 defined to be multi-line; for all others, the response is contained 332 in a single line. The initial line of the response MUST NOT exceed 333 512 octets, which includes the response code and the terminating CRLF 334 pair; an extension MAY specify a greater maximum for commands that it 335 defines, but not for any other command. Single-line responses 336 consist of an initial line only. Multi-line responses consist of an 337 initial line followed by a multi-line data block. 339 An NNTP server MAY have an inactivity autologout timer. Such a timer 340 SHOULD be of at least three minutes duration, with the exception that 341 there MAY be a shorter limit on how long the server is willing to 342 wait for the first command from the client. The receipt of any 343 command from the client during the timer interval SHOULD suffice to 344 reset the autologout timer. Similarly, the receipt of any 345 significant amount of data from a client that is sending a multi-line 346 data block (such as during a POST or IHAVE command) SHOULD suffice to 347 reset the autologout timer. When the timer expires, the server 348 SHOULD close the connection without sending any response to the 349 client. 351 3.1.1. Multi-line data blocks 353 A multi-line data block is used in certain commands and responses. 354 It MUST adhere to the following rules: 356 1. The block consists of a sequence of zero or more "lines", each 357 being a stream of octets ending with a CRLF pair. Apart from 358 those line endings, the stream MUST NOT include the octets NUL, 359 LF, or CR. 361 2. In a multi-line response, the block immediately follows the CRLF 362 at the end of the initial line of the response. When used in any 363 other context, the specific command will define when the block is 364 sent. 366 3. If any line of the data block begins with the "termination octet" 367 ("." or %x2E), that line MUST be "dot-stuffed" by pre-pending an 368 additional termination octet to that line of the block. 370 4. The lines of the block MUST be followed by a terminating line 371 consisting of a single termination octet followed by a CRLF pair 372 in the normal way. Thus, unless it is empty, a multi-line block 373 is always terminated with the five octets CRLF "." CRLF 374 (%x0D.0A.2E.0D.0A). 376 5. When interpreting a multi-line block, the "dot-stuffing" MUST be 377 undone; i.e. the recipient MUST ensure that, in any line 378 beginning with the termination octet followed by octets other 379 than a CRLF pair, that initial termination octet is disregarded. 381 6. Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT 382 be considered part of the multi-line block; i.e. the recipient 383 MUST ensure that any line beginning with the termination octet 384 followed immediately by a CRLF pair is disregarded; (the first 385 CRLF pair of the terminating CRLF "." CRLF of a non-empty block 386 is, of course, part of the last line of the block). 388 Note that texts using an encoding (such as UTF-16 or UTF-32) that may 389 contain the octets NUL, LF, or CR other than a CRLF pair cannot be 390 reliably conveyed in the above format (that is, they violate the MUST 391 requirement above). However, except when stated otherwise, this 392 specification does not require the content to be UTF-8 and therefore 393 (subject to that same requirement) it MAY include octets above and 394 below 128 mixed arbitrarily. 396 This document does not place any limit on the length of a line in a 397 multi-line block. However, the standards that define the format of 398 articles may do so. 400 3.2. Response Codes 402 Each response MUST begin with a three-digit status indicator. These 403 are status reports from the server and indicate the response to the 404 last command received from the client. 406 The first digit of the response broadly indicates the success, 407 failure, or progress of the previous command: 409 1xx - Informative message. 410 2xx - Command completed OK. 411 3xx - Command OK so far; send the rest of it. 412 4xx - Command was syntactically correct but failed for some 413 reason. 414 5xx - Command unknown, unsupported, unavailable, or syntax error. 416 The next digit in the code indicates the function response category: 418 x0x - Connection, set-up, and miscellaneous messages 419 x1x - Newsgroup selection 420 x2x - Article selection 421 x3x - Distribution functions 422 x4x - Posting 423 x8x - Reserved for authentication and privacy extensions 424 x9x - Reserved for private use (non-standard extensions) 426 Certain responses contain arguments such as numbers and names in 427 addition to the status indicator. In those cases, to simplify 428 interpretation by the client the number and type of such arguments is 429 fixed for each response code, as is whether or not the code is 430 single-line or multi-line. Any extension MUST follow this principle 431 as well. Note that, for historical reasons, the 211 response code is 432 an exception to this in that the response may be single-line or 433 multi-line depending on the command (GROUP or LISTGROUP) that 434 generated it. In all other cases, the client MUST only use the 435 status indicator itself to determine the nature of the response. The 436 exact response codes that can be returned by any given command are 437 detailed in the description of that command. 439 Arguments MUST be separated from the numeric status indicator and 440 from each other by a single space. All numeric arguments MUST be in 441 base 10 (decimal) format, and MAY have leading zeros. String 442 arguments MUST contain at least one character and MUST NOT contain 443 TAB, LF, CR, or space. The server MAY add any text after the 444 response code or last argument as appropriate, and the client MUST 445 NOT make decisions based on this text. Such text MUST be separated 446 from the numeric status indicator or the last argument by at least 447 one space. 449 The server MUST respond to any command with the appropriate generic 450 response (given in Section 3.2.1) if it represents the situation. 451 Otherwise, each recognized command MUST return one of the response 452 codes specifically listed in its description or in an extension. A 453 server MAY provide extensions to this specification, including new 454 commands, new variants or features of existing commands, and other 455 ways of changing the internal state of the server. However, the 456 server MUST NOT produce any other responses to a client that does not 457 invoke any of the additional features. (Therefore a client that 458 restricts itself to this specification will only receive the 459 responses that are listed.) 461 If a client receives an unexpected response, it SHOULD use the first 462 digit of the response to determine the result. For example, an 463 unexpected 2xx should be taken as success and an unexpected 4xx or 464 5xx as failure. 466 Response codes not specified in this document MAY be used for any 467 installation-specific additional commands also not specified. These 468 SHOULD be chosen to fit the pattern of x9x specified above. 470 Neither this document nor any registered extension (see 471 Section 3.3.3) will specify any response codes of the x9x pattern. 472 (Implementers of extensions are accordingly cautioned not to use such 473 responses for extensions that may subsequently be submitted for 474 registration.) 476 3.2.1. Generic Response Codes 478 The server MUST respond to any command with the appropriate one of 479 the following generic responses if it represents the situation. 481 If the command is not recognized, or it is an optional command that 482 is not implemented by the server, the response code 500 MUST be 483 returned. 485 If there is a syntax error in the arguments of a recognized command, 486 including the case where more arguments are provided than the command 487 specifies or the command line is longer than the server accepts, the 488 response code 501 MUST be returned. The line MUST NOT be truncated 489 or split and then interpreted. Note that where a command has 490 variants depending on a second keyword (e.g. LIST ACTIVE and LIST 491 NEWSGROUPS), then 501 MUST be used when the base command is 492 implemented but the requested variant is not, and 500 MUST be used 493 only when the base command itself is not implemented. 495 As a special case, if an argument is required to be a base64-encoded 496 string [RFC3548] (there are no such arguments in this specification, 497 but there may be in extensions) and is not validly encoded, the 498 response code 504 MUST be returned. 500 If the server experiences an internal fault or problem that means it 501 is unable to carry out the command (for example, a necessary file is 502 missing or a necessary service could not be contacted), the response 503 code 403 MUST be returned. If the server recognizes the command but 504 does not provide an optional feature (for example because it does not 505 store the required information), or only handles a subset of 506 legitimate cases (see the HDR command (Section 8.5) for an example), 507 the response code 503 MUST be returned. 509 If the client is not authorized to use the specified facility when 510 the server is in its current state, then the appropriate one of the 511 following response codes MUST be used. 513 502: it is necessary to terminate the connection and start a new one 514 with the appropriate authority before the command can be used. 515 Historically, some mode-switching servers (see Section 3.4.1) have 516 used this response to indicate that this command will become 517 available after the MODE READER (Section 5.3) command is used, but 518 this usage is not conforming to this specification and MUST NOT be 519 used. Note that the server MUST NOT close the connection 520 immediately after a 502 response except at the initial connection 521 (Section 5.1) and with the MODE READER command. 523 480: the client must authenticate itself to the server (that is, 524 provide information as to the identity of the client) before the 525 facility can be used on this connection. This will involve the 526 use of an authentication extension such as [NNTP-AUTH]. 528 483: the client must negotiate appropriate privacy protection on the 529 connection. This will involve the use of a privacy extension such 530 as [NNTP-TLS]. 532 401: the client must change the state of the connection in some other 533 manner. The first argument of the response MUST be the capability 534 label (see Section 5.2) of the facility (usually an extension, 535 which may be a private extension) that provides the necessary 536 mechanism. The server MUST NOT use this response code except as 537 specified by the definition of the capability in question. 539 If the server has to terminate the connection for some reason, it 540 MUST give a 400 response code to the next command and then 541 immediately close the connection. Following a 400 response, clients 542 SHOULD NOT simply reconnect immediately and retry the same actions. 543 Rather, a client SHOULD either use an exponentially increasing delay 544 between retries (e.g. double the waiting time after each 400 545 response) or present any associated text to the user for them to 546 decide whether and when to retry. 548 The client MUST be prepared to receive any of these responses for any 549 command (except, of course, that the server MUST NOT generate a 500 550 response code for mandatory commands). 552 3.2.1.1. Examples 554 Example of an unknown command: 556 [C] MAIL 557 [S] 500 Unknown command 559 Example of an unsupported command: 561 [C] CAPABILITIES 562 [S] 101 Capability list: 563 [S] VERSION 2 564 [S] READER 565 [S] NEWNEWS 566 [S] LIST ACTIVE NEWSGROUPS 567 [S] . 568 [C] OVER 569 [S] 500 Unknown command 571 Example of an unsupported variant: 573 [C] MODE POSTER 574 [S] 501 Unknown MODE option 576 Example of a syntax error: 578 [C] ARTICLE a.message.id@no.angle.brackets 579 [S] 501 Syntax error 581 Example of an overlong command line: 583 [C] HEAD 53 54 55 584 [S] 501 Too many arguments 586 Example of a bad wildmat: 588 [C] LIST ACTIVE u[ks].* 589 [S] 501 Syntax error 591 Example of a base64-encoding error (the second argument is meant to 592 be base64-encoded): 594 [C] XENCRYPT RSA abcd=efg 595 [S] 504 Base64 encoding error 597 Example of an attempt to access a facility not available to this 598 connection: 600 [C] MODE READER 601 [S] 200 Reader mode, posting permitted 602 [C] IHAVE 603 [S] 500 Permission denied 605 Example of an attempt to access a facility requiring authentication: 607 [C] GROUP secret.group 608 [S] 480 Permission denied 610 followed by a successful attempt following such authentication: 612 [C] XSECRET fred flintstone 613 [S] 290 Password for fred accepted 614 [C] GROUP secret.group 615 [S] 211 5 1 20 secret.group selected 617 Example of an attempt to access a facility requiring privacy: 619 [C] GROUP secret.group 620 [S] 483 Secure connection required 621 [C] XENCRYPT 622 [Client and server negotiate encryption on the link] 623 [S] 283 Encrypted link established 624 [C] GROUP secret.group 625 [S] 211 5 1 20 secret.group selected 627 Example of a need to change mode before using a facility: 629 [C] GROUP binary.group 630 [S] 401 XHOST Not on this virtual host 631 [C] XHOST binary.news.example.org 632 [S] 290 binary.news.example.org virtual host selected 633 [C] GROUP binary.group 634 [S] 211 5 1 77 binary.group selected 636 Example of a temporary failure: 638 [C] GROUP archive.local 639 [S] 403 Archive server temporarily offline 641 Example of the server needing to close down immediately: 643 [C] ARTICLE 123 644 [S] 400 Power supply failed, running on UPS 645 [Server closes connection.] 647 3.3. Capabilities and Extensions 649 Not all NNTP servers provide exactly the same facilities, both 650 because this specification allows variation and because servers may 651 provide extensions. A set of facilities that are related are called 652 a "capability". This specification provides a way to determine what 653 capabilities are available, includes a list of standard capabilities, 654 and includes a mechanism (the extension mechanism) for defining new 655 capabilities. 657 3.3.1. Capability descriptions 659 A client can determine the available capabilities of the server by 660 using the CAPABILITIES command (Section 5.2). This returns a 661 capability list, which is a list of capability lines. Each line 662 describes one available capability. 664 Each capability line consists of one or more tokens, which MUST be 665 separated by one or more space or TAB characters. A token is a 666 string of 1 or more printable UTF-8 characters (that is, either 667 printable US-ASCII characters or any UTF-8 sequence outside the US- 668 ASCII range, but not space or TAB). Unless stated otherwise, tokens 669 are case-insensitive. Each capability line consists of: 670 o The capability label, which is a keyword indicating the 671 capability. A capability label may be defined by this 672 specification or a successor, or may be defined by an extension. 673 o The label is then followed by zero or more tokens, which are 674 arguments of the capability. The form and meaning of these tokens 675 is specific to each capability. 677 The server MUST ensure that the capability list accurately reflects 678 the capabilities (including extensions) currently available. If a 679 capability is only available with the server in a certain state (for 680 example, only after authentication), the list MUST only include the 681 capability label when in that state. Similarly, if only some of the 682 commands in an extension will be available, or if the behaviour of 683 the extension will change in some other manner, according to the 684 state of the server, this MUST be indicated by different arguments in 685 the capability line. 687 Note that a capability line can only begin with a letter. Lines 688 beginning with other characters are reserved for future versions of 689 this specification. In order to interoperate with such versions, 690 clients MUST be prepared to receive lines beginning with other 691 characters and MUST ignore any they do not understand. 693 3.3.2. Standard capabilities 695 The following capabilities are defined by this specification. 697 VERSION 698 This capability MUST be advertised by all servers and MUST be the 699 first capability in the capability list; it indicates the 700 version(s) of NNTP that the server supports. There must be at 701 least one argument; each argument is a decimal number and MUST NOT 702 have a leading zero. Version numbers are assigned only in RFCs 703 which update or replace this specification; servers MUST NOT 704 create their own version numbers. 706 The version number of this specification is 2. 708 READER 709 This capability indicates that the server implements the various 710 commands useful for reading clients. 712 IHAVE 713 This capability indicates that the server implements the IHAVE 714 command. 716 POST 717 This capability indicates that the server implements the POST 718 command. 720 NEWNEWS 721 This capability indicates that the server implements the NEWNEWS 722 command. 724 HDR 725 This capability indicates that the server implements the header 726 access commands (HDR and LIST HEADERS). 728 OVER 729 This capability indicates that the server implements the overview 730 access commands (OVER and LIST OVERVIEW.FMT). If and only if the 731 server supports the message-id form of the OVER command, there 732 must be a single argument MSGID. 734 LIST 735 This capability indicates that the server implements at least one 736 variant of the LIST command. There MUST be one argument for each 737 variant of the LIST command supported by the server, giving the 738 keyword for that variant. 740 IMPLEMENTATION 741 This capability MAY be provided by a server. If so, the arguments 742 SHOULD be used to provide information such as the server software 743 name and version number. The client MUST NOT use this line to 744 determine capabilities of the server. (While servers often 745 provide this information in the initial greeting, clients need to 746 guess whether this is the case; this capability makes it clear 747 what the information is.) 749 MODE-READER 750 This capability indicates that the server is mode-switching 751 (Section 3.4.2) and the MODE READER command needs to be used to 752 enable the READER capability. 754 3.3.3. Extensions 756 Although NNTP is widely and robustly deployed, some parts of the 757 Internet community might wish to extend the NNTP service. It must be 758 emphasized that any extension to NNTP should not be considered 759 lightly. NNTP's strength comes primarily from its simplicity. 760 Experience with many protocols has shown that: 762 Protocols with few options tend towards ubiquity, whilst protocols 763 with many options tend towards obscurity. 765 This means that each and every extension, regardless of its benefits, 766 must be carefully scrutinized with respect to its implementation, 767 deployment, and interoperability costs. In many cases, the cost of 768 extending the NNTP service will likely outweigh the benefit. 770 An extension is a package of associated facilities, often but not 771 always including one or more new commands. Each extension MUST 772 define at least one new capability label (this will often, but need 773 not, be the name of one of these new commands). While any additional 774 capability information can normally be specified using arguments to 775 that label, an extension MAY define more than one capability label. 776 However, this SHOULD be limited to exceptional circumstances. 778 An extension is either a private extension or else its capabilities 779 are included in the IANA registry of capabilities (see Section 3.3.4) 780 and it is defined in an RFC (in which case it is a "registered 781 extension"). Such RFCs either must be on the standards track or must 782 define an IESG-approved experimental protocol. 784 The definition of an extension must include: 785 o a descriptive name for the extension; 786 o the capability label or labels defined by the extension; the 787 capability label of a registered extension MUST NOT begin with 788 "X"; 789 o the syntax, values, and meanings of any arguments for each 790 capability label defined by the extension; 791 o any new NNTP commands associated with the extension - the names of 792 commands associated with registered extensions MUST NOT begin with 793 "X"; 794 o the syntax and possible values of arguments associated with the 795 new NNTP commands; 796 o the response codes and possible values of arguments for the 797 responses of the new NNTP commands; 798 o any new arguments the extension associates with any other pre- 799 existing NNTP commands; 801 o any increase in the maximum length of commands and initial 802 response lines over the value specified in this document; 803 o a specific statement about the effect on pipelining this extension 804 may have (if any); 805 o a specific statement about the circumstances when use of this 806 extension can alter the contents of the capabilities list (other 807 than the new capability labels it defines); 808 o the circumstances under which the extension can cause any pre- 809 existing command to produce a 401, 480, or 483 response; 810 o how the use of MODE READER on a mode-switching server interacts 811 with the extension; 812 o how support for the extension affects the behaviour of a server 813 and NNTP client in any other manner not outlined above; 814 o formal syntax as described in Section 9.9. 816 A private extension MAY or MAY NOT be included in the capabilities 817 list. If it is, the capability label MUST begin with "X". A server 818 MAY provide additional keywords - for new commands and also for new 819 variants of existing commands - as part of a private extension. To 820 avoid the risk of a clash with a future registered extension, these 821 keywords SHOULD begin with "X". 823 If the server advertises a capability defined by a registered 824 extension, it MUST implement the extension so as to fully conform 825 with the specification (for example, it MUST implement all of the 826 commands that the extension describes as mandatory). If it does not 827 implement the extension as specified, it MUST NOT list the extension 828 in the capabilities list under its registered name; in this case it 829 MAY, but SHOULD NOT, provide a private extension (not listed, or 830 listed with a different name) that implements part of the extension 831 or implements the commands of the extension with a different meaning. 833 A server MUST NOT send different response codes to basic NNTP 834 commands documented here or commands documented in registered 835 extensions in response to the availability or use of a private 836 extension. 838 3.3.4. Initial IANA register 840 IANA is requested to maintain a registry of NNTP capability labels. 841 All capability labels in the registry MUST be keywords and MUST NOT 842 begin with X. 844 The initial contents of the registry consists of these entries: 846 +--------------------+-------------------------+--------------------+ 847 | Label | Meaning | Definition | 848 +--------------------+-------------------------+--------------------+ 849 | AUTHINFO | Authentication | [NNTP-AUTH] | 850 | | | | 851 | HDR | Batched header | Section 3.3.2, | 852 | | retrieval | Section 8.5, and | 853 | | | Section 8.6 | 854 | | | | 855 | IHAVE | IHAVE command available | Section 3.3.2 and | 856 | | | Section 6.3.2 | 857 | | | | 858 | IMPLEMENTATION | Server | Section 3.3.2 | 859 | | implementation-specific | | 860 | | information | | 861 | | | | 862 | LIST | LIST command variants | Section 3.3.2 and | 863 | | | Section 7.6.1 | 864 | | | | 865 | MODE-READER | Mode-switching server | Section 3.4.2 | 866 | | and MODE READER command | | 867 | | available | | 868 | | | | 869 | NEWNEWS | NEWNEWS command | Section 3.3.2 and | 870 | | available | Section 7.4 | 871 | | | | 872 | OVER | Overview support | Section 3.3.2, | 873 | | | Section 8.3, and | 874 | | | Section 8.4 | 875 | | | | 876 | POST | POST command available | Section 3.3.2 and | 877 | | | Section 6.3.1 | 878 | | | | 879 | READER | Reader commands | Section 3.3.2 | 880 | | available | | 881 | | | | 882 | SASL | Supported SASL | [NNTP-AUTH] | 883 | | mechanisms | | 884 | | | | 885 | STARTTLS | Transport layer | [NNTP-TLS] | 886 | | security | | 887 | | | | 888 | STREAMING | Streaming feeds | [NNTP-STREAM] | 889 | | | | 890 | VERSION | Supported NNTP versions | Section 3.3.2 | 891 +--------------------+-------------------------+--------------------+ 893 3.4. Mandatory and Optional Commands 895 For a number of reasons, not all the commands in this specification 896 are mandatory. However, it is equally undesirable for every command 897 to be optional, since this means that a client will have no idea what 898 facilities are available. Therefore, as a compromise, some of the 899 commands in this specification are mandatory - they must be supported 900 by all servers - while the remainder are not. The latter are then 901 subdivided into bundles, each indicated by a single capability label. 902 o If the label is included in the capability list returned by the 903 server, the server MUST support all commands in that bundle. 904 o If the label is not included, the server MAY support none or some 905 of the commands, but SHOULD NOT support all of them. In general, 906 there will be no way for a client to determine which commands are 907 supported without trying them. 908 The bundles have been chosen to provide useful functionality, and 909 therefore server authors are discouraged from implementing only part 910 of a bundle. 912 The description of each command will either indicate that it is 913 mandatory, or will give, using the term "indicating capability", the 914 capability label indicating whether or not the bundle including this 915 command is available. 917 Where a server does not implement a command, it MUST always generate 918 a 500 generic response code (or a 501 generic response code in the 919 case of a variant of a command depending on a second keyword where 920 the base command is recognised). Otherwise the command MUST be fully 921 implemented as specified; a server MUST NOT only partially implement 922 any of the commands in this specification. (Client authors should 923 note that some servers, not conforming to this specification, will 924 return a 502 generic response code to some commands that are not 925 implemented.) 927 Note: some commands have cases that require other commands to be used 928 first. If the former command is implemented but the latter is not, 929 the former MUST still generate the relevant specific response code. 930 For example, if ARTICLE (Section 6.2.1) is implemented but GROUP 931 (Section 6.1.1) is not, the correct response to "ARTICLE 1234" 932 remains 412. 934 3.4.1. Reading and Transit Servers 936 NNTP is traditionally used in two different ways. The first use is 937 "reading", where the client fetches articles from a large store 938 maintained by the server for immediate or later presentation to a 939 user, and sends articles created by that user back to the server (an 940 action called "posting") to be stored and distributed to other stores 941 and users. The second use is for the bulk transfer of articles from 942 one store to another. Since the hosts doing this transfer tend to be 943 peers in a network that transmit articles among one another, rather 944 than end-user systems, this process is called "peering" or "transit" 945 (even so, one host is still the client and the other is the server). 947 In practice these two uses are so different that some server 948 implementations are optimised for reading or for transit and, as a 949 result, do not offer the other facility or only offer limited 950 features. Other implementations are more general and offer both. 951 This specification allows for this by bundling the relevant commands 952 accordingly: the IHAVE command is designed for transit, while the 953 commands indicated by the READER capability are designed for reading 954 clients. 956 Except as an effect of the MODE READER (Section 5.3) command on a 957 mode-switching server, once a server advertises either or both of the 958 IHAVE or READER capabilities, it MUST continue to advertise them for 959 the entire session. 961 A server MAY provide different modes of behaviour (transit, reader, 962 or a combination) to different client connections and MAY use 963 external information, such as the IP address of the client, to 964 determine which mode to provide to any given connection. 966 The official TCP port for the NNTP service is 119. However, if a 967 host wishes to offer separate servers for transit and reading 968 clients, port 433 SHOULD be used for the transit server and 119 for 969 the reading server. 971 3.4.2. Mode switching 973 An implementation MAY, but SHOULD NOT, provide both transit and 974 reader facilities on the same server but require the client to select 975 which it wishes to use. Such an arrangement is called a "mode- 976 switching" server. 978 A mode-switching server has two modes: 979 o Transit mode, which applies after the initial connection: 980 * it MUST advertise the MODE-READER capability; 981 * it MUST NOT advertise the READER capability. 982 However, the server MAY cease to advertise the MODE-READER 983 capability after the client uses any command except CAPABILITIES. 984 o Reading mode, after a successful MODE READER (Section 5.3) 985 command: 986 * it MUST NOT advertise the MODE-READER capability; 987 * it MUST advertise the READER capability; 988 * it MAY NOT advertise the IHAVE capability even if it was 989 advertising it in transit mode. 991 A client SHOULD only issue a MODE READER command to a server if it is 992 advertising the MODE-READER capability. If the server does not 993 support CAPABILITIES (and therefore does not conform to this 994 specification), the client MAY use the following heuristic: 995 o if the client wishes to use any "reader" commands, it SHOULD use 996 the MODE READER command immediately after the initial connection; 997 o otherwise it SHOULD NOT use the MODE READER command. 998 In each case it should be prepared for some commands to be 999 unavailable that would have been available if it had made the other 1000 choice. 1002 3.5. Pipelining 1004 NNTP is designed to operate over a reliable bi-directional connection 1005 such as TCP. Therefore, if a command does not depend on the response 1006 to the previous one, it should not matter if it is sent before that 1007 response is received. Doing this is called "pipelining". However, 1008 certain server implementations throw away all text received from the 1009 client following certain commands before sending their response. If 1010 this happens, pipelining will be affected because one or more 1011 commands will have been ignored or misinterpreted, and the client 1012 will be matching the wrong responses to each command. Since there 1013 are significant benefits to pipelining, but also circumstances where 1014 it is reasonable or common for servers to behave in the above manner, 1015 this document puts certain requirements on both clients and servers. 1017 Except where stated otherwise, a client MAY use pipelining. That is, 1018 it may send a command before receiving the response for the previous 1019 command. The server MUST allow pipelining and MUST NOT throw away 1020 any text received after a command. Irrespective of whether or not 1021 pipelining is used, the server MUST process commands in the order 1022 they are sent. 1024 If the specific description of a command says it "MUST NOT be 1025 pipelined", that command MUST end any pipeline of commands. That is, 1026 the client MUST NOT send any following command until receiving the 1027 CRLF at the end of the response from the command. The server MAY 1028 ignore any data received after the command and before the CRLF at the 1029 end of the response is sent to the client. 1031 The initial connection must not be part of a pipeline; that is, the 1032 client MUST NOT send any command until receiving the CRLF at the end 1033 of the greeting. 1035 If the client uses blocking system calls to send commands, it MUST 1036 ensure that the amount of text sent in pipelining does not cause a 1037 deadlock between transmission and reception. The amount of text 1038 involved will depend on window sizes in the transmission layer, and 1039 is typically 4k octets for TCP. (Since the server only sends data in 1040 response to commands from the client, the converse problem does not 1041 occur.) 1043 3.5.1. Examples 1045 Example of correct use of pipelining: 1047 [C] GROUP misc.test 1048 [C] STAT 1049 [C] NEXT 1050 [S] 211 1234 3000234 3002322 misc.test 1051 [S] 223 3000234 <45223423@example.com> retrieved 1052 [S] 223 3000237 <668929@example.org> retrieved 1054 Example of incorrect use of pipelining (the MODE READER command may 1055 not be pipelined): 1057 [C] MODE READER 1058 [C] DATE 1059 [C] NEXT 1060 [S] 200 Server ready, posting allowed 1061 [S] 223 3000237 <668929@example.org> retrieved 1063 The DATE command has been thrown away by the server and so there is 1064 no 111 response to match it. 1066 3.6. Articles 1068 NNTP is intended to transfer articles between clients and servers. 1069 For the purposes of this specification, articles are required to 1070 conform to the rules in this section and clients and servers MUST 1071 correctly process any article received from the other that does so. 1072 Note that this requirement applies only to the contents of 1073 communications over NNTP; it does not prevent the client or server 1074 from subsequently rejecting an article for reasons of local policy. 1075 Also see Appendix A for further restrictions on the format of 1076 articles in some uses of NNTP. 1078 An article consists of two parts: the headers and the body. They are 1079 separated by a single empty line, or in other words by two 1080 consecutive CRLF pairs (if there is more than one empty line, the 1081 second and subsequent ones are part of the body). In order to meet 1082 the general requirements of NNTP, an article MUST NOT include the 1083 octet NUL, MUST NOT contain the octets LF and CR other than as part 1084 of a CRLF pair, and MUST end with a CRLF pair. This specification 1085 puts no further restrictions on the body; in particular, it MAY be 1086 empty. 1088 The headers of an article consist of one or more header lines. Each 1089 header line consists of a header name, a colon, a space, the header 1090 content, and a CRLF in that order. The name consists of one or more 1091 printable US-ASCII characters other than colon and, for the purposes 1092 of this specification, is not case-sensitive. There MAY be more than 1093 one header line with the same name. The content MUST NOT contain 1094 CRLF; it MAY be empty. A header may be "folded"; that is, a CRLF 1095 pair may be placed before any TAB or space in the line; there MUST 1096 still be some other octet between any two CRLF pairs in a header 1097 line. (Note that folding means that the header line occupies more 1098 than one line when displayed or transmitted; nevertheless it is still 1099 referred to as "a" header line.) The presence or absence of folding 1100 does not affect the meaning of the header line; that is, the CRLF 1101 pairs introduced by folding are not considered part of the header 1102 content. Header lines SHOULD NOT be folded before the space after 1103 the colon that follows the header name, and SHOULD include at least 1104 one octet other than %x09 or %x20 between CRLF pairs. However, if an 1105 article has been received from elsewhere with one of these, clients 1106 and servers MAY transfer it to the other without re-folding it. 1108 The content of a header SHOULD be in UTF-8. However, if an 1109 implementation receives an article from elsewhere that uses octets in 1110 the range 128 to 255 in some other manner, it MAY pass it to a client 1111 or server without modification. Therefore implementations MUST be 1112 prepared to receive such headers and also data derived from them 1113 (e.g. in the responses from the OVER (Section 8.3) command) and MUST 1114 NOT assume that they are always UTF-8. Any external processing of 1115 those headers, including identifying the encoding used, is outside 1116 the scope of this document. 1118 Each article MUST have a unique message-id; two articles offered by 1119 an NNTP server MUST NOT have the same message-id. For the purposes 1120 of this specification, message-ids are opaque strings that MUST meet 1121 the following requirements: 1122 o A message-id MUST begin with "<" and end with ">", and MUST NOT 1123 contain the latter except at the end. 1124 o A message-id MUST be between 3 and 250 octets in length. 1125 o A message-id MUST NOT contain octets other than printable US-ASCII 1126 characters. 1127 Two message-ids are the same if and only if they consist of the same 1128 sequence of octets. 1130 This specification does not describe how the message-id of an article 1131 is determined. If the server does not have any way to determine a 1132 message-id from the article itself, it MUST synthesize one (this 1133 specification does not require the article to be changed as a 1134 result). See also Appendix A.2. 1136 4. The WILDMAT format 1138 The WILDMAT format described here is based on the version first 1139 developed by Rich Salz [SALZ1992], which in turn was derived from the 1140 format used in the UNIX "find" command to articulate file names. It 1141 was developed to provide a uniform mechanism for matching patterns in 1142 the same manner that the UNIX shell matches filenames. 1144 4.1. Wildmat syntax 1146 A wildmat is described by the following ABNF [RFC2234] syntax, which 1147 is an extract of that in Section 9.8. 1149 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 1150 wildmat-pattern = 1*wildmat-item 1151 wildmat-item = wildmat-exact / wildmat-wild 1152 wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 1153 UTF8-non-ascii ; exclude ! * , ? [ \ ] 1154 wildmat-wild = "*" / "?" 1156 Note: the characters \ , [ and ] are not allowed in wildmats, while * 1157 and ? are always wildcards. This should not be a problem since these 1158 characters cannot occur in newsgroup names, which is the only current 1159 use of wildmats. Backslash is commonly used to suppress the special 1160 meaning of characters while brackets are used to introduce sets. 1161 However, these usages are not universal and interpretation of these 1162 characters in the context of UTF-8 strings is both potentially 1163 complex and differs from existing practice, so they were omitted from 1164 this specification. A future extension to this specification may 1165 provide semantics for these characters. 1167 4.2. Wildmat semantics 1169 A wildmat is tested against a string, and either matches or does not 1170 match. To do this, each constituent is matched 1171 against the string and the rightmost pattern that matches is 1172 identified. If that is not preceded with "!", the 1173 whole wildmat matches. If it is preceded by "!", or if no matches, the whole wildmat does not match. 1176 For example, consider the wildmat "a*,!*b,*c*": 1177 o the string "aaa" matches because the rightmost match is with "a*" 1178 o the string "abb" does not match because the rightmost match is 1179 with "*b" 1181 o the string "ccb" matches because the rightmost match is with "*c*" 1182 o the string "xxx" does not match because no 1183 matches 1185 A matches a string if the string can be broken into 1186 components, each of which matches the corresponding in 1187 the pattern; the matches must be in the same order, and the whole 1188 string must be used in the match. The pattern is "anchored"; that 1189 is, the first and last characters in the string must match the first 1190 and last item respectively (unless that item is an asterisk matching 1191 zero characters). 1193 A matches the same character (which may be more than 1194 one octet in UTF-8). 1196 "?" matches exactly one character (which may be more than one octet). 1198 "*" matches zero or more characters. It can match an empty string, 1199 but it cannot match a subsequence of a UTF-8 sequence that is not 1200 aligned to the character boundaries. 1202 4.3. Extensions 1204 An NNTP server or extension MAY extend the syntax or semantics of 1205 wildmats provided that all wildmats that meet the requirements of 1206 Section 4.1 have the meaning ascribed to them by Section 4.2. Future 1207 editions of this document may also extend wildmats. 1209 4.4. Examples 1211 In these examples, $ and @ are used to represent the two octets %xC2 1212 and %xA3 respectively; $@ is thus the UTF-8 encoding for the pound 1213 sterling symbol, shown as # in the descriptions. 1215 Wildmat Description of strings that match 1216 abc the one string "abc" 1217 abc,def the two strings "abc" and "def" 1218 $@ the one character string "#" 1219 a* any string that begins with "a" 1220 a*b any string that begins with "a" and ends with "b" 1221 a*,*b any string that begins with "a" or ends with "b" 1222 a*,!*b any string that begins with "a" and does not end with 1223 "b" 1224 a*,!*b,c* any string that begins with "a" and does not end with 1225 "b", and any string that begins with "c" no matter 1226 what it ends with 1227 a*,c*,!*b any string that begins with "a" or "c" and does not 1228 end with "b" 1229 ?a* any string with "a" as its second character 1230 ??a* any string with "a" as its third character 1231 *a? any string with "a" as its penultimate character 1232 *a?? any string with "a" as its antepenultimate character 1234 5. Session administration commands 1236 5.1. Initial Connection 1238 5.1.1. Usage 1240 This command MUST NOT be pipelined. 1242 Responses 1244 200 Service available, posting allowed [1] 1245 201 Service available, posting prohibited [1] 1246 400 Service temporarily unavailable [1][2] 1247 502 Service permanently unavailable [1][2] 1249 [1] These are the only valid response codes for the initial 1250 greeting; the server MUST not return any other generic 1251 response code. 1252 [2] Following a 400 or 502 response the server MUST 1253 immediately close the connection. 1255 5.1.2. Description 1257 There is no command presented by the client upon initial connection 1258 to the server. The server MUST present an appropriate response code 1259 as a greeting to the client. This response informs the client 1260 whether service is available and whether the client is permitted to 1261 post. 1263 If the server will accept further commands from the client including 1264 POST, the server MUST present a 200 greeting code. If the server 1265 will accept further commands from the client, but it is not 1266 authorized to post articles using the POST command, the server MUST 1267 present a 201 greeting code. 1269 Otherwise the server MUST present a 400 or 502 greeting code and then 1270 immediately close the connection. 400 SHOULD be used if the issue is 1271 only temporary (for example, because of load) and the client can 1272 expect to be able to connect successfully at some point in the future 1273 without making any changes. 502 MUST be used if the client is not 1274 permitted under any circumstances to interact with the server, and 1275 MAY be used if the server has insufficient information to determine 1276 whether the issue is temporary or permanent. 1278 Note: the distinction between the 200 and 201 response codes has 1279 turned out in practice to be insufficient; for example, some servers 1280 do not allow posting until the client has authenticated, while other 1281 clients assume that a 201 response means that posting will never be 1282 possible even after authentication. Therefore clients SHOULD use the 1283 CAPABILITIES command (Section 5.2) rather than rely on this response. 1285 5.1.3. Examples 1287 Example of a normal connection from an authorized client which then 1288 terminates the session (see Section 5.4): 1290 [Initial connection set-up completed.] 1291 [S] 200 NNTP Service Ready, posting permitted 1292 [C] QUIT 1293 [S] 205 NNTP Service exits normally 1294 [Server closes connection.] 1296 Example of a normal connection from an authorized client that is not 1297 permitted to post; it also immediately terminates the session: 1299 [Initial connection set-up completed.] 1300 [S] 201 NNTP Service Ready, posting prohibited 1301 [C] QUIT 1302 [S] 205 NNTP Service exits normally 1303 [Server closes connection.] 1305 Example of a normal connection from an unauthorized client: 1307 [Initial connection set-up completed.] 1308 [S] 502 NNTP Service permanently unavailable 1309 [Server closes connection.] 1311 Example of a connection from a client where the server is unable to 1312 provide service: 1314 [Initial connection set-up completed.] 1315 [S] 400 NNTP Service temporarily unavailable 1316 [Server closes connection.] 1318 5.2. CAPABILITIES 1320 5.2.1. Usage 1322 This command is mandatory. 1324 Syntax 1326 CAPABILITIES [keyword] 1328 Responses 1330 101 Capability list follows (multi-line) 1332 Parameters 1334 keyword additional feature, see description 1336 5.2.2. Description 1338 The CAPABILITIES command allows a client to determine the 1339 capabilities of the server at any given time. 1341 This command MAY be issued at any time; the server MUST NOT require 1342 it to be issued in order to make use of any capability. The response 1343 generated by this command MAY change during a session because of 1344 other state information (which in turn may be changed by the effects 1345 of other commands or by external events). An NNTP client is only 1346 able to get the current and correct information concerning available 1347 capabilities at any point during a session by issuing a CAPABILITIES 1348 command at that point of that session and processing the response. 1350 The capability list is returned as a multi-line data block following 1351 the 101 response code. Each capability is described by a separate 1352 capability line. The server MUST NOT list the same capability twice 1353 in the response, even with different arguments. Except that the 1354 VERSION capability MUST be the first line, the order in which the 1355 capability lines appears is not significant; the server need not even 1356 consistently return the same order. 1358 While some capabilities are likely to be always available or never 1359 available, others - notably extensions - will appear and disappear 1360 depending on server state changes within the session or external 1361 events between sessions. An NNTP client MAY cache the results of 1362 this command, but MUST NOT rely on the correctness of any cached 1363 results, whether from earlier in this session or from a previous 1364 session, MUST cope gracefully with the cached status being out of 1365 date, and SHOULD (if caching results) provide a way to force the 1366 cached information to be refreshed. Furthermore, a client MUST NOT 1367 use cached results in relation to security, privacy, and 1368 authentication extensions. See Section 12.6 for further discussion 1369 of this topic. 1371 The keyword argument is not used by this specification. It is 1372 provided so that extensions or revisions to this specification can 1373 include extra features for this command without requiring the 1374 CAPABILITIES command to be used twice (once to determine if the extra 1375 features are available and a second time to make use of them). If 1376 the server does not recognise the argument (and it is a keyword), it 1377 MUST respond with the 101 response code as if the argument had been 1378 omitted. If an argument is provided that the server does recognise, 1379 it MAY use the 101 response code or MAY use some other response code 1380 (which will be defined in the specification of that feature). If the 1381 argument is not a keyword, the 501 generic response code MUST be 1382 returned. The server MUST NOT generate any other response code to 1383 the CAPABILITIES command. 1385 5.2.3. Examples 1387 Example of a minimal response (a read-only server): 1389 [C] CAPABILITIES 1390 [S] 101 Capability list: 1391 [S] VERSION 2 1392 [S] READER 1393 [S] LIST ACTIVE NEWSGROUPS 1394 [S] . 1396 Example of a response from a server that has a range of facilities 1397 and also describes itself: 1399 [C] CAPABILITIES 1400 [S] 101 Capability list: 1401 [S] VERSION 2 1402 [S] READER 1403 [S] IHAVE 1404 [S] POST 1405 [S] NEWNEWS 1406 [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES OVERVIEW.FMT 1407 [S] IMPLEMENTATION INN 4.2 2004-12-25 1408 [S] OVER MSGID 1409 [S] STREAMING 1410 [S] XSECRET 1411 [S] . 1413 Example of a server that supports more than one version of NNTP: 1415 [C] CAPABILITIES 1416 [S] 101 Capability list: 1417 [S] VERSION 2 3 1418 [S] READER 1419 [S] LIST ACTIVE NEWSGROUPS 1421 [S] . 1423 Example of a client attempting to use a feature of the CAPABILITIES 1424 command that the server does not support: 1426 [C] CAPABILITIES AUTOUPDATE 1427 [S] 101 Capability list: 1428 [S] VERSION 2 1429 [S] READER 1430 [S] IHAVE 1431 [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT HEADERS 1432 [S] OVER MSGID 1433 [S] HDR 1434 [S] NEWNEWS 1435 [S] . 1437 5.3. MODE READER 1439 5.3.1. Usage 1441 Indicating capability: MODE-READER 1443 This command MUST NOT be pipelined. 1445 Syntax 1447 MODE READER 1449 Responses 1451 200 Posting allowed 1452 201 Posting prohibited 1453 502 Reading service permanently unavailable [1] 1455 [1] Following a 502 response the server MUST immediately close 1456 the connection. 1458 5.3.2. Description 1460 The MODE READER command instructs a mode-switching server to switch 1461 modes, as described in Section 3.4.2. 1463 If the server is mode-switching, it switches from its transit mode to 1464 its reader mode, indicating the fact by changing the capability list 1465 accordingly, and then MUST return a 200 or 201 response with the same 1466 meaning as for the initial greeting (as described in Section 5.1.1); 1467 note that the response need not be the same as the one presented 1468 during the initial greeting. The client MUST NOT issue MODE READER 1469 more than once in a session or after any security or privacy commands 1470 are issued. When the MODE READER command is issued, the server MAY 1471 reset its state to that immediately after the initial connection 1472 before switching mode. 1474 If the server is not mode-switching, then: 1475 o If it advertises the READER capability, it MUST return a 200 or 1476 201 response with the same meaning as for the initial greeting; in 1477 this case the command MUST NOT affect the server state in any way. 1478 o If it does not advertise the READER capability, it MUST return a 1479 502 response and then immediately close the connection. 1481 5.3.3. Examples 1483 Example of use of the MODE READER command on a transit-only server 1484 (which therefore does not providing reading facilities): 1486 [C] CAPABILITIES 1487 [S] 101 Capability list: 1488 [S] VERSION 2 1489 [S] IHAVE 1490 [S] . 1491 [C] MODE READER 1492 [S] 502 Transit service only 1493 [Server closes connection.] 1495 Example of use of the MODE READER command on a server that provides 1496 reading facilities: 1498 [C] CAPABILITIES 1499 [S] 101 Capability list: 1500 [S] VERSION 2 1501 [S] READER 1502 [S] LIST ACTIVE NEWSGROUPS 1503 [S] . 1504 [C] MODE READER 1505 [S] 200 Reader mode, posting permitted 1506 [C] IHAVE 1507 [S] 500 Permission denied 1508 [C] GROUP misc.test 1509 [S] 211 1234 3000234 3002322 misc.test 1511 Note that in both these situations the client SHOULD NOT use MODE 1512 READER. 1514 Example of use of the MODE READER command on a mode-switching server: 1516 [C] CAPABILITIES 1517 [S] 101 Capability list: 1518 [S] VERSION 2 1519 [S] IHAVE 1520 [S] MODE-READER 1521 [S] . 1522 [C] MODE READER 1523 [S] 200 Reader mode, posting permitted 1524 [C] CAPABILITIES 1525 [S] 101 Capability list: 1526 [S] VERSION 2 1527 [S] READER 1528 [S] NEWNEWS 1529 [S] LIST ACTIVE NEWSGROUPS 1530 [S] STARTTLS 1531 [S] . 1533 In this case the server offers (but does not require) TLS privacy in 1534 its reading mode but not its transit mode. 1536 Example of use of the MODE READER command where the client is not 1537 permitted to post: 1539 [C] MODE READER 1540 [S] 201 NNTP Service Ready, posting prohibited 1542 5.4. QUIT 1544 5.4.1. Usage 1546 This command is mandatory. 1548 Syntax 1550 QUIT 1552 Responses 1554 205 Connection closing 1556 5.4.2. Description 1558 The client uses the QUIT command to terminate the session. The 1559 server MUST acknowledge the QUIT command and then close the 1560 connection to the client. This is the preferred method for a client 1561 to indicate that it has finished all its transactions with the NNTP 1562 server. 1564 If a client simply disconnects (or the connection times out or some 1565 other fault occurs), the server MUST gracefully cease its attempts to 1566 service the client, disconnecting from its end if necessary. 1568 The server MUST NOT generate any response code to the QUIT command 1569 other than 205 or, if any arguments are provided, 501. 1571 5.4.3. Examples 1573 [C] QUIT 1574 [S] 205 closing connection 1575 [Server closes connection.] 1577 6. Article posting and retrieval 1579 News reading clients have available a variety of mechanisms to 1580 retrieve articles via NNTP. The news articles are stored and indexed 1581 using three types of keys. The first type of key is the message-id 1582 of an article and is globally unique. The second type of key is 1583 composed of a newsgroup name and an article number within that 1584 newsgroup. On a particular server there MUST be only one article 1585 with a given number within any newsgroup and an article MUST NOT have 1586 two different numbers in the same newsgroup. An article can be 1587 cross-posted to multiple newsgroups, so there may be multiple keys 1588 that point to the same article on the same server; these MAY have 1589 different numbers in each newsgroup. However, this type of key is 1590 not required to be globally unique and so the same key MAY refer to 1591 different articles on different servers. (Note that the terms 1592 "group" and "newsgroup" are equivalent.) 1594 The final type of key is the arrival timestamp, giving the time that 1595 the article arrived at the server. The server MUST ensure that 1596 article numbers are issued in order of arrival timestamp; that is, 1597 articles arriving later MUST have higher numbers than those that 1598 arrive earlier. The server SHOULD allocate the next sequential 1599 unused number to each new article. 1601 Article numbers MUST lie between 1 and 4,294,967,295 inclusive. The 1602 client and server MAY use leading zeroes in specifying article 1603 numbers, but MUST NOT use more than 16 digits. In some situations, 1604 the value zero replaces an article number to show some special 1605 situation. 1607 6.1. Group and article selection 1609 The following commands are used to set the "currently selected 1610 newsgroup" and the "current article number", which are used by 1611 various commands. At the start of an NNTP session, both of these 1612 values are set to the special value "invalid". 1614 6.1.1. GROUP 1616 6.1.1.1. Usage 1618 Indicating capability: READER 1620 Syntax 1622 GROUP group 1624 Responses 1626 211 number low high group Group successfully selected 1627 411 No such newsgroup 1629 Parameters 1631 group name of newsgroup 1632 number estimated number of articles in the group 1633 low reported low water mark 1634 high reported high water mark 1636 6.1.1.2. Description 1638 The GROUP command selects a newsgroup as the currently selected 1639 newsgroup and returns summary information about it. 1641 The required argument is the name of the newsgroup to be selected 1642 (e.g. "news.software.nntp"). A list of valid newsgroups may be 1643 obtained by using the LIST ACTIVE command (see Section 7.6.3). 1645 The successful selection response will return the article numbers of 1646 the first and last articles in the group at the moment of selection 1647 (these numbers are referred to as the "reported low water mark" and 1648 the "reported high water mark"), and an estimate of the number of 1649 articles in the group currently available. 1651 If the group is not empty, the estimate MUST be at least the actual 1652 number of articles available, and MUST be no greater than one more 1653 than the difference between the reported low and high water marks. 1654 (Some implementations will actually count the number of articles 1655 currently stored. Others will just subtract the low water mark from 1656 the high water mark and add one to get an estimate.) 1658 If the group is empty, one of the following three situations will 1659 occur. Clients MUST accept all three cases; servers MUST NOT 1660 represent an empty group in any other way. 1661 o The high water mark will be one less than the low water mark, and 1662 the estimated article count will be zero. Servers SHOULD use this 1663 method to show an empty group. This is the only time that the 1664 high water mark can be less than the low water mark. 1665 o All three numbers will be zero. 1666 o The high water mark is greater than or equal to the low water 1667 mark. The estimated article count might be zero or non-zero; if 1668 non-zero, the same requirements apply as for a non-empty group. 1670 The set of articles in a group may change after the GROUP command is 1671 carried out. That is: 1672 o articles may be removed from the group 1673 o articles may be reinstated in the group with the same article 1674 number, but those articles MUST have numbers no less than the 1675 reported low water mark (note that this is a reinstatement of the 1676 previous article, not a new article reusing the number) 1677 o new articles may be added with article numbers greater than the 1678 reported high water mark (if an article that was the one with the 1679 highest number has been removed and the high water mark adjusted 1680 accordingly, the next new article will not have the number one 1681 greater than the reported high water mark) 1683 Except when the group is empty and all three numbers are zero, 1684 whenever a subsequent GROUP command for the same newsgroup is issued, 1685 either by the same client or a different client, the reported low 1686 water mark in the response MUST be no less than that in any previous 1687 response for that newsgroup in any session, and SHOULD be no less 1688 than that in any previous response for that newsgroup ever sent to 1689 any client. Any failure to meet the latter condition SHOULD be 1690 transient only. The client may make use of the low water mark to 1691 remove all remembered information about articles with lower numbers, 1692 as these will never recur. This includes the situation when the high 1693 water mark is one less than the low water mark. No similar 1694 assumption can be made about the high water mark, as this can 1695 decrease if an article is removed, and then increase again if it is 1696 reinstated or if new articles arrive. 1698 When a valid group is selected by means of this command, the 1699 currently selected newsgroup MUST be set to that group and the 1700 current article number MUST be set to the first article in the group 1701 (this applies even if the group is already the currently selected 1702 newsgroup). If an empty newsgroup is selected, the current article 1703 number is made invalid. If an invalid group is specified, the 1704 currently selected newsgroup and current article number MUST NOT be 1705 changed. 1707 The GROUP or LISTGROUP command (see Section 6.1.2) MUST be used by a 1708 client and a successful response received before any other command is 1709 used that depends on the value of the currently selected newsgroup or 1710 current article number. 1712 If the group specified is not available on the server, a 411 response 1713 MUST be returned. 1715 6.1.1.3. Examples 1717 Example for a group known to the server: 1719 [C] GROUP misc.test 1720 [S] 211 1234 3000234 3002322 misc.test 1722 Example for a group unknown to the server: 1724 [C] GROUP example.is.sob.bradner.or.barber 1725 [S] 411 example.is.sob.bradner.or.barber is unknown 1727 Example of an empty group using the preferred response: 1729 [C] GROUP example.currently.empty.newsgroup 1730 [S] 211 0 4000 3999 example.currently.empty.newsgroup 1732 Example of an empty group using an alternative response: 1734 [C] GROUP example.currently.empty.newsgroup 1735 [S] 211 0 0 0 example.currently.empty.newsgroup 1737 Example of an empty group using a different alternative response: 1739 [C] GROUP example.currently.empty.newsgroup 1740 [S] 211 0 4000 4321 example.currently.empty.newsgroup 1742 Example reselecting the currently selected newsgroup: 1744 [C] GROUP misc.test 1745 [S] 211 1234 234 567 misc.test 1746 [C] STAT 444 1747 [S] 223 444 <123456@example.net> retrieved 1748 [C] GROUP misc.test 1749 [S] 211 1234 234 567 misc.test 1750 [C] STAT 1751 [S] 223 234 retrieved 1753 6.1.2. LISTGROUP 1755 6.1.2.1. Usage 1757 Indicating capability: READER 1759 Syntax 1761 LISTGROUP [group [range]] 1763 Responses 1765 211 number low high group Article numbers follow (multi-line) 1766 411 No such newsgroup 1767 412 No newsgroup selected [1] 1769 Parameters 1771 group name of newsgroup 1772 range range of articles to report 1773 number estimated number of articles in the group 1774 low reported low water mark 1775 high reported high water mark 1777 [1] The 412 response can only occur if no group has been 1778 specified. 1780 6.1.2.2. Description 1782 The LISTGROUP command selects a newsgroup in the same manner as the 1783 the GROUP command (see Section 6.1.1) but also provides a list of 1784 article numbers in the newsgroup. If no group is specified, the 1785 currently selected newsgroup is used. 1787 On success, a list of article numbers is returned as a multi-line 1788 data block following the 211 response code (the arguments on the 1789 initial response line are the same as for the GROUP command). The 1790 list contains one number per line and is in numerical order. It 1791 lists precisely those articles that exist in the group at the moment 1792 of selection (therefore an empty group produces an empty list); if 1793 the optional range argument is specified, only those articles that 1794 are within the range are included in the list (therefore the list MAY 1795 be empty even if the group is not). 1797 The range argument may be any of the following: 1798 o an article number 1799 o an article number followed by a dash to indicate all following 1800 o an article number followed by a dash followed by another article 1801 number 1802 In the last case, if the second number is less than the first number 1803 then the range contains no articles. Omitting the range is 1804 equivalent to the range 1- being specified. 1806 If the group specified is not available on the server, a 411 response 1807 MUST be returned. If no group is specified and the currently 1808 selected newsgroup is invalid, a 412 response MUST be returned. 1810 Except that the group argument is optional, a range argument can be 1811 specified, and that a multi-line data block follows the 211 response 1812 code, the LISTGROUP command is identical to the GROUP command. In 1813 particular, when successful, the command sets the current article 1814 number to the first article in the group, if any, even if this is not 1815 within the range specified by the second argument. 1817 Note that the range argument is a new feature in this specification 1818 and servers that do not support CAPABILITIES (and therefore do not 1819 conform to this specification) are unlikely to support it. 1821 6.1.2.3. Examples 1823 Example of LISTGROUP being used to select a group: 1825 [C] LISTGROUP misc.test 1826 [S] 211 2000 3000234 3002322 misc.test list follows 1827 [S] 3000234 1828 [S] 3000237 1829 [S] 3000238 1830 [S] 3000239 1831 [S] 3002322 1832 [S] . 1834 Example of LISTGROUP on an empty group: 1836 [C] LISTGROUP example.empty.newsgroup 1837 [S] 211 0 0 0 example.empty.newsgroup list follows 1838 [S] . 1840 Example of LISTGROUP on a valid currently selected newsgroup: 1842 [C] GROUP misc.test 1843 [S] 211 2000 3000234 3002322 misc.test 1844 [C] LISTGROUP 1845 [S] 211 2000 3000234 3002322 misc.test list follows 1846 [S] 3000234 1848 [S] 3000237 1849 [S] 3000238 1850 [S] 3000239 1851 [S] 3002322 1852 [S] . 1854 Example of LISTGROUP with a range: 1856 [C] LISTGROUP misc.test 3000238-3000248 1857 [S] 211 2000 3000234 3002322 misc.test list follows 1858 [S] 3000238 1859 [S] 3000239 1860 [S] . 1862 Example of LISTGROUP with an empty range: 1864 [C] LISTGROUP misc.test 12345678- 1865 [S] 211 2000 3000234 3002322 misc.test list follows 1866 [S] . 1868 Example of LISTGROUP with an invalid range: 1870 [C] LISTGROUP misc.test 9999-111 1871 [S] 211 2000 3000234 3002322 misc.test list follows 1872 [S] . 1874 6.1.3. LAST 1876 6.1.3.1. Usage 1878 Indicating capability: READER 1880 Syntax 1882 LAST 1884 Responses 1886 223 n message-id Article found 1887 412 No newsgroup selected 1888 420 Current article number is invalid 1889 422 No previous article in this group 1891 Parameters 1893 n article number 1894 message-id article message-id 1896 6.1.3.2. Description 1898 If the currently selected newsgroup is valid, the current article 1899 number MUST be set to the previous article in that newsgroup (that 1900 is, the highest existing article number less than the current article 1901 number). If successful, a response indicating the new current 1902 article number and the message-id of that article MUST be returned. 1903 No article text is sent in response to this command. 1905 There MAY be no previous article in the group, although the current 1906 article number is not the reported low water mark. There MUST NOT be 1907 a previous article when the current article number is the reported 1908 low water mark. 1910 Because articles can be removed and added, the results of multiple 1911 LAST and NEXT commands MAY not be consistent over the life of a 1912 particular NNTP session. 1914 If the current article number is already the first article of the 1915 newsgroup, a 422 response MUST be returned. If the current article 1916 number is invalid, a 420 response MUST be returned. If the currently 1917 selected newsgroup is invalid, a 412 response MUST be returned. In 1918 all three cases the currently selected newsgroup and current article 1919 number MUST NOT be altered. 1921 6.1.3.3. Examples 1923 Example of a successful article retrieval using LAST: 1925 [C] GROUP misc.test 1926 [S] 211 1234 3000234 3002322 misc.test 1927 [C] NEXT 1928 [S] 223 3000237 <668929@example.org> retrieved 1929 [C] LAST 1930 [S] 223 3000234 <45223423@example.com> retrieved 1932 Example of an attempt to retrieve an article without having selected 1933 a group (via the GROUP command) first: 1935 [Assumes currently selected newsgroup is invalid.] 1936 [C] LAST 1937 [S] 412 no newsgroup selected 1939 Example of an attempt to retrieve an article using the LAST command 1940 when the current article number is that of the first article in the 1941 group: 1943 [C] GROUP misc.test 1944 [S] 211 1234 3000234 3002322 misc.test 1945 [C] LAST 1946 [S] 422 No previous article to retrieve 1948 Example of an attempt to retrieve an article using the LAST command 1949 when the currently selected newsgroup is empty: 1951 [C] GROUP example.empty.newsgroup 1952 [S] 211 0 0 0 example.empty.newsgroup 1953 [C] LAST 1954 [S] 420 No current article selected 1956 6.1.4. NEXT 1958 6.1.4.1. Usage 1960 Indicating capability: READER 1962 Syntax 1964 NEXT 1966 Responses 1968 223 n message-id Article found 1969 412 No newsgroup selected 1970 420 Current article number is invalid 1971 421 No next article in this group 1973 Parameters 1975 n article number 1976 message-id article message-id 1978 6.1.4.2. Description 1980 If the currently selected newsgroup is valid, the current article 1981 number MUST be set to the next article in that newsgroup (that is, 1982 the lowest existing article number greater than the current article 1983 number). If successful, a response indicating the new current 1984 article number and the message-id of that article MUST be returned. 1985 No article text is sent in response to this command. 1987 If the current article number is already the last article of the 1988 newsgroup, a 421 response MUST be returned. In all other aspects 1989 (apart, of course, from the lack of 422 response) this command is 1990 identical to the LAST command (Section 6.1.3). 1992 6.1.4.3. Examples 1994 Example of a successful article retrieval using NEXT: 1996 [C] GROUP misc.test 1997 [S] 211 1234 3000234 3002322 misc.test 1998 [C] NEXT 1999 [S] 223 3000237 <668929@example.org> retrieved 2001 Example of an attempt to retrieve an article without having selected 2002 a group (via the GROUP command) first: 2004 [Assumes currently selected newsgroup is invalid.] 2005 [C] NEXT 2006 [S] 412 no newsgroup selected 2008 Example of an attempt to retrieve an article using the NEXT command 2009 when the current article number is that of the last article in the 2010 group: 2012 [C] GROUP misc.test 2013 [S] 211 1234 3000234 3002322 misc.test 2014 [C] STAT 3002322 2015 [S] 223 3002322 <411@example.net> retrieved 2016 [C] NEXT 2017 [S] 421 No next article to retrieve 2019 Example of an attempt to retrieve an article using the NEXT command 2020 when the currently selected newsgroup is empty: 2022 [C] GROUP example.empty.newsgroup 2023 [S] 211 0 0 0 example.empty.newsgroup 2024 [C] NEXT 2025 [S] 420 No current article selected 2027 6.2. Retrieval of articles and article sections 2029 The ARTICLE, BODY, HEAD, and STAT commands are very similar. They 2030 differ only in the parts of the article that are presented to the 2031 client and in the successful response code. The ARTICLE command is 2032 described here in full, while the other commands are described in 2033 terms of the differences. As specified in Section 3.6, an article 2034 consists of two parts: the article headers and the article body. 2036 When responding to one of these commands, the server MUST present the 2037 entire article or appropriate part and MUST NOT attempt to alter or 2038 translate it in any way. 2040 6.2.1. ARTICLE 2042 6.2.1.1. Usage 2044 Indicating capability: READER 2046 Syntax 2048 ARTICLE message-id 2049 ARTICLE number 2050 ARTICLE 2052 Responses 2054 First form (message-id specified) 2056 220 0|n message-id Article follows (multi-line) 2057 430 No article with that message-id 2059 Second form (article number specified) 2061 220 n message-id Article follows (multi-line) 2062 412 No newsgroup selected 2063 423 No article with that number 2065 Third form (current article number used) 2067 220 n message-id Article follows (multi-line) 2068 412 No newsgroup selected 2069 420 Current article number is invalid 2071 Parameters 2073 number Requested article number 2074 n Returned article number 2075 message-id Article message-id 2077 6.2.1.2. Description 2079 The ARTICLE command selects an article based on the arguments and 2080 presents the entire article (that is, the headers, an empty line, and 2081 the body in that order). The command has three forms. 2083 In the first form, a message-id is specified and the server presents 2084 the article with that message-id. In this case, the server MUST NOT 2085 alter the currently selected newsgroup or current article number. 2086 This is both to facilitate the presentation of articles that may be 2087 referenced within another article being read, and because of the 2088 semantic difficulties of determining the proper sequence and 2089 membership of an article that may have been cross-posted to more than 2090 one newsgroup. 2092 In the response, the article number MUST be replaced with zero, 2093 except that if there is a currently selected newsgroup and the 2094 article is present in that group, the server MAY use that article 2095 number. (The server is not required to determine whether the article 2096 is in the currently selected newsgroup or, if so, what article number 2097 it has; the client MUST always be prepared for zero to be specified.) 2098 The server MUST NOT provide an article number unless use of that 2099 number in a second ARTICLE command immediately following this one 2100 would return the same article. Even if the server chooses to return 2101 article numbers in these circumstances, it need not do so 2102 consistently; it MAY return zero to any such command (also see the 2103 STAT examples (Section 6.2.4.3)). 2105 In the second form, an article number is specified. If there is an 2106 article with that number in the currently selected newsgroup, the 2107 server MUST set the current article number to that number. 2109 In the third form, the article indicated by the current article 2110 number in the currently selected newsgroup is used. 2112 Note that a previously valid article number MAY become invalid if the 2113 article has been removed. A previously invalid article number MAY 2114 become valid if the article has been reinstated, but such an article 2115 number MUST be no less than the reported low water mark for that 2116 group. 2118 The server MUST NOT change the currently selected newsgroup as a 2119 result of this command. The server MUST NOT change the current 2120 article number except when an article number argument was provided 2121 and the article exists; in particular, it MUST NOT change it 2122 following an unsuccessful response. 2124 Since the message-id is unique for each article, it may be used by a 2125 client to skip duplicate displays of articles that have been posted 2126 more than once, or to more than one newsgroup. 2128 The article is returned as a multi-line data block following the 220 2129 response code. 2131 If the argument is a message-id and no such article exists, a 430 2132 response MUST be returned. If the argument is a number or is omitted 2133 and the currently selected newsgroup is invalid, a 412 response MUST 2134 be returned. If the argument is a number and that article does not 2135 exist in the currently selected newsgroup, a 423 response MUST be 2136 returned. If the argument is omitted and the current article number 2137 is invalid, a 420 response MUST be returned. 2139 6.2.1.3. Examples 2141 Example of a successful retrieval of an article (using no article 2142 number): 2144 [C] GROUP misc.test 2145 [S] 211 1234 3000234 3002322 misc.test 2146 [C] ARTICLE 2147 [S] 220 3000234 <45223423@example.com> 2148 [S] Path: pathost!demo!whitehouse!not-for-mail 2149 [S] From: "Demo User" 2150 [S] Newsgroups: misc.test 2151 [S] Subject: I am just a test article 2152 [S] Date: 6 Oct 1998 04:38:40 -0500 2153 [S] Organization: An Example Net, Uncertain, Texas 2154 [S] Message-ID: <411@example.net> 2155 [S] 2156 [S] This is just a test article. 2157 [S] . 2159 Example of a successful retrieval of an article by message-id: 2161 [C] ARTICLE <45223423@example.com> 2162 [S] 220 0 <45223423@example.com> 2163 [S] Path: pathost!demo!whitehouse!not-for-mail 2164 [S] From: "Demo User" 2165 [S] Newsgroups: misc.test 2166 [S] Subject: I am just a test article 2167 [S] Date: 6 Oct 1998 04:38:40 -0500 2168 [S] Organization: An Example Net, Uncertain, Texas 2169 [S] Message-ID: <411@example.net> 2170 [S] 2171 [S] This is just a test article. 2172 [S] . 2174 Example of an unsuccessful retrieval of an article by message-id: 2176 [C] ARTICLE 2177 [S] 430 No Such Article Found 2179 Example of an unsuccessful retrieval of an article by number: 2181 [C] GROUP misc.test 2182 [S] 211 1234 3000234 3002322 news.groups 2183 [C] ARTICLE 300256 2184 [S] 423 No article with that number 2186 Example of an unsuccessful retrieval of an article by number because 2187 no newsgroup was selected first: 2189 [Assumes currently selected newsgroup is invalid.] 2190 [C] ARTICLE 300256 2191 [S] 412 No newsgroup selected 2193 Example of an attempt to retrieve an article when the currently 2194 selected newsgroup is empty: 2196 [C] GROUP example.empty.newsgroup 2197 [S] 211 0 0 0 example.empty.newsgroup 2198 [C] ARTICLE 2199 [S] 420 No current article selected 2201 6.2.2. HEAD 2203 6.2.2.1. Usage 2205 This command is mandatory. 2207 Syntax 2209 HEAD message-id 2210 HEAD number 2211 HEAD 2213 Responses 2215 First form (message-id specified) 2217 221 0|n message-id Headers follow (multi-line) 2218 430 No article with that message-id 2220 Second form (article number specified) 2222 221 n message-id Headers follow (multi-line) 2223 412 No newsgroup selected 2224 423 No article with that number 2226 Third form (current article number used) 2228 221 n message-id Headers follow (multi-line) 2229 412 No newsgroup selected 2230 420 Current article number is invalid 2232 Parameters 2234 number Requested article number 2235 n Returned article number 2236 message-id Article message-id 2238 6.2.2.2. Description 2240 The HEAD command behaves identically to the ARTICLE command except 2241 that, if the article exists, the response code is 221 instead of 220 2242 and only the headers are presented (the empty line separating the 2243 headers and body MUST NOT be included). 2245 6.2.2.3. Examples 2247 Example of a successful retrieval of the headers of an article (using 2248 no article number): 2250 [C] GROUP misc.test 2251 [S] 211 1234 3000234 3002322 misc.test 2252 [C] HEAD 2253 [S] 221 3000234 <45223423@example.com> 2254 [S] Path: pathost!demo!whitehouse!not-for-mail 2255 [S] From: "Demo User" 2256 [S] Newsgroups: misc.test 2257 [S] Subject: I am just a test article 2258 [S] Date: 6 Oct 1998 04:38:40 -0500 2259 [S] Organization: An Example Net, Uncertain, Texas 2260 [S] Message-ID: <411@example.net> 2261 [S] . 2263 Example of a successful retrieval of the headers of an article by 2264 message-id: 2266 [C] HEAD <45223423@example.com> 2267 [S] 221 0 <45223423@example.com> 2269 [S] Path: pathost!demo!whitehouse!not-for-mail 2270 [S] From: "Demo User" 2271 [S] Newsgroups: misc.test 2272 [S] Subject: I am just a test article 2273 [S] Date: 6 Oct 1998 04:38:40 -0500 2274 [S] Organization: An Example Net, Uncertain, Texas 2275 [S] Message-ID: <411@example.net> 2276 [S] . 2278 Example of an unsuccessful retrieval of the headers of an article by 2279 message-id: 2281 [C] HEAD 2282 [S] 430 No Such Article Found 2284 Example of an unsuccessful retrieval of the headers of an article by 2285 number: 2287 [C] GROUP misc.test 2288 [S] 211 1234 3000234 3002322 misc.test 2289 [C] HEAD 300256 2290 [S] 423 No article with that number 2292 Example of an unsuccessful retrieval of the headers of an article by 2293 number because no newsgroup was selected first: 2295 [Assumes currently selected newsgroup is invalid.] 2296 [C] HEAD 300256 2297 [S] 412 No newsgroup selected 2299 Example of an attempt to retrieve the headers of an article when the 2300 currently selected newsgroup is empty: 2302 [C] GROUP example.empty.newsgroup 2303 [S] 211 0 0 0 example.empty.newsgroup 2304 [C] HEAD 2305 [S] 420 No current article selected 2307 6.2.3. BODY 2309 6.2.3.1. Usage 2311 Indicating capability: READER 2312 Syntax 2314 BODY message-id 2315 BODY number 2316 BODY 2318 Responses 2320 First form (message-id specified) 2322 222 0|n message-id Body follows (multi-line) 2323 430 No article with that message-id 2325 Second form (article number specified) 2327 222 n message-id Body follows (multi-line) 2328 412 No newsgroup selected 2329 423 No article with that number 2331 Third form (current article number used) 2333 222 n message-id Body follows (multi-line) 2334 412 No newsgroup selected 2335 420 Current article number is invalid 2337 Parameters 2339 number Requested article number 2340 n Returned article number 2341 message-id Article message-id 2343 6.2.3.2. Description 2345 The BODY command behaves identically to the ARTICLE command except 2346 that, if the article exists, the response code is 222 instead of 220 2347 and only the body is presented (the empty line separating the headers 2348 and body MUST NOT be included). 2350 6.2.3.3. Examples 2352 Example of a successful retrieval of the body of an article (using no 2353 article number): 2355 [C] GROUP misc.test 2356 [S] 211 1234 3000234 3002322 misc.test 2357 [C] BODY 2358 [S] 222 3000234 <45223423@example.com> 2359 [S] This is just a test article. 2361 [S] . 2363 Example of a successful retrieval of the body of an article by 2364 message-id: 2366 [C] BODY <45223423@example.com> 2367 [S] 222 0 <45223423@example.com> 2368 [S] This is just a test article. 2369 [S] . 2371 Example of an unsuccessful retrieval of the body of an article by 2372 message-id: 2374 [C] BODY 2375 [S] 430 No Such Article Found 2377 Example of an unsuccessful retrieval of the body of an article by 2378 number: 2380 [C] GROUP misc.test 2381 [S] 211 1234 3000234 3002322 misc.test 2382 [C] BODY 300256 2383 [S] 423 No article with that number 2385 Example of an unsuccessful retrieval of the body of an article by 2386 number because no newsgroup was selected first: 2388 [Assumes currently selected newsgroup is invalid.] 2389 [C] BODY 300256 2390 [S] 412 No newsgroup selected 2392 Example of an attempt to retrieve the body of an article when the 2393 currently selected newsgroup is empty: 2395 [C] GROUP example.empty.newsgroup 2396 [S] 211 0 0 0 example.empty.newsgroup 2397 [C] BODY 2398 [S] 420 No current article selected 2400 6.2.4. STAT 2402 6.2.4.1. Usage 2404 This command is mandatory. 2406 Syntax 2408 STAT message-id 2409 STAT number 2410 STAT 2412 Responses 2414 First form (message-id specified) 2416 223 0|n message-id Article exists 2417 430 No article with that message-id 2419 Second form (article number specified) 2421 223 n message-id Article exists 2422 412 No newsgroup selected 2423 423 No article with that number 2425 Third form (current article number used) 2427 223 n message-id Article exists 2428 412 No newsgroup selected 2429 420 Current article number is invalid 2431 Parameters 2433 number Requested article number 2434 n Returned article number 2435 message-id Article message-id 2437 6.2.4.2. Description 2439 The STAT command behaves identically to the ARTICLE command except 2440 that, if the article exists, it is NOT presented to the client and 2441 the response code is 223 instead of 220. Note that the response is 2442 NOT multi-line. 2444 This command allows the client to determine whether an article 2445 exists, and in the second and third forms what its message-id is, 2446 without having to process an arbitrary amount of text. 2448 6.2.4.3. Examples 2450 Example of STAT on an existing article (using no article number): 2452 [C] GROUP misc.test 2453 [S] 211 1234 3000234 3002322 misc.test 2455 [C] STAT 2456 [S] 223 3000234 <45223423@example.com> 2458 Example of STAT on an existing article by message-id: 2460 [C] STAT <45223423@example.com> 2461 [S] 223 0 <45223423@example.com> 2463 Example of STAT on an article not on the server by message-id: 2465 [C] STAT 2466 [S] 430 No Such Article Found 2468 Example of STAT on an article not in the server by number: 2470 [C] GROUP misc.test 2471 [S] 211 1234 3000234 3002322 misc.test 2472 [C] STAT 300256 2473 [S] 423 No article with that number 2475 Example of STAT on an article by number when no newsgroup was 2476 selected first: 2478 [Assumes currently selected newsgroup is invalid.] 2479 [C] STAT 300256 2480 [S] 412 No newsgroup selected 2482 Example of STAT on an article when the currently selected newsgroup 2483 is empty: 2485 [C] GROUP example.empty.newsgroup 2486 [S] 211 0 0 0 example.empty.newsgroup 2487 [C] STAT 2488 [S] 420 No current article selected 2490 Example of STAT by message-id on a server which sometimes reports the 2491 actual article number: 2493 [C] GROUP misc.test 2494 [S] 211 1234 3000234 3002322 misc.test 2495 [C] STAT 2496 [S] 223 3000234 <45223423@example.com> 2497 [C] STAT <45223423@example.com> 2498 [S] 223 0 <45223423@example.com> 2499 [C] STAT <45223423@example.com> 2500 [S] 223 3000234 <45223423@example.com> 2501 [C] GROUP example.empty.newsgroup 2502 [S] 211 0 0 0 example.empty.newsgroup 2504 [C] STAT <45223423@example.com> 2505 [S] 223 0 <45223423@example.com> 2506 [C] GROUP alt.crossposts 2507 [S] 211 9999 111111 222222 alt.crossposts 2508 [C] STAT <45223423@example.com> 2509 [S] 223 123456 <45223423@example.com> 2510 [C] STAT 2511 [S] 223 111111 <23894720@example.com> 2513 The first STAT command establishes the identity of an article in the 2514 group. The second and third show that the server may, but need not, 2515 give the article number when the message-id is specified. The fourth 2516 STAT command shows that zero must be specified if the article isn't 2517 in the currently selected newsgroup, the fifth shows that the number, 2518 if provided, must be that relating to the currently selected 2519 newsgroup, and the last one shows that the current article number is 2520 still not changed by the use of STAT with a message-id even if it 2521 returns an article number. 2523 6.3. Article posting 2525 Article posting is done in one of two ways: individual article 2526 posting from news reading clients using POST, and article transfer 2527 from other news servers using IHAVE. 2529 6.3.1. POST 2531 6.3.1.1. Usage 2533 Indicating capability: POST 2535 This command MUST NOT be pipelined. 2537 Syntax 2539 POST 2541 Responses 2543 Initial responses 2545 340 Send article to be posted 2546 440 Posting not permitted 2548 Subsequent responses 2550 240 Article received OK 2551 441 Posting failed 2553 6.3.1.2. Description 2555 If posting is allowed, a 340 response MUST be returned to indicate 2556 that the article to be posted should be sent. If posting is 2557 prohibited for some installation-dependent reason, a 440 response 2558 MUST be returned. 2560 If posting is permitted, the article MUST be in the format specified 2561 in Section 3.6 and MUST be sent by the client to the server as a 2562 multi-line data block (see Section 3.1.1). Thus a single dot (".") 2563 on a line indicates the end of the text, and lines starting with a 2564 dot in the original text have that dot doubled during transmission. 2566 Following the presentation of the termination sequence by the client, 2567 the server MUST return a response indicating success or failure of 2568 the article transfer. Note that response codes 340 and 440 are used 2569 in direct response to the POST command. Others are returned 2570 following the sending of the article. 2572 A response of 240 SHOULD indicate that, barring unforeseen server 2573 errors, the posted article will be made available on the server 2574 and/or transferred to other servers as appropriate, possibly 2575 following further processing. In other words, articles not wanted by 2576 the server SHOULD be rejected with a 441 response and not accepted 2577 and silently discarded. However, the client SHOULD NOT assume that 2578 the article has been successfully transferred unless it receives an 2579 affirmative response from the server, and SHOULD NOT assume that it 2580 is being made available to other clients without explicitly checking 2581 (for example using the STAT command). 2583 If the session is interrupted before the response is received, it is 2584 possible that an affirmative response was sent but has been lost. 2585 Therefore, in any subsequent session, the client SHOULD either check 2586 whether the article was successfully posted before resending or 2587 ensure that the server will allocate the same message-id to the new 2588 attempt (see Appendix A.2) - the latter approach is preferred since 2589 the article might not have been made available for reading yet (for 2590 example, it may have to go through a moderation process). 2592 6.3.1.3. Examples 2594 Example of a successful posting: 2596 [C] POST 2597 [S] 340 Input article; end with . 2598 [C] From: "Demo User" 2599 [C] Newsgroups: misc.test 2600 [C] Subject: I am just a test article 2601 [C] Organization: An Example Net 2602 [C] 2603 [C] This is just a test article. 2604 [C] . 2605 [S] 240 Article received OK 2607 Example of an unsuccessful posting: 2609 [C] POST 2610 [S] 340 Input article; end with . 2611 [C] From: "Demo User" 2612 [C] Newsgroups: misc.test 2613 [C] Subject: I am just a test article 2614 [C] Organization: An Example Net 2615 [C] 2616 [C] This is just a test article. 2617 [C] . 2618 [S] 441 Posting failed 2620 Example of an attempt to post when posting is not allowed: 2622 [Initial connection set-up completed.] 2623 [S] 201 NNTP Service Ready, posting prohibited 2624 [C] POST 2625 [S] 440 Posting not permitted 2627 6.3.2. IHAVE 2629 6.3.2.1. Usage 2631 Indicating capability: IHAVE 2633 This command MUST NOT be pipelined. 2635 Syntax 2637 IHAVE message-id 2639 Responses 2640 Initial responses 2642 335 Send article to be transferred 2643 435 Article not wanted 2644 436 Transfer not possible; try again later 2646 Subsequent responses 2648 235 Article transferred OK 2649 436 Transfer failed; try again later 2650 437 Transfer rejected; do not retry 2652 Parameters 2654 message-id Article message-id 2656 6.3.2.2. Description 2658 The IHAVE command informs the server that the client has an article 2659 with the specified message-id. If the server desires a copy of that 2660 article a 335 response MUST be returned, instructing the client to 2661 send the entire article. If the server does not want the article 2662 (if, for example, the server already has a copy of it), a 435 2663 response MUST be returned, indicating that the article is not wanted. 2664 Finally, if the article isn't wanted immediately but the client 2665 should retry later if possible (if, for example, another client is in 2666 the process of sending the same article to the server), a 436 2667 response MUST be returned. 2669 If transmission of the article is requested, the client MUST send the 2670 entire article, including headers and body, to the server as a multi- 2671 line data block (see Section 3.1.1). Thus a single dot (".") on a 2672 line indicates the end of the text, and lines starting with a dot in 2673 the original text have that dot doubled during transmission. The 2674 server MUST return either a 235 response, indicating that the article 2675 was successfully transferred, a 436 response, indicating that the 2676 transfer failed but should be tried again later, or a 437 response, 2677 indicating that the article was rejected. 2679 This function differs from the POST command in that it is intended 2680 for use in transferring already-posted articles between hosts. It 2681 SHOULD NOT be used when the client is a personal news reading 2682 program, since use of this command indicates that the article has 2683 already been posted at another site and is simply being forwarded 2684 from another host. However, despite this, the server MAY elect not 2685 to post or forward the article if, after further examination of the 2686 article, it deems it inappropriate to do so. Reasons for such 2687 subsequent rejection of an article may include such problems as 2688 inappropriate newsgroups or distributions, disc space limitations, 2689 article lengths, garbled headers, and the like. These are typically 2690 restrictions enforced by the server host's news software and not 2691 necessarily the NNTP server itself. 2693 The client SHOULD NOT assume that the article has been successfully 2694 transferred unless it receives an affirmative response from the 2695 server. A lack of response (such as a dropped network connection or 2696 a network timeout) SHOULD be treated the same as a 436 response. 2698 Because some news server software may not be able immediately to 2699 determine whether or not an article is suitable for posting or 2700 forwarding, an NNTP server MAY acknowledge the successful transfer of 2701 the article (with a 235 response) but later silently discard it. 2703 6.3.2.3. Examples 2705 Example of successfully sending an article to another site: 2707 [C] IHAVE 2708 [S] 335 Send it; end with . 2709 [C] Path: pathost!demo!somewhere!not-for-mail 2710 [C] From: "Demo User" 2711 [C] Newsgroups: misc.test 2712 [C] Subject: I am just a test article 2713 [C] Date: 6 Oct 1998 04:38:40 -0500 2714 [C] Organization: An Example Com, San Jose, CA 2715 [C] Message-ID: 2716 [C] 2717 [C] This is just a test article. 2718 [C] . 2719 [S] 235 Article transferred OK 2721 Example of sending an article to another site that rejects it. Note 2722 that the message-id in the IHAVE command is not the same as the one 2723 in the article headers; while this is bad practice and SHOULD NOT be 2724 done, it is not forbidden. 2726 [C] IHAVE 2727 [S] 335 Send it; end with . 2728 [C] Path: pathost!demo!somewhere!not-for-mail 2729 [C] From: "Demo User" 2730 [C] Newsgroups: misc.test 2731 [C] Subject: I am just a test article 2732 [C] Date: 6 Oct 1998 04:38:40 -0500 2733 [C] Organization: An Example Com, San Jose, CA 2734 [C] Message-ID: 2735 [C] 2737 [C] This is just a test article. 2738 [C] . 2739 [S] 437 Article rejected; don't send again 2741 Example of sending an article to another site where the transfer 2742 fails: 2744 [C] IHAVE 2745 [S] 335 Send it; end with . 2746 [C] Path: pathost!demo!somewhere!not-for-mail 2747 [C] From: "Demo User" 2748 [C] Newsgroups: misc.test 2749 [C] Subject: I am just a test article 2750 [C] Date: 6 Oct 1998 04:38:40 -0500 2751 [C] Organization: An Example Com, San Jose, CA 2752 [C] Message-ID: 2753 [C] 2754 [C] This is just a test article. 2755 [C] . 2756 [S] 436 Transfer failed 2758 Example of sending an article to a site that already has it: 2760 [C] IHAVE 2761 [S] 435 Duplicate 2763 Example of sending an article to a site that requests the article be 2764 tried again later: 2766 [C] IHAVE 2767 [S] 436 Retry later 2769 7. Information commands 2771 This section lists other commands that may be used at any time 2772 between the beginning of a session and its termination. Using these 2773 commands does not alter any state information, but the response 2774 generated from their use may provide useful information to clients. 2776 7.1. DATE 2778 7.1.1. Usage 2780 Indicating capability: READER 2782 Syntax 2784 DATE 2786 Responses 2788 111 yyyymmddhhmmss server date and time 2790 Parameters 2792 yyyymmddHHmmss Current UTC date and time on server 2794 7.1.2. Description 2796 This command exists to help clients find out the current Coordinated 2797 Universal Time [TF.686-1] from the server's perspective. This 2798 command SHOULD NOT be used as a substitute for NTP [RFC1305] but to 2799 provide information that might be useful when using the NEWNEWS 2800 command (see Section 7.4). 2802 The DATE command MUST return a timestamp from the same clock as is 2803 used for determining article arrival and group creation times (see 2804 Section 6). This clock SHOULD be monotonic, and adjustments SHOULD 2805 be made by running it fast or slow compared to "real" time rather 2806 than by making sudden jumps. A system providing NNTP service SHOULD 2807 keep the system clock as accurate as possible, either with NTP or by 2808 some other method. 2810 The server MUST return a 111 response specifying the date and time on 2811 the server in the form yyyymmddhhmmss. This date and time is in 2812 Coordinated Universal Time. 2814 7.1.3. Examples 2816 [C] DATE 2817 [S] 111 19990623135624 2819 7.2. HELP 2821 7.2.1. Usage 2823 This command is mandatory. 2825 Syntax 2827 HELP 2829 Responses 2831 100 Help text follows (multi-line) 2833 7.2.2. Description 2835 This command provides a short summary of the commands that are 2836 understood by this implementation of the server. The help text will 2837 be presented as a multi-line data block following the 100 response 2838 code. 2840 This text is not guaranteed to be in any particular format (but must 2841 be UTF-8) and MUST NOT be used by clients as a replacement for the 2842 CAPABILITIES command described in Section 5.2. 2844 7.2.3. Examples 2846 [C] HELP 2847 [S] 100 Help text follows 2848 [S] This is some help text. There is no specific 2849 [S] formatting requirement for this test, though 2850 [S] it is customary for it to list the valid commands 2851 [S] and give a brief definition of what they do 2852 [S] . 2854 7.3. NEWGROUPS 2856 7.3.1. Usage 2858 Indicating capability: READER 2859 Syntax 2861 NEWGROUPS date time [GMT] 2863 Responses 2865 231 List of new newsgroups follows (multi-line) 2867 Parameters 2869 date Date in yymmdd or yyyymmdd format 2870 time Time in hhmmss format 2872 7.3.2. Description 2874 This command returns a list of newsgroups created on the server since 2875 the specified date and time. The results are in the same format as 2876 the LIST ACTIVE command (see Section 7.6.3). However, they MAY 2877 include groups not available on the server (and so not returned by 2878 LIST ACTIVE) and MAY omit groups for which the creation date is not 2879 available. 2881 The date is specified as 6 or 8 digits in the format [xx]yymmdd, 2882 where xx is the first two digits of the year (19-99), yy is the last 2883 two digits of the year (00-99), mm is the month (01-12), and dd is 2884 the day of the month (01-31). Clients SHOULD specify all four digits 2885 of the year. If the first two digits of the year are not specified 2886 (this is supported only for backwards compatibility), the year is to 2887 be taken from the current century if yy is smaller than or equal to 2888 the current year, otherwise the year is from the previous century. 2890 The time is specified as 6 digits in the format hhmmss, where hh is 2891 the hours in the 24-hour clock (00-23), mm is the minutes (00-59), 2892 and ss is the seconds (00-60, to allow for leap seconds). The token 2893 "GMT" specifies that the date and time are given in Coordinated 2894 Universal Time [TF.686-1]; if it is omitted then the date and time 2895 are specified in the server's local timezone. Note that there is no 2896 way using the protocol specified in this document to establish the 2897 server's local timezone. 2899 Note that an empty list is a possible valid response and indicates 2900 that there are no new newsgroups since that date-time. 2902 Clients SHOULD make all queries using Coordinated Universal Time 2903 (i.e. by including the "GMT" argument) when possible. 2905 7.3.3. Examples 2907 Example where there are new groups: 2909 [C] NEWGROUPS 19990624 000000 GMT 2910 [S] 231 list of new newsgroups follows 2911 [S] alt.rfc-writers.recovery 4 1 y 2912 [S] tx.natives.recovery 89 56 y 2913 [S] . 2915 Example where there are no new groups: 2917 [C] NEWGROUPS 19990624 000000 GMT 2918 [S] 231 list of new newsgroups follows 2919 [S] . 2921 7.4. NEWNEWS 2923 7.4.1. Usage 2925 Indicating capability: NEWNEWS 2927 Syntax 2929 NEWNEWS wildmat date time [GMT] 2931 Responses 2933 230 List of new articles follows (multi-line) 2935 Parameters 2937 wildmat Newsgroups of interest 2938 date Date in yymmdd or yyyymmdd format 2939 time Time in hhmmss format 2941 7.4.2. Description 2943 This command returns a list of message-ids of articles posted or 2944 received on the server, in the newsgroups whose names match the 2945 wildmat, since the specified date and time. One message-id is sent 2946 on each line; the order of the response has no specific significance 2947 and may vary from response to response in the same session. A 2948 message-id MAY appear more than once; if it does so, it has the same 2949 meaning as if it appeared only once. 2951 Date and time are in the same format as the NEWGROUPS command (see 2952 Section 7.3). 2954 Note that an empty list is a possible valid response and indicates 2955 that there is currently no new news in the relevant groups. 2957 Clients SHOULD make all queries in Coordinated Universal Time (i.e. 2958 by using the "GMT" argument) when possible. 2960 7.4.3. Examples 2962 Example where there are new articles: 2964 [C] NEWNEWS news.*,sci.* 19990624 000000 GMT 2965 [S] 230 list of new articles by message-id follows 2966 [S] 2967 [S] 2968 [S] . 2970 Example where there are no new articles: 2972 [C] NEWNEWS alt.* 19990624 000000 GMT 2973 [S] 230 list of new articles by message-id follows 2974 [S] . 2976 7.5. Time 2978 As described in Section 6, each article has an arrival timestamp. 2979 Each newsgroup also has a creation timestamp. These timestamps are 2980 used by the NEWNEWS and NEWGROUP commands to construct their 2981 responses. 2983 Clients can ensure that they do not have gaps in lists of articles or 2984 groups by using the DATE command in the following manner: 2986 First session: 2987 Issue DATE command and record result 2988 Issue NEWNEWS command using a previously chosen timestamp 2990 Subsequent sessions: 2991 Issue DATE command and hold result in temporary storage 2992 Issue NEWNEWS command using timestamp saved from previous session 2993 Overwrite saved timestamp with that currently in temporary storage 2995 In order to allow for minor errors, clients MAY want to adjust the 2996 timestamp back by two or three minutes before using it in NEWNEWS. 2998 7.5.1. Examples 3000 First session: 3002 [C] DATE 3003 [S] 111 20010203112233 3004 [C] NEWNEWS local.chat 20001231 235959 GMT 3005 [S] 230 list follows 3006 [S] 3007 [S] 3008 [S] 3009 [S] . 3011 Second session (the client has subtracted 3 minutes from the 3012 timestamp returned previously): 3014 [C] DATE 3015 [S] 111 20010204003344 3016 [C] NEWNEWS local.chat 20010203 111933 GMT 3017 [S] 230 list follows 3018 [S] 3019 [S] 3020 [S] 3021 [S] . 3023 Note how arrived in the 3 minute gap and so 3024 is listed in both responses. 3026 7.6. The LIST commands 3028 The LIST family of commands all return information that is multi-line 3029 and, in general, can be expected not to change during the session. 3030 Often the information is related to newsgroups, in which case the 3031 response has one line per newsgroup and a wildmat MAY be provided to 3032 restrict the groups for which information is returned. 3034 The set of available keywords (including those provided by 3035 extensions) is given in the capability list with capability label 3036 LIST. 3038 7.6.1. LIST 3040 7.6.1.1. Usage 3042 Indicating capability: LIST 3043 Syntax 3045 LIST [keyword [wildmat|argument]] 3047 Responses 3049 215 Information follows (multi-line) 3051 Parameters 3053 keyword information requested [1] 3054 argument specific to keyword 3055 wildmat groups of interest 3057 [1] If no keyword is provided, it defaults to ACTIVE. 3059 7.6.1.2. Description 3061 The LIST command allows the server to provide blocks of information 3062 to the client. This information may be global or may be related to 3063 newsgroups; in the latter case, the information may be returned 3064 either for all groups or only for those matching a wildmat. Each 3065 block of information is represented by a different keyword. The 3066 command returns the specific information identified by the keyword. 3068 If the information is available, it is returned as a multi-line data 3069 block following the 215 response code. The format of the information 3070 depends on the keyword. The information MAY be affected by the 3071 additional argument, but the format MUST NOT be. 3073 If the information is based on newsgroups and the optional wildmat 3074 argument is specified, the response is limited to only the groups (if 3075 any) whose names match the wildmat and for which the information is 3076 available. 3078 Note that an empty list is a possible valid response; for a 3079 newsgroup-based keyword, it indicates that there are no groups 3080 meeting the above criteria. 3082 If the keyword is not recognised, or if an argument is specified and 3083 the keyword does not expect one, a 501 response code MUST BE 3084 returned. If the keyword is recognised but the server does not 3085 maintain the information, a 503 response code MUST BE returned. 3087 The LIST command MUST NOT change the visible state of the server in 3088 any way; that is, the behaviour of subsequent commands MUST NOT be 3089 affected by whether the LIST command was issued or not. For example, 3090 it MUST NOT make groups available that otherwise would not have been. 3092 7.6.1.3. Examples 3094 Example of LIST with the ACTIVE keyword: 3096 [C] LIST ACTIVE 3097 [S] 215 list of newsgroups follows 3098 [S] misc.test 3002322 3000234 y 3099 [S] comp.risks 442001 441099 m 3100 [S] alt.rfc-writers.recovery 4 1 y 3101 [S] tx.natives.recovery 89 56 y 3102 [S] tx.natives.recovery.d 11 9 n 3103 [S] . 3105 Example of LIST with no keyword: 3107 [C] LIST 3108 [S] 215 list of newsgroups follows 3109 [S] misc.test 3002322 3000234 y 3110 [S] comp.risks 442001 441099 m 3111 [S] alt.rfc-writers.recovery 4 1 y 3112 [S] tx.natives.recovery 89 56 y 3113 [S] tx.natives.recovery.d 11 9 n 3114 [S] . 3116 The output is identical to that of the previous example. 3118 Example of LIST on a newsgroup-based keyword with and without 3119 wildmat: 3121 [C] LIST ACTIVE.TIMES 3122 [S] 215 information follows 3123 [S] misc.test 930445408 3124 [S] alt.rfc-writers.recovery 930562309 3125 [S] tx.natives.recovery 930678923 3126 [S] . 3127 [C] LIST ACTIVE.TIMES tx.* 3128 [S] 215 information follows 3129 [S] tx.natives.recovery 930678923 3130 [S] . 3132 Example of LIST returning an error where the keyword is recognized 3133 but the software does not maintain this information: 3135 [C] CAPABILITIES 3136 [S] 101 Capability list: 3137 [S] VERSION 2 3138 [S] READER 3139 [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA 3141 [S] . 3142 [C] LIST XTRA.DATA 3143 [S] 503 Data item not stored 3145 Example of LIST where the keyword is not recognised: 3147 [C] CAPABILITIES 3148 [S] 101 Capability list: 3149 [S] VERSION 2 3150 [S] READER 3151 [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA 3152 [S] . 3153 [C] LIST DISTRIB.PATS 3154 [S] 501 Syntax Error 3156 7.6.2. Standard LIST keywords 3158 This specification defines the following LIST keywords: 3160 +----------------------+----------------------+---------------------+ 3161 | Keyword | Definition | Status | 3162 +----------------------+----------------------+---------------------+ 3163 | ACTIVE | Section 7.6.3 | Mandatory if the | 3164 | | | READER capability | 3165 | | | is advertised | 3166 | | | | 3167 | ACTIVE.TIMES | Section 7.6.4 | Optional | 3168 | | | | 3169 | DISTRIB.PATS | Section 7.6.5 | Optional | 3170 | | | | 3171 | HEADERS | Section 8.6 | Mandatory if the | 3172 | | | HDR capability is | 3173 | | | advertised | 3174 | | | | 3175 | NEWSGROUPS | Section 7.6.6 | Mandatory if the | 3176 | | | READER capability | 3177 | | | is advertised | 3178 | | | | 3179 | OVERVIEW.FMT | Section 8.4 | Mandatory if the | 3180 | | | OVER capability is | 3181 | | | advertised | 3182 +----------------------+----------------------+---------------------+ 3184 Where one of these LIST keywords is supported by a server, it MUST 3185 have the meaning given in the following sub-sections. 3187 7.6.3. LIST ACTIVE 3189 This keyword MUST be supported by servers advertising the READER 3190 capability. 3192 LIST ACTIVE returns a list of valid newsgroups and associated 3193 information. If no wildmat is specified, the server MUST include 3194 every group that the client is permitted to select with the GROUP 3195 (Section 6.1.1) command. Each line of this list consists of four 3196 fields separated from each other by one or more spaces: 3197 o the name of the newsgroup; 3198 o the reported high water mark for the group; 3199 o the reported low water mark for the group; 3200 o the current status of the group on this server. 3202 The reported high and low water marks are as described in the GROUP 3203 command (see Section 6.1.1). 3205 The status field is typically one of: 3207 "y" posting is permitted 3209 "n" posting is not permitted 3211 "m" postings will be forwarded to the newsgroup moderator 3213 The server SHOULD use these values when these meanings are required 3214 and MUST NOT use them with any other meaning. Other values for the 3215 status may exist; the definition of these other values and the 3216 circumstances under which they are returned may be specified in an 3217 extension or may be private to the server. A client SHOULD treat an 3218 unrecognized status as giving no information. 3220 The status of a newsgroup only indicates how posts to that newsgroup 3221 are normally processed and is not necessarily customised to the 3222 specific client. For example, if the current client is forbidden 3223 from posting, then this will apply equally to groups with status "y". 3224 Conversely, a client with special privileges (not defined by this 3225 specification) might be able to post to a group with status "n". 3227 For example: 3229 [C] LIST ACTIVE 3230 [S] 215 list of newsgroups follows 3231 [S] misc.test 3002322 3000234 y 3232 [S] comp.risks 442001 441099 m 3233 [S] alt.rfc-writers.recovery 4 1 y 3234 [S] tx.natives.recovery 89 56 y 3236 [S] tx.natives.recovery.d 11 9 n 3237 [S] . 3239 or, on an implementation that includes leading zeroes: 3241 [C] LIST ACTIVE 3242 [S] 215 list of newsgroups follows 3243 [S] misc.test 0003002322 0003000234 y 3244 [S] comp.risks 0000442001 0000441099 m 3245 [S] alt.rfc-writers.recovery 0000000004 0000000001 y 3246 [S] tx.natives.recovery 0000000089 0000000056 y 3247 [S] tx.natives.recovery.d 0000000011 0000000009 n 3248 [S] . 3250 The information is newsgroup-based and a wildmat MAY be specified, in 3251 which case the response is limited to only the groups (if any) whose 3252 names match the wildmat. For example: 3254 [C] LIST ACTIVE *.recovery 3255 [S] 215 list of newsgroups follows 3256 [S] alt.rfc-writers.recovery 4 1 y 3257 [S] tx.natives.recovery 89 56 y 3258 [S] . 3260 7.6.4. LIST ACTIVE.TIMES 3262 This keyword is optional. 3264 The active.times list is maintained by some NNTP servers to contain 3265 information about who created a particular newsgroup and when. Each 3266 line of this list consists of three fields separated from each other 3267 by one or more spaces. The first field is the name of the newsgroup. 3268 The second is the time when this group was created on this news 3269 server, measured in seconds since the start of January 1, 1970. The 3270 third is plain text intended to describe the entity that created the 3271 newsgroup; it is often a mailbox as defined in RFC 2822 [RFC2822]. 3272 For example: 3274 [C] LIST ACTIVE.TIMES 3275 [S] 215 information follows 3276 [S] misc.test 930445408 3277 [S] alt.rfc-writers.recovery 930562309 3278 [S] tx.natives.recovery 930678923 3279 [S] . 3281 The list MAY omit newsgroups for which the information is unavailable 3282 and MAY include groups not available on the server; in particular, it 3283 MAY omit all groups created before the date and time of the oldest 3284 entry. The client MUST NOT assume that the list is complete or that 3285 it matches the list returned by the LIST ACTIVE (Section 7.6.3) 3286 command. The NEWGROUPS command (Section 7.3) may provide a better 3287 way to access this information, and the results of the two commands 3288 SHOULD be consistent except that, if the latter is invoked with a 3289 date and time earlier than the oldest entry in active.times list, its 3290 result may include extra groups. 3292 The information is newsgroup-based and a wildmat MAY be specified, in 3293 which case the response is limited to only the groups (if any) whose 3294 names match the wildmat. 3296 7.6.5. LIST DISTRIB.PATS 3298 This keyword is optional. 3300 The distrib.pats list is maintained by some NNTP servers to assist 3301 clients to choose a value for the content of the Distribution header 3302 of a news article being posted. Each line of this list consists of 3303 three fields separated from each other by a colon (":"). The first 3304 field is a weight, the second field is a wildmat (which may be a 3305 simple newsgroup name), and the third field is a value for the 3306 Distribution header content. For example: 3308 [C] LIST DISTRIB.PATS 3309 [S] 215 information follows 3310 [S] 10:local.*:local 3311 [S] 5:*:world 3312 [S] 20:local.here.*:thissite 3313 [S] . 3315 The client MAY use this information to construct an appropriate 3316 Distribution header given the name of a newsgroup. To do so, it 3317 should determine the lines whose second field matches the newsgroup 3318 name, select from among them the line with the highest weight (with 0 3319 being the lowest), and use the value of the third field to construct 3320 the Distribution header. 3322 The information is not newsgroup-based and an argument MUST NOT be 3323 specified. 3325 7.6.6. LIST NEWSGROUPS 3327 This keyword MUST be supported by servers advertising the READER 3328 capability. 3330 The newsgroups list is maintained by NNTP servers to contain the name 3331 of each newsgroup that is available on the server and a short 3332 description about the purpose of the group. Each line of this list 3333 consists of two fields separated from each other by one or more space 3334 or TAB characters (the usual practice is a single TAB). The first 3335 field is the name of the newsgroup and the second is a short 3336 description of the group. For example: 3338 [C] LIST NEWSGROUPS 3339 [S] 215 information follows 3340 [S] misc.test General Usenet testing 3341 [S] alt.rfc-writers.recovery RFC Writers Recovery 3342 [S] tx.natives.recovery Texas Natives Recovery 3343 [S] . 3345 The list MAY omit newsgroups for which the information is unavailable 3346 and MAY include groups not available on the server. The client MUST 3347 NOT assume that the list is complete or that it matches the list 3348 returned by LIST ACTIVE. 3350 The description SHOULD be in UTF-8. However, servers often obtain 3351 the information from external sources. These sources may have used 3352 different encodings (ones that use octets in the range 128 to 255 in 3353 some other manner) and, in this case, the server MAY pass it on 3354 unchanged; therefore clients MUST be prepared to receive such 3355 descriptions. 3357 The information is newsgroup-based and a wildmat MAY be specified, in 3358 which case the response is limited to only the groups (if any) whose 3359 names match the wildmat. 3361 8. Article field access commands 3363 This section lists commands that may be used to access specific 3364 article fields; that is, headers of articles and metadata about 3365 articles. These commands typically fetch data from an "overview 3366 database", which is a database of headers extracted from incoming 3367 articles plus metadata determined as the article arrives. Only 3368 certain fields are included in the database. 3370 This section is based on the Overview/NOV database [ROBE1995] 3371 developed by Geoff Collyer. 3373 8.1. Article metadata 3375 Article "metadata" is data about articles that does not occur within 3376 the article itself. Each metadata item has a name which MUST begin 3377 with a colon (and which MUST NOT contain a colon elsewhere within 3378 it). As with header names, metadata item names are not case- 3379 sensitive. 3381 When generating a metadata item, the server MUST compute it for 3382 itself and MUST NOT trust any related value provided in the article. 3383 (In particular, a Lines or Bytes header in the article MUST NOT be 3384 assumed to specify the correct number of lines or bytes in the 3385 article.) If the server has access to several non-identical copies 3386 of an article, the value returned MUST be correct for any copy of 3387 that article retrieved during the same session. 3389 This specification defines two metadata items: ":bytes" and ":lines". 3390 Other metadata items may be defined by extensions. The names of 3391 metadata items defined by registered extensions MUST NOT begin with 3392 ":x-". To avoid the risk of a clash with a future registered 3393 extension, the names of metadata items defined by private extensions 3394 SHOULD begin with ":x-". 3396 8.1.1. The :bytes metadata item 3398 The :bytes metadata item for an article is a decimal integer. It 3399 SHOULD equal the number of octets in the entire article - headers, 3400 body, and separating empty line (counting a CRLF pair as two octets, 3401 and excluding both the "." CRLF terminating the response and any "." 3402 added for "dot-stuffing" purposes). 3404 Note to client implementers: some existing servers return a value 3405 different to that above. The commonest reasons for this are: 3406 o counting a CRLF pair as one octet; 3407 o including the "." character used for dot-stuffing in the number; 3408 o including the terminating "." CRLF in the number; 3409 o using one copy of an article for counting the octets but then 3410 returning another one that differs in some (permitted) manner. 3411 Implementations should be prepared for such variation and MUST NOT 3412 rely on the value being accurate. 3414 8.1.2. The :lines metadata item 3416 The :lines metadata item for an article is a decimal integer. It 3417 MUST equal the number of lines in the article body (excluding the 3418 empty line separating headers and body); equivalently, it is two less 3419 than the number of CRLF pairs that the BODY command would return for 3420 that article (the extra two are those following the response code and 3421 the termination octet). 3423 8.2. Database consistency 3425 The information stored in the overview database may change over time. 3426 If the database records the content or absence of a given field (that 3427 is, a header or metadata item) for all articles, it is said to be 3428 "consistent" for that field. If it records the content of a header 3429 for some articles but not for others that nevertheless included that 3430 header, or records a metadata item for some articles but not others 3431 to which that item applies, it is said to be "inconsistent" for that 3432 field. 3434 The LIST OVERVIEW.FMT command SHOULD list all the fields for which 3435 the database is consistent at that moment. It MAY omit such fields 3436 (for example if it is not known whether the database is consistent or 3437 inconsistent). It MUST NOT include fields for which the database is 3438 inconsistent or which are not stored in the database. Therefore if a 3439 header appears in the LIST OVERVIEW.FMT output but not the OVER 3440 output for a given article, that header does not appear in the 3441 article, and similarly for metadata items. 3443 These rules assume the fields being stored in the database remain 3444 constant for long periods of time, with the database therefore being 3445 consistent. When the set of fields to be stored is changed, it will 3446 be inconsistent until either the database is rebuilt or the only 3447 articles remaining are those received since the change. Therefore 3448 the output from LIST OVERVIEW.FMT needs to be altered twice: before 3449 any fields stop being stored, they MUST be removed from the output, 3450 then when the database is once more known to be consistent, the new 3451 fields SHOULD be added to the output. 3453 If the HDR command uses the overview database rather than taking 3454 information directly from the articles, the same issues of 3455 consistency and inconsistency apply and the and the LIST HEADERS 3456 command SHOULD take the same approach as the LIST OVERVIEW.FMT 3457 command in resolving them. 3459 8.3. OVER 3461 8.3.1. Usage 3463 Indicating capability: OVER 3465 Syntax 3467 OVER message-id 3468 OVER range 3469 OVER 3471 Responses 3473 First form (message-id specified) 3475 224 Overview information follows (multi-line) 3476 430 No article with that message-id 3478 Second form (range specified) 3480 224 Overview information follows (multi-line) 3481 412 No newsgroup selected 3482 423 No articles in that range 3484 Third form (current article number used) 3486 224 Overview information follows (multi-line) 3487 412 No newsgroup selected 3488 420 Current article number is invalid 3490 Parameters 3492 range number(s) of articles 3493 message-id message-id of article 3495 8.3.2. Description 3497 The OVER command returns the contents of all the fields in the 3498 database for an article specified by message-id, or from a specified 3499 article or range of articles in the currently selected newsgroup. 3501 The message-id argument indicates a specific article. The range 3502 argument may be any of the following: 3504 o an article number 3505 o an article number followed by a dash to indicate all following 3506 o an article number followed by a dash followed by another article 3507 number 3508 If neither is specified, the current article number is used. 3510 Support for the first (message-id) form is optional. If is is 3511 supported, the OVER capability line MUST include the argument 3512 "MSGID". Otherwise, the capability line MUST NOT include this 3513 argument, and the OVER command MUST return the the generic response 3514 code 503 when this form is used. 3516 If the information is available, it is returned as a multi-line data 3517 block following the 224 response code and contains one line per 3518 article, sorted in numerical order of article number (note that 3519 unless the argument is a range including a dash, there will be 3520 exactly one line in the data block). Each line consists of a number 3521 of fields separated by a TAB. A field may be empty (in which case 3522 there will be two adjacent TABs), and a sequence of trailing TABs may 3523 be omitted. 3525 The first 8 fields MUST be the following, in order: 3527 "0" or article number (see below) 3528 Subject header content 3529 From header content 3530 Date header content 3531 Message-ID header content 3532 References header content 3533 :bytes metadata item 3534 :lines metadata item 3536 If the article is specified by message-id (the first form of the 3537 command), the article number MUST be replaced with zero, except that 3538 if there is a currently selected newsgroup and the article is present 3539 in that group, the server MAY use that article number (see the 3540 ARTICLE command (Section 6.2.1) and STAT examples (Section 6.2.4.3) 3541 for more details). In the other two forms of the command, the 3542 article number MUST be returned. 3544 Any subsequent fields are the contents of the other headers and 3545 metadata held in the database. 3547 For the five mandatory headers, the content of each field MUST be 3548 based on the content of the header (that is, with the header name and 3549 following colon and space removed). If the article does not contain 3550 that header, or if the content is empty, the field MUST be empty. 3551 For the two mandatory metadata items, the content of the field MUST 3552 be just the value, with no other text. 3554 For all subsequent fields that contain headers, the content MUST be 3555 the entire header line other than the trailing CRLF. For all 3556 subsequent fields that contain metadata, the field consists of the 3557 metadata name, a single space, and then the value. 3559 For all fields, the value is processed by first removing all CRLF 3560 pairs (that is, undoing any folding and removing the terminating 3561 CRLF) and then replacing each TAB with a single space. If there is 3562 no such header in the article, or no such metadata item, or no header 3563 or item stored in the database for that article, the corresponding 3564 field MUST be empty. 3566 Note that, after unfolding, the characters NUL, LF, and CR cannot 3567 occur in the header of an article offered by a conformant server. 3568 Nevertheless, servers SHOULD check for these characters and replace 3569 each one by a single space (so that, for example, CR LF LF TAB will 3570 become two spaces, since the CR and first LF will be removed by the 3571 unfolding process). This will encourage robustness in the face of 3572 non-conforming data; it is also possible that future versions of this 3573 specification could permit these characters to appear in articles. 3575 The server SHOULD NOT produce output for articles that no longer 3576 exist. 3578 If the argument is a message-id and no such article exists, a 430 3579 response MUST be returned. If the argument is a range or is omitted 3580 and the currently selected newsgroup is invalid, a 412 response MUST 3581 be returned. If the argument is a range and no articles in that 3582 number range exist in the currently selected newsgroup, including the 3583 case where the second number is less than the first one, a 423 3584 response MUST be returned. If the argument is omitted and the 3585 current article number is invalid, a 420 response MUST be returned. 3587 8.3.3. Examples 3589 In the first three examples, TAB has been replaced by vertical bar 3590 and some lines have been folded for readability. 3592 Example of a successful retrieval of overview information for an 3593 article (using no article number): 3595 [C] GROUP misc.test 3596 [S] 211 1234 3000234 3002322 misc.test 3597 [C] OVER 3598 [S] 224 Overview information follows 3599 [S] 300234|I am just a test article|"Demo User" 3600 |6 Oct 1998 04:38:40 -0500| 3601 <45223423@example.com>|<45454@example.net>|1234| 3602 17|Xref: news.example.com misc.test:3000363 3603 [S] . 3605 Example of a successful retrieval of overview information for an 3606 article by message-id: 3608 [C] CAPABILITIES 3609 [S] 101 Capability list: 3610 [S] VERSION 2 3611 [S] READER 3612 [S] OVER MSGID 3613 [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT 3614 [S] . 3615 [C] OVER <45223423@example.com> 3616 [S] 224 Overview information follows 3617 [S] 0|I am just a test article|"Demo User" 3618 |6 Oct 1998 04:38:40 -0500| 3619 <45223423@example.com>|<45454@example.net>|1234| 3620 17|Xref: news.example.com misc.test:3000363 3621 [S] . 3623 Note that the article number has been replaced by "0". 3625 Example of the same commands on a system that does not implement 3626 retrieval by message-id: 3628 [C] CAPABILITIES 3629 [S] 101 Capability list: 3630 [S] VERSION 2 3631 [S] READER 3632 [S] OVER 3633 [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT 3634 [S] . 3635 [C] OVER <45223423@example.com> 3636 [S] 503 Overview by message-id unsupported 3638 Example of a successful retrieval of overview information for a range 3639 of articles: 3641 [C] GROUP misc.test 3642 [S] 211 1234 3000234 3002322 misc.test 3643 [C] OVER 3000234-3000240 3644 [S] 224 Overview information follows 3645 [S] 300234|I am just a test article|"Demo User" 3646 |6 Oct 1998 04:38:40 -0500| 3647 <45223423@example.com>|<45454@example.net>|1234| 3648 17|Xref: news.example.com misc.test:3000363 3649 [S] 3000235|Another test article|nobody@nowhere.to 3650 (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>|| 3651 4818|37||Distribution: fi 3652 [S] 3000238|Re: I am just a test article|somebody@elsewhere.to| 3653 7 Oct 1998 11:38:40 +1200|| 3654 <45223423@to.to>|9234|51 3655 [S] . 3657 Note the missing "References" and Xref headers in the second line, 3658 the missing trailing field(s) in the first and last lines, and that 3659 there are only results for those articles that still exist. 3661 Example of an unsuccessful retrieval of overview information on an 3662 article by number: 3664 [C] GROUP misc.test 3665 [S] 211 1234 3000234 3002322 misc.test 3666 [C] OVER 300256 3667 [S] 423 No such article in this group 3669 Example of an invalid range: 3671 [C] GROUP misc.test 3672 [S] 211 1234 3000234 3002322 misc.test 3673 [C] OVER 3000444-3000222 3674 [S] 423 Empty range 3676 Example of an unsuccessful retrieval of overview information by 3677 number because no newsgroup was selected first: 3679 [Assumes currently selected newsgroup is invalid.] 3680 [C] OVER 3681 [S] 412 No newsgroup selected 3683 Example of an attempt to retrieve information when the currently 3684 selected newsgroup is empty: 3686 [C] GROUP example.empty.newsgroup 3687 [S] 211 0 0 0 example.empty.newsgroup 3688 [C] OVER 3689 [S] 420 No current article selected 3691 8.4. LIST OVERVIEW.FMT 3693 8.4.1. Usage 3694 Indicating capability: OVER 3696 Syntax 3698 LIST OVERVIEW.FMT 3700 Responses 3702 215 Information follows (multi-line) 3704 8.4.2. Description 3706 See Section 7.6.1 for general requirements of the LIST command. 3708 The LIST OVERVIEW.FMT command returns a description of the fields in 3709 the database for which it is consistent (as described above). The 3710 information is returned as a multi-line data block following the 215 3711 response code. The information contains one line per field in the 3712 order they are returned by the OVER command; the first 7 lines MUST 3713 (except for the case of letters) be exactly: 3715 Subject: 3716 From: 3717 Date: 3718 Message-ID: 3719 References: 3720 :bytes 3721 :lines 3723 except that, for compatibility with existing implementations, the 3724 last two lines MAY instead be: 3726 Bytes: 3727 Lines: 3729 even though they refer to metadata, not headers. 3731 All subsequent lines MUST consist of either a header name followed by 3732 ":full", or the name of a piece of metadata. 3734 There are no leading or trailing spaces in the output. 3736 Note that the 7 fixed lines describe the 2nd to 8th fields of the 3737 OVER output. The "full" suffix (which may use either uppercase, 3738 lowercase, or a mix) is a reminder that the corresponding fields 3739 include the header name. 3741 This command MAY generate different results if used more than once in 3742 a session. 3744 8.4.3. Examples 3746 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3747 output above, using the preferred format: 3749 [C] LIST OVERVIEW.FMT 3750 [S] 215 Order of fields in overview database. 3751 [S] Subject: 3752 [S] From: 3753 [S] Date: 3754 [S] Message-ID: 3755 [S] References: 3756 [S] :bytes 3757 [S] :lines 3758 [S] Xref:full 3759 [S] Distribution:full 3760 [S] . 3762 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3763 output above, using the alternative format: 3765 [C] LIST OVERVIEW.FMT 3766 [S] 215 Order of fields in overview database. 3767 [S] Subject: 3768 [S] From: 3769 [S] Date: 3770 [S] Message-ID: 3771 [S] References: 3772 [S] Bytes: 3773 [S] Lines: 3774 [S] Xref:FULL 3775 [S] Distribution:FULL 3776 [S] . 3778 8.5. HDR 3780 8.5.1. Usage 3782 Indicating capability: HDR 3783 Syntax 3785 HDR field message-id 3786 HDR field range 3787 HDR field 3789 Responses 3791 First form (message-id specified) 3793 225 Headers follow (multi-line) 3794 430 No article with that message-id 3796 Second form (range specified) 3798 225 Headers follow (multi-line) 3799 412 No newsgroup selected 3800 423 No articles in that range 3802 Third form (current article number used) 3804 225 Headers follow (multi-line) 3805 412 No newsgroup selected 3806 420 Current article number is invalid 3808 Parameters 3810 field name of field 3811 range number(s) of articles 3812 message-id message-id of article 3814 8.5.2. Description 3816 The HDR command provides access to specific fields from an article 3817 specified by message-id, or from a specified article or range of 3818 articles in the currently selected newsgroup. It MAY take the 3819 information directly from the articles or from the overview database. 3820 In the case of headers, an implementation MAY restrict the use of 3821 this command to a specific list of headers or MAY allow it to be used 3822 with any header; it may behave differently when it is used with a 3823 message-id argument and when it is used with a range or no argument. 3825 The required field argument is the name of a header with the colon 3826 omitted (e.g. "subject"), or the name of a metadata item including 3827 the leading colon (e.g. ":bytes"), and is case-insensitive. 3829 The message-id argument indicates a specific article. The range 3830 argument may be any of the following: 3832 o an article number 3833 o an article number followed by a dash to indicate all following 3834 o an article number followed by a dash followed by another article 3835 number 3836 If neither is specified, the current article number is used. 3838 If the information is available, it is returned as a multi-line data 3839 block following the 225 response code and contains one line for each 3840 article in the range that exists (note that unless the argument is a 3841 range including a dash, there will be exactly one line in the data 3842 block). The line consists of the article number, a space, and then 3843 the contents of the field. In the case of a header, the header name, 3844 colon, and the first space after the colon are all omitted. 3846 If the article is specified by message-id (the first form of the 3847 command), the article number MUST be replaced with zero, except that 3848 if there is a currently selected newsgroup and the article is present 3849 in that group, the server MAY use that article number (see the 3850 ARTICLE command (Section 6.2.1) and STAT examples (Section 6.2.4.3) 3851 for more details). In the other two forms of the command, the 3852 article number MUST be returned. 3854 Header contents are modified as follows: all CRLF pairs are removed, 3855 and then each TAB is replaced with a single space (note that this is 3856 the same transformation as is performed by the OVER command 3857 (Section 8.3.2), and the same comment concerning NUL, CR, and LF 3858 applies). 3860 Note the distinction between headers and metadata appearing to have 3861 the same meaning. Headers are always taken unchanged from the 3862 article; metadata are always calculated. For example, a request for 3863 "Lines" returns the contents of the "Lines" header of the specified 3864 articles, if any, no matter whether or not they accurately state the 3865 number of lines, while a request for ":lines" returns the line count 3866 metadata, which is always the actual number of lines irrespective of 3867 what any header may state. 3869 If the requested header is not present in the article or if it is 3870 present but empty, a line for that article is included in the output 3871 but the header content portion of the line is empty (the space after 3872 the article number MAY be retained or omitted). If the header occurs 3873 in a given article more than once, only the content of the first 3874 occurrence is returned by HDR. If any article number in the provided 3875 range does not exist in the group, no line for that article number is 3876 included in the output. 3878 If the second argument is a message-id and no such article exists, a 3879 430 response MUST be returned. If the second argument is a range or 3880 is omitted and the currently selected newsgroup is invalid, a 412 3881 response MUST be returned. If the second argument is a range and no 3882 articles in that number range exist in the currently selected 3883 newsgroup, including the case where the second number is less than 3884 the first one, a 423 response MUST be returned. If the second 3885 argument is omitted and the current article number is invalid, a 420 3886 response MUST be returned. 3888 A server MAY only allow HDR commands for a limited set of fields; it 3889 may behave differently in this respect for the first (message-id) 3890 form than for the other forms. If so, it MUST respond with the 3891 generic 503 response to attempts to request other fields, rather than 3892 returning erroneous results such as a successful empty response. 3894 If HDR uses the overview database and it is inconsistent for the 3895 requested field, the server MAY return what results it can or it MAY 3896 respond with the generic 503 response; in the latter case, the field 3897 MUST NOT appear in the output from LIST HEADERS. 3899 8.5.3. Examples 3901 Example of a successful retrieval of subject lines from a range of 3902 articles (3000235 has no Subject header, and 3000236 is missing): 3904 [C] GROUP misc.test 3905 [S] 211 1234 3000234 3002322 misc.test 3906 [C] HDR Subject 3000234-300238 3907 [S] 225 Headers follow 3908 [S] 3000234 I am just a test article 3909 [S] 3000235 3910 [S] 3000237 Re: I am just a test article 3911 [S] 3000238 Ditto 3912 [S] . 3914 Example of a successful retrieval of line counts from a range of 3915 articles: 3917 [C] GROUP misc.test 3918 [S] 211 1234 3000234 3002322 misc.test 3919 [C] HDR :lines 3000234-300238 3920 [S] 225 Headers follow 3921 [S] 3000234 42 3922 [S] 3000235 5 3923 [S] 3000237 11 3924 [S] 3000238 2378 3925 [S] . 3927 Example of a successful retrieval of the subject line from an article 3928 by message-id: 3930 [C] GROUP misc.test 3931 [S] 211 1234 3000234 3002322 misc.test 3932 [C] HDR subject 3933 [S] 225 Header information follows 3934 [S] 0 I am just a test article 3935 [S] . 3937 Example of a successful retrieval of the subject line from the 3938 current article: 3940 [C] GROUP misc.test 3941 [S] 211 1234 3000234 3002322 misc.test 3942 [C] HDR subject 3943 [S] 225 Header information follows 3944 [S] 3000234 I am just a test article 3945 [S] . 3947 Example of an unsuccessful retrieval of a header from an article by 3948 message-id: 3950 [C] HDR subject 3951 [S] 430 No Such Article Found 3953 Example of an unsuccessful retrieval of headers from articles by 3954 number because no newsgroup was selected first: 3956 [Assumes currently selected newsgroup is invalid.] 3957 [C] HDR subject 300256- 3958 [S] 412 No newsgroup selected 3960 Example of an unsuccessful retrieval of headers because the currently 3961 selected newsgroup is empty: 3963 [C] GROUP example.empty.newsgroup 3964 [S] 211 0 0 0 example.empty.newsgroup 3965 [C] HDR subject 1- 3966 [S] 423 No articles in that range 3968 Example of an unsuccessful retrieval of headers because the server 3969 does not allow HDR commands for that header: 3971 [C] GROUP misc.test 3972 [S] 211 1234 3000234 3002322 misc.test 3973 [C] HDR Content-Type 3000234-300238 3974 [S] 503 HDR not permitted on Content-Type 3976 8.6. LIST HEADERS 3978 8.6.1. Usage 3980 Indicating capability: HDR 3982 Syntax 3984 LIST HEADERS [MSGID|RANGE] 3986 Responses 3988 215 Field list follows (multi-line) 3990 Parameters 3992 MSGID requests list for access by message-id 3993 RANGE requests list for access by range 3995 8.6.2. Description 3997 See Section 7.6.1 for general requirements of the LIST command. 3999 The LIST HEADERS command returns a list of fields that may be 4000 retrieved using the HDR command. 4002 The information is returned as a multi-line data block following the 4003 215 response code and contains one line for each field name 4004 (excluding the trailing colon for headers and including the leading 4005 colon for metadata items). If the implementation allows any header 4006 to be retrieved, it MUST NOT include any header names in the list but 4007 MUST include the special entry ":" (a single colon on its own); it 4008 MUST still explicitly list any metadata items that are available. 4009 The order of items in the list is not significant; the server need 4010 not even consistently return the same order. The list MAY be empty 4011 (though in this circumstance there is little point in providing the 4012 HDR command). 4014 An implementation that also supports the OVER command SHOULD at least 4015 permit all the headers and metadata items listed in the output from 4016 the LIST OVERVIEW.FMT command. 4018 If the server treats the first form of the HDR command (message-id 4019 specified) differently to the other two forms (range specified or 4020 current article number used) in respect of which headers or metadata 4021 items are available, then: 4023 o if the MSGID argument is specified, the results MUST be those 4024 available for the first form of the HDR command; 4025 o if the RANGE argument is specified, the results MUST be those 4026 available for the second and third forms of the HDR command; 4027 o if no argument is specified, the results MUST be those available 4028 in all forms of the HDR command (that is, it MUST only list those 4029 items listed in both the previous cases). 4031 If the server does not treat the various forms differently, then it 4032 MUST always produce the same results and ignore any argument. 4034 8.6.3. Examples 4036 Example of an implementation providing access to only a few headers: 4038 [C] LIST HEADERS 4039 [S] 215 headers supported: 4040 [S] Subject 4041 [S] Message-ID 4042 [S] Xref 4043 [S] . 4045 Example of an implementation providing access to the same fields as 4046 the first example in Section 8.4.3: 4048 [C] CAPABILITIES 4049 [S] 101 Capability list: 4050 [S] VERSION 2 4051 [S] READER 4052 [S] OVER 4053 [S] HDR 4054 [S] LIST ACTIVE NEWSGROUPS HEADERS OVERVIEW.FMT 4055 [S] . 4056 [C] LIST HEADERS 4057 [S] 215 headers and metadata items supported: 4058 [S] Date 4059 [S] Distribution 4060 [S] From 4061 [S] Message-ID 4062 [S] References 4063 [S] Subject 4064 [S] Xref 4065 [S] :bytes 4066 [S] :lines 4067 [S] . 4069 Example of an implementation providing access to all headers: 4071 [C] LIST HEADERS 4072 [S] 215 metadata items supported: 4073 [S] : 4074 [S] :lines 4075 [S] :bytes 4076 [S] :x-article-number 4077 [S] . 4079 Example of an implementation distinguishing the first form of the HDR 4080 command from the other two forms: 4082 [C] LIST HEADERS RANGE 4083 [S] 215 metadata items supported: 4084 [S] : 4085 [S] :lines 4086 [S] :bytes 4087 [S] . 4088 [C] LIST HEADERS MSGID 4089 [S] 215 headers and metadata items supported: 4090 [S] Date 4091 [S] Distribution 4092 [S] From 4093 [S] Message-ID 4094 [S] References 4095 [S] Subject 4096 [S] :lines 4097 [S] :bytes 4098 [S] :x-article-number 4099 [S] . 4100 [C] LIST HEADERS 4101 [S] 215 headers and metadata items supported: 4102 [S] Date 4103 [S] Distribution 4104 [S] From 4105 [S] Message-ID 4106 [S] References 4107 [S] Subject 4108 [S] :lines 4109 [S] :bytes 4110 [S] . 4112 Note how :x-article-number does not appear in the last set of output. 4114 9. Augmented BNF Syntax for NNTP 4116 9.1. Introduction 4118 Each of the following sections describes the syntax of a major 4119 element of NNTP. This syntax extends and refines the descriptions 4120 elsewhere in this specification, and should be given precedence when 4121 resolving apparent conflicts. Note that ABNF [RFC2234] strings are 4122 case-insensitive. Non-terminals used in several places are defined 4123 in a separate section at the end. 4125 The non-terminals , , , and between them specify the text that 4127 flows between client and server. A consistent naming scheme is used 4128 in this document for the non-terminals relating to each command, and 4129 SHOULD be used by the specification of registered extensions. 4131 For each command, the sequence is: 4132 o The client sends an instance of ; the syntax for the 4133 EXAMPLE command is . 4134 o If the client is one that immediately streams data, it sends an 4135 instance of ; the syntax for the EXAMPLE 4136 command is . 4137 o The server sends an instance of . 4138 * The initial response line is independent of the command that 4139 generated it; if the 000 response has arguments, the syntax of 4140 the initial line is . 4141 * If the response is multi-line, the initial line is followed by 4142 a . The syntax for the contents of this 4143 block after "dot-stuffing" has been removed is (for the 000 4144 response to the EXAMPLE command) and 4145 is an instance of . 4146 o While the latest response is one that indicates more data is 4147 required (in general, a 3xx response): 4148 * the client sends an instance of ; the 4149 syntax for the EXAMPLE continuation following a 333 response is 4150 . 4151 * the server sends another instance of as above. 4153 (There are no commands in this specification that immediately stream 4154 data, but this non-terminal is defined for the convenience of 4155 extensions.) 4157 9.2. Commands 4159 This syntax defines the non-terminal , which represents 4160 what is sent from the client to the server. 4162 command-line = command EOL 4163 command = X-command 4164 X-command = keyword *(WS token) 4166 command =/ article-command / 4167 body-command / 4168 capabilities-command / 4169 date-command / 4170 group-command / 4171 hdr-command / 4172 head-command / 4173 help-command / 4174 ihave-command / 4175 last-command / 4176 list-command / 4177 listgroup-command / 4178 mode-reader-command / 4179 newgroups-command / 4180 newnews-command / 4181 next-command / 4182 over-command / 4183 post-command / 4184 quit-command / 4185 stat-command 4187 article-command = "ARTICLE" [WS article-ref] 4188 body-command = "BODY" [WS article-ref] 4189 capabilities-command = "CAPABILITIES" [WS keyword] 4190 date-command = "DATE" 4191 group-command = "GROUP" [WS newsgroup-name] 4192 hdr-command = "HDR" WS header-meta-name [WS range-ref] 4193 head-command = "HEAD" [WS article-ref] 4194 help-command = "HELP" 4195 ihave-command = "IHAVE" WS message-id 4196 last-command = "LAST" 4197 list-command = "LIST" [WS list-arguments] 4198 listgroup-command = "LISTGROUP" [WS newsgroup-name [WS range]] 4199 mode-reader-command = "MODE" WS "READER" 4200 newgroups-command = "NEWGROUPS" WS date-time 4201 newnews-command = "NEWNEWS" WS wildmat WS date-time 4202 next-command = "NEXT" 4203 over-command = "OVER" [WS range-ref] 4204 post-command = "POST" 4205 quit-command = "QUIT" 4206 stat-command = "STAT" [WS article-ref] 4208 article-ref = article-number / message-id 4209 date = date2y / date4y 4210 date4y = 4DIGIT 2DIGIT 2DIGIT 4211 date2y = 2DIGIT 2DIGIT 2DIGIT 4212 date-time = date WS time [WS "GMT"] 4213 header-meta-name = header-name / metadata-name 4214 list-arguments = keyword [WS token] 4215 metadata-name = ":" 1*A-NOTCOLON 4216 range = article-number ["-" [article-number]] 4217 range-ref = range / message-id 4218 time = 2DIGIT 2DIGIT 2DIGIT 4220 9.3. Command continuation 4222 This syntax defines the further material sent by the client in the 4223 case of multi-stage commands and those that stream data. 4225 command-datastream = UNDEFINED 4226 ; not used, provided as a hook for extensions 4227 command-continuation = ihave-335-continuation / 4228 post-340-continuation 4230 ihave-335-continuation = encoded-article 4231 post-340-continuation = encoded-article 4233 encoded-article = multi-line-data-block 4234 ; after undoing the "dot-stuffing", this MUST match
4236 9.4. Responses 4238 9.4.1. Generic responses 4240 This syntax defines the non-terminal , which represents the 4241 generic form of responses - that is, what is sent from the server to 4242 the client in response to a or a . 4244 response = simple-response / multi-line-response 4245 simple-response = initial-response-line 4246 multi-line-response = initial-response-line multi-line-data-block 4248 initial-response-line = 4249 initial-response-content [SP trailing-comment] CRLF 4250 initial-response-content = X-initial-response-content 4251 X-initial-response-content = 3DIGIT *(SP response-argument) 4252 response-argument = 1*A-CHAR 4253 trailing-comment = *U-CHAR 4255 9.4.2. Initial response line contents 4257 This syntax defines the specific initial response lines for the 4258 various commands in this specification. Only those response codes 4259 with arguments are listed. 4261 initial-response-content =/ response-111-content / 4262 response-211-content / 4263 response-220-content / 4264 response-221-content / 4265 response-222-content / 4266 response-223-content / 4267 response-401-content 4269 response-111-content = "111" SP date4y time 4270 response-211-content = "211" 3(SP article-number) SP newsgroup-name 4271 response-220-content = "220" SP article-number SP message-id 4272 response-221-content = "221" SP article-number SP message-id 4273 response-222-content = "222" SP article-number SP message-id 4274 response-223-content = "223" SP article-number SP message-id 4275 response-401-content = "401" SP capability-label 4277 9.4.3. Multi-line response contents 4279 This syntax defines the content of the various multi-line responses; 4280 more precisely, it defines the part of the response in the multi-line 4281 data block after any "dot-stuffing" has been undone. The numeric 4282 portion of each non-terminal name indicates the response code that is 4283 followed by this data. 4285 multi-line-response-content = article-220-ml-content / 4286 body-222-ml-content / 4287 capabilities-101-ml-content / 4288 hdr-225-ml-content / 4289 head-221-ml-content / 4290 help-100-ml-content / 4291 list-215-ml-content / 4292 listgroup-211-ml-content / 4293 newgroups-231-ml-content / 4294 newnews-230-ml-content / 4295 over-224-ml-content 4297 article-220-ml-content = article 4298 body-222-ml-content = body 4299 capabilities-101-ml-content = version-line CRLF 4300 *(capability-line CRLF) 4301 hdr-225-ml-content = *(article-number SP hdr-content CRLF) 4302 head-221-ml-content = 1*header 4303 help-100-ml-content = *(*U-CHAR CRLF) 4304 list-215-ml-content = list-content 4305 listgroup-211-ml-content = *(article-number CRLF) 4306 newgroups-231-ml-content = active-groups-list 4307 newnews-230-ml-content = *(message-id CRLF) 4308 over-224-ml-content = *(article-number over-content CRLF) 4310 active-groups-list = *(newsgroup-name SPA article-number 4311 SPA article-number SPA newsgroup-status CRLF) 4312 hdr-content = *S-NONTAB 4313 hdr-n-content = [(header-name ":" / metadata-name) SP hdr-content] 4314 list-content = body 4315 newsgroup-status = %x79 / %x6E / %x6D / private-status 4316 over-content = 1*6(TAB hdr-content) / 4317 7(TAB hdr-content) *(TAB hdr-n-content) 4318 private-status = token ; except the values in newsgroup-status 4320 9.5. Capability lines 4322 This syntax defines the generic form of a capability line in the 4323 capabilities list (see Section 3.3.1). 4325 capability-line = capability-entry 4326 capability-entry = X-capability-entry 4327 X-capability-entry = capability-label *(WS capability-argument) 4328 capability-label = keyword 4329 capability-argument = token 4331 This syntax defines the specific capability entries for the 4332 capabilities in this specification. 4334 capability-entry =/ 4335 hdr-capability / 4336 ihave-capability / 4337 implementation-capability / 4338 list-capability / 4339 mode-reader-capability / 4340 newnews-capability / 4341 over-capability / 4342 post-capability / 4343 reader-capability 4345 hdr-capability = "HDR" 4346 ihave-capability = "IHAVE" 4347 implementation-capability = "IMPLEMENTATION" *(WS token) 4348 list-capability = "LIST" 1*(WS keyword) 4349 mode-reader-capability = "MODE-READER" 4350 newnews-capability = "NEWNEWS" 4351 over-capability = "OVER" [WS "MSGID"] 4352 post-capability = "POST" 4353 reader-capability = "READER" 4355 version-line = "VERSION" 1*(WS version-number) 4356 version-number = nzDIGIT *5DIGIT 4358 9.6. LIST variants 4360 This section defines more specifically the keywords for the LIST 4361 command and the syntax of the corresponding response contents. 4363 ; active 4364 list-arguments =/ "ACTIVE" [WS wildmat] 4365 list-content =/ list-active-content 4366 list-active-content = active-groups-list 4368 ; active.times 4369 list-arguments =/ "ACTIVE.TIMES" [WS wildmat] 4370 list-content =/ list-active-times-content 4371 list-active-times-content = 4372 *(newsgroup-name SPA 1*DIGIT SPA newsgroup-creator CRLF) 4373 newsgroup-creator = U-TEXT 4375 ; distrib.pats 4376 list-arguments =/ "DISTRIB.PATS" 4377 list-content =/ list-distrib-pats-content 4378 list-distrib-pats-content = 4379 *(1*DIGIT ":" wildmat ":" distribution CRLF) 4380 distribution = token 4382 ; headers 4383 list-arguments =/ "HEADERS" [WS ("MSGID" / "RANGE")] 4384 list-content =/ list-headers-content 4385 list-headers-content = *(header-meta-name CRLF) / 4386 *((metadata-name / ":") CRLF) 4388 ; newsgroups 4389 list-arguments =/ "NEWSGROUPS" [WS wildmat] 4390 list-content =/ list-newsgroups-content 4391 list-newsgroups-content = 4392 *(newsgroup-name WS newsgroup-description CRLF) 4393 newsgroup-description = S-TEXT 4395 ; overview.fmt 4396 list-arguments =/ "OVERVIEW.FMT" 4397 list-content =/ list-overview-fmt-content 4398 list-overview-fmt-content = "Subject:" CRLF 4399 "From:" CRLF 4400 "Date:" CRLF 4401 "Message-ID:" CRLF 4402 "References:" CRLF 4403 ( ":bytes" CRLF ":lines" / "Bytes:" CRLF "Lines:") CRLF 4404 *((header-name ":full" / metadata-name) CRLF) 4406 9.7. Articles 4408 This syntax defines the non-terminal
, which represents the 4409 format of an article as described in Section 3.6. 4411 article = 1*header CRLF body 4412 header = header-name ":" [CRLF] SP header-content CRLF 4413 header-content = *(S-CHAR / [CRLF] WS) 4414 body = *(*B-CHAR CRLF) 4416 9.8. General non-terminals 4418 These non-terminals are used at various places in the syntax and are 4419 collected here for convenience. A few of these non-terminals are not 4420 used in this specification but are provided for the consistency and 4421 convenience of extension authors. 4423 multi-line-data-block = content-lines termination 4424 content-lines = *([content-text] CRLF) 4425 content-text = (".." / B-NONDOT) *B-CHAR 4426 termination = "." CRLF 4428 article-number = 1*16DIGIT 4429 header-name = 1*A-NOTCOLON 4430 keyword = ALPHA 2*11(ALPHA / DIGIT / "." / "-") 4431 message-id = "<" 1*248A-NOTGT ">" 4432 newsgroup-name = 1*wildmat-exact 4433 token = 1*P-CHAR 4435 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 4436 wildmat-pattern = 1*wildmat-item 4437 wildmat-item = wildmat-exact / wildmat-wild 4438 wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 4439 UTF8-non-ascii ; exclude ! * , ? [ \ ] 4440 wildmat-wild = "*" / "?" 4442 base64 = *(4base64-char) [base64-terminal] 4443 base64-char = UPPER / LOWER / DIGIT / "+" / "/" 4444 base64-terminal = 2base64-char "==" / 3base64-char "=" 4446 ; Assorted special character sets 4447 ; A- means based on US-ASCII, excluding controls and SP 4448 ; P- means based on UTF-8, excluding controls and SP 4449 ; U- means based on UTF-8, excluding NUL CR and LF 4450 ; B- means based on bytes, excluding NUL CR and LF 4451 A-CHAR = %x21-7E 4452 A-NOTCOLON = %x21-39 / %x3B-7E ; exclude ":" 4453 A-NOTGT = %x21-3D / %x3F-7E ; exclude ">" 4454 P-CHAR = A-CHAR / UTF8-non-ascii 4455 U-CHAR = CTRL / TAB / SP / A-CHAR / UTF8-non-ascii 4456 U-NONTAB = CTRL / SP / A-CHAR / UTF8-non-ascii 4457 U-TEXT = P-CHAR *U-CHAR 4458 B-CHAR = CTRL / TAB / SP / %x21-FF 4459 B-NONDOT = CTRL / TAB / SP / %x21-2D / %x2F-FF ; exclude "." 4461 ALPHA = UPPER / LOWER ; use only when case-insensitive 4462 CR = %x0D 4463 CRLF = CR LF 4464 CTRL = %x01-08 / %x0B-0C / %x0E-1F 4465 DIGIT = %x30-39 4466 nzDIGIT = %x31-39 4467 EOL = *(SP / TAB) CRLF 4468 LF = %x0A 4469 LOWER = %x61-7A 4470 SP = %x20 4471 SPA = 1*SP 4472 TAB = %x09 4473 UPPER = %x41-5A 4474 UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4 4475 UTF8-2 = %xC2-DF UTF8-tail 4476 UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail / 4477 %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail 4478 UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail / 4479 %xF4 %x80-8F 2UTF8-tail 4480 UTF8-tail = %x80-BF 4481 WS = 1*(SP / TAB) 4483 The following non-terminals require special consideration. They 4484 represent situations where material SHOULD be restricted to UTF-8, 4485 but implementations MUST be able to cope with other character 4486 encodings. Therefore there are two sets of definitions for them. 4488 Implementations MUST accept any content that meets this syntax: 4490 S-CHAR = %x21-FF 4491 S-NONTAB = CTRL / SP / S-CHAR 4492 S-TEXT = (CTRL / S-CHAR) *B-CHAR 4494 and MAY pass such content on unaltered. 4496 When generating new content or re-encoding existing content, 4497 implementations SHOULD conform to this syntax: 4499 S-CHAR = P-CHAR 4500 S-NONTAB = U-NONTAB 4501 S-TEXT = U-TEXT 4503 9.9. Extensions and Validation 4505 The specification of a registered extension MUST include formal 4506 syntax that defines additional forms for the following non-terminals: 4508 command 4509 for each new command other than a variant of the LIST command - 4510 the syntax of each command MUST be compatible with the definition 4511 of ; 4513 command-datastream 4514 for each new command that immediately streams data; 4516 command-continuation 4517 for each new command that sends further material after the initial 4518 command line - the syntax of each continuation MUST be exactly 4519 what is sent to the server, including any escape mechanisms such 4520 as "dot-stuffing"; 4522 initial-response-content 4523 for each new response code that has arguments - the syntax of each 4524 response MUST be compatible with the definition of ; 4527 multi-line-response-content 4528 for each new response code that has a multi-line response - the 4529 syntax MUST show the response after the lines containing the 4530 response code and the terminating octet have been removed and any 4531 "dot-stuffing" undone; 4533 capability-entry 4534 for each new capability label - the syntax of each entry MUST be 4535 compatible with the definition of ; 4537 list-arguments 4538 for each new variant of the LIST command - the syntax of each 4539 entry MUST be compatible with the definition of ; 4541 list-content 4542 for each new variant of the LIST command - the syntax MUST show 4543 the response after the lines containing the 215 response code and 4544 the terminating octet have been removed and any "dot-stuffing" 4545 undone. 4547 The =/ notation of ABNF [RFC2234] and the naming conventions 4548 described in Section 9.1 SHOULD be used for this. 4550 When validating the syntax in this specification, or syntax based on 4551 it, it should be noted that: 4552 o the non-terminals , , , , and 4554 describe basic concepts of the protocol and are not referred to by 4555 any other rule; 4556 o the non-terminal is provided for the convenience of 4557 extension authors and is not referred to by any rule in this 4558 specification; 4559 o for the reasons given above, the non-terminals , 4560 , and each have two definitions; 4561 o the non-terminal is deliberately not defined. 4563 10. Internationalisation Considerations 4565 10.1. Introduction and historical situation 4567 RFC 977 [RFC977] was written at a time when internationalisation was 4568 not seen as a significant issue. As such, it was written on the 4569 assumption that all communication would be in ASCII and use only a 4570 7-bit transport layer, although in practice just about all known 4571 implementations are 8-bit clean. 4573 Since then, Usenet and NNTP have spread throughout the world. In the 4574 absence of standards for handling the issues of language and 4575 character sets, countries, newsgroup hierarchies, and individuals 4576 have found a variety of solutions that work for them but are not 4577 necessarily appropriate elsewhere. For example, some have adopted a 4578 default 8-bit character set appropriate to their needs (such as ISO/ 4579 IEC 8859-1 in Western Europe or KOI-8 in Russia), others have used 4580 ASCII (either US-ASCII or national variants) in headers but local 16- 4581 bit character sets in article bodies, and still others have gone for 4582 a combination of MIME [RFC2045] and UTF-8. With the increased use of 4583 MIME in email, it is becoming more common to find NNTP articles 4584 containing MIME headers identifying the character set of the body, 4585 but this is far from universal. 4587 The resulting confusion does not help interoperability. 4589 One point that has been generally accepted is that articles can 4590 contain octets with the top bit set, and NNTP is only expected to 4591 operate on 8-bit clean transport paths. 4593 10.2. This specification 4595 Part of the role of this present specification is to eliminate this 4596 confusion and promote interoperability as far as possible. At the 4597 same time, it is necessary to accept the existence of the present 4598 situation and not gratuitously break existing implementations and 4599 arrangements, even if they are less than optimal. Therefore the 4600 current practice described above has been taken into consideration in 4601 producing this specification. 4603 This specification extends NNTP from US-ASCII [ANSI1986] to UTF-8 4604 [RFC3629]. Except in the two areas discussed below, UTF-8 (which is 4605 a superset of US-ASCII) is mandatory and implementations MUST NOT use 4606 any other encoding. 4608 Firstly, the use of MIME for article headers and bodies is strongly 4609 recommended. However, given widely divergent existing practices, an 4610 attempt to require a particular encoding and tagging standard would 4611 be premature at this time. Accordingly, this specification allows 4612 the use of arbitrary 8-bit data in articles subject to the following 4613 requirements and recommendations. 4615 o The names of headers (e.g. "From" or "Subject") MUST be in US- 4616 ASCII. 4618 o Header values SHOULD use US-ASCII or an encoding based on it such 4619 as RFC 2047 [RFC2047] until such time as another approach has been 4620 standardised. At present, 8-bit encodings (including UTF-8) 4621 SHOULD NOT be used because they are likely to cause 4622 interoperability problems. 4624 o The character set of article bodies SHOULD be indicated in the 4625 article headers, and this SHOULD be done in accordance with MIME. 4627 o Where an article is obtained from an external source an 4628 implementation MAY pass it on, and derive data from it (such as 4629 the response to the HDR command), even though the article or the 4630 data does not meet the above requirements. Implementations MUST 4631 transfer such articles and data correctly and unchanged; they MUST 4632 NOT attempt to convert or re-encode the article or derived data. 4633 (Nevertheless, a client or server MAY elect not to post or forward 4634 the article if, after further examination of the article, it deems 4635 it inappropriate to do so.) 4637 This requirement affects the ARTICLE (Section 6.2.1), BODY 4638 (Section 6.2.3), HDR (Section 8.5), HEAD (Section 6.2.2), IHAVE 4639 (Section 6.3.2), OVER (Section 8.3), and POST (Section 6.3.1) 4640 commands. 4642 Secondly, the following requirements are placed on the newsgroups 4643 list returned by the LIST NEWSGROUPS (Section 7.6.6) command: 4645 o Although this specification allows UTF-8 for newsgroup names, they 4646 SHOULD be restricted to US-ASCII until a successor to RFC 1036 4647 [RFC1036] standardises another approach. 8-bit encodings SHOULD 4648 NOT be used because they are likely to cause interoperability 4649 problems. 4651 o The newsgroup description SHOULD be in US-ASCII or UTF-8 unless 4652 and until a successor to RFC 1036 standardised other encoding 4653 arrangements. 8-bit encodings other than UTF-8 SHOULD NOT be used 4654 because they are likely to cause interoperability problems. 4656 o Implementations which obtain this data from an external source 4657 MUST correctly handle it even if it does not meet the above 4658 requirements. Implementations (in particular, clients) MUST 4659 handle such data correctly. 4661 10.3. Outstanding issues 4663 While the primary use of NNTP is for transmitting articles that 4664 conform to RFC 1036 (Netnews articles), it is also used for other 4665 formats (see Appendix A). It is therefore most appropriate that 4666 internationalisation issues related to article formats be addressed 4667 in the relevant specifications. For Netnews articles, this is any 4668 successor to RFC 1036. For email messages, it is RFC 2822 [RFC2822]. 4670 Of course, any article transmitted via NNTP needs to conform to this 4671 specification as well. 4673 Restricting newsgroup names to UTF-8 is not a complete solution. In 4674 particular, when new newsgroup names are created or a user is asked 4675 to enter a newsgroup name, some scheme of canonicalisation will need 4676 to take place. This specification does not attempt to define that 4677 canonicalization; further work is needed in this area in conjunction 4678 with the article format specifications. Until such specifications 4679 are published, implementations SHOULD match newsgroup names octet-by- 4680 octet. It is anticipated that any approved scheme will be applied 4681 "at the edges" and therefore octet-by-octet comparison will continue 4682 to apply to most, if not all, uses of newsgroup names in NNTP. 4684 In the meantime, any implementation experimenting with UTF-8 4685 newsgroup names is strongly cautioned that a future specification may 4686 require that those names be canonicalized when used with NNTP in a 4687 way that is not compatible with their experiments. 4689 Since the primary use of NNTP is with Netnews, and since newsgroup 4690 descriptions are normally distributed through specially formatted 4691 articles, it is recommended that the internationalisation issues 4692 related to them be addressed in any successor to RFC 1036. 4694 11. IANA Considerations 4696 This specification requires IANA to keep a registry of capability 4697 labels. The initial contents of this registry are specified in 4698 Section 3.3.4. As described in Section 3.3.3, labels beginning with 4699 X are reserved for private use while all other names are expected to 4700 be associated with a specification in an RFC on the standards-track 4701 or defining an IESG-approved experimental protocol. 4703 Different entries in the registry MUST use different capability 4704 labels. 4706 Different entries in the registry MUST NOT use the same command name. 4707 For this purpose, variants distinguished by a second or subsequent 4708 keyword (e.g. "LIST HEADERS" and "LIST OVERVIEW.FMT") count as 4709 different commands. If there is a need for two extensions to use the 4710 same command, a single harmonised specification MUST be registered. 4712 12. Security Considerations 4714 This section is meant to inform application developers, information 4715 providers, and users of the security limitations in NNTP as described 4716 by this document. The discussion does not include definitive 4717 solutions to the problems revealed, though it does make some 4718 suggestions for reducing security risks. 4720 12.1. Personal and Proprietary Information 4722 NNTP, because it was created to distribute network news articles, 4723 will forward whatever information is stored in those articles. 4724 Specification of that information is outside this scope of this 4725 document, but it is likely that some personal and/or proprietary 4726 information is available in some of those articles. It is very 4727 important that designers and implementers provide informative 4728 warnings to users so personal and/or proprietary information in 4729 material that is added automatically to articles (e.g. in headers) is 4730 not disclosed inadvertently. Additionally, effective and easily 4731 understood mechanisms to manage the distribution of news articles 4732 SHOULD be provided to NNTP Server administrators, so that they are 4733 able to report with confidence the likely spread of any particular 4734 set of news articles. 4736 12.2. Abuse of Server Log Information 4738 A server is in the position to save session data about a user's 4739 requests that might identify their reading patterns or subjects of 4740 interest. This information is clearly confidential in nature and its 4741 handling can be constrained by law in certain countries. People 4742 using the NNTP protocol to provide data are responsible for ensuring 4743 that such material is not distributed without the permission of any 4744 individuals that are identifiable by the published results. 4746 12.3. Weak Authentication and Access Control 4748 There is no user-based or token-based authentication in the basic 4749 NNTP specification. Access is normally controlled by server 4750 configuration files. Those files specify access by using domain 4751 names or IP addresses. However, this specification does permit the 4752 creation of extensions to the NNTP protocol itself for such purposes; 4753 one such extension is [NNTP-AUTH]. While including such mechanisms 4754 is optional, doing so is strongly encouraged. 4756 Other mechanisms are also available. For example, a proxy server 4757 could be put in place that requires authentication before connecting 4758 via the proxy to the NNTP server. 4760 12.4. DNS Spoofing 4762 Many existing NNTP implementations authorize incoming connections by 4763 checking the IP address of that connection against the IP addresses 4764 obtained via DNS lookups of lists of domain names given in local 4765 configuration files. Servers that use this type of authentication, 4766 and clients that find a server by doing a DNS lookup of the server 4767 name, rely very heavily on the Domain Name Service, and are thus 4768 generally prone to security attacks based on the deliberate 4769 misassociation of IP addresses and DNS names. Clients and servers 4770 need to be cautious in assuming the continuing validity of an IP 4771 number/DNS name association. 4773 In particular, NNTP clients and servers SHOULD rely on their name 4774 resolver for confirmation of an IP number/DNS name association, 4775 rather than caching the result of previous host name lookups. Many 4776 platforms already can cache host name lookups locally when 4777 appropriate, and they SHOULD be configured to do so. It is proper 4778 for these lookups to be cached, however, only when the TTL (Time To 4779 Live) information reported by the name server makes it likely that 4780 the cached information will remain useful. 4782 If NNTP clients or servers cache the results of host name lookups in 4783 order to achieve a performance improvement, they MUST observe the TTL 4784 information reported by DNS. If NNTP clients or servers do not 4785 observe this rule, they could be spoofed when a previously accessed 4786 server's IP address changes. As network renumbering is expected to 4787 become increasingly common, the possibility of this form of attack 4788 will grow. Observing this requirement thus reduces this potential 4789 security vulnerability. 4791 This requirement also improves the load-balancing behaviour of 4792 clients for replicated servers using the same DNS name and reduces 4793 the likelihood of a user's experiencing failure in accessing sites 4794 that use that strategy. 4796 12.5. UTF-8 issues 4798 UTF-8 [RFC3629] permits only certain sequences of octets and 4799 designates others as either malformed or "illegal". The Unicode 4800 standard identifies a number of security issues related to illegal 4801 sequences and forbids their generation by conforming implementations. 4803 Implementations of this specification MUST NOT generate malformed or 4804 illegal sequences and SHOULD detect them and take some appropriate 4805 action. This could include: 4807 o generating a 501 response code. 4808 o replacing such sequences by the sequence %xEF.BF.BD, which encodes 4809 the "replacement character" U+FFFD; 4810 o closing the connection; 4811 o replacing such sequences by a "guessed" valid sequence (based on 4812 properties of the UTF-8 encoding); 4813 In the last case, the implementation MUST ensure that any replacement 4814 cannot be used to bypass validity or security checks. For example, 4815 the illegal sequence %xC0.A0 is an over-long encoding for space 4816 (%x20). If it is replaced by the latter in a command line, this 4817 needs to happen before the command line is parsed into individual 4818 arguments. If the replacement came after parsing, it would be 4819 possible to generate an argument with an embedded space, which is 4820 forbidden. Use of the "replacement character" does not have this 4821 problem, since it is permitted wherever non-US-ASCII characters are. 4822 Implementations SHOULD use one of the first two solutions where the 4823 general structure of the NNTP stream remains intact, and close the 4824 connection if it is no longer possible to parse it sensibly. 4826 12.6. Caching of capability lists 4828 The CAPABILITIES command provides a capability list, which is 4829 information about the current capabilities of the server. Whenever 4830 there is a relevant change to the server state, the results of this 4831 command are required to change accordingly. 4833 In most situations the capabilities list in a given server state will 4834 not change from session to session; for example, a given extension 4835 will be installed permanently on a server. Some clients may 4836 therefore wish to remember which extensions a server supports to 4837 avoid the delay of an additional command and response, particularly 4838 if they open multiple connections in the same session. 4840 However, information about extensions related to security and privacy 4841 MUST NOT be cached, since this could allow a variety of attacks. 4843 For example, consider a server which permits the use of cleartext 4844 passwords on links that are encrypted but not otherwise: 4846 [Initial connection set-up completed.] 4847 [S] 200 NNTP Service Ready, posting permitted 4848 [C] CAPABILITIES 4849 [S] 101 Capability list: 4850 [S] VERSION 2 4851 [S] READER 4852 [S] NEWNEWS 4853 [S] POST 4854 [S] XENCRYPT 4856 [S] LIST ACTIVE NEWSGROUPS 4857 [S] . 4858 [C] XENCRYPT 4859 [Client and server negotiate encryption on the link] 4860 [S] 283 Encrypted link established 4861 [C] CAPABILITIES 4862 [S] 101 Capability list: 4863 [S] VERSION 2 4864 [S] READER 4865 [S] NEWNEWS 4866 [S] POST 4867 [S] XSECRET 4868 [S] LIST ACTIVE NEWSGROUPS 4869 [S] . 4870 [C] XSECRET fred flintstone 4871 [S] 290 Password for fred accepted 4873 If the client caches the last capabilities list, then on the next 4874 session it will attempt to use XSECRET on an unencrypted link: 4876 [Initial connection set-up completed.] 4877 [S] 200 NNTP Service Ready, posting permitted 4878 [C] XSECRET fred flintstone 4879 [S] 483 Only permitted on secure links 4881 exposing the password to any eavesdropper. While the primary cause 4882 of this is passing a secret without first checking the security of 4883 the link, caching of capability lists can increase the risk. 4885 Any security extension should include requirements to check the 4886 security state of the link in a manner appropriate to that extension. 4888 Caching should normally only be considered for anonymous clients that 4889 do not use any security or privacy extensions and for which the time 4890 required for an additional command and response is a noticeable 4891 issue. 4893 13. Acknowledgements 4895 This document is the result of much effort by the present and past 4896 members of the NNTP Working Group, chaired by Russ Allbery and Ned 4897 Freed. It could not have been produced without them. 4899 The author acknowledges the original authors of NNTP as documented in 4900 RFC 977 [RFC977]: Brian Kantor and Phil Lapsey. 4902 The author gratefully acknowledges: 4904 o The work of the NNTP committee chaired by Eliot Lear. The 4905 organization of this document was influenced by the last available 4906 draft from this working group. A special thanks to Eliot for 4907 generously providing the original machine-readable sources for 4908 that document. 4910 o The work of the DRUMS working group, specifically RFC 1869 4911 [RFC1869], which drove the original thinking which led to the 4912 CAPABILITIES command and the extensions mechanism detailed in this 4913 document. 4915 o The authors of RFC 2616 [RFC2616] for providing specific and 4916 relevant examples of security issues that should be considered for 4917 HTTP. Since many of the same considerations exist for NNTP, those 4918 examples that are relevant have been included here with some minor 4919 rewrites. 4921 o The comments and additional information provided by the following 4922 individuals in preparing one or more of the progenitors of this 4923 document: 4924 Russ Allbery 4925 Wayne Davison 4926 Chris Lewis 4927 Tom Limoncelli 4928 Eric Schnoebelen 4929 Rich Salz 4931 This work was motivated by the work of various news reader authors 4932 and news server authors, which includes those listed below: 4934 Rick Adams 4935 Original author of the NNTP extensions to the RN news reader and 4936 last maintainer of Bnews 4938 Stan Barber 4939 Original author of the NNTP extensions to the news readers that 4940 are part of Bnews 4942 Geoff Collyer 4943 Original author of the OVERVIEW database proposal and one of the 4944 original authors of CNEWS 4946 Dan Curry 4947 Original author of the xvnews news reader 4949 Wayne Davison 4950 Author of the first threading extensions to the RN news reader 4951 (commonly called TRN) 4953 Geoff Huston 4954 Original author of ANU NEWS 4956 Phil Lapsey 4957 Original author of the UNIX reference implementation for NNTP 4959 Iain Lea 4960 Original maintainer of the TIN news reader 4962 Chris Lewis 4963 First known implementer of the AUTHINFO GENERIC extension 4965 Rich Salz 4966 Original author of INN 4968 Henry Spencer 4969 One of the original authors of CNEWS 4971 Kim Storm 4972 Original author of the NN news reader 4974 Other people who contributed to this document include: 4976 Matthias Andree 4977 Greg Andruk 4978 Daniel Barclay 4979 Maurizio Codogno 4980 Mark Crispin 4981 Andrew Gierth 4982 Juergen Helbing 4983 Scott Hollenbeck 4984 Charles Lindsey 4985 Ade Lovett 4986 David Magda 4987 Ken Murchison 4988 Francois Petillon 4989 Peter Robinson 4990 Rob Siemborski 4991 Howard Swinehart 4992 Ruud van Tol 4993 Jeffrey Vinocur 4995 The author thanks them all and apologises to anyone omitted. 4997 Finally, the present author gratefully acknowledges the vast amount 4998 of work put into previous drafts by the previous author: 5000 Stan Barber 5002 14. References 5004 14.1 Normative References 5006 [ANSI1986] 5007 American National Standards Institute, "Coded Character 5008 Set - 7-bit American Standard Code for Information 5009 Interchange", ANSI X3.4, 1986. 5011 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 5012 Extensions (MIME) Part One: Format of Internet Message 5013 Bodies", RFC 2045, November 1996. 5015 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 5016 Part Three: Message Header Extensions for Non-ASCII Text", 5017 RFC 2047, November 1996. 5019 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 5020 Requirement Levels", BCP 14, RFC 2119, March 1997. 5022 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 5023 Specifications: ABNF", RFC 2234, November 1997. 5025 [RFC3548] Josefsson, S., "The Base16, Base32, and Base64 Data 5026 Encodings", RFC 3548, July 2003. 5028 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 5029 10646", STD 63, RFC 3629, November 2003. 5031 [RFC977] Kantor, B. and P. Lapsley, "Network News Transfer 5032 Protocol", RFC 977, February 1986. 5034 [TF.686-1] 5035 International Telecommunications Union - Radio, "Glossary, 5036 ITU-R Recommendation TF.686-1", ITU-R Recommendation 5037 TF.686-1, October 1997. 5039 14.2 Informative References 5041 [NNTP-AUTH] 5042 Vinocur, J., Murchison, K., and C. Newman, "NNTP 5043 Authentication", draft-ietf-nntpext-authinfo-06 (work in 5044 progress), December 2004. 5046 [NNTP-STREAM] 5047 Vinocur, J. and K. Murchison, "NNTP Authentication", 5048 draft-ietf-nntpext-streaming-03 (work in progress), 5049 December 2004. 5051 [NNTP-TLS] 5052 Vinocur, J., Murchison, K., and C. Newman, "Using TLS with 5053 NNTP", draft-ietf-nntpext-tls-nntp-04 (work in progress), 5054 December 2004. 5056 [RFC1036] Horton, M. and R. Adams, "Standard for interchange of 5057 USENET messages", RFC 1036, December 1987. 5059 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 5060 Specification, Implementation", RFC 1305, March 1992. 5062 [RFC1869] Klensin, J., Freed, N., Rose, M., Stefferud, E., and D. 5063 Crocker, "SMTP Service Extensions", STD 10, RFC 1869, 5064 November 1995. 5066 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 5067 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 5068 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 5070 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 5071 June 1999. 5073 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, 5074 April 2001. 5076 [RFC2980] Barber, S., "Common NNTP Extensions", RFC 2980, 5077 October 2000. 5079 [ROBE1995] 5080 Robertson, R., "FAQ: Overview database / NOV General 5081 Information", January 1995. 5083 There is no definitive copy of this document known to the 5084 author. It was previously posted as the Usenet article 5085 5087 [SALZ1992] 5088 Salz, R., "Manual Page for wildmat(3) from the INN 1.4 5089 distribution, Revision 1.10", April 1992. 5091 There is no definitive copy of this document known to the 5092 author. 5094 Appendix A. Interaction with other specifications 5096 NNTP is most often used for transferring articles that conform to 5097 RFC 1036 [RFC1036] (such articles are called "Netnews articles" 5098 here). It is also sometimes used for transferring email messages 5099 that conform to RFC 2822 [RFC2822] (such articles are called "email 5100 articles" here). In this situation, articles must conform both to 5101 this specification and to that other one; this appendix describes 5102 some relevant issues. 5104 A.1. Header folding 5106 NNTP allows a header line to be folded (by inserting a CRLF pair) 5107 before any space or TAB character. 5109 Both email and Netnews articles are required to have at least one 5110 octet other than space or TAB on each header line. Thus folding can 5111 only happen at one point in each sequence of consecutive spaces or 5112 TABs. Netnews articles are further required to have the header name, 5113 colon, and following space all on the first line; folding may only 5114 happen beyond that space. Finally, some non-conforming software will 5115 remove trailing spaces and TABs from a line. Therefore it might be 5116 inadvisable to fold a header after a space or TAB. 5118 For maximum safety, header lines SHOULD conform to the following 5119 syntax rather than that in Section 9.7. 5121 header = header-name ":" SP [header-content] CRLF 5122 header-content = [WS] token *( [CRLF] WS token ) 5124 A.2. Message-IDs 5126 Every article handled by an NNTP server MUST have a unique 5127 message-id. For the purposes of this specification, a message-id is 5128 an arbitrary opaque string that merely needs to meet certain 5129 syntactic requirements and is just a way to refer to the article. 5131 Because there is a significant risk of old articles being reinjected 5132 into the global Usenet system, RFC 1036 [RFC1036] requires that 5133 message-ids are globally unique for all time. 5135 This specification states that message-ids are the same if and only 5136 if they consist of the same sequence of octets. Other specifications 5137 may define two different sequences as being equal because they are 5138 putting an interpretation on particular characters. RFC 2822 5139 [RFC2822] has a concept of "quoted" and "escaped" characters. It 5140 therefore considers the three message-ids: 5142 5143 <"ab.cd"@example.com> 5144 <"ab.\cd"@example.com> 5146 as being identical. Therefore an NNTP implementation handing email 5147 articles must ensure that only one of these three appears in the 5148 protocol and the other two are converted to it as and when necessary, 5149 such as when a client checks the results of a NEWNEWS command against 5150 an internal database of message-ids. Note that RFC 1036 [RFC1036] 5151 never treats two different strings as being identical. Its draft 5152 successor restricts the syntax of message-ids so that, whenever 5153 RFC 2822 would treat two strings as equivalent, only one of them is 5154 valid (in the above example only the first string is valid). 5156 This specification does not describe how the message-id of an article 5157 is determined; it may be deduced from the contents of the article or 5158 derived from some external source. If the server is also conforming 5159 to another specification that contains a definition of message-id 5160 compatible with this one, the server SHOULD use those message-ids. A 5161 common approach, and one that SHOULD be used for email and Netnews 5162 articles, is to extract the message-id from the contents of a header 5163 with name "Message-ID". This may not be as simple as copying the 5164 entire header contents; it may be necessary to strip off comments and 5165 undo quoting, or to reduce "equivalent" message-ids to a canonical 5166 form. 5168 If an article is obtained through the IHAVE command, there will be a 5169 message-id provided with the command. The server MAY either use it 5170 or determine one from the article contents. However, whichever it 5171 does it SHOULD ensure that, if the IHAVE command is repeated with the 5172 same argument and article, it will be recognized as a duplicate. 5174 If an article does not contain a message-id that the server can 5175 identify, it MUST synthesize one. This could, for example, be a 5176 simple sequence number or based on the date and time that the article 5177 arrived. When handling email or Netnews articles, a Message-ID 5178 header SHOULD be added to ensure global consistency and uniqueness. 5180 A.3. Article posting 5182 As far as NNTP is concerned, the POST and IHAVE commands provide the 5183 same basic facilities in a slightly different way. However they have 5184 rather different intentions. 5186 The IHAVE command is intended for transmitting conforming articles 5187 between a system of NNTP servers, with all articles perhaps also 5188 conforming to another specification (e.g. all articles are Netnews 5189 articles). It is expected that the client will have already done any 5190 necessary validation (or has in turn obtained the article from a 5191 third party which has done so); therefore the contents SHOULD be left 5192 unchanged. 5194 In contrast, the POST command is intended for use when an end-user is 5195 injecting a newly-created article into a such a system. The article 5196 being transferred might not be a conforming email or Netnews article, 5197 and the server is expected to validate it and, if necessary, convert 5198 it to the right form for onward distribution. This is often done by 5199 a separate piece of software on the server installation; if so, the 5200 NNTP server SHOULD pass the incoming article to that software 5201 unaltered, making no attempt to filter characters, fold or limit 5202 lines, or otherwise process the incoming text. 5204 The POST command can fail in various ways and clients should be 5205 prepared to re-send an article. When doing so, however, it is often 5206 important to ensure - as far as possible - that the same message-id 5207 is allocated to both attempts so that the server, or other servers, 5208 can recognize the two articles as being duplicates. In the case of 5209 email or Netnews articles, therefore, the posted article SHOULD 5210 contain a header with name "Message-ID" and the contents of this 5211 header SHOULD be identical on each attempt. The server SHOULD ensure 5212 that two POSTed articles with the same contents for this header are 5213 recognized as identical and the same message-id allocated, whether or 5214 not those contents are suitable for use as the message-id. 5216 Appendix B. Summary of Commands 5218 This section contains a list of every command defined in this 5219 document, ordered by command name and by indicating capability. 5221 Ordered by command name: 5223 +-------------------+-----------------------+---------------+ 5224 | Command | Indicating capability | Definition | 5225 +-------------------+-----------------------+---------------+ 5226 | ARTICLE | READER | Section 6.2.1 | 5227 | BODY | READER | Section 6.2.3 | 5228 | CAPABILITIES | mandatory | Section 5.2 | 5229 | DATE | READER | Section 7.1 | 5230 | GROUP | READER | Section 6.1.1 | 5231 | HDR | HDR | Section 8.5 | 5232 | HEAD | mandatory | Section 6.2.2 | 5233 | HELP | mandatory | Section 7.2 | 5234 | IHAVE | IHAVE | Section 6.3.2 | 5235 | LAST | READER | Section 6.1.3 | 5236 | LIST | LIST | Section 7.6.1 | 5237 | LIST ACTIVE.TIMES | LIST | Section 7.6.4 | 5238 | LIST ACTIVE | LIST | Section 7.6.3 | 5239 | LIST DISTRIB.PATS | LIST | Section 7.6.5 | 5240 | LIST HEADERS | HDR | Section 8.6 | 5241 | LIST NEWSGROUPS | LIST | Section 7.6.6 | 5242 | LIST OVERVIEW.FMT | OVER | Section 8.4 | 5243 | LISTGROUP | READER | Section 6.1.2 | 5244 | MODE READER | MODE-READER | Section 5.3 | 5245 | NEWGROUPS | READER | Section 7.3 | 5246 | NEWNEWS | NEWNEWS | Section 7.4 | 5247 | NEXT | READER | Section 6.1.4 | 5248 | OVER | OVER | Section 8.3 | 5249 | POST | POST | Section 6.3.1 | 5250 | QUIT | mandatory | Section 5.4 | 5251 | STAT | mandatory | Section 6.2.4 | 5252 +-------------------+-----------------------+---------------+ 5254 Ordered by indicating capability: 5256 +-------------------+-----------------------+---------------+ 5257 | Command | Indicating capability | Definition | 5258 +-------------------+-----------------------+---------------+ 5259 | CAPABILITIES | mandatory | Section 5.2 | 5260 | HEAD | mandatory | Section 6.2.2 | 5261 | HELP | mandatory | Section 7.2 | 5262 | QUIT | mandatory | Section 5.4 | 5263 | STAT | mandatory | Section 6.2.4 | 5264 | HDR | HDR | Section 8.5 | 5265 | LIST HEADERS | HDR | Section 8.6 | 5266 | IHAVE | IHAVE | Section 6.3.2 | 5267 | LIST | LIST | Section 7.6.1 | 5268 | LIST ACTIVE | LIST | Section 7.6.3 | 5269 | LIST ACTIVE.TIMES | LIST | Section 7.6.4 | 5270 | LIST DISTRIB.PATS | LIST | Section 7.6.5 | 5271 | LIST NEWSGROUPS | LIST | Section 7.6.6 | 5272 | MODE READER | MODE-READER | Section 5.3 | 5273 | NEWNEWS | NEWNEWS | Section 7.4 | 5274 | OVER | OVER | Section 8.3 | 5275 | LIST OVERVIEW.FMT | OVER | Section 8.4 | 5276 | POST | POST | Section 6.3.1 | 5277 | ARTICLE | READER | Section 6.2.1 | 5278 | BODY | READER | Section 6.2.3 | 5279 | DATE | READER | Section 7.1 | 5280 | GROUP | READER | Section 6.1.1 | 5281 | LAST | READER | Section 6.1.3 | 5282 | LISTGROUP | READER | Section 6.1.2 | 5283 | NEWGROUPS | READER | Section 7.3 | 5284 | NEXT | READER | Section 6.1.4 | 5285 +-------------------+-----------------------+---------------+ 5287 Appendix C. Summary of Response Codes 5289 This section contains a list of every response code defined in this 5290 document, whether it is multi-line, which commands can generate it, 5291 what arguments it has, and what its meaning is. 5293 Response code 100 (multi-line) 5294 Generated by: HELP 5295 Meaning: help text follows. 5297 Response code 101 (multi-line) 5298 Generated by: CAPABILITIES 5299 Meaning: capabilities list follows. 5301 Response code 111 5302 Generated by: DATE 5303 1 argument: yyyymmddhhmmss 5304 Meaning: server date and time. 5306 Response code 200 5307 Generated by: initial connection, MODE READER 5308 Meaning: service available, posting allowed. 5310 Response code 201 5311 Generated by: initial connection, MODE READER 5312 Meaning: service available, posting prohibited. 5314 Response code 205 5315 Generated by: QUIT 5316 Meaning: connection closing (the server immediately closes the 5317 connection). 5319 Response code 211 5320 The 211 response code has two completely different forms depending 5321 on which command generated it: 5323 Generated by: GROUP 5324 4 arguments: number low high group 5325 Meaning: group selected. 5327 (multi-line) 5328 Generated by: LISTGROUP 5329 4 arguments: number low high group 5330 Meaning: article numbers follow. 5332 Response code 215 (multi-line) 5333 Generated by: LIST 5334 Meaning: information follows. 5336 Response code 220 (multi-line) 5337 Generated by: ARTICLE 5338 2 arguments: n message-id 5339 Meaning: article follows. 5341 Response code 221 (multi-line) 5342 Generated by: HEAD 5343 2 arguments: n message-id 5344 Meaning: article headers follow. 5346 Response code 222 (multi-line) 5347 Generated by: BODY 5348 2 arguments: n message-id 5349 Meaning: article body follows. 5351 Response code 223 5352 Generated by: LAST, NEXT, STAT 5353 2 arguments: n message-id 5354 Meaning: article exists and selected. 5356 Response code 224 (multi-line) 5357 Generated by: OVER 5358 Meaning: overview information follows. 5360 Response code 225 (multi-line) 5361 Generated by: HDR 5362 Meaning: headers follow. 5364 Response code 230 (multi-line) 5365 Generated by: NEWNEWS 5366 Meaning: list of new articles follows. 5368 Response code 231 (multi-line) 5369 Generated by: NEWGROUPS 5370 Meaning: list of new newsgroups follows. 5372 Response code 235 5373 Generated by: IHAVE (second stage) 5374 Meaning: article transferred OK. 5376 Response code 240 5377 Generated by: POST (second stage) 5378 Meaning: article received OK. 5380 Response code 335 5381 Generated by: IHAVE (first stage) 5382 Meaning: send article to be transferred. 5384 Response code 340 5385 Generated by: POST (first stage) 5386 Meaning: send article to be posted. 5388 Response code 400 5389 Generic response and generated by initial connection 5390 Meaning: service not available or no longer available (the server 5391 immediately closes the connection). 5393 Response code 401 5394 Generic response 5395 1 argument: capability-label 5396 Meaning: the server is in the wrong mode; the indicated capability 5397 should be used to change the mode. 5399 Response code 403 5400 Generic response 5401 Meaning: internal fault or problem preventing action being taken. 5403 Response code 411 5404 Generated by: GROUP, LISTGROUP 5405 Meaning: no such newsgroup. 5407 Response code 412 5408 Generated by: ARTICLE, BODY, GROUP, HDR, HEAD, LAST, LISTGROUP, 5409 NEXT, OVER, STAT 5410 Meaning: no newsgroup selected. 5412 Response code 420 5413 Generated by: ARTICLE, BODY, HDR, HEAD, LAST, NEXT, OVER, STAT 5414 Meaning: current article number is invalid. 5416 Response code 421 5417 Generated by: NEXT 5418 Meaning: no next article in this group. 5420 Response code 422 5421 Generated by: LAST 5422 Meaning: no previous article in this group. 5424 Response code 423 5425 Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT 5426 Meaning: no article with that number or in that range. 5428 Response code 430 5429 Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT 5430 Meaning: no article with that message-id. 5432 Response code 435 5433 Generated by: IHAVE (first stage) 5434 Meaning: article not wanted. 5436 Response code 436 5437 Generated by: IHAVE (either stage) 5438 Meaning: transfer not possible (first stage) or failed (second 5439 stage); try again later. 5441 Response code 437 5442 Generated by: IHAVE (second stage) 5443 Meaning: transfer rejected; do not retry. 5445 Response code 440 5446 Generated by: POST (first stage) 5447 Meaning: posting not permitted. 5449 Response code 441 5450 Generated by: POST (second stage) 5451 Meaning: posting failed. 5453 Response code 480 5454 Generic response 5455 Meaning: command unavailable until the client has authenticated 5456 itself. 5458 Response code 483 5459 Generic response 5460 Meaning: command unavailable until suitable privacy has been 5461 arranged. 5463 Response code 500 5464 Generic response 5465 Meaning: unknown command. 5467 Response code 501 5468 Generic response 5469 Meaning: syntax error in command. 5471 Response code 502 5472 Generic response and generated by initial connection 5473 Meaning for the initial connection and the MODE READER command: 5474 service permanently unavailable (the server immediately closes the 5475 connection). 5477 Meaning for all other commands: command not permitted (and there 5478 is no way for the client to change this). 5480 Response code 503 5481 Generic response 5482 Meaning: feature not supported. 5484 Response code 504 5485 Generic response 5486 Meaning: error in base64-encoding [RFC3548] of an argument 5488 Appendix D. Changes from RFC 977 5490 In general every attempt has been made to ensure that the protocol 5491 specification in this document is compatible with the version 5492 specified in RFC 977 [RFC977] and the various facilities adopted from 5493 RFC 2980 [RFC2980]. However, there have been a number of changes, 5494 some compatible and some not. 5496 This appendix lists these changes. It is not guaranteed to be 5497 exhaustive or correct and MUST NOT be relied on. 5499 o A formal syntax specification (Section 9) has been added. 5501 o The default character set is changed from US-ASCII [ANSI1986] to 5502 UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8). This 5503 matter is discussed further in Section 10. 5505 o All articles are required to have a message-id, eliminating the 5506 "<0>" placeholder used in RFC 977 in some responses. 5508 o The newsgroup name matching capabilities already documented in 5509 RFC 977 ("wildmats" (Section 4)) are clarified and extended. The 5510 new facilities (e.g. the use of commas and exclamation marks) are 5511 allowed wherever wildmats appear in the protocol. 5513 o Support for pipelining of commands (Section 3.5) is made 5514 mandatory. 5516 o The principles behind response codes (Section 3.2) have been 5517 tidied up. In particular: 5518 * the x8x response code family, formerly used for private 5519 extensions, is now reserved for authentication and privacy 5520 extensions; 5521 * the x9x response code family, formerly intended for debugging 5522 facilities, are now reserved for private extensions; 5523 * the 502 and 503 generic response codes (Section 3.2.1) have 5524 been redefined; 5525 * new 401, 403, 480, 483, and 504 generic response codes have 5526 been added. 5528 o The rules for article numbering (Section 6) have been clarified 5529 (also see Section 6.1.1.2). 5531 o The SLAVE command (which was ill-defined) is removed from the 5532 protocol. 5534 o Four-digit years are permitted in the NEWNEWS (Section 7.4) and 5535 NEWGROUPS (Section 7.3) commands (two-digit years are still 5536 permitted). The optional distribution parameter to these commands 5537 has been removed. 5539 o The LIST (Section 7.6.1) command is greatly extended; the original 5540 is available as LIST ACTIVE, while new variants include 5541 ACTIVE.TIMES, DISTRIB.PATS, and NEWSGROUPS. A new "m" status flag 5542 is added to the LIST ACTIVE response. 5544 o A new CAPABILITIES (Section 5.2) command allows clients to 5545 determine what facilities are supported by a server. 5547 o The DATE (Section 7.1) command is adopted from RFC 2980 5548 effectively unchanged. 5550 o The LISTGROUP (Section 6.1.2) command is adopted from RFC 2980. 5551 An optional range argument has been added, and the 211 initial 5552 response line now has the same format as the 211 response from the 5553 GROUP command. 5555 o The MODE READER (Section 5.3) command is adopted from RFC 2980 and 5556 its meaning and effects clarified. 5558 o The XHDR command in RFC 2980 has been formalised as the new HDR 5559 (Section 8.5) and LIST HEADERS (Section 8.6) commands. 5561 o The XOVER command in RFC 2980 has been formalised as the new OVER 5562 (Section 8.3) and LIST OVERVIEW.FMT (Section 8.4) commands. The 5563 former can be applied to a message-id as well as to a range. 5565 o The concept of article metadata (Section 8.1) has been formalised, 5566 allowing the Bytes and Lines pseudo-headers to be deprecated. 5568 Client authors should note in particular that lack of support for the 5569 CAPABILITIES command is a good indication that the server does not 5570 support this specification. 5572 Author's Address 5574 Clive D.W. Feather 5575 Thus plc 5576 322 Regents Park Road 5577 London N3 2QQ 5578 GB 5580 Phone: +44 20 8495 6138 5581 Fax: +44 870 051 9937 5582 Email: clive@demon.net 5583 URI: http://www.davros.org/ 5585 Intellectual Property Statement 5587 The IETF takes no position regarding the validity or scope of any 5588 Intellectual Property Rights or other rights that might be claimed to 5589 pertain to the implementation or use of the technology described in 5590 this document or the extent to which any license under such rights 5591 might or might not be available; nor does it represent that it has 5592 made any independent effort to identify any such rights. Information 5593 on the procedures with respect to rights in RFC documents can be 5594 found in BCP 78 and BCP 79. 5596 Copies of IPR disclosures made to the IETF Secretariat and any 5597 assurances of licenses to be made available, or the result of an 5598 attempt made to obtain a general license or permission for the use of 5599 such proprietary rights by implementers or users of this 5600 specification can be obtained from the IETF on-line IPR repository at 5601 http://www.ietf.org/ipr. 5603 The IETF invites any interested party to bring to its attention any 5604 copyrights, patents or patent applications, or other proprietary 5605 rights that may cover technology that may be required to implement 5606 this standard. Please address the information to the IETF at 5607 ietf-ipr@ietf.org. 5609 Disclaimer of Validity 5611 This document and the information contained herein are provided on an 5612 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 5613 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 5614 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 5615 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 5616 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 5617 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5619 Copyright Statement 5621 Copyright (C) The Internet Society (2005). This document is subject 5622 to the rights, licenses and restrictions contained in BCP 78, and 5623 except as set forth therein, the authors retain all their rights. 5625 Acknowledgment 5627 Funding for the RFC Editor function is currently provided by the 5628 Internet Society.