idnits 2.17.1 draft-ietf-nntpext-base-27.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 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 5659. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 5636. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 5643. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 5649. ** 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 ([NNTP-AUTH], [NNTP-STREAM], [RFC2234], [NNTP-TLS], [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. -- The draft header indicates that this document obsoletes RFC977, but the abstract doesn't seem to directly say this. It does mention RFC977 though, so this could be OK. -- The draft header indicates that this document updates RFC2980, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 238 has weird spacing: '...cal|bar indic...' == Line 1233 has weird spacing: '...abc,def the t...' == Line 1350 has weird spacing: '...keyword addi...' == Line 1647 has weird spacing: '... group nam...' == Line 1648 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. (Using the creation date from RFC2980, updated by this document, for RFC5378 checks: 1997-10-13) -- 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 (June 8, 2005) is 6868 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 5210, but not defined == Missing Reference: 'S' is mentioned on line 5220, but not defined -- Looks like a reference, but probably isn't: '1' on line 3073 -- Looks like a reference, but probably isn't: '2' on line 1268 == Missing Reference: 'GMT' is mentioned on line 2945, 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 (==), 19 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 Updates: 2980 (if approved) June 8, 2005 5 Obsoletes: 977 (if approved) 6 Expires: December 10, 2005 8 Network News Transfer Protocol 9 draft-ietf-nntpext-base-27 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on December 10, 2005. 36 Copyright Notice 38 Copyright (C) The Internet Society (2005). 40 Abstract 42 The Network News Transfer Protocol (NNTP) has been in use in the 43 Internet for a decade and remains one of the most popular protocols 44 (by volume) in use today. This document is a replacement for RFC 977 45 and officially updates the protocol specification. It clarifies some 46 vagueness in RFC 977, includes some new base functionality, and 47 provides a specific mechanism to add standardized extensions to NNTP. 49 Administration 51 This document is a product of the NNTP Working Group, chaired by Russ 52 Allbery and Ned Freed. 54 Author's Note 56 This document is written in XML using an NNTP-specific DTD. Custom 57 software is used to convert this to RFC 2629 [RFC2629] format, and 58 then the public "xml2rfc" package to further reduce this to text, 59 nroff source, and HTML. 61 No perl was used in producing this document. 63 Rights 65 UNIX is a registered trademark of The Open Group. 67 Note to the RFC Editor 69 The normative reference to RFC 2234 [RFC2234] and the informative 70 reference to RFC 2629 [RFC2629] may be replaced by 71 draft-crocker-abnf-rfc2234bis and draft-mrose-writing-rfcs 72 respectively should either or both of those documents reach RFC 73 status before this one. 75 The informative references to [NNTP-AUTH], [NNTP-STREAM], and [NNTP- 76 TLS] are documents which are expected to be published simultaneously 77 with this one and so can be replaced by references to the resulting 78 RFCs. 80 Table of Contents 82 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 83 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 7 84 3. Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . 9 85 3.1. Commands and Responses . . . . . . . . . . . . . . . . . 9 86 3.1.1. Multi-line data blocks . . . . . . . . . . . . . . . 10 87 3.2. Response Codes . . . . . . . . . . . . . . . . . . . . . 11 88 3.2.1. Generic Response Codes . . . . . . . . . . . . . . . 13 89 3.2.1.1. Examples . . . . . . . . . . . . . . . . . . . . 14 90 3.3. Capabilities and Extensions . . . . . . . . . . . . . . . 16 91 3.3.1. Capability descriptions . . . . . . . . . . . . . . . 17 92 3.3.2. Standard capabilities . . . . . . . . . . . . . . . . 17 93 3.3.3. Extensions . . . . . . . . . . . . . . . . . . . . . 19 94 3.3.4. Initial IANA register . . . . . . . . . . . . . . . . 20 95 3.4. Mandatory and Optional Commands . . . . . . . . . . . . . 22 96 3.4.1. Reading and Transit Servers . . . . . . . . . . . . . 22 97 3.4.2. Mode switching . . . . . . . . . . . . . . . . . . . 23 98 3.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 24 99 3.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 25 100 3.6. Articles . . . . . . . . . . . . . . . . . . . . . . . . 25 101 4. The WILDMAT format . . . . . . . . . . . . . . . . . . . . . 28 102 4.1. Wildmat syntax . . . . . . . . . . . . . . . . . . . . . 28 103 4.2. Wildmat semantics . . . . . . . . . . . . . . . . . . . . 28 104 4.3. Extensions . . . . . . . . . . . . . . . . . . . . . . . 29 105 4.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 30 106 5. Session administration commands . . . . . . . . . . . . . . . 31 107 5.1. Initial Connection . . . . . . . . . . . . . . . . . . . 31 108 5.2. CAPABILITIES . . . . . . . . . . . . . . . . . . . . . . 32 109 5.3. MODE READER . . . . . . . . . . . . . . . . . . . . . . . 35 110 5.4. QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . 37 111 6. Article posting and retrieval . . . . . . . . . . . . . . . . 38 112 6.1. Group and article selection . . . . . . . . . . . . . . . 38 113 6.1.1. GROUP . . . . . . . . . . . . . . . . . . . . . . . . 39 114 6.1.2. LISTGROUP . . . . . . . . . . . . . . . . . . . . . . 42 115 6.1.3. LAST . . . . . . . . . . . . . . . . . . . . . . . . 44 116 6.1.4. NEXT . . . . . . . . . . . . . . . . . . . . . . . . 46 117 6.2. Retrieval of articles and article sections . . . . . . . 47 118 6.2.1. ARTICLE . . . . . . . . . . . . . . . . . . . . . . . 48 119 6.2.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 51 120 6.2.3. BODY . . . . . . . . . . . . . . . . . . . . . . . . 53 121 6.2.4. STAT . . . . . . . . . . . . . . . . . . . . . . . . 55 122 6.3. Article posting . . . . . . . . . . . . . . . . . . . . . 58 123 6.3.1. POST . . . . . . . . . . . . . . . . . . . . . . . . 58 124 6.3.2. IHAVE . . . . . . . . . . . . . . . . . . . . . . . . 60 125 7. Information commands . . . . . . . . . . . . . . . . . . . . 64 126 7.1. DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 64 127 7.2. HELP . . . . . . . . . . . . . . . . . . . . . . . . . . 65 128 7.3. NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 65 129 7.4. NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 67 130 7.5. Time . . . . . . . . . . . . . . . . . . . . . . . . . . 68 131 7.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 68 132 7.6. The LIST commands . . . . . . . . . . . . . . . . . . . . 69 133 7.6.1. LIST . . . . . . . . . . . . . . . . . . . . . . . . 69 134 7.6.2. Standard LIST keywords . . . . . . . . . . . . . . . 72 135 7.6.3. LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . 73 136 7.6.4. LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . 74 137 7.6.5. LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . 75 138 7.6.6. LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . 75 139 8. Article field access commands . . . . . . . . . . . . . . . . 77 140 8.1. Article metadata . . . . . . . . . . . . . . . . . . . . 77 141 8.1.1. The :bytes metadata item . . . . . . . . . . . . . . 77 142 8.1.2. The :lines metadata item . . . . . . . . . . . . . . 78 143 8.2. Database consistency . . . . . . . . . . . . . . . . . . 78 144 8.3. OVER . . . . . . . . . . . . . . . . . . . . . . . . . . 79 145 8.4. LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 83 146 8.5. HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 147 8.6. LIST HEADERS . . . . . . . . . . . . . . . . . . . . . . 90 148 9. Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . . . 93 149 9.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 93 150 9.2. Commands . . . . . . . . . . . . . . . . . . . . . . . . 93 151 9.3. Command continuation . . . . . . . . . . . . . . . . . . 95 152 9.4. Responses . . . . . . . . . . . . . . . . . . . . . . . . 95 153 9.4.1. Generic responses . . . . . . . . . . . . . . . . . . 95 154 9.4.2. Initial response line contents . . . . . . . . . . . 96 155 9.4.3. Multi-line response contents . . . . . . . . . . . . 97 156 9.5. Capability lines . . . . . . . . . . . . . . . . . . . . 98 157 9.6. LIST variants . . . . . . . . . . . . . . . . . . . . . . 99 158 9.7. Articles . . . . . . . . . . . . . . . . . . . . . . . . 100 159 9.8. General non-terminals . . . . . . . . . . . . . . . . . . 100 160 9.9. Extensions and Validation . . . . . . . . . . . . . . . . 102 161 10. Internationalisation Considerations . . . . . . . . . . . . . 104 162 10.1. Introduction and historical situation . . . . . . . . . . 104 163 10.2. This specification . . . . . . . . . . . . . . . . . . . 104 164 10.3. Outstanding issues . . . . . . . . . . . . . . . . . . . 106 165 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 107 166 12. Security Considerations . . . . . . . . . . . . . . . . . . . 108 167 12.1. Personal and Proprietary Information . . . . . . . . . . 108 168 12.2. Abuse of Server Log Information . . . . . . . . . . . . . 108 169 12.3. Weak Authentication and Access Control . . . . . . . . . 108 170 12.4. DNS Spoofing . . . . . . . . . . . . . . . . . . . . . . 109 171 12.5. UTF-8 issues . . . . . . . . . . . . . . . . . . . . . . 109 172 12.6. Caching of capability lists . . . . . . . . . . . . . . . 110 173 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 112 174 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 115 175 14.1. Normative References . . . . . . . . . . . . . . . . . . 115 176 14.2. Informative References . . . . . . . . . . . . . . . . . 115 177 A. Interaction with other specifications . . . . . . . . . . . . 117 178 A.1. Header folding . . . . . . . . . . . . . . . . . . . . . 117 179 A.2. Message-IDs . . . . . . . . . . . . . . . . . . . . . . . 117 180 A.3. Article posting . . . . . . . . . . . . . . . . . . . . . 119 181 B. Summary of Commands . . . . . . . . . . . . . . . . . . . . . 120 182 C. Summary of Response Codes . . . . . . . . . . . . . . . . . . 122 183 D. Changes from RFC 977 . . . . . . . . . . . . . . . . . . . . 127 184 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 129 185 Intellectual Property and Copyright Statements . . . . . . . . . 130 187 1. Introduction 189 This document specifies the Network News Transfer Protocol (NNTP), 190 which is used for the distribution, inquiry, retrieval, and posting 191 of Netnews articles using a reliable stream-based mechanism. For 192 news reading clients, NNTP enables retrieval of news articles that 193 are stored in a central database, giving subscribers the ability to 194 select only those articles they wish to read. 196 The Netnews model provides for indexing, cross-referencing, and 197 expiration of aged messages. NNTP is designed for efficient 198 transmission of Netnews articles over a reliable full duplex 199 communication channel. 201 While the protocol specification in this document is largely 202 compatible with the version specified in RFC 977 [RFC977], there are 203 a number of changes which are summarised in Appendix D. In 204 particular: 205 o the default character set is changed from US-ASCII [ANSI1986] to 206 UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8); 207 o a number of commands that were optional in RFC 977 or have been 208 taken from RFC 2980 [RFC2980] are now mandatory; 209 o a CAPABILITIES command has been added to allow clients to 210 determine what functionality is available from a server. 212 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 213 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 214 document are to be interpreted as described in RFC 2119 [RFC2119]. 216 An implementation is not compliant if it fails to satisfy one or more 217 of the MUST requirements for this protocol. An implementation that 218 satisfies all the MUST and all the SHOULD requirements for its 219 protocols is said to be "unconditionally compliant"; one that 220 satisfies all the MUST requirements but not all the SHOULD 221 requirements for NNTP is said to be "conditionally compliant". 223 For the remainder of this document, the term "client" or "client 224 host" refers to a host making use of the NNTP service, while the term 225 "server" or "server host" refers to a host that offers the NNTP 226 service. 228 2. Notation 230 The following notational conventions are used in this document. 232 UPPERCASE indicates literal text to be included in the 233 command; 234 lowercase indicates a token described elsewhere; 235 [brackets] indicate that the argument is optional; 236 ellipsis... indicates that the argument may be repeated any 237 number of times (it must occur at least once); 238 vertical|bar indicates a choice of two mutually exclusive 239 arguments (exactly one must be provided). 241 The name "message-id" for a command or response argument indicates 242 that it is the message-id of an article as described in Section 3.6, 243 including the angle brackets. 245 The name "wildmat" for an argument indicates that it is a wildmat as 246 defined in Section 4. If the argument does not meet the requirements 247 of that section (for example, if it does not fit the grammar of 248 Section 4.1) the NNTP server MAY place some interpretation on it (not 249 specified by this document) or otherwise MUST treat it as a syntax 250 error. 252 Responses for each command will be described in tables listing the 253 required format of a response followed by the meaning that should be 254 ascribed to that response. 256 The terms "NUL", "TAB", "LF", "CR, and "space" refer to the octets 257 %x00, %x09, %x0A, %x0D, and %x20 respectively (that is, the octets 258 with those codes in US-ASCII [ANSI1986] and thus UTF-8 [RFC3629]). 259 The term "CRLF" or "CRLF pair" means the sequence CR immediately 260 followed by LF (that is, %x0D.0A). A "printable US-ASCII character" 261 is an octet in the range %x21-7E. Quoted characters refer to the 262 octets with those codes in US-ASCII (so "." and "<" refer to %x2E and 263 %x3C) and will always be printable US-ASCII characters; similarly, 264 "digit" refers to the octets %x30-39. 266 A "keyword" MUST consist only of US-ASCII letters, digits, and the 267 characters dot (".") and dash ("-"), and MUST begin with a letter. 268 Keywords MUST be at least three characters and MUST NOT exceed 12 269 characters. 271 Examples in this document are not normative but serve to illustrate 272 usages, arguments, and responses. In the examples, a "[C]" will be 273 used to represent the client host and a "[S]" will be used to 274 represent the server host. Most of the examples do not rely on a 275 particular server state. In some cases, however, they do assume that 276 the currently selected newsgroup (see the GROUP command 277 (Section 6.1.1)) is invalid; when so, this is indicated at the start 278 of the example. Examples may use commands or other keywords not 279 defined in this specification (such as an XENCRYPT command). These 280 will be used to illustrate some point and do not imply that any such 281 command is defined elsewhere or needs to exist in any particular 282 implementation. 284 Terms which might be read as specifying details of a client or server 285 implementation, such as "database", are used simply to ease 286 description. Providing that implementations conform to the protocol 287 and format specifications in this document, no specific technique is 288 mandated. 290 3. Basic Concepts 292 3.1. Commands and Responses 294 NNTP operates over any reliable bidirectional 8-bit-wide data stream 295 channel. When the connection is established, the NNTP server host 296 MUST send a greeting. The client host and server host then exchange 297 commands and responses (respectively) until the connection is closed 298 or aborted. If the connection used is TCP, then the server host 299 starts the NNTP service by listening on a TCP port. When a client 300 host wishes to make use of the service, it MUST establish a TCP 301 connection with the server host by connecting to that host on the 302 same port on which the server is listening. 304 The character set for all NNTP commands is UTF-8 [RFC3629]. Commands 305 in NNTP MUST consist of a keyword, which MAY be followed by one or 306 more arguments. A CRLF pair MUST terminate all commands. Multiple 307 commands MUST NOT be on the same line. Unless otherwise noted 308 elsewhere in this document, arguments SHOULD consist of printable US- 309 ASCII characters. Keywords and arguments MUST be each separated by 310 one or more space or TAB characters. Command lines MUST NOT exceed 311 512 octets, which includes the terminating CRLF pair. The arguments 312 MUST NOT exceed 497 octets. A server MAY relax these limits for 313 commands defined in an extension. 315 Where this specification permits UTF-8 characters outside the range 316 U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark 317 (U+FEFF, encoding %xEF.BB.BF), and MUST use the Word Joiner (U+2060, 318 encoding %xE2.91.A0) for the meaning Zero Width No-Break Space, in 319 command lines and the initial lines of responses, and SHOULD apply 320 these same principles throughout. 322 The term "character" means a single Unicode code point and 323 implementations are not required to carry out normalisation. Thus 324 U+0084 (A-dieresis) is one character while U+0041 U+0308 (A composed 325 with dieresis) is two; the two need not be treated as equivalent. 327 Commands may have variants, using a second keyword immediately after 328 the first to indicate which variant is required. The only such 329 commands in this specification are LIST and MODE. Note that such 330 variants are sometimes referred to as if they were commands in their 331 own right: "the LIST ACTIVE" command should be read as shorthand for 332 "the ACTIVE variant of the LIST command". 334 Keywords are case-insensitive; the case of keywords for commands MUST 335 be ignored by the server. Command and response arguments are case- 336 or language-specific only when stated, either in this document or in 337 other relevant specifications. 339 In some cases a command involves more data than just a single line. 340 The further data may be sent either immediately after the command 341 line (there are no instances of this in this specification, but there 342 are in extensions such as [NNTP-STREAM]) or following a request from 343 the server (indicated by a 3xx response). 345 Each response MUST start with a three-digit response code that is 346 sufficient to distinguish all responses. Certain valid responses are 347 defined to be multi-line; for all others, the response is contained 348 in a single line. The initial line of the response MUST NOT exceed 349 512 octets, which includes the response code and the terminating CRLF 350 pair; an extension MAY specify a greater maximum for commands that it 351 defines, but not for any other command. Single-line responses 352 consist of an initial line only. Multi-line responses consist of an 353 initial line followed by a multi-line data block. 355 An NNTP server MAY have an inactivity autologout timer. Such a timer 356 SHOULD be of at least three minutes duration, with the exception that 357 there MAY be a shorter limit on how long the server is willing to 358 wait for the first command from the client. The receipt of any 359 command from the client during the timer interval SHOULD suffice to 360 reset the autologout timer. Similarly, the receipt of any 361 significant amount of data from a client that is sending a multi-line 362 data block (such as during a POST or IHAVE command) SHOULD suffice to 363 reset the autologout timer. When the timer expires, the server 364 SHOULD close the connection without sending any response to the 365 client. 367 3.1.1. Multi-line data blocks 369 A multi-line data block is used in certain commands and responses. 370 It MUST adhere to the following rules: 372 1. The block consists of a sequence of zero or more "lines", each 373 being a stream of octets ending with a CRLF pair. Apart from 374 those line endings, the stream MUST NOT include the octets NUL, 375 LF, or CR. 377 2. In a multi-line response, the block immediately follows the CRLF 378 at the end of the initial line of the response. When used in any 379 other context, the specific command will define when the block is 380 sent. 382 3. If any line of the data block begins with the "termination octet" 383 ("." or %x2E), that line MUST be "dot-stuffed" by pre-pending an 384 additional termination octet to that line of the block. 386 4. The lines of the block MUST be followed by a terminating line 387 consisting of a single termination octet followed by a CRLF pair 388 in the normal way. Thus, unless it is empty, a multi-line block 389 is always terminated with the five octets CRLF "." CRLF 390 (%x0D.0A.2E.0D.0A). 392 5. When interpreting a multi-line block, the "dot-stuffing" MUST be 393 undone; i.e. the recipient MUST ensure that, in any line 394 beginning with the termination octet followed by octets other 395 than a CRLF pair, that initial termination octet is disregarded. 397 6. Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT 398 be considered part of the multi-line block; i.e. the recipient 399 MUST ensure that any line beginning with the termination octet 400 followed immediately by a CRLF pair is disregarded; (the first 401 CRLF pair of the terminating CRLF "." CRLF of a non-empty block 402 is, of course, part of the last line of the block). 404 Note that texts using an encoding (such as UTF-16 or UTF-32) that may 405 contain the octets NUL, LF, or CR other than a CRLF pair cannot be 406 reliably conveyed in the above format (that is, they violate the MUST 407 requirement above). However, except when stated otherwise, this 408 specification does not require the content to be UTF-8 and therefore 409 (subject to that same requirement) it MAY include octets above and 410 below 128 mixed arbitrarily. 412 This document does not place any limit on the length of a line in a 413 multi-line block. However, the standards that define the format of 414 articles may do so. 416 3.2. Response Codes 418 Each response MUST begin with a three-digit status indicator. These 419 are status reports from the server and indicate the response to the 420 last command received from the client. 422 The first digit of the response broadly indicates the success, 423 failure, or progress of the previous command: 425 1xx - Informative message. 426 2xx - Command completed OK. 427 3xx - Command OK so far; send the rest of it. 428 4xx - Command was syntactically correct but failed for some 429 reason. 430 5xx - Command unknown, unsupported, unavailable, or syntax error. 432 The next digit in the code indicates the function response category: 434 x0x - Connection, set-up, and miscellaneous messages 435 x1x - Newsgroup selection 436 x2x - Article selection 437 x3x - Distribution functions 438 x4x - Posting 439 x8x - Reserved for authentication and privacy extensions 440 x9x - Reserved for private use (non-standard extensions) 442 Certain responses contain arguments such as numbers and names in 443 addition to the status indicator. In those cases, to simplify 444 interpretation by the client the number and type of such arguments is 445 fixed for each response code, as is whether or not the code is 446 single-line or multi-line. Any extension MUST follow this principle 447 as well. Note that, for historical reasons, the 211 response code is 448 an exception to this in that the response may be single-line or 449 multi-line depending on the command (GROUP or LISTGROUP) that 450 generated it. In all other cases, the client MUST only use the 451 status indicator itself to determine the nature of the response. The 452 exact response codes that can be returned by any given command are 453 detailed in the description of that command. 455 Arguments MUST be separated from the numeric status indicator and 456 from each other by a single space. All numeric arguments MUST be in 457 base 10 (decimal) format, and MAY have leading zeros. String 458 arguments MUST contain at least one character and MUST NOT contain 459 TAB, LF, CR, or space. The server MAY add any text after the 460 response code or last argument as appropriate, and the client MUST 461 NOT make decisions based on this text. Such text MUST be separated 462 from the numeric status indicator or the last argument by at least 463 one space. 465 The server MUST respond to any command with the appropriate generic 466 response (given in Section 3.2.1) if it represents the situation. 467 Otherwise, each recognized command MUST return one of the response 468 codes specifically listed in its description or in an extension. A 469 server MAY provide extensions to this specification, including new 470 commands, new variants or features of existing commands, and other 471 ways of changing the internal state of the server. However, the 472 server MUST NOT produce any other responses to a client that does not 473 invoke any of the additional features. (Therefore a client that 474 restricts itself to this specification will only receive the 475 responses that are listed.) 477 If a client receives an unexpected response, it SHOULD use the first 478 digit of the response to determine the result. For example, an 479 unexpected 2xx should be taken as success and an unexpected 4xx or 480 5xx as failure. 482 Response codes not specified in this document MAY be used for any 483 installation-specific additional commands also not specified. These 484 SHOULD be chosen to fit the pattern of x9x specified above. 486 Neither this document nor any registered extension (see 487 Section 3.3.3) will specify any response codes of the x9x pattern. 488 (Implementers of extensions are accordingly cautioned not to use such 489 responses for extensions that may subsequently be submitted for 490 registration.) 492 3.2.1. Generic Response Codes 494 The server MUST respond to any command with the appropriate one of 495 the following generic responses if it represents the situation. 497 If the command is not recognized, or it is an optional command that 498 is not implemented by the server, the response code 500 MUST be 499 returned. 501 If there is a syntax error in the arguments of a recognized command, 502 including the case where more arguments are provided than the command 503 specifies or the command line is longer than the server accepts, the 504 response code 501 MUST be returned. The line MUST NOT be truncated 505 or split and then interpreted. Note that where a command has 506 variants depending on a second keyword (e.g. LIST ACTIVE and LIST 507 NEWSGROUPS), then 501 MUST be used when the base command is 508 implemented but the requested variant is not, and 500 MUST be used 509 only when the base command itself is not implemented. 511 As a special case, if an argument is required to be a base64-encoded 512 string [RFC3548] (there are no such arguments in this specification, 513 but there may be in extensions) and is not validly encoded, the 514 response code 504 MUST be returned. 516 If the server experiences an internal fault or problem that means it 517 is unable to carry out the command (for example, a necessary file is 518 missing or a necessary service could not be contacted), the response 519 code 403 MUST be returned. If the server recognizes the command but 520 does not provide an optional feature (for example because it does not 521 store the required information), or only handles a subset of 522 legitimate cases (see the HDR command (Section 8.5) for an example), 523 the response code 503 MUST be returned. 525 If the client is not authorized to use the specified facility when 526 the server is in its current state, then the appropriate one of the 527 following response codes MUST be used. 529 502: it is necessary to terminate the connection and start a new one 530 with the appropriate authority before the command can be used. 531 Historically, some mode-switching servers (see Section 3.4.1) have 532 used this response to indicate that this command will become 533 available after the MODE READER (Section 5.3) command is used, but 534 this usage is not conforming to this specification and MUST NOT be 535 used. Note that the server MUST NOT close the connection 536 immediately after a 502 response except at the initial connection 537 (Section 5.1) and with the MODE READER command. 539 480: the client must authenticate itself to the server (that is, 540 provide information as to the identity of the client) before the 541 facility can be used on this connection. This will involve the 542 use of an authentication extension such as [NNTP-AUTH]. 544 483: the client must negotiate appropriate privacy protection on the 545 connection. This will involve the use of a privacy extension such 546 as [NNTP-TLS]. 548 401: the client must change the state of the connection in some other 549 manner. The first argument of the response MUST be the capability 550 label (see Section 5.2) of the facility (usually an extension, 551 which may be a private extension) that provides the necessary 552 mechanism. The server MUST NOT use this response code except as 553 specified by the definition of the capability in question. 555 If the server has to terminate the connection for some reason, it 556 MUST give a 400 response code to the next command and then 557 immediately close the connection. Following a 400 response, clients 558 SHOULD NOT simply reconnect immediately and retry the same actions. 559 Rather, a client SHOULD either use an exponentially increasing delay 560 between retries (e.g. double the waiting time after each 400 561 response) or present any associated text to the user for them to 562 decide whether and when to retry. 564 The client MUST be prepared to receive any of these responses for any 565 command (except, of course, that the server MUST NOT generate a 500 566 response code for mandatory commands). 568 3.2.1.1. Examples 570 Example of an unknown command: 572 [C] MAIL 573 [S] 500 Unknown command 575 Example of an unsupported command: 577 [C] CAPABILITIES 578 [S] 101 Capability list: 579 [S] VERSION 2 580 [S] READER 581 [S] NEWNEWS 582 [S] LIST ACTIVE NEWSGROUPS 583 [S] . 584 [C] OVER 585 [S] 500 Unknown command 587 Example of an unsupported variant: 589 [C] MODE POSTER 590 [S] 501 Unknown MODE option 592 Example of a syntax error: 594 [C] ARTICLE a.message.id@no.angle.brackets 595 [S] 501 Syntax error 597 Example of an overlong command line: 599 [C] HEAD 53 54 55 600 [S] 501 Too many arguments 602 Example of a bad wildmat: 604 [C] LIST ACTIVE u[ks].* 605 [S] 501 Syntax error 607 Example of a base64-encoding error (the second argument is meant to 608 be base64-encoded): 610 [C] XENCRYPT RSA abcd=efg 611 [S] 504 Base64 encoding error 613 Example of an attempt to access a facility not available to this 614 connection: 616 [C] MODE READER 617 [S] 200 Reader mode, posting permitted 618 [C] IHAVE 619 [S] 500 Permission denied 621 Example of an attempt to access a facility requiring authentication: 623 [C] GROUP secret.group 624 [S] 480 Permission denied 626 followed by a successful attempt following such authentication: 628 [C] XSECRET fred flintstone 629 [S] 290 Password for fred accepted 630 [C] GROUP secret.group 631 [S] 211 5 1 20 secret.group selected 633 Example of an attempt to access a facility requiring privacy: 635 [C] GROUP secret.group 636 [S] 483 Secure connection required 637 [C] XENCRYPT 638 [Client and server negotiate encryption on the link] 639 [S] 283 Encrypted link established 640 [C] GROUP secret.group 641 [S] 211 5 1 20 secret.group selected 643 Example of a need to change mode before using a facility: 645 [C] GROUP binary.group 646 [S] 401 XHOST Not on this virtual host 647 [C] XHOST binary.news.example.org 648 [S] 290 binary.news.example.org virtual host selected 649 [C] GROUP binary.group 650 [S] 211 5 1 77 binary.group selected 652 Example of a temporary failure: 654 [C] GROUP archive.local 655 [S] 403 Archive server temporarily offline 657 Example of the server needing to close down immediately: 659 [C] ARTICLE 123 660 [S] 400 Power supply failed, running on UPS 661 [Server closes connection.] 663 3.3. Capabilities and Extensions 665 Not all NNTP servers provide exactly the same facilities, both 666 because this specification allows variation and because servers may 667 provide extensions. A set of facilities that are related are called 668 a "capability". This specification provides a way to determine what 669 capabilities are available, includes a list of standard capabilities, 670 and includes a mechanism (the extension mechanism) for defining new 671 capabilities. 673 3.3.1. Capability descriptions 675 A client can determine the available capabilities of the server by 676 using the CAPABILITIES command (Section 5.2). This returns a 677 capability list, which is a list of capability lines. Each line 678 describes one available capability. 680 Each capability line consists of one or more tokens, which MUST be 681 separated by one or more space or TAB characters. A token is a 682 string of 1 or more printable UTF-8 characters (that is, either 683 printable US-ASCII characters or any UTF-8 sequence outside the US- 684 ASCII range, but not space or TAB). Unless stated otherwise, tokens 685 are case-insensitive. Each capability line consists of: 686 o The capability label, which is a keyword indicating the 687 capability. A capability label may be defined by this 688 specification or a successor, or may be defined by an extension. 689 o The label is then followed by zero or more tokens, which are 690 arguments of the capability. The form and meaning of these tokens 691 is specific to each capability. 693 The server MUST ensure that the capability list accurately reflects 694 the capabilities (including extensions) currently available. If a 695 capability is only available with the server in a certain state (for 696 example, only after authentication), the list MUST only include the 697 capability label when in that state. Similarly, if only some of the 698 commands in an extension will be available, or if the behaviour of 699 the extension will change in some other manner, according to the 700 state of the server, this MUST be indicated by different arguments in 701 the capability line. 703 Note that a capability line can only begin with a letter. Lines 704 beginning with other characters are reserved for future versions of 705 this specification. In order to interoperate with such versions, 706 clients MUST be prepared to receive lines beginning with other 707 characters and MUST ignore any they do not understand. 709 3.3.2. Standard capabilities 711 The following capabilities are defined by this specification. 713 VERSION 714 This capability MUST be advertised by all servers and MUST be the 715 first capability in the capability list; it indicates the 716 version(s) of NNTP that the server supports. There must be at 717 least one argument; each argument is a decimal number and MUST NOT 718 have a leading zero. Version numbers are assigned only in RFCs 719 which update or replace this specification; servers MUST NOT 720 create their own version numbers. 722 The version number of this specification is 2. 724 READER 725 This capability indicates that the server implements the various 726 commands useful for reading clients. 728 IHAVE 729 This capability indicates that the server implements the IHAVE 730 command. 732 POST 733 This capability indicates that the server implements the POST 734 command. 736 NEWNEWS 737 This capability indicates that the server implements the NEWNEWS 738 command. 740 HDR 741 This capability indicates that the server implements the header 742 access commands (HDR and LIST HEADERS). 744 OVER 745 This capability indicates that the server implements the overview 746 access commands (OVER and LIST OVERVIEW.FMT). If and only if the 747 server supports the message-id form of the OVER command, there 748 must be a single argument MSGID. 750 LIST 751 This capability indicates that the server implements at least one 752 variant of the LIST command. There MUST be one argument for each 753 variant of the LIST command supported by the server, giving the 754 keyword for that variant. 756 IMPLEMENTATION 757 This capability MAY be provided by a server. If so, the arguments 758 SHOULD be used to provide information such as the server software 759 name and version number. The client MUST NOT use this line to 760 determine capabilities of the server. (While servers often 761 provide this information in the initial greeting, clients need to 762 guess whether this is the case; this capability makes it clear 763 what the information is.) 765 MODE-READER 766 This capability indicates that the server is mode-switching 767 (Section 3.4.2) and the MODE READER command needs to be used to 768 enable the READER capability. 770 3.3.3. Extensions 772 Although NNTP is widely and robustly deployed, some parts of the 773 Internet community might wish to extend the NNTP service. It must be 774 emphasized that any extension to NNTP should not be considered 775 lightly. NNTP's strength comes primarily from its simplicity. 776 Experience with many protocols has shown that: 778 Protocols with few options tend towards ubiquity, whilst protocols 779 with many options tend towards obscurity. 781 This means that each and every extension, regardless of its benefits, 782 must be carefully scrutinized with respect to its implementation, 783 deployment, and interoperability costs. In many cases, the cost of 784 extending the NNTP service will likely outweigh the benefit. 786 An extension is a package of associated facilities, often but not 787 always including one or more new commands. Each extension MUST 788 define at least one new capability label (this will often, but need 789 not, be the name of one of these new commands). While any additional 790 capability information can normally be specified using arguments to 791 that label, an extension MAY define more than one capability label. 792 However, this SHOULD be limited to exceptional circumstances. 794 An extension is either a private extension or else its capabilities 795 are included in the IANA registry of capabilities (see Section 3.3.4) 796 and it is defined in an RFC (in which case it is a "registered 797 extension"). Such RFCs either must be on the standards track or must 798 define an IESG-approved experimental protocol. 800 The definition of an extension must include: 801 o a descriptive name for the extension; 802 o the capability label or labels defined by the extension; the 803 capability label of a registered extension MUST NOT begin with 804 "X"; 805 o the syntax, values, and meanings of any arguments for each 806 capability label defined by the extension; 807 o any new NNTP commands associated with the extension - the names of 808 commands associated with registered extensions MUST NOT begin with 809 "X"; 810 o the syntax and possible values of arguments associated with the 811 new NNTP commands; 812 o the response codes and possible values of arguments for the 813 responses of the new NNTP commands; 814 o any new arguments the extension associates with any other pre- 815 existing NNTP commands; 817 o any increase in the maximum length of commands and initial 818 response lines over the value specified in this document; 819 o a specific statement about the effect on pipelining this extension 820 may have (if any); 821 o a specific statement about the circumstances when use of this 822 extension can alter the contents of the capabilities list (other 823 than the new capability labels it defines); 824 o the circumstances under which the extension can cause any pre- 825 existing command to produce a 401, 480, or 483 response; 826 o how the use of MODE READER on a mode-switching server interacts 827 with the extension; 828 o how support for the extension affects the behaviour of a server 829 and NNTP client in any other manner not outlined above; 830 o formal syntax as described in Section 9.9. 832 A private extension MAY or MAY NOT be included in the capabilities 833 list. If it is, the capability label MUST begin with "X". A server 834 MAY provide additional keywords - for new commands and also for new 835 variants of existing commands - as part of a private extension. To 836 avoid the risk of a clash with a future registered extension, these 837 keywords SHOULD begin with "X". 839 If the server advertises a capability defined by a registered 840 extension, it MUST implement the extension so as to fully conform 841 with the specification (for example, it MUST implement all of the 842 commands that the extension describes as mandatory). If it does not 843 implement the extension as specified, it MUST NOT list the extension 844 in the capabilities list under its registered name; in this case it 845 MAY, but SHOULD NOT, provide a private extension (not listed, or 846 listed with a different name) that implements part of the extension 847 or implements the commands of the extension with a different meaning. 849 A server MUST NOT send different response codes to basic NNTP 850 commands documented here or commands documented in registered 851 extensions in response to the availability or use of a private 852 extension. 854 3.3.4. Initial IANA register 856 IANA is requested to maintain a registry of NNTP capability labels. 857 All capability labels in the registry MUST be keywords and MUST NOT 858 begin with X. 860 The initial contents of the registry consists of these entries: 862 +--------------------+-------------------------+--------------------+ 863 | Label | Meaning | Definition | 864 +--------------------+-------------------------+--------------------+ 865 | AUTHINFO | Authentication | [NNTP-AUTH] | 866 | | | | 867 | HDR | Batched header | Section 3.3.2, | 868 | | retrieval | Section 8.5, and | 869 | | | Section 8.6 | 870 | | | | 871 | IHAVE | IHAVE command available | Section 3.3.2 and | 872 | | | Section 6.3.2 | 873 | | | | 874 | IMPLEMENTATION | Server | Section 3.3.2 | 875 | | implementation-specific | | 876 | | information | | 877 | | | | 878 | LIST | LIST command variants | Section 3.3.2 and | 879 | | | Section 7.6.1 | 880 | | | | 881 | MODE-READER | Mode-switching server | Section 3.4.2 | 882 | | and MODE READER command | | 883 | | available | | 884 | | | | 885 | NEWNEWS | NEWNEWS command | Section 3.3.2 and | 886 | | available | Section 7.4 | 887 | | | | 888 | OVER | Overview support | Section 3.3.2, | 889 | | | Section 8.3, and | 890 | | | Section 8.4 | 891 | | | | 892 | POST | POST command available | Section 3.3.2 and | 893 | | | Section 6.3.1 | 894 | | | | 895 | READER | Reader commands | Section 3.3.2 | 896 | | available | | 897 | | | | 898 | SASL | Supported SASL | [NNTP-AUTH] | 899 | | mechanisms | | 900 | | | | 901 | STARTTLS | Transport layer | [NNTP-TLS] | 902 | | security | | 903 | | | | 904 | STREAMING | Streaming feeds | [NNTP-STREAM] | 905 | | | | 906 | VERSION | Supported NNTP versions | Section 3.3.2 | 907 +--------------------+-------------------------+--------------------+ 909 3.4. Mandatory and Optional Commands 911 For a number of reasons, not all the commands in this specification 912 are mandatory. However, it is equally undesirable for every command 913 to be optional, since this means that a client will have no idea what 914 facilities are available. Therefore, as a compromise, some of the 915 commands in this specification are mandatory - they must be supported 916 by all servers - while the remainder are not. The latter are then 917 subdivided into bundles, each indicated by a single capability label. 918 o If the label is included in the capability list returned by the 919 server, the server MUST support all commands in that bundle. 920 o If the label is not included, the server MAY support none or some 921 of the commands, but SHOULD NOT support all of them. In general, 922 there will be no way for a client to determine which commands are 923 supported without trying them. 924 The bundles have been chosen to provide useful functionality, and 925 therefore server authors are discouraged from implementing only part 926 of a bundle. 928 The description of each command will either indicate that it is 929 mandatory, or will give, using the term "indicating capability", the 930 capability label indicating whether or not the bundle including this 931 command is available. 933 Where a server does not implement a command, it MUST always generate 934 a 500 generic response code (or a 501 generic response code in the 935 case of a variant of a command depending on a second keyword where 936 the base command is recognised). Otherwise the command MUST be fully 937 implemented as specified; a server MUST NOT only partially implement 938 any of the commands in this specification. (Client authors should 939 note that some servers, not conforming to this specification, will 940 return a 502 generic response code to some commands that are not 941 implemented.) 943 Note: some commands have cases that require other commands to be used 944 first. If the former command is implemented but the latter is not, 945 the former MUST still generate the relevant specific response code. 946 For example, if ARTICLE (Section 6.2.1) is implemented but GROUP 947 (Section 6.1.1) is not, the correct response to "ARTICLE 1234" 948 remains 412. 950 3.4.1. Reading and Transit Servers 952 NNTP is traditionally used in two different ways. The first use is 953 "reading", where the client fetches articles from a large store 954 maintained by the server for immediate or later presentation to a 955 user, and sends articles created by that user back to the server (an 956 action called "posting") to be stored and distributed to other stores 957 and users. The second use is for the bulk transfer of articles from 958 one store to another. Since the hosts doing this transfer tend to be 959 peers in a network that transmit articles among one another, rather 960 than end-user systems, this process is called "peering" or "transit" 961 (even so, one host is still the client and the other is the server). 963 In practice these two uses are so different that some server 964 implementations are optimised for reading or for transit and, as a 965 result, do not offer the other facility or only offer limited 966 features. Other implementations are more general and offer both. 967 This specification allows for this by bundling the relevant commands 968 accordingly: the IHAVE command is designed for transit, while the 969 commands indicated by the READER capability are designed for reading 970 clients. 972 Except as an effect of the MODE READER (Section 5.3) command on a 973 mode-switching server, once a server advertises either or both of the 974 IHAVE or READER capabilities, it MUST continue to advertise them for 975 the entire session. 977 A server MAY provide different modes of behaviour (transit, reader, 978 or a combination) to different client connections and MAY use 979 external information, such as the IP address of the client, to 980 determine which mode to provide to any given connection. 982 The official TCP port for the NNTP service is 119. However, if a 983 host wishes to offer separate servers for transit and reading 984 clients, port 433 SHOULD be used for the transit server and 119 for 985 the reading server. 987 3.4.2. Mode switching 989 An implementation MAY, but SHOULD NOT, provide both transit and 990 reader facilities on the same server but require the client to select 991 which it wishes to use. Such an arrangement is called a "mode- 992 switching" server. 994 A mode-switching server has two modes: 995 o Transit mode, which applies after the initial connection: 996 * it MUST advertise the MODE-READER capability; 997 * it MUST NOT advertise the READER capability. 998 However, the server MAY cease to advertise the MODE-READER 999 capability after the client uses any command except CAPABILITIES. 1000 o Reading mode, after a successful MODE READER (Section 5.3) 1001 command: 1002 * it MUST NOT advertise the MODE-READER capability; 1003 * it MUST advertise the READER capability; 1004 * it MAY NOT advertise the IHAVE capability even if it was 1005 advertising it in transit mode. 1007 A client SHOULD only issue a MODE READER command to a server if it is 1008 advertising the MODE-READER capability. If the server does not 1009 support CAPABILITIES (and therefore does not conform to this 1010 specification), the client MAY use the following heuristic: 1011 o if the client wishes to use any "reader" commands, it SHOULD use 1012 the MODE READER command immediately after the initial connection; 1013 o otherwise it SHOULD NOT use the MODE READER command. 1014 In each case it should be prepared for some commands to be 1015 unavailable that would have been available if it had made the other 1016 choice. 1018 3.5. Pipelining 1020 NNTP is designed to operate over a reliable bi-directional connection 1021 such as TCP. Therefore, if a command does not depend on the response 1022 to the previous one, it should not matter if it is sent before that 1023 response is received. Doing this is called "pipelining". However, 1024 certain server implementations throw away all text received from the 1025 client following certain commands before sending their response. If 1026 this happens, pipelining will be affected because one or more 1027 commands will have been ignored or misinterpreted, and the client 1028 will be matching the wrong responses to each command. Since there 1029 are significant benefits to pipelining, but also circumstances where 1030 it is reasonable or common for servers to behave in the above manner, 1031 this document puts certain requirements on both clients and servers. 1033 Except where stated otherwise, a client MAY use pipelining. That is, 1034 it may send a command before receiving the response for the previous 1035 command. The server MUST allow pipelining and MUST NOT throw away 1036 any text received after a command. Irrespective of whether or not 1037 pipelining is used, the server MUST process commands in the order 1038 they are sent. 1040 If the specific description of a command says it "MUST NOT be 1041 pipelined", that command MUST end any pipeline of commands. That is, 1042 the client MUST NOT send any following command until receiving the 1043 CRLF at the end of the response from the command. The server MAY 1044 ignore any data received after the command and before the CRLF at the 1045 end of the response is sent to the client. 1047 The initial connection must not be part of a pipeline; that is, the 1048 client MUST NOT send any command until receiving the CRLF at the end 1049 of the greeting. 1051 If the client uses blocking system calls to send commands, it MUST 1052 ensure that the amount of text sent in pipelining does not cause a 1053 deadlock between transmission and reception. The amount of text 1054 involved will depend on window sizes in the transmission layer, and 1055 is typically 4k octets for TCP. (Since the server only sends data in 1056 response to commands from the client, the converse problem does not 1057 occur.) 1059 3.5.1. Examples 1061 Example of correct use of pipelining: 1063 [C] GROUP misc.test 1064 [C] STAT 1065 [C] NEXT 1066 [S] 211 1234 3000234 3002322 misc.test 1067 [S] 223 3000234 <45223423@example.com> retrieved 1068 [S] 223 3000237 <668929@example.org> retrieved 1070 Example of incorrect use of pipelining (the MODE READER command may 1071 not be pipelined): 1073 [C] MODE READER 1074 [C] DATE 1075 [C] NEXT 1076 [S] 200 Server ready, posting allowed 1077 [S] 223 3000237 <668929@example.org> retrieved 1079 The DATE command has been thrown away by the server and so there is 1080 no 111 response to match it. 1082 3.6. Articles 1084 NNTP is intended to transfer articles between clients and servers. 1085 For the purposes of this specification, articles are required to 1086 conform to the rules in this section and clients and servers MUST 1087 correctly process any article received from the other that does so. 1088 Note that this requirement applies only to the contents of 1089 communications over NNTP; it does not prevent the client or server 1090 from subsequently rejecting an article for reasons of local policy. 1091 Also see Appendix A for further restrictions on the format of 1092 articles in some uses of NNTP. 1094 An article consists of two parts: the headers and the body. They are 1095 separated by a single empty line, or in other words by two 1096 consecutive CRLF pairs (if there is more than one empty line, the 1097 second and subsequent ones are part of the body). In order to meet 1098 the general requirements of NNTP, an article MUST NOT include the 1099 octet NUL, MUST NOT contain the octets LF and CR other than as part 1100 of a CRLF pair, and MUST end with a CRLF pair. This specification 1101 puts no further restrictions on the body; in particular, it MAY be 1102 empty. 1104 The headers of an article consist of one or more header lines. Each 1105 header line consists of a header name, a colon, a space, the header 1106 content, and a CRLF in that order. The name consists of one or more 1107 printable US-ASCII characters other than colon and, for the purposes 1108 of this specification, is not case-sensitive. There MAY be more than 1109 one header line with the same name. The content MUST NOT contain 1110 CRLF; it MAY be empty. A header may be "folded"; that is, a CRLF 1111 pair may be placed before any TAB or space in the line; there MUST 1112 still be some other octet between any two CRLF pairs in a header 1113 line. (Note that folding means that the header line occupies more 1114 than one line when displayed or transmitted; nevertheless it is still 1115 referred to as "a" header line.) The presence or absence of folding 1116 does not affect the meaning of the header line; that is, the CRLF 1117 pairs introduced by folding are not considered part of the header 1118 content. Header lines SHOULD NOT be folded before the space after 1119 the colon that follows the header name, and SHOULD include at least 1120 one octet other than %x09 or %x20 between CRLF pairs. However, if an 1121 article has been received from elsewhere with one of these, clients 1122 and servers MAY transfer it to the other without re-folding it. 1124 The content of a header SHOULD be in UTF-8. However, if an 1125 implementation receives an article from elsewhere that uses octets in 1126 the range 128 to 255 in some other manner, it MAY pass it to a client 1127 or server without modification. Therefore implementations MUST be 1128 prepared to receive such headers and also data derived from them 1129 (e.g. in the responses from the OVER (Section 8.3) command) and MUST 1130 NOT assume that they are always UTF-8. Any external processing of 1131 those headers, including identifying the encoding used, is outside 1132 the scope of this document. 1134 Each article MUST have a unique message-id; two articles offered by 1135 an NNTP server MUST NOT have the same message-id. For the purposes 1136 of this specification, message-ids are opaque strings that MUST meet 1137 the following requirements: 1138 o A message-id MUST begin with "<" and end with ">", and MUST NOT 1139 contain the latter except at the end. 1140 o A message-id MUST be between 3 and 250 octets in length. 1141 o A message-id MUST NOT contain octets other than printable US-ASCII 1142 characters. 1143 Two message-ids are the same if and only if they consist of the same 1144 sequence of octets. 1146 This specification does not describe how the message-id of an article 1147 is determined. If the server does not have any way to determine a 1148 message-id from the article itself, it MUST synthesize one (this 1149 specification does not require the article to be changed as a 1150 result). See also Appendix A.2. 1152 4. The WILDMAT format 1154 The WILDMAT format described here is based on the version first 1155 developed by Rich Salz [SALZ1992], which in turn was derived from the 1156 format used in the UNIX "find" command to articulate file names. It 1157 was developed to provide a uniform mechanism for matching patterns in 1158 the same manner that the UNIX shell matches filenames. 1160 4.1. Wildmat syntax 1162 A wildmat is described by the following ABNF [RFC2234] syntax, which 1163 is an extract of that in Section 9.8. 1165 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 1166 wildmat-pattern = 1*wildmat-item 1167 wildmat-item = wildmat-exact / wildmat-wild 1168 wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 1169 UTF8-non-ascii ; exclude ! * , ? [ \ ] 1170 wildmat-wild = "*" / "?" 1172 Note: the characters \ , [ and ] are not allowed in wildmats, while * 1173 and ? are always wildcards. This should not be a problem since these 1174 characters cannot occur in newsgroup names, which is the only current 1175 use of wildmats. Backslash is commonly used to suppress the special 1176 meaning of characters while brackets are used to introduce sets. 1177 However, these usages are not universal and interpretation of these 1178 characters in the context of UTF-8 strings is both potentially 1179 complex and differs from existing practice, so they were omitted from 1180 this specification. A future extension to this specification may 1181 provide semantics for these characters. 1183 4.2. Wildmat semantics 1185 A wildmat is tested against a string, and either matches or does not 1186 match. To do this, each constituent is matched 1187 against the string and the rightmost pattern that matches is 1188 identified. If that is not preceded with "!", the 1189 whole wildmat matches. If it is preceded by "!", or if no matches, the whole wildmat does not match. 1192 For example, consider the wildmat "a*,!*b,*c*": 1193 o the string "aaa" matches because the rightmost match is with "a*" 1194 o the string "abb" does not match because the rightmost match is 1195 with "*b" 1197 o the string "ccb" matches because the rightmost match is with "*c*" 1198 o the string "xxx" does not match because no 1199 matches 1201 A matches a string if the string can be broken into 1202 components, each of which matches the corresponding in 1203 the pattern; the matches must be in the same order, and the whole 1204 string must be used in the match. The pattern is "anchored"; that 1205 is, the first and last characters in the string must match the first 1206 and last item respectively (unless that item is an asterisk matching 1207 zero characters). 1209 A matches the same character (which may be more than 1210 one octet in UTF-8). 1212 "?" matches exactly one character (which may be more than one octet). 1214 "*" matches zero or more characters. It can match an empty string, 1215 but it cannot match a subsequence of a UTF-8 sequence that is not 1216 aligned to the character boundaries. 1218 4.3. Extensions 1220 An NNTP server or extension MAY extend the syntax or semantics of 1221 wildmats provided that all wildmats that meet the requirements of 1222 Section 4.1 have the meaning ascribed to them by Section 4.2. Future 1223 editions of this document may also extend wildmats. 1225 4.4. Examples 1227 In these examples, $ and @ are used to represent the two octets %xC2 1228 and %xA3 respectively; $@ is thus the UTF-8 encoding for the pound 1229 sterling symbol, shown as # in the descriptions. 1231 Wildmat Description of strings that match 1232 abc the one string "abc" 1233 abc,def the two strings "abc" and "def" 1234 $@ the one character string "#" 1235 a* any string that begins with "a" 1236 a*b any string that begins with "a" and ends with "b" 1237 a*,*b any string that begins with "a" or ends with "b" 1238 a*,!*b any string that begins with "a" and does not end with 1239 "b" 1240 a*,!*b,c* any string that begins with "a" and does not end with 1241 "b", and any string that begins with "c" no matter 1242 what it ends with 1243 a*,c*,!*b any string that begins with "a" or "c" and does not 1244 end with "b" 1245 ?a* any string with "a" as its second character 1246 ??a* any string with "a" as its third character 1247 *a? any string with "a" as its penultimate character 1248 *a?? any string with "a" as its antepenultimate character 1250 5. Session administration commands 1252 5.1. Initial Connection 1254 5.1.1. Usage 1256 This command MUST NOT be pipelined. 1258 Responses 1260 200 Service available, posting allowed [1] 1261 201 Service available, posting prohibited [1] 1262 400 Service temporarily unavailable [1][2] 1263 502 Service permanently unavailable [1][2] 1265 [1] These are the only valid response codes for the initial 1266 greeting; the server MUST not return any other generic 1267 response code. 1268 [2] Following a 400 or 502 response the server MUST 1269 immediately close the connection. 1271 5.1.2. Description 1273 There is no command presented by the client upon initial connection 1274 to the server. The server MUST present an appropriate response code 1275 as a greeting to the client. This response informs the client 1276 whether service is available and whether the client is permitted to 1277 post. 1279 If the server will accept further commands from the client including 1280 POST, the server MUST present a 200 greeting code. If the server 1281 will accept further commands from the client, but it is not 1282 authorized to post articles using the POST command, the server MUST 1283 present a 201 greeting code. 1285 Otherwise the server MUST present a 400 or 502 greeting code and then 1286 immediately close the connection. 400 SHOULD be used if the issue is 1287 only temporary (for example, because of load) and the client can 1288 expect to be able to connect successfully at some point in the future 1289 without making any changes. 502 MUST be used if the client is not 1290 permitted under any circumstances to interact with the server, and 1291 MAY be used if the server has insufficient information to determine 1292 whether the issue is temporary or permanent. 1294 Note: the distinction between the 200 and 201 response codes has 1295 turned out in practice to be insufficient; for example, some servers 1296 do not allow posting until the client has authenticated, while other 1297 clients assume that a 201 response means that posting will never be 1298 possible even after authentication. Therefore clients SHOULD use the 1299 CAPABILITIES command (Section 5.2) rather than rely on this response. 1301 5.1.3. Examples 1303 Example of a normal connection from an authorized client which then 1304 terminates the session (see Section 5.4): 1306 [Initial connection set-up completed.] 1307 [S] 200 NNTP Service Ready, posting permitted 1308 [C] QUIT 1309 [S] 205 NNTP Service exits normally 1310 [Server closes connection.] 1312 Example of a normal connection from an authorized client that is not 1313 permitted to post; it also immediately terminates the session: 1315 [Initial connection set-up completed.] 1316 [S] 201 NNTP Service Ready, posting prohibited 1317 [C] QUIT 1318 [S] 205 NNTP Service exits normally 1319 [Server closes connection.] 1321 Example of a normal connection from an unauthorized client: 1323 [Initial connection set-up completed.] 1324 [S] 502 NNTP Service permanently unavailable 1325 [Server closes connection.] 1327 Example of a connection from a client where the server is unable to 1328 provide service: 1330 [Initial connection set-up completed.] 1331 [S] 400 NNTP Service temporarily unavailable 1332 [Server closes connection.] 1334 5.2. CAPABILITIES 1336 5.2.1. Usage 1338 This command is mandatory. 1340 Syntax 1342 CAPABILITIES [keyword] 1344 Responses 1346 101 Capability list follows (multi-line) 1348 Parameters 1350 keyword additional feature, see description 1352 5.2.2. Description 1354 The CAPABILITIES command allows a client to determine the 1355 capabilities of the server at any given time. 1357 This command MAY be issued at any time; the server MUST NOT require 1358 it to be issued in order to make use of any capability. The response 1359 generated by this command MAY change during a session because of 1360 other state information (which in turn may be changed by the effects 1361 of other commands or by external events). An NNTP client is only 1362 able to get the current and correct information concerning available 1363 capabilities at any point during a session by issuing a CAPABILITIES 1364 command at that point of that session and processing the response. 1366 The capability list is returned as a multi-line data block following 1367 the 101 response code. Each capability is described by a separate 1368 capability line. The server MUST NOT list the same capability twice 1369 in the response, even with different arguments. Except that the 1370 VERSION capability MUST be the first line, the order in which the 1371 capability lines appears is not significant; the server need not even 1372 consistently return the same order. 1374 While some capabilities are likely to be always available or never 1375 available, others - notably extensions - will appear and disappear 1376 depending on server state changes within the session or external 1377 events between sessions. An NNTP client MAY cache the results of 1378 this command, but MUST NOT rely on the correctness of any cached 1379 results, whether from earlier in this session or from a previous 1380 session, MUST cope gracefully with the cached status being out of 1381 date, and SHOULD (if caching results) provide a way to force the 1382 cached information to be refreshed. Furthermore, a client MUST NOT 1383 use cached results in relation to security, privacy, and 1384 authentication extensions. See Section 12.6 for further discussion 1385 of this topic. 1387 The keyword argument is not used by this specification. It is 1388 provided so that extensions or revisions to this specification can 1389 include extra features for this command without requiring the 1390 CAPABILITIES command to be used twice (once to determine if the extra 1391 features are available and a second time to make use of them). If 1392 the server does not recognise the argument (and it is a keyword), it 1393 MUST respond with the 101 response code as if the argument had been 1394 omitted. If an argument is provided that the server does recognise, 1395 it MAY use the 101 response code or MAY use some other response code 1396 (which will be defined in the specification of that feature). If the 1397 argument is not a keyword, the 501 generic response code MUST be 1398 returned. The server MUST NOT generate any other response code to 1399 the CAPABILITIES command. 1401 5.2.3. Examples 1403 Example of a minimal response (a read-only server): 1405 [C] CAPABILITIES 1406 [S] 101 Capability list: 1407 [S] VERSION 2 1408 [S] READER 1409 [S] LIST ACTIVE NEWSGROUPS 1410 [S] . 1412 Example of a response from a server that has a range of facilities 1413 and also describes itself: 1415 [C] CAPABILITIES 1416 [S] 101 Capability list: 1417 [S] VERSION 2 1418 [S] READER 1419 [S] IHAVE 1420 [S] POST 1421 [S] NEWNEWS 1422 [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES OVERVIEW.FMT 1423 [S] IMPLEMENTATION INN 4.2 2004-12-25 1424 [S] OVER MSGID 1425 [S] STREAMING 1426 [S] XSECRET 1427 [S] . 1429 Example of a server that supports more than one version of NNTP: 1431 [C] CAPABILITIES 1432 [S] 101 Capability list: 1433 [S] VERSION 2 3 1434 [S] READER 1435 [S] LIST ACTIVE NEWSGROUPS 1437 [S] . 1439 Example of a client attempting to use a feature of the CAPABILITIES 1440 command that the server does not support: 1442 [C] CAPABILITIES AUTOUPDATE 1443 [S] 101 Capability list: 1444 [S] VERSION 2 1445 [S] READER 1446 [S] IHAVE 1447 [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT HEADERS 1448 [S] OVER MSGID 1449 [S] HDR 1450 [S] NEWNEWS 1451 [S] . 1453 5.3. MODE READER 1455 5.3.1. Usage 1457 Indicating capability: MODE-READER 1459 This command MUST NOT be pipelined. 1461 Syntax 1463 MODE READER 1465 Responses 1467 200 Posting allowed 1468 201 Posting prohibited 1469 502 Reading service permanently unavailable [1] 1471 [1] Following a 502 response the server MUST immediately close 1472 the connection. 1474 5.3.2. Description 1476 The MODE READER command instructs a mode-switching server to switch 1477 modes, as described in Section 3.4.2. 1479 If the server is mode-switching, it switches from its transit mode to 1480 its reader mode, indicating the fact by changing the capability list 1481 accordingly, and then MUST return a 200 or 201 response with the same 1482 meaning as for the initial greeting (as described in Section 5.1.1); 1483 note that the response need not be the same as the one presented 1484 during the initial greeting. The client MUST NOT issue MODE READER 1485 more than once in a session or after any security or privacy commands 1486 are issued. When the MODE READER command is issued, the server MAY 1487 reset its state to that immediately after the initial connection 1488 before switching mode. 1490 If the server is not mode-switching, then: 1491 o If it advertises the READER capability, it MUST return a 200 or 1492 201 response with the same meaning as for the initial greeting; in 1493 this case the command MUST NOT affect the server state in any way. 1494 o If it does not advertise the READER capability, it MUST return a 1495 502 response and then immediately close the connection. 1497 5.3.3. Examples 1499 Example of use of the MODE READER command on a transit-only server 1500 (which therefore does not providing reading facilities): 1502 [C] CAPABILITIES 1503 [S] 101 Capability list: 1504 [S] VERSION 2 1505 [S] IHAVE 1506 [S] . 1507 [C] MODE READER 1508 [S] 502 Transit service only 1509 [Server closes connection.] 1511 Example of use of the MODE READER command on a server that provides 1512 reading facilities: 1514 [C] CAPABILITIES 1515 [S] 101 Capability list: 1516 [S] VERSION 2 1517 [S] READER 1518 [S] LIST ACTIVE NEWSGROUPS 1519 [S] . 1520 [C] MODE READER 1521 [S] 200 Reader mode, posting permitted 1522 [C] IHAVE 1523 [S] 500 Permission denied 1524 [C] GROUP misc.test 1525 [S] 211 1234 3000234 3002322 misc.test 1527 Note that in both these situations the client SHOULD NOT use MODE 1528 READER. 1530 Example of use of the MODE READER command on a mode-switching server: 1532 [C] CAPABILITIES 1533 [S] 101 Capability list: 1534 [S] VERSION 2 1535 [S] IHAVE 1536 [S] MODE-READER 1537 [S] . 1538 [C] MODE READER 1539 [S] 200 Reader mode, posting permitted 1540 [C] CAPABILITIES 1541 [S] 101 Capability list: 1542 [S] VERSION 2 1543 [S] READER 1544 [S] NEWNEWS 1545 [S] LIST ACTIVE NEWSGROUPS 1546 [S] STARTTLS 1547 [S] . 1549 In this case the server offers (but does not require) TLS privacy in 1550 its reading mode but not its transit mode. 1552 Example of use of the MODE READER command where the client is not 1553 permitted to post: 1555 [C] MODE READER 1556 [S] 201 NNTP Service Ready, posting prohibited 1558 5.4. QUIT 1560 5.4.1. Usage 1562 This command is mandatory. 1564 Syntax 1566 QUIT 1568 Responses 1570 205 Connection closing 1572 5.4.2. Description 1574 The client uses the QUIT command to terminate the session. The 1575 server MUST acknowledge the QUIT command and then close the 1576 connection to the client. This is the preferred method for a client 1577 to indicate that it has finished all its transactions with the NNTP 1578 server. 1580 If a client simply disconnects (or the connection times out or some 1581 other fault occurs), the server MUST gracefully cease its attempts to 1582 service the client, disconnecting from its end if necessary. 1584 The server MUST NOT generate any response code to the QUIT command 1585 other than 205 or, if any arguments are provided, 501. 1587 5.4.3. Examples 1589 [C] QUIT 1590 [S] 205 closing connection 1591 [Server closes connection.] 1593 6. Article posting and retrieval 1595 News reading clients have available a variety of mechanisms to 1596 retrieve articles via NNTP. The news articles are stored and indexed 1597 using three types of keys. The first type of key is the message-id 1598 of an article and is globally unique. The second type of key is 1599 composed of a newsgroup name and an article number within that 1600 newsgroup. On a particular server there MUST be only one article 1601 with a given number within any newsgroup and an article MUST NOT have 1602 two different numbers in the same newsgroup. An article can be 1603 cross-posted to multiple newsgroups, so there may be multiple keys 1604 that point to the same article on the same server; these MAY have 1605 different numbers in each newsgroup. However, this type of key is 1606 not required to be globally unique and so the same key MAY refer to 1607 different articles on different servers. (Note that the terms 1608 "group" and "newsgroup" are equivalent.) 1610 The final type of key is the arrival timestamp, giving the time that 1611 the article arrived at the server. The server MUST ensure that 1612 article numbers are issued in order of arrival timestamp; that is, 1613 articles arriving later MUST have higher numbers than those that 1614 arrive earlier. The server SHOULD allocate the next sequential 1615 unused number to each new article. 1617 Article numbers MUST lie between 1 and 4,294,967,295 inclusive. The 1618 client and server MAY use leading zeroes in specifying article 1619 numbers, but MUST NOT use more than 16 digits. In some situations, 1620 the value zero replaces an article number to show some special 1621 situation. 1623 6.1. Group and article selection 1625 The following commands are used to set the "currently selected 1626 newsgroup" and the "current article number", which are used by 1627 various commands. At the start of an NNTP session, both of these 1628 values are set to the special value "invalid". 1630 6.1.1. GROUP 1632 6.1.1.1. Usage 1634 Indicating capability: READER 1636 Syntax 1638 GROUP group 1640 Responses 1642 211 number low high group Group successfully selected 1643 411 No such newsgroup 1645 Parameters 1647 group name of newsgroup 1648 number estimated number of articles in the group 1649 low reported low water mark 1650 high reported high water mark 1652 6.1.1.2. Description 1654 The GROUP command selects a newsgroup as the currently selected 1655 newsgroup and returns summary information about it. 1657 The required argument is the name of the newsgroup to be selected 1658 (e.g. "news.software.nntp"). A list of valid newsgroups may be 1659 obtained by using the LIST ACTIVE command (see Section 7.6.3). 1661 The successful selection response will return the article numbers of 1662 the first and last articles in the group at the moment of selection 1663 (these numbers are referred to as the "reported low water mark" and 1664 the "reported high water mark"), and an estimate of the number of 1665 articles in the group currently available. 1667 If the group is not empty, the estimate MUST be at least the actual 1668 number of articles available, and MUST be no greater than one more 1669 than the difference between the reported low and high water marks. 1670 (Some implementations will actually count the number of articles 1671 currently stored. Others will just subtract the low water mark from 1672 the high water mark and add one to get an estimate.) 1674 If the group is empty, one of the following three situations will 1675 occur. Clients MUST accept all three cases; servers MUST NOT 1676 represent an empty group in any other way. 1677 o The high water mark will be one less than the low water mark, and 1678 the estimated article count will be zero. Servers SHOULD use this 1679 method to show an empty group. This is the only time that the 1680 high water mark can be less than the low water mark. 1681 o All three numbers will be zero. 1682 o The high water mark is greater than or equal to the low water 1683 mark. The estimated article count might be zero or non-zero; if 1684 non-zero, the same requirements apply as for a non-empty group. 1686 The set of articles in a group may change after the GROUP command is 1687 carried out. That is: 1688 o articles may be removed from the group 1689 o articles may be reinstated in the group with the same article 1690 number, but those articles MUST have numbers no less than the 1691 reported low water mark (note that this is a reinstatement of the 1692 previous article, not a new article reusing the number) 1693 o new articles may be added with article numbers greater than the 1694 reported high water mark (if an article that was the one with the 1695 highest number has been removed and the high water mark adjusted 1696 accordingly, the next new article will not have the number one 1697 greater than the reported high water mark) 1699 Except when the group is empty and all three numbers are zero, 1700 whenever a subsequent GROUP command for the same newsgroup is issued, 1701 either by the same client or a different client, the reported low 1702 water mark in the response MUST be no less than that in any previous 1703 response for that newsgroup in any session, and SHOULD be no less 1704 than that in any previous response for that newsgroup ever sent to 1705 any client. Any failure to meet the latter condition SHOULD be 1706 transient only. The client may make use of the low water mark to 1707 remove all remembered information about articles with lower numbers, 1708 as these will never recur. This includes the situation when the high 1709 water mark is one less than the low water mark. No similar 1710 assumption can be made about the high water mark, as this can 1711 decrease if an article is removed, and then increase again if it is 1712 reinstated or if new articles arrive. 1714 When a valid group is selected by means of this command, the 1715 currently selected newsgroup MUST be set to that group and the 1716 current article number MUST be set to the first article in the group 1717 (this applies even if the group is already the currently selected 1718 newsgroup). If an empty newsgroup is selected, the current article 1719 number is made invalid. If an invalid group is specified, the 1720 currently selected newsgroup and current article number MUST NOT be 1721 changed. 1723 The GROUP or LISTGROUP command (see Section 6.1.2) MUST be used by a 1724 client and a successful response received before any other command is 1725 used that depends on the value of the currently selected newsgroup or 1726 current article number. 1728 If the group specified is not available on the server, a 411 response 1729 MUST be returned. 1731 6.1.1.3. Examples 1733 Example for a group known to the server: 1735 [C] GROUP misc.test 1736 [S] 211 1234 3000234 3002322 misc.test 1738 Example for a group unknown to the server: 1740 [C] GROUP example.is.sob.bradner.or.barber 1741 [S] 411 example.is.sob.bradner.or.barber is unknown 1743 Example of an empty group using the preferred response: 1745 [C] GROUP example.currently.empty.newsgroup 1746 [S] 211 0 4000 3999 example.currently.empty.newsgroup 1748 Example of an empty group using an alternative response: 1750 [C] GROUP example.currently.empty.newsgroup 1751 [S] 211 0 0 0 example.currently.empty.newsgroup 1753 Example of an empty group using a different alternative response: 1755 [C] GROUP example.currently.empty.newsgroup 1756 [S] 211 0 4000 4321 example.currently.empty.newsgroup 1758 Example reselecting the currently selected newsgroup: 1760 [C] GROUP misc.test 1761 [S] 211 1234 234 567 misc.test 1762 [C] STAT 444 1763 [S] 223 444 <123456@example.net> retrieved 1764 [C] GROUP misc.test 1765 [S] 211 1234 234 567 misc.test 1766 [C] STAT 1767 [S] 223 234 retrieved 1769 6.1.2. LISTGROUP 1771 6.1.2.1. Usage 1773 Indicating capability: READER 1775 Syntax 1777 LISTGROUP [group [range]] 1779 Responses 1781 211 number low high group Article numbers follow (multi-line) 1782 411 No such newsgroup 1783 412 No newsgroup selected [1] 1785 Parameters 1787 group name of newsgroup 1788 range range of articles to report 1789 number estimated number of articles in the group 1790 low reported low water mark 1791 high reported high water mark 1793 [1] The 412 response can only occur if no group has been 1794 specified. 1796 6.1.2.2. Description 1798 The LISTGROUP command selects a newsgroup in the same manner as the 1799 the GROUP command (see Section 6.1.1) but also provides a list of 1800 article numbers in the newsgroup. If no group is specified, the 1801 currently selected newsgroup is used. 1803 On success, a list of article numbers is returned as a multi-line 1804 data block following the 211 response code (the arguments on the 1805 initial response line are the same as for the GROUP command). The 1806 list contains one number per line and is in numerical order. It 1807 lists precisely those articles that exist in the group at the moment 1808 of selection (therefore an empty group produces an empty list); if 1809 the optional range argument is specified, only those articles that 1810 are within the range are included in the list (therefore the list MAY 1811 be empty even if the group is not). 1813 The range argument may be any of the following: 1814 o an article number 1815 o an article number followed by a dash to indicate all following 1816 o an article number followed by a dash followed by another article 1817 number 1818 In the last case, if the second number is less than the first number 1819 then the range contains no articles. Omitting the range is 1820 equivalent to the range 1- being specified. 1822 If the group specified is not available on the server, a 411 response 1823 MUST be returned. If no group is specified and the currently 1824 selected newsgroup is invalid, a 412 response MUST be returned. 1826 Except that the group argument is optional, a range argument can be 1827 specified, and that a multi-line data block follows the 211 response 1828 code, the LISTGROUP command is identical to the GROUP command. In 1829 particular, when successful, the command sets the current article 1830 number to the first article in the group, if any, even if this is not 1831 within the range specified by the second argument. 1833 Note that the range argument is a new feature in this specification 1834 and servers that do not support CAPABILITIES (and therefore do not 1835 conform to this specification) are unlikely to support it. 1837 6.1.2.3. Examples 1839 Example of LISTGROUP being used to select a group: 1841 [C] LISTGROUP misc.test 1842 [S] 211 2000 3000234 3002322 misc.test list follows 1843 [S] 3000234 1844 [S] 3000237 1845 [S] 3000238 1846 [S] 3000239 1847 [S] 3002322 1848 [S] . 1850 Example of LISTGROUP on an empty group: 1852 [C] LISTGROUP example.empty.newsgroup 1853 [S] 211 0 0 0 example.empty.newsgroup list follows 1854 [S] . 1856 Example of LISTGROUP on a valid currently selected newsgroup: 1858 [C] GROUP misc.test 1859 [S] 211 2000 3000234 3002322 misc.test 1860 [C] LISTGROUP 1861 [S] 211 2000 3000234 3002322 misc.test list follows 1862 [S] 3000234 1864 [S] 3000237 1865 [S] 3000238 1866 [S] 3000239 1867 [S] 3002322 1868 [S] . 1870 Example of LISTGROUP with a range: 1872 [C] LISTGROUP misc.test 3000238-3000248 1873 [S] 211 2000 3000234 3002322 misc.test list follows 1874 [S] 3000238 1875 [S] 3000239 1876 [S] . 1878 Example of LISTGROUP with an empty range: 1880 [C] LISTGROUP misc.test 12345678- 1881 [S] 211 2000 3000234 3002322 misc.test list follows 1882 [S] . 1884 Example of LISTGROUP with an invalid range: 1886 [C] LISTGROUP misc.test 9999-111 1887 [S] 211 2000 3000234 3002322 misc.test list follows 1888 [S] . 1890 6.1.3. LAST 1892 6.1.3.1. Usage 1894 Indicating capability: READER 1896 Syntax 1898 LAST 1900 Responses 1902 223 n message-id Article found 1903 412 No newsgroup selected 1904 420 Current article number is invalid 1905 422 No previous article in this group 1907 Parameters 1909 n article number 1910 message-id article message-id 1912 6.1.3.2. Description 1914 If the currently selected newsgroup is valid, the current article 1915 number MUST be set to the previous article in that newsgroup (that 1916 is, the highest existing article number less than the current article 1917 number). If successful, a response indicating the new current 1918 article number and the message-id of that article MUST be returned. 1919 No article text is sent in response to this command. 1921 There MAY be no previous article in the group, although the current 1922 article number is not the reported low water mark. There MUST NOT be 1923 a previous article when the current article number is the reported 1924 low water mark. 1926 Because articles can be removed and added, the results of multiple 1927 LAST and NEXT commands MAY not be consistent over the life of a 1928 particular NNTP session. 1930 If the current article number is already the first article of the 1931 newsgroup, a 422 response MUST be returned. If the current article 1932 number is invalid, a 420 response MUST be returned. If the currently 1933 selected newsgroup is invalid, a 412 response MUST be returned. In 1934 all three cases the currently selected newsgroup and current article 1935 number MUST NOT be altered. 1937 6.1.3.3. Examples 1939 Example of a successful article retrieval using LAST: 1941 [C] GROUP misc.test 1942 [S] 211 1234 3000234 3002322 misc.test 1943 [C] NEXT 1944 [S] 223 3000237 <668929@example.org> retrieved 1945 [C] LAST 1946 [S] 223 3000234 <45223423@example.com> retrieved 1948 Example of an attempt to retrieve an article without having selected 1949 a group (via the GROUP command) first: 1951 [Assumes currently selected newsgroup is invalid.] 1952 [C] LAST 1953 [S] 412 no newsgroup selected 1955 Example of an attempt to retrieve an article using the LAST command 1956 when the current article number is that of the first article in the 1957 group: 1959 [C] GROUP misc.test 1960 [S] 211 1234 3000234 3002322 misc.test 1961 [C] LAST 1962 [S] 422 No previous article to retrieve 1964 Example of an attempt to retrieve an article using the LAST command 1965 when the currently selected newsgroup is empty: 1967 [C] GROUP example.empty.newsgroup 1968 [S] 211 0 0 0 example.empty.newsgroup 1969 [C] LAST 1970 [S] 420 No current article selected 1972 6.1.4. NEXT 1974 6.1.4.1. Usage 1976 Indicating capability: READER 1978 Syntax 1980 NEXT 1982 Responses 1984 223 n message-id Article found 1985 412 No newsgroup selected 1986 420 Current article number is invalid 1987 421 No next article in this group 1989 Parameters 1991 n article number 1992 message-id article message-id 1994 6.1.4.2. Description 1996 If the currently selected newsgroup is valid, the current article 1997 number MUST be set to the next article in that newsgroup (that is, 1998 the lowest existing article number greater than the current article 1999 number). If successful, a response indicating the new current 2000 article number and the message-id of that article MUST be returned. 2001 No article text is sent in response to this command. 2003 If the current article number is already the last article of the 2004 newsgroup, a 421 response MUST be returned. In all other aspects 2005 (apart, of course, from the lack of 422 response) this command is 2006 identical to the LAST command (Section 6.1.3). 2008 6.1.4.3. Examples 2010 Example of a successful article retrieval using NEXT: 2012 [C] GROUP misc.test 2013 [S] 211 1234 3000234 3002322 misc.test 2014 [C] NEXT 2015 [S] 223 3000237 <668929@example.org> retrieved 2017 Example of an attempt to retrieve an article without having selected 2018 a group (via the GROUP command) first: 2020 [Assumes currently selected newsgroup is invalid.] 2021 [C] NEXT 2022 [S] 412 no newsgroup selected 2024 Example of an attempt to retrieve an article using the NEXT command 2025 when the current article number is that of the last article in the 2026 group: 2028 [C] GROUP misc.test 2029 [S] 211 1234 3000234 3002322 misc.test 2030 [C] STAT 3002322 2031 [S] 223 3002322 <411@example.net> retrieved 2032 [C] NEXT 2033 [S] 421 No next article to retrieve 2035 Example of an attempt to retrieve an article using the NEXT command 2036 when the currently selected newsgroup is empty: 2038 [C] GROUP example.empty.newsgroup 2039 [S] 211 0 0 0 example.empty.newsgroup 2040 [C] NEXT 2041 [S] 420 No current article selected 2043 6.2. Retrieval of articles and article sections 2045 The ARTICLE, BODY, HEAD, and STAT commands are very similar. They 2046 differ only in the parts of the article that are presented to the 2047 client and in the successful response code. The ARTICLE command is 2048 described here in full, while the other commands are described in 2049 terms of the differences. As specified in Section 3.6, an article 2050 consists of two parts: the article headers and the article body. 2052 When responding to one of these commands, the server MUST present the 2053 entire article or appropriate part and MUST NOT attempt to alter or 2054 translate it in any way. 2056 6.2.1. ARTICLE 2058 6.2.1.1. Usage 2060 Indicating capability: READER 2062 Syntax 2064 ARTICLE message-id 2065 ARTICLE number 2066 ARTICLE 2068 Responses 2070 First form (message-id specified) 2072 220 0|n message-id Article follows (multi-line) 2073 430 No article with that message-id 2075 Second form (article number specified) 2077 220 n message-id Article follows (multi-line) 2078 412 No newsgroup selected 2079 423 No article with that number 2081 Third form (current article number used) 2083 220 n message-id Article follows (multi-line) 2084 412 No newsgroup selected 2085 420 Current article number is invalid 2087 Parameters 2089 number Requested article number 2090 n Returned article number 2091 message-id Article message-id 2093 6.2.1.2. Description 2095 The ARTICLE command selects an article based on the arguments and 2096 presents the entire article (that is, the headers, an empty line, and 2097 the body in that order). The command has three forms. 2099 In the first form, a message-id is specified and the server presents 2100 the article with that message-id. In this case, the server MUST NOT 2101 alter the currently selected newsgroup or current article number. 2102 This is both to facilitate the presentation of articles that may be 2103 referenced within another article being read, and because of the 2104 semantic difficulties of determining the proper sequence and 2105 membership of an article that may have been cross-posted to more than 2106 one newsgroup. 2108 In the response, the article number MUST be replaced with zero, 2109 except that if there is a currently selected newsgroup and the 2110 article is present in that group, the server MAY use that article 2111 number. (The server is not required to determine whether the article 2112 is in the currently selected newsgroup or, if so, what article number 2113 it has; the client MUST always be prepared for zero to be specified.) 2114 The server MUST NOT provide an article number unless use of that 2115 number in a second ARTICLE command immediately following this one 2116 would return the same article. Even if the server chooses to return 2117 article numbers in these circumstances, it need not do so 2118 consistently; it MAY return zero to any such command (also see the 2119 STAT examples (Section 6.2.4.3)). 2121 In the second form, an article number is specified. If there is an 2122 article with that number in the currently selected newsgroup, the 2123 server MUST set the current article number to that number. 2125 In the third form, the article indicated by the current article 2126 number in the currently selected newsgroup is used. 2128 Note that a previously valid article number MAY become invalid if the 2129 article has been removed. A previously invalid article number MAY 2130 become valid if the article has been reinstated, but such an article 2131 number MUST be no less than the reported low water mark for that 2132 group. 2134 The server MUST NOT change the currently selected newsgroup as a 2135 result of this command. The server MUST NOT change the current 2136 article number except when an article number argument was provided 2137 and the article exists; in particular, it MUST NOT change it 2138 following an unsuccessful response. 2140 Since the message-id is unique for each article, it may be used by a 2141 client to skip duplicate displays of articles that have been posted 2142 more than once, or to more than one newsgroup. 2144 The article is returned as a multi-line data block following the 220 2145 response code. 2147 If the argument is a message-id and no such article exists, a 430 2148 response MUST be returned. If the argument is a number or is omitted 2149 and the currently selected newsgroup is invalid, a 412 response MUST 2150 be returned. If the argument is a number and that article does not 2151 exist in the currently selected newsgroup, a 423 response MUST be 2152 returned. If the argument is omitted and the current article number 2153 is invalid, a 420 response MUST be returned. 2155 6.2.1.3. Examples 2157 Example of a successful retrieval of an article (using no article 2158 number): 2160 [C] GROUP misc.test 2161 [S] 211 1234 3000234 3002322 misc.test 2162 [C] ARTICLE 2163 [S] 220 3000234 <45223423@example.com> 2164 [S] Path: pathost!demo!whitehouse!not-for-mail 2165 [S] From: "Demo User" 2166 [S] Newsgroups: misc.test 2167 [S] Subject: I am just a test article 2168 [S] Date: 6 Oct 1998 04:38:40 -0500 2169 [S] Organization: An Example Net, Uncertain, Texas 2170 [S] Message-ID: <45223423@example.com> 2171 [S] 2172 [S] This is just a test article. 2173 [S] . 2175 Example of a successful retrieval of an article by message-id: 2177 [C] ARTICLE <45223423@example.com> 2178 [S] 220 0 <45223423@example.com> 2179 [S] Path: pathost!demo!whitehouse!not-for-mail 2180 [S] From: "Demo User" 2181 [S] Newsgroups: misc.test 2182 [S] Subject: I am just a test article 2183 [S] Date: 6 Oct 1998 04:38:40 -0500 2184 [S] Organization: An Example Net, Uncertain, Texas 2185 [S] Message-ID: <45223423@example.com> 2186 [S] 2187 [S] This is just a test article. 2188 [S] . 2190 Example of an unsuccessful retrieval of an article by message-id: 2192 [C] ARTICLE 2193 [S] 430 No Such Article Found 2195 Example of an unsuccessful retrieval of an article by number: 2197 [C] GROUP misc.test 2198 [S] 211 1234 3000234 3002322 news.groups 2199 [C] ARTICLE 300256 2200 [S] 423 No article with that number 2202 Example of an unsuccessful retrieval of an article by number because 2203 no newsgroup was selected first: 2205 [Assumes currently selected newsgroup is invalid.] 2206 [C] ARTICLE 300256 2207 [S] 412 No newsgroup selected 2209 Example of an attempt to retrieve an article when the currently 2210 selected newsgroup is empty: 2212 [C] GROUP example.empty.newsgroup 2213 [S] 211 0 0 0 example.empty.newsgroup 2214 [C] ARTICLE 2215 [S] 420 No current article selected 2217 6.2.2. HEAD 2219 6.2.2.1. Usage 2221 This command is mandatory. 2223 Syntax 2225 HEAD message-id 2226 HEAD number 2227 HEAD 2229 Responses 2231 First form (message-id specified) 2233 221 0|n message-id Headers follow (multi-line) 2234 430 No article with that message-id 2236 Second form (article number specified) 2238 221 n message-id Headers follow (multi-line) 2239 412 No newsgroup selected 2240 423 No article with that number 2242 Third form (current article number used) 2244 221 n message-id Headers follow (multi-line) 2245 412 No newsgroup selected 2246 420 Current article number is invalid 2248 Parameters 2250 number Requested article number 2251 n Returned article number 2252 message-id Article message-id 2254 6.2.2.2. Description 2256 The HEAD command behaves identically to the ARTICLE command except 2257 that, if the article exists, the response code is 221 instead of 220 2258 and only the headers are presented (the empty line separating the 2259 headers and body MUST NOT be included). 2261 6.2.2.3. Examples 2263 Example of a successful retrieval of the headers of an article (using 2264 no article number): 2266 [C] GROUP misc.test 2267 [S] 211 1234 3000234 3002322 misc.test 2268 [C] HEAD 2269 [S] 221 3000234 <45223423@example.com> 2270 [S] Path: pathost!demo!whitehouse!not-for-mail 2271 [S] From: "Demo User" 2272 [S] Newsgroups: misc.test 2273 [S] Subject: I am just a test article 2274 [S] Date: 6 Oct 1998 04:38:40 -0500 2275 [S] Organization: An Example Net, Uncertain, Texas 2276 [S] Message-ID: <45223423@example.com> 2277 [S] . 2279 Example of a successful retrieval of the headers of an article by 2280 message-id: 2282 [C] HEAD <45223423@example.com> 2283 [S] 221 0 <45223423@example.com> 2285 [S] Path: pathost!demo!whitehouse!not-for-mail 2286 [S] From: "Demo User" 2287 [S] Newsgroups: misc.test 2288 [S] Subject: I am just a test article 2289 [S] Date: 6 Oct 1998 04:38:40 -0500 2290 [S] Organization: An Example Net, Uncertain, Texas 2291 [S] Message-ID: <45223423@example.com> 2292 [S] . 2294 Example of an unsuccessful retrieval of the headers of an article by 2295 message-id: 2297 [C] HEAD 2298 [S] 430 No Such Article Found 2300 Example of an unsuccessful retrieval of the headers of an article by 2301 number: 2303 [C] GROUP misc.test 2304 [S] 211 1234 3000234 3002322 misc.test 2305 [C] HEAD 300256 2306 [S] 423 No article with that number 2308 Example of an unsuccessful retrieval of the headers of an article by 2309 number because no newsgroup was selected first: 2311 [Assumes currently selected newsgroup is invalid.] 2312 [C] HEAD 300256 2313 [S] 412 No newsgroup selected 2315 Example of an attempt to retrieve the headers of an article when the 2316 currently selected newsgroup is empty: 2318 [C] GROUP example.empty.newsgroup 2319 [S] 211 0 0 0 example.empty.newsgroup 2320 [C] HEAD 2321 [S] 420 No current article selected 2323 6.2.3. BODY 2325 6.2.3.1. Usage 2327 Indicating capability: READER 2328 Syntax 2330 BODY message-id 2331 BODY number 2332 BODY 2334 Responses 2336 First form (message-id specified) 2338 222 0|n message-id Body follows (multi-line) 2339 430 No article with that message-id 2341 Second form (article number specified) 2343 222 n message-id Body follows (multi-line) 2344 412 No newsgroup selected 2345 423 No article with that number 2347 Third form (current article number used) 2349 222 n message-id Body follows (multi-line) 2350 412 No newsgroup selected 2351 420 Current article number is invalid 2353 Parameters 2355 number Requested article number 2356 n Returned article number 2357 message-id Article message-id 2359 6.2.3.2. Description 2361 The BODY command behaves identically to the ARTICLE command except 2362 that, if the article exists, the response code is 222 instead of 220 2363 and only the body is presented (the empty line separating the headers 2364 and body MUST NOT be included). 2366 6.2.3.3. Examples 2368 Example of a successful retrieval of the body of an article (using no 2369 article number): 2371 [C] GROUP misc.test 2372 [S] 211 1234 3000234 3002322 misc.test 2373 [C] BODY 2374 [S] 222 3000234 <45223423@example.com> 2375 [S] This is just a test article. 2377 [S] . 2379 Example of a successful retrieval of the body of an article by 2380 message-id: 2382 [C] BODY <45223423@example.com> 2383 [S] 222 0 <45223423@example.com> 2384 [S] This is just a test article. 2385 [S] . 2387 Example of an unsuccessful retrieval of the body of an article by 2388 message-id: 2390 [C] BODY 2391 [S] 430 No Such Article Found 2393 Example of an unsuccessful retrieval of the body of an article by 2394 number: 2396 [C] GROUP misc.test 2397 [S] 211 1234 3000234 3002322 misc.test 2398 [C] BODY 300256 2399 [S] 423 No article with that number 2401 Example of an unsuccessful retrieval of the body of an article by 2402 number because no newsgroup was selected first: 2404 [Assumes currently selected newsgroup is invalid.] 2405 [C] BODY 300256 2406 [S] 412 No newsgroup selected 2408 Example of an attempt to retrieve the body of an article when the 2409 currently selected newsgroup is empty: 2411 [C] GROUP example.empty.newsgroup 2412 [S] 211 0 0 0 example.empty.newsgroup 2413 [C] BODY 2414 [S] 420 No current article selected 2416 6.2.4. STAT 2418 6.2.4.1. Usage 2420 This command is mandatory. 2422 Syntax 2424 STAT message-id 2425 STAT number 2426 STAT 2428 Responses 2430 First form (message-id specified) 2432 223 0|n message-id Article exists 2433 430 No article with that message-id 2435 Second form (article number specified) 2437 223 n message-id Article exists 2438 412 No newsgroup selected 2439 423 No article with that number 2441 Third form (current article number used) 2443 223 n message-id Article exists 2444 412 No newsgroup selected 2445 420 Current article number is invalid 2447 Parameters 2449 number Requested article number 2450 n Returned article number 2451 message-id Article message-id 2453 6.2.4.2. Description 2455 The STAT command behaves identically to the ARTICLE command except 2456 that, if the article exists, it is NOT presented to the client and 2457 the response code is 223 instead of 220. Note that the response is 2458 NOT multi-line. 2460 This command allows the client to determine whether an article 2461 exists, and in the second and third forms what its message-id is, 2462 without having to process an arbitrary amount of text. 2464 6.2.4.3. Examples 2466 Example of STAT on an existing article (using no article number): 2468 [C] GROUP misc.test 2469 [S] 211 1234 3000234 3002322 misc.test 2471 [C] STAT 2472 [S] 223 3000234 <45223423@example.com> 2474 Example of STAT on an existing article by message-id: 2476 [C] STAT <45223423@example.com> 2477 [S] 223 0 <45223423@example.com> 2479 Example of STAT on an article not on the server by message-id: 2481 [C] STAT 2482 [S] 430 No Such Article Found 2484 Example of STAT on an article not in the server by number: 2486 [C] GROUP misc.test 2487 [S] 211 1234 3000234 3002322 misc.test 2488 [C] STAT 300256 2489 [S] 423 No article with that number 2491 Example of STAT on an article by number when no newsgroup was 2492 selected first: 2494 [Assumes currently selected newsgroup is invalid.] 2495 [C] STAT 300256 2496 [S] 412 No newsgroup selected 2498 Example of STAT on an article when the currently selected newsgroup 2499 is empty: 2501 [C] GROUP example.empty.newsgroup 2502 [S] 211 0 0 0 example.empty.newsgroup 2503 [C] STAT 2504 [S] 420 No current article selected 2506 Example of STAT by message-id on a server which sometimes reports the 2507 actual article number: 2509 [C] GROUP misc.test 2510 [S] 211 1234 3000234 3002322 misc.test 2511 [C] STAT 2512 [S] 223 3000234 <45223423@example.com> 2513 [C] STAT <45223423@example.com> 2514 [S] 223 0 <45223423@example.com> 2515 [C] STAT <45223423@example.com> 2516 [S] 223 3000234 <45223423@example.com> 2517 [C] GROUP example.empty.newsgroup 2518 [S] 211 0 0 0 example.empty.newsgroup 2520 [C] STAT <45223423@example.com> 2521 [S] 223 0 <45223423@example.com> 2522 [C] GROUP alt.crossposts 2523 [S] 211 9999 111111 222222 alt.crossposts 2524 [C] STAT <45223423@example.com> 2525 [S] 223 123456 <45223423@example.com> 2526 [C] STAT 2527 [S] 223 111111 <23894720@example.com> 2529 The first STAT command establishes the identity of an article in the 2530 group. The second and third show that the server may, but need not, 2531 give the article number when the message-id is specified. The fourth 2532 STAT command shows that zero must be specified if the article isn't 2533 in the currently selected newsgroup, the fifth shows that the number, 2534 if provided, must be that relating to the currently selected 2535 newsgroup, and the last one shows that the current article number is 2536 still not changed by the use of STAT with a message-id even if it 2537 returns an article number. 2539 6.3. Article posting 2541 Article posting is done in one of two ways: individual article 2542 posting from news reading clients using POST, and article transfer 2543 from other news servers using IHAVE. 2545 6.3.1. POST 2547 6.3.1.1. Usage 2549 Indicating capability: POST 2551 This command MUST NOT be pipelined. 2553 Syntax 2555 POST 2557 Responses 2559 Initial responses 2561 340 Send article to be posted 2562 440 Posting not permitted 2564 Subsequent responses 2566 240 Article received OK 2567 441 Posting failed 2569 6.3.1.2. Description 2571 If posting is allowed, a 340 response MUST be returned to indicate 2572 that the article to be posted should be sent. If posting is 2573 prohibited for some installation-dependent reason, a 440 response 2574 MUST be returned. 2576 If posting is permitted, the article MUST be in the format specified 2577 in Section 3.6 and MUST be sent by the client to the server as a 2578 multi-line data block (see Section 3.1.1). Thus a single dot (".") 2579 on a line indicates the end of the text, and lines starting with a 2580 dot in the original text have that dot doubled during transmission. 2582 Following the presentation of the termination sequence by the client, 2583 the server MUST return a response indicating success or failure of 2584 the article transfer. Note that response codes 340 and 440 are used 2585 in direct response to the POST command. Others are returned 2586 following the sending of the article. 2588 A response of 240 SHOULD indicate that, barring unforeseen server 2589 errors, the posted article will be made available on the server 2590 and/or transferred to other servers as appropriate, possibly 2591 following further processing. In other words, articles not wanted by 2592 the server SHOULD be rejected with a 441 response and not accepted 2593 and silently discarded. However, the client SHOULD NOT assume that 2594 the article has been successfully transferred unless it receives an 2595 affirmative response from the server, and SHOULD NOT assume that it 2596 is being made available to other clients without explicitly checking 2597 (for example using the STAT command). 2599 If the session is interrupted before the response is received, it is 2600 possible that an affirmative response was sent but has been lost. 2601 Therefore, in any subsequent session, the client SHOULD either check 2602 whether the article was successfully posted before resending or 2603 ensure that the server will allocate the same message-id to the new 2604 attempt (see Appendix A.2) - the latter approach is preferred since 2605 the article might not have been made available for reading yet (for 2606 example, it may have to go through a moderation process). 2608 6.3.1.3. Examples 2610 Example of a successful posting: 2612 [C] POST 2613 [S] 340 Input article; end with . 2614 [C] From: "Demo User" 2615 [C] Newsgroups: misc.test 2616 [C] Subject: I am just a test article 2617 [C] Organization: An Example Net 2618 [C] 2619 [C] This is just a test article. 2620 [C] . 2621 [S] 240 Article received OK 2623 Example of an unsuccessful posting: 2625 [C] POST 2626 [S] 340 Input article; end with . 2627 [C] From: "Demo User" 2628 [C] Newsgroups: misc.test 2629 [C] Subject: I am just a test article 2630 [C] Organization: An Example Net 2631 [C] 2632 [C] This is just a test article. 2633 [C] . 2634 [S] 441 Posting failed 2636 Example of an attempt to post when posting is not allowed: 2638 [Initial connection set-up completed.] 2639 [S] 201 NNTP Service Ready, posting prohibited 2640 [C] POST 2641 [S] 440 Posting not permitted 2643 6.3.2. IHAVE 2645 6.3.2.1. Usage 2647 Indicating capability: IHAVE 2649 This command MUST NOT be pipelined. 2651 Syntax 2653 IHAVE message-id 2655 Responses 2656 Initial responses 2658 335 Send article to be transferred 2659 435 Article not wanted 2660 436 Transfer not possible; try again later 2662 Subsequent responses 2664 235 Article transferred OK 2665 436 Transfer failed; try again later 2666 437 Transfer rejected; do not retry 2668 Parameters 2670 message-id Article message-id 2672 6.3.2.2. Description 2674 The IHAVE command informs the server that the client has an article 2675 with the specified message-id. If the server desires a copy of that 2676 article a 335 response MUST be returned, instructing the client to 2677 send the entire article. If the server does not want the article 2678 (if, for example, the server already has a copy of it), a 435 2679 response MUST be returned, indicating that the article is not wanted. 2680 Finally, if the article isn't wanted immediately but the client 2681 should retry later if possible (if, for example, another client is in 2682 the process of sending the same article to the server), a 436 2683 response MUST be returned. 2685 If transmission of the article is requested, the client MUST send the 2686 entire article, including headers and body, to the server as a multi- 2687 line data block (see Section 3.1.1). Thus a single dot (".") on a 2688 line indicates the end of the text, and lines starting with a dot in 2689 the original text have that dot doubled during transmission. The 2690 server MUST return either a 235 response, indicating that the article 2691 was successfully transferred, a 436 response, indicating that the 2692 transfer failed but should be tried again later, or a 437 response, 2693 indicating that the article was rejected. 2695 This function differs from the POST command in that it is intended 2696 for use in transferring already-posted articles between hosts. It 2697 SHOULD NOT be used when the client is a personal news reading 2698 program, since use of this command indicates that the article has 2699 already been posted at another site and is simply being forwarded 2700 from another host. However, despite this, the server MAY elect not 2701 to post or forward the article if, after further examination of the 2702 article, it deems it inappropriate to do so. Reasons for such 2703 subsequent rejection of an article may include such problems as 2704 inappropriate newsgroups or distributions, disc space limitations, 2705 article lengths, garbled headers, and the like. These are typically 2706 restrictions enforced by the server host's news software and not 2707 necessarily the NNTP server itself. 2709 The client SHOULD NOT assume that the article has been successfully 2710 transferred unless it receives an affirmative response from the 2711 server. A lack of response (such as a dropped network connection or 2712 a network timeout) SHOULD be treated the same as a 436 response. 2714 Because some news server software may not be able immediately to 2715 determine whether or not an article is suitable for posting or 2716 forwarding, an NNTP server MAY acknowledge the successful transfer of 2717 the article (with a 235 response) but later silently discard it. 2719 6.3.2.3. Examples 2721 Example of successfully sending an article to another site: 2723 [C] IHAVE 2724 [S] 335 Send it; end with . 2725 [C] Path: pathost!demo!somewhere!not-for-mail 2726 [C] From: "Demo User" 2727 [C] Newsgroups: misc.test 2728 [C] Subject: I am just a test article 2729 [C] Date: 6 Oct 1998 04:38:40 -0500 2730 [C] Organization: An Example Com, San Jose, CA 2731 [C] Message-ID: 2732 [C] 2733 [C] This is just a test article. 2734 [C] . 2735 [S] 235 Article transferred OK 2737 Example of sending an article to another site that rejects it. Note 2738 that the message-id in the IHAVE command is not the same as the one 2739 in the article headers; while this is bad practice and SHOULD NOT be 2740 done, it is not forbidden. 2742 [C] IHAVE 2743 [S] 335 Send it; end with . 2744 [C] Path: pathost!demo!somewhere!not-for-mail 2745 [C] From: "Demo User" 2746 [C] Newsgroups: misc.test 2747 [C] Subject: I am just a test article 2748 [C] Date: 6 Oct 1998 04:38:40 -0500 2749 [C] Organization: An Example Com, San Jose, CA 2750 [C] Message-ID: 2751 [C] 2753 [C] This is just a test article. 2754 [C] . 2755 [S] 437 Article rejected; don't send again 2757 Example of sending an article to another site where the transfer 2758 fails: 2760 [C] IHAVE 2761 [S] 335 Send it; end with . 2762 [C] Path: pathost!demo!somewhere!not-for-mail 2763 [C] From: "Demo User" 2764 [C] Newsgroups: misc.test 2765 [C] Subject: I am just a test article 2766 [C] Date: 6 Oct 1998 04:38:40 -0500 2767 [C] Organization: An Example Com, San Jose, CA 2768 [C] Message-ID: 2769 [C] 2770 [C] This is just a test article. 2771 [C] . 2772 [S] 436 Transfer failed 2774 Example of sending an article to a site that already has it: 2776 [C] IHAVE 2777 [S] 435 Duplicate 2779 Example of sending an article to a site that requests the article be 2780 tried again later: 2782 [C] IHAVE 2783 [S] 436 Retry later 2785 7. Information commands 2787 This section lists other commands that may be used at any time 2788 between the beginning of a session and its termination. Using these 2789 commands does not alter any state information, but the response 2790 generated from their use may provide useful information to clients. 2792 7.1. DATE 2794 7.1.1. Usage 2796 Indicating capability: READER 2798 Syntax 2800 DATE 2802 Responses 2804 111 yyyymmddhhmmss server date and time 2806 Parameters 2808 yyyymmddHHmmss Current UTC date and time on server 2810 7.1.2. Description 2812 This command exists to help clients find out the current Coordinated 2813 Universal Time [TF.686-1] from the server's perspective. This 2814 command SHOULD NOT be used as a substitute for NTP [RFC1305] but to 2815 provide information that might be useful when using the NEWNEWS 2816 command (see Section 7.4). 2818 The DATE command MUST return a timestamp from the same clock as is 2819 used for determining article arrival and group creation times (see 2820 Section 6). This clock SHOULD be monotonic, and adjustments SHOULD 2821 be made by running it fast or slow compared to "real" time rather 2822 than by making sudden jumps. A system providing NNTP service SHOULD 2823 keep the system clock as accurate as possible, either with NTP or by 2824 some other method. 2826 The server MUST return a 111 response specifying the date and time on 2827 the server in the form yyyymmddhhmmss. This date and time is in 2828 Coordinated Universal Time. 2830 7.1.3. Examples 2832 [C] DATE 2833 [S] 111 19990623135624 2835 7.2. HELP 2837 7.2.1. Usage 2839 This command is mandatory. 2841 Syntax 2843 HELP 2845 Responses 2847 100 Help text follows (multi-line) 2849 7.2.2. Description 2851 This command provides a short summary of the commands that are 2852 understood by this implementation of the server. The help text will 2853 be presented as a multi-line data block following the 100 response 2854 code. 2856 This text is not guaranteed to be in any particular format (but must 2857 be UTF-8) and MUST NOT be used by clients as a replacement for the 2858 CAPABILITIES command described in Section 5.2. 2860 7.2.3. Examples 2862 [C] HELP 2863 [S] 100 Help text follows 2864 [S] This is some help text. There is no specific 2865 [S] formatting requirement for this test, though 2866 [S] it is customary for it to list the valid commands 2867 [S] and give a brief definition of what they do 2868 [S] . 2870 7.3. NEWGROUPS 2872 7.3.1. Usage 2874 Indicating capability: READER 2875 Syntax 2877 NEWGROUPS date time [GMT] 2879 Responses 2881 231 List of new newsgroups follows (multi-line) 2883 Parameters 2885 date Date in yymmdd or yyyymmdd format 2886 time Time in hhmmss format 2888 7.3.2. Description 2890 This command returns a list of newsgroups created on the server since 2891 the specified date and time. The results are in the same format as 2892 the LIST ACTIVE command (see Section 7.6.3). However, they MAY 2893 include groups not available on the server (and so not returned by 2894 LIST ACTIVE) and MAY omit groups for which the creation date is not 2895 available. 2897 The date is specified as 6 or 8 digits in the format [xx]yymmdd, 2898 where xx is the first two digits of the year (19-99), yy is the last 2899 two digits of the year (00-99), mm is the month (01-12), and dd is 2900 the day of the month (01-31). Clients SHOULD specify all four digits 2901 of the year. If the first two digits of the year are not specified 2902 (this is supported only for backwards compatibility), the year is to 2903 be taken from the current century if yy is smaller than or equal to 2904 the current year, otherwise the year is from the previous century. 2906 The time is specified as 6 digits in the format hhmmss, where hh is 2907 the hours in the 24-hour clock (00-23), mm is the minutes (00-59), 2908 and ss is the seconds (00-60, to allow for leap seconds). The token 2909 "GMT" specifies that the date and time are given in Coordinated 2910 Universal Time [TF.686-1]; if it is omitted then the date and time 2911 are specified in the server's local timezone. Note that there is no 2912 way using the protocol specified in this document to establish the 2913 server's local timezone. 2915 Note that an empty list is a possible valid response and indicates 2916 that there are no new newsgroups since that date-time. 2918 Clients SHOULD make all queries using Coordinated Universal Time 2919 (i.e. by including the "GMT" argument) when possible. 2921 7.3.3. Examples 2923 Example where there are new groups: 2925 [C] NEWGROUPS 19990624 000000 GMT 2926 [S] 231 list of new newsgroups follows 2927 [S] alt.rfc-writers.recovery 4 1 y 2928 [S] tx.natives.recovery 89 56 y 2929 [S] . 2931 Example where there are no new groups: 2933 [C] NEWGROUPS 19990624 000000 GMT 2934 [S] 231 list of new newsgroups follows 2935 [S] . 2937 7.4. NEWNEWS 2939 7.4.1. Usage 2941 Indicating capability: NEWNEWS 2943 Syntax 2945 NEWNEWS wildmat date time [GMT] 2947 Responses 2949 230 List of new articles follows (multi-line) 2951 Parameters 2953 wildmat Newsgroups of interest 2954 date Date in yymmdd or yyyymmdd format 2955 time Time in hhmmss format 2957 7.4.2. Description 2959 This command returns a list of message-ids of articles posted or 2960 received on the server, in the newsgroups whose names match the 2961 wildmat, since the specified date and time. One message-id is sent 2962 on each line; the order of the response has no specific significance 2963 and may vary from response to response in the same session. A 2964 message-id MAY appear more than once; if it does so, it has the same 2965 meaning as if it appeared only once. 2967 Date and time are in the same format as the NEWGROUPS command (see 2968 Section 7.3). 2970 Note that an empty list is a possible valid response and indicates 2971 that there is currently no new news in the relevant groups. 2973 Clients SHOULD make all queries in Coordinated Universal Time (i.e. 2974 by using the "GMT" argument) when possible. 2976 7.4.3. Examples 2978 Example where there are new articles: 2980 [C] NEWNEWS news.*,sci.* 19990624 000000 GMT 2981 [S] 230 list of new articles by message-id follows 2982 [S] 2983 [S] 2984 [S] . 2986 Example where there are no new articles: 2988 [C] NEWNEWS alt.* 19990624 000000 GMT 2989 [S] 230 list of new articles by message-id follows 2990 [S] . 2992 7.5. Time 2994 As described in Section 6, each article has an arrival timestamp. 2995 Each newsgroup also has a creation timestamp. These timestamps are 2996 used by the NEWNEWS and NEWGROUP commands to construct their 2997 responses. 2999 Clients can ensure that they do not have gaps in lists of articles or 3000 groups by using the DATE command in the following manner: 3002 First session: 3003 Issue DATE command and record result 3004 Issue NEWNEWS command using a previously chosen timestamp 3006 Subsequent sessions: 3007 Issue DATE command and hold result in temporary storage 3008 Issue NEWNEWS command using timestamp saved from previous session 3009 Overwrite saved timestamp with that currently in temporary storage 3011 In order to allow for minor errors, clients MAY want to adjust the 3012 timestamp back by two or three minutes before using it in NEWNEWS. 3014 7.5.1. Examples 3016 First session: 3018 [C] DATE 3019 [S] 111 20010203112233 3020 [C] NEWNEWS local.chat 20001231 235959 GMT 3021 [S] 230 list follows 3022 [S] 3023 [S] 3024 [S] 3025 [S] . 3027 Second session (the client has subtracted 3 minutes from the 3028 timestamp returned previously): 3030 [C] DATE 3031 [S] 111 20010204003344 3032 [C] NEWNEWS local.chat 20010203 111933 GMT 3033 [S] 230 list follows 3034 [S] 3035 [S] 3036 [S] 3037 [S] . 3039 Note how arrived in the 3 minute gap and so 3040 is listed in both responses. 3042 7.6. The LIST commands 3044 The LIST family of commands all return information that is multi-line 3045 and, in general, can be expected not to change during the session. 3046 Often the information is related to newsgroups, in which case the 3047 response has one line per newsgroup and a wildmat MAY be provided to 3048 restrict the groups for which information is returned. 3050 The set of available keywords (including those provided by 3051 extensions) is given in the capability list with capability label 3052 LIST. 3054 7.6.1. LIST 3056 7.6.1.1. Usage 3058 Indicating capability: LIST 3059 Syntax 3061 LIST [keyword [wildmat|argument]] 3063 Responses 3065 215 Information follows (multi-line) 3067 Parameters 3069 keyword information requested [1] 3070 argument specific to keyword 3071 wildmat groups of interest 3073 [1] If no keyword is provided, it defaults to ACTIVE. 3075 7.6.1.2. Description 3077 The LIST command allows the server to provide blocks of information 3078 to the client. This information may be global or may be related to 3079 newsgroups; in the latter case, the information may be returned 3080 either for all groups or only for those matching a wildmat. Each 3081 block of information is represented by a different keyword. The 3082 command returns the specific information identified by the keyword. 3084 If the information is available, it is returned as a multi-line data 3085 block following the 215 response code. The format of the information 3086 depends on the keyword. The information MAY be affected by the 3087 additional argument, but the format MUST NOT be. 3089 If the information is based on newsgroups and the optional wildmat 3090 argument is specified, the response is limited to only the groups (if 3091 any) whose names match the wildmat and for which the information is 3092 available. 3094 Note that an empty list is a possible valid response; for a 3095 newsgroup-based keyword, it indicates that there are no groups 3096 meeting the above criteria. 3098 If the keyword is not recognised, or if an argument is specified and 3099 the keyword does not expect one, a 501 response code MUST BE 3100 returned. If the keyword is recognised but the server does not 3101 maintain the information, a 503 response code MUST BE returned. 3103 The LIST command MUST NOT change the visible state of the server in 3104 any way; that is, the behaviour of subsequent commands MUST NOT be 3105 affected by whether the LIST command was issued or not. For example, 3106 it MUST NOT make groups available that otherwise would not have been. 3108 7.6.1.3. Examples 3110 Example of LIST with the ACTIVE keyword: 3112 [C] LIST ACTIVE 3113 [S] 215 list of newsgroups follows 3114 [S] misc.test 3002322 3000234 y 3115 [S] comp.risks 442001 441099 m 3116 [S] alt.rfc-writers.recovery 4 1 y 3117 [S] tx.natives.recovery 89 56 y 3118 [S] tx.natives.recovery.d 11 9 n 3119 [S] . 3121 Example of LIST with no keyword: 3123 [C] LIST 3124 [S] 215 list of newsgroups follows 3125 [S] misc.test 3002322 3000234 y 3126 [S] comp.risks 442001 441099 m 3127 [S] alt.rfc-writers.recovery 4 1 y 3128 [S] tx.natives.recovery 89 56 y 3129 [S] tx.natives.recovery.d 11 9 n 3130 [S] . 3132 The output is identical to that of the previous example. 3134 Example of LIST on a newsgroup-based keyword with and without 3135 wildmat: 3137 [C] LIST ACTIVE.TIMES 3138 [S] 215 information follows 3139 [S] misc.test 930445408 3140 [S] alt.rfc-writers.recovery 930562309 3141 [S] tx.natives.recovery 930678923 3142 [S] . 3143 [C] LIST ACTIVE.TIMES tx.* 3144 [S] 215 information follows 3145 [S] tx.natives.recovery 930678923 3146 [S] . 3148 Example of LIST returning an error where the keyword is recognized 3149 but the software does not maintain this information: 3151 [C] CAPABILITIES 3152 [S] 101 Capability list: 3153 [S] VERSION 2 3154 [S] READER 3155 [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA 3157 [S] . 3158 [C] LIST XTRA.DATA 3159 [S] 503 Data item not stored 3161 Example of LIST where the keyword is not recognised: 3163 [C] CAPABILITIES 3164 [S] 101 Capability list: 3165 [S] VERSION 2 3166 [S] READER 3167 [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA 3168 [S] . 3169 [C] LIST DISTRIB.PATS 3170 [S] 501 Syntax Error 3172 7.6.2. Standard LIST keywords 3174 This specification defines the following LIST keywords: 3176 +----------------------+----------------------+---------------------+ 3177 | Keyword | Definition | Status | 3178 +----------------------+----------------------+---------------------+ 3179 | ACTIVE | Section 7.6.3 | Mandatory if the | 3180 | | | READER capability | 3181 | | | is advertised | 3182 | | | | 3183 | ACTIVE.TIMES | Section 7.6.4 | Optional | 3184 | | | | 3185 | DISTRIB.PATS | Section 7.6.5 | Optional | 3186 | | | | 3187 | HEADERS | Section 8.6 | Mandatory if the | 3188 | | | HDR capability is | 3189 | | | advertised | 3190 | | | | 3191 | NEWSGROUPS | Section 7.6.6 | Mandatory if the | 3192 | | | READER capability | 3193 | | | is advertised | 3194 | | | | 3195 | OVERVIEW.FMT | Section 8.4 | Mandatory if the | 3196 | | | OVER capability is | 3197 | | | advertised | 3198 +----------------------+----------------------+---------------------+ 3200 Where one of these LIST keywords is supported by a server, it MUST 3201 have the meaning given in the following sub-sections. 3203 7.6.3. LIST ACTIVE 3205 This keyword MUST be supported by servers advertising the READER 3206 capability. 3208 LIST ACTIVE returns a list of valid newsgroups and associated 3209 information. If no wildmat is specified, the server MUST include 3210 every group that the client is permitted to select with the GROUP 3211 (Section 6.1.1) command. Each line of this list consists of four 3212 fields separated from each other by one or more spaces: 3213 o the name of the newsgroup; 3214 o the reported high water mark for the group; 3215 o the reported low water mark for the group; 3216 o the current status of the group on this server. 3218 The reported high and low water marks are as described in the GROUP 3219 command (see Section 6.1.1). 3221 The status field is typically one of: 3223 "y" posting is permitted 3225 "n" posting is not permitted 3227 "m" postings will be forwarded to the newsgroup moderator 3229 The server SHOULD use these values when these meanings are required 3230 and MUST NOT use them with any other meaning. Other values for the 3231 status may exist; the definition of these other values and the 3232 circumstances under which they are returned may be specified in an 3233 extension or may be private to the server. A client SHOULD treat an 3234 unrecognized status as giving no information. 3236 The status of a newsgroup only indicates how posts to that newsgroup 3237 are normally processed and is not necessarily customised to the 3238 specific client. For example, if the current client is forbidden 3239 from posting, then this will apply equally to groups with status "y". 3240 Conversely, a client with special privileges (not defined by this 3241 specification) might be able to post to a group with status "n". 3243 For example: 3245 [C] LIST ACTIVE 3246 [S] 215 list of newsgroups follows 3247 [S] misc.test 3002322 3000234 y 3248 [S] comp.risks 442001 441099 m 3249 [S] alt.rfc-writers.recovery 4 1 y 3250 [S] tx.natives.recovery 89 56 y 3252 [S] tx.natives.recovery.d 11 9 n 3253 [S] . 3255 or, on an implementation that includes leading zeroes: 3257 [C] LIST ACTIVE 3258 [S] 215 list of newsgroups follows 3259 [S] misc.test 0003002322 0003000234 y 3260 [S] comp.risks 0000442001 0000441099 m 3261 [S] alt.rfc-writers.recovery 0000000004 0000000001 y 3262 [S] tx.natives.recovery 0000000089 0000000056 y 3263 [S] tx.natives.recovery.d 0000000011 0000000009 n 3264 [S] . 3266 The information is newsgroup-based and a wildmat MAY be specified, in 3267 which case the response is limited to only the groups (if any) whose 3268 names match the wildmat. For example: 3270 [C] LIST ACTIVE *.recovery 3271 [S] 215 list of newsgroups follows 3272 [S] alt.rfc-writers.recovery 4 1 y 3273 [S] tx.natives.recovery 89 56 y 3274 [S] . 3276 7.6.4. LIST ACTIVE.TIMES 3278 This keyword is optional. 3280 The active.times list is maintained by some NNTP servers to contain 3281 information about who created a particular newsgroup and when. Each 3282 line of this list consists of three fields separated from each other 3283 by one or more spaces. The first field is the name of the newsgroup. 3284 The second is the time when this group was created on this news 3285 server, measured in seconds since the start of January 1, 1970. The 3286 third is plain text intended to describe the entity that created the 3287 newsgroup; it is often a mailbox as defined in RFC 2822 [RFC2822]. 3288 For example: 3290 [C] LIST ACTIVE.TIMES 3291 [S] 215 information follows 3292 [S] misc.test 930445408 3293 [S] alt.rfc-writers.recovery 930562309 3294 [S] tx.natives.recovery 930678923 3295 [S] . 3297 The list MAY omit newsgroups for which the information is unavailable 3298 and MAY include groups not available on the server; in particular, it 3299 MAY omit all groups created before the date and time of the oldest 3300 entry. The client MUST NOT assume that the list is complete or that 3301 it matches the list returned by the LIST ACTIVE (Section 7.6.3) 3302 command. The NEWGROUPS command (Section 7.3) may provide a better 3303 way to access this information, and the results of the two commands 3304 SHOULD be consistent except that, if the latter is invoked with a 3305 date and time earlier than the oldest entry in active.times list, its 3306 result may include extra groups. 3308 The information is newsgroup-based and a wildmat MAY be specified, in 3309 which case the response is limited to only the groups (if any) whose 3310 names match the wildmat. 3312 7.6.5. LIST DISTRIB.PATS 3314 This keyword is optional. 3316 The distrib.pats list is maintained by some NNTP servers to assist 3317 clients to choose a value for the content of the Distribution header 3318 of a news article being posted. Each line of this list consists of 3319 three fields separated from each other by a colon (":"). The first 3320 field is a weight, the second field is a wildmat (which may be a 3321 simple newsgroup name), and the third field is a value for the 3322 Distribution header content. For example: 3324 [C] LIST DISTRIB.PATS 3325 [S] 215 information follows 3326 [S] 10:local.*:local 3327 [S] 5:*:world 3328 [S] 20:local.here.*:thissite 3329 [S] . 3331 The client MAY use this information to construct an appropriate 3332 Distribution header given the name of a newsgroup. To do so, it 3333 should determine the lines whose second field matches the newsgroup 3334 name, select from among them the line with the highest weight (with 0 3335 being the lowest), and use the value of the third field to construct 3336 the Distribution header. 3338 The information is not newsgroup-based and an argument MUST NOT be 3339 specified. 3341 7.6.6. LIST NEWSGROUPS 3343 This keyword MUST be supported by servers advertising the READER 3344 capability. 3346 The newsgroups list is maintained by NNTP servers to contain the name 3347 of each newsgroup that is available on the server and a short 3348 description about the purpose of the group. Each line of this list 3349 consists of two fields separated from each other by one or more space 3350 or TAB characters (the usual practice is a single TAB). The first 3351 field is the name of the newsgroup and the second is a short 3352 description of the group. For example: 3354 [C] LIST NEWSGROUPS 3355 [S] 215 information follows 3356 [S] misc.test General Usenet testing 3357 [S] alt.rfc-writers.recovery RFC Writers Recovery 3358 [S] tx.natives.recovery Texas Natives Recovery 3359 [S] . 3361 The list MAY omit newsgroups for which the information is unavailable 3362 and MAY include groups not available on the server. The client MUST 3363 NOT assume that the list is complete or that it matches the list 3364 returned by LIST ACTIVE. 3366 The description SHOULD be in UTF-8. However, servers often obtain 3367 the information from external sources. These sources may have used 3368 different encodings (ones that use octets in the range 128 to 255 in 3369 some other manner) and, in this case, the server MAY pass it on 3370 unchanged; therefore clients MUST be prepared to receive such 3371 descriptions. 3373 The information is newsgroup-based and a wildmat MAY be specified, in 3374 which case the response is limited to only the groups (if any) whose 3375 names match the wildmat. 3377 8. Article field access commands 3379 This section lists commands that may be used to access specific 3380 article fields; that is, headers of articles and metadata about 3381 articles. These commands typically fetch data from an "overview 3382 database", which is a database of headers extracted from incoming 3383 articles plus metadata determined as the article arrives. Only 3384 certain fields are included in the database. 3386 This section is based on the Overview/NOV database [ROBE1995] 3387 developed by Geoff Collyer. 3389 8.1. Article metadata 3391 Article "metadata" is data about articles that does not occur within 3392 the article itself. Each metadata item has a name which MUST begin 3393 with a colon (and which MUST NOT contain a colon elsewhere within 3394 it). As with header names, metadata item names are not case- 3395 sensitive. 3397 When generating a metadata item, the server MUST compute it for 3398 itself and MUST NOT trust any related value provided in the article. 3399 (In particular, a Lines or Bytes header in the article MUST NOT be 3400 assumed to specify the correct number of lines or bytes in the 3401 article.) If the server has access to several non-identical copies 3402 of an article, the value returned MUST be correct for any copy of 3403 that article retrieved during the same session. 3405 This specification defines two metadata items: ":bytes" and ":lines". 3406 Other metadata items may be defined by extensions. The names of 3407 metadata items defined by registered extensions MUST NOT begin with 3408 ":x-". To avoid the risk of a clash with a future registered 3409 extension, the names of metadata items defined by private extensions 3410 SHOULD begin with ":x-". 3412 8.1.1. The :bytes metadata item 3414 The :bytes metadata item for an article is a decimal integer. It 3415 SHOULD equal the number of octets in the entire article - headers, 3416 body, and separating empty line (counting a CRLF pair as two octets, 3417 and excluding both the "." CRLF terminating the response and any "." 3418 added for "dot-stuffing" purposes). 3420 Note to client implementers: some existing servers return a value 3421 different to that above. The commonest reasons for this are: 3422 o counting a CRLF pair as one octet; 3423 o including the "." character used for dot-stuffing in the number; 3424 o including the terminating "." CRLF in the number; 3425 o using one copy of an article for counting the octets but then 3426 returning another one that differs in some (permitted) manner. 3427 Implementations should be prepared for such variation and MUST NOT 3428 rely on the value being accurate. 3430 8.1.2. The :lines metadata item 3432 The :lines metadata item for an article is a decimal integer. It 3433 MUST equal the number of lines in the article body (excluding the 3434 empty line separating headers and body); equivalently, it is two less 3435 than the number of CRLF pairs that the BODY command would return for 3436 that article (the extra two are those following the response code and 3437 the termination octet). 3439 8.2. Database consistency 3441 The information stored in the overview database may change over time. 3442 If the database records the content or absence of a given field (that 3443 is, a header or metadata item) for all articles, it is said to be 3444 "consistent" for that field. If it records the content of a header 3445 for some articles but not for others that nevertheless included that 3446 header, or records a metadata item for some articles but not others 3447 to which that item applies, it is said to be "inconsistent" for that 3448 field. 3450 The LIST OVERVIEW.FMT command SHOULD list all the fields for which 3451 the database is consistent at that moment. It MAY omit such fields 3452 (for example if it is not known whether the database is consistent or 3453 inconsistent). It MUST NOT include fields for which the database is 3454 inconsistent or which are not stored in the database. Therefore if a 3455 header appears in the LIST OVERVIEW.FMT output but not the OVER 3456 output for a given article, that header does not appear in the 3457 article, and similarly for metadata items. 3459 These rules assume the fields being stored in the database remain 3460 constant for long periods of time, with the database therefore being 3461 consistent. When the set of fields to be stored is changed, it will 3462 be inconsistent until either the database is rebuilt or the only 3463 articles remaining are those received since the change. Therefore 3464 the output from LIST OVERVIEW.FMT needs to be altered twice: before 3465 any fields stop being stored, they MUST be removed from the output, 3466 then when the database is once more known to be consistent, the new 3467 fields SHOULD be added to the output. 3469 If the HDR command uses the overview database rather than taking 3470 information directly from the articles, the same issues of 3471 consistency and inconsistency apply and the and the LIST HEADERS 3472 command SHOULD take the same approach as the LIST OVERVIEW.FMT 3473 command in resolving them. 3475 8.3. OVER 3477 8.3.1. Usage 3479 Indicating capability: OVER 3481 Syntax 3483 OVER message-id 3484 OVER range 3485 OVER 3487 Responses 3489 First form (message-id specified) 3491 224 Overview information follows (multi-line) 3492 430 No article with that message-id 3494 Second form (range specified) 3496 224 Overview information follows (multi-line) 3497 412 No newsgroup selected 3498 423 No articles in that range 3500 Third form (current article number used) 3502 224 Overview information follows (multi-line) 3503 412 No newsgroup selected 3504 420 Current article number is invalid 3506 Parameters 3508 range number(s) of articles 3509 message-id message-id of article 3511 8.3.2. Description 3513 The OVER command returns the contents of all the fields in the 3514 database for an article specified by message-id, or from a specified 3515 article or range of articles in the currently selected newsgroup. 3517 The message-id argument indicates a specific article. The range 3518 argument may be any of the following: 3520 o an article number 3521 o an article number followed by a dash to indicate all following 3522 o an article number followed by a dash followed by another article 3523 number 3524 If neither is specified, the current article number is used. 3526 Support for the first (message-id) form is optional. If is is 3527 supported, the OVER capability line MUST include the argument 3528 "MSGID". Otherwise, the capability line MUST NOT include this 3529 argument, and the OVER command MUST return the the generic response 3530 code 503 when this form is used. 3532 If the information is available, it is returned as a multi-line data 3533 block following the 224 response code and contains one line per 3534 article, sorted in numerical order of article number (note that 3535 unless the argument is a range including a dash, there will be 3536 exactly one line in the data block). Each line consists of a number 3537 of fields separated by a TAB. A field may be empty (in which case 3538 there will be two adjacent TABs), and a sequence of trailing TABs may 3539 be omitted. 3541 The first 8 fields MUST be the following, in order: 3543 "0" or article number (see below) 3544 Subject header content 3545 From header content 3546 Date header content 3547 Message-ID header content 3548 References header content 3549 :bytes metadata item 3550 :lines metadata item 3552 If the article is specified by message-id (the first form of the 3553 command), the article number MUST be replaced with zero, except that 3554 if there is a currently selected newsgroup and the article is present 3555 in that group, the server MAY use that article number (see the 3556 ARTICLE command (Section 6.2.1) and STAT examples (Section 6.2.4.3) 3557 for more details). In the other two forms of the command, the 3558 article number MUST be returned. 3560 Any subsequent fields are the contents of the other headers and 3561 metadata held in the database. 3563 For the five mandatory headers, the content of each field MUST be 3564 based on the content of the header (that is, with the header name and 3565 following colon and space removed). If the article does not contain 3566 that header, or if the content is empty, the field MUST be empty. 3567 For the two mandatory metadata items, the content of the field MUST 3568 be just the value, with no other text. 3570 For all subsequent fields that contain headers, the content MUST be 3571 the entire header line other than the trailing CRLF. For all 3572 subsequent fields that contain metadata, the field consists of the 3573 metadata name, a single space, and then the value. 3575 For all fields, the value is processed by first removing all CRLF 3576 pairs (that is, undoing any folding and removing the terminating 3577 CRLF) and then replacing each TAB with a single space. If there is 3578 no such header in the article, or no such metadata item, or no header 3579 or item stored in the database for that article, the corresponding 3580 field MUST be empty. 3582 Note that, after unfolding, the characters NUL, LF, and CR cannot 3583 occur in the header of an article offered by a conformant server. 3584 Nevertheless, servers SHOULD check for these characters and replace 3585 each one by a single space (so that, for example, CR LF LF TAB will 3586 become two spaces, since the CR and first LF will be removed by the 3587 unfolding process). This will encourage robustness in the face of 3588 non-conforming data; it is also possible that future versions of this 3589 specification could permit these characters to appear in articles. 3591 The server SHOULD NOT produce output for articles that no longer 3592 exist. 3594 If the argument is a message-id and no such article exists, a 430 3595 response MUST be returned. If the argument is a range or is omitted 3596 and the currently selected newsgroup is invalid, a 412 response MUST 3597 be returned. If the argument is a range and no articles in that 3598 number range exist in the currently selected newsgroup, including the 3599 case where the second number is less than the first one, a 423 3600 response MUST be returned. If the argument is omitted and the 3601 current article number is invalid, a 420 response MUST be returned. 3603 8.3.3. Examples 3605 In the first three examples, TAB has been replaced by vertical bar 3606 and some lines have been folded for readability. 3608 Example of a successful retrieval of overview information for an 3609 article (using no article number): 3611 [C] GROUP misc.test 3612 [S] 211 1234 3000234 3002322 misc.test 3613 [C] OVER 3614 [S] 224 Overview information follows 3615 [S] 300234|I am just a test article|"Demo User" 3616 |6 Oct 1998 04:38:40 -0500| 3617 <45223423@example.com>|<45454@example.net>|1234| 3618 17|Xref: news.example.com misc.test:3000363 3619 [S] . 3621 Example of a successful retrieval of overview information for an 3622 article by message-id: 3624 [C] CAPABILITIES 3625 [S] 101 Capability list: 3626 [S] VERSION 2 3627 [S] READER 3628 [S] OVER MSGID 3629 [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT 3630 [S] . 3631 [C] OVER <45223423@example.com> 3632 [S] 224 Overview information follows 3633 [S] 0|I am just a test article|"Demo User" 3634 |6 Oct 1998 04:38:40 -0500| 3635 <45223423@example.com>|<45454@example.net>|1234| 3636 17|Xref: news.example.com misc.test:3000363 3637 [S] . 3639 Note that the article number has been replaced by "0". 3641 Example of the same commands on a system that does not implement 3642 retrieval by message-id: 3644 [C] CAPABILITIES 3645 [S] 101 Capability list: 3646 [S] VERSION 2 3647 [S] READER 3648 [S] OVER 3649 [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT 3650 [S] . 3651 [C] OVER <45223423@example.com> 3652 [S] 503 Overview by message-id unsupported 3654 Example of a successful retrieval of overview information for a range 3655 of articles: 3657 [C] GROUP misc.test 3658 [S] 211 1234 3000234 3002322 misc.test 3659 [C] OVER 3000234-3000240 3660 [S] 224 Overview information follows 3661 [S] 300234|I am just a test article|"Demo User" 3662 |6 Oct 1998 04:38:40 -0500| 3663 <45223423@example.com>|<45454@example.net>|1234| 3664 17|Xref: news.example.com misc.test:3000363 3665 [S] 3000235|Another test article|nobody@nowhere.to 3666 (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>|| 3667 4818|37||Distribution: fi 3668 [S] 3000238|Re: I am just a test article|somebody@elsewhere.to| 3669 7 Oct 1998 11:38:40 +1200|| 3670 <45223423@to.to>|9234|51 3671 [S] . 3673 Note the missing "References" and Xref headers in the second line, 3674 the missing trailing field(s) in the first and last lines, and that 3675 there are only results for those articles that still exist. 3677 Example of an unsuccessful retrieval of overview information on an 3678 article by number: 3680 [C] GROUP misc.test 3681 [S] 211 1234 3000234 3002322 misc.test 3682 [C] OVER 300256 3683 [S] 423 No such article in this group 3685 Example of an invalid range: 3687 [C] GROUP misc.test 3688 [S] 211 1234 3000234 3002322 misc.test 3689 [C] OVER 3000444-3000222 3690 [S] 423 Empty range 3692 Example of an unsuccessful retrieval of overview information by 3693 number because no newsgroup was selected first: 3695 [Assumes currently selected newsgroup is invalid.] 3696 [C] OVER 3697 [S] 412 No newsgroup selected 3699 Example of an attempt to retrieve information when the currently 3700 selected newsgroup is empty: 3702 [C] GROUP example.empty.newsgroup 3703 [S] 211 0 0 0 example.empty.newsgroup 3704 [C] OVER 3705 [S] 420 No current article selected 3707 8.4. LIST OVERVIEW.FMT 3709 8.4.1. Usage 3710 Indicating capability: OVER 3712 Syntax 3714 LIST OVERVIEW.FMT 3716 Responses 3718 215 Information follows (multi-line) 3720 8.4.2. Description 3722 See Section 7.6.1 for general requirements of the LIST command. 3724 The LIST OVERVIEW.FMT command returns a description of the fields in 3725 the database for which it is consistent (as described above). The 3726 information is returned as a multi-line data block following the 215 3727 response code. The information contains one line per field in the 3728 order they are returned by the OVER command; the first 7 lines MUST 3729 (except for the case of letters) be exactly: 3731 Subject: 3732 From: 3733 Date: 3734 Message-ID: 3735 References: 3736 :bytes 3737 :lines 3739 except that, for compatibility with existing implementations, the 3740 last two lines MAY instead be: 3742 Bytes: 3743 Lines: 3745 even though they refer to metadata, not headers. 3747 All subsequent lines MUST consist of either a header name followed by 3748 ":full", or the name of a piece of metadata. 3750 There are no leading or trailing spaces in the output. 3752 Note that the 7 fixed lines describe the 2nd to 8th fields of the 3753 OVER output. The "full" suffix (which may use either uppercase, 3754 lowercase, or a mix) is a reminder that the corresponding fields 3755 include the header name. 3757 This command MAY generate different results if used more than once in 3758 a session. 3760 If the OVER command is not implemented, the meaning of the output 3761 from this command is not specified but it must still meet the above 3762 syntactic requirements. 3764 8.4.3. Examples 3766 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3767 output above, using the preferred format: 3769 [C] LIST OVERVIEW.FMT 3770 [S] 215 Order of fields in overview database. 3771 [S] Subject: 3772 [S] From: 3773 [S] Date: 3774 [S] Message-ID: 3775 [S] References: 3776 [S] :bytes 3777 [S] :lines 3778 [S] Xref:full 3779 [S] Distribution:full 3780 [S] . 3782 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3783 output above, using the alternative format: 3785 [C] LIST OVERVIEW.FMT 3786 [S] 215 Order of fields in overview database. 3787 [S] Subject: 3788 [S] From: 3789 [S] Date: 3790 [S] Message-ID: 3791 [S] References: 3792 [S] Bytes: 3793 [S] Lines: 3794 [S] Xref:FULL 3795 [S] Distribution:FULL 3796 [S] . 3798 8.5. HDR 3800 8.5.1. Usage 3801 Indicating capability: HDR 3803 Syntax 3805 HDR field message-id 3806 HDR field range 3807 HDR field 3809 Responses 3811 First form (message-id specified) 3813 225 Headers follow (multi-line) 3814 430 No article with that message-id 3816 Second form (range specified) 3818 225 Headers follow (multi-line) 3819 412 No newsgroup selected 3820 423 No articles in that range 3822 Third form (current article number used) 3824 225 Headers follow (multi-line) 3825 412 No newsgroup selected 3826 420 Current article number is invalid 3828 Parameters 3830 field name of field 3831 range number(s) of articles 3832 message-id message-id of article 3834 8.5.2. Description 3836 The HDR command provides access to specific fields from an article 3837 specified by message-id, or from a specified article or range of 3838 articles in the currently selected newsgroup. It MAY take the 3839 information directly from the articles or from the overview database. 3840 In the case of headers, an implementation MAY restrict the use of 3841 this command to a specific list of headers or MAY allow it to be used 3842 with any header; it may behave differently when it is used with a 3843 message-id argument and when it is used with a range or no argument. 3845 The required field argument is the name of a header with the colon 3846 omitted (e.g. "subject"), or the name of a metadata item including 3847 the leading colon (e.g. ":bytes"), and is case-insensitive. 3849 The message-id argument indicates a specific article. The range 3850 argument may be any of the following: 3851 o an article number 3852 o an article number followed by a dash to indicate all following 3853 o an article number followed by a dash followed by another article 3854 number 3855 If neither is specified, the current article number is used. 3857 If the information is available, it is returned as a multi-line data 3858 block following the 225 response code and contains one line for each 3859 article in the range that exists (note that unless the argument is a 3860 range including a dash, there will be exactly one line in the data 3861 block). The line consists of the article number, a space, and then 3862 the contents of the field. In the case of a header, the header name, 3863 colon, and the first space after the colon are all omitted. 3865 If the article is specified by message-id (the first form of the 3866 command), the article number MUST be replaced with zero, except that 3867 if there is a currently selected newsgroup and the article is present 3868 in that group, the server MAY use that article number (see the 3869 ARTICLE command (Section 6.2.1) and STAT examples (Section 6.2.4.3) 3870 for more details). In the other two forms of the command, the 3871 article number MUST be returned. 3873 Header contents are modified as follows: all CRLF pairs are removed, 3874 and then each TAB is replaced with a single space (note that this is 3875 the same transformation as is performed by the OVER command 3876 (Section 8.3.2), and the same comment concerning NUL, CR, and LF 3877 applies). 3879 Note the distinction between headers and metadata appearing to have 3880 the same meaning. Headers are always taken unchanged from the 3881 article; metadata are always calculated. For example, a request for 3882 "Lines" returns the contents of the "Lines" header of the specified 3883 articles, if any, no matter whether or not they accurately state the 3884 number of lines, while a request for ":lines" returns the line count 3885 metadata, which is always the actual number of lines irrespective of 3886 what any header may state. 3888 If the requested header is not present in the article or if it is 3889 present but empty, a line for that article is included in the output 3890 but the header content portion of the line is empty (the space after 3891 the article number MAY be retained or omitted). If the header occurs 3892 in a given article more than once, only the content of the first 3893 occurrence is returned by HDR. If any article number in the provided 3894 range does not exist in the group, no line for that article number is 3895 included in the output. 3897 If the second argument is a message-id and no such article exists, a 3898 430 response MUST be returned. If the second argument is a range or 3899 is omitted and the currently selected newsgroup is invalid, a 412 3900 response MUST be returned. If the second argument is a range and no 3901 articles in that number range exist in the currently selected 3902 newsgroup, including the case where the second number is less than 3903 the first one, a 423 response MUST be returned. If the second 3904 argument is omitted and the current article number is invalid, a 420 3905 response MUST be returned. 3907 A server MAY only allow HDR commands for a limited set of fields; it 3908 may behave differently in this respect for the first (message-id) 3909 form than for the other forms. If so, it MUST respond with the 3910 generic 503 response to attempts to request other fields, rather than 3911 returning erroneous results such as a successful empty response. 3913 If HDR uses the overview database and it is inconsistent for the 3914 requested field, the server MAY return what results it can or it MAY 3915 respond with the generic 503 response; in the latter case, the field 3916 MUST NOT appear in the output from LIST HEADERS. 3918 8.5.3. Examples 3920 Example of a successful retrieval of subject lines from a range of 3921 articles (3000235 has no Subject header, and 3000236 is missing): 3923 [C] GROUP misc.test 3924 [S] 211 1234 3000234 3002322 misc.test 3925 [C] HDR Subject 3000234-300238 3926 [S] 225 Headers follow 3927 [S] 3000234 I am just a test article 3928 [S] 3000235 3929 [S] 3000237 Re: I am just a test article 3930 [S] 3000238 Ditto 3931 [S] . 3933 Example of a successful retrieval of line counts from a range of 3934 articles: 3936 [C] GROUP misc.test 3937 [S] 211 1234 3000234 3002322 misc.test 3938 [C] HDR :lines 3000234-300238 3939 [S] 225 Headers follow 3940 [S] 3000234 42 3941 [S] 3000235 5 3942 [S] 3000237 11 3943 [S] 3000238 2378 3944 [S] . 3946 Example of a successful retrieval of the subject line from an article 3947 by message-id: 3949 [C] GROUP misc.test 3950 [S] 211 1234 3000234 3002322 misc.test 3951 [C] HDR subject 3952 [S] 225 Header information follows 3953 [S] 0 I am just a test article 3954 [S] . 3956 Example of a successful retrieval of the subject line from the 3957 current article: 3959 [C] GROUP misc.test 3960 [S] 211 1234 3000234 3002322 misc.test 3961 [C] HDR subject 3962 [S] 225 Header information follows 3963 [S] 3000234 I am just a test article 3964 [S] . 3966 Example of an unsuccessful retrieval of a header from an article by 3967 message-id: 3969 [C] HDR subject 3970 [S] 430 No Such Article Found 3972 Example of an unsuccessful retrieval of headers from articles by 3973 number because no newsgroup was selected first: 3975 [Assumes currently selected newsgroup is invalid.] 3976 [C] HDR subject 300256- 3977 [S] 412 No newsgroup selected 3979 Example of an unsuccessful retrieval of headers because the currently 3980 selected newsgroup is empty: 3982 [C] GROUP example.empty.newsgroup 3983 [S] 211 0 0 0 example.empty.newsgroup 3984 [C] HDR subject 1- 3985 [S] 423 No articles in that range 3987 Example of an unsuccessful retrieval of headers because the server 3988 does not allow HDR commands for that header: 3990 [C] GROUP misc.test 3991 [S] 211 1234 3000234 3002322 misc.test 3992 [C] HDR Content-Type 3000234-300238 3993 [S] 503 HDR not permitted on Content-Type 3995 8.6. LIST HEADERS 3997 8.6.1. Usage 3999 Indicating capability: HDR 4001 Syntax 4003 LIST HEADERS [MSGID|RANGE] 4005 Responses 4007 215 Field list follows (multi-line) 4009 Parameters 4011 MSGID requests list for access by message-id 4012 RANGE requests list for access by range 4014 8.6.2. Description 4016 See Section 7.6.1 for general requirements of the LIST command. 4018 The LIST HEADERS command returns a list of fields that may be 4019 retrieved using the HDR command. 4021 The information is returned as a multi-line data block following the 4022 215 response code and contains one line for each field name 4023 (excluding the trailing colon for headers and including the leading 4024 colon for metadata items). If the implementation allows any header 4025 to be retrieved, it MUST NOT include any header names in the list but 4026 MUST include the special entry ":" (a single colon on its own); it 4027 MUST still explicitly list any metadata items that are available. 4028 The order of items in the list is not significant; the server need 4029 not even consistently return the same order. The list MAY be empty 4030 (though in this circumstance there is little point in providing the 4031 HDR command). 4033 An implementation that also supports the OVER command SHOULD at least 4034 permit all the headers and metadata items listed in the output from 4035 the LIST OVERVIEW.FMT command. 4037 If the server treats the first form of the HDR command (message-id 4038 specified) differently to the other two forms (range specified or 4039 current article number used) in respect of which headers or metadata 4040 items are available, then: 4042 o if the MSGID argument is specified, the results MUST be those 4043 available for the first form of the HDR command; 4044 o if the RANGE argument is specified, the results MUST be those 4045 available for the second and third forms of the HDR command; 4046 o if no argument is specified, the results MUST be those available 4047 in all forms of the HDR command (that is, it MUST only list those 4048 items listed in both the previous cases). 4050 If the server does not treat the various forms differently, then it 4051 MUST always produce the same results and ignore any argument. 4053 If the HDR command is not implemented, the meaning of the output from 4054 this command is not specified but it must still meet the above 4055 syntactic requirements. 4057 8.6.3. Examples 4059 Example of an implementation providing access to only a few headers: 4061 [C] LIST HEADERS 4062 [S] 215 headers supported: 4063 [S] Subject 4064 [S] Message-ID 4065 [S] Xref 4066 [S] . 4068 Example of an implementation providing access to the same fields as 4069 the first example in Section 8.4.3: 4071 [C] CAPABILITIES 4072 [S] 101 Capability list: 4073 [S] VERSION 2 4074 [S] READER 4075 [S] OVER 4076 [S] HDR 4077 [S] LIST ACTIVE NEWSGROUPS HEADERS OVERVIEW.FMT 4078 [S] . 4079 [C] LIST HEADERS 4080 [S] 215 headers and metadata items supported: 4081 [S] Date 4082 [S] Distribution 4083 [S] From 4084 [S] Message-ID 4085 [S] References 4086 [S] Subject 4087 [S] Xref 4088 [S] :bytes 4089 [S] :lines 4091 [S] . 4093 Example of an implementation providing access to all headers: 4095 [C] LIST HEADERS 4096 [S] 215 metadata items supported: 4097 [S] : 4098 [S] :lines 4099 [S] :bytes 4100 [S] :x-article-number 4101 [S] . 4103 Example of an implementation distinguishing the first form of the HDR 4104 command from the other two forms: 4106 [C] LIST HEADERS RANGE 4107 [S] 215 metadata items supported: 4108 [S] : 4109 [S] :lines 4110 [S] :bytes 4111 [S] . 4112 [C] LIST HEADERS MSGID 4113 [S] 215 headers and metadata items supported: 4114 [S] Date 4115 [S] Distribution 4116 [S] From 4117 [S] Message-ID 4118 [S] References 4119 [S] Subject 4120 [S] :lines 4121 [S] :bytes 4122 [S] :x-article-number 4123 [S] . 4124 [C] LIST HEADERS 4125 [S] 215 headers and metadata items supported: 4126 [S] Date 4127 [S] Distribution 4128 [S] From 4129 [S] Message-ID 4130 [S] References 4131 [S] Subject 4132 [S] :lines 4133 [S] :bytes 4134 [S] . 4136 Note how :x-article-number does not appear in the last set of output. 4138 9. Augmented BNF Syntax for NNTP 4140 9.1. Introduction 4142 Each of the following sections describes the syntax of a major 4143 element of NNTP. This syntax extends and refines the descriptions 4144 elsewhere in this specification, and should be given precedence when 4145 resolving apparent conflicts. Note that ABNF [RFC2234] strings are 4146 case-insensitive. Non-terminals used in several places are defined 4147 in a separate section at the end. 4149 The non-terminals , , , and between them specify the text that 4151 flows between client and server. A consistent naming scheme is used 4152 in this document for the non-terminals relating to each command, and 4153 SHOULD be used by the specification of registered extensions. 4155 For each command, the sequence is: 4156 o The client sends an instance of ; the syntax for the 4157 EXAMPLE command is . 4158 o If the client is one that immediately streams data, it sends an 4159 instance of ; the syntax for the EXAMPLE 4160 command is . 4161 o The server sends an instance of . 4162 * The initial response line is independent of the command that 4163 generated it; if the 000 response has arguments, the syntax of 4164 the initial line is . 4165 * If the response is multi-line, the initial line is followed by 4166 a . The syntax for the contents of this 4167 block after "dot-stuffing" has been removed is (for the 000 4168 response to the EXAMPLE command) and 4169 is an instance of . 4170 o While the latest response is one that indicates more data is 4171 required (in general, a 3xx response): 4172 * the client sends an instance of ; the 4173 syntax for the EXAMPLE continuation following a 333 response is 4174 . 4175 * the server sends another instance of as above. 4177 (There are no commands in this specification that immediately stream 4178 data, but this non-terminal is defined for the convenience of 4179 extensions.) 4181 9.2. Commands 4183 This syntax defines the non-terminal , which represents 4184 what is sent from the client to the server. 4186 command-line = command EOL 4187 command = X-command 4188 X-command = keyword *(WS token) 4190 command =/ article-command / 4191 body-command / 4192 capabilities-command / 4193 date-command / 4194 group-command / 4195 hdr-command / 4196 head-command / 4197 help-command / 4198 ihave-command / 4199 last-command / 4200 list-command / 4201 listgroup-command / 4202 mode-reader-command / 4203 newgroups-command / 4204 newnews-command / 4205 next-command / 4206 over-command / 4207 post-command / 4208 quit-command / 4209 stat-command 4211 article-command = "ARTICLE" [WS article-ref] 4212 body-command = "BODY" [WS article-ref] 4213 capabilities-command = "CAPABILITIES" [WS keyword] 4214 date-command = "DATE" 4215 group-command = "GROUP" [WS newsgroup-name] 4216 hdr-command = "HDR" WS header-meta-name [WS range-ref] 4217 head-command = "HEAD" [WS article-ref] 4218 help-command = "HELP" 4219 ihave-command = "IHAVE" WS message-id 4220 last-command = "LAST" 4221 list-command = "LIST" [WS list-arguments] 4222 listgroup-command = "LISTGROUP" [WS newsgroup-name [WS range]] 4223 mode-reader-command = "MODE" WS "READER" 4224 newgroups-command = "NEWGROUPS" WS date-time 4225 newnews-command = "NEWNEWS" WS wildmat WS date-time 4226 next-command = "NEXT" 4227 over-command = "OVER" [WS range-ref] 4228 post-command = "POST" 4229 quit-command = "QUIT" 4230 stat-command = "STAT" [WS article-ref] 4232 article-ref = article-number / message-id 4233 date = date2y / date4y 4234 date4y = 4DIGIT 2DIGIT 2DIGIT 4235 date2y = 2DIGIT 2DIGIT 2DIGIT 4236 date-time = date WS time [WS "GMT"] 4237 header-meta-name = header-name / metadata-name 4238 list-arguments = keyword [WS token] 4239 metadata-name = ":" 1*A-NOTCOLON 4240 range = article-number ["-" [article-number]] 4241 range-ref = range / message-id 4242 time = 2DIGIT 2DIGIT 2DIGIT 4244 9.3. Command continuation 4246 This syntax defines the further material sent by the client in the 4247 case of multi-stage commands and those that stream data. 4249 command-datastream = UNDEFINED 4250 ; not used, provided as a hook for extensions 4251 command-continuation = ihave-335-continuation / 4252 post-340-continuation 4254 ihave-335-continuation = encoded-article 4255 post-340-continuation = encoded-article 4257 encoded-article = multi-line-data-block 4258 ; after undoing the "dot-stuffing", this MUST match
4260 9.4. Responses 4262 9.4.1. Generic responses 4264 This syntax defines the non-terminal , which represents the 4265 generic form of responses - that is, what is sent from the server to 4266 the client in response to a or a . 4268 response = simple-response / multi-line-response 4269 simple-response = initial-response-line 4270 multi-line-response = initial-response-line multi-line-data-block 4272 initial-response-line = 4273 initial-response-content [SP trailing-comment] CRLF 4274 initial-response-content = X-initial-response-content 4275 X-initial-response-content = 3DIGIT *(SP response-argument) 4276 response-argument = 1*A-CHAR 4277 trailing-comment = *U-CHAR 4279 9.4.2. Initial response line contents 4281 This syntax defines the specific initial response lines for the 4282 various commands in this specification. Only those response codes 4283 with arguments are listed. 4285 initial-response-content =/ response-111-content / 4286 response-211-content / 4287 response-220-content / 4288 response-221-content / 4289 response-222-content / 4290 response-223-content / 4291 response-401-content 4293 response-111-content = "111" SP date4y time 4294 response-211-content = "211" 3(SP article-number) SP newsgroup-name 4295 response-220-content = "220" SP article-number SP message-id 4296 response-221-content = "221" SP article-number SP message-id 4297 response-222-content = "222" SP article-number SP message-id 4298 response-223-content = "223" SP article-number SP message-id 4299 response-401-content = "401" SP capability-label 4301 9.4.3. Multi-line response contents 4303 This syntax defines the content of the various multi-line responses; 4304 more precisely, it defines the part of the response in the multi-line 4305 data block after any "dot-stuffing" has been undone. The numeric 4306 portion of each non-terminal name indicates the response code that is 4307 followed by this data. 4309 multi-line-response-content = article-220-ml-content / 4310 body-222-ml-content / 4311 capabilities-101-ml-content / 4312 hdr-225-ml-content / 4313 head-221-ml-content / 4314 help-100-ml-content / 4315 list-215-ml-content / 4316 listgroup-211-ml-content / 4317 newgroups-231-ml-content / 4318 newnews-230-ml-content / 4319 over-224-ml-content 4321 article-220-ml-content = article 4322 body-222-ml-content = body 4323 capabilities-101-ml-content = version-line CRLF 4324 *(capability-line CRLF) 4325 hdr-225-ml-content = *(article-number SP hdr-content CRLF) 4326 head-221-ml-content = 1*header 4327 help-100-ml-content = *(*U-CHAR CRLF) 4328 list-215-ml-content = list-content 4329 listgroup-211-ml-content = *(article-number CRLF) 4330 newgroups-231-ml-content = active-groups-list 4331 newnews-230-ml-content = *(message-id CRLF) 4332 over-224-ml-content = *(article-number over-content CRLF) 4334 active-groups-list = *(newsgroup-name SPA article-number 4335 SPA article-number SPA newsgroup-status CRLF) 4336 hdr-content = *S-NONTAB 4337 hdr-n-content = [(header-name ":" / metadata-name) SP hdr-content] 4338 list-content = body 4339 newsgroup-status = %x79 / %x6E / %x6D / private-status 4340 over-content = 1*6(TAB hdr-content) / 4341 7(TAB hdr-content) *(TAB hdr-n-content) 4342 private-status = token ; except the values in newsgroup-status 4344 9.5. Capability lines 4346 This syntax defines the generic form of a capability line in the 4347 capabilities list (see Section 3.3.1). 4349 capability-line = capability-entry 4350 capability-entry = X-capability-entry 4351 X-capability-entry = capability-label *(WS capability-argument) 4352 capability-label = keyword 4353 capability-argument = token 4355 This syntax defines the specific capability entries for the 4356 capabilities in this specification. 4358 capability-entry =/ 4359 hdr-capability / 4360 ihave-capability / 4361 implementation-capability / 4362 list-capability / 4363 mode-reader-capability / 4364 newnews-capability / 4365 over-capability / 4366 post-capability / 4367 reader-capability 4369 hdr-capability = "HDR" 4370 ihave-capability = "IHAVE" 4371 implementation-capability = "IMPLEMENTATION" *(WS token) 4372 list-capability = "LIST" 1*(WS keyword) 4373 mode-reader-capability = "MODE-READER" 4374 newnews-capability = "NEWNEWS" 4375 over-capability = "OVER" [WS "MSGID"] 4376 post-capability = "POST" 4377 reader-capability = "READER" 4379 version-line = "VERSION" 1*(WS version-number) 4380 version-number = nzDIGIT *5DIGIT 4382 9.6. LIST variants 4384 This section defines more specifically the keywords for the LIST 4385 command and the syntax of the corresponding response contents. 4387 ; active 4388 list-arguments =/ "ACTIVE" [WS wildmat] 4389 list-content =/ list-active-content 4390 list-active-content = active-groups-list 4392 ; active.times 4393 list-arguments =/ "ACTIVE.TIMES" [WS wildmat] 4394 list-content =/ list-active-times-content 4395 list-active-times-content = 4396 *(newsgroup-name SPA 1*DIGIT SPA newsgroup-creator CRLF) 4397 newsgroup-creator = U-TEXT 4399 ; distrib.pats 4400 list-arguments =/ "DISTRIB.PATS" 4401 list-content =/ list-distrib-pats-content 4402 list-distrib-pats-content = 4403 *(1*DIGIT ":" wildmat ":" distribution CRLF) 4404 distribution = token 4406 ; headers 4407 list-arguments =/ "HEADERS" [WS ("MSGID" / "RANGE")] 4408 list-content =/ list-headers-content 4409 list-headers-content = *(header-meta-name CRLF) / 4410 *((metadata-name / ":") CRLF) 4412 ; newsgroups 4413 list-arguments =/ "NEWSGROUPS" [WS wildmat] 4414 list-content =/ list-newsgroups-content 4415 list-newsgroups-content = 4416 *(newsgroup-name WS newsgroup-description CRLF) 4417 newsgroup-description = S-TEXT 4419 ; overview.fmt 4420 list-arguments =/ "OVERVIEW.FMT" 4421 list-content =/ list-overview-fmt-content 4422 list-overview-fmt-content = "Subject:" CRLF 4423 "From:" CRLF 4424 "Date:" CRLF 4425 "Message-ID:" CRLF 4426 "References:" CRLF 4427 ( ":bytes" CRLF ":lines" / "Bytes:" CRLF "Lines:") CRLF 4428 *((header-name ":full" / metadata-name) CRLF) 4430 9.7. Articles 4432 This syntax defines the non-terminal
, which represents the 4433 format of an article as described in Section 3.6. 4435 article = 1*header CRLF body 4436 header = header-name ":" [CRLF] SP header-content CRLF 4437 header-content = *(S-CHAR / [CRLF] WS) 4438 body = *(*B-CHAR CRLF) 4440 9.8. General non-terminals 4442 These non-terminals are used at various places in the syntax and are 4443 collected here for convenience. A few of these non-terminals are not 4444 used in this specification but are provided for the consistency and 4445 convenience of extension authors. 4447 multi-line-data-block = content-lines termination 4448 content-lines = *([content-text] CRLF) 4449 content-text = (".." / B-NONDOT) *B-CHAR 4450 termination = "." CRLF 4452 article-number = 1*16DIGIT 4453 header-name = 1*A-NOTCOLON 4454 keyword = ALPHA 2*11(ALPHA / DIGIT / "." / "-") 4455 message-id = "<" 1*248A-NOTGT ">" 4456 newsgroup-name = 1*wildmat-exact 4457 token = 1*P-CHAR 4459 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 4460 wildmat-pattern = 1*wildmat-item 4461 wildmat-item = wildmat-exact / wildmat-wild 4462 wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 4463 UTF8-non-ascii ; exclude ! * , ? [ \ ] 4464 wildmat-wild = "*" / "?" 4466 base64 = *(4base64-char) [base64-terminal] 4467 base64-char = UPPER / LOWER / DIGIT / "+" / "/" 4468 base64-terminal = 2base64-char "==" / 3base64-char "=" 4470 ; Assorted special character sets 4471 ; A- means based on US-ASCII, excluding controls and SP 4472 ; P- means based on UTF-8, excluding controls and SP 4473 ; U- means based on UTF-8, excluding NUL CR and LF 4474 ; B- means based on bytes, excluding NUL CR and LF 4475 A-CHAR = %x21-7E 4476 A-NOTCOLON = %x21-39 / %x3B-7E ; exclude ":" 4477 A-NOTGT = %x21-3D / %x3F-7E ; exclude ">" 4478 P-CHAR = A-CHAR / UTF8-non-ascii 4479 U-CHAR = CTRL / TAB / SP / A-CHAR / UTF8-non-ascii 4480 U-NONTAB = CTRL / SP / A-CHAR / UTF8-non-ascii 4481 U-TEXT = P-CHAR *U-CHAR 4482 B-CHAR = CTRL / TAB / SP / %x21-FF 4483 B-NONDOT = CTRL / TAB / SP / %x21-2D / %x2F-FF ; exclude "." 4485 ALPHA = UPPER / LOWER ; use only when case-insensitive 4486 CR = %x0D 4487 CRLF = CR LF 4488 CTRL = %x01-08 / %x0B-0C / %x0E-1F 4489 DIGIT = %x30-39 4490 nzDIGIT = %x31-39 4491 EOL = *(SP / TAB) CRLF 4492 LF = %x0A 4493 LOWER = %x61-7A 4494 SP = %x20 4495 SPA = 1*SP 4496 TAB = %x09 4497 UPPER = %x41-5A 4498 UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4 4499 UTF8-2 = %xC2-DF UTF8-tail 4500 UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail / 4501 %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail 4502 UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail / 4503 %xF4 %x80-8F 2UTF8-tail 4504 UTF8-tail = %x80-BF 4505 WS = 1*(SP / TAB) 4507 The following non-terminals require special consideration. They 4508 represent situations where material SHOULD be restricted to UTF-8, 4509 but implementations MUST be able to cope with other character 4510 encodings. Therefore there are two sets of definitions for them. 4512 Implementations MUST accept any content that meets this syntax: 4514 S-CHAR = %x21-FF 4515 S-NONTAB = CTRL / SP / S-CHAR 4516 S-TEXT = (CTRL / S-CHAR) *B-CHAR 4518 and MAY pass such content on unaltered. 4520 When generating new content or re-encoding existing content, 4521 implementations SHOULD conform to this syntax: 4523 S-CHAR = P-CHAR 4524 S-NONTAB = U-NONTAB 4525 S-TEXT = U-TEXT 4527 9.9. Extensions and Validation 4529 The specification of a registered extension MUST include formal 4530 syntax that defines additional forms for the following non-terminals: 4532 command 4533 for each new command other than a variant of the LIST command - 4534 the syntax of each command MUST be compatible with the definition 4535 of ; 4537 command-datastream 4538 for each new command that immediately streams data; 4540 command-continuation 4541 for each new command that sends further material after the initial 4542 command line - the syntax of each continuation MUST be exactly 4543 what is sent to the server, including any escape mechanisms such 4544 as "dot-stuffing"; 4546 initial-response-content 4547 for each new response code that has arguments - the syntax of each 4548 response MUST be compatible with the definition of ; 4551 multi-line-response-content 4552 for each new response code that has a multi-line response - the 4553 syntax MUST show the response after the lines containing the 4554 response code and the terminating octet have been removed and any 4555 "dot-stuffing" undone; 4557 capability-entry 4558 for each new capability label - the syntax of each entry MUST be 4559 compatible with the definition of ; 4561 list-arguments 4562 for each new variant of the LIST command - the syntax of each 4563 entry MUST be compatible with the definition of ; 4565 list-content 4566 for each new variant of the LIST command - the syntax MUST show 4567 the response after the lines containing the 215 response code and 4568 the terminating octet have been removed and any "dot-stuffing" 4569 undone. 4571 The =/ notation of ABNF [RFC2234] and the naming conventions 4572 described in Section 9.1 SHOULD be used for this. 4574 When validating the syntax in this specification, or syntax based on 4575 it, it should be noted that: 4576 o the non-terminals , , , , and 4578 describe basic concepts of the protocol and are not referred to by 4579 any other rule; 4580 o the non-terminal is provided for the convenience of 4581 extension authors and is not referred to by any rule in this 4582 specification; 4583 o for the reasons given above, the non-terminals , 4584 , and each have two definitions; 4585 o the non-terminal is deliberately not defined. 4587 10. Internationalisation Considerations 4589 10.1. Introduction and historical situation 4591 RFC 977 [RFC977] was written at a time when internationalisation was 4592 not seen as a significant issue. As such, it was written on the 4593 assumption that all communication would be in ASCII and use only a 4594 7-bit transport layer, although in practice just about all known 4595 implementations are 8-bit clean. 4597 Since then, Usenet and NNTP have spread throughout the world. In the 4598 absence of standards for handling the issues of language and 4599 character sets, countries, newsgroup hierarchies, and individuals 4600 have found a variety of solutions that work for them but are not 4601 necessarily appropriate elsewhere. For example, some have adopted a 4602 default 8-bit character set appropriate to their needs (such as ISO/ 4603 IEC 8859-1 in Western Europe or KOI-8 in Russia), others have used 4604 ASCII (either US-ASCII or national variants) in headers but local 16- 4605 bit character sets in article bodies, and still others have gone for 4606 a combination of MIME [RFC2045] and UTF-8. With the increased use of 4607 MIME in email, it is becoming more common to find NNTP articles 4608 containing MIME headers identifying the character set of the body, 4609 but this is far from universal. 4611 The resulting confusion does not help interoperability. 4613 One point that has been generally accepted is that articles can 4614 contain octets with the top bit set, and NNTP is only expected to 4615 operate on 8-bit clean transport paths. 4617 10.2. This specification 4619 Part of the role of this present specification is to eliminate this 4620 confusion and promote interoperability as far as possible. At the 4621 same time, it is necessary to accept the existence of the present 4622 situation and not gratuitously break existing implementations and 4623 arrangements, even if they are less than optimal. Therefore the 4624 current practice described above has been taken into consideration in 4625 producing this specification. 4627 This specification extends NNTP from US-ASCII [ANSI1986] to UTF-8 4628 [RFC3629]. Except in the two areas discussed below, UTF-8 (which is 4629 a superset of US-ASCII) is mandatory and implementations MUST NOT use 4630 any other encoding. 4632 Firstly, the use of MIME for article headers and bodies is strongly 4633 recommended. However, given widely divergent existing practices, an 4634 attempt to require a particular encoding and tagging standard would 4635 be premature at this time. Accordingly, this specification allows 4636 the use of arbitrary 8-bit data in articles subject to the following 4637 requirements and recommendations. 4639 o The names of headers (e.g. "From" or "Subject") MUST be in US- 4640 ASCII. 4642 o Header values SHOULD use US-ASCII or an encoding based on it such 4643 as RFC 2047 [RFC2047] until such time as another approach has been 4644 standardised. At present, 8-bit encodings (including UTF-8) 4645 SHOULD NOT be used because they are likely to cause 4646 interoperability problems. 4648 o The character set of article bodies SHOULD be indicated in the 4649 article headers, and this SHOULD be done in accordance with MIME. 4651 o Where an article is obtained from an external source an 4652 implementation MAY pass it on, and derive data from it (such as 4653 the response to the HDR command), even though the article or the 4654 data does not meet the above requirements. Implementations MUST 4655 transfer such articles and data correctly and unchanged; they MUST 4656 NOT attempt to convert or re-encode the article or derived data. 4657 (Nevertheless, a client or server MAY elect not to post or forward 4658 the article if, after further examination of the article, it deems 4659 it inappropriate to do so.) 4661 This requirement affects the ARTICLE (Section 6.2.1), BODY 4662 (Section 6.2.3), HDR (Section 8.5), HEAD (Section 6.2.2), IHAVE 4663 (Section 6.3.2), OVER (Section 8.3), and POST (Section 6.3.1) 4664 commands. 4666 Secondly, the following requirements are placed on the newsgroups 4667 list returned by the LIST NEWSGROUPS (Section 7.6.6) command: 4669 o Although this specification allows UTF-8 for newsgroup names, they 4670 SHOULD be restricted to US-ASCII until a successor to RFC 1036 4671 [RFC1036] standardises another approach. 8-bit encodings SHOULD 4672 NOT be used because they are likely to cause interoperability 4673 problems. 4675 o The newsgroup description SHOULD be in US-ASCII or UTF-8 unless 4676 and until a successor to RFC 1036 standardised other encoding 4677 arrangements. 8-bit encodings other than UTF-8 SHOULD NOT be used 4678 because they are likely to cause interoperability problems. 4680 o Implementations which obtain this data from an external source 4681 MUST correctly handle it even if it does not meet the above 4682 requirements. Implementations (in particular, clients) MUST 4683 handle such data correctly. 4685 10.3. Outstanding issues 4687 While the primary use of NNTP is for transmitting articles that 4688 conform to RFC 1036 (Netnews articles), it is also used for other 4689 formats (see Appendix A). It is therefore most appropriate that 4690 internationalisation issues related to article formats be addressed 4691 in the relevant specifications. For Netnews articles, this is any 4692 successor to RFC 1036. For email messages, it is RFC 2822 [RFC2822]. 4694 Of course, any article transmitted via NNTP needs to conform to this 4695 specification as well. 4697 Restricting newsgroup names to UTF-8 is not a complete solution. In 4698 particular, when new newsgroup names are created or a user is asked 4699 to enter a newsgroup name, some scheme of canonicalisation will need 4700 to take place. This specification does not attempt to define that 4701 canonicalization; further work is needed in this area in conjunction 4702 with the article format specifications. Until such specifications 4703 are published, implementations SHOULD match newsgroup names octet-by- 4704 octet. It is anticipated that any approved scheme will be applied 4705 "at the edges" and therefore octet-by-octet comparison will continue 4706 to apply to most, if not all, uses of newsgroup names in NNTP. 4708 In the meantime, any implementation experimenting with UTF-8 4709 newsgroup names is strongly cautioned that a future specification may 4710 require that those names be canonicalized when used with NNTP in a 4711 way that is not compatible with their experiments. 4713 Since the primary use of NNTP is with Netnews, and since newsgroup 4714 descriptions are normally distributed through specially formatted 4715 articles, it is recommended that the internationalisation issues 4716 related to them be addressed in any successor to RFC 1036. 4718 11. IANA Considerations 4720 This specification requires IANA to keep a registry of capability 4721 labels. The initial contents of this registry are specified in 4722 Section 3.3.4. As described in Section 3.3.3, labels beginning with 4723 X are reserved for private use while all other names are expected to 4724 be associated with a specification in an RFC on the standards-track 4725 or defining an IESG-approved experimental protocol. 4727 Different entries in the registry MUST use different capability 4728 labels. 4730 Different entries in the registry MUST NOT use the same command name. 4731 For this purpose, variants distinguished by a second or subsequent 4732 keyword (e.g. "LIST HEADERS" and "LIST OVERVIEW.FMT") count as 4733 different commands. If there is a need for two extensions to use the 4734 same command, a single harmonised specification MUST be registered. 4736 12. Security Considerations 4738 This section is meant to inform application developers, information 4739 providers, and users of the security limitations in NNTP as described 4740 by this document. The discussion does not include definitive 4741 solutions to the problems revealed, though it does make some 4742 suggestions for reducing security risks. 4744 12.1. Personal and Proprietary Information 4746 NNTP, because it was created to distribute network news articles, 4747 will forward whatever information is stored in those articles. 4748 Specification of that information is outside this scope of this 4749 document, but it is likely that some personal and/or proprietary 4750 information is available in some of those articles. It is very 4751 important that designers and implementers provide informative 4752 warnings to users so personal and/or proprietary information in 4753 material that is added automatically to articles (e.g. in headers) is 4754 not disclosed inadvertently. Additionally, effective and easily 4755 understood mechanisms to manage the distribution of news articles 4756 SHOULD be provided to NNTP Server administrators, so that they are 4757 able to report with confidence the likely spread of any particular 4758 set of news articles. 4760 12.2. Abuse of Server Log Information 4762 A server is in the position to save session data about a user's 4763 requests that might identify their reading patterns or subjects of 4764 interest. This information is clearly confidential in nature and its 4765 handling can be constrained by law in certain countries. People 4766 using the NNTP protocol to provide data are responsible for ensuring 4767 that such material is not distributed without the permission of any 4768 individuals that are identifiable by the published results. 4770 12.3. Weak Authentication and Access Control 4772 There is no user-based or token-based authentication in the basic 4773 NNTP specification. Access is normally controlled by server 4774 configuration files. Those files specify access by using domain 4775 names or IP addresses. However, this specification does permit the 4776 creation of extensions to the NNTP protocol itself for such purposes; 4777 one such extension is [NNTP-AUTH]. While including such mechanisms 4778 is optional, doing so is strongly encouraged. 4780 Other mechanisms are also available. For example, a proxy server 4781 could be put in place that requires authentication before connecting 4782 via the proxy to the NNTP server. 4784 12.4. DNS Spoofing 4786 Many existing NNTP implementations authorize incoming connections by 4787 checking the IP address of that connection against the IP addresses 4788 obtained via DNS lookups of lists of domain names given in local 4789 configuration files. Servers that use this type of authentication, 4790 and clients that find a server by doing a DNS lookup of the server 4791 name, rely very heavily on the Domain Name Service, and are thus 4792 generally prone to security attacks based on the deliberate 4793 misassociation of IP addresses and DNS names. Clients and servers 4794 need to be cautious in assuming the continuing validity of an IP 4795 number/DNS name association. 4797 In particular, NNTP clients and servers SHOULD rely on their name 4798 resolver for confirmation of an IP number/DNS name association, 4799 rather than caching the result of previous host name lookups. Many 4800 platforms already can cache host name lookups locally when 4801 appropriate, and they SHOULD be configured to do so. It is proper 4802 for these lookups to be cached, however, only when the TTL (Time To 4803 Live) information reported by the name server makes it likely that 4804 the cached information will remain useful. 4806 If NNTP clients or servers cache the results of host name lookups in 4807 order to achieve a performance improvement, they MUST observe the TTL 4808 information reported by DNS. If NNTP clients or servers do not 4809 observe this rule, they could be spoofed when a previously accessed 4810 server's IP address changes. As network renumbering is expected to 4811 become increasingly common, the possibility of this form of attack 4812 will grow. Observing this requirement thus reduces this potential 4813 security vulnerability. 4815 This requirement also improves the load-balancing behaviour of 4816 clients for replicated servers using the same DNS name and reduces 4817 the likelihood of a user's experiencing failure in accessing sites 4818 that use that strategy. 4820 12.5. UTF-8 issues 4822 UTF-8 [RFC3629] permits only certain sequences of octets and 4823 designates others as either malformed or "illegal". The Unicode 4824 standard identifies a number of security issues related to illegal 4825 sequences and forbids their generation by conforming implementations. 4827 Implementations of this specification MUST NOT generate malformed or 4828 illegal sequences and SHOULD detect them and take some appropriate 4829 action. This could include: 4831 o generating a 501 response code. 4832 o replacing such sequences by the sequence %xEF.BF.BD, which encodes 4833 the "replacement character" U+FFFD; 4834 o closing the connection; 4835 o replacing such sequences by a "guessed" valid sequence (based on 4836 properties of the UTF-8 encoding); 4837 In the last case, the implementation MUST ensure that any replacement 4838 cannot be used to bypass validity or security checks. For example, 4839 the illegal sequence %xC0.A0 is an over-long encoding for space 4840 (%x20). If it is replaced by the latter in a command line, this 4841 needs to happen before the command line is parsed into individual 4842 arguments. If the replacement came after parsing, it would be 4843 possible to generate an argument with an embedded space, which is 4844 forbidden. Use of the "replacement character" does not have this 4845 problem, since it is permitted wherever non-US-ASCII characters are. 4846 Implementations SHOULD use one of the first two solutions where the 4847 general structure of the NNTP stream remains intact, and close the 4848 connection if it is no longer possible to parse it sensibly. 4850 12.6. Caching of capability lists 4852 The CAPABILITIES command provides a capability list, which is 4853 information about the current capabilities of the server. Whenever 4854 there is a relevant change to the server state, the results of this 4855 command are required to change accordingly. 4857 In most situations the capabilities list in a given server state will 4858 not change from session to session; for example, a given extension 4859 will be installed permanently on a server. Some clients may 4860 therefore wish to remember which extensions a server supports to 4861 avoid the delay of an additional command and response, particularly 4862 if they open multiple connections in the same session. 4864 However, information about extensions related to security and privacy 4865 MUST NOT be cached, since this could allow a variety of attacks. 4867 For example, consider a server which permits the use of cleartext 4868 passwords on links that are encrypted but not otherwise: 4870 [Initial connection set-up completed.] 4871 [S] 200 NNTP Service Ready, posting permitted 4872 [C] CAPABILITIES 4873 [S] 101 Capability list: 4874 [S] VERSION 2 4875 [S] READER 4876 [S] NEWNEWS 4877 [S] POST 4878 [S] XENCRYPT 4880 [S] LIST ACTIVE NEWSGROUPS 4881 [S] . 4882 [C] XENCRYPT 4883 [Client and server negotiate encryption on the link] 4884 [S] 283 Encrypted link established 4885 [C] CAPABILITIES 4886 [S] 101 Capability list: 4887 [S] VERSION 2 4888 [S] READER 4889 [S] NEWNEWS 4890 [S] POST 4891 [S] XSECRET 4892 [S] LIST ACTIVE NEWSGROUPS 4893 [S] . 4894 [C] XSECRET fred flintstone 4895 [S] 290 Password for fred accepted 4897 If the client caches the last capabilities list, then on the next 4898 session it will attempt to use XSECRET on an unencrypted link: 4900 [Initial connection set-up completed.] 4901 [S] 200 NNTP Service Ready, posting permitted 4902 [C] XSECRET fred flintstone 4903 [S] 483 Only permitted on secure links 4905 exposing the password to any eavesdropper. While the primary cause 4906 of this is passing a secret without first checking the security of 4907 the link, caching of capability lists can increase the risk. 4909 Any security extension should include requirements to check the 4910 security state of the link in a manner appropriate to that extension. 4912 Caching should normally only be considered for anonymous clients that 4913 do not use any security or privacy extensions and for which the time 4914 required for an additional command and response is a noticeable 4915 issue. 4917 13. Acknowledgements 4919 This document is the result of much effort by the present and past 4920 members of the NNTP Working Group, chaired by Russ Allbery and Ned 4921 Freed. It could not have been produced without them. 4923 The author acknowledges the original authors of NNTP as documented in 4924 RFC 977 [RFC977]: Brian Kantor and Phil Lapsey. 4926 The author gratefully acknowledges: 4928 o The work of the NNTP committee chaired by Eliot Lear. The 4929 organization of this document was influenced by the last available 4930 draft from this working group. A special thanks to Eliot for 4931 generously providing the original machine-readable sources for 4932 that document. 4934 o The work of the DRUMS working group, specifically RFC 1869 4935 [RFC1869], which drove the original thinking which led to the 4936 CAPABILITIES command and the extensions mechanism detailed in this 4937 document. 4939 o The authors of RFC 2616 [RFC2616] for providing specific and 4940 relevant examples of security issues that should be considered for 4941 HTTP. Since many of the same considerations exist for NNTP, those 4942 examples that are relevant have been included here with some minor 4943 rewrites. 4945 o The comments and additional information provided by the following 4946 individuals in preparing one or more of the progenitors of this 4947 document: 4948 Russ Allbery 4949 Wayne Davison 4950 Chris Lewis 4951 Tom Limoncelli 4952 Eric Schnoebelen 4953 Rich Salz 4955 This work was motivated by the work of various news reader authors 4956 and news server authors, which includes those listed below: 4958 Rick Adams 4959 Original author of the NNTP extensions to the RN news reader and 4960 last maintainer of Bnews 4962 Stan Barber 4963 Original author of the NNTP extensions to the news readers that 4964 are part of Bnews 4966 Geoff Collyer 4967 Original author of the OVERVIEW database proposal and one of the 4968 original authors of CNEWS 4970 Dan Curry 4971 Original author of the xvnews news reader 4973 Wayne Davison 4974 Author of the first threading extensions to the RN news reader 4975 (commonly called TRN) 4977 Geoff Huston 4978 Original author of ANU NEWS 4980 Phil Lapsey 4981 Original author of the UNIX reference implementation for NNTP 4983 Iain Lea 4984 Original maintainer of the TIN news reader 4986 Chris Lewis 4987 First known implementer of the AUTHINFO GENERIC extension 4989 Rich Salz 4990 Original author of INN 4992 Henry Spencer 4993 One of the original authors of CNEWS 4995 Kim Storm 4996 Original author of the NN news reader 4998 Other people who contributed to this document include: 5000 Matthias Andree 5001 Greg Andruk 5002 Daniel Barclay 5003 Maurizio Codogno 5004 Mark Crispin 5005 Andrew Gierth 5006 Juergen Helbing 5007 Scott Hollenbeck 5008 Urs Janssen 5009 Charles Lindsey 5010 Ade Lovett 5011 David Magda 5012 Ken Murchison 5013 Francois Petillon 5014 Peter Robinson 5015 Rob Siemborski 5016 Howard Swinehart 5017 Ruud van Tol 5018 Jeffrey Vinocur 5019 Eric Warmelink 5021 The author thanks them all and apologises to anyone omitted. 5023 Finally, the present author gratefully acknowledges the vast amount 5024 of work put into previous drafts by the previous author: 5026 Stan Barber 5028 14. References 5030 14.1 Normative References 5032 [ANSI1986] 5033 American National Standards Institute, "Coded Character 5034 Set - 7-bit American Standard Code for Information 5035 Interchange", ANSI X3.4, 1986. 5037 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 5038 Extensions (MIME) Part One: Format of Internet Message 5039 Bodies", RFC 2045, November 1996. 5041 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 5042 Part Three: Message Header Extensions for Non-ASCII Text", 5043 RFC 2047, November 1996. 5045 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 5046 Requirement Levels", BCP 14, RFC 2119, March 1997. 5048 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 5049 Specifications: ABNF", RFC 2234, November 1997. 5051 [RFC3548] Josefsson, S., "The Base16, Base32, and Base64 Data 5052 Encodings", RFC 3548, July 2003. 5054 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 5055 10646", STD 63, RFC 3629, November 2003. 5057 [RFC977] Kantor, B. and P. Lapsley, "Network News Transfer 5058 Protocol", RFC 977, February 1986. 5060 [TF.686-1] 5061 International Telecommunications Union - Radio, "Glossary, 5062 ITU-R Recommendation TF.686-1", ITU-R Recommendation 5063 TF.686-1, October 1997. 5065 14.2 Informative References 5067 [NNTP-AUTH] 5068 Vinocur, J., Murchison, K., and C. Newman, "NNTP 5069 Authentication", draft-ietf-nntpext-authinfo-06 (work in 5070 progress), December 2004. 5072 [NNTP-STREAM] 5073 Vinocur, J. and K. Murchison, "NNTP Authentication", 5074 draft-ietf-nntpext-streaming-03 (work in progress), 5075 December 2004. 5077 [NNTP-TLS] 5078 Vinocur, J., Murchison, K., and C. Newman, "Using TLS with 5079 NNTP", draft-ietf-nntpext-tls-nntp-04 (work in progress), 5080 December 2004. 5082 [RFC1036] Horton, M. and R. Adams, "Standard for interchange of 5083 USENET messages", RFC 1036, December 1987. 5085 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 5086 Specification, Implementation", RFC 1305, March 1992. 5088 [RFC1869] Klensin, J., Freed, N., Rose, M., Stefferud, E., and D. 5089 Crocker, "SMTP Service Extensions", STD 10, RFC 1869, 5090 November 1995. 5092 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 5093 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 5094 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 5096 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 5097 June 1999. 5099 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, 5100 April 2001. 5102 [RFC2980] Barber, S., "Common NNTP Extensions", RFC 2980, 5103 October 2000. 5105 [ROBE1995] 5106 Robertson, R., "FAQ: Overview database / NOV General 5107 Information", January 1995. 5109 There is no definitive copy of this document known to the 5110 author. It was previously posted as the Usenet article 5111 5113 [SALZ1992] 5114 Salz, R., "Manual Page for wildmat(3) from the INN 1.4 5115 distribution, Revision 1.10", April 1992. 5117 There is no definitive copy of this document known to the 5118 author. 5120 Appendix A. Interaction with other specifications 5122 NNTP is most often used for transferring articles that conform to 5123 RFC 1036 [RFC1036] (such articles are called "Netnews articles" 5124 here). It is also sometimes used for transferring email messages 5125 that conform to RFC 2822 [RFC2822] (such articles are called "email 5126 articles" here). In this situation, articles must conform both to 5127 this specification and to that other one; this appendix describes 5128 some relevant issues. 5130 A.1. Header folding 5132 NNTP allows a header line to be folded (by inserting a CRLF pair) 5133 before any space or TAB character. 5135 Both email and Netnews articles are required to have at least one 5136 octet other than space or TAB on each header line. Thus folding can 5137 only happen at one point in each sequence of consecutive spaces or 5138 TABs. Netnews articles are further required to have the header name, 5139 colon, and following space all on the first line; folding may only 5140 happen beyond that space. Finally, some non-conforming software will 5141 remove trailing spaces and TABs from a line. Therefore it might be 5142 inadvisable to fold a header after a space or TAB. 5144 For maximum safety, header lines SHOULD conform to the following 5145 syntax rather than that in Section 9.7. 5147 header = header-name ":" SP [header-content] CRLF 5148 header-content = [WS] token *( [CRLF] WS token ) 5150 A.2. Message-IDs 5152 Every article handled by an NNTP server MUST have a unique 5153 message-id. For the purposes of this specification, a message-id is 5154 an arbitrary opaque string that merely needs to meet certain 5155 syntactic requirements and is just a way to refer to the article. 5157 Because there is a significant risk of old articles being reinjected 5158 into the global Usenet system, RFC 1036 [RFC1036] requires that 5159 message-ids are globally unique for all time. 5161 This specification states that message-ids are the same if and only 5162 if they consist of the same sequence of octets. Other specifications 5163 may define two different sequences as being equal because they are 5164 putting an interpretation on particular characters. RFC 2822 5165 [RFC2822] has a concept of "quoted" and "escaped" characters. It 5166 therefore considers the three message-ids: 5168 5169 <"ab.cd"@example.com> 5170 <"ab.\cd"@example.com> 5172 as being identical. Therefore an NNTP implementation handing email 5173 articles must ensure that only one of these three appears in the 5174 protocol and the other two are converted to it as and when necessary, 5175 such as when a client checks the results of a NEWNEWS command against 5176 an internal database of message-ids. Note that RFC 1036 [RFC1036] 5177 never treats two different strings as being identical. Its draft 5178 successor restricts the syntax of message-ids so that, whenever 5179 RFC 2822 would treat two strings as equivalent, only one of them is 5180 valid (in the above example only the first string is valid). 5182 This specification does not describe how the message-id of an article 5183 is determined; it may be deduced from the contents of the article or 5184 derived from some external source. If the server is also conforming 5185 to another specification that contains a definition of message-id 5186 compatible with this one, the server SHOULD use those message-ids. A 5187 common approach, and one that SHOULD be used for email and Netnews 5188 articles, is to extract the message-id from the contents of a header 5189 with name "Message-ID". This may not be as simple as copying the 5190 entire header contents; it may be necessary to strip off comments and 5191 undo quoting, or to reduce "equivalent" message-ids to a canonical 5192 form. 5194 If an article is obtained through the IHAVE command, there will be a 5195 message-id provided with the command. The server MAY either use it 5196 or determine one from the article contents. However, whichever it 5197 does it SHOULD ensure that, if the IHAVE command is repeated with the 5198 same argument and article, it will be recognized as a duplicate. 5200 If an article does not contain a message-id that the server can 5201 identify, it MUST synthesize one. This could, for example, be a 5202 simple sequence number or based on the date and time that the article 5203 arrived. When handling email or Netnews articles, a Message-ID 5204 header SHOULD be added to ensure global consistency and uniqueness. 5206 Note that, because the message-id might not have been derived from 5207 the Message-ID header in the article, the following example is 5208 legitimate (though unusual): 5210 [C] HEAD <45223423@example.com> 5211 [S] 221 0 <45223423@example.com> 5212 [S] Path: pathost!demo!whitehouse!not-for-mail 5213 [S] Message-ID: <1234@example.net> 5215 [S] From: "Demo User" 5216 [S] Newsgroups: misc.test 5217 [S] Subject: I am just a test article 5218 [S] Date: 6 Oct 1998 04:38:40 -0500 5219 [S] Organization: An Example Net, Uncertain, Texas 5220 [S] . 5222 A.3. Article posting 5224 As far as NNTP is concerned, the POST and IHAVE commands provide the 5225 same basic facilities in a slightly different way. However they have 5226 rather different intentions. 5228 The IHAVE command is intended for transmitting conforming articles 5229 between a system of NNTP servers, with all articles perhaps also 5230 conforming to another specification (e.g. all articles are Netnews 5231 articles). It is expected that the client will have already done any 5232 necessary validation (or has in turn obtained the article from a 5233 third party which has done so); therefore the contents SHOULD be left 5234 unchanged. 5236 In contrast, the POST command is intended for use when an end-user is 5237 injecting a newly-created article into a such a system. The article 5238 being transferred might not be a conforming email or Netnews article, 5239 and the server is expected to validate it and, if necessary, convert 5240 it to the right form for onward distribution. This is often done by 5241 a separate piece of software on the server installation; if so, the 5242 NNTP server SHOULD pass the incoming article to that software 5243 unaltered, making no attempt to filter characters, fold or limit 5244 lines, or otherwise process the incoming text. 5246 The POST command can fail in various ways and clients should be 5247 prepared to re-send an article. When doing so, however, it is often 5248 important to ensure - as far as possible - that the same message-id 5249 is allocated to both attempts so that the server, or other servers, 5250 can recognize the two articles as being duplicates. In the case of 5251 email or Netnews articles, therefore, the posted article SHOULD 5252 contain a header with name "Message-ID" and the contents of this 5253 header SHOULD be identical on each attempt. The server SHOULD ensure 5254 that two POSTed articles with the same contents for this header are 5255 recognized as identical and the same message-id allocated, whether or 5256 not those contents are suitable for use as the message-id. 5258 Appendix B. Summary of Commands 5260 This section contains a list of every command defined in this 5261 document, ordered by command name and by indicating capability. 5263 Ordered by command name: 5265 +-------------------+-----------------------+---------------+ 5266 | Command | Indicating capability | Definition | 5267 +-------------------+-----------------------+---------------+ 5268 | ARTICLE | READER | Section 6.2.1 | 5269 | BODY | READER | Section 6.2.3 | 5270 | CAPABILITIES | mandatory | Section 5.2 | 5271 | DATE | READER | Section 7.1 | 5272 | GROUP | READER | Section 6.1.1 | 5273 | HDR | HDR | Section 8.5 | 5274 | HEAD | mandatory | Section 6.2.2 | 5275 | HELP | mandatory | Section 7.2 | 5276 | IHAVE | IHAVE | Section 6.3.2 | 5277 | LAST | READER | Section 6.1.3 | 5278 | LIST | LIST | Section 7.6.1 | 5279 | LIST ACTIVE.TIMES | LIST | Section 7.6.4 | 5280 | LIST ACTIVE | LIST | Section 7.6.3 | 5281 | LIST DISTRIB.PATS | LIST | Section 7.6.5 | 5282 | LIST HEADERS | HDR | Section 8.6 | 5283 | LIST NEWSGROUPS | LIST | Section 7.6.6 | 5284 | LIST OVERVIEW.FMT | OVER | Section 8.4 | 5285 | LISTGROUP | READER | Section 6.1.2 | 5286 | MODE READER | MODE-READER | Section 5.3 | 5287 | NEWGROUPS | READER | Section 7.3 | 5288 | NEWNEWS | NEWNEWS | Section 7.4 | 5289 | NEXT | READER | Section 6.1.4 | 5290 | OVER | OVER | Section 8.3 | 5291 | POST | POST | Section 6.3.1 | 5292 | QUIT | mandatory | Section 5.4 | 5293 | STAT | mandatory | Section 6.2.4 | 5294 +-------------------+-----------------------+---------------+ 5296 Ordered by indicating capability: 5298 +-------------------+-----------------------+---------------+ 5299 | Command | Indicating capability | Definition | 5300 +-------------------+-----------------------+---------------+ 5301 | CAPABILITIES | mandatory | Section 5.2 | 5302 | HEAD | mandatory | Section 6.2.2 | 5303 | HELP | mandatory | Section 7.2 | 5304 | QUIT | mandatory | Section 5.4 | 5305 | STAT | mandatory | Section 6.2.4 | 5306 | HDR | HDR | Section 8.5 | 5307 | LIST HEADERS | HDR | Section 8.6 | 5308 | IHAVE | IHAVE | Section 6.3.2 | 5309 | LIST | LIST | Section 7.6.1 | 5310 | LIST ACTIVE | LIST | Section 7.6.3 | 5311 | LIST ACTIVE.TIMES | LIST | Section 7.6.4 | 5312 | LIST DISTRIB.PATS | LIST | Section 7.6.5 | 5313 | LIST NEWSGROUPS | LIST | Section 7.6.6 | 5314 | MODE READER | MODE-READER | Section 5.3 | 5315 | NEWNEWS | NEWNEWS | Section 7.4 | 5316 | OVER | OVER | Section 8.3 | 5317 | LIST OVERVIEW.FMT | OVER | Section 8.4 | 5318 | POST | POST | Section 6.3.1 | 5319 | ARTICLE | READER | Section 6.2.1 | 5320 | BODY | READER | Section 6.2.3 | 5321 | DATE | READER | Section 7.1 | 5322 | GROUP | READER | Section 6.1.1 | 5323 | LAST | READER | Section 6.1.3 | 5324 | LISTGROUP | READER | Section 6.1.2 | 5325 | NEWGROUPS | READER | Section 7.3 | 5326 | NEXT | READER | Section 6.1.4 | 5327 +-------------------+-----------------------+---------------+ 5329 Appendix C. Summary of Response Codes 5331 This section contains a list of every response code defined in this 5332 document, whether it is multi-line, which commands can generate it, 5333 what arguments it has, and what its meaning is. 5335 Response code 100 (multi-line) 5336 Generated by: HELP 5337 Meaning: help text follows. 5339 Response code 101 (multi-line) 5340 Generated by: CAPABILITIES 5341 Meaning: capabilities list follows. 5343 Response code 111 5344 Generated by: DATE 5345 1 argument: yyyymmddhhmmss 5346 Meaning: server date and time. 5348 Response code 200 5349 Generated by: initial connection, MODE READER 5350 Meaning: service available, posting allowed. 5352 Response code 201 5353 Generated by: initial connection, MODE READER 5354 Meaning: service available, posting prohibited. 5356 Response code 205 5357 Generated by: QUIT 5358 Meaning: connection closing (the server immediately closes the 5359 connection). 5361 Response code 211 5362 The 211 response code has two completely different forms depending 5363 on which command generated it: 5365 Generated by: GROUP 5366 4 arguments: number low high group 5367 Meaning: group selected. 5369 (multi-line) 5370 Generated by: LISTGROUP 5371 4 arguments: number low high group 5372 Meaning: article numbers follow. 5374 Response code 215 (multi-line) 5375 Generated by: LIST 5376 Meaning: information follows. 5378 Response code 220 (multi-line) 5379 Generated by: ARTICLE 5380 2 arguments: n message-id 5381 Meaning: article follows. 5383 Response code 221 (multi-line) 5384 Generated by: HEAD 5385 2 arguments: n message-id 5386 Meaning: article headers follow. 5388 Response code 222 (multi-line) 5389 Generated by: BODY 5390 2 arguments: n message-id 5391 Meaning: article body follows. 5393 Response code 223 5394 Generated by: LAST, NEXT, STAT 5395 2 arguments: n message-id 5396 Meaning: article exists and selected. 5398 Response code 224 (multi-line) 5399 Generated by: OVER 5400 Meaning: overview information follows. 5402 Response code 225 (multi-line) 5403 Generated by: HDR 5404 Meaning: headers follow. 5406 Response code 230 (multi-line) 5407 Generated by: NEWNEWS 5408 Meaning: list of new articles follows. 5410 Response code 231 (multi-line) 5411 Generated by: NEWGROUPS 5412 Meaning: list of new newsgroups follows. 5414 Response code 235 5415 Generated by: IHAVE (second stage) 5416 Meaning: article transferred OK. 5418 Response code 240 5419 Generated by: POST (second stage) 5420 Meaning: article received OK. 5422 Response code 335 5423 Generated by: IHAVE (first stage) 5424 Meaning: send article to be transferred. 5426 Response code 340 5427 Generated by: POST (first stage) 5428 Meaning: send article to be posted. 5430 Response code 400 5431 Generic response and generated by initial connection 5432 Meaning: service not available or no longer available (the server 5433 immediately closes the connection). 5435 Response code 401 5436 Generic response 5437 1 argument: capability-label 5438 Meaning: the server is in the wrong mode; the indicated capability 5439 should be used to change the mode. 5441 Response code 403 5442 Generic response 5443 Meaning: internal fault or problem preventing action being taken. 5445 Response code 411 5446 Generated by: GROUP, LISTGROUP 5447 Meaning: no such newsgroup. 5449 Response code 412 5450 Generated by: ARTICLE, BODY, GROUP, HDR, HEAD, LAST, LISTGROUP, 5451 NEXT, OVER, STAT 5452 Meaning: no newsgroup selected. 5454 Response code 420 5455 Generated by: ARTICLE, BODY, HDR, HEAD, LAST, NEXT, OVER, STAT 5456 Meaning: current article number is invalid. 5458 Response code 421 5459 Generated by: NEXT 5460 Meaning: no next article in this group. 5462 Response code 422 5463 Generated by: LAST 5464 Meaning: no previous article in this group. 5466 Response code 423 5467 Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT 5468 Meaning: no article with that number or in that range. 5470 Response code 430 5471 Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT 5472 Meaning: no article with that message-id. 5474 Response code 435 5475 Generated by: IHAVE (first stage) 5476 Meaning: article not wanted. 5478 Response code 436 5479 Generated by: IHAVE (either stage) 5480 Meaning: transfer not possible (first stage) or failed (second 5481 stage); try again later. 5483 Response code 437 5484 Generated by: IHAVE (second stage) 5485 Meaning: transfer rejected; do not retry. 5487 Response code 440 5488 Generated by: POST (first stage) 5489 Meaning: posting not permitted. 5491 Response code 441 5492 Generated by: POST (second stage) 5493 Meaning: posting failed. 5495 Response code 480 5496 Generic response 5497 Meaning: command unavailable until the client has authenticated 5498 itself. 5500 Response code 483 5501 Generic response 5502 Meaning: command unavailable until suitable privacy has been 5503 arranged. 5505 Response code 500 5506 Generic response 5507 Meaning: unknown command. 5509 Response code 501 5510 Generic response 5511 Meaning: syntax error in command. 5513 Response code 502 5514 Generic response and generated by initial connection 5515 Meaning for the initial connection and the MODE READER command: 5516 service permanently unavailable (the server immediately closes the 5517 connection). 5519 Meaning for all other commands: command not permitted (and there 5520 is no way for the client to change this). 5522 Response code 503 5523 Generic response 5524 Meaning: feature not supported. 5526 Response code 504 5527 Generic response 5528 Meaning: error in base64-encoding [RFC3548] of an argument 5530 Appendix D. Changes from RFC 977 5532 In general every attempt has been made to ensure that the protocol 5533 specification in this document is compatible with the version 5534 specified in RFC 977 [RFC977] and the various facilities adopted from 5535 RFC 2980 [RFC2980]. However, there have been a number of changes, 5536 some compatible and some not. 5538 This appendix lists these changes. It is not guaranteed to be 5539 exhaustive or correct and MUST NOT be relied on. 5541 o A formal syntax specification (Section 9) has been added. 5543 o The default character set is changed from US-ASCII [ANSI1986] to 5544 UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8). This 5545 matter is discussed further in Section 10. 5547 o All articles are required to have a message-id, eliminating the 5548 "<0>" placeholder used in RFC 977 in some responses. 5550 o The newsgroup name matching capabilities already documented in 5551 RFC 977 ("wildmats" (Section 4)) are clarified and extended. The 5552 new facilities (e.g. the use of commas and exclamation marks) are 5553 allowed wherever wildmats appear in the protocol. 5555 o Support for pipelining of commands (Section 3.5) is made 5556 mandatory. 5558 o The principles behind response codes (Section 3.2) have been 5559 tidied up. In particular: 5560 * the x8x response code family, formerly used for private 5561 extensions, is now reserved for authentication and privacy 5562 extensions; 5563 * the x9x response code family, formerly intended for debugging 5564 facilities, are now reserved for private extensions; 5565 * the 502 and 503 generic response codes (Section 3.2.1) have 5566 been redefined; 5567 * new 401, 403, 480, 483, and 504 generic response codes have 5568 been added. 5570 o The rules for article numbering (Section 6) have been clarified 5571 (also see Section 6.1.1.2). 5573 o The SLAVE command (which was ill-defined) is removed from the 5574 protocol. 5576 o Four-digit years are permitted in the NEWNEWS (Section 7.4) and 5577 NEWGROUPS (Section 7.3) commands (two-digit years are still 5578 permitted). The optional distribution parameter to these commands 5579 has been removed. 5581 o The LIST (Section 7.6.1) command is greatly extended; the original 5582 is available as LIST ACTIVE, while new variants include 5583 ACTIVE.TIMES, DISTRIB.PATS, and NEWSGROUPS. A new "m" status flag 5584 is added to the LIST ACTIVE response. 5586 o A new CAPABILITIES (Section 5.2) command allows clients to 5587 determine what facilities are supported by a server. 5589 o The DATE (Section 7.1) command is adopted from RFC 2980 5590 effectively unchanged. 5592 o The LISTGROUP (Section 6.1.2) command is adopted from RFC 2980. 5593 An optional range argument has been added, and the 211 initial 5594 response line now has the same format as the 211 response from the 5595 GROUP command. 5597 o The MODE READER (Section 5.3) command is adopted from RFC 2980 and 5598 its meaning and effects clarified. 5600 o The XHDR command in RFC 2980 has been formalised as the new HDR 5601 (Section 8.5) and LIST HEADERS (Section 8.6) commands. 5603 o The XOVER command in RFC 2980 has been formalised as the new OVER 5604 (Section 8.3) and LIST OVERVIEW.FMT (Section 8.4) commands. The 5605 former can be applied to a message-id as well as to a range. 5607 o The concept of article metadata (Section 8.1) has been formalised, 5608 allowing the Bytes and Lines pseudo-headers to be deprecated. 5610 Client authors should note in particular that lack of support for the 5611 CAPABILITIES command is a good indication that the server does not 5612 support this specification. 5614 Author's Address 5616 Clive D.W. Feather 5617 Thus plc 5618 322 Regents Park Road 5619 London N3 2QQ 5620 GB 5622 Phone: +44 20 8495 6138 5623 Fax: +44 870 051 9937 5624 Email: clive@demon.net 5625 URI: http://www.davros.org/ 5627 Intellectual Property Statement 5629 The IETF takes no position regarding the validity or scope of any 5630 Intellectual Property Rights or other rights that might be claimed to 5631 pertain to the implementation or use of the technology described in 5632 this document or the extent to which any license under such rights 5633 might or might not be available; nor does it represent that it has 5634 made any independent effort to identify any such rights. Information 5635 on the procedures with respect to rights in RFC documents can be 5636 found in BCP 78 and BCP 79. 5638 Copies of IPR disclosures made to the IETF Secretariat and any 5639 assurances of licenses to be made available, or the result of an 5640 attempt made to obtain a general license or permission for the use of 5641 such proprietary rights by implementers or users of this 5642 specification can be obtained from the IETF on-line IPR repository at 5643 http://www.ietf.org/ipr. 5645 The IETF invites any interested party to bring to its attention any 5646 copyrights, patents or patent applications, or other proprietary 5647 rights that may cover technology that may be required to implement 5648 this standard. Please address the information to the IETF at 5649 ietf-ipr@ietf.org. 5651 Disclaimer of Validity 5653 This document and the information contained herein are provided on an 5654 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 5655 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 5656 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 5657 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 5658 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 5659 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5661 Copyright Statement 5663 Copyright (C) The Internet Society (2005). This document is subject 5664 to the rights, licenses and restrictions contained in BCP 78, and 5665 except as set forth therein, the authors retain all their rights. 5667 Acknowledgment 5669 Funding for the RFC Editor function is currently provided by the 5670 Internet Society.