idnits 2.17.1 draft-ietf-nntpext-base-18.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC2629]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 38 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 281 has weird spacing: '...cal|bar indic...' == Line 929 has weird spacing: '...abc,def the t...' == Line 2181 has weird spacing: '...dhhmmss serv...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: These are the only valid response codes for the initial greeting; the server MUST not return any other generic response code. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 25, 2003) is 7672 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 3451, but not defined == Missing Reference: 'S' is mentioned on line 3452, but not defined -- Looks like a reference, but probably isn't: '1' on line 2894 == Missing Reference: 'GMT' is mentioned on line 2305, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'ANSI1986' ** Obsolete normative reference: RFC 1305 (Obsoleted by RFC 5905) ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 2822 (Obsoleted by RFC 5322) ** Obsolete normative reference: RFC 977 (Obsoleted by RFC 3977) -- Possible downref: Non-RFC (?) normative reference: ref. 'ROBE1995' -- Obsolete informational reference (is this intentional?): RFC 1036 (Obsoleted by RFC 5536, RFC 5537) -- Obsolete informational reference (is this intentional?): RFC 1869 (Obsoleted by RFC 2821) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2629 (Obsoleted by RFC 7749) Summary: 7 errors (**), 0 flaws (~~), 10 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NNTP C. Feather 3 Internet-Draft Thus plc 4 Expires: October 24, 2003 April 25, 2003 6 Network News Transport Protocol 7 draft-ietf-nntpext-base-18 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that other 16 groups may also distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 The list of current Internet-Drafts can be accessed at http:// 24 www.ietf.org/ietf/1id-abstracts.txt. 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 This Internet-Draft will expire on October 24, 2003. 31 Copyright Notice 33 Copyright (C) The Internet Society (2003). All Rights Reserved. 35 Abstract 37 The Network News Transport Protocol (NNTP) has been in use in the 38 Internet for a decade and remains one of the most popular protocols 39 (by volume) in use today. This document is a replacement for RFC 977 40 and officially updates the protocol specification. It clarifies some 41 vagueness in RFC 977, includes some new base functionality and 42 provides a specific mechanism to add standardized extensions to NNTP. 44 Administration 46 This document is a product of the NNTP Working Group, chaired by Russ 47 Allbery and Ned Freed. 49 Outstanding issues 50 OUTSTANDING ISSUE 52 Outstanding substantive (as opposed to editorial) issues in the 53 text are shown thus. 55 Author's Note 57 This draft is written in XML using an NNTP-specific DTD. Custom 58 software is used to convert this to RFC 2629 [RFC2629] format, and 59 then the public "xml2rfc" package to further reduce this to text, 60 nroff source, and HTML. 62 No perl was used in producing this draft. 64 Rights 66 UNIX is a registered trademark of the X/Open Company Ltd. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 7 71 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 3. Basic Concepts . . . . . . . . . . . . . . . . . . . . . . 9 73 3.1 Commands and Responses . . . . . . . . . . . . . . . . . . 9 74 3.2 Response Codes . . . . . . . . . . . . . . . . . . . . . . 11 75 3.2.1 Generic Response Codes . . . . . . . . . . . . . . . . . . 13 76 3.2.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 14 77 3.3 Pipelining . . . . . . . . . . . . . . . . . . . . . . . . 16 78 3.3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 17 79 3.4 Articles . . . . . . . . . . . . . . . . . . . . . . . . . 17 80 4. The WILDMAT format . . . . . . . . . . . . . . . . . . . . 20 81 4.1 Wildmat syntax . . . . . . . . . . . . . . . . . . . . . . 20 82 4.2 Wildmat semantics . . . . . . . . . . . . . . . . . . . . 20 83 4.3 Extensions . . . . . . . . . . . . . . . . . . . . . . . . 21 84 4.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 22 85 5. Session administration commands . . . . . . . . . . . . . 23 86 5.1 Initial Connection . . . . . . . . . . . . . . . . . . . . 23 87 5.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 23 88 5.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . 23 89 5.1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 23 90 5.2 MODE READER . . . . . . . . . . . . . . . . . . . . . . . 24 91 5.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 24 92 5.2.2 Description . . . . . . . . . . . . . . . . . . . . . . . 24 93 5.2.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 25 94 5.3 LIST EXTENSIONS . . . . . . . . . . . . . . . . . . . . . 26 95 5.3.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 26 96 5.3.2 Description . . . . . . . . . . . . . . . . . . . . . . . 26 97 5.3.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 27 98 5.4 QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 99 5.4.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 28 100 5.4.2 Description . . . . . . . . . . . . . . . . . . . . . . . 28 101 5.4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 28 102 6. Article posting and retrieval . . . . . . . . . . . . . . 29 103 6.1 Group and article selection . . . . . . . . . . . . . . . 29 104 6.1.1 GROUP . . . . . . . . . . . . . . . . . . . . . . . . . . 29 105 6.1.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 29 106 6.1.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . 30 107 6.1.1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 31 108 6.1.2 LAST . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 109 6.1.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 32 110 6.1.2.2 Description . . . . . . . . . . . . . . . . . . . . . . . 32 111 6.1.2.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 33 112 6.1.3 NEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 113 6.1.3.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 33 114 6.1.3.2 Description . . . . . . . . . . . . . . . . . . . . . . . 34 115 6.1.3.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 34 116 6.2 Retrieval of articles and article sections . . . . . . . . 35 117 6.2.1 ARTICLE . . . . . . . . . . . . . . . . . . . . . . . . . 35 118 6.2.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 35 119 6.2.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . 36 120 6.2.1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 37 121 6.2.2 HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 122 6.2.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 38 123 6.2.2.2 Description . . . . . . . . . . . . . . . . . . . . . . . 39 124 6.2.2.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 39 125 6.2.3 BODY . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 126 6.2.3.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 40 127 6.2.3.2 Description . . . . . . . . . . . . . . . . . . . . . . . 41 128 6.2.3.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 41 129 6.2.4 STAT . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 130 6.2.4.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 42 131 6.2.4.2 Description . . . . . . . . . . . . . . . . . . . . . . . 42 132 6.2.4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 43 133 6.3 Article posting . . . . . . . . . . . . . . . . . . . . . 44 134 6.3.1 POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 135 6.3.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 44 136 6.3.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . 44 137 6.3.1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 45 138 6.3.2 IHAVE . . . . . . . . . . . . . . . . . . . . . . . . . . 46 139 6.3.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 46 140 6.3.2.2 Description . . . . . . . . . . . . . . . . . . . . . . . 46 141 6.3.2.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 47 142 7. Information commands . . . . . . . . . . . . . . . . . . . 50 143 7.1 DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 144 7.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 50 145 7.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . 50 146 7.1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 50 147 7.2 HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 148 7.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 50 149 7.2.2 Description . . . . . . . . . . . . . . . . . . . . . . . 51 150 7.2.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 51 151 7.3 NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 51 152 7.3.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 51 153 7.3.2 Description . . . . . . . . . . . . . . . . . . . . . . . 51 154 7.3.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 52 155 7.4 NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 53 156 7.4.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 53 157 7.4.2 Description . . . . . . . . . . . . . . . . . . . . . . . 53 158 7.4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 53 159 7.5 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 160 7.5.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 54 161 7.6 The LIST commands . . . . . . . . . . . . . . . . . . . . 55 162 7.6.1 LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . . . 55 163 7.6.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 55 164 7.6.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . 55 165 7.6.1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 56 166 7.6.2 LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . . . 57 167 7.6.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 57 168 7.6.2.2 Description . . . . . . . . . . . . . . . . . . . . . . . 57 169 7.6.2.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 58 170 7.6.3 LIST DISTRIBUTIONS . . . . . . . . . . . . . . . . . . . . 58 171 7.6.3.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 59 172 7.6.3.2 Description . . . . . . . . . . . . . . . . . . . . . . . 59 173 7.6.3.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 59 174 7.6.4 LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . . . 60 175 7.6.4.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 60 176 7.6.4.2 Description . . . . . . . . . . . . . . . . . . . . . . . 60 177 7.6.4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 60 178 7.6.5 LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . . . 61 179 7.6.5.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 61 180 7.6.5.2 Description . . . . . . . . . . . . . . . . . . . . . . . 61 181 7.6.5.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 62 182 8. Framework for NNTP extensions . . . . . . . . . . . . . . 63 183 8.1 Initial IANA registry . . . . . . . . . . . . . . . . . . 65 184 8.2 Standard extensions . . . . . . . . . . . . . . . . . . . 65 185 8.3 The LISTGROUP extension . . . . . . . . . . . . . . . . . 65 186 8.3.1 LISTGROUP . . . . . . . . . . . . . . . . . . . . . . . . 65 187 8.3.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 65 188 8.3.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . 66 189 8.3.1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 66 190 8.4 Article metadata . . . . . . . . . . . . . . . . . . . . . 67 191 8.4.1 The :bytes metadata item . . . . . . . . . . . . . . . . . 68 192 8.4.2 The :lines metadata item . . . . . . . . . . . . . . . . . 68 193 8.5 The OVER extension . . . . . . . . . . . . . . . . . . . . 68 194 8.5.1 OVER . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 195 8.5.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 68 196 8.5.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . 69 197 8.5.1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 70 198 8.5.2 LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 72 199 8.5.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 72 200 8.5.2.2 Description . . . . . . . . . . . . . . . . . . . . . . . 72 201 8.5.2.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 73 202 8.6 The HDR extension . . . . . . . . . . . . . . . . . . . . 74 203 8.6.1 HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 204 8.6.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 74 205 8.6.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . 74 206 8.6.1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 76 207 9. Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . 78 208 9.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . 78 209 9.2 Responses . . . . . . . . . . . . . . . . . . . . . . . . 80 210 9.3 Articles . . . . . . . . . . . . . . . . . . . . . . . . . 80 211 9.4 General non-terminals . . . . . . . . . . . . . . . . . . 80 212 10. IANA Considerations . . . . . . . . . . . . . . . . . . . 82 213 11. Security Considerations . . . . . . . . . . . . . . . . . 83 214 11.1 Personal and Proprietary Information . . . . . . . . . . . 83 215 11.2 Abuse of Server Log Information . . . . . . . . . . . . . 83 216 11.3 Weak Authentication and Access Control . . . . . . . . . . 83 217 11.4 DNS Spoofing . . . . . . . . . . . . . . . . . . . . . . . 84 218 11.5 UTF-8 issues . . . . . . . . . . . . . . . . . . . . . . . 84 219 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 86 220 Normative References . . . . . . . . . . . . . . . . . . . 88 221 Informative References . . . . . . . . . . . . . . . . . . 89 222 Author's Address . . . . . . . . . . . . . . . . . . . . . 89 223 Intellectual Property and Copyright Statements . . . . . . 90 225 1. Introduction 227 This document specifies the Network News Transport Protocol (NNTP), 228 which is used for the distribution, inquiry, retrieval, and posting 229 of Netnews articles using a reliable stream-based mechanism. For news 230 reading clients, NNTP enables retrieval of news articles that are 231 stored in a central database, giving subscribers the ability to 232 select only those articles they wish to read. 234 The Netnews model provides for indexing, cross-referencing, and 235 expiration of aged messages. For server-to-server interaction, NNTP 236 is designed for efficient transmission of Netnews articles over a 237 reliable full duplex communication channel. 239 Every attempt is made to ensure that the protocol specification in 240 this document is compatible with the version specified in RFC 977 241 [RFC977]. However, this version does not support the ill-defined 242 SLAVE command and permits four digit years to be specified in the 243 NEWNEWS and NEWGROUPS commands. It changes the default character set 244 to UTF-8 [RFC2279] instead of US-ASCII [ANSI1986]. It now requires 245 all articles to have a message-id, eliminating the "<0>" placeholder 246 used in RFC 977. It also extends the newsgroup name matching 247 capabilities already documented in RFC 977. 249 Generally, new functionality is made available using new commands. 250 Part of that new functionality involves a mechanism to discover what 251 new functionality is available to clients from a server. This 252 mechanism can also be used to add more functionality as needs merit 253 such additions. 255 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 256 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 257 document are to be interpreted as described in RFC 2119 [RFC2119]. 259 An implementation is not compliant if it fails to satisfy one or more 260 of the MUST requirements for this protocol. An implementation that 261 satisfies all the MUST and all the SHOULD requirements for its 262 protocols is said to be "unconditionally compliant"; one that 263 satisfies all the MUST requirements but not all the SHOULD 264 requirements for NNTP is said to be "conditionally compliant". 266 For the remainder of this document, the term "client" or "client 267 host" refers to a host making use of the NNTP service, while the term 268 "server" or "server host" refers to a host that offers the NNTP 269 service. 271 2. Notation 273 The following notational conventions are used in this document. 275 UPPERCASE indicates literal text to be included in the 276 command; 277 lowercase indicates a token described elsewhere; 278 [brackets] indicate that the parameter is optional; 279 ellipsis... indicates that the parameter may be repeated any 280 number of times (it must occur at least once); 281 vertical|bar indicates a choice of two mutually exclusive 282 parameters (exactly one must be provided). 284 The name "message-id" for a command or response parameter indicates 285 that it is the message-id of an article as described in Section 3.4, 286 including the angle brackets. 288 The name "wildmat" for a parameter indicates that it is a wildmat as 289 defined in Section 4. If the parameter does not meet the requirements 290 of that section (for example, if it does not fit the grammar of 291 Section 4.1) the NNTP server MAY place some interpretation on it (not 292 specified by this document) or otherwise MUST treat it as a syntax 293 error. 295 Responses for each command will be described in tables listing the 296 required format of a response followed by the meaning that should be 297 ascribed to that response. 299 The terms "NUL", "TAB", "LF", "CR, and "space" refer to the octets 300 with those codes in US-ASCII [ANSI1986] (that is, %x00, %x09, %x0A, 301 %x0D, and %x20 respectively), as do quoted characters (so "." and "<" 302 refer to %x2E and %x3C). The term "CRLF" or "CRLF pair" means the 303 sequence CR immediately followed by LF (that is, %x0D.0A). A 304 "printable US-ASCII character" is an octet in the range %x21-7E. 306 Examples in this document are not normative but serve to illustrate 307 usages, arguments, and responses. In the examples, a "[C]" will be 308 used to represent the client host and a "[S]" will be used to 309 represent the server host. Most of the examples do not rely on a 310 particular server state. In some cases, however, they do assume that 311 the current selected newsgroup (see the GROUP command (Section 312 6.1.1)) is invalid; when so, this is indicated at the start of the 313 example. 315 3. Basic Concepts 317 3.1 Commands and Responses 319 NNTP operates over any reliable data stream 8-bit-wide channel. 320 Initially, the server host starts the NNTP service by listening on a 321 TCP port; when running over TCP/IP, the official port for the NNTP 322 service is 119. When a client host wishes to make use of the service, 323 it MUST establish a TCP connection with the server host by connecting 324 to that host on the same port on which the server is listening. When 325 the connection is established, the NNTP server host MUST send a 326 greeting. The client host and server host then exchange commands and 327 responses (respectively) until the connection is closed or aborted. 329 The character set for all NNTP commands is UTF-8 [RFC2279]. Commands 330 in NNTP MUST consist of a keyword, which MAY be followed by one or 331 more arguments. A CRLF pair MUST terminate all commands. Multiple 332 commands MUST NOT be on the same line. Keywords MUST consist of 333 printable US-ASCII characters. Unless otherwise noted elsewhere in 334 this document, arguments SHOULD consist of printable US-ASCII 335 characters. Keywords and arguments MUST be each separated by one or 336 more space or TAB characters. Keywords MUST be at least three 337 characters and MUST NOT exceed 12 characters. Command lines MUST NOT 338 exceed 512 octets, which includes the terminating CRLF pair. The 339 arguments MUST NOT exceed 497 octets. 341 Where this specification permits UTF-8 characters outside the range 342 U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark 343 (U+FEFF, encoding %xEF.BB.BF), and MUST use the Word Joiner (U+2060, 344 encoding %xE2.91.A0) for the meaning Zero Width No-Break Space, in 345 command lines and the initial lines of responses, and SHOULD apply 346 these same principles throughout. 348 Commands may have variants, using a second keyword immediately after 349 the first to indicate which variant is required. The only such 350 commands in this specification are LIST and MODE. 352 Keywords are case-insensitive; the case of keywords for commands MUST 353 be ignored by the server. Command and response parameters are case or 354 language specific only when stated, either in this document or in 355 other relevant specifications. 357 An NNTP server MUST implement all the commands in this specification 358 except for those marked as optional and those in extensions. 360 Each response MUST start with a three-digit response code that is 361 sufficient to distinguish all responses. Certain valid responses are 362 defined to be multi-line; for all others, the response is contained 363 in a single line. 365 OUTSTANDING ISSUE 367 Should the initial response line be limited to 512 octets as well? 368 Possible text: 370 The first or only line of the response MUST NOT exceed 512 octets, 371 which includes the response code and the terminating CRLF pair. 373 The text further down about "does not place any limit on the 374 length" would need equivalent edits. 376 All multi-line responses MUST adhere to the following format: 378 1. The response consists of a sequence of one or more "lines", each 379 being a stream of octets ending with a CRLF pair. Apart from 380 those line endings, the stream MUST NOT include the octets NUL, 381 LF, or CR. 383 2. The first such line contains the response code as with a single 384 line response. 386 3. If any subsequent line begins with the "termination octet" ("." 387 or %x2E), that line MUST be "byte-stuffed" by pre-pending an 388 additional termination octet to that line of the response. 390 4. The lines of the response MUST be followed by a terminating line 391 consisting of a single termination octet followed by a CRLF pair 392 in the normal way. Thus a multi-line response is always 393 terminated with the five octets CRLF "." CRLF (%x0D.0A.2E.0D.0A). 395 5. When interpreting a multi-line response, the "byte stuffing" MUST 396 be undone; i.e. the client MUST ensure that, in any line 397 beginning with the termination octet followed by octets other 398 than a CRLF pair, that initial termination octet is disregarded. 400 6. Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT 401 be considered part of the multi-line response; i.e. the client 402 MUST ensure that any line beginning with the termination octet 403 followed immediately by a CRLF pair is disregarded; (the first 404 CRLF pair of the terminating CRLF "." CRLF is, of course, part of 405 the last line of the response). 407 Note that texts using an encoding (such as UTF-16 or UTF-32) that may 408 contain the octets NUL, LF, or CR other than a CRLF pair cannot be 409 reliably conveyed in the above format. However, except when stated 410 otherwise, this specification does not require the content to be 411 UTF-8 and it is possible for octets above and below 128 to be mixed 412 arbitrarily. 414 This document does not place any limit on the length of a line. 415 However, the standards that define the format of articles may do so. 417 An NNTP server MAY have an inactivity autologout timer. Such a timer 418 SHOULD be of at least three minutes duration, with the exception that 419 there MAY be a shorter limit on how long the server is willing to 420 wait for the first command from the client. The receipt of any 421 command from the client during the timer interval SHOULD suffice to 422 reset the autologout timer. Similarly, the receipt of any significant 423 amount of data from the client while in the midst of sending a 424 multi-line message to the server (such as during a POST or IHAVE 425 command) SHOULD suffice to reset the autologout timer. When the timer 426 expires, the server SHOULD close the TCP connection without sending 427 any response to the client. 429 3.2 Response Codes 431 Each response MUST begin with a three-digit status indicator. These 432 are status reports from the server and indicate the response to the 433 last command received from the client. 435 The first digit of the response broadly indicates the success, 436 failure, or progress of the previous command. 438 1xx - Informative message. 439 2xx - Command completed OK. 440 3xx - Command OK so far; send the rest of it. 441 4xx - Command was correct, but couldn't be performed for some 442 reason. 443 5xx - Command unimplemented, or incorrect, or a serious program 444 error occurred. 446 OUTSTANDING ISSUE 448 I proposed that we assign 6xx for extensions and future commands 449 to use for multiline responses, thus at least limiting (if not 450 eliminating) the problem clients have of working out whether one 451 is coming up. Nobody was violently against the idea, but nobody 452 was particularly in favour either. 454 The next digit in the code indicates the function response category. 456 x0x - Connection, setup, and miscellaneous messages 457 x1x - Newsgroup selection 458 x2x - Article selection 459 x3x - Distribution functions 460 x4x - Posting 461 x8x - Reserved for authentication and authorization extensions 462 x9x - Reserved for private use (non-standard extensions) 464 Certain responses contain parameters such as numbers and names in 465 addition to the status indicator. In those cases, to simplify 466 interpretation by the client the number and type of such parameters 467 is fixed for each response code, as is whether or not the code 468 introduces a multi-line response. Any extension MUST follow this 469 principle as well, but note that, for historical reasons, the 211 470 response code is an exception to this. In all other cases, the client 471 MUST only use the status indicator itself to determine the nature of 472 the response. The exact response codes that can be returned by any 473 given command are detailed in the description of that command. 475 Parameters MUST be separated from the numeric status indicator and 476 from each other by a single space. All numeric parameters MUST be in 477 base 10 (decimal) format, and MAY have leading zeros. String 478 parameters MUST contain at least one character and MUST NOT contain 479 TAB, LF, CR, or space. The server MAY add any text after the response 480 code or last parameter as appropriate, and the client MUST NOT make 481 decisions based on this text. Such text MUST be separated from the 482 numeric status indicator or the last parameter by at least one space. 484 The server MUST respond to any command with the appropriate generic 485 response (given in Section 3.2.1) if it represents the situation. 486 Otherwise, each recognized command MUST return one of the response 487 codes specifically listed in its description or in an extension. A 488 server MAY provide extensions to this specification, including new 489 commands, new variants or features of existing commands, and other 490 ways of changing the internal state of the server. However, the 491 server MUST NOT produce any other responses to a client that does not 492 invoke any of the additional features. (Therefore a client that 493 restricts itself to this specification will only receive the 494 responses that are listed.) 496 If a client receives an unexpected response, it SHOULD use the first 497 digit of the response to determine the result. For example, an 498 unexpected 2xx should be taken as success and an unexpected 4xx or 499 5xx as failure. 501 Response codes not specified in this document MAY be used for any 502 installation-specific additional commands also not specified. These 503 SHOULD be chosen to fit the pattern of x9x specified above. 505 Neither this document nor any extension registered with IANA (see 506 Section 8) will specify any response codes of the x9x pattern. 508 (Implementers of extensions are accordingly cautioned not to use such 509 responses for extensions that may subsequently be submitted for 510 registration.) 512 3.2.1 Generic Response Codes 514 The server MUST respond to any command with the appropriate one of 515 the following generic responses if it represents the situation. 517 If the command is not recognized, or it is an optional command or 518 extension that is not implemented by the server, the response code 519 500 MUST be returned. 521 If there is a syntax error in the arguments of a recognized command, 522 including the case where more arguments are provided than the command 523 specifies, the response code 501 MUST be returned. Note that where a 524 command has variants depending on a second keyword (e.g. LIST ACTIVE 525 and LIST NEWSGROUPS), then 501 MUST be used when the requested 526 variant is not implemented but the base command is. 528 If the server experiences an internal fault or problem that means it 529 is unable to carry out the command (for example, a necessary file is 530 missing or a necessary service could not be contacted), the response 531 code 403 MUST be returned. If the server recognises the command but 532 does not provide an optional feature (for example because it does not 533 store the required information), or only handles a subset of 534 legitimate cases (see the HDR command (Section 8.6.1) for an 535 example), the response code 503 MUST be returned. Note that where a 536 command is optional (e.g. LIST ACTIVE.TIMES) and is not provided by a 537 server, this MAY be treated as an unimplemented command (response 538 code 500 or 501) or as a working command where the information is not 539 available (response code 503). 541 OUTSTANDING ISSUE 543 Do we need to add text like: 545 For backwards compatibility a server MAY return the response 546 code 503 where this specification requires the response code 547 403, and a client SHOULD be prepared for this. This waiver may 548 be removed in a future revision of this specification. 550 If the client is not authorized to use the specified facility when 551 the server is in its current state, then either the response code 480 552 or the response code 502 MUST be returned. The response code 480 553 SHOULD be used if a different command (for example, an extension used 554 to present credentials) might change the server state so that the 555 command is permitted. The response code 502 SHOULD be used if the 556 server wishes to indicate that it is necessary to terminate the 557 connection and start a new one with the appropriate authority before 558 the command can be used. Since it is not always possible to clearly 559 distinguish these two cases, a server MAY issue either of these 560 response codes for either case. (Note that the server MUST NOT close 561 the TCP connection immediately after a 502 response except at the 562 initial connection (Section 5.1) and with the MODE READER (Section 563 5.2) command.) 565 OUTSTANDING ISSUE 567 This isn't a complete solution to the 480 issue; what about the 568 TLS extension, which uses 483 to mean "you need encryption". 569 Should 480 be used for other than "you need authentication"? What 570 code should be used to mean "can't do AUTH until after MODE 571 READER"? 573 Do we need a more generic mechanism for "you must invoke extension 574 X to do Y"? 576 The best proposal made so far is that all 48x codes, if returned 577 from an existing command, mean "unavailable unless some 578 authentication or privacy extension is invoked". Does this tie in 579 with the issue of permitting existing commands not listed in an 580 extension? 582 If the server has to terminate the connection for some reason, it 583 MUST give a 400 response code to the next command and then 584 immediately close the TCP connection. It MAY give a 401 response code 585 to any command to indicate that termination is imminent (following a 586 401 response, it MUST NOT close the TCP connection immediately). 588 OUTSTANDING ISSUE 590 It's not clear that we need 401; it appears to have been an 591 invention. If we do keep it, then text is needed to indicate what 592 happens with commands that change the status (for example, if 593 GROUP returns 401 what happens to the current selected newsgroup), 594 and how to make those commands work. 596 With the exception of mandatory commands and the 500 response, the 597 client MUST be prepared to receive any of these responses for any 598 command. 600 3.2.1.1 Examples 602 Example of an unknown command: 604 [C] MAIL 605 [S] 500 Unknown command 607 Example of an unsupported extension: 609 [C] LIST EXTENSIONS 610 [S] 202 Extensions supported: 611 [S] LISTGROUP 612 [S] . 613 [C] OVER 614 [S] 500 Unknown command 616 Example of an unsupported variant: 618 [C] MODE POSTER 619 [S] 501 Unknown MODE option 621 Example of a syntax error: 623 [C] ARTICLE a.message.id@no.angle.brackets 624 [S] 501 Syntax error 626 Example of an overlong command line: 628 [C] HEAD 53 54 55 629 [S] 501 Too many arguments 631 Example of a bad wildmat: 633 [C] LIST ACTIVE u[ks].* 634 [S] 501 Syntax error 636 Example of an attempt to access a restricted facility: 638 [C] GROUP secret.group 639 [S] 480 Permission denied 641 followed by a successful attempt following authentication: 643 [C] XSECRET fred flintstone 644 [S] 290 Password for fred accepted. 645 [C] GROUP secret.group 646 [S] 211 5 1 20 secret.group selected 648 Example of an attempt to access a facility not available to this 649 connection: 651 [C] MODE READER 653 [S] 200 Reader mode, posting permitted 654 [C] IHAVE 655 [S] 502 Permission denied 657 Example of a temporary failure: 659 [C] GROUP archive.local 660 [S] 403 Archive server temporarily offline 662 Example of the server needing to close down immediately: 664 [C] ARTICLE 123 665 [S] 400 Power supply failed, running on UPS 666 [Server closes connection.] 668 Example of imminent termination of the server: 670 [C] STAT 123 671 [S] 401 Pre-payment expired, you have 10 seconds 672 [C] STAT 123 673 [S] 423 No such article number in this group 674 [C] NEXT 675 [S] 400 Time expired 676 [Server closes connection.] 678 3.3 Pipelining 680 NNTP is designed to operate over a reliable bi-directional connection 681 such as TCP. Therefore, if a command does not depend on the response 682 to the previous one, it should not matter if it is sent before that 683 response is received. Doing this is called "pipelining". However, 684 certain server implementations throw away all text received from the 685 client following certain commands before sending their response. If 686 this happens, pipelining will be affected because one or more 687 commands will have been ignored or misinterpreted, and the client 688 will be matching the wrong responses to each command. Since there are 689 significant benefits to pipelining, but also circumstances where it 690 is reasonable or common for servers to behave in the above manner, 691 this document puts certain requirements on both clients and servers. 693 Except where stated otherwise, a client MAY use pipelining. That is, 694 it may send a command before receiving the response for the previous 695 command. The server MUST allow pipelining and MUST NOT throw away any 696 text received after a command. Irrespective of whether or not 697 pipelining is used, the server MUST process commands in the order 698 they are sent. 700 If the specific description of a command says it "MUST NOT be 701 pipelined", that command MUST end any pipeline of commands. That is, 702 the client MUST NOT send any following command until receiving the 703 CRLF at the end of the response from the command. The server MAY 704 ignore any data received after the command and before the CRLF at the 705 end of the response is sent to the client. 707 The initial connection must not be part of a pipeline; that is, the 708 client MUST NOT send any command until receiving the CRLF at the end 709 of the greeting. 711 If the client uses blocking system calls to send commands, it MUST 712 ensure that the amount of text sent in pipelining does not cause a 713 deadlock between transmission and reception. The amount of text 714 involved will depend on window sizes in the transmission layer, and 715 is typically 4k octets for TCP. 717 3.3.1 Examples 719 Example of correct use of pipelining: 721 [C] GROUP misc.test 722 [C] STAT 723 [C] NEXT 724 [S] 211 1234 3000234 3002322 misc.test 725 [S] 223 3000234 <45223423@example.com> retrieved 726 [S] 223 3000237 <668929@example.org> retrieved 728 Example of incorrect use of pipelining (the MODE READER command may 729 not be pipelined): 731 [C] GROUP misc.test 732 [C] MODE READER 733 [C] DATE 734 [C] NEXT 735 [S] 211 1234 3000234 3002322 misc.test 736 [S] 200 Server ready, posting allowed 737 [S] 223 3000237 <668929@example.org> retrieved 739 The DATE command has been thrown away by the server and so there is 740 no 111 response to match it. 742 3.4 Articles 744 OUTSTANDING ISSUE 746 This section is new. If anyone has better wording, I won't 747 complain. 749 NNTP is intended to transfer articles between clients and servers. 750 For the purposes of this specification, articles are required to 751 conform to the rules in this section and clients and servers MUST 752 correctly process any article received from the other that does so. 753 Note that this requirement applies only to the contents of 754 communications over NNTP; it does not prevent the client or server 755 from subsequently rejecting an article for reasons of local policy. 756 In particular, where NNTP is used to transport articles that conform 757 to other specifications such as RFC 1036 [RFC1036] or RFC 2822 758 [RFC2822], articles must meet both this specification and that other. 760 OUTSTANDING ISSUE 762 Need to add an appendix that spells out how this document 763 interacts with RFC 1036. That would allow us to remove some of the 764 convoluted wording about "other specifications". 766 An article consists of two parts: the headers and the body. They are 767 separated by a single empty line, or in other words by two 768 consecutive CRLF pairs (if there is more than one empty line, the 769 second and subsequent ones are part of the body). In order to meet 770 the general requirements of NNTP, an article MUST NOT include the 771 octet NUL, MUST NOT contain the octets LF and CR other than as part 772 of a CRLF pair, and MUST end with a CRLF pair. This specification 773 puts no further restrictions on the body; in particular, it MAY be 774 empty. 776 The headers of an article consist of one or more header lines. Each 777 header line consists of a header name, a colon, a space, the header 778 content, and a CRLF in that order. The name consists of one or more 779 printable US-ASCII characters other than colon and, for the purposes 780 of this specification, is not case sensitive. There MAY be more than 781 one header line with the same name. The content MUST NOT contain CRLF 782 but is otherwise unrestricted; in particular, it MAY be empty. A 783 header may be "folded"; that is, a CRLF pair may be placed before any 784 TAB or space in the line (including the space after the colon after 785 the header name), except that there MUST be at least one octet other 786 than %x09 or %x20 between any two CRLF pairs in a header line. (Note 787 that folding means that the header line occupies more than one line 788 when displayed or transmitted; nevertheless it is still referred to 789 as "a" header line.) The presence or absence of folding does not 790 affect the meaning of the header line; that is, the CRLF pairs 791 introduced by folding are not considered part of the header value. 793 Each article MUST have a unique message-id; two articles offered by 794 an NNTP server MUST NOT have the same message-id. Note that RFC 1036 795 [RFC1036] further requires that message-ids are globally unique for 796 all time. 798 For the purposes of this specification, message-ids are opaque 799 strings that MUST meet the following requirements: 801 o A message-id MUST begin with "<" and end with ">", and MUST NOT 802 contain the latter except at the end. 804 o A message-id MUST be between 3 and 250 octets in length. 806 o A message-id MUST NOT contain octets other than printable US-ASCII 807 characters. 809 Two message-ids are the same if and only if they consist of the same 810 sequence of octets. Other specifications may define two different 811 sequences as being equal; an NNTP server that also conforms to such a 812 specification must consistently use only one or the other. As an 813 example, the message-ids: 815 816 <"abcd"@example.com> 817 <"ab\cd"@example.com> 819 are considered distinct by this specification even though they would 820 be considered semantically identical according to the specification 821 in RFC 2822 [RFC2822]. 823 This specification does not describe how the message-id of an article 824 is determined (if the server is also conforming to another 825 specification that contains a definition of message-id compatible 826 with this one, the server SHOULD use those message-ids). Many servers 827 will extract the message-id from the contents of a header with name 828 "Message-ID", but this is not required by this document. If the 829 server does not have any way to determine a message-id from the 830 article itself, it MUST synthesise one (it need not modify the 831 article to add such a header unless required to by another 832 specification). 834 4. The WILDMAT format 836 The WILDMAT format described here is based on the version first 837 developed by Rich Salz [SALZ1992], which in turn was derived from the 838 format used in the UNIX "find" command to articulate file names. It 839 was developed to provide a uniform mechanism for matching patterns in 840 the same manner that the UNIX shell matches filenames. 842 4.1 Wildmat syntax 844 A wildmat is described by the following ABNF [RFC2234] syntax (note 845 that this syntax contains ambiguities and special cases described at 846 the end): 848 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 850 wildmat-pattern = 1*wildmat-item 852 wildmat-item = wildmat-exact / wildmat-wild 854 wildmat-exact = %x21-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 855 UTF8-non-ascii ; exclude * , ? [ \ ] 857 wildmat-wild = "*" / "?" 859 UTF8-non-ascii is defined in Section 9. 861 This syntax must be interpreted subject to the following rule: 863 Where a wildmat-pattern is not immediately preceded by "!", it shall 864 not begin with a "!". 866 Note: the characters \ , [ and ] are not allowed in wildmats, while * 867 and ? are always wildcards. This should not be a problem since these 868 characters cannot occur in newsgroup names, which is the only current 869 use of wildmats. Backslash is commonly used to suppress the special 870 meaning of characters while brackets are used to introduce sets. 871 However, these usages are not universal and interpretation of these 872 characters in the context of UTF-8 strings is both potentially 873 complex and differs from existing practice, so they were omitted from 874 this specification. A future extension to this specification may 875 provide semantics for these characters. 877 4.2 Wildmat semantics 879 A wildmat is tested against a string, and either matches or does not 880 match. To do this, each constituent wildmat-pattern is matched 881 against the string and the rightmost pattern that matches is 882 identified. If that wildmat-pattern is not preceded with "!", the 883 whole wildmat matches. If it is preceded by "!", or if no 884 wildmat-pattern matches, the whole wildmat does not match. 886 For example, consider the wildmat "a*,!*b,*c*": 888 the string "aaa" matches because the rightmost match is with "a*" 890 the string "abb" does not match because the rightmost match is 891 with "*b" 893 the string "ccb" matches because the rightmost match is with "*c*" 895 the string "xxx" does not match because no wildmat-pattern matches 897 A wildmat-pattern matches a string if the string can be broken into 898 components, each of which matches the corresponding wildmat-item in 899 the pattern; the matches must be in the same order, and the whole 900 string must be used in the match. The pattern is "anchored"; that is, 901 the first and last characters in the string must match the first and 902 last item respectively (unless that item is an asterisk matching zero 903 characters). 905 A wildmat-exact matches the same character (which may be more than 906 one octet in UTF-8). 908 "?" matches exactly one character (which may be more than one octet). 910 "*" matches zero or more characters. It can match an empty string, 911 but it cannot match a subsequence of a UTF-8 sequence that is not 912 aligned to the character boundaries. 914 4.3 Extensions 916 An NNTP server or extension MAY extend the syntax or semantics of 917 wildmats provided that all wildmats that meet the requirements of 918 Section 4.1 have the meaning ascribed to them by Section 4.2. Future 919 editions of this document may also extend wildmats. 921 4.4 Examples 923 In these examples, $ and @ are used to represent the two octets %xC2 924 and %xA3 respectively; $@ is thus the UTF-8 encoding for the pound 925 sterling symbol, shown as # in the descriptions. 927 Wildmat Description of strings that match 928 abc the one string "abc" 929 abc,def the two strings "abc" and "def" 930 $@ the one character string "#" 931 a* any string that begins with "a" 932 a*b any string that begins with "a" and ends with "b" 933 a*,*b any string that begins with "a" or ends with "b" 934 a*,!*b any string that begins with "a" and does not end with 935 "b" 936 a*,!*b,c* any string that begins with "a" and does not end with 937 "b", and any string that begins with "c" no matter 938 what it ends with 939 a*,c*,!*b any string that begins with "a" or "c" and does not 940 end with "b" 941 ?a* any string with "a" as its second character 942 ??a* any string with "a" as its third character 943 *a? any string with "a" as its penultimate character 944 *a?? any string with "a" as its antepenultimate character 946 5. Session administration commands 948 5.1 Initial Connection 950 5.1.1 Usage 952 Responses 953 200 Service available, posting allowed 954 201 Service available, posting prohibited 955 400 Service temporarily unavailable [1] 956 502 Service permanently unavailable [1] 958 These are the only valid response codes for the initial greeting; 959 the server MUST not return any other generic response code. 961 [1] Following a 400 or 502 response the server MUST immediately close 962 the connection. 964 5.1.2 Description 966 There is no command presented by the client upon initial connection 967 to the server. The server MUST present an appropriate response code 968 as a greeting to the client. This response informs the client whether 969 service is available and whether the client is permitted to post. 971 If the server will accept further commands from the client including 972 POST, the server MUST present a 200 greeting code. If the server will 973 accept further commands from the client, but it is not authorized to 974 post articles using the POST command, the server MUST present a 201 975 greeting code. 977 Otherwise the server MUST present a 400 or 502 greeting code and then 978 immediately close the connection. 502 MUST be used if the client is 979 not permitted under any circumstances to interact with the server and 980 400 otherwise. 982 5.1.3 Examples 984 Example of a normal connection from an authorized client which then 985 terminates the session (see Section 5.4): 987 [Initial TCP connection setup completed.] 988 [S] 200 NNTP Service Ready, posting permitted 989 [C] QUIT 990 [S] 205 NNTP Service exits normally 991 [Server closes connection.] 993 Example of a normal connection from an authorized client that is not 994 permitted to post; it also immediately terminates the session: 996 [Initial TCP connection setup completed.] 997 [S] 201 NNTP Service Ready, posting prohibited 998 [C] QUIT 999 [S] 205 NNTP Service exits normally 1000 [Server closes connection.] 1002 Example of a normal connection from an unauthorized client: 1004 [Initial TCP connection setup completed.] 1005 [S] 502 NNTP Service permanently unavailable 1006 [Server closes connection.] 1008 Example of a connection from a client where the server is unable to 1009 provide service: 1011 [Initial TCP connection setup completed.] 1012 [S] 400 NNTP Service temporarily unavailable 1013 [Server closes connection.] 1015 5.2 MODE READER 1017 5.2.1 Usage 1019 This command MUST NOT be pipelined. 1021 Syntax 1022 MODE READER 1024 Responses 1025 200 Posting allowed 1026 201 Posting prohibited 1027 400 Service temporarily unavailable [1] 1028 502 Service permanently unavailable [1] 1030 [1] Following a 400 or 502 response the server MUST immediately close 1031 the connection. 1033 5.2.2 Description 1035 MODE READER SHOULD be sent by any client that intends to use any 1036 command other than IHAVE, HEAD, STAT, LIST ACTIVE, LIST EXTENSIONS, 1037 or a command advertised by the server as available via LIST 1038 EXTENSIONS. 1040 Servers MAY require that this command be issued before any commands 1041 other than the above are sent and MAY reject such commands until 1042 after a MODE READER command has been sent. Where an extension is only 1043 available after a MODE READER command, or where the effects of the 1044 extension will change, the LIST EXTENSIONS command MUST produce 1045 different results that indicate the change. 1047 The server MUST return a response using the same codes as the initial 1048 greeting (as described in Section 5.1.1) to indicate its ability to 1049 provide reading service to the client. Note that the response need 1050 not be the same as the one presented during the initial greeting. 1052 Once MODE READER is sent, IHAVE (and any extensions intended for 1053 peer-to-peer article transfer) MAY no longer be permitted, even if it 1054 were permitted before the MODE READER command. The results of LIST 1055 EXTENSIONS MAY be different following a MODE READER command than 1056 prior to the issuing of that command. 1058 Servers are encouraged to not require this command even though 1059 clients SHOULD send it when appropriate. It is present to support 1060 some news architectures that switch between modes based on whether a 1061 given connection is a peer-to-peer connection with another server or 1062 a news reading client. 1064 5.2.3 Examples 1066 Example of use of the MODE READER command by an authorized client 1067 which then terminates the session (see Section 5.4): 1069 [C] MODE READER 1070 [S] 200 NNTP Service Ready, posting permitted 1071 [C] QUIT 1072 [S] 205 NNTP Service exits normally 1073 [Server closes connection.] 1075 Example of use of the MODE READER command by an authorized client 1076 that is not permitted to post; it also immediately terminates the 1077 session: 1079 [C] MODE READER 1080 [S] 201 NNTP Service Ready, posting prohibited 1081 [C] QUIT 1082 [S] 205 NNTP Service exits normally 1083 [Server closes connection.] 1085 Example of use of MODE READER by a client not authorized to receive 1086 service from the server as a news reader: 1088 [C] MODE READER 1089 [S] 502 NNTP Service permanently unavailable 1090 [Server closes connection.] 1092 Example of a connection from any client where the server is 1093 temporarily unable to provide news reader service: 1095 [C] MODE READER 1096 [S] 400 NNTP Service temporarily unavailable 1097 [Server closes connection.] 1099 5.3 LIST EXTENSIONS 1101 5.3.1 Usage 1103 This command is optional. 1105 This command MUST NOT be pipelined. 1107 Syntax 1108 LIST EXTENSIONS 1110 Responses 1111 202 Extension list follows (multiline) 1112 402 Server has no extensions 1114 5.3.2 Description 1116 The LIST EXTENSIONS command allows a client to determine which 1117 extensions are supported by the server at any given time. See Section 1118 8 for further discussion of extensions. 1120 This command MUST be implemented by any server that implements any 1121 extensions defined in this document or any other extension in the 1122 IANA registry, and is optional otherwise. 1124 This command MAY be issued at anytime during a session. It is not 1125 required that the client issues this command before attempting to 1126 make use of any extension. The response generated by this command MAY 1127 change during a session because of other state information (which in 1128 turn may be changed by the effects of other commands). An NNTP client 1129 MUST NOT cache (for use in another session) any information returned 1130 if the LIST EXTENSIONS command succeeds. That is, an NNTP client is 1131 only able to get the current and correct information concerning 1132 available extensions at any point during a session by issuing a LIST 1133 EXTENSIONS command at that point of that session and processing the 1134 response. 1136 The list of extensions is returned as a multi-line response following 1137 the 202 response code. Each extension is listed on a separate line; 1138 the line MUST begin with an extension-label and optionally one or 1139 more parameters (separated by single spaces). The extension-label and 1140 the meaning of the parameters are specified as part of the definition 1141 of the extension. The extension-label is a string of 1 to 12 US-ASCII 1142 letters and MUST be in uppercase. Parameters are strings of 1 or more 1143 printable UTF-8 characters (that is, either printable US-ASCII 1144 characters or any UTF-8 sequence outside the US-ASCII range, but not 1145 space or TAB). 1147 The server MUST NOT list the same extension twice in the response, 1148 and MUST list all supported extensions. The order in which the 1149 extensions are listed is not significant. The server need not even 1150 consistently return the same order. If the server does not support 1151 any extensions, it MUST return an empty list. The 402 response code 1152 is documented for historic reasons only; clients SHOULD handle it 1153 gracefully, but servers MUST NOT generate it. 1155 Following a generic failure response, such as 403, an extension might 1156 still be available, and the client MAY attempt to use it. 1158 5.3.3 Examples 1160 Example of a successful response: 1162 [C] LIST EXTENSIONS 1163 [S] 202 Extensions supported: 1164 [S] OVER 1165 [S] HDR 1166 [S] LISTGROUP 1167 [S] . 1169 The particular extensions shown here are simply examples of what 1170 might be defined in other places, and no particular meaning should be 1171 attributed to them. 1173 Example where no extensions are available: 1175 [C] LIST EXTENSIONS 1176 [S] 202 Extensions supported: 1177 [S] . 1179 Example from a non-conforming server which indicates "no extensions 1180 available" using the 402 response code: 1182 [C] LIST EXTENSIONS 1183 [S] 402 Server has no extensions 1185 5.4 QUIT 1187 5.4.1 Usage 1189 Syntax 1190 QUIT 1192 Responses 1193 205 Connection closing 1195 5.4.2 Description 1197 The client uses the QUIT command to terminate the session. The server 1198 MUST acknowledge the QUIT command and then close the connection to 1199 the client. This is the preferred method for a client to indicate 1200 that it has finished all its transactions with the NNTP server. 1202 If a client simply disconnects (or the connection times out or some 1203 other fault occurs), the server MUST gracefully cease its attempts to 1204 service the client, disconnecting from its end if necessary. 1206 5.4.3 Examples 1208 [C] QUIT 1209 [S] 205 closing connection 1210 [Server closes connection.] 1212 6. Article posting and retrieval 1214 News reading clients have available a variety of mechanisms to 1215 retrieve articles via NNTP. The news articles are stored and indexed 1216 using three types of keys. One key is the message-id of an article. 1217 Another key is composed of the newsgroup name and the article number 1218 within that newsgroup. That key MUST be unique to a particular server 1219 (there will be only one article with that number within a particular 1220 newsgroup), but is not required to be globally unique. Additionally, 1221 because the same article can be cross-posted to multiple newsgroups, 1222 there may be multiple keys that point to the same article on the same 1223 server. The final key is the arrival timestamp, giving the time that 1224 the article arrived at the server. 1226 The server MUST ensure that article numbers are issued in order of 1227 arrival timestamp; that is, articles arriving later MUST have higher 1228 numbers than those that arrive earlier. The server SHOULD allocate 1229 the next sequential unused number to each new article. 1231 Article numbers MUST lie between 1 and 4,294,967,295 inclusive. The 1232 client and server SHOULD NOT use leading zeroes in specifying article 1233 numbers, and MUST NOT use more than 16 digits. In some situations, 1234 the value zero replaces an article number to show some special 1235 situation. 1237 6.1 Group and article selection 1239 The following commands are used to set the "current selected 1240 newsgroup" and the "current article number", which are used by 1241 various commands. At the start of an NNTP session, both of these 1242 values are set to the special value "invalid". 1244 6.1.1 GROUP 1246 6.1.1.1 Usage 1248 Syntax 1249 GROUP group 1251 Responses 1252 211 number low high group Group successfully selected 1253 411 No such newsgroup 1255 Parameters 1256 group = name of newsgroup 1257 number = estimated number of articles in the group 1258 low = reported low water mark 1259 high = reported high water mark 1261 6.1.1.2 Description 1263 The required parameter is the name of the newsgroup to be selected 1264 (e.g. "news.software.b"). A list of valid newsgroups may be obtained 1265 by using the LIST ACTIVE command (see Section 7.6.1). 1267 The successful selection response will return the article numbers of 1268 the first and last articles in the group at the moment of selection 1269 (these numbers are referred to as the "reported low water mark" and 1270 the "reported high water mark"), and an estimate of the number of 1271 articles on file in the group. 1273 If the group is not empty, the estimate MUST be at least the actual 1274 number of articles available, and MUST be no greater than one more 1275 than the difference between the reported low and high water marks. 1276 (Some implementations will actually count the number of articles on 1277 file. Others will just subtract the low water mark from the high 1278 water mark and add one to get an estimate.) 1280 If the group is empty, one of the following three situations will 1281 occur. Clients MUST accept all three cases; servers MUST NOT 1282 represent an empty group in any other way. 1284 o The high water mark will be one less than the low water mark, and 1285 the estimated article count will be zero. Servers SHOULD use this 1286 method to show an empty group. This is the only time that the high 1287 water mark can be less than the low water mark. 1289 o All three numbers will be zero. 1291 o The high water mark is greater than or equal to the low water 1292 mark. The estimated article count might be zero or non-zero; if 1293 non-zero, the same requirements apply as for a non-empty group. 1295 The set of articles in a group may change after the GROUP command is 1296 carried out. That is: 1298 o articles may be removed from the group 1300 o articles may be reinstated in the group with the same article 1301 number, but those articles MUST have numbers no less than the 1302 reported low water mark (note that this is a reinstatement of the 1303 previous article, not a new article reusing the number) 1305 o new articles may be added with article numbers greater than the 1306 reported high water mark (if an article that was the one with the 1307 highest number has been removed, the next new article will not 1308 have the number one greater than the reported high water mark) 1310 Except when the group is empty and all three numbers are zero, 1311 whenever a subsequent GROUP command for the same newsgroup is issued, 1312 either by the same client or a different client, the reported low 1313 water mark in the response MUST be no less than that in any previous 1314 response for that newsgroup sent to any client. The client may make 1315 use of the low water mark to remove all remembered information about 1316 articles with lower numbers, as these will never recur. This includes 1317 the situation when the high water mark is one less than the low water 1318 mark. No similar assumption can be made about the high water mark, as 1319 this can decrease if an article is removed, and then increase again 1320 if it is reinstated or if new articles arrive. 1322 When a valid group is selected by means of this command, the current 1323 selected newsgroup MUST be set to that group and the current article 1324 number MUST be set to the first article in the group. If an empty 1325 newsgroup is selected, the current article pointer is made invalid. 1326 If an invalid group is specified, the current selected newsgroup and 1327 current article number MUST NOT be changed. 1329 The GROUP command (or the LISTGROUP command, if implemented) MUST be 1330 used by a client and a successful response received before any other 1331 command is used that depends on the value of the current selected 1332 newsgroup or current article number. 1334 If the group specified is not available on the server, a 411 response 1335 MUST be returned. 1337 6.1.1.3 Examples 1339 Example for a group known to the server: 1341 [C] GROUP misc.test 1342 [S] 211 1234 3000234 3002322 misc.test 1344 Example for a group unknown to the server: 1346 [C] GROUP example.is.sob.bradner.or.barber 1347 [S] 411 example.is.sob.bradner.or.barber is unknown 1349 Example of an empty group using the preferred response: 1351 [C] GROUP example.currently.empty.newsgroup 1352 [S] 211 0 4000 3999 example.currently.empty.newsgroup 1354 Example of an empty group using an alternative response: 1356 [C] GROUP example.currently.empty.newsgroup 1357 [S] 211 0 0 0 example.currently.empty.newsgroup 1359 Example of an empty group using a different alternative response: 1361 [C] GROUP example.currently.empty.newsgroup 1362 [S] 211 0 4000 4321 example.currently.empty.newsgroup 1364 6.1.2 LAST 1366 6.1.2.1 Usage 1368 Syntax 1369 LAST 1371 Responses 1372 223 n message-id Article found 1373 412 No newsgroup selected 1374 420 Current article number is invalid 1375 422 No previous article in this group 1377 Parameters 1378 n = article number 1379 message-id = article message-id 1381 6.1.2.2 Description 1383 If the current selected newsgroup is valid, the current article 1384 number MUST be set to the previous article in that newsgroup (that 1385 is, the highest existing article number less than the current article 1386 number). If successful, a response indicating the new current article 1387 number and the message-id of that article MUST be returned. No 1388 article text is sent in response to this command. 1390 There MAY be no previous article in the group, although the current 1391 article number is not the reported low water mark. There MUST NOT be 1392 a previous article when the current article number is the reported 1393 low water mark. 1395 Because articles can be removed and added, the results of multiple 1396 LAST and NEXT commands MAY not be consistent over the life of a 1397 particular NNTP session. 1399 If the current article number is already the first article of the 1400 newsgroup, a 422 response MUST be returned. If the current article 1401 number is invalid, a 420 response MUST be returned. If the current 1402 selected newsgroup is invalid, a 412 response MUST be returned. In 1403 all three cases the current selected newsgroup and current article 1404 number MUST NOT be altered. 1406 6.1.2.3 Examples 1408 Example of a successful article retrieval using LAST: 1410 [C] GROUP misc.test 1411 [S] 211 1234 3000234 3002322 misc.test 1412 [C] NEXT 1413 [S] 223 3000237 <668929@example.org> retrieved 1414 [C] LAST 1415 [S] 223 3000234 <45223423@example.com> retrieved 1417 Example of an attempt to retrieve an article without having selected 1418 a group (via the GROUP command) first: 1420 [Assumes current selected newsgroup is invalid.] 1421 [C] LAST 1422 [S] 412 no newsgroup selected 1424 Example of an attempt to retrieve an article using the LAST command 1425 when the current article number is that of the first article in the 1426 group: 1428 [C] GROUP misc.test 1429 [S] 211 1234 3000234 3002322 misc.test 1430 [C] LAST 1431 [S] 422 No previous article to retrieve 1433 Example of an attempt to retrieve an article using the LAST command 1434 when the current selected newsgroup is empty: 1436 [C] GROUP example.empty.newsgroup 1437 [S] 211 0 0 0 example.empty.newsgroup 1438 [C] LAST 1439 [S] 420 No current article selected 1441 6.1.3 NEXT 1443 6.1.3.1 Usage 1445 Syntax 1446 NEXT 1448 Responses 1449 223 n message-id Article found 1450 412 No newsgroup selected 1451 420 Current article number is invalid 1452 421 No next article in this group 1454 Parameters 1455 n = article number 1456 message-id = article message-id 1458 6.1.3.2 Description 1460 If the current selected newsgroup is valid, the current article 1461 number MUST be set to the next article in that newsgroup (that is, 1462 the lowest existing article number greater than the current article 1463 number). If successful, a response indicating the new current article 1464 number and the message-id of that article MUST be returned. No 1465 article text is sent in response to this command. 1467 If the current article number is already the last article of the 1468 newsgroup, a 421 response MUST be returned. In all other aspects 1469 (apart, of course, from the lack of 422 response) this command is 1470 identical to the LAST command (Section 6.1.2). 1472 6.1.3.3 Examples 1474 Example of a successful article retrieval using NEXT: 1476 [C] GROUP misc.test 1477 [S] 211 1234 3000234 3002322 misc.test 1478 [C] NEXT 1479 [S] 223 3000237 <668929@example.org> retrieved 1481 Example of an attempt to retrieve an article without having selected 1482 a group (via the GROUP command) first: 1484 [Assumes current selected newsgroup is invalid.] 1485 [C] NEXT 1486 [S] 412 no newsgroup selected 1488 Example of an attempt to retrieve an article using the NEXT command 1489 when the current article number is that of the last article in the 1490 group: 1492 [C] GROUP misc.test 1493 [S] 211 1234 3000234 3002322 misc.test 1494 [C] STAT 3002322 1495 [S] 223 3002322 <411@example.net> retrieved 1496 [C] NEXT 1497 [S] 421 No next article to retrieve 1499 Example of an attempt to retrieve an article using the NEXT command 1500 when the current selected newsgroup is empty: 1502 [C] GROUP example.empty.newsgroup 1503 [S] 211 0 0 0 example.empty.newsgroup 1504 [C] NEXT 1505 [S] 420 No current article selected 1507 6.2 Retrieval of articles and article sections 1509 The ARTICLE, BODY, HEAD, and STAT commands are very similar. They 1510 differ only in the parts of the article that are presented to the 1511 client and in the successful response code. The ARTICLE command is 1512 described here in full, while the other commands are described in 1513 terms of the differences. As specified in Section 3.4, an article 1514 consists of two parts: the article headers and the article body. When 1515 responding to one of these commands, the server MUST present the 1516 entire article or appropriate part and MUST NOT attempt to alter or 1517 translate it in any way. 1519 6.2.1 ARTICLE 1521 6.2.1.1 Usage 1523 Syntax 1524 ARTICLE message-id 1525 ARTICLE [number] 1527 Responses 1529 First form (message-id specified) 1530 220 0 message-id Article follows (multiline) 1531 430 No article found with that message-id 1533 Second form (optional article number specified) 1534 220 n message-id Article follows (multiline) 1535 412 No newsgroup selected 1536 420 Current article number is invalid [1] 1537 423 No such article in this newsgroup 1539 Parameters 1540 number = Requested article number 1541 n = Returned article number 1542 message-id = Article message-id 1544 [1] The 420 response can only occur if no article number has been 1545 specified. 1547 6.2.1.2 Description 1549 The ARTICLE command selects an article based on the arguments and 1550 presents the entire article (that is, the headers, an empty line, and 1551 the body in that order). The command has two forms. 1553 In the first form, a message-id is specified (including the angle 1554 brackets), and the server presents the article with that message-id. 1555 In this case, the server MUST NOT alter the current selected 1556 newsgroup or current article number. This is both to facilitate the 1557 presentation of articles that may be referenced within another 1558 article being read, and because of the semantic difficulties of 1559 determining the proper sequence and membership of an article that may 1560 have been crossposted to more than one newsgroup. 1562 In the response, the article number is replaced with zero (that is, 1563 the server is not required to determine whether the article is in the 1564 current group or what article number(s) it has). 1566 In the second form, an article number may be specified. If so, and if 1567 there is an article with that number in the currently selected 1568 newsgroup, the server MUST set the current article number to that 1569 number. 1571 Then, whether or not a number was specified, the article indicated by 1572 the current article number is presented to the client. 1574 Note that a previously valid article number MAY become invalid if the 1575 article has been removed. A previously invalid article number MAY 1576 become valid if the article has been reinstated, but such an article 1577 number MUST be no less than the reported low water mark for that 1578 group. 1580 The server MUST NOT change the current selected newsgroup as a result 1581 of this command. The server MUST NOT change the current article 1582 number except when an article number argument was provided and the 1583 article exists; in particular, it MUST NOT change it following an 1584 unsuccessful response. 1586 Since the message-id is unique for each article, it may be used by a 1587 client to skip duplicate displays of articles that have been posted 1588 more than once, or to more than one newsgroup. 1590 The article is returned as a multi-line response following the 220 1591 response code. 1593 If the current article number is invalid, a 420 response MUST be 1594 returned. If there is no article with the specified number, a 423 1595 response MUST be returned. If the current selected newsgroup is 1596 invalid, a 412 response MUST be returned. 1598 6.2.1.3 Examples 1600 Example of a successful retrieval of an article (using no article 1601 number): 1603 [C] GROUP misc.test 1604 [S] 211 1234 3000234 3002322 misc.test 1605 [C] ARTICLE 1606 [S] 220 3000234 <45223423@example.com> 1607 [S] Path: pathost!demo!whitehouse!not-for-mail 1608 [S] From: "Demo User" 1609 [S] Newsgroups: misc.test 1610 [S] Subject: I am just a test article 1611 [S] Date: 6 Oct 1998 04:38:40 -0500 1612 [S] Organization: An Example Net, Uncertain, Texas 1613 [S] Message-ID: <411@example.net> 1614 [S] 1615 [S] This is just a test article. 1616 [S] . 1618 Example of a successful retrieval of an article by message-id: 1620 [C] ARTICLE <45223423@example.com> 1621 [S] 220 0 <45223423@example.com> 1622 [S] Path: pathost!demo!whitehouse!not-for-mail 1623 [S] From: "Demo User" 1624 [S] Newsgroups: misc.test 1625 [S] Subject: I am just a test article 1626 [S] Date: 6 Oct 1998 04:38:40 -0500 1627 [S] Organization: An Example Net, Uncertain, Texas 1628 [S] Message-ID: <411@example.net> 1629 [S] 1630 [S] This is just a test article. 1631 [S] . 1633 Example of an unsuccessful retrieval of an article by message-id: 1635 [C] ARTICLE 1636 [S] 430 No Such Article Found 1638 Example of an unsuccessful retrieval of an article by number: 1640 [C] GROUP misc.test 1641 [S] 211 1234 3000234 3002322 news.groups 1642 [C] ARTICLE 300256 1644 [S] 423 No such article number in this group 1646 Example of an unsuccessful retrieval of an article by number because 1647 no newsgroup was selected first: 1649 [Assumes current selected newsgroup is invalid.] 1650 [C] ARTICLE 300256 1651 [S] 412 No newsgroup selected 1653 Example of an attempt to retrieve an article when the current 1654 selected newsgroup is empty: 1656 [C] GROUP example.empty.newsgroup 1657 [S] 211 0 0 0 example.empty.newsgroup 1658 [C] ARTICLE 1659 [S] 420 No current article selected 1661 6.2.2 HEAD 1663 6.2.2.1 Usage 1665 Syntax 1666 HEAD message-id 1667 HEAD [number] 1669 Responses 1671 First form (message-id specified) 1672 221 0 message-id Headers follow (multiline) 1673 430 No article found with that message-id 1675 Second form (optional article number specified) 1676 221 n message-id Headers follow (multiline) 1677 412 No newsgroup selected 1678 420 Current article number is invalid [1] 1679 423 No such article in this newsgroup 1681 Parameters 1682 number = Requested article number 1683 n = Returned article number 1684 message-id = Article message-id 1686 [1] The 420 response can only occur if no article number has been 1687 specified. 1689 6.2.2.2 Description 1691 The HEAD command behaves identically to the ARTICLE command except 1692 that, if the article exists, the response code is 221 instead of 220 1693 and only the headers are presented (the empty line separating the 1694 headers and body MUST NOT be included). 1696 6.2.2.3 Examples 1698 Example of a successful retrieval of the headers of an article (using 1699 no article number): 1701 [C] GROUP misc.test 1702 [S] 211 1234 3000234 3002322 misc.test 1703 [C] HEAD 1704 [S] 221 3000234 <45223423@example.com> 1705 [S] Path: pathost!demo!whitehouse!not-for-mail 1706 [S] From: "Demo User" 1707 [S] Newsgroups: misc.test 1708 [S] Subject: I am just a test article 1709 [S] Date: 6 Oct 1998 04:38:40 -0500 1710 [S] Organization: An Example Net, Uncertain, Texas 1711 [S] Message-ID: <411@example.net> 1712 [S] . 1714 Example of a successful retrieval of the headers of an article by 1715 message-id: 1717 [C] HEAD <45223423@example.com> 1718 [S] 221 0 <45223423@example.com> 1719 [S] Path: pathost!demo!whitehouse!not-for-mail 1720 [S] From: "Demo User" 1721 [S] Newsgroups: misc.test 1722 [S] Subject: I am just a test article 1723 [S] Date: 6 Oct 1998 04:38:40 -0500 1724 [S] Organization: An Example Net, Uncertain, Texas 1725 [S] Message-ID: <411@example.net> 1726 [S] . 1728 Example of an unsuccessful retrieval of the headers of an article by 1729 message-id: 1731 [C] HEAD 1732 [S] 430 No Such Article Found 1734 Example of an unsuccessful retrieval of the headers of an article by 1735 number: 1737 [C] GROUP misc.test 1738 [S] 211 1234 3000234 3002322 misc.test 1739 [C] HEAD 300256 1740 [S] 423 No such article number in this group 1742 Example of an unsuccessful retrieval the headers of an article by 1743 number because no newsgroup was selected first: 1745 [Assumes current selected newsgroup is invalid.] 1746 [C] HEAD 300256 1747 [S] 412 No newsgroup selected 1749 Example of an attempt to retrieve the headers of an article when the 1750 current selected newsgroup is empty: 1752 [C] GROUP example.empty.newsgroup 1753 [S] 211 0 0 0 example.empty.newsgroup 1754 [C] HEAD 1755 [S] 420 No current article selected 1757 6.2.3 BODY 1759 6.2.3.1 Usage 1761 Syntax 1762 BODY message-id 1763 BODY [number] 1765 Responses 1767 First form (message-id specified) 1768 222 0 message-id Body follows (multiline) 1769 430 No article found with that message-id 1771 Second form (optional article number specified) 1772 222 n message-id Body follows (multiline) 1773 412 No newsgroup selected 1774 420 Current article number is invalid [1] 1775 423 No such article in this newsgroup 1777 Parameters 1778 number = Requested article number 1779 n = Returned article number 1780 message-id = Article message-id 1782 [1] The 420 response can only occur if no article number has been 1783 specified. 1785 6.2.3.2 Description 1787 The BODY command behaves identically to the ARTICLE command except 1788 that, if the article exists, the response code is 222 instead of 220 1789 and only the body is presented (the empty line separating the headers 1790 and body MUST NOT be included). 1792 6.2.3.3 Examples 1794 Example of a successful retrieval of the body of an article (using no 1795 article number): 1797 [C] GROUP misc.test 1798 [S] 211 1234 3000234 3002322 misc.test 1799 [C] BODY 1800 [S] 222 3000234 <45223423@example.com> 1801 [S] This is just a test article. 1802 [S] . 1804 Example of a successful retrieval of the body of an article by 1805 message-id: 1807 [C] BODY <45223423@example.com> 1808 [S] 222 0 <45223423@example.com> 1809 [S] This is just a test article. 1810 [S] . 1812 Example of an unsuccessful retrieval of the body of an article by 1813 message-id: 1815 [C] BODY 1816 [S] 430 No Such Article Found 1818 Example of an unsuccessful retrieval of the body of an article by 1819 number: 1821 [C] GROUP misc.test 1822 [S] 211 1234 3000234 3002322 misc.test 1823 [C] BODY 300256 1824 [S] 423 No such article number in this group 1826 Example of an unsuccessful retrieval of the body of an article by 1827 number because no newsgroup was selected first: 1829 [Assumes current selected newsgroup is invalid.] 1830 [C] BODY 300256 1831 [S] 412 No newsgroup selected 1833 Example of an attempt to retrieve the body of an article when the 1834 current selected newsgroup is empty: 1836 [C] GROUP example.empty.newsgroup 1837 [S] 211 0 0 0 example.empty.newsgroup 1838 [C] BODY 1839 [S] 420 No current article selected 1841 6.2.4 STAT 1843 6.2.4.1 Usage 1845 Syntax 1846 STAT message-id 1847 STAT [number] 1849 Responses 1851 First form (message-id specified) 1852 223 0 message-id Article exists 1853 430 No article found with that message-id 1855 Second form (optional article number specified) 1856 223 n message-id Article exists 1857 412 No newsgroup selected 1858 420 Current article number is invalid [1] 1859 423 No such article in this newsgroup 1861 Parameters 1862 number = Requested article number 1863 n = Returned article number 1864 message-id = Article message-id 1866 [1] The 420 response can only occur if no article number has been 1867 specified. 1869 6.2.4.2 Description 1871 The STAT command behaves identically to the ARTICLE command except 1872 that, if the article exists, it is NOT presented to the client and 1873 the response code is 223 instead of 220. Note that the response is 1874 NOT multi-line. 1876 This command allows the client to determine whether an article 1877 exists, and in the second form what its message-id is, without having 1878 to process an arbitrary amount of text. 1880 6.2.4.3 Examples 1882 Example of STAT on an existing article (using no article number): 1884 [C] GROUP misc.test 1885 [S] 211 1234 3000234 3002322 misc.test 1886 [C] STAT 1887 [S] 223 3000234 <45223423@example.com> 1889 Example of a STAT of an existing article by message-id: 1891 [C] STAT <45223423@example.com> 1892 [S] 223 0 <45223423@example.com> 1894 Example of an STAT of an article not on the server by message-id: 1896 [C] STAT 1897 [S] 430 No Such Article Found 1899 Example of STAT of an article not in the server by number: 1901 [C] GROUP misc.test 1902 [S] 211 1234 3000234 3002322 misc.test 1903 [C] STAT 300256 1904 [S] 423 No such article number in this group 1906 Example of STAT of an article by number when no newsgroup was 1907 selected first: 1909 [Assumes current selected newsgroup is invalid.] 1910 [C] STAT 300256 1911 [S] 412 No newsgroup selected 1913 Example of STAT of an article when the current selected newsgroup is 1914 empty: 1916 [C] GROUP example.empty.newsgroup 1917 [S] 211 0 0 0 example.empty.newsgroup 1918 [C] STAT 1919 [S] 420 No current article selected 1921 6.3 Article posting 1923 Article posting is done in one of two modes: individual article 1924 posting from news reading clients using POST, and article transfer 1925 from other news servers using IHAVE. 1927 6.3.1 POST 1929 6.3.1.1 Usage 1931 This command MUST NOT be pipelined. 1933 Syntax 1934 POST 1936 Responses 1938 Initial responses 1939 340 Send article to be posted 1940 440 Posting not permitted 1942 Subsequent responses 1943 240 Article received OK 1944 441 Posting failed 1946 6.3.1.2 Description 1948 If posting is allowed, a 340 response MUST be returned to indicate 1949 that the article to be posted should be sent. If posting is 1950 prohibited for some installation-dependent reason, a 440 response 1951 MUST be returned. 1953 If posting is permitted, the article MUST be in the format specified 1954 in Section 3.4 and MUST be sent by the client to the server in the 1955 manner specified in (Section 3.1) for multi-line responses (except 1956 that there is no initial line containing a response code). Thus a 1957 single dot (".") on a line indicates the end of the text, and lines 1958 starting with a dot in the original text have that dot doubled during 1959 transmission. 1961 Following the presentation of the termination sequence by the client, 1962 the server MUST return a response indicating success or failure of 1963 the article transfer. Note that response codes 340 and 440 are used 1964 in direct response to the POST command. Others are returned following 1965 the sending of the article. 1967 A response of 240 SHOULD indicate that, barring unforseen server 1968 errors, the posted article will be made available on the server and/ 1969 or transferred to other servers as appropriate. In other words, 1970 articles not wanted by the server SHOULD be rejected with a 441 1971 response and not accepted and silently discarded. 1973 No attempt shall be made by the server to filter characters, fold or 1974 limit lines, or otherwise process incoming text. The intent is that 1975 the server just passes the incoming message to be posted to the 1976 server installation's news posting software, which is not defined by 1977 this document. 1979 The client SHOULD NOT assume that the article has been successfully 1980 transferred unless it receives an affirmative response from the 1981 server. If the session is interrupted before the response is 1982 received, it is possible that an affirmative response was sent but 1983 has been lost. Therefore, in any subsequent session, the client 1984 SHOULD either check whether the article was successfully posted 1985 before resending or, if the client supplied a message-id in the 1986 original article, ensure it supplies the same message-id - the latter 1987 approach is preferred since the article might not have been made 1988 available for reading yet (for example, it may have to go through a 1989 moderation process). In particular, if the article contained a header 1990 with name "Message-ID", the client SHOULD ensure that the contents of 1991 this header are identical when resending it and the server SHOULD 1992 ensure that the re-sent article is recognised as a duplicate and not 1993 assigned a different message-id to the original. 1995 6.3.1.3 Examples 1997 Example of a successful posting: 1999 [C] POST 2000 [S] 340 Input article; end with . 2001 [C] From: "Demo User" 2002 [C] Newsgroups: misc.test 2003 [C] Subject: I am just a test article 2004 [C] Organization: An Example Net 2005 [C] 2006 [C] This is just a test article. 2007 [C] . 2008 [S] 240 Article received OK 2010 Example of an unsuccessful posting: 2012 [C] POST 2013 [S] 340 Input article; end with . 2014 [C] From: "Demo User" 2015 [C] Newsgroups: misc.test 2017 [C] Subject: I am just a test article 2018 [C] Organization: An Example Net 2019 [C] 2020 [C] This is just a test article. 2021 [C] . 2022 [S] 441 Posting failed 2024 Example of an attempt to post when posting is not allowed: 2026 [C] MODE READER 2027 [S] 201 NNTP Service Ready, posting prohibited 2028 [C] POST 2029 [S] 440 Posting not permitted 2031 6.3.2 IHAVE 2033 6.3.2.1 Usage 2035 This command MUST NOT be pipelined. 2037 Syntax 2038 IHAVE message-id 2040 Responses 2042 Initial responses 2043 335 Send article to be transferred 2044 435 Article not wanted 2045 436 Transfer not possible; try again later 2047 Subsequent responses 2048 235 Article transferred OK 2049 436 Transfer failed; try again later 2050 437 Transfer rejected; do not retry 2052 Parameters 2053 message-id = Article message-id 2055 6.3.2.2 Description 2057 The IHAVE command informs the server that the client has an article 2058 with the specified message-id. If the server desires a copy of that 2059 article a 335 response MUST be returned, instructing the client to 2060 send the entire article. If the server does not want the article (if, 2061 for example, the server already has a copy of it), a 435 response 2062 MUST be returned, indicating that the article is not wanted. Finally, 2063 if the article isn't wanted immediately but the client should retry 2064 later if possible (if, for example, another client is in the process 2065 of sending the same article to the server), a 436 response MUST be 2066 returned. 2068 If transmission of the article is requested, the client MUST send the 2069 entire article, including headers and body, in the format defined 2070 above (Section 3.1) for multi-line responses (except that there is no 2071 initial line containing a response code). Thus a single dot (".") on 2072 a line indicates the end of the text, and lines starting with a dot 2073 in the original text have that dot doubled during transmission. The 2074 server MUST return either a 235 response, indicating that the article 2075 was successfully transferred, a 436 response, indicating that the 2076 transfer failed but should be tried again later, or a 437 response, 2077 indicating that the article was rejected. 2079 This function differs from the POST command in that it is intended 2080 for use in transferring already-posted articles between hosts. It 2081 SHOULD NOT be used when the client is a personal news reading 2082 program, since use of this command indicates that the article has 2083 already been posted at another site and is simply being forwarded 2084 from another host. However, despite this, the server MAY elect not to 2085 post or forward the article if, after further examination of the 2086 article, it deems it inappropriate to do so. Reasons for such 2087 subsequent rejection of an article may include such problems as 2088 inappropriate newsgroups or distributions, disc space limitations, 2089 article lengths, garbled headers, and the like. These are typically 2090 restrictions enforced by the server host's news software and not 2091 necessarily the NNTP server itself. 2093 The client SHOULD NOT assume that the article has been successfully 2094 transferred unless it receives an affirmative response from the 2095 server. A lack of response (such as a dropped network connection or a 2096 network timeout) SHOULD be treated the same as a 436 response. 2098 Because some news server software may not be able immediately to 2099 determine whether or not an article is suitable for posting or 2100 forwarding, an NNTP server MAY acknowledge the successful transfer of 2101 the article (with a 235 response) but later silently discard it. 2103 6.3.2.3 Examples 2105 Example of successfully sending an article to another site: 2107 [C] IHAVE 2108 [S] 335 Send it; end with . 2109 [C] Path: pathost!demo!somewhere!not-for-mail 2110 [C] From: "Demo User" 2112 [C] Newsgroups: misc.test 2113 [C] Subject: I am just a test article 2114 [C] Date: 6 Oct 1998 04:38:40 -0500 2115 [C] Organization: An Example Com, San Jose, CA 2116 [C] Message-ID: 2117 [C] 2118 [C] This is just a test article. 2119 [C] . 2120 [S] 235 Article transferred OK 2122 Example of sending an article to another site that rejects it: 2124 [C] IHAVE 2125 [S] 335 Send it; end with . 2126 [C] Path: pathost!demo!somewhere!not-for-mail 2127 [C] From: "Demo User" 2128 [C] Newsgroups: misc.test 2129 [C] Subject: I am just a test article 2130 [C] Date: 6 Oct 1998 04:38:40 -0500 2131 [C] Organization: An Example Com, San Jose, CA 2132 [C] Message-ID: 2133 [C] 2134 [C] This is just a test article. 2135 [C] . 2136 [S] 437 Article rejected; don't send again 2138 Example of sending an article to another site where the transfer 2139 fails: 2141 [C] IHAVE 2142 [S] 335 Send it; end with . 2143 [C] Path: pathost!demo!somewhere!not-for-mail 2144 [C] From: "Demo User" 2145 [C] Newsgroups: misc.test 2146 [C] Subject: I am just a test article 2147 [C] Date: 6 Oct 1998 04:38:40 -0500 2148 [C] Organization: An Example Com, San Jose, CA 2149 [C] Message-ID: 2150 [C] 2151 [C] This is just a test article. 2152 [C] . 2153 [S] 436 Transfer failed 2155 Example of sending an article to a site that already has it: 2157 [C] IHAVE 2158 [S] 435 Duplicate 2160 Example of sending an article to a site that requests the article be 2161 tried again later: 2163 [C] IHAVE 2164 [S] 436 Retry later 2166 7. Information commands 2168 This section lists other commands that may be used at any time 2169 between the beginning of a session and its termination. Using these 2170 commands does not alter any state information, but the response 2171 generated from their use may provide useful information to clients. 2173 7.1 DATE 2175 7.1.1 Usage 2177 Syntax 2178 DATE 2180 Responses 2181 111 yyyymmddhhmmss server date and time 2183 Parameters 2184 yyyymmddHHmmss = Current UTC date and time on server 2186 7.1.2 Description 2188 This command exists to help clients find out the current Coordinated 2189 Universal Time [TF.686-1] from the server's perspective. This command 2190 SHOULD NOT be used as a substitute for NTP [RFC1305] but to provide 2191 information that might be useful when using the NEWNEWS command (see 2192 Section 7.4). A system providing NNTP service SHOULD keep the system 2193 clock as accurate as possible, either with NTP or by some other 2194 method. 2196 The server MUST return a 111 response specifying the date and time on 2197 the server in the form yyyymmddhhmmss. This date and time is in 2198 Coordinated Universal Time. 2200 7.1.3 Examples 2202 [C] DATE 2203 [S] 111 19990623135624 2205 7.2 HELP 2207 7.2.1 Usage 2208 Syntax 2209 HELP 2211 Responses 2212 100 Help text follows (multiline) 2214 7.2.2 Description 2216 This command provides a short summary of commands that are understood 2217 by this implementation of the server. The help text will be presented 2218 as a multiline response following the 100 response code. 2220 This text is not guaranteed to be in any particular format and MUST 2221 NOT be used by clients as a replacement for the LIST EXTENSIONS 2222 command described in Section 5.3 2224 7.2.3 Examples 2226 [C] HELP 2227 [S] 100 Help text follows 2228 [S] This is some help text. There is no specific 2229 [S] formatting requirement for this test, though 2230 [S] it is customary for it to list the valid commands 2231 [S] and give a brief definition of what they do 2232 [S] . 2234 7.3 NEWGROUPS 2236 7.3.1 Usage 2238 Syntax 2239 NEWGROUPS date time [GMT] 2241 Responses 2242 231 List of new newsgroups follows (multiline) 2244 Parameters 2245 date = Date in yymmdd or yyyymmdd format 2246 time = Time in hhmmss format 2248 7.3.2 Description 2250 This command returns a list of newsgroups created on the server since 2251 the specified date and time. The results are in the same format as 2252 the LIST ACTIVE command (see Section 7.6.1). However, they MAY 2253 include groups not available on the server (and so not returned by 2254 LIST ACTIVE) and MAY omit groups for which the creation date is not 2255 available. The results SHOULD be consistent with those of the LIST 2256 ACTIVE.TIMES command (Section 7.6.2), except that if the specified 2257 date and time is earlier than the oldest entry in the latter then the 2258 results of this command may include extra groups. 2260 The date is specified as 6 or 8 digits in the format [xx]yymmdd, 2261 where xx is the first two digits of the year (19-99), yy is the last 2262 two digits of the year (00-99), mm is the month (01-12), and dd is 2263 the day of the month (01-31). Clients SHOULD specify all four digits 2264 of the year. If the first two digits of the year are not specified 2265 (this is supported only for backwards compatibility), the year is to 2266 be taken from the current century if yy is smaller than or equal to 2267 the current year, otherwise the year is from the previous century. 2269 The time is specified as 6 digits in the format hhmmss, where hh is 2270 the hours in the 24-hour clock (00-23), mm is the minutes (00-59), 2271 and ss is the seconds (00-60, to allow for leap seconds). The token 2272 "GMT" specifies that the date and time are given in Coordinated 2273 Universal Time [TF.686-1]; if it is omitted then the date and time 2274 are specified in the server's local timezone. Note that there is no 2275 way using the protocol specified in this document to establish the 2276 server's local timezone. 2278 Note that an empty list is a possible valid response and indicates 2279 that there are no new newsgroups since that date-time. 2281 Clients SHOULD make all queries using Coordinated Universal Time 2282 (i.e. by including the "GMT" parameter) when possible. 2284 7.3.3 Examples 2286 Example where there are new groups: 2288 [C] NEWGROUPS 19990624 000000 GMT 2289 [S] 231 list of new newsgroups follows 2290 [S] alt.fc-writers.recovery 4 1 y 2291 [S] tx.natives.recovery 89 56 y 2292 [S] . 2294 Example where there are no new groups: 2296 [C] NEWGROUPS 19990624 000000 GMT 2297 [S] 231 list of new newsgroups follows 2298 [S] . 2300 7.4 NEWNEWS 2302 7.4.1 Usage 2304 Syntax 2305 NEWNEWS wildmat date time [GMT] 2307 Responses 2308 230 List of new articles follows (multiline) 2310 Parameters 2311 wildmat = Newsgroups of interest 2312 date = Date in yymmdd or yyyymmdd format 2313 time = Time in hhmmss format 2315 7.4.2 Description 2317 This command returns a list of message-ids of articles posted or 2318 received on the server, in the newsgroups whose names match the 2319 wildmat, since the specified date and time. One message-id is sent on 2320 each line; the order of the response has no specific significance and 2321 may vary from response to response in the same session. A message-id 2322 MAY appear more than once; if it does so, it has the same meaning as 2323 if it appeared only once. 2325 Date and time are in the same format as the NEWGROUPS command (see 2326 Section 7.3). 2328 Note that an empty list is a possible valid response and indicates 2329 that there is currently no new news in the relevant groups. 2331 Clients SHOULD make all queries in Coordinated Universal Time (i.e. 2332 by using the "GMT" parameter) when possible. 2334 7.4.3 Examples 2336 Example where there are new articles: 2338 [C] NEWNEWS news.*,sci.* 19990624 000000 GMT 2339 [S] 230 list of new articles by message-id follows 2340 [S] 2341 [S] 2342 [S] . 2344 Example where there are no new articles: 2346 [C] NEWNEWS alt.* 19990624 000000 GMT 2348 [S] 230 list of new articles by message-id follows 2349 [S] . 2351 7.5 Time 2353 As described in Section 6, each article has an arrival timestamp. 2354 Each newsgroup also has a creation timestamp. These timestamps are 2355 used by the NEWNEWS and NEWGROUP commands to construct their 2356 reponses. 2358 The DATE command MUST return a timestamp from the same clock as is 2359 used for determining article arrival and group creation times. This 2360 clock SHOULD be monotonic, and adjustments SHOULD be made by running 2361 it fast or slow compared to "real" time rather than by making sudden 2362 jumps. 2364 Clients can ensure that they do not have gaps in lists of articles or 2365 groups by using the DATE command in the following manner: 2367 First session: 2368 Issue DATE command and record result 2369 Issue NEWNEWS command using a previously chosen timestamp 2371 Subsequent sessions: 2372 Issue DATE command and hold result in temporary storage 2373 Issue NEWNEWS command using timestamp saved from previous session 2374 Overwrite saved timestamp with that currently in temporary storage 2376 In order to allow for minor errors, clients MAY want to adjust the 2377 timestamp back by two or three minutes before using it in NEWNEWS. 2379 7.5.1 Examples 2381 First session: 2383 [C] DATE 2384 [S] 111 20010203112233 2385 [C] NEWNEWS local.chat 20001231 235959 GMT 2386 [S] 230 list follows 2387 [S] 2388 [S] 2389 [S] 2390 [S] . 2392 Second session (the client has subtracted 3 minutes from the 2393 timestamp returned previously): 2395 [C] DATE 2396 [S] 111 20010204003344 2397 [C] NEWNEWS local.chat 20010203 111933 GMT 2398 [S] 230 list follows 2399 [S] 2400 [S] 2401 [S] 2402 [S] . 2404 Note how arrived in the 3 minute gap and so 2405 is listed in both responses. 2407 7.6 The LIST commands 2409 7.6.1 LIST ACTIVE 2411 7.6.1.1 Usage 2413 Syntax 2414 LIST ACTIVE [wildmat] 2416 Responses 2417 215 Information follows (multiline) 2419 Parameters 2420 wildmat = groups of interest 2422 7.6.1.2 Description 2424 The LIST ACTIVE command with no parameters returns a list of valid 2425 newsgroups and associated information. The server MUST include every 2426 group that the client is permitted to select with the GROUP (Section 2427 6.1.1) command. Each newsgroup is sent as a line of text in the 2428 following format: 2430 group high low status 2432 where: 2434 "group" is the name of the newsgroup; 2436 "high" is the reported high water mark for the group; 2438 "low" is the reported low water mark for the group; 2439 "status" is the current status of the group on this server. 2441 Each field in the line is separated from its neighboring fields by 2442 one or more spaces. Note that an empty list is a possible valid 2443 response, and indicates that there are currently no valid newsgroups. 2445 The reported high and low water marks are as described in the GROUP 2446 command (see Section 6.1.1). 2448 The status field is typically one of: 2450 "y" posting is permitted 2452 "n" posting is not permitted 2454 "m" postings will be forwarded to the newsgroup moderator 2456 The server SHOULD use these values when these meanings are required 2457 and MUST NOT use them with any other meaning. Other values for the 2458 status may exist; the definition of these other values and the 2459 circumstances under which they are returned may be specified in an 2460 extension or may be private to the server. A client SHOULD treat an 2461 unrecognised status as giving no information. 2463 The status of a newsgroup only indicates how posts to that newsgroup 2464 are normally processed and is not necessarily customised to the 2465 specific client. For example, if the current client is forbidden from 2466 posting, then this will apply equally to groups with status "y". 2467 Conversely, a client with special privileges (not defined by this 2468 specification) might be able to post to a group with status "n". 2470 If the optional wildmat parameter is specified, the list is limited 2471 to only the groups whose names match the wildmat. If no wildmat is 2472 specified, the keyword ACTIVE MAY be omitted without altering the 2473 effect of the command. 2475 7.6.1.3 Examples 2477 Example of LIST ACTIVE returning a list of newsgroups: 2479 [C] LIST ACTIVE 2480 [S] 215 list of newsgroups follows 2481 [S] misc.test 3002322 3000234 y 2482 [S] comp.risks 442001 441099 m 2483 [S] alt.fc-writers.recovery 4 1 y 2484 [S] tx.natives.recovery 89 56 y 2485 [S] tx.natives.recovery.d 11 9 n 2486 [S] . 2488 Example of LIST ACTIVE omitting the second keyword and returning no 2489 newsgroups: 2491 [C] LIST 2492 [S] 215 list of newsgroups follows 2493 [S] . 2495 Example of LIST ACTIVE with a wildmat: 2497 [C] LIST ACTIVE *.recovery 2498 [S] 215 list of newsgroups follows 2499 [S] alt.fc-writers.recovery 4 1 y 2500 [S] tx.natives.recovery 89 56 y 2501 [S] . 2503 7.6.2 LIST ACTIVE.TIMES 2505 7.6.2.1 Usage 2507 This command is optional. 2509 Syntax 2510 LIST ACTIVE.TIMES [wildmat] 2512 Responses 2513 215 Information follows (multiline) 2515 Parameters 2516 wildmat = groups of interest 2518 7.6.2.2 Description 2520 The active.times file is maintained by some news transport systems to 2521 contain information about who created a particular newsgroup and 2522 when. Each line of this file consists of three fields separated from 2523 each other by one or more spaces. The first field is the name of the 2524 newsgroup. The second is the time when this group was created on this 2525 news server, measured in seconds since the start of January 1, 1970. 2526 The third is the email address of the entity that created the 2527 newsgroup, and must be a mailbox as defined in RFC 2822 [RFC2822]. 2529 OUTSTANDING ISSUE 2531 Should the third field simply be free-form, or should it be 2532 recommended usage rather than mandatory? The problem with 2533 "mailbox" is that mailbox requires that it be fully qualified, and 2534 unqualified addresses are apparently very common for groups 2535 created directly by the administrator. 2537 The file MAY omit newsgroups for which the information is unavailable 2538 and MAY include groups not available on the server; in particular, 2539 the file MAY omit all groups created before the date and time of the 2540 oldest entry. The client MUST NOT assume that the list is complete or 2541 that it matches the list returned by LIST ACTIVE. The NEWGROUPS 2542 command (Section 7.3) may provide a better way to access this 2543 information and the results of the two commands SHOULD be consistent 2544 (subject to the caveats in the description of that command). 2546 If the information is available, it is returned as a multi-line 2547 response following the 215 response code. 2549 If the optional wildmat parameter is specified, the list is limited 2550 to only the groups in the file whose names match the wildmat. Note 2551 that an empty list is a possible valid response, and indicates that 2552 there are no groups in the file, or that match the wildmat. 2554 7.6.2.3 Examples 2556 Example of LIST ACTIVE.TIMES returning a list of newsgroups: 2558 [C] LIST ACTIVE.TIMES 2559 [S] 215 information follows 2560 [S] misc.test 930445408 2561 [S] alt.rfc-writers.recovery 930562309 2562 [S] tx.natives.recovery 930678923 2563 [S] . 2565 Example of LIST ACTIVE.TIMES returning an error where the command is 2566 recognised but the software does not maintain this information: 2568 [C] LIST ACTIVE.TIMES 2569 [S] 503 program error, function not performed 2571 Example of LIST ACTIVE.TIMES sent to a server that does not recognize 2572 this command: 2574 [C] LIST ACTIVE.TIMES 2575 [S] 501 Syntax Error 2577 7.6.3 LIST DISTRIBUTIONS 2578 7.6.3.1 Usage 2580 This command is optional. 2582 Syntax 2583 LIST DISTRIBUTIONS 2585 Responses 2586 215 Information follows (multiline) 2588 7.6.3.2 Description 2590 The distributions file is maintained by some news transport systems 2591 to contain information about valid values for the content of the 2592 Distribution header in a news article and about what the various 2593 values mean. Each line of this file consists of two fields separated 2594 from each other by one or more spaces. The first field is a value and 2595 the second is a short explanation of the meaning of that value. 2597 If the information is available, it is returned as a multi-line 2598 response following the 215 response code. 2600 7.6.3.3 Examples 2602 Example of LIST DISTRIBUTIONS returning a list of distributions: 2604 [C] LIST DISTRIBUTIONS 2605 [S] 215 information follows 2606 [S] usa United States of America 2607 [S] na North America 2608 [S] world All over the World 2609 [S] . 2611 Example of LIST DISTRIBUTIONS returning an error where the command is 2612 recognised but the software does not maintain this information: 2614 [C] LIST DISTRIBUTIONS 2615 [S] 503 program error, function not performed 2617 Example of LIST DISTRIBUTIONS sent to a server that does not 2618 recognize this command: 2620 [C] LIST DISTRIBUTIONS 2621 [S] 501 Syntax Error 2623 7.6.4 LIST DISTRIB.PATS 2625 7.6.4.1 Usage 2627 This command is optional. 2629 Syntax 2630 LIST DISTRIB.PATS 2632 Responses 2633 215 Information follows (multiline) 2635 7.6.4.2 Description 2637 The distrib.pats file is maintained by some news transport systems to 2638 choose a value for the content of the Distribution header of a news 2639 article being posted. Each line of this file consists of three fields 2640 separated from each other by a colon (":"). The first field is a 2641 weight, the second field is a wildmat (which may be a simple group 2642 name), and the third field is a value for the Distribution header 2643 content. 2645 The client MAY use this information to construct an appropriate 2646 Distribution header given the name of a newsgroup. To do so, it 2647 should determine the lines whose second field matches the newsgroup 2648 name, select from among them the line with the highest weight (with 0 2649 being the lowest), and use the value of the third field to construct 2650 the Distribution header. 2652 If the information is available, it is returned as a multi-line 2653 response following the 215 response code. 2655 7.6.4.3 Examples 2657 Example of LIST DISTRIB.PATS returning a list of newsgroups: 2659 [C] LIST DISTRIB.PATS 2660 [S] 215 information follows 2661 [S] 10:local.*:local 2662 [S] 5:*:world 2663 [S] 20:local.here.*:thissite 2664 [S] . 2666 Example of LIST DISTRIB.PATS returning an error where the command is 2667 recognised but the software does not maintain this information: 2669 [C] LIST DISTRIB.PATS 2671 [S] 503 program error, function not performed 2673 Example of LIST DISTRIB.PATS sent to a server that does not recognize 2674 this command: 2676 [C] LIST DISTRIB.PATS 2677 [S] 501 Syntax Error 2679 7.6.5 LIST NEWSGROUPS 2681 7.6.5.1 Usage 2683 This command is optional. 2685 Syntax 2686 LIST NEWSGROUPS [wildmat] 2688 Responses 2689 215 Information follows (multiline) 2691 Parameters 2692 wildmat = groups of interest 2694 7.6.5.2 Description 2696 The newsgroups file is maintained by some news transport systems to 2697 contain the name of each newsgroup that is available on the server 2698 and a short description about the purpose of the group. Each line of 2699 this file consists of two fields separated from each other by one or 2700 more space or TAB characters (usual practice is a single TAB). The 2701 first field is the name of the newsgroup and the second is a short 2702 description of the group. Note that an empty list is a possible valid 2703 response, and indicates that there are currently no valid newsgroups. 2705 The file MAY omit newsgroups for which the information is unavailable 2706 and MAY include groups not available on the server. The client MUST 2707 NOT assume that the list is complete or that it matches the list 2708 returned by LIST ACTIVE. 2710 If the information is available, it is returned as a multi-line 2711 response following the 215 response code. 2713 If the optional wildmat parameter is specified, the list is limited 2714 to only the groups in the file whose names match the wildmat. Note 2715 that an empty list is a possible valid response, and indicates that 2716 there are no groups in the file, or that match the wildmat. 2718 7.6.5.3 Examples 2720 Example of LIST NEWSGROUPS returning a list of newsgroups: 2722 [C] LIST NEWSGROUPS 2723 [S] 215 information follows 2724 [S] misc.test General Usenet testing 2725 [S] alt.rfc-writers.recovery RFC Writers Recovery 2726 [S] tx.natives.recovery Texas Natives Recovery 2727 [S] . 2729 Example of LIST NEWSGROUPS returning an error where the command is 2730 recognised but the software does not maintain this information: 2732 [C] LIST NEWSGROUPS 2733 [S] 503 program error, function not performed 2735 Example of LIST NEWSGROUPS sent to a server that does not recognize 2736 this command: 2738 [C] LIST NEWSGROUPS 2739 [S] 501 Syntax error 2741 8. Framework for NNTP extensions 2743 Although NNTP is widely and robustly deployed, some parts of the 2744 Internet community might wish to extend the NNTP service. This 2745 document defines a means whereby an extended NNTP client can query 2746 the server to determine the service extensions that it supports. 2748 It must be emphasized that any extension to the NNTP service should 2749 not be considered lightly. NNTP's strength comes primarily from its 2750 simplicity. Experience with many protocols has shown that: 2752 Protocols with few options tend towards ubiquity, whilst protocols 2753 with many options tend towards obscurity. 2755 This means that each and every extension, regardless of its benefits, 2756 must be carefully scrutinized with respect to its implementation, 2757 deployment, and interoperability costs. In many cases, the cost of 2758 extending the NNTP service will likely outweigh the benefit. 2760 Given this environment, the framework for extensions described in 2761 this document consists of: 2763 o a mechanism for clients to determine a server's available 2764 extensions 2766 o a registry of NNTP service extensions 2768 The LIST EXTENSIONS command is described in this document (see 2769 Section 5.3) and is the mechanism for clients to use to determine 2770 what extensions are available. 2772 The IANA shall maintain a registry of NNTP service extensions. 2774 An extension is identified by a unique extension-label, which is a 2775 string of 1 to 12 uppercase US-ASCII letters. The extension-label 2776 will often be the name of a new command that the extension adds. 2777 However this is not a requirement: an extension might not add any new 2778 commands or keywords. 2780 An extension is either a private extension or else it is included in 2781 the IANA registry and is defined in an RFC. Such RFCs either must be 2782 on the standards-track or must define an IESG-approved experimental 2783 protocol. 2785 The definition of an extension must include: 2787 o a descriptive name for the extension 2788 o the extension-label (which is returned by LIST EXTENSIONS to 2789 indicate to the client that the server supports this particular 2790 extension) 2792 o the syntax, values, and meanings of any parameters following the 2793 extension-label in the output of LIST EXTENSIONS 2795 o any new NNTP commands associated with the extension 2797 o the syntax and possible values of parameters associated with the 2798 new NNTP commands 2800 o the response codes and possible values of parameters for the 2801 responses of the new NNTP commands 2803 o any new parameters the extension associates with any other 2804 pre-existing NNTP commands 2806 o how support for the extension affects the behavior of a server and 2807 NNTP client 2809 o any increase in the maximum length of commands over the value 2810 specified in this document 2812 o a specific statement about the effect on pipelining this extension 2813 may have (if any) 2815 The extension-label of private extensions MUST begin with "X". The 2816 extension-label of registered extensions MUST NOT begin with "X". 2818 A server MUST NOT provide any extension, whether or not listed in the 2819 output from LIST EXTENSIONS, unless it is either a registered 2820 extension or a private extension. 2822 OUTSTANDING ISSUE 2824 As worded, this forbids commands like MODE SLAVE that servers 2825 already provide but that aren't part of an existing extension. We 2826 can't simply make these illegal. 2828 The wording about starting keywords with an X could be reduced to 2829 a SHOULD, except for backwards compatibility (with a pointer to 2830 RFC 2980). But is that the right answer? 2832 Except where stated otherwise, the commands in this document are 2833 understood (even if not supported) by all servers and are not 2834 described in the list of features returned by the LIST EXTENSIONS 2835 command. 2837 A server MAY provide additional keywords - either for new commands or 2838 new variants of existing commands - as part of a private extension. 2839 These new keywords MUST begin with "X". 2841 A server MUST NOT send different response codes to basic NNTP 2842 commands documented here or commands documented in registered 2843 extensions in response to the availability or use of a private 2844 extension. 2846 8.1 Initial IANA registry 2848 The IANA's initial registry of NNTP service extensions consists of 2849 these entries: 2851 Extension Label Added behavior 2852 Specific article numbers LISTGROUP Defined in this document 2853 Overview support OVER Defined in this document 2854 Header pattern matching HDR Defined in this document 2856 8.2 Standard extensions 2858 Each of the following sections describes an extension that a server 2859 MAY provide. If the server provides the extension, it MUST include 2860 the appropriate extension label in the response to LIST EXTENSIONS. 2861 If it does not provide it, it MUST NOT include the appropriate 2862 extension label. The descriptions of facilities in each section are 2863 written as if the extension is provided. If it is not provided, the 2864 entire section should be ignored. 2866 If the server provides an extension, it MUST implement all of the 2867 commands in the specification of the extension except for those 2868 marked as optional. If it does not provide an extension, it MUST NOT 2869 implement any of the commands in the specification of that extension. 2871 8.3 The LISTGROUP extension 2873 This extension provides one command and has the extension label 2874 LISTGROUP. 2876 8.3.1 LISTGROUP 2878 8.3.1.1 Usage 2880 Syntax 2881 LISTGROUP [group] 2883 Responses 2884 211 number low high group Article numbers follow (multiline) 2885 411 No such newsgroup 2886 412 No newsgroup selected [1] 2888 Parameters 2889 group = name of newsgroup 2890 number = estimated number of articles in the group 2891 low = reported low water mark 2892 high = reported high water mark 2894 [1] The 412 response can only occur if no group has been specified. 2896 8.3.1.2 Description 2898 The LISTGROUP command is used to get a listing of all the article 2899 numbers in a particular newsgroup. 2901 The optional parameter is the name of the newsgroup to be selected 2902 (e.g. "news.software.misc"). A list of valid newsgroups may be 2903 obtained from the LIST ACTIVE command. If no group is specified, the 2904 current selected newsgroup is used. 2906 The list of article numbers is returned as a multi-line response 2907 following the 211 response code (the parameters on the initial 2908 response line are the same as for the GROUP command (see Section 2909 6.1.1). The list contains one number per line, is in numerical order, 2910 and lists precisely those articles that exist in the group. 2912 When a valid group is selected by means of this command, the current 2913 selected newsgroup MUST be set to that group and the current article 2914 number MUST be set to the first article in the group. If an empty 2915 newsgroup is selected, the current article pointer is made invalid. 2916 If an invalid group is specified, the current selected newsgroup and 2917 current article number MUST NOT be changed. 2919 The LISTGROUP command MAY be used by a client as a replacement for 2920 the GROUP command in establishing a valid current selected newsgroup 2921 and current article number. 2923 If the group specified is not available on the server, a 411 response 2924 MUST be returned. If no group is specified and the current selected 2925 newsgroup is invalid, a 412 response MUST be returned. 2927 8.3.1.3 Examples 2929 Example of LISTGROUP on an empty group: 2931 [C] LISTGROUP example.empty.newsgroup 2932 [S] 211 0 0 0 example.empty.newsgroup list follows 2933 [S] . 2935 Example of LISTGROUP on a valid current selected newsgroup: 2937 [C] GROUP misc.test 2938 [S] 211 2000 3000234 3002322 misc.test 2939 [C] LISTGROUP 2940 [S] 211 2000 3000234 3002322 misc.test list follows 2941 [S] 3000234 2942 [S] 3000237 2943 [S] 3000238 2944 [S] 3000239 2945 [S] 3002322 2946 [S] . 2948 Example of LISTGROUP failing because no group has been selected: 2950 [Assumes current selected newsgroup is invalid.] 2951 [C] LISTGROUP 2952 [S] 412 no current group 2953 [C] GROUP example.is.sob.bradner.or.barber 2954 [S] 411 no such group 2955 [C] LISTGROUP 2956 [S] 412 no current group 2958 8.4 Article metadata 2960 The OVER and HDR extensions refer to the concept of "article 2961 metadata". This is data about articles that does not occur within the 2962 article itself. Each metadata item has a name which MUST begin with a 2963 colon (and which MUST NOT contain a colon elsewhere within it). 2965 When generating a metadata item, the server MUST compute it for 2966 itself and MUST NOT trust any related value provided in the article. 2967 (In particular, a Lines or Bytes header in the article MUST NOT be 2968 assumed to specify the correct number of lines or bytes in the 2969 article.) 2971 This specification defines two metadata items: ":bytes" and ":lines". 2972 Implementations and other extensions may define other metadata items. 2974 OUTSTANDING ISSUE 2976 Do we need a separate private namespace? For example, we could 2977 reserve :name for extensions and ::name for implementation use. 2979 8.4.1 The :bytes metadata item 2981 The :bytes metadata item for an article is a decimal integer. It MUST 2982 equal the number of octets in the entire article - headers, body, and 2983 separating empty line - except that each CRLF pair MAY (but SHOULD 2984 NOT) be counted as a single octet. 2986 OUTSTANDING ISSUE 2988 Should this be called ":octets" instead? 2990 8.4.2 The :lines metadata item 2992 The :lines metadata item for an article is a decimal integer. It MUST 2993 equal the number of lines in the article body (excluding the empty 2994 line separating headers and body); equivalently, it is two less than 2995 the number of CRLF pairs that the BODY command would return for that 2996 article (the extra two are those following the response code and the 2997 termination octet). 2999 8.5 The OVER extension 3001 This extension provides two commands, OVER and LIST OVERVIEW.FMT. The 3002 label for this extension is OVER. 3004 The OVER extension provides access to the "overview database", which 3005 is a database of headers extracted from incoming articles. Only 3006 certain headers are included in the database. The database also 3007 includes some article metadata. The information stored in the 3008 database may change over time. The LIST OVERVIEW.FMT command 3009 describes the information that would be stored for an article 3010 arriving at the same time as the command was executed. 3012 This extension is based on the Overview/NOV database [ROBE1995] 3013 developed by Geoff Collyer. 3015 8.5.1 OVER 3017 8.5.1.1 Usage 3019 Syntax 3020 OVER [range] 3022 Responses 3023 224 Overview information follows (multiline) 3024 412 No newsgroup selected 3025 420 Current article number is invalid 3026 423 No articles in that range 3028 Parameters 3029 range = Article(s) to return information for 3031 8.5.1.2 Description 3033 The OVER command returns the contents of the headers and metadata in 3034 the database for the article(s) specified from the current selected 3035 newsgroup. 3037 The optional range argument may be any of the following: 3039 o an article number 3041 o an article number followed by a dash to indicate all following 3043 o an article number followed by a dash followed by another article 3044 number 3046 If no argument is specified, then the current article number is used. 3048 If the information is available, it is returned as a multi-line 3049 response following the 224 response code. If the current selected 3050 newsgroup is invalid, a 412 response MUST be returned. If there are 3051 no articles in the range specified, a 423 response MUST be returned. 3052 If OVER is sent without any arguments and the current article number 3053 is invalid, a 420 response MUST be returned. 3055 For a successful response, the output consists of one line per 3056 article, sorted in numerical order of article number. Each line 3057 consists of a number of fields separated by a TAB. A field may be 3058 empty (in which case there will be two adjacent TABs), and a sequence 3059 of trailing TABs may be omitted. 3061 The first 8 fields MUST be the following, in order: 3063 article number 3064 Subject header content 3065 From header content 3066 Date header content 3067 Message-ID header content 3068 References header content 3069 :bytes metadata item 3070 :lines metadata item 3072 Any subsequent fields are the contents of the other headers and 3073 metadata held in the database. 3075 For the five mandatory headers, the content of each field MUST be 3076 based on the content of the header (that is, with the header name and 3077 following colon and space removed). If the article does not contain 3078 that header, or if the content is empty, the field MUST be empty. For 3079 the two mandatory metadata items, the content of the field MUST be 3080 just the value, with no other text. 3082 For all subsequent fields that contain headers, the content MUST be 3083 the entire header line other than the trailing CRLF. For all 3084 subsequent fields that contain metadata, the field consists of the 3085 metadata name, a single space, and then the value. 3087 For all fields, the value is processed by first removing all CRLF 3088 pairs (that is, undoing any folding and removing the terminating 3089 CRLF) and then replacing each TAB with a single space. If there is no 3090 such header in the article, or no such metadata item, or no header or 3091 item stored in the database for that article, the corresponding field 3092 MUST be empty. 3094 Note that, after unfolding, the characters NUL, LF, and CR cannot 3095 occur in the header of an article offered by a conformant server. 3096 Nevertheless, servers SHOULD check for these characters and replace 3097 each one by a single space (so that, for example, CR LF LF TAB will 3098 become two spaces, since the CR and first LF will be removed by the 3099 unfolding process). This will encourage robustness in the face of 3100 non-conforming data; it is also possible that future versions of this 3101 specification may permit these characters to appear in articles. 3103 The server SHOULD NOT produce output for articles that no longer 3104 exist. 3106 8.5.1.3 Examples 3108 In the first two examples, TAB has been replaced by vertical bar and 3109 some lines have been folded for readability. 3111 Example of a successful retrieval of overview information for an 3112 article (using no article number): 3114 [C] GROUP misc.test 3115 [S] 211 1234 3000234 3002322 misc.test 3116 [C] OVER 3117 [S] 224 Overview information follows 3118 [S] 300234|I am just a test article|"Demo User" 3119 |6 Oct 1998 04:38:40 -0500| 3120 <45223423@example.com>|<45454@example.net>|1234| 3121 17|Xref: news.example.com misc.test:3000363 3122 [S] . 3124 Example of a successful retrieval of overview information for a range 3125 of articles: 3127 [C] GROUP misc.test 3128 [S] 211 1234 3000234 3002322 misc.test 3129 [C] OVER 3000234-3000240 3130 [S] 224 Overview information follows 3131 [S] 300234|I am just a test article|"Demo User" 3132 |6 Oct 1998 04:38:40 -0500| 3133 <45223423@example.com>|<45454@example.net>|1234| 3134 17|Xref: news.example.com misc.test:3000363 3135 [S] 3000235|Another test article|nobody@nowhere.to 3136 (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>|| 3137 4818|37||Distribution: fi 3138 [S] 3000238|Re: I am just a test article|somebody@elsewhere.to| 3139 7 Oct 1998 11:38:40 +1200|| 3140 <45223423@to.to>|9234|51 3141 [S] . 3143 Note the missing "References" and Xref headers in the second line, 3144 the missing trailing field(s) in the first and last lines, and that 3145 there are only results for those articles that still exist. 3147 Example of an unsuccessful retrieval of overview information on an 3148 article by number: 3150 [C] GROUP misc.test 3151 [S] 211 1234 3000234 3002322 misc.test 3152 [C] OVER 300256 3153 [S] 420 No such article in this group 3155 Example of an unsuccessful retrieval of overview information by 3156 number because no newsgroup was selected first: 3158 [Assumes current selected newsgroup is invalid.] 3159 [C] OVER 3160 [S] 412 No newsgroup selected 3162 Example of an attempt to retrieve information when the current 3163 selected newsgroup is empty: 3165 [C] GROUP example.empty.newsgroup 3166 [S] 211 0 0 0 example.empty.newsgroup 3167 [C] OVER 3168 [S] 420 No current article selected 3170 8.5.2 LIST OVERVIEW.FMT 3172 8.5.2.1 Usage 3174 Syntax 3175 LIST OVERVIEW.FMT 3177 Responses 3178 215 Information follows (multiline) 3180 8.5.2.2 Description 3182 OUTSTANDING ISSUE 3184 Should this be optional even when the OVER extension is provided? 3185 Or even just removed entirely? What do we want to require about 3186 the OVER contents being consistent with the output of this 3187 command? 3189 The LIST OVERVIEW.FMT command returns a description of the fields in 3190 the database. The fields MUST be listed in the order that they will 3191 be returned by the OVER command for a newly-received article (the 3192 information stored for articles may change over time). 3194 If the information is available, it is returned as a multi-line 3195 response following the 215 response code. The information contains 3196 one line per field in the order they are returned by the OVER 3197 command; the first 7 lines MUST be exactly: 3199 Subject: 3200 From: 3201 Date: 3202 Message-ID: 3203 References: 3204 :bytes 3205 :lines 3207 except that, for compatibility with existing implementations, the 3208 last two lines MAY instead be: 3210 Bytes: 3211 Lines: 3213 even though they refer to metadata, not headers. 3215 All subsequent lines MUST consist of either a header name followed by 3216 ":full", or the name of a piece of metadata. 3218 There are no leading or trailing spaces in the output. 3220 Note that the 7 fixed lines describe the 2nd to 8th fields of the 3221 OVER output. The "full" suffix is a reminder that the corresponding 3222 fields include the header name. 3224 This command MAY generate different results if used more than once in 3225 a session. 3227 8.5.2.3 Examples 3229 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3230 output above, using the preferred format: 3232 [C] LIST OVERVIEW.FMT 3233 [S] 215 Order of fields in overview database. 3234 [S] Subject: 3235 [S] From: 3236 [S] Date: 3237 [S] Message-ID: 3238 [S] References: 3239 [S] :bytes 3240 [S] :lines 3241 [S] Xref:full 3242 [S] Distribution:full 3243 [S] . 3245 Example of LIST OVERVIEW.FMT output corresponding to the example OVER 3246 output above, using the alternative format: 3248 [C] LIST OVERVIEW.FMT 3249 [S] 215 Order of fields in overview database. 3250 [S] Subject: 3251 [S] From: 3252 [S] Date: 3253 [S] Message-ID: 3254 [S] References: 3255 [S] Bytes: 3256 [S] Lines: 3257 [S] Xref:full 3258 [S] Distribution:full 3259 [S] . 3261 Example of LIST OVERVIEW.FMT returning an error: 3263 [C] LIST OVERVIEW.FMT 3264 [S] 503 overview.fmt not available 3266 8.6 The HDR extension 3268 This extension provides one new command: HDR. The label for this 3269 extension is HDR. 3271 OUTSTANDING ISSUE 3273 There is ongoing discussion about whether this extension should 3274 have a parameter and, if so, what it means. 3276 8.6.1 HDR 3278 8.6.1.1 Usage 3280 Syntax 3281 HDR header range 3282 HDR header message-id 3283 HDR header 3285 Responses 3287 First form (range specified) 3288 225 Headers follow (multiline) 3289 412 No newsgroup selected 3290 423 No articles in that range 3292 Second form (message-id specified) 3293 225 Headers follow (multiline) 3294 430 No article with that message-id 3296 Third form (current article number used) 3297 225 Headers follow (multiline) 3298 412 No newsgroup selected 3299 420 Current article number is invalid 3301 Parameters 3302 header = name of header, without the colon 3303 range = number(s) of articles 3304 message-id = message-id of article 3306 8.6.1.2 Description 3308 The HDR command retrieves specific headers from an article or 3309 specified range of articles in the current selected newsgroup, or 3310 from an article specified by message-id. It can also return certain 3311 metadata about the article or articles. 3313 The required header parameter is the name of a header (e.g. 3314 "subject") in an article, or the name of a metadata item, and is 3315 case-insensitive. Names of metadata items always begin with a colon. 3316 Except where stated otherwise, metadata items are treated as if they 3317 were header contents, and references to headers in this description 3318 apply equally to metadata items. 3320 The range parameter may be any of the following: 3322 o an article number 3324 o an article number followed by a dash to indicate all following 3326 o an article number followed by a dash followed by another article 3327 number 3329 The message-id argument indicates a specific article. As shown by the 3330 syntax, the range and message-id arguments are mutually exclusive; if 3331 neither is specified, the current article number is used. 3333 If the information is available, it is returned as a multi-line 3334 response following the 225 response code and contains one line for 3335 each article where the relevant header line exists. The line consists 3336 of the article number, a space, and then the contents of the header 3337 (without the header name or the colon and space that follow it) or 3338 metadata item. If the article is specified by message-id rather than 3339 by article range, the article number is given as "0". 3341 Header contents are modified as follows: all CRLF pairs are removed, 3342 and then each TAB is replaced with a single space (note that this is 3343 the same transformation as is performed by the OVER extension 3344 (Section 8.5.1.2), and the same comment concerning NUL, CR, and LF 3345 applies). 3347 The header content is in all cases taken from the article. This means 3348 that, for example, a request for the header "Lines" returns the 3349 contents of the "Lines" header of the specified articles, if any, not 3350 the line count metadata or any other server-generated value. If the 3351 header occurs in a given article multiple times, only the content of 3352 the first occurrence is returned by HDR. 3354 If the requested header is not present in the article or if it is 3355 present but empty, a line for that article is included in the output 3356 but the header content portion of the line is empty (the space after 3357 the article number MAY be retained or omitted). If any article number 3358 in the provided range does not exist in the group, no line for that 3359 article number is included in the output. 3361 If the optional argument is a message-id and no such article exists, 3362 a 430 response MUST be returned. If the optional argument is not a 3363 message-id and the current selected newsgroup is invalid, a 412 3364 response MUST be returned. If the optional argument is an article 3365 number or number range and no article with that number or in that 3366 number range exists in the current selected newsgroup, a 423 response 3367 MUST be returned. If HDR is sent without any arguments and the 3368 current article number is invalid, a 420 response MUST be returned. 3370 A server MAY only allow HDR commands for a limited set of headers and 3371 metadata items (such as those present in the overview database). If 3372 so, it MUST respond with a 503 response to attempts to request other 3373 headers, rather than returning erroneous results such as a successful 3374 empty response. 3376 8.6.1.3 Examples 3378 Example of a successful retrieval of subject lines from a range of 3379 articles (3000235 has no Subject header, and 3000236 is missing): 3381 [C] GROUP misc.test 3382 [S] 211 1234 3000234 3002322 misc.test 3383 [C] HDR Subject 3000234-300238 3384 [S] 225 Headers follow 3385 [S] 3000234 I am just a test article 3386 [S] 3000235 3387 [S] 3000237 Re: I am just a test article 3388 [S] 3000238 Ditto 3389 [S] . 3391 Example of a successful retrieval of line counts from a range of 3392 articles: 3394 [C] GROUP misc.test 3395 [S] 211 1234 3000234 3002322 misc.test 3396 [C] HDR :lines 3000234-300238 3397 [S] 225 Headers follow 3398 [S] 3000234 42 3399 [S] 3000235 5 3400 [S] 3000237 11 3401 [S] 3000238 2378 3402 [S] . 3404 Example of a successful retrieval of the subject line from an article 3405 by message-id: 3407 [C] GROUP misc.test 3408 [S] 211 1234 3000234 3002322 misc.test 3410 [C] HDR subject 3411 [S] 225 Header information follows 3412 [S] 0 I am just a test article 3413 [S] . 3415 Example of a successful retrieval of the subject line from the 3416 current article: 3418 [C] GROUP misc.test 3419 [S] 211 1234 3000234 3002322 misc.test 3420 [C] HDR subject 3421 [S] 225 Header information follows 3422 [S] 3000234 I am just a test article 3423 [S] . 3425 Example of an unsuccessful retrieval of a header from an article by 3426 message-id: 3428 [C] HDR subject 3429 [S] 430 No Such Article Found 3431 Example of an unsuccessful retrieval of headers from articles by 3432 number because no newsgroup was selected first: 3434 [Assumes current selected newsgroup is invalid.] 3435 [C] HDR subject 300256- 3436 [S] 412 No newsgroup selected 3438 Example of an unsuccessful retrieval of headers because the current 3439 selected newsgroup is empty: 3441 [C] GROUP example.empty.newsgroup 3442 [S] 211 0 0 0 example.empty.newsgroup 3443 [C] HDR subject 1- 3444 [S] 423 No articles in that range 3446 Example of an unsuccessful retrieval of headers because the server 3447 does not allow HDR commands for that header: 3449 [C] GROUP misc.test 3450 [S] 211 1234 3000234 3002322 misc.test 3451 [C] HDR Content-Type 3000234-300238 3452 [S] 503 HDR not permitted on Content-Type 3454 9. Augmented BNF Syntax for NNTP 3456 Each of the following sections describes the syntax of a major 3457 element of NNTP. This syntax extends and refines the descriptions 3458 elsewhere in this specification, and should be given precedence when 3459 resolving apparent conflicts. Note that ABNF [RFC2234] strings are 3460 case insensitive. Non-terminals used in several places are defined in 3461 a separate section at the end. 3463 9.1 Commands 3465 This syntax defines the non-terminal "command-line", which 3466 represents what is sent from the client to the server. 3468 command-line = command EOL 3469 command = article-command / 3470 body-command / 3471 date-command / 3472 group-command / 3473 hdr-command / 3474 head-command / 3475 help-command / 3476 ihave-command / 3477 last-command / 3478 list-active-command / 3479 list-active-times-command / 3480 list-distrib-pats-command / 3481 list-distributions-command / 3482 list-extensions-command / 3483 list-newsgroups-command / 3484 list-overview-fmt-command / 3485 listgroup-command / 3486 mode-reader-command / 3487 newgroups-command / 3488 newnews-command / 3489 next-command / 3490 over-command / 3491 post-command / 3492 quit-command / 3493 stat-command / 3494 x-command 3496 article-command = "ARTICLE" [article-ref] 3497 body-command = "BODY" [article-ref] 3498 date-command = "DATE" 3499 group-command = "GROUP" WS newsgroup-name 3500 hdr-command = "HDR" WS header-meta-name [range-ref] 3501 head-command = "HEAD" [article-ref] 3502 help-command = "HELP" 3503 ihave-command = "IHAVE" WS message-id 3504 last-command = "LAST" 3505 list-active-command = "LIST" [WS "ACTIVE" [WS wildmat]] 3506 list-active-times-command = "LIST" WS "ACTIVE.TIMES" [WS wildmat] 3507 list-distrib-pats-command = "LIST" WS "DISTRIB.PATS" 3508 list-distributions-command = "LIST" WS "DISTRIBUTIONS" 3509 list-extensions-command = "LIST" WS "EXTENSIONS" 3510 list-newsgroups-command = "LIST" WS "NEWSGROUPS" [WS wildmat] 3511 list-overview-fmt-command = "LIST" WS "OVERVIEW.FMT" 3512 listgroup-command = "LISTGROUP" [WS newsgroup-name] 3513 mode-reader-command = "MODE" WS "READER" 3514 newgroups-command = "NEWGROUPS" WS date-time 3515 newnews-command = "NEWNEWS" WS wildmat WS date-time 3516 next-command = "NEXT" 3517 over-command = "OVER" [WS range] 3518 post-command = "POST" 3519 quit-command = "QUIT" 3520 stat-command = "STAT" [article-ref] 3521 x-command = x-command-name *(WS x-argument) 3522 ; Each extension command is specified fully elsewhere 3524 article-ref = WS (article-number / message-id) 3525 article-number = 1*16DIGIT 3526 date = [2DIGIT] 6DIGIT 3527 date-time = date WS time [WS "GMT"] 3528 header-meta-name = header-name / metadata-name 3529 metadata-name = ":" 1*A-NOTCOLON 3530 newsgroup-name = 1*wildmat-exact 3531 range = article-number ["-" [article-number]] 3532 range-ref = WS (range / message-id) 3533 time = 6DIGIT 3534 x-command-name = 3*12A-CHAR 3535 x-argument = 1*P-CHAR 3537 wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) 3538 wildmat-pattern = 1*wildmat-item 3539 wildmat-item = wildmat-exact / wildmat-wild 3540 wildmat-exact = %x21-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / 3541 UTF8-non-ascii ; exclude * , ? [ \ ] 3542 wildmat-wild = "*" / "?" 3544 9.2 Responses 3546 This syntax defines the non-terminal "response", which represents 3547 what is sent from the server to the client in response to a command. 3549 response = simple-response / multiline-response 3550 multiline-response = simple-response *content-line termination 3551 termination = "." CRLF 3552 content-line = [content-text] CRLF 3553 content-text = (".." / B-NONDOT) B-CHAR 3555 simple-response = 3DIGIT parameters [ SP trailing-comment ] CRLF 3556 trailing-comment = *U-CHAR 3557 parameters = *( SP parameter ) ; How many depends on the response 3558 parameter = 1*A-CHAR 3560 9.3 Articles 3562 This syntax defines the non-terminal "article", which represents the 3563 format of an article as described in Section 3.4. 3565 article = 1*header CRLF body 3566 body = *(*B-CHAR CRLF) 3567 header = header-name ":" header-tail CRLF 3568 header-tail = SP header-content-u / CRLF SP header-content-f 3569 header-content-u = *( header-gap header-text) *WS 3570 header-content-f = *WS header-text header-content-u 3571 header-gap = *WS [CRLF] 1*WS 3572 header-text = 1*P-CHAR 3574 9.4 General non-terminals 3575 header-name = 1*A-NOTCOLON 3576 message-id = "<" 1*248A-NOTGT ">" 3578 ; Assorted special character sets 3579 ; A- means based on ASCII, excluding controls and SP 3580 ; P- means based on UTF-8, excluding controls and SP 3581 ; U- means based on UTF-8, excluding NUL CR and LF 3582 ; B- means based on bytes, excluding NUL CR and LF 3583 A-CHAR = %x21-7E 3584 A-NOTCOLON = %x21-39 / %x3B-7E ; exclude ":" 3585 A-NOTGT = %x21-3D / %x3F-7E ; exclude ">" 3586 P-CHAR = A-CHAR / UTF8-non-ascii 3587 U-CHAR = %x01-09 / %x0B-0C / %x0E-7F / UTF8-non-ascii 3588 B-CHAR = %x01-09 / %x0B-0C / %x0E-FF 3589 B-NONDOT = %x01-09 / %x0B-0C / %x0E-2D / %x2F-FF ; exclude "." 3591 CR = %x0D 3592 CRLF = CR LF 3593 DIGIT = %x30-39 3594 EOL = *(SP / HT) CRLF 3595 HT = %x09 3596 LF = %x0A 3597 SP = %x20 3598 UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4 3599 UTF8-2 = %xC2-DF UTF8-tail 3600 UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail / 3601 %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail 3602 UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail / 3603 %xF4 %x80-8F 2UTF8-tail 3604 UTF8-tail = %x80-BF 3605 WS = 1*(SP / HT) 3607 OUTSTANDING ISSUE 3609 When draft-yergeau-rfc2279bis-04.txt replaces 2279, need to update 3610 references. 3612 10. IANA Considerations 3614 This specification requires IANA to keep a registry of 3615 extension-labels. The initial contents of this registry are specified 3616 in Section 8.1. As described in Section 8, names beginning with X are 3617 reserved for private use while all other names are to be associated 3618 with a specification in an RFC on the standards-track or defining an 3619 IESG-approved experimental protocol. 3621 11. Security Considerations 3623 This section is meant to inform application developers, information 3624 providers, and users of the security limitations in NNTP as described 3625 by this document. The discussion does not include definitive 3626 solutions to the problems revealed, though it does make some 3627 suggestions for reducing security risks. 3629 11.1 Personal and Proprietary Information 3631 NNTP, because it was created to distribute network news articles, 3632 will forward whatever information is stored in those articles. 3633 Specification of that information is outside this scope of this 3634 document, but it is likely that some personal and/or proprietary 3635 information is available in some of those articles. It is very 3636 important that designers and implementers provide informative 3637 warnings to users so personal and/or proprietary information in 3638 material that is added automatically to articles (e.g. in headers) is 3639 not disclosed inadvertently. Additionally, effective and easily 3640 understood mechanisms to manage the distribution of news articles 3641 SHOULD be provided to NNTP Server administrators, so that they are 3642 able to report with confidence the likely spread of any particular 3643 set of news articles. 3645 11.2 Abuse of Server Log Information 3647 A server is in the position to save session data about a user's 3648 requests that might identify their reading patterns or subjects of 3649 interest. This information is clearly confidential in nature and its 3650 handling can be constrained by law in certain countries. People using 3651 the NNTP protocol to provide data are responsible for ensuring that 3652 such material is not distributed without the permission of any 3653 individuals that are identifiable by the published results. 3655 11.3 Weak Authentication and Access Control 3657 There is no user-based or token-based authentication in the basic 3658 NNTP specification. Access is normally controlled by server 3659 configuration files. Those files specify access by using domain names 3660 or IP addresses. However, this specification does permit the creation 3661 of extensions to the NNTP protocol itself for such purposes. While 3662 including such mechanisms is optional, doing so is strongly 3663 encouraged. 3665 Other mechanisms are also available. For example, a proxy server 3666 could be put in place that requires authentication before connecting 3667 via the proxy to the NNTP server. 3669 11.4 DNS Spoofing 3671 Many existing NNTP implementations authorize incoming connections by 3672 checking the IP address of that connection against the IP addresses 3673 obtained via DNS lookups of lists of domain names given in local 3674 configuration files. Servers that use this type of authentication, 3675 and clients that find a server by doing a DNS lookup of the server 3676 name, rely very heavily on the Domain Name Service, and are thus 3677 generally prone to security attacks based on the deliberate 3678 misassociation of IP addresses and DNS names. Clients and servers 3679 need to be cautious in assuming the continuing validity of an IP 3680 number/DNS name association. 3682 In particular, NNTP clients and servers SHOULD rely on their name 3683 resolver for confirmation of an IP number/DNS name association, 3684 rather than caching the result of previous host name lookups. Many 3685 platforms already can cache host name lookups locally when 3686 appropriate, and they SHOULD be configured to do so. It is proper for 3687 these lookups to be cached, however, only when the TTL (Time To Live) 3688 information reported by the name server makes it likely that the 3689 cached information will remain useful. 3691 If NNTP clients or servers cache the results of host name lookups in 3692 order to achieve a performance improvement, they MUST observe the TTL 3693 information reported by DNS. If NNTP clients or servers do not 3694 observe this rule, they could be spoofed when a previously accessed 3695 server's IP address changes. As network renumbering is expected to 3696 become increasingly common, the possibility of this form of attack 3697 will grow. Observing this requirement thus reduces this potential 3698 security vulnerability. 3700 This requirement also improves the load-balancing behavior of clients 3701 for replicated servers using the same DNS name and reduces the 3702 likelihood of a user's experiencing failure in accessing sites that 3703 use that strategy. 3705 11.5 UTF-8 issues 3707 UTF-8 [RFC2279] permits only certain sequences of octets and 3708 designates others as either malformed or "illegal". The Unicode 3709 standard identifies a number of security issues related to illegal 3710 sequences and forbids their generation by conforming implementations. 3712 Implementations of this specification MUST NOT generate malformed or 3713 illegal sequences and SHOULD detect them and take some appropriate 3714 action. This could include: 3716 o replacing such sequences by a "guessed" valid sequence (based on 3717 properties of the UTF-8 encoding); 3719 o replacing such sequences by the sequence %xEF.BF.BD, which encodes 3720 the "replacement character" U+FFFD; 3722 o closing the connection; 3724 o generating a 501 response code. 3726 In the first case, the implementation MUST ensure that any 3727 replacement cannot be used to bypass validity or security checks. For 3728 example, the illegal sequence %xC0.A0 is an over-long encoding for 3729 space (%x20). If it is replaced by the latter in a command line, this 3730 needs to happen before the command line is parsed into individual 3731 arguments. If the replacement came after parsing, it would be 3732 possible to generate an argument with an embedded space, which is 3733 forbidden. Use of the "replacement character" does not have this 3734 problem, since it is permitted wherever non-US-ASCII characters are. 3736 OUTSTANDING ISSUE 3738 Yergeau says that you MUST detect illegal sequences. He also 3739 rejects the first bullet point and consequent text; I'm discussing 3740 it with him now. 3742 12. Acknowledgments 3744 The author acknowledges the original authors of NNTP as documented in 3745 RFC 977 [RFC977]: Brian Kantor and Phil Lapsey. 3747 The author gratefully acknowledges the work of the NNTP committee 3748 chaired by Eliot Lear. The organization of this document was 3749 influenced by the last available draft from this working group. A 3750 special thanks to Eliot for generously providing the original 3751 machine-readable sources for that document. 3753 The author gratefully acknowledges the work of Marshall Rose & John 3754 G. Meyers in RFC 1939 [RFC1939] and the work of the DRUMS working 3755 group, specifically RFC 1869 [RFC1869], which is the basis of the 3756 NNTP extensions mechanism detailed in this document. 3758 OUTSTANDING ISSUE 3760 Why RFC 1939? 3762 The author gratefully acknowledges the authors of RFC 2616 [RFC2616] 3763 for providing specific and relevant examples of security issues that 3764 should be considered for HTTP. Since many of the same considerations 3765 exist for NNTP, those examples that are relevant have been included 3766 here with some minor rewrites. 3768 The author gratefully acknowledges the comments and additional 3769 information provided by the following individuals in preparing one or 3770 more of the progenitors of this document: 3772 Russ Allbery 3773 Wayne Davison 3774 Chris Lewis 3775 Tom Limoncelli 3776 Eric Schnoebelen 3777 Rich Salz 3779 This work was motivated by the work of various news reader authors 3780 and news server authors, which includes those listed below: 3782 Rick Adams 3783 Original author of the NNTP extensions to the RN news reader and 3784 last maintainer of Bnews 3786 Stan Barber 3787 Original author of the NNTP extensions to the news readers that 3788 are part of Bnews 3790 Geoff Collyer 3791 Original author of the OVERVIEW database proposal and one of the 3792 original authors of CNEWS 3794 Dan Curry 3795 Original author of the xvnews news reader 3797 Wayne Davison 3798 Author of the first threading extensions to the RN news reader 3799 (commonly called TRN) 3801 Geoff Huston 3802 Original author of ANU NEWS 3804 Phil Lapsey 3805 Original author of the UNIX reference implementation for NNTP 3807 Iain Lea 3808 Original maintainer of the TIN news reader 3810 Chris Lewis 3811 First known implementer of the AUTHINFO GENERIC extension 3813 Rich Salz 3814 Original author of INN 3816 Henry Spencer 3817 One of the original authors of CNEWS 3819 Kim Storm 3820 Original author of the NN news reader 3822 Finally, the present author gratefully acknowledges the vast amount 3823 of work put into previous drafts by the previous author: 3825 Stan Barber 3827 Normative References 3829 [ANSI1986] 3830 American National Standards Institute, "Coded Character 3831 Set - 7-bit American Standard Code for Information 3832 Interchange", ANSI X3.4, 1986. 3834 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 3835 Specification, Implementation", RFC 1305, March 1992. 3837 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3838 Requirement Levels", BCP 14, RFC 2119, March 1997. 3840 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3841 Specifications: ABNF", RFC 2234, November 1997. 3843 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 3844 10646", RFC 2279, January 1998. 3846 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 3847 2001. 3849 [RFC977] Kantor, B. and P. Lapsley, "Network News Transfer 3850 Protocol", RFC 977, February 1986. 3852 [ROBE1995] 3853 Robertson, R., "FAQ: Overview database / NOV General 3854 Information", January 1995. 3856 [TF.686-1] 3857 International Telecommunications Union - Radio, "Glossary, 3858 ITU-R Recommendation TF.686-1", ITU-R Recommendation 3859 TF.686-1, October 1997. 3861 Informative References 3863 [RFC1036] Horton, M. and R. Adams, "Standard for interchange of 3864 USENET messages", RFC 1036, December 1987. 3866 [RFC1869] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D. 3867 Crocker, "SMTP Service Extensions", STD 10, RFC 1869, 3868 November 1995. 3870 [RFC1939] Myers, J. and M. Rose, "Post Office Protocol - Version 3", 3871 STD 53, RFC 1939, May 1996. 3873 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 3874 Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext 3875 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3877 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 3878 June 1999. 3880 [SALZ1992] 3881 Salz, R., "Manual Page for wildmat(3) from the INN 1.4 3882 distribution, Revision 1.10", April 1992. 3884 Author's Address 3886 Clive D.W. Feather 3887 Thus plc 3888 322 Regents Park Road 3889 London N3 2QQ 3890 GB 3892 Phone: +44 20 8495 6138 3893 Fax: +44 870 051 9937 3894 URI: http://www.davros.org/ 3896 Intellectual Property Statement 3898 The IETF takes no position regarding the validity or scope of any 3899 intellectual property or other rights that might be claimed to 3900 pertain to the implementation or use of the technology described in 3901 this document or the extent to which any license under such rights 3902 might or might not be available; neither does it represent that it 3903 has made any effort to identify any such rights. Information on the 3904 IETF's procedures with respect to rights in standards-track and 3905 standards-related documentation can be found in BCP-11. Copies of 3906 claims of rights made available for publication and any assurances of 3907 licenses to be made available, or the result of an attempt made to 3908 obtain a general license or permission for the use of such 3909 proprietary rights by implementors or users of this specification can 3910 be obtained from the IETF Secretariat. 3912 The IETF invites any interested party to bring to its attention any 3913 copyrights, patents or patent applications, or other proprietary 3914 rights which may cover technology that may be required to practice 3915 this standard. Please address the information to the IETF Executive 3916 Director. 3918 Full Copyright Statement 3920 Copyright (C) The Internet Society (2003). All Rights Reserved. 3922 This document and translations of it may be copied and furnished to 3923 others, and derivative works that comment on or otherwise explain it 3924 or assist in its implementation may be prepared, copied, published 3925 and distributed, in whole or in part, without restriction of any 3926 kind, provided that the above copyright notice and this paragraph are 3927 included on all such copies and derivative works. However, this 3928 document itself may not be modified in any way, such as by removing 3929 the copyright notice or references to the Internet Society or other 3930 Internet organizations, except as needed for the purpose of 3931 developing Internet standards in which case the procedures for 3932 copyrights defined in the Internet Standards process must be 3933 followed, or as required to translate it into languages other than 3934 English. 3936 The limited permissions granted above are perpetual and will not be 3937 revoked by the Internet Society or its successors or assignees. 3939 This document and the information contained herein is provided on an 3940 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3941 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3942 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3943 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3944 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3946 Acknowledgement 3948 Funding for the RFC Editor function is currently provided by the 3949 Internet Society.