chris@1: chris@1: Network Working Group C. Feather chris@1: Request for Comments: 3977 THUS plc chris@1: Obsoletes: 977 October 2006 chris@1: Updates: 2980 chris@1: Category: Standards Track chris@1: chris@1: chris@1: Network News Transfer Protocol (NNTP) chris@1: chris@1: Status of This Memo chris@1: chris@1: This document specifies an Internet standards track protocol for the chris@1: Internet community, and requests discussion and suggestions for chris@1: improvements. Please refer to the current edition of the "Internet chris@1: Official Protocol Standards" (STD 1) for the standardization state chris@1: and status of this protocol. Distribution of this memo is unlimited. chris@1: chris@1: Copyright Notice chris@1: chris@1: Copyright (C) The Internet Society (2006). chris@1: chris@1: Abstract chris@1: chris@1: The Network News Transfer Protocol (NNTP) has been in use in the chris@1: Internet for a decade, and remains one of the most popular protocols chris@1: (by volume) in use today. This document is a replacement for chris@1: RFC 977, and officially updates the protocol specification. It chris@1: clarifies some vagueness in RFC 977, includes some new base chris@1: functionality, and provides a specific mechanism to add standardized chris@1: extensions to NNTP. chris@1: chris@1: Table of Contents chris@1: chris@1: 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 chris@1: 1.1. Author's Note . . . . . . . . . . . . . . . . . . . . . . 4 chris@1: 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 5 chris@1: 3. Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . 6 chris@1: 3.1. Commands and Responses . . . . . . . . . . . . . . . . . 6 chris@1: 3.1.1. Multi-line Data Blocks . . . . . . . . . . . . . . . . 8 chris@1: 3.2. Response Codes . . . . . . . . . . . . . . . . . . . . . 9 chris@1: 3.2.1. Generic Response Codes . . . . . . . . . . . . . . . 10 chris@1: 3.2.1.1. Examples . . . . . . . . . . . . . . . . . . . . 12 chris@1: 3.3. Capabilities and Extensions . . . . . . . . . . . . . . . 14 chris@1: 3.3.1. Capability Descriptions . . . . . . . . . . . . . . . 14 chris@1: 3.3.2. Standard Capabilities . . . . . . . . . . . . . . . . 15 chris@1: 3.3.3. Extensions . . . . . . . . . . . . . . . . . . . . . 16 chris@1: 3.3.4. Initial IANA Register . . . . . . . . . . . . . . . . 18 chris@1: 3.4. Mandatory and Optional Commands . . . . . . . . . . . . . 20 chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 1] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 3.4.1. Reading and Transit Servers . . . . . . . . . . . . . 21 chris@1: 3.4.2. Mode Switching . . . . . . . . . . . . . . . . . . . 21 chris@1: 3.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 22 chris@1: 3.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 23 chris@1: 3.6. Articles . . . . . . . . . . . . . . . . . . . . . . . . 24 chris@1: 4. The WILDMAT Format . . . . . . . . . . . . . . . . . . . . . 25 chris@1: 4.1. Wildmat Syntax . . . . . . . . . . . . . . . . . . . . . 26 chris@1: 4.2. Wildmat Semantics . . . . . . . . . . . . . . . . . . . . 26 chris@1: 4.3. Extensions . . . . . . . . . . . . . . . . . . . . . . . 27 chris@1: 4.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 27 chris@1: 5. Session Administration Commands . . . . . . . . . . . . . . . 28 chris@1: 5.1. Initial Connection . . . . . . . . . . . . . . . . . . . 28 chris@1: 5.2. CAPABILITIES . . . . . . . . . . . . . . . . . . . . . . 29 chris@1: 5.3. MODE READER . . . . . . . . . . . . . . . . . . . . . . . 32 chris@1: 5.4. QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . 34 chris@1: 6. Article Posting and Retrieval . . . . . . . . . . . . . . . . 35 chris@1: 6.1. Group and Article Selection . . . . . . . . . . . . . . . 36 chris@1: 6.1.1. GROUP . . . . . . . . . . . . . . . . . . . . . . . . 36 chris@1: 6.1.2. LISTGROUP . . . . . . . . . . . . . . . . . . . . . . 39 chris@1: 6.1.3. LAST . . . . . . . . . . . . . . . . . . . . . . . . 42 chris@1: 6.1.4. NEXT . . . . . . . . . . . . . . . . . . . . . . . . 44 chris@1: 6.2. Retrieval of Articles and Article Sections . . . . . . . 45 chris@1: 6.2.1. ARTICLE . . . . . . . . . . . . . . . . . . . . . . . 46 chris@1: 6.2.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 49 chris@1: 6.2.3. BODY . . . . . . . . . . . . . . . . . . . . . . . . 51 chris@1: 6.2.4. STAT . . . . . . . . . . . . . . . . . . . . . . . . 53 chris@1: 6.3. Article Posting . . . . . . . . . . . . . . . . . . . . . 56 chris@1: 6.3.1. POST . . . . . . . . . . . . . . . . . . . . . . . . 56 chris@1: 6.3.2. IHAVE . . . . . . . . . . . . . . . . . . . . . . . . 58 chris@1: 7. Information Commands . . . . . . . . . . . . . . . . . . . . 61 chris@1: 7.1. DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 61 chris@1: 7.2. HELP . . . . . . . . . . . . . . . . . . . . . . . . . . 62 chris@1: 7.3. NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 63 chris@1: 7.4. NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 64 chris@1: 7.5. Time . . . . . . . . . . . . . . . . . . . . . . . . . . 65 chris@1: 7.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 66 chris@1: 7.6. The LIST Commands . . . . . . . . . . . . . . . . . . . . 66 chris@1: 7.6.1. LIST . . . . . . . . . . . . . . . . . . . . . . . . 67 chris@1: 7.6.2. Standard LIST Keywords . . . . . . . . . . . . . . . 69 chris@1: 7.6.3. LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . 70 chris@1: 7.6.4. LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . 71 chris@1: 7.6.5. LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . 72 chris@1: 7.6.6. LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . 73 chris@1: 8. Article Field Access Commands . . . . . . . . . . . . . . . . 73 chris@1: 8.1. Article Metadata . . . . . . . . . . . . . . . . . . . . 74 chris@1: 8.1.1. The :bytes Metadata Item . . . . . . . . . . . . . . 74 chris@1: 8.1.2. The :lines Metadata Item . . . . . . . . . . . . . . 75 chris@1: 8.2. Database Consistency . . . . . . . . . . . . . . . . . . 75 chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 2] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 8.3. OVER . . . . . . . . . . . . . . . . . . . . . . . . . . 76 chris@1: 8.4. LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 81 chris@1: 8.5. HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 chris@1: 8.6. LIST HEADERS . . . . . . . . . . . . . . . . . . . . . . 87 chris@1: 9. Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . . . 90 chris@1: 9.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 90 chris@1: 9.2. Commands . . . . . . . . . . . . . . . . . . . . . . . . 92 chris@1: 9.3. Command Continuation . . . . . . . . . . . . . . . . . . 93 chris@1: 9.4. Responses . . . . . . . . . . . . . . . . . . . . . . . . 93 chris@1: 9.4.1. Generic Responses . . . . . . . . . . . . . . . . . . 93 chris@1: 9.4.2. Initial Response Line Contents . . . . . . . . . . . 94 chris@1: 9.4.3. Multi-line Response Contents . . . . . . . . . . . . 94 chris@1: 9.5. Capability Lines . . . . . . . . . . . . . . . . . . . . 95 chris@1: 9.6. LIST Variants . . . . . . . . . . . . . . . . . . . . . . 96 chris@1: 9.7. Articles . . . . . . . . . . . . . . . . . . . . . . . . 97 chris@1: 9.8. General Non-terminals . . . . . . . . . . . . . . . . . . 97 chris@1: 9.9. Extensions and Validation . . . . . . . . . . . . . . . . 99 chris@1: 10. Internationalisation Considerations . . . . . . . . . . . . .100 chris@1: 10.1. Introduction and Historical Situation . . . . . . . . . .100 chris@1: 10.2. This Specification . . . . . . . . . . . . . . . . . . .101 chris@1: 10.3. Outstanding Issues . . . . . . . . . . . . . . . . . . .102 chris@1: 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .103 chris@1: 12. Security Considerations . . . . . . . . . . . . . . . . . . .103 chris@1: 12.1. Personal and Proprietary Information . . . . . . . . . .104 chris@1: 12.2. Abuse of Server Log Information . . . . . . . . . . . . .104 chris@1: 12.3. Weak Authentication and Access Control . . . . . . . . .104 chris@1: 12.4. DNS Spoofing . . . . . . . . . . . . . . . . . . . . . .104 chris@1: 12.5. UTF-8 Issues . . . . . . . . . . . . . . . . . . . . . .105 chris@1: 12.6. Caching of Capability Lists . . . . . . . . . . . . . . .106 chris@1: 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . .107 chris@1: 14. References . . . . . . . . . . . . . . . . . . . . . . . . .110 chris@1: 14.1. Normative References . . . . . . . . . . . . . . . . . .110 chris@1: 14.2. Informative References . . . . . . . . . . . . . . . . .110 chris@1: A. Interaction with Other Specifications . . . . . . . . . . . .112 chris@1: A.1. Header Folding . . . . . . . . . . . . . . . . . . . . .112 chris@1: A.2. Message-IDs . . . . . . . . . . . . . . . . . . . . . . .112 chris@1: A.3. Article Posting . . . . . . . . . . . . . . . . . . . . .114 chris@1: B. Summary of Commands . . . . . . . . . . . . . . . . . . . . .115 chris@1: C. Summary of Response Codes . . . . . . . . . . . . . . . . . .117 chris@1: D. Changes from RFC 977 . . . . . . . . . . . . . . . . . . . .121 chris@1: chris@1: 1. Introduction chris@1: chris@1: This document specifies the Network News Transfer Protocol (NNTP), chris@1: which is used for the distribution, inquiry, retrieval, and posting chris@1: of Netnews articles using a reliable stream-based mechanism. For chris@1: news-reading clients, NNTP enables retrieval of news articles that chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 3] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: are stored in a central database, giving subscribers the ability to chris@1: select only those articles they wish to read. chris@1: chris@1: The Netnews model provides for indexing, cross-referencing, and chris@1: expiration of aged messages. NNTP is designed for efficient chris@1: transmission of Netnews articles over a reliable full duplex chris@1: communication channel. chris@1: chris@1: Although the protocol specification in this document is largely chris@1: compatible with the version specified in RFC 977 [RFC977], a number chris@1: of changes are summarised in Appendix D. In particular: chris@1: chris@1: o the default character set is changed from US-ASCII [ANSI1986] to chris@1: UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8); chris@1: chris@1: o a number of commands that were optional in RFC 977 or that have chris@1: been taken from RFC 2980 [RFC2980] are now mandatory; and chris@1: chris@1: o a CAPABILITIES command has been added to allow clients to chris@1: determine what functionality is available from a server. chris@1: chris@1: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", chris@1: "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this chris@1: document are to be interpreted as described in RFC 2119 [RFC2119]. chris@1: chris@1: An implementation is not compliant if it fails to satisfy one or more chris@1: of the MUST requirements for this protocol. An implementation that chris@1: satisfies all the MUST and all the SHOULD requirements for its chris@1: protocols is said to be "unconditionally compliant"; one that chris@1: satisfies all the MUST requirements but not all the SHOULD chris@1: requirements for NNTP is said to be "conditionally compliant". chris@1: chris@1: For the remainder of this document, the terms "client" and "client chris@1: host" refer to a host making use of the NNTP service, while the terms chris@1: "server" and "server host" refer to a host that offers the NNTP chris@1: service. chris@1: chris@1: 1.1. Author's Note chris@1: chris@1: This document is written in XML using an NNTP-specific DTD. Custom chris@1: software is used to convert this to RFC 2629 [RFC2629] format, and chris@1: then the public "xml2rfc" package to further reduce this to text, chris@1: nroff source, and HTML. chris@1: chris@1: No perl was used in producing this document. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 4] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 2. Notation chris@1: chris@1: The following notational conventions are used in this document. chris@1: chris@1: UPPERCASE indicates literal text to be included in the chris@1: command. chris@1: chris@1: lowercase indicates a token described elsewhere. chris@1: chris@1: [brackets] indicate that the enclosed material is optional. chris@1: chris@1: elliptical indicates that the argument may be repeated any chris@1: ... marks number of times (it must occur at least once). chris@1: chris@1: vertical|bar indicates a choice of two mutually exclusive chris@1: arguments (exactly one must be provided). chris@1: chris@1: The name "message-id" for a command or response argument indicates chris@1: that it is the message-id of an article as described in Section 3.6, chris@1: including the angle brackets. chris@1: chris@1: The name "wildmat" for an argument indicates that it is a wildmat as chris@1: defined in Section 4. If the argument does not meet the requirements chris@1: of that section (for example, if it does not fit the grammar of chris@1: Section 4.1), the NNTP server MAY place some interpretation on it chris@1: (not specified by this document) or otherwise MUST treat it as a chris@1: syntax error. chris@1: chris@1: Responses for each command will be described in tables listing the chris@1: required format of a response followed by the meaning that should be chris@1: ascribed to that response. chris@1: chris@1: The terms "NUL", "TAB", "LF", "CR, and "space" refer to the octets chris@1: %x00, %x09, %x0A, %x0D, and %x20, respectively (that is, the octets chris@1: with those codes in US-ASCII [ANSI1986] and thus in UTF-8 [RFC3629]). chris@1: The term "CRLF" or "CRLF pair" means the sequence CR immediately chris@1: followed by LF (that is, %x0D.0A). A "printable US-ASCII character" chris@1: is an octet in the range %x21-7E. Quoted characters refer to the chris@1: octets with those codes in US-ASCII (so "." and "<" refer to %x2E and chris@1: %x3C) and will always be printable US-ASCII characters; similarly, chris@1: "digit" refers to the octets %x30-39. chris@1: chris@1: A "keyword" MUST consist only of US-ASCII letters, digits, and the chris@1: characters dot (".") and dash ("-") and MUST begin with a letter. chris@1: Keywords MUST be at least three characters in length. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 5] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Examples in this document are not normative but serve to illustrate chris@1: usages, arguments, and responses. In the examples, a "[C]" will be chris@1: used to represent the client host and an "[S]" will be used to chris@1: represent the server host. Most of the examples do not rely on a chris@1: particular server state. In some cases, however, they do assume that chris@1: the currently selected newsgroup (see the GROUP command, chris@1: Section 6.1.1) is invalid; when so, this is indicated at the start of chris@1: the example. Examples may use commands or other keywords not defined chris@1: in this specification (such as an XENCRYPT command). These will be chris@1: used to illustrate some point and do not imply that any such command chris@1: is defined elsewhere or needs to exist in any particular chris@1: implementation. chris@1: chris@1: Terms that might be read as specifying details of a client or server chris@1: implementation, such as "database", are used simply to ease chris@1: description. Provided that implementations conform to the protocol chris@1: and format specifications in this document, no specific technique is chris@1: mandated. chris@1: chris@1: 3. Basic Concepts chris@1: chris@1: 3.1. Commands and Responses chris@1: chris@1: NNTP operates over any reliable bi-directional 8-bit-wide data stream chris@1: channel. When the connection is established, the NNTP server host chris@1: MUST send a greeting. The client host and server host then exchange chris@1: commands and responses (respectively) until the connection is closed chris@1: or aborted. If the connection used is TCP, then the server host chris@1: starts the NNTP service by listening on a TCP port. When a client chris@1: host wishes to make use of the service, it MUST establish a TCP chris@1: connection with the server host by connecting to that host on the chris@1: same port on which the server is listening. chris@1: chris@1: The character set for all NNTP commands is UTF-8 [RFC3629]. Commands chris@1: in NNTP MUST consist of a keyword, which MAY be followed by one or chris@1: more arguments. A CRLF pair MUST terminate all commands. Multiple chris@1: commands MUST NOT be on the same line. Unless otherwise noted chris@1: elsewhere in this document, arguments SHOULD consist of printable US- chris@1: ASCII characters. Keywords and arguments MUST each be separated by chris@1: one or more space or TAB characters. Command lines MUST NOT exceed chris@1: 512 octets, which includes the terminating CRLF pair. The arguments chris@1: MUST NOT exceed 497 octets. A server MAY relax these limits for chris@1: commands defined in an extension. chris@1: chris@1: Where this specification permits UTF-8 characters outside the range chris@1: of U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark chris@1: (U+FEFF, encoding %xEF.BB.BF) and MUST use the Word Joiner (U+2060, chris@1: encoding %xE2.91.A0) for the meaning Zero Width No-Break Space in chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 6] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: command lines and the initial lines of responses. Implementations chris@1: SHOULD apply these same principles throughout. chris@1: chris@1: The term "character" means a single Unicode code point. chris@1: Implementations are not required to carry out Unicode normalisation. chris@1: Thus, U+0084 (A-dieresis) is one character, while U+0041 U+0308 (A chris@1: composed with dieresis) is two; the two need not be treated as chris@1: equivalent. chris@1: chris@1: Commands may have variants; if so, they use a second keyword chris@1: immediately after the first to indicate which variant is required. chris@1: The only such commands in this specification are LIST and MODE. Note chris@1: that such variants are sometimes referred to as if they were commands chris@1: in their own right: "the LIST ACTIVE" command should be read as chris@1: shorthand for "the ACTIVE variant of the LIST command". chris@1: chris@1: Keywords are case insensitive; the case of keywords for commands MUST chris@1: be ignored by the server. Command and response arguments are case or chris@1: language specific only when stated, either in this document or in chris@1: other relevant specifications. chris@1: chris@1: In some cases, a command involves more data than just a single line. chris@1: The further data may be sent either immediately after the command chris@1: line (there are no instances of this in this specification, but there chris@1: are in extensions such as [NNTP-STREAM]) or following a request from chris@1: the server (indicated by a 3xx response). chris@1: chris@1: Each response MUST start with a three-digit response code that is chris@1: sufficient to distinguish all responses. Certain valid responses are chris@1: defined to be multi-line; for all others, the response is contained chris@1: in a single line. The initial line of the response MUST NOT exceed chris@1: 512 octets, which includes the response code and the terminating CRLF chris@1: pair; an extension MAY specify a greater maximum for commands that it chris@1: defines, but not for any other command. Single-line responses chris@1: consist of an initial line only. Multi-line responses consist of an chris@1: initial line followed by a multi-line data block. chris@1: chris@1: An NNTP server MAY have an inactivity autologout timer. Such a timer chris@1: SHOULD be of at least three minutes' duration, with the exception chris@1: that there MAY be a shorter limit on how long the server is willing chris@1: to wait for the first command from the client. The receipt of any chris@1: command from the client during the timer interval SHOULD suffice to chris@1: reset the autologout timer. Similarly, the receipt of any chris@1: significant amount of data from a client that is sending a multi-line chris@1: data block (such as during a POST or IHAVE command) SHOULD suffice to chris@1: reset the autologout timer. When the timer expires, the server chris@1: SHOULD close the connection without sending any response to the chris@1: client. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 7] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 3.1.1. Multi-line Data Blocks chris@1: chris@1: A multi-line data block is used in certain commands and responses. chris@1: It MUST adhere to the following rules: chris@1: chris@1: 1. The block consists of a sequence of zero or more "lines", each chris@1: being a stream of octets ending with a CRLF pair. Apart from chris@1: those line endings, the stream MUST NOT include the octets NUL, chris@1: LF, or CR. chris@1: chris@1: 2. In a multi-line response, the block immediately follows the CRLF chris@1: at the end of the initial line of the response. When used in any chris@1: other context, the specific command will define when the block is chris@1: sent. chris@1: chris@1: 3. If any line of the data block begins with the "termination octet" chris@1: ("." or %x2E), that line MUST be "dot-stuffed" by prepending an chris@1: additional termination octet to that line of the block. chris@1: chris@1: 4. The lines of the block MUST be followed by a terminating line chris@1: consisting of a single termination octet followed by a CRLF pair chris@1: in the normal way. Thus, unless it is empty, a multi-line block chris@1: is always terminated with the five octets CRLF "." CRLF chris@1: (%x0D.0A.2E.0D.0A). chris@1: chris@1: 5. When a multi-line block is interpreted, the "dot-stuffing" MUST chris@1: be undone; i.e., the recipient MUST ensure that, in any line chris@1: beginning with the termination octet followed by octets other chris@1: than a CRLF pair, that initial termination octet is disregarded. chris@1: chris@1: 6. Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT chris@1: be considered part of the multi-line block; i.e., the recipient chris@1: MUST ensure that any line beginning with the termination octet chris@1: followed immediately by a CRLF pair is disregarded. (The first chris@1: CRLF pair of the terminating CRLF "." CRLF of a non-empty block chris@1: is, of course, part of the last line of the block.) chris@1: chris@1: Note that texts using an encoding (such as UTF-16 or UTF-32) that may chris@1: contain the octets NUL, LF, or CR other than a CRLF pair cannot be chris@1: reliably conveyed in the above format (that is, they violate the MUST chris@1: requirement above). However, except when stated otherwise, this chris@1: specification does not require the content to be UTF-8, and therefore chris@1: (subject to that same requirement) it MAY include octets above and chris@1: below 128 mixed arbitrarily. chris@1: chris@1: This document does not place any limit on the length of a line in a chris@1: multi-line block. However, the standards that define the format of chris@1: articles may do so. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 8] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 3.2. Response Codes chris@1: chris@1: Each response MUST begin with a three-digit status indicator. These chris@1: are status reports from the server and indicate the response to the chris@1: last command received from the client. chris@1: chris@1: The first digit of the response broadly indicates the success, chris@1: failure, or progress of the previous command: chris@1: chris@1: 1xx - Informative message chris@1: 2xx - Command completed OK chris@1: 3xx - Command OK so far; send the rest of it chris@1: 4xx - Command was syntactically correct but failed for some reason chris@1: 5xx - Command unknown, unsupported, unavailable, or syntax error chris@1: chris@1: The next digit in the code indicates the function response category: chris@1: chris@1: x0x - Connection, setup, and miscellaneous messages chris@1: x1x - Newsgroup selection chris@1: x2x - Article selection chris@1: x3x - Distribution functions chris@1: x4x - Posting chris@1: x8x - Reserved for authentication and privacy extensions chris@1: x9x - Reserved for private use (non-standard extensions) chris@1: chris@1: Certain responses contain arguments such as numbers and names in chris@1: addition to the status indicator. In those cases, to simplify chris@1: interpretation by the client, the number and type of such arguments chris@1: is fixed for each response code, as is whether the code is chris@1: single-line or multi-line. Any extension MUST follow this principle chris@1: as well. Note that, for historical reasons, the 211 response code is chris@1: an exception to this in that the response may be single-line or chris@1: multi-line depending on the command (GROUP or LISTGROUP) that chris@1: generated it. In all other cases, the client MUST only use the chris@1: status indicator itself to determine the nature of the response. The chris@1: exact response codes that can be returned by any given command are chris@1: detailed in the description of that command. chris@1: chris@1: Arguments MUST be separated from the numeric status indicator and chris@1: from each other by a single space. All numeric arguments MUST be in chris@1: base 10 (decimal) format and MAY have leading zeros. String chris@1: arguments MUST contain at least one character and MUST NOT contain chris@1: TAB, LF, CR, or space. The server MAY add any text after the chris@1: response code or last argument, as appropriate, and the client MUST chris@1: NOT make decisions based on this text. Such text MUST be separated chris@1: from the numeric status indicator or the last argument by at least chris@1: one space. chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 9] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: The server MUST respond to any command with the appropriate generic chris@1: response (given in Section 3.2.1) if it represents the situation. chris@1: Otherwise, each recognized command MUST return one of the response chris@1: codes specifically listed in its description or in an extension. A chris@1: server MAY provide extensions to this specification, including new chris@1: commands, new variants or features of existing commands, and other chris@1: ways of changing the internal state of the server. However, the chris@1: server MUST NOT produce any other responses to a client that does not chris@1: invoke any of the additional features. (Therefore, a client that chris@1: restricts itself to this specification will only receive the chris@1: responses that are listed.) chris@1: chris@1: If a client receives an unexpected response, it SHOULD use the first chris@1: digit of the response to determine the result. For example, an chris@1: unexpected 2xx should be taken as success, and an unexpected 4xx or chris@1: 5xx as failure. chris@1: chris@1: Response codes not specified in this document MAY be used for any chris@1: installation-specific additional commands also not specified. These chris@1: SHOULD be chosen to fit the pattern of x9x specified above. chris@1: chris@1: Neither this document nor any registered extension (see chris@1: Section 3.3.3) will specify any response codes of the x9x pattern. chris@1: (Implementers of extensions are accordingly cautioned not to use such chris@1: responses for extensions that may subsequently be submitted for chris@1: registration.) chris@1: chris@1: 3.2.1. Generic Response Codes chris@1: chris@1: The server MUST respond to any command with the appropriate one of chris@1: the following generic responses if it represents the situation. chris@1: chris@1: If the command is not recognized, or if it is an optional command chris@1: that is not implemented by the server, the response code 500 MUST be chris@1: returned. chris@1: chris@1: If there is a syntax error in the arguments of a recognized command, chris@1: including the case where more arguments are provided than the command chris@1: specifies or the command line is longer than the server accepts, the chris@1: response code 501 MUST be returned. The line MUST NOT be truncated chris@1: or split and then interpreted. Note that where a command has chris@1: variants depending on a second keyword (e.g., LIST ACTIVE and LIST chris@1: NEWSGROUPS), 501 MUST be used when the base command is implemented chris@1: but the requested variant is not, and 500 MUST be used only when the chris@1: base command itself is not implemented. chris@1: chris@1: If an argument is required to be a base64-encoded string [RFC4648] chris@1: (there are no such arguments in this specification, but there may be chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 10] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: in extensions) and is not validly encoded, the response code 504 MUST chris@1: be returned. chris@1: chris@1: If the server experiences an internal fault or problem that means it chris@1: is unable to carry out the command (for example, a necessary file is chris@1: missing or a necessary service could not be contacted), the response chris@1: code 403 MUST be returned. If the server recognizes the command but chris@1: does not provide an optional feature (for example, because it does chris@1: not store the required information), or if it only handles a subset chris@1: of legitimate cases (see the HDR command, Section 8.5, for an chris@1: example), the response code 503 MUST be returned. chris@1: chris@1: If the client is not authorized to use the specified facility when chris@1: the server is in its current state, then the appropriate one of the chris@1: following response codes MUST be used. chris@1: chris@1: 502: It is necessary to terminate the connection and to start a new chris@1: one with the appropriate authority before the command can be used. chris@1: Historically, some mode-switching servers (see Section 3.4.1) used chris@1: this response to indicate that this command will become available chris@1: after the MODE READER command (Section 5.3) is used, but this chris@1: usage does not conform to this specification and MUST NOT be used. chris@1: Note that the server MUST NOT close the connection immediately chris@1: after a 502 response except at the initial connection chris@1: (Section 5.1) and with the MODE READER command. chris@1: chris@1: 480: The client must authenticate itself to the server (that is, it chris@1: must provide information as to the identity of the client) before chris@1: the facility can be used on this connection. This will involve chris@1: the use of an authentication extension such as [NNTP-AUTH]. chris@1: chris@1: 483: The client must negotiate appropriate privacy protection on the chris@1: connection. This will involve the use of a privacy extension such chris@1: as [NNTP-TLS]. chris@1: chris@1: 401: The client must change the state of the connection in some other chris@1: manner. The first argument of the response MUST be the capability chris@1: label (see Section 5.2) of the facility that provides the chris@1: necessary mechanism (usually an extension, which may be a private chris@1: extension). The server MUST NOT use this response code except as chris@1: specified by the definition of the capability in question. chris@1: chris@1: If the server has to terminate the connection for some reason, it chris@1: MUST give a 400 response code to the next command and then chris@1: immediately close the connection. Following a 400 response, clients chris@1: SHOULD NOT simply reconnect immediately and retry the same actions. chris@1: Rather, a client SHOULD either use an exponentially increasing delay chris@1: between retries (e.g., double the waiting time after each 400 chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 11] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: response) or present any associated text to the user for them to chris@1: decide whether and when to retry. chris@1: chris@1: The client MUST be prepared to receive any of these responses for any chris@1: command (except, of course, that the server MUST NOT generate a 500 chris@1: response code for mandatory commands). chris@1: chris@1: 3.2.1.1. Examples chris@1: chris@1: Example of an unknown command: chris@1: chris@1: [C] MAIL chris@1: [S] 500 Unknown command chris@1: chris@1: Example of an unsupported command: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] NEWNEWS chris@1: [S] LIST ACTIVE NEWSGROUPS chris@1: [S] . chris@1: [C] OVER chris@1: [S] 500 Unknown command chris@1: chris@1: Example of an unsupported variant: chris@1: chris@1: [C] MODE POSTER chris@1: [S] 501 Unknown MODE option chris@1: chris@1: Example of a syntax error: chris@1: chris@1: [C] ARTICLE a.message.id@no.angle.brackets chris@1: [S] 501 Syntax error chris@1: chris@1: Example of an overlong command line: chris@1: chris@1: [C] HEAD 53 54 55 chris@1: [S] 501 Too many arguments chris@1: chris@1: Example of a bad wildmat: chris@1: chris@1: [C] LIST ACTIVE u[ks].* chris@1: [S] 501 Syntax error chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 12] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of a base64-encoding error (the second argument is meant to chris@1: be base64 encoded): chris@1: chris@1: [C] XENCRYPT RSA abcd=efg chris@1: [S] 504 Base64 encoding error chris@1: chris@1: Example of an attempt to access a facility not available to this chris@1: connection: chris@1: chris@1: [C] MODE READER chris@1: [S] 200 Reader mode, posting permitted chris@1: [C] IHAVE chris@1: [S] 500 Permission denied chris@1: chris@1: Example of an attempt to access a facility requiring authentication: chris@1: chris@1: [C] GROUP secret.group chris@1: [S] 480 Permission denied chris@1: chris@1: Example of a successful attempt following such authentication: chris@1: chris@1: [C] XSECRET fred flintstone chris@1: [S] 290 Password for fred accepted chris@1: [C] GROUP secret.group chris@1: [S] 211 5 1 20 secret.group selected chris@1: chris@1: Example of an attempt to access a facility requiring privacy: chris@1: chris@1: [C] GROUP secret.group chris@1: [S] 483 Secure connection required chris@1: [C] XENCRYPT chris@1: [Client and server negotiate encryption on the link] chris@1: [S] 283 Encrypted link established chris@1: [C] GROUP secret.group chris@1: [S] 211 5 1 20 secret.group selected chris@1: chris@1: Example of a need to change mode before a facility is used: chris@1: chris@1: [C] GROUP binary.group chris@1: [S] 401 XHOST Not on this virtual host chris@1: [C] XHOST binary.news.example.org chris@1: [S] 290 binary.news.example.org virtual host selected chris@1: [C] GROUP binary.group chris@1: [S] 211 5 1 77 binary.group selected chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 13] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of a temporary failure: chris@1: chris@1: [C] GROUP archive.local chris@1: [S] 403 Archive server temporarily offline chris@1: chris@1: Example of the server needing to close down immediately: chris@1: chris@1: [C] ARTICLE 123 chris@1: [S] 400 Power supply failed, running on UPS chris@1: [Server closes connection.] chris@1: chris@1: 3.3. Capabilities and Extensions chris@1: chris@1: Not all NNTP servers provide exactly the same facilities, both chris@1: because this specification allows variation and because servers may chris@1: provide extensions. A set of facilities that are related are called chris@1: a "capability". This specification provides a way to determine what chris@1: capabilities are available, includes a list of standard capabilities, chris@1: and includes a mechanism (the extension mechanism) for defining new chris@1: capabilities. chris@1: chris@1: 3.3.1. Capability Descriptions chris@1: chris@1: A client can determine the available capabilities of the server by chris@1: using the CAPABILITIES command (Section 5.2). This returns a chris@1: capability list, which is a list of capability lines. Each line chris@1: describes one available capability. chris@1: chris@1: Each capability line consists of one or more tokens, which MUST be chris@1: separated by one or more space or TAB characters. A token is a chris@1: string of 1 or more printable UTF-8 characters (that is, either chris@1: printable US-ASCII characters or any UTF-8 sequence outside the US- chris@1: ASCII range, but not space or TAB). Unless stated otherwise, tokens chris@1: are case insensitive. Each capability line consists of the chris@1: following: chris@1: chris@1: o The capability label, which is a keyword indicating the chris@1: capability. A capability label may be defined by this chris@1: specification or a successor, or by an extension. chris@1: chris@1: o The label is then followed by zero or more tokens, which are chris@1: arguments of the capability. The form and meaning of these tokens chris@1: is specific to each capability. chris@1: chris@1: The server MUST ensure that the capability list accurately reflects chris@1: the capabilities (including extensions) currently available. If a chris@1: capability is only available with the server in a certain state (for chris@1: example, only after authentication), the list MUST only include the chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 14] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: capability label when the server is in that state. Similarly, if chris@1: only some of the commands in an extension will be available, or if chris@1: the behaviour of the extension will change in some other manner, chris@1: according to the state of the server, this MUST be indicated by chris@1: different arguments in the capability line. chris@1: chris@1: Note that a capability line can only begin with a letter. Lines chris@1: beginning with other characters are reserved for future versions of chris@1: this specification. In order to interoperate with such versions, chris@1: clients MUST be prepared to receive lines beginning with other chris@1: characters and MUST ignore any they do not understand. chris@1: chris@1: 3.3.2. Standard Capabilities chris@1: chris@1: The following capabilities are defined by this specification. chris@1: chris@1: VERSION chris@1: This capability MUST be advertised by all servers and MUST be the chris@1: first capability in the capability list; it indicates the chris@1: version(s) of NNTP that the server supports. There must be at chris@1: least one argument; each argument is a decimal number and MUST NOT chris@1: have a leading zero. Version numbers are assigned only in RFCs chris@1: that update or replace this specification; servers MUST NOT create chris@1: their own version numbers. chris@1: chris@1: The version number of this specification is 2. chris@1: chris@1: READER chris@1: This capability indicates that the server implements the various chris@1: commands useful for reading clients. chris@1: chris@1: IHAVE chris@1: This capability indicates that the server implements the IHAVE chris@1: command. chris@1: chris@1: POST chris@1: This capability indicates that the server implements the POST chris@1: command. chris@1: chris@1: NEWNEWS chris@1: This capability indicates that the server implements the NEWNEWS chris@1: command. chris@1: chris@1: HDR chris@1: This capability indicates that the server implements the header chris@1: access commands (HDR and LIST HEADERS). chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 15] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: OVER chris@1: This capability indicates that the server implements the overview chris@1: access commands (OVER and LIST OVERVIEW.FMT). If and only if the chris@1: server supports the message-id form of the OVER command, there chris@1: must be a single argument MSGID. chris@1: chris@1: LIST chris@1: This capability indicates that the server implements at least one chris@1: variant of the LIST command. There MUST be one argument for each chris@1: variant of the LIST command supported by the server, giving the chris@1: keyword for that variant. chris@1: chris@1: IMPLEMENTATION chris@1: This capability MAY be provided by a server. If so, the arguments chris@1: SHOULD be used to provide information such as the server software chris@1: name and version number. The client MUST NOT use this line to chris@1: determine capabilities of the server. (While servers often chris@1: provide this information in the initial greeting, clients need to chris@1: guess whether this is the case; this capability makes it clear chris@1: what the information is.) chris@1: chris@1: MODE-READER chris@1: This capability indicates that the server is mode-switching chris@1: (Section 3.4.2) and that the MODE READER command needs to be used chris@1: to enable the READER capability. chris@1: chris@1: 3.3.3. Extensions chris@1: chris@1: Although NNTP is widely and robustly deployed, some parts of the chris@1: Internet community might wish to extend the NNTP service. It must be chris@1: emphasized that any extension to NNTP should not be considered chris@1: lightly. NNTP's strength comes primarily from its simplicity. chris@1: Experience with many protocols has shown that: chris@1: chris@1: Protocols with few options tend towards ubiquity, whilst protocols chris@1: with many options tend towards obscurity. chris@1: chris@1: This means that each and every extension, regardless of its benefits, chris@1: must be carefully scrutinized with respect to its implementation, chris@1: deployment, and interoperability costs. In many cases, the cost of chris@1: extending the NNTP service will likely outweigh the benefit. chris@1: chris@1: An extension is a package of associated facilities, often but not chris@1: always including one or more new commands. Each extension MUST chris@1: define at least one new capability label (this will often, but need chris@1: not, be the name of one of these new commands). While any additional chris@1: capability information can normally be specified using arguments to chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 16] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: that label, an extension MAY define more than one capability label. chris@1: However, this SHOULD be limited to exceptional circumstances. chris@1: chris@1: An extension is either a private extension, or its capabilities are chris@1: included in the IANA registry of capabilities (see Section 3.3.4) and chris@1: it is defined in an RFC (in which case it is a "registered chris@1: extension"). Such RFCs either must be on the standards track or must chris@1: define an IESG-approved experimental protocol. chris@1: chris@1: The definition of an extension must include the following: chris@1: chris@1: o a descriptive name for the extension. chris@1: chris@1: o the capability label or labels defined by the extension (the chris@1: capability label of a registered extension MUST NOT begin with chris@1: "X"). chris@1: chris@1: o The syntax, values, and meanings of any arguments for each chris@1: capability label defined by the extension. chris@1: chris@1: o Any new NNTP commands associated with the extension (the names of chris@1: commands associated with registered extensions MUST NOT begin with chris@1: "X"). chris@1: chris@1: o The syntax and possible values of arguments associated with the chris@1: new NNTP commands. chris@1: chris@1: o The response codes and possible values of arguments for the chris@1: responses of the new NNTP commands. chris@1: chris@1: o Any new arguments the extension associates with any other chris@1: pre-existing NNTP commands. chris@1: chris@1: o Any increase in the maximum length of commands and initial chris@1: response lines over the value specified in this document. chris@1: chris@1: o A specific statement about the effect on pipelining that this chris@1: extension may have (if any). chris@1: chris@1: o A specific statement about the circumstances when use of this chris@1: extension can alter the contents of the capabilities list (other chris@1: than the new capability labels it defines). chris@1: chris@1: o A specific statement about the circumstances under which the chris@1: extension can cause any pre-existing command to produce a 401, chris@1: 480, or 483 response. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 17] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: o A description of how the use of MODE READER on a mode-switching chris@1: server interacts with the extension. chris@1: chris@1: o A description of how support for the extension affects the chris@1: behaviour of a server and NNTP client in any other manner not chris@1: outlined above. chris@1: chris@1: o Formal syntax as described in Section 9.9. chris@1: chris@1: A private extension MAY or MAY NOT be included in the capabilities chris@1: list. If it is, the capability label MUST begin with "X". A server chris@1: MAY provide additional keywords (for new commands and also for new chris@1: variants of existing commands) as part of a private extension. To chris@1: avoid the risk of a clash with a future registered extension, these chris@1: keywords SHOULD begin with "X". chris@1: chris@1: If the server advertises a capability defined by a registered chris@1: extension, it MUST implement the extension so as to fully conform chris@1: with the specification (for example, it MUST implement all the chris@1: commands that the extension describes as mandatory). If it does not chris@1: implement the extension as specified, it MUST NOT list the extension chris@1: in the capabilities list under its registered name. In that case, it chris@1: MAY, but SHOULD NOT, provide a private extension (not listed, or chris@1: listed with a different name) that implements part of the extension chris@1: or implements the commands of the extension with a different meaning. chris@1: chris@1: A server MUST NOT send different response codes to basic NNTP chris@1: commands documented here or to commands documented in registered chris@1: extensions in response to the availability or use of a private chris@1: extension. chris@1: chris@1: 3.3.4. Initial IANA Register chris@1: chris@1: IANA will maintain a registry of NNTP capability labels. All chris@1: capability labels in the registry MUST be keywords and MUST NOT begin chris@1: with X. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 18] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: The initial content of the registry consists of these entries: chris@1: chris@1: +-------------------+--------------------------+--------------------+ chris@1: | Label | Meaning | Definition | chris@1: +-------------------+--------------------------+--------------------+ chris@1: | AUTHINFO | Authentication | [NNTP-AUTH] | chris@1: | | | | chris@1: | HDR | Batched header retrieval | Section 3.3.2, | chris@1: | | | Section 8.5, and | chris@1: | | | Section 8.6 | chris@1: | | | | chris@1: | IHAVE | IHAVE command available | Section 3.3.2 and | chris@1: | | | Section 6.3.2 | chris@1: | | | | chris@1: | IMPLEMENTATION | Server | Section 3.3.2 | chris@1: | | implementation-specific | | chris@1: | | information | | chris@1: | | | | chris@1: | LIST | LIST command variants | Section 3.3.2 and | chris@1: | | | Section 7.6.1 | chris@1: | | | | chris@1: | MODE-READER | Mode-switching server | Section 3.4.2 | chris@1: | | and MODE READER command | | chris@1: | | available | | chris@1: | | | | chris@1: | NEWNEWS | NEWNEWS command | Section 3.3.2 and | chris@1: | | available | Section 7.4 | chris@1: | | | | chris@1: | OVER | Overview support | Section 3.3.2, | chris@1: | | | Section 8.3, and | chris@1: | | | Section 8.4 | chris@1: | | | | chris@1: | POST | POST command available | Section 3.3.2 and | chris@1: | | | Section 6.3.1 | chris@1: | | | | chris@1: | READER | Reader commands | Section 3.3.2 | chris@1: | | available | | chris@1: | | | | chris@1: | SASL | Supported SASL | [NNTP-AUTH] | chris@1: | | mechanisms | | chris@1: | | | | chris@1: | STARTTLS | Transport layer security | [NNTP-TLS] | chris@1: | | | | chris@1: | STREAMING | Streaming feeds | [NNTP-STREAM] | chris@1: | | | | chris@1: | VERSION | Supported NNTP versions | Section 3.3.2 | chris@1: +-------------------+--------------------------+--------------------+ chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 19] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 3.4. Mandatory and Optional Commands chris@1: chris@1: For a number of reasons, not all the commands in this specification chris@1: are mandatory. However, it is equally undesirable for every command chris@1: to be optional, since this means that a client will have no idea what chris@1: facilities are available. Therefore, as a compromise, some of the chris@1: commands in this specification are mandatory (they must be supported chris@1: by all servers) while the remainder are not. The latter are then chris@1: subdivided into bundles, each indicated by a single capability label. chris@1: chris@1: o If the label is included in the capability list returned by the chris@1: server, the server MUST support all commands in that bundle. chris@1: chris@1: o If the label is not included, the server MAY support none or some chris@1: of the commands but SHOULD NOT support all of them. In general, chris@1: there will be no way for a client to determine which commands are chris@1: supported without trying them. chris@1: chris@1: The bundles have been chosen to provide useful functionality, and chris@1: therefore server authors are discouraged from implementing only part chris@1: of a bundle. chris@1: chris@1: The description of each command will either indicate that it is chris@1: mandatory, or will give, using the term "indicating capability", the chris@1: capability label indicating whether the bundle including this command chris@1: is available. chris@1: chris@1: Where a server does not implement a command, it MUST always generate chris@1: a 500 generic response code (or a 501 generic response code in the chris@1: case of a variant of a command depending on a second keyword where chris@1: the base command is recognised). Otherwise, the command MUST be chris@1: fully implemented as specified; a server MUST NOT only partially chris@1: implement any of the commands in this specification. (Client authors chris@1: should note that some servers not conforming to this specification chris@1: will return a 502 generic response code to some commands that are not chris@1: implemented.) chris@1: chris@1: Note: some commands have cases that require other commands to be used chris@1: first. If the former command is implemented but the latter is not, chris@1: the former MUST still generate the relevant specific response code. chris@1: For example, if ARTICLE (Section 6.2.1) is implemented but GROUP chris@1: (Section 6.1.1) is not, the correct response to "ARTICLE 1234" chris@1: remains 412. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 20] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 3.4.1. Reading and Transit Servers chris@1: chris@1: NNTP is traditionally used in two different ways. The first use is chris@1: "reading", where the client fetches articles from a large store chris@1: maintained by the server for immediate or later presentation to a chris@1: user and sends articles created by that user back to the server (an chris@1: action called "posting") to be stored and distributed to other stores chris@1: and users. The second use is for the bulk transfer of articles from chris@1: one store to another. Since the hosts making this transfer tend to chris@1: be peers in a network that transmit articles among one another, and chris@1: not end-user systems, this process is called "peering" or "transit". chris@1: (Even so, one host is still the client and the other is the server). chris@1: chris@1: In practice, these two uses are so different that some server chris@1: implementations are optimised for reading or for transit and, as a chris@1: result, do not offer the other facility or only offer limited chris@1: features. Other implementations are more general and offer both. chris@1: This specification allows for this by bundling the relevant commands chris@1: accordingly: the IHAVE command is designed for transit, while the chris@1: commands indicated by the READER capability are designed for reading chris@1: clients. chris@1: chris@1: Except as an effect of the MODE READER command (Section 5.3) on a chris@1: mode-switching server, once a server advertises either or both of the chris@1: IHAVE or READER capabilities, it MUST continue to advertise them for chris@1: the entire session. chris@1: chris@1: A server MAY provide different modes of behaviour (transit, reader, chris@1: or a combination) to different client connections and MAY use chris@1: external information, such as the IP address of the client, to chris@1: determine which mode to provide to any given connection. chris@1: chris@1: The official TCP port for the NNTP service is 119. However, if a chris@1: host wishes to offer separate servers for transit and reading chris@1: clients, port 433 SHOULD be used for the transit server and 119 for chris@1: the reading server. chris@1: chris@1: 3.4.2. Mode Switching chris@1: chris@1: An implementation MAY, but SHOULD NOT, provide both transit and chris@1: reader facilities on the same server but require the client to select chris@1: which it wishes to use. Such an arrangement is called a chris@1: "mode-switching" server. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 21] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: A mode-switching server has two modes: chris@1: chris@1: o Transit mode, which applies after the initial connection. chris@1: chris@1: * It MUST advertise the MODE-READER capability. chris@1: chris@1: * It MUST NOT advertise the READER capability. chris@1: chris@1: However, the server MAY cease to advertise the MODE-READER chris@1: capability after the client uses any command except CAPABILITIES. chris@1: chris@1: o Reading mode, after a successful MODE READER command (see Section chris@1: 5.3). chris@1: chris@1: * It MUST NOT advertise the MODE-READER capability. chris@1: chris@1: * It MUST advertise the READER capability. chris@1: chris@1: * It MAY NOT advertise the IHAVE capability, even if it was chris@1: advertising it in transit mode. chris@1: chris@1: A client SHOULD only issue a MODE READER command to a server if it is chris@1: advertising the MODE-READER capability. If the server does not chris@1: support CAPABILITIES (and therefore does not conform to this chris@1: specification), the client MAY use the following heuristic: chris@1: chris@1: o If the client wishes to use any "reader" commands, it SHOULD use chris@1: the MODE READER command immediately after the initial connection. chris@1: chris@1: o Otherwise, it SHOULD NOT use the MODE READER command. chris@1: chris@1: In each case, it should be prepared for some commands to be chris@1: unavailable that would have been available if it had made the other chris@1: choice. chris@1: chris@1: 3.5. Pipelining chris@1: chris@1: NNTP is designed to operate over a reliable bi-directional chris@1: connection, such as TCP. Therefore, if a command does not depend on chris@1: the response to the previous one, it should not matter if it is sent chris@1: before that response is received. Doing this is called "pipelining". chris@1: However, certain server implementations throw away all text received chris@1: from the client following certain commands before sending their chris@1: response. If this happens, pipelining will be affected because one chris@1: or more commands will have been ignored or misinterpreted, and the chris@1: client will be matching the wrong responses to each command. Since chris@1: there are significant benefits to pipelining, but also circumstances chris@1: where it is reasonable or common for servers to behave in the above chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 22] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: manner, this document puts certain requirements on both clients and chris@1: servers. chris@1: chris@1: Except where stated otherwise, a client MAY use pipelining. That is, chris@1: it may send a command before receiving the response for the previous chris@1: command. The server MUST allow pipelining and MUST NOT throw away chris@1: any text received after a command. Irrespective of whether chris@1: pipelining is used, the server MUST process commands in the order chris@1: they are sent. chris@1: chris@1: If the specific description of a command says it "MUST NOT be chris@1: pipelined", that command MUST end any pipeline of commands. That is, chris@1: the client MUST NOT send any following command until it receives the chris@1: CRLF at the end of the response from the command. The server MAY chris@1: ignore any data received after the command and before the CRLF at the chris@1: end of the response is sent to the client. chris@1: chris@1: The initial connection must not be part of a pipeline; that is, the chris@1: client MUST NOT send any command until it receives the CRLF at the chris@1: end of the greeting. chris@1: chris@1: If the client uses blocking system calls to send commands, it MUST chris@1: ensure that the amount of text sent in pipelining does not cause a chris@1: deadlock between transmission and reception. The amount of text chris@1: involved will depend on window sizes in the transmission layer; chris@1: typically, it is 4k octets for TCP. (Since the server only sends chris@1: data in response to commands from the client, the converse problem chris@1: does not occur.) chris@1: chris@1: 3.5.1. Examples chris@1: chris@1: Example of correct use of pipelining: chris@1: chris@1: [C] GROUP misc.test chris@1: [C] STAT chris@1: [C] NEXT chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [S] 223 3000234 <45223423@example.com> retrieved chris@1: [S] 223 3000237 <668929@example.org> retrieved chris@1: chris@1: Example of incorrect use of pipelining (the MODE READER command may chris@1: not be pipelined): chris@1: chris@1: [C] MODE READER chris@1: [C] DATE chris@1: [C] NEXT chris@1: [S] 200 Server ready, posting allowed chris@1: [S] 223 3000237 <668929@example.org> retrieved chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 23] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: The DATE command has been thrown away by the server, so there is no chris@1: 111 response to match it. chris@1: chris@1: 3.6. Articles chris@1: chris@1: NNTP is intended to transfer articles between clients and servers. chris@1: For the purposes of this specification, articles are required to chris@1: conform to the rules in this section, and clients and servers MUST chris@1: correctly process any article received from the other that does so. chris@1: Note that this requirement applies only to the contents of chris@1: communications over NNTP; it does not prevent the client or server chris@1: from subsequently rejecting an article for reasons of local policy. chris@1: Also see Appendix A for further restrictions on the format of chris@1: articles in some uses of NNTP. chris@1: chris@1: An article consists of two parts: the headers and the body. They are chris@1: separated by a single empty line, or in other words by two chris@1: consecutive CRLF pairs (if there is more than one empty line, the chris@1: second and subsequent ones are part of the body). In order to meet chris@1: the general requirements of NNTP, an article MUST NOT include the chris@1: octet NUL, MUST NOT contain the octets LF and CR other than as part chris@1: of a CRLF pair, and MUST end with a CRLF pair. This specification chris@1: puts no further restrictions on the body; in particular, it MAY be chris@1: empty. chris@1: chris@1: The headers of an article consist of one or more header lines. Each chris@1: header line consists of a header name, a colon, a space, the header chris@1: content, and a CRLF, in that order. The name consists of one or more chris@1: printable US-ASCII characters other than colon and, for the purposes chris@1: of this specification, is not case sensitive. There MAY be more than chris@1: one header line with the same name. The content MUST NOT contain chris@1: CRLF; it MAY be empty. A header may be "folded"; that is, a CRLF chris@1: pair may be placed before any TAB or space in the line. There MUST chris@1: still be some other octet between any two CRLF pairs in a header chris@1: line. (Note that folding means that the header line occupies more chris@1: than one line when displayed or transmitted; nevertheless, it is chris@1: still referred to as "a" header line.) The presence or absence of chris@1: folding does not affect the meaning of the header line; that is, the chris@1: CRLF pairs introduced by folding are not considered part of the chris@1: header content. Header lines SHOULD NOT be folded before the space chris@1: after the colon that follows the header name and SHOULD include at chris@1: least one octet other than %x09 or %x20 between CRLF pairs. However, chris@1: if an article that fails to satisfy this requirement has been chris@1: received from elsewhere, clients and servers MAY transfer it to each chris@1: other without re-folding it. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 24] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: The content of a header SHOULD be in UTF-8. However, if an chris@1: implementation receives an article from elsewhere that uses octets in chris@1: the range 128 to 255 in some other manner, it MAY pass it to a client chris@1: or server without modification. Therefore, implementations MUST be chris@1: prepared to receive such headers, and data derived from them (e.g., chris@1: in the responses from the OVER command, Section 8.3), and MUST NOT chris@1: assume that they are always UTF-8. Any external processing of those chris@1: headers, including identifying the encoding used, is outside the chris@1: scope of this document. chris@1: chris@1: Each article MUST have a unique message-id; two articles offered by chris@1: an NNTP server MUST NOT have the same message-id. For the purposes chris@1: of this specification, message-ids are opaque strings that MUST meet chris@1: the following requirements: chris@1: chris@1: o A message-id MUST begin with "<", end with ">", and MUST NOT chris@1: contain the latter except at the end. chris@1: chris@1: o A message-id MUST be between 3 and 250 octets in length. chris@1: chris@1: o A message-id MUST NOT contain octets other than printable US-ASCII chris@1: characters. chris@1: chris@1: Two message-ids are the same if and only if they consist of the same chris@1: sequence of octets. chris@1: chris@1: This specification does not describe how the message-id of an article chris@1: is determined. If the server does not have any way to determine a chris@1: message-id from the article itself, it MUST synthesize one (this chris@1: specification does not require that the article be changed as a chris@1: result). See also Appendix A.2. chris@1: chris@1: 4. The WILDMAT Format chris@1: chris@1: The WILDMAT format described here is based on the version first chris@1: developed by Rich Salz [SALZ1992], which was in turn derived from the chris@1: format used in the UNIX "find" command to articulate file names. It chris@1: was developed to provide a uniform mechanism for matching patterns in chris@1: the same manner that the UNIX shell matches filenames. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 25] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 4.1. Wildmat Syntax chris@1: chris@1: A wildmat is described by the following ABNF [RFC4234] syntax, which chris@1: is an extract of that in Section 9.8. chris@1: chris@1: wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) chris@1: wildmat-pattern = 1*wildmat-item chris@1: wildmat-item = wildmat-exact / wildmat-wild chris@1: wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / chris@1: UTF8-non-ascii ; exclude ! * , ? [ \ ] chris@1: wildmat-wild = "*" / "?" chris@1: chris@1: Note: the characters ",", "\", "[", and "]" are not allowed in chris@1: wildmats, while * and ? are always wildcards. This should not be a chris@1: problem, since these characters cannot occur in newsgroup names, chris@1: which is the only current use of wildmats. Backslash is commonly chris@1: used to suppress the special meaning of characters, whereas brackets chris@1: are used to introduce sets. However, these usages are not universal, chris@1: and interpretation of these characters in the context of UTF-8 chris@1: strings is potentially complex and differs from existing practice, so chris@1: they were omitted from this specification. A future extension to chris@1: this specification may provide semantics for these characters. chris@1: chris@1: 4.2. Wildmat Semantics chris@1: chris@1: A wildmat is tested against a string and either matches or does not chris@1: match. To do this, each constituent is matched chris@1: against the string, and the rightmost pattern that matches is chris@1: identified. If that is not preceded with "!", the chris@1: whole wildmat matches. If it is preceded by "!", or if no matches, the whole wildmat does not match. chris@1: chris@1: For example, consider the wildmat "a*,!*b,*c*": chris@1: chris@1: o The string "aaa" matches because the rightmost match is with "a*". chris@1: chris@1: o The string "abb" does not match because the rightmost match is chris@1: with "*b". chris@1: chris@1: o The string "ccb" matches because the rightmost match is with chris@1: "*c*". chris@1: chris@1: o The string "xxx" does not match because no chris@1: matches. chris@1: chris@1: A matches a string if the string can be broken into chris@1: components, each of which matches the corresponding in chris@1: the pattern. The matches must be in the same order, and the whole chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 26] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: string must be used in the match. The pattern is "anchored"; that chris@1: is, the first and last characters in the string must match the first chris@1: and last item, respectively (unless that item is an asterisk matching chris@1: zero characters). chris@1: chris@1: A matches the same character (which may be more than chris@1: one octet in UTF-8). chris@1: chris@1: "?" matches exactly one character (which may be more than one octet). chris@1: chris@1: "*" matches zero or more characters. It can match an empty string, chris@1: but it cannot match a subsequence of a UTF-8 sequence that is not chris@1: aligned to the character boundaries. chris@1: chris@1: 4.3. Extensions chris@1: chris@1: An NNTP server or extension MAY extend the syntax or semantics of chris@1: wildmats provided that all wildmats that meet the requirements of chris@1: Section 4.1 have the meaning ascribed to them by Section 4.2. Future chris@1: editions of this document may also extend wildmats. chris@1: chris@1: 4.4. Examples chris@1: chris@1: In these examples, $ and @ are used to represent the two octets %xC2 chris@1: and %xA3, respectively; $@ is thus the UTF-8 encoding for the pound chris@1: sterling symbol, shown as # in the descriptions. chris@1: chris@1: Wildmat Description of strings that match chris@1: abc The one string "abc" chris@1: abc,def The two strings "abc" and "def" chris@1: $@ The one character string "#" chris@1: a* Any string that begins with "a" chris@1: a*b Any string that begins with "a" and ends with "b" chris@1: a*,*b Any string that begins with "a" or ends with "b" chris@1: a*,!*b Any string that begins with "a" and does not end with chris@1: "b" chris@1: a*,!*b,c* Any string that begins with "a" and does not end with chris@1: "b", and any string that begins with "c" no matter chris@1: what it ends with chris@1: a*,c*,!*b Any string that begins with "a" or "c" and does not chris@1: end with "b" chris@1: ?a* Any string with "a" as its second character chris@1: ??a* Any string with "a" as its third character chris@1: *a? Any string with "a" as its penultimate character chris@1: *a?? Any string with "a" as its antepenultimate character chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 27] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 5. Session Administration Commands chris@1: chris@1: 5.1. Initial Connection chris@1: chris@1: 5.1.1. Usage chris@1: chris@1: This command MUST NOT be pipelined. chris@1: chris@1: Responses [1] chris@1: 200 Service available, posting allowed chris@1: 201 Service available, posting prohibited chris@1: 400 Service temporarily unavailable [2] chris@1: 502 Service permanently unavailable [2] chris@1: chris@1: [1] These are the only valid response codes for the initial greeting; chris@1: the server MUST not return any other generic response code. chris@1: chris@1: [2] Following a 400 or 502 response, the server MUST immediately chris@1: close the connection. chris@1: chris@1: 5.1.2. Description chris@1: chris@1: There is no command presented by the client upon initial connection chris@1: to the server. The server MUST present an appropriate response code chris@1: as a greeting to the client. This response informs the client chris@1: whether service is available and whether the client is permitted to chris@1: post. chris@1: chris@1: If the server will accept further commands from the client including chris@1: POST, the server MUST present a 200 greeting code. If the server chris@1: will accept further commands from the client, but the client is not chris@1: authorized to post articles using the POST command, the server MUST chris@1: present a 201 greeting code. chris@1: chris@1: Otherwise, the server MUST present a 400 or 502 greeting code and chris@1: then immediately close the connection. 400 SHOULD be used if the chris@1: issue is only temporary (for example, because of load) and the client chris@1: can expect to be able to connect successfully at some point in the chris@1: future without making any changes. 502 MUST be used if the client is chris@1: not permitted under any circumstances to interact with the server, chris@1: and MAY be used if the server has insufficient information to chris@1: determine whether the issue is temporary or permanent. chris@1: chris@1: Note: the distinction between the 200 and 201 response codes has chris@1: turned out in practice to be insufficient; for example, some servers chris@1: do not allow posting until the client has authenticated, while other chris@1: clients assume that a 201 response means that posting will never be chris@1: possible even after authentication. Therefore, clients SHOULD use chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 28] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: the CAPABILITIES command (Section 5.2) rather than rely on this chris@1: response. chris@1: chris@1: 5.1.3. Examples chris@1: chris@1: Example of a normal connection from an authorized client that then chris@1: terminates the session (see Section 5.4): chris@1: chris@1: [Initial connection set-up completed.] chris@1: [S] 200 NNTP Service Ready, posting permitted chris@1: [C] QUIT chris@1: [S] 205 NNTP Service exits normally chris@1: [Server closes connection.] chris@1: chris@1: Example of a normal connection from an authorized client that is not chris@1: permitted to post, which also immediately terminates the session: chris@1: chris@1: [Initial connection set-up completed.] chris@1: [S] 201 NNTP Service Ready, posting prohibited chris@1: [C] QUIT chris@1: [S] 205 NNTP Service exits normally chris@1: [Server closes connection.] chris@1: chris@1: Example of a normal connection from an unauthorized client: chris@1: chris@1: [Initial connection set-up completed.] chris@1: [S] 502 NNTP Service permanently unavailable chris@1: [Server closes connection.] chris@1: chris@1: Example of a connection from a client if the server is unable to chris@1: provide service: chris@1: chris@1: [Initial connection set-up completed.] chris@1: [S] 400 NNTP Service temporarily unavailable chris@1: [Server closes connection.] chris@1: chris@1: 5.2. CAPABILITIES chris@1: chris@1: 5.2.1. Usage chris@1: chris@1: This command is mandatory. chris@1: chris@1: Syntax chris@1: CAPABILITIES [keyword] chris@1: chris@1: Responses chris@1: 101 Capability list follows (multi-line) chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 29] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Parameters chris@1: keyword additional feature, see description chris@1: chris@1: 5.2.2. Description chris@1: chris@1: The CAPABILITIES command allows a client to determine the chris@1: capabilities of the server at any given time. chris@1: chris@1: This command MAY be issued at any time; the server MUST NOT require chris@1: it to be issued in order to make use of any capability. The response chris@1: generated by this command MAY change during a session because of chris@1: other state information (which, in turn, may be changed by the chris@1: effects of other commands or by external events). An NNTP client is chris@1: only able to get the current and correct information concerning chris@1: available capabilities at any point during a session by issuing a chris@1: CAPABILITIES command at that point of that session and processing the chris@1: response. chris@1: chris@1: The capability list is returned as a multi-line data block following chris@1: the 101 response code. Each capability is described by a separate chris@1: capability line. The server MUST NOT list the same capability twice chris@1: in the response, even with different arguments. Except that the chris@1: VERSION capability MUST be the first line, the order in which the chris@1: capability lines appears is not significant; the server need not even chris@1: consistently return the same order. chris@1: chris@1: While some capabilities are likely to be always available or never chris@1: available, others (notably extensions) will appear and disappear chris@1: depending on server state changes within the session or on external chris@1: events between sessions. An NNTP client MAY cache the results of chris@1: this command, but MUST NOT rely on the correctness of any cached chris@1: results, whether from earlier in this session or from a previous chris@1: session, MUST cope gracefully with the cached status being out of chris@1: date, and SHOULD (if caching results) provide a way to force the chris@1: cached information to be refreshed. Furthermore, a client MUST NOT chris@1: use cached results in relation to security, privacy, and chris@1: authentication extensions. See Section 12.6 for further discussion chris@1: of this topic. chris@1: chris@1: The keyword argument is not used by this specification. It is chris@1: provided so that extensions or revisions to this specification can chris@1: include extra features for this command without requiring the chris@1: CAPABILITIES command to be used twice (once to determine if the extra chris@1: features are available, and a second time to make use of them). If chris@1: the server does not recognise the argument (and it is a keyword), it chris@1: MUST respond with the 101 response code as if the argument had been chris@1: omitted. If an argument is provided that the server does recognise, chris@1: it MAY use the 101 response code or MAY use some other response code chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 30] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: (which will be defined in the specification of that feature). If the chris@1: argument is not a keyword, the 501 generic response code MUST be chris@1: returned. The server MUST NOT generate any other response code to chris@1: the CAPABILITIES command. chris@1: chris@1: 5.2.3. Examples chris@1: chris@1: Example of a minimal response (a read-only server): chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] LIST ACTIVE NEWSGROUPS chris@1: [S] . chris@1: chris@1: Example of a response from a server that has a range of facilities chris@1: and that also describes itself: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] IHAVE chris@1: [S] POST chris@1: [S] NEWNEWS chris@1: [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES OVERVIEW.FMT chris@1: [S] IMPLEMENTATION INN 4.2 2004-12-25 chris@1: [S] OVER MSGID chris@1: [S] STREAMING chris@1: [S] XSECRET chris@1: [S] . chris@1: chris@1: Example of a server that supports more than one version of NNTP: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 3 chris@1: [S] READER chris@1: [S] LIST ACTIVE NEWSGROUPS chris@1: [S] . chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 31] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of a client attempting to use a feature of the CAPABILITIES chris@1: command that the server does not support: chris@1: chris@1: [C] CAPABILITIES AUTOUPDATE chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] IHAVE chris@1: [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT HEADERS chris@1: [S] OVER MSGID chris@1: [S] HDR chris@1: [S] NEWNEWS chris@1: [S] . chris@1: chris@1: 5.3. MODE READER chris@1: chris@1: 5.3.1. Usage chris@1: chris@1: Indicating capability: MODE-READER chris@1: chris@1: This command MUST NOT be pipelined. chris@1: chris@1: Syntax chris@1: MODE READER chris@1: chris@1: Responses chris@1: 200 Posting allowed chris@1: 201 Posting prohibited chris@1: 502 Reading service permanently unavailable [1] chris@1: chris@1: [1] Following a 502 response the server MUST immediately close the chris@1: connection. chris@1: chris@1: 5.3.2. Description chris@1: chris@1: The MODE READER command instructs a mode-switching server to switch chris@1: modes, as described in Section 3.4.2. chris@1: chris@1: If the server is mode-switching, it switches from its transit mode to chris@1: its reader mode, indicating this by changing the capability list chris@1: accordingly. It MUST then return a 200 or 201 response with the same chris@1: meaning as for the initial greeting (as described in Section 5.1.1). chris@1: Note that the response need not be the same as that presented during chris@1: the initial greeting. The client MUST NOT issue MODE READER more chris@1: than once in a session or after any security or privacy commands are chris@1: issued. When the MODE READER command is issued, the server MAY reset chris@1: its state to that immediately after the initial connection before chris@1: switching mode. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 32] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: If the server is not mode-switching, then the following apply: chris@1: chris@1: o If it advertises the READER capability, it MUST return a 200 or chris@1: 201 response with the same meaning as for the initial greeting; in chris@1: this case, the command MUST NOT affect the server state in any chris@1: way. chris@1: chris@1: o If it does not advertise the READER capability, it MUST return a chris@1: 502 response and then immediately close the connection. chris@1: chris@1: 5.3.3. Examples chris@1: chris@1: Example of use of the MODE READER command on a transit-only server chris@1: (which therefore does not providing reading facilities): chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] IHAVE chris@1: [S] . chris@1: [C] MODE READER chris@1: [S] 502 Transit service only chris@1: [Server closes connection.] chris@1: chris@1: Example of use of the MODE READER command on a server that provides chris@1: reading facilities: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] LIST ACTIVE NEWSGROUPS chris@1: [S] . chris@1: [C] MODE READER chris@1: [S] 200 Reader mode, posting permitted chris@1: [C] IHAVE chris@1: [S] 500 Permission denied chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: chris@1: Note that in both of these situations, the client SHOULD NOT use MODE chris@1: READER. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 33] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of use of the MODE READER command on a mode-switching server: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] IHAVE chris@1: [S] MODE-READER chris@1: [S] . chris@1: [C] MODE READER chris@1: [S] 200 Reader mode, posting permitted chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] NEWNEWS chris@1: [S] LIST ACTIVE NEWSGROUPS chris@1: [S] STARTTLS chris@1: [S] . chris@1: chris@1: In this case, the server offers (but does not require) TLS privacy in chris@1: its reading mode but not in its transit mode. chris@1: chris@1: Example of use of the MODE READER command where the client is not chris@1: permitted to post: chris@1: chris@1: [C] MODE READER chris@1: [S] 201 NNTP Service Ready, posting prohibited chris@1: chris@1: 5.4. QUIT chris@1: chris@1: 5.4.1. Usage chris@1: chris@1: This command is mandatory. chris@1: chris@1: Syntax chris@1: QUIT chris@1: chris@1: Responses chris@1: 205 Connection closing chris@1: chris@1: 5.4.2. Description chris@1: chris@1: The client uses the QUIT command to terminate the session. The chris@1: server MUST acknowledge the QUIT command and then close the chris@1: connection to the client. This is the preferred method for a client chris@1: to indicate that it has finished all of its transactions with the chris@1: NNTP server. chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 34] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: If a client simply disconnects (or if the connection times out or chris@1: some other fault occurs), the server MUST gracefully cease its chris@1: attempts to service the client, disconnecting from its end if chris@1: necessary. chris@1: chris@1: The server MUST NOT generate any response code to the QUIT command chris@1: other than 205 or, if any arguments are provided, 501. chris@1: chris@1: 5.4.3. Examples chris@1: chris@1: [C] QUIT chris@1: [S] 205 closing connection chris@1: [Server closes connection.] chris@1: chris@1: 6. Article Posting and Retrieval chris@1: chris@1: News-reading clients have available a variety of mechanisms to chris@1: retrieve articles via NNTP. The news articles are stored and indexed chris@1: using three types of keys. The first type of key is the message-id chris@1: of an article and is globally unique. The second type of key is chris@1: composed of a newsgroup name and an article number within that chris@1: newsgroup. On a particular server, there MUST only be one article chris@1: with a given number within any newsgroup, and an article MUST NOT chris@1: have two different numbers in the same newsgroup. An article can be chris@1: cross-posted to multiple newsgroups, so there may be multiple keys chris@1: that point to the same article on the same server; these MAY have chris@1: different numbers in each newsgroup. However, this type of key is chris@1: not required to be globally unique, so the same key MAY refer to chris@1: different articles on different servers. (Note that the terms chris@1: "group" and "newsgroup" are equivalent.) chris@1: chris@1: The final type of key is the arrival timestamp, giving the time that chris@1: the article arrived at the server. The server MUST ensure that chris@1: article numbers are issued in order of arrival timestamp; that is, chris@1: articles arriving later MUST have higher numbers than those that chris@1: arrive earlier. The server SHOULD allocate the next sequential chris@1: unused number to each new article. chris@1: chris@1: Article numbers MUST lie between 1 and 2,147,483,647, inclusive. The chris@1: client and server MAY use leading zeroes in specifying article chris@1: numbers but MUST NOT use more than 16 digits. In some situations, chris@1: the value zero replaces an article number to show some special chris@1: situation. chris@1: chris@1: Note that it is likely that the article number limit of 2,147,483,647 chris@1: will be increased by a future revision or extension to this chris@1: specification. While servers MUST NOT send article numbers greater chris@1: than this current limit, client and server developers are advised to chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 35] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: use internal structures and datatypes capable of handling larger chris@1: values in anticipation of such a change. chris@1: chris@1: 6.1. Group and Article Selection chris@1: chris@1: The following commands are used to set the "currently selected chris@1: newsgroup" and the "current article number", which are used by chris@1: various commands. At the start of an NNTP session, both of these chris@1: values are set to the special value "invalid". chris@1: chris@1: 6.1.1. GROUP chris@1: chris@1: 6.1.1.1. Usage chris@1: chris@1: Indicating capability: READER chris@1: chris@1: Syntax chris@1: GROUP group chris@1: chris@1: Responses chris@1: 211 number low high group Group successfully selected chris@1: 411 No such newsgroup chris@1: chris@1: Parameters chris@1: group Name of newsgroup chris@1: number Estimated number of articles in the group chris@1: low Reported low water mark chris@1: high Reported high water mark chris@1: chris@1: 6.1.1.2. Description chris@1: chris@1: The GROUP command selects a newsgroup as the currently selected chris@1: newsgroup and returns summary information about it. chris@1: chris@1: The required argument is the name of the newsgroup to be selected chris@1: (e.g., "news.software.nntp"). A list of valid newsgroups may be chris@1: obtained by using the LIST ACTIVE command (see Section 7.6.3). chris@1: chris@1: The successful selection response will return the article numbers of chris@1: the first and last articles in the group at the moment of selection chris@1: (these numbers are referred to as the "reported low water mark" and chris@1: the "reported high water mark") and an estimate of the number of chris@1: articles in the group currently available. chris@1: chris@1: If the group is not empty, the estimate MUST be at least the actual chris@1: number of articles available and MUST be no greater than one more chris@1: than the difference between the reported low and high water marks. chris@1: (Some implementations will actually count the number of articles chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 36] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: currently stored. Others will just subtract the low water mark from chris@1: the high water mark and add one to get an estimate.) chris@1: chris@1: If the group is empty, one of the following three situations will chris@1: occur. Clients MUST accept all three cases; servers MUST NOT chris@1: represent an empty group in any other way. chris@1: chris@1: o The high water mark will be one less than the low water mark, and chris@1: the estimated article count will be zero. Servers SHOULD use this chris@1: method to show an empty group. This is the only time that the chris@1: high water mark can be less than the low water mark. chris@1: chris@1: o All three numbers will be zero. chris@1: chris@1: o The high water mark is greater than or equal to the low water chris@1: mark. The estimated article count might be zero or non-zero; if chris@1: it is non-zero, the same requirements apply as for a non-empty chris@1: group. chris@1: chris@1: The set of articles in a group may change after the GROUP command is chris@1: carried out: chris@1: chris@1: o Articles may be removed from the group. chris@1: chris@1: o Articles may be reinstated in the group with the same article chris@1: number, but those articles MUST have numbers no less than the chris@1: reported low water mark (note that this is a reinstatement of the chris@1: previous article, not a new article reusing the number). chris@1: chris@1: o New articles may be added with article numbers greater than the chris@1: reported high water mark. (If an article that was the one with chris@1: the highest number has been removed and the high water mark has chris@1: been adjusted accordingly, the next new article will not have the chris@1: number one greater than the reported high water mark.) chris@1: chris@1: Except when the group is empty and all three numbers are zero, chris@1: whenever a subsequent GROUP command for the same newsgroup is issued, chris@1: either by the same client or a different client, the reported low chris@1: water mark in the response MUST be no less than that in any previous chris@1: response for that newsgroup in this session, and it SHOULD be no less chris@1: than that in any previous response for that newsgroup ever sent to chris@1: any client. Any failure to meet the latter condition SHOULD be chris@1: transient only. The client may make use of the low water mark to chris@1: remove all remembered information about articles with lower numbers, chris@1: as these will never recur. This includes the situation when the high chris@1: water mark is one less than the low water mark. No similar chris@1: assumption can be made about the high water mark, as this can chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 37] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: decrease if an article is removed and then increase again if it is chris@1: reinstated or if new articles arrive. chris@1: chris@1: When a valid group is selected by means of this command, the chris@1: currently selected newsgroup MUST be set to that group, and the chris@1: current article number MUST be set to the first article in the group chris@1: (this applies even if the group is already the currently selected chris@1: newsgroup). If an empty newsgroup is selected, the current article chris@1: number is made invalid. If an invalid group is specified, the chris@1: currently selected newsgroup and current article number MUST NOT be chris@1: changed. chris@1: chris@1: The GROUP or LISTGROUP command (see Section 6.1.2) MUST be used by a chris@1: client, and a successful response received, before any other command chris@1: is used that depends on the value of the currently selected newsgroup chris@1: or current article number. chris@1: chris@1: If the group specified is not available on the server, a 411 response chris@1: MUST be returned. chris@1: chris@1: 6.1.1.3. Examples chris@1: chris@1: Example for a group known to the server: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: chris@1: Example for a group unknown to the server: chris@1: chris@1: [C] GROUP example.is.sob.bradner.or.barber chris@1: [S] 411 example.is.sob.bradner.or.barber is unknown chris@1: chris@1: Example of an empty group using the preferred response: chris@1: chris@1: [C] GROUP example.currently.empty.newsgroup chris@1: [S] 211 0 4000 3999 example.currently.empty.newsgroup chris@1: chris@1: Example of an empty group using an alternative response: chris@1: chris@1: [C] GROUP example.currently.empty.newsgroup chris@1: [S] 211 0 0 0 example.currently.empty.newsgroup chris@1: chris@1: Example of an empty group using a different alternative response: chris@1: chris@1: [C] GROUP example.currently.empty.newsgroup chris@1: [S] 211 0 4000 4321 example.currently.empty.newsgroup chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 38] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example reselecting the currently selected newsgroup: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 234 567 misc.test chris@1: [C] STAT 444 chris@1: [S] 223 444 <123456@example.net> retrieved chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 234 567 misc.test chris@1: [C] STAT chris@1: [S] 223 234 retrieved chris@1: chris@1: 6.1.2. LISTGROUP chris@1: chris@1: 6.1.2.1. Usage chris@1: chris@1: Indicating capability: READER chris@1: chris@1: Syntax chris@1: LISTGROUP [group [range]] chris@1: chris@1: Responses chris@1: 211 number low high group Article numbers follow (multi-line) chris@1: 411 No such newsgroup chris@1: 412 No newsgroup selected [1] chris@1: chris@1: Parameters chris@1: group Name of newsgroup chris@1: range Range of articles to report chris@1: number Estimated number of articles in the group chris@1: low Reported low water mark chris@1: high Reported high water mark chris@1: chris@1: [1] The 412 response can only occur if no group has been specified. chris@1: chris@1: 6.1.2.2. Description chris@1: chris@1: The LISTGROUP command selects a newsgroup in the same manner as the chris@1: GROUP command (see Section 6.1.1) but also provides a list of article chris@1: numbers in the newsgroup. If no group is specified, the currently chris@1: selected newsgroup is used. chris@1: chris@1: On success, a list of article numbers is returned as a multi-line chris@1: data block following the 211 response code (the arguments on the chris@1: initial response line are the same as for the GROUP command). The chris@1: list contains one number per line and is in numerical order. It chris@1: lists precisely those articles that exist in the group at the moment chris@1: of selection (therefore, an empty group produces an empty list). If chris@1: the optional range argument is specified, only articles within the chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 39] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: range are included in the list (therefore, the list MAY be empty even chris@1: if the group is not). chris@1: chris@1: The range argument may be any of the following: chris@1: chris@1: o An article number. chris@1: chris@1: o An article number followed by a dash to indicate all following. chris@1: chris@1: o An article number followed by a dash followed by another article chris@1: number. chris@1: chris@1: In the last case, if the second number is less than the first number, chris@1: then the range contains no articles. Omitting the range is chris@1: equivalent to the range 1- being specified. chris@1: chris@1: If the group specified is not available on the server, a 411 response chris@1: MUST be returned. If no group is specified and the currently chris@1: selected newsgroup is invalid, a 412 response MUST be returned. chris@1: chris@1: Except that the group argument is optional, that a range argument can chris@1: be specified, and that a multi-line data block follows the 211 chris@1: response code, the LISTGROUP command is identical to the GROUP chris@1: command. In particular, when successful, the command sets the chris@1: current article number to the first article in the group, if any, chris@1: even if this is not within the range specified by the second chris@1: argument. chris@1: chris@1: Note that the range argument is a new feature in this specification chris@1: and servers that do not support CAPABILITIES (and therefore do not chris@1: conform to this specification) are unlikely to support it. chris@1: chris@1: 6.1.2.3. Examples chris@1: chris@1: Example of LISTGROUP being used to select a group: chris@1: chris@1: [C] LISTGROUP misc.test chris@1: [S] 211 2000 3000234 3002322 misc.test list follows chris@1: [S] 3000234 chris@1: [S] 3000237 chris@1: [S] 3000238 chris@1: [S] 3000239 chris@1: [S] 3002322 chris@1: [S] . chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 40] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of LISTGROUP on an empty group: chris@1: chris@1: [C] LISTGROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup list follows chris@1: [S] . chris@1: chris@1: Example of LISTGROUP on a valid, currently selected newsgroup: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 2000 3000234 3002322 misc.test chris@1: [C] LISTGROUP chris@1: [S] 211 2000 3000234 3002322 misc.test list follows chris@1: [S] 3000234 chris@1: [S] 3000237 chris@1: [S] 3000238 chris@1: [S] 3000239 chris@1: [S] 3002322 chris@1: [S] . chris@1: chris@1: Example of LISTGROUP with a range: chris@1: chris@1: [C] LISTGROUP misc.test 3000238-3000248 chris@1: [S] 211 2000 3000234 3002322 misc.test list follows chris@1: [S] 3000238 chris@1: [S] 3000239 chris@1: [S] . chris@1: chris@1: Example of LISTGROUP with an empty range: chris@1: chris@1: [C] LISTGROUP misc.test 12345678- chris@1: [S] 211 2000 3000234 3002322 misc.test list follows chris@1: [S] . chris@1: chris@1: Example of LISTGROUP with an invalid range: chris@1: chris@1: [C] LISTGROUP misc.test 9999-111 chris@1: [S] 211 2000 3000234 3002322 misc.test list follows chris@1: [S] . chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 41] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 6.1.3. LAST chris@1: chris@1: 6.1.3.1. Usage chris@1: chris@1: Indicating capability: READER chris@1: chris@1: Syntax chris@1: LAST chris@1: chris@1: Responses chris@1: 223 n message-id Article found chris@1: 412 No newsgroup selected chris@1: 420 Current article number is invalid chris@1: 422 No previous article in this group chris@1: chris@1: Parameters chris@1: n Article number chris@1: message-id Article message-id chris@1: chris@1: 6.1.3.2. Description chris@1: chris@1: If the currently selected newsgroup is valid, the current article chris@1: number MUST be set to the previous article in that newsgroup (that chris@1: is, the highest existing article number less than the current article chris@1: number). If successful, a response indicating the new current chris@1: article number and the message-id of that article MUST be returned. chris@1: No article text is sent in response to this command. chris@1: chris@1: There MAY be no previous article in the group, although the current chris@1: article number is not the reported low water mark. There MUST NOT be chris@1: a previous article when the current article number is the reported chris@1: low water mark. chris@1: chris@1: Because articles can be removed and added, the results of multiple chris@1: LAST and NEXT commands MAY not be consistent over the life of a chris@1: particular NNTP session. chris@1: chris@1: If the current article number is already the first article of the chris@1: newsgroup, a 422 response MUST be returned. If the current article chris@1: number is invalid, a 420 response MUST be returned. If the currently chris@1: selected newsgroup is invalid, a 412 response MUST be returned. In chris@1: all three cases, the currently selected newsgroup and current article chris@1: number MUST NOT be altered. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 42] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 6.1.3.3. Examples chris@1: chris@1: Example of a successful article retrieval using LAST: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] NEXT chris@1: [S] 223 3000237 <668929@example.org> retrieved chris@1: [C] LAST chris@1: [S] 223 3000234 <45223423@example.com> retrieved chris@1: chris@1: Example of an attempt to retrieve an article without having selected chris@1: a group (via the GROUP command) first: chris@1: chris@1: [Assumes currently selected newsgroup is invalid.] chris@1: [C] LAST chris@1: [S] 412 no newsgroup selected chris@1: chris@1: Example of an attempt to retrieve an article using the LAST command chris@1: when the current article number is that of the first article in the chris@1: group: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] LAST chris@1: [S] 422 No previous article to retrieve chris@1: chris@1: Example of an attempt to retrieve an article using the LAST command chris@1: when the currently selected newsgroup is empty: chris@1: chris@1: [C] GROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup chris@1: [C] LAST chris@1: [S] 420 No current article selected chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 43] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 6.1.4. NEXT chris@1: chris@1: 6.1.4.1. Usage chris@1: chris@1: Indicating capability: READER chris@1: chris@1: Syntax chris@1: NEXT chris@1: chris@1: Responses chris@1: 223 n message-id Article found chris@1: 412 No newsgroup selected chris@1: 420 Current article number is invalid chris@1: 421 No next article in this group chris@1: chris@1: Parameters chris@1: n Article number chris@1: message-id Article message-id chris@1: chris@1: 6.1.4.2. Description chris@1: chris@1: If the currently selected newsgroup is valid, the current article chris@1: number MUST be set to the next article in that newsgroup (that is, chris@1: the lowest existing article number greater than the current article chris@1: number). If successful, a response indicating the new current chris@1: article number and the message-id of that article MUST be returned. chris@1: No article text is sent in response to this command. chris@1: chris@1: If the current article number is already the last article of the chris@1: newsgroup, a 421 response MUST be returned. In all other aspects chris@1: (apart, of course, from the lack of 422 response), this command is chris@1: identical to the LAST command (Section 6.1.3). chris@1: chris@1: 6.1.4.3. Examples chris@1: chris@1: Example of a successful article retrieval using NEXT: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] NEXT chris@1: [S] 223 3000237 <668929@example.org> retrieved chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 44] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of an attempt to retrieve an article without having selected chris@1: a group (via the GROUP command) first: chris@1: chris@1: [Assumes currently selected newsgroup is invalid.] chris@1: [C] NEXT chris@1: [S] 412 no newsgroup selected chris@1: chris@1: Example of an attempt to retrieve an article using the NEXT command chris@1: when the current article number is that of the last article in the chris@1: group: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] STAT 3002322 chris@1: [S] 223 3002322 <411@example.net> retrieved chris@1: [C] NEXT chris@1: [S] 421 No next article to retrieve chris@1: chris@1: Example of an attempt to retrieve an article using the NEXT command chris@1: when the currently selected newsgroup is empty: chris@1: chris@1: [C] GROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup chris@1: [C] NEXT chris@1: [S] 420 No current article selected chris@1: chris@1: 6.2. Retrieval of Articles and Article Sections chris@1: chris@1: The ARTICLE, BODY, HEAD, and STAT commands are very similar. They chris@1: differ only in the parts of the article that are presented to the chris@1: client and in the successful response code. The ARTICLE command is chris@1: described here in full, while the other three commands are described chris@1: in terms of the differences. As specified in Section 3.6, an article chris@1: consists of two parts: the article headers and the article body. chris@1: chris@1: When responding to one of these commands, the server MUST present the chris@1: entire article or appropriate part and MUST NOT attempt to alter or chris@1: translate it in any way. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 45] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 6.2.1. ARTICLE chris@1: chris@1: 6.2.1.1. Usage chris@1: chris@1: Indicating capability: READER chris@1: chris@1: Syntax chris@1: ARTICLE message-id chris@1: ARTICLE number chris@1: ARTICLE chris@1: chris@1: Responses chris@1: chris@1: First form (message-id specified) chris@1: 220 0|n message-id Article follows (multi-line) chris@1: 430 No article with that message-id chris@1: chris@1: Second form (article number specified) chris@1: 220 n message-id Article follows (multi-line) chris@1: 412 No newsgroup selected chris@1: 423 No article with that number chris@1: chris@1: Third form (current article number used) chris@1: 220 n message-id Article follows (multi-line) chris@1: 412 No newsgroup selected chris@1: 420 Current article number is invalid chris@1: chris@1: Parameters chris@1: number Requested article number chris@1: n Returned article number chris@1: message-id Article message-id chris@1: chris@1: 6.2.1.2. Description chris@1: chris@1: The ARTICLE command selects an article according to the arguments and chris@1: presents the entire article (that is, the headers, an empty line, and chris@1: the body, in that order) to the client. The command has three forms. chris@1: chris@1: In the first form, a message-id is specified, and the server presents chris@1: the article with that message-id. In this case, the server MUST NOT chris@1: alter the currently selected newsgroup or current article number. chris@1: This is both to facilitate the presentation of articles that may be chris@1: referenced within another article being read, and because of the chris@1: semantic difficulties of determining the proper sequence and chris@1: membership of an article that may have been cross-posted to more than chris@1: one newsgroup. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 46] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: In the response, the article number MUST be replaced with zero, chris@1: unless there is a currently selected newsgroup and the article is chris@1: present in that group, in which case the server MAY use the article's chris@1: number in that group. (The server is not required to determine chris@1: whether the article is in the currently selected newsgroup or, if so, chris@1: what article number it has; the client MUST always be prepared for chris@1: zero to be specified.) The server MUST NOT provide an article number chris@1: unless use of that number in a second ARTICLE command immediately chris@1: following this one would return the same article. Even if the server chris@1: chooses to return article numbers in these circumstances, it need not chris@1: do so consistently; it MAY return zero to any such command (also see chris@1: the STAT examples, Section 6.2.4.3). chris@1: chris@1: In the second form, an article number is specified. If there is an chris@1: article with that number in the currently selected newsgroup, the chris@1: server MUST set the current article number to that number. chris@1: chris@1: In the third form, the article indicated by the current article chris@1: number in the currently selected newsgroup is used. chris@1: chris@1: Note that a previously valid article number MAY become invalid if the chris@1: article has been removed. A previously invalid article number MAY chris@1: become valid if the article has been reinstated, but this article chris@1: number MUST be no less than the reported low water mark for that chris@1: group. chris@1: chris@1: The server MUST NOT change the currently selected newsgroup as a chris@1: result of this command. The server MUST NOT change the current chris@1: article number except when an article number argument was provided chris@1: and the article exists; in particular, it MUST NOT change it chris@1: following an unsuccessful response. chris@1: chris@1: Since the message-id is unique for each article, it may be used by a chris@1: client to skip duplicate displays of articles that have been posted chris@1: more than once, or to more than one newsgroup. chris@1: chris@1: The article is returned as a multi-line data block following the 220 chris@1: response code. chris@1: chris@1: If the argument is a message-id and no such article exists, a 430 chris@1: response MUST be returned. If the argument is a number or is omitted chris@1: and the currently selected newsgroup is invalid, a 412 response MUST chris@1: be returned. If the argument is a number and that article does not chris@1: exist in the currently selected newsgroup, a 423 response MUST be chris@1: returned. If the argument is omitted and the current article number chris@1: is invalid, a 420 response MUST be returned. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 47] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 6.2.1.3. Examples chris@1: chris@1: Example of a successful retrieval of an article (explicitly not using chris@1: an article number): chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] ARTICLE chris@1: [S] 220 3000234 <45223423@example.com> chris@1: [S] Path: pathost!demo!whitehouse!not-for-mail chris@1: [S] From: "Demo User" chris@1: [S] Newsgroups: misc.test chris@1: [S] Subject: I am just a test article chris@1: [S] Date: 6 Oct 1998 04:38:40 -0500 chris@1: [S] Organization: An Example Net, Uncertain, Texas chris@1: [S] Message-ID: <45223423@example.com> chris@1: [S] chris@1: [S] This is just a test article. chris@1: [S] . chris@1: chris@1: Example of a successful retrieval of an article by message-id: chris@1: chris@1: [C] ARTICLE <45223423@example.com> chris@1: [S] 220 0 <45223423@example.com> chris@1: [S] Path: pathost!demo!whitehouse!not-for-mail chris@1: [S] From: "Demo User" chris@1: [S] Newsgroups: misc.test chris@1: [S] Subject: I am just a test article chris@1: [S] Date: 6 Oct 1998 04:38:40 -0500 chris@1: [S] Organization: An Example Net, Uncertain, Texas chris@1: [S] Message-ID: <45223423@example.com> chris@1: [S] chris@1: [S] This is just a test article. chris@1: [S] . chris@1: chris@1: Example of an unsuccessful retrieval of an article by message-id: chris@1: chris@1: [C] ARTICLE chris@1: [S] 430 No Such Article Found chris@1: chris@1: Example of an unsuccessful retrieval of an article by number: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 news.groups chris@1: [C] ARTICLE 300256 chris@1: [S] 423 No article with that number chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 48] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of an unsuccessful retrieval of an article by number because chris@1: no newsgroup was selected first: chris@1: chris@1: [Assumes currently selected newsgroup is invalid.] chris@1: [C] ARTICLE 300256 chris@1: [S] 412 No newsgroup selected chris@1: chris@1: Example of an attempt to retrieve an article when the currently chris@1: selected newsgroup is empty: chris@1: chris@1: [C] GROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup chris@1: [C] ARTICLE chris@1: [S] 420 No current article selected chris@1: chris@1: 6.2.2. HEAD chris@1: chris@1: 6.2.2.1. Usage chris@1: chris@1: This command is mandatory. chris@1: chris@1: Syntax chris@1: HEAD message-id chris@1: HEAD number chris@1: HEAD chris@1: chris@1: Responses chris@1: chris@1: First form (message-id specified) chris@1: 221 0|n message-id Headers follow (multi-line) chris@1: 430 No article with that message-id chris@1: chris@1: Second form (article number specified) chris@1: 221 n message-id Headers follow (multi-line) chris@1: 412 No newsgroup selected chris@1: 423 No article with that number chris@1: chris@1: Third form (current article number used) chris@1: 221 n message-id Headers follow (multi-line) chris@1: 412 No newsgroup selected chris@1: 420 Current article number is invalid chris@1: chris@1: Parameters chris@1: number Requested article number chris@1: n Returned article number chris@1: message-id Article message-id chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 49] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 6.2.2.2. Description chris@1: chris@1: The HEAD command behaves identically to the ARTICLE command except chris@1: that, if the article exists, the response code is 221 instead of 220 chris@1: and only the headers are presented (the empty line separating the chris@1: headers and body MUST NOT be included). chris@1: chris@1: 6.2.2.3. Examples chris@1: chris@1: Example of a successful retrieval of the headers of an article chris@1: (explicitly not using an article number): chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] HEAD chris@1: [S] 221 3000234 <45223423@example.com> chris@1: [S] Path: pathost!demo!whitehouse!not-for-mail chris@1: [S] From: "Demo User" chris@1: [S] Newsgroups: misc.test chris@1: [S] Subject: I am just a test article chris@1: [S] Date: 6 Oct 1998 04:38:40 -0500 chris@1: [S] Organization: An Example Net, Uncertain, Texas chris@1: [S] Message-ID: <45223423@example.com> chris@1: [S] . chris@1: chris@1: Example of a successful retrieval of the headers of an article by chris@1: message-id: chris@1: chris@1: [C] HEAD <45223423@example.com> chris@1: [S] 221 0 <45223423@example.com> chris@1: [S] Path: pathost!demo!whitehouse!not-for-mail chris@1: [S] From: "Demo User" chris@1: [S] Newsgroups: misc.test chris@1: [S] Subject: I am just a test article chris@1: [S] Date: 6 Oct 1998 04:38:40 -0500 chris@1: [S] Organization: An Example Net, Uncertain, Texas chris@1: [S] Message-ID: <45223423@example.com> chris@1: [S] . chris@1: chris@1: Example of an unsuccessful retrieval of the headers of an article by chris@1: message-id: chris@1: chris@1: [C] HEAD chris@1: [S] 430 No Such Article Found chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 50] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of an unsuccessful retrieval of the headers of an article by chris@1: number: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] HEAD 300256 chris@1: [S] 423 No article with that number chris@1: chris@1: Example of an unsuccessful retrieval of the headers of an article by chris@1: number because no newsgroup was selected first: chris@1: chris@1: [Assumes currently selected newsgroup is invalid.] chris@1: [C] HEAD 300256 chris@1: [S] 412 No newsgroup selected chris@1: chris@1: Example of an attempt to retrieve the headers of an article when the chris@1: currently selected newsgroup is empty: chris@1: chris@1: [C] GROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup chris@1: [C] HEAD chris@1: [S] 420 No current article selected chris@1: chris@1: 6.2.3. BODY chris@1: chris@1: 6.2.3.1. Usage chris@1: chris@1: Indicating capability: READER chris@1: chris@1: Syntax chris@1: BODY message-id chris@1: BODY number chris@1: BODY chris@1: chris@1: Responses chris@1: chris@1: First form (message-id specified) chris@1: 222 0|n message-id Body follows (multi-line) chris@1: 430 No article with that message-id chris@1: chris@1: Second form (article number specified) chris@1: 222 n message-id Body follows (multi-line) chris@1: 412 No newsgroup selected chris@1: 423 No article with that number chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 51] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Third form (current article number used) chris@1: 222 n message-id Body follows (multi-line) chris@1: 412 No newsgroup selected chris@1: 420 Current article number is invalid chris@1: chris@1: Parameters chris@1: number Requested article number chris@1: n Returned article number chris@1: message-id Article message-id chris@1: chris@1: 6.2.3.2. Description chris@1: chris@1: The BODY command behaves identically to the ARTICLE command except chris@1: that, if the article exists, the response code is 222 instead of 220 chris@1: and only the body is presented (the empty line separating the headers chris@1: and body MUST NOT be included). chris@1: chris@1: 6.2.3.3. Examples chris@1: chris@1: Example of a successful retrieval of the body of an article chris@1: (explicitly not using an article number): chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] BODY chris@1: [S] 222 3000234 <45223423@example.com> chris@1: [S] This is just a test article. chris@1: [S] . chris@1: chris@1: Example of a successful retrieval of the body of an article by chris@1: message-id: chris@1: chris@1: [C] BODY <45223423@example.com> chris@1: [S] 222 0 <45223423@example.com> chris@1: [S] This is just a test article. chris@1: [S] . chris@1: chris@1: Example of an unsuccessful retrieval of the body of an article by chris@1: message-id: chris@1: chris@1: [C] BODY chris@1: [S] 430 No Such Article Found chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 52] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of an unsuccessful retrieval of the body of an article by chris@1: number: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] BODY 300256 chris@1: [S] 423 No article with that number chris@1: chris@1: Example of an unsuccessful retrieval of the body of an article by chris@1: number because no newsgroup was selected first: chris@1: chris@1: [Assumes currently selected newsgroup is invalid.] chris@1: [C] BODY 300256 chris@1: [S] 412 No newsgroup selected chris@1: chris@1: Example of an attempt to retrieve the body of an article when the chris@1: currently selected newsgroup is empty: chris@1: chris@1: [C] GROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup chris@1: [C] BODY chris@1: [S] 420 No current article selected chris@1: chris@1: 6.2.4. STAT chris@1: chris@1: 6.2.4.1. Usage chris@1: chris@1: This command is mandatory. chris@1: chris@1: Syntax chris@1: STAT message-id chris@1: STAT number chris@1: STAT chris@1: chris@1: Responses chris@1: chris@1: First form (message-id specified) chris@1: 223 0|n message-id Article exists chris@1: 430 No article with that message-id chris@1: chris@1: Second form (article number specified) chris@1: 223 n message-id Article exists chris@1: 412 No newsgroup selected chris@1: 423 No article with that number chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 53] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Third form (current article number used) chris@1: 223 n message-id Article exists chris@1: 412 No newsgroup selected chris@1: 420 Current article number is invalid chris@1: chris@1: Parameters chris@1: number Requested article number chris@1: n Returned article number chris@1: message-id Article message-id chris@1: chris@1: 6.2.4.2. Description chris@1: chris@1: The STAT command behaves identically to the ARTICLE command except chris@1: that, if the article exists, it is NOT presented to the client and chris@1: the response code is 223 instead of 220. Note that the response is chris@1: NOT multi-line. chris@1: chris@1: This command allows the client to determine whether an article exists chris@1: and, in the second and third forms, what its message-id is, without chris@1: having to process an arbitrary amount of text. chris@1: chris@1: 6.2.4.3. Examples chris@1: chris@1: Example of STAT on an existing article (explicitly not using an chris@1: article number): chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] STAT chris@1: [S] 223 3000234 <45223423@example.com> chris@1: chris@1: Example of STAT on an existing article by message-id: chris@1: chris@1: [C] STAT <45223423@example.com> chris@1: [S] 223 0 <45223423@example.com> chris@1: chris@1: Example of STAT on an article not on the server by message-id: chris@1: chris@1: [C] STAT chris@1: [S] 430 No Such Article Found chris@1: chris@1: Example of STAT on an article not in the server by number: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] STAT 300256 chris@1: [S] 423 No article with that number chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 54] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of STAT on an article by number when no newsgroup was chris@1: selected first: chris@1: chris@1: [Assumes currently selected newsgroup is invalid.] chris@1: [C] STAT 300256 chris@1: [S] 412 No newsgroup selected chris@1: chris@1: Example of STAT on an article when the currently selected newsgroup chris@1: is empty: chris@1: chris@1: [C] GROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup chris@1: [C] STAT chris@1: [S] 420 No current article selected chris@1: chris@1: Example of STAT by message-id on a server that sometimes reports the chris@1: actual article number: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] STAT chris@1: [S] 223 3000234 <45223423@example.com> chris@1: [C] STAT <45223423@example.com> chris@1: [S] 223 0 <45223423@example.com> chris@1: [C] STAT <45223423@example.com> chris@1: [S] 223 3000234 <45223423@example.com> chris@1: [C] GROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup chris@1: [C] STAT <45223423@example.com> chris@1: [S] 223 0 <45223423@example.com> chris@1: [C] GROUP alt.crossposts chris@1: [S] 211 9999 111111 222222 alt.crossposts chris@1: [C] STAT <45223423@example.com> chris@1: [S] 223 123456 <45223423@example.com> chris@1: [C] STAT chris@1: [S] 223 111111 <23894720@example.com> chris@1: chris@1: The first STAT command establishes the identity of an article in the chris@1: group. The second and third show that the server may, but need not, chris@1: give the article number when the message-id is specified. The fourth chris@1: STAT command shows that zero must be specified if the article isn't chris@1: in the currently selected newsgroup. The fifth shows that the chris@1: number, if provided, must be that relating to the currently selected chris@1: newsgroup. The last one shows that the current article number is chris@1: still not changed by the use of STAT with a message-id even if it chris@1: returns an article number. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 55] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 6.3. Article Posting chris@1: chris@1: Article posting is done in one of two ways: individual article chris@1: posting from news-reading clients using POST, and article transfer chris@1: from other news servers using IHAVE. chris@1: chris@1: 6.3.1. POST chris@1: chris@1: 6.3.1.1. Usage chris@1: chris@1: Indicating capability: POST chris@1: chris@1: This command MUST NOT be pipelined. chris@1: chris@1: Syntax chris@1: POST chris@1: chris@1: Responses chris@1: chris@1: Initial responses chris@1: 340 Send article to be posted chris@1: 440 Posting not permitted chris@1: chris@1: Subsequent responses chris@1: 240 Article received OK chris@1: 441 Posting failed chris@1: chris@1: 6.3.1.2. Description chris@1: chris@1: If posting is allowed, a 340 response MUST be returned to indicate chris@1: that the article to be posted should be sent. If posting is chris@1: prohibited for some installation-dependent reason, a 440 response chris@1: MUST be returned. chris@1: chris@1: If posting is permitted, the article MUST be in the format specified chris@1: in Section 3.6 and MUST be sent by the client to the server as a chris@1: multi-line data block (see Section 3.1.1). Thus a single dot (".") chris@1: on a line indicates the end of the text, and lines starting with a chris@1: dot in the original text have that dot doubled during transmission. chris@1: chris@1: Following the presentation of the termination sequence by the client, chris@1: the server MUST return a response indicating success or failure of chris@1: the article transfer. Note that response codes 340 and 440 are used chris@1: in direct response to the POST command while 240 and 441 are returned chris@1: after the article is sent. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 56] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: A response of 240 SHOULD indicate that, barring unforeseen server chris@1: errors, the posted article will be made available on the server chris@1: and/or transferred to other servers, as appropriate, possibly chris@1: following further processing. In other words, articles not wanted by chris@1: the server SHOULD be rejected with a 441 response, rather than being chris@1: accepted and then discarded silently. However, the client SHOULD NOT chris@1: assume that the article has been successfully transferred unless it chris@1: receives an affirmative response from the server and SHOULD NOT chris@1: assume that it is being made available to other clients without chris@1: explicitly checking (for example, using the STAT command). chris@1: chris@1: If the session is interrupted before the response is received, it is chris@1: possible that an affirmative response was sent but has been lost. chris@1: Therefore, in any subsequent session, the client SHOULD either check chris@1: whether the article was successfully posted before resending or chris@1: ensure that the server will allocate the same message-id to the new chris@1: attempt (see Appendix A.2). The latter approach is preferred since chris@1: the article might not have been made available for reading yet (for chris@1: example, it may have to go through a moderation process). chris@1: chris@1: 6.3.1.3. Examples chris@1: chris@1: Example of a successful posting: chris@1: chris@1: [C] POST chris@1: [S] 340 Input article; end with . chris@1: [C] From: "Demo User" chris@1: [C] Newsgroups: misc.test chris@1: [C] Subject: I am just a test article chris@1: [C] Organization: An Example Net chris@1: [C] chris@1: [C] This is just a test article. chris@1: [C] . chris@1: [S] 240 Article received OK chris@1: chris@1: Example of an unsuccessful posting: chris@1: chris@1: [C] POST chris@1: [S] 340 Input article; end with . chris@1: [C] From: "Demo User" chris@1: [C] Newsgroups: misc.test chris@1: [C] Subject: I am just a test article chris@1: [C] Organization: An Example Net chris@1: [C] chris@1: [C] This is just a test article. chris@1: [C] . chris@1: [S] 441 Posting failed chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 57] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of an attempt to post when posting is not allowed: chris@1: chris@1: [Initial connection set-up completed.] chris@1: [S] 201 NNTP Service Ready, posting prohibited chris@1: [C] POST chris@1: [S] 440 Posting not permitted chris@1: chris@1: 6.3.2. IHAVE chris@1: chris@1: 6.3.2.1. Usage chris@1: chris@1: Indicating capability: IHAVE chris@1: chris@1: This command MUST NOT be pipelined. chris@1: chris@1: Syntax chris@1: IHAVE message-id chris@1: chris@1: Responses chris@1: chris@1: Initial responses chris@1: 335 Send article to be transferred chris@1: 435 Article not wanted chris@1: 436 Transfer not possible; try again later chris@1: chris@1: Subsequent responses chris@1: 235 Article transferred OK chris@1: 436 Transfer failed; try again later chris@1: 437 Transfer rejected; do not retry chris@1: chris@1: Parameters chris@1: message-id Article message-id chris@1: chris@1: 6.3.2.2. Description chris@1: chris@1: The IHAVE command informs the server that the client has an article chris@1: with the specified message-id. If the server desires a copy of that chris@1: article, a 335 response MUST be returned, instructing the client to chris@1: send the entire article. If the server does not want the article chris@1: (if, for example, the server already has a copy of it), a 435 chris@1: response MUST be returned, indicating that the article is not wanted. chris@1: Finally, if the article isn't wanted immediately but the client chris@1: should retry later if possible (if, for example, another client is in chris@1: the process of sending the same article to the server), a 436 chris@1: response MUST be returned. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 58] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: If transmission of the article is requested, the client MUST send the chris@1: entire article, including headers and body, to the server as a chris@1: multi-line data block (see Section 3.1.1). Thus, a single dot (".") chris@1: on a line indicates the end of the text, and lines starting with a chris@1: dot in the original text have that dot doubled during transmission. chris@1: The server MUST return a 235 response, indicating that the article chris@1: was successfully transferred; a 436 response, indicating that the chris@1: transfer failed but should be tried again later; or a 437 response, chris@1: indicating that the article was rejected. chris@1: chris@1: This function differs from the POST command in that it is intended chris@1: for use in transferring already-posted articles between hosts. It chris@1: SHOULD NOT be used when the client is a personal news-reading chris@1: program, since use of this command indicates that the article has chris@1: already been posted at another site and is simply being forwarded chris@1: from another host. However, despite this, the server MAY elect not chris@1: to post or forward the article if, after further examination of the chris@1: article, it deems it inappropriate to do so. Reasons for such chris@1: subsequent rejection of an article may include problems such as chris@1: inappropriate newsgroups or distributions, disc space limitations, chris@1: article lengths, garbled headers, and the like. These are typically chris@1: restrictions enforced by the server host's news software and not chris@1: necessarily by the NNTP server itself. chris@1: chris@1: The client SHOULD NOT assume that the article has been successfully chris@1: transferred unless it receives an affirmative response from the chris@1: server. A lack of response (such as a dropped network connection or chris@1: a network timeout) SHOULD be treated the same as a 436 response. chris@1: chris@1: Because some news server software may not immediately be able to chris@1: determine whether an article is suitable for posting or forwarding, chris@1: an NNTP server MAY acknowledge the successful transfer of the article chris@1: (with a 235 response) but later silently discard it. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 59] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 6.3.2.3. Examples chris@1: chris@1: Example of successfully sending an article to another site: chris@1: chris@1: [C] IHAVE chris@1: [S] 335 Send it; end with . chris@1: [C] Path: pathost!demo!somewhere!not-for-mail chris@1: [C] From: "Demo User" chris@1: [C] Newsgroups: misc.test chris@1: [C] Subject: I am just a test article chris@1: [C] Date: 6 Oct 1998 04:38:40 -0500 chris@1: [C] Organization: An Example Com, San Jose, CA chris@1: [C] Message-ID: chris@1: [C] chris@1: [C] This is just a test article. chris@1: [C] . chris@1: [S] 235 Article transferred OK chris@1: chris@1: Example of sending an article to another site that rejects it. Note chris@1: that the message-id in the IHAVE command is not the same as the one chris@1: in the article headers; while this is bad practice and SHOULD NOT be chris@1: done, it is not forbidden. chris@1: chris@1: [C] IHAVE chris@1: [S] 335 Send it; end with . chris@1: [C] Path: pathost!demo!somewhere!not-for-mail chris@1: [C] From: "Demo User" chris@1: [C] Newsgroups: misc.test chris@1: [C] Subject: I am just a test article chris@1: [C] Date: 6 Oct 1998 04:38:40 -0500 chris@1: [C] Organization: An Example Com, San Jose, CA chris@1: [C] Message-ID: chris@1: [C] chris@1: [C] This is just a test article. chris@1: [C] . chris@1: [S] 437 Article rejected; don't send again chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 60] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of sending an article to another site where the transfer chris@1: fails: chris@1: chris@1: [C] IHAVE chris@1: [S] 335 Send it; end with . chris@1: [C] Path: pathost!demo!somewhere!not-for-mail chris@1: [C] From: "Demo User" chris@1: [C] Newsgroups: misc.test chris@1: [C] Subject: I am just a test article chris@1: [C] Date: 6 Oct 1998 04:38:40 -0500 chris@1: [C] Organization: An Example Com, San Jose, CA chris@1: [C] Message-ID: chris@1: [C] chris@1: [C] This is just a test article. chris@1: [C] . chris@1: [S] 436 Transfer failed chris@1: chris@1: Example of sending an article to a site that already has it: chris@1: chris@1: [C] IHAVE chris@1: [S] 435 Duplicate chris@1: chris@1: Example of sending an article to a site that requests that the chris@1: article be tried again later: chris@1: chris@1: [C] IHAVE chris@1: [S] 436 Retry later chris@1: chris@1: 7. Information Commands chris@1: chris@1: This section lists other commands that may be used at any time chris@1: between the beginning of a session and its termination. Using these chris@1: commands does not alter any state information, but the response chris@1: generated from their use may provide useful information to clients. chris@1: chris@1: 7.1. DATE chris@1: chris@1: 7.1.1. Usage chris@1: chris@1: Indicating capability: READER chris@1: chris@1: Syntax chris@1: DATE chris@1: chris@1: Responses chris@1: 111 yyyymmddhhmmss Server date and time chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 61] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Parameters chris@1: yyyymmddhhmmss Current UTC date and time on server chris@1: chris@1: 7.1.2. Description chris@1: chris@1: This command exists to help clients find out the current Coordinated chris@1: Universal Time [TF.686-1] from the server's perspective. This chris@1: command SHOULD NOT be used as a substitute for NTP [RFC1305] but to chris@1: provide information that might be useful when using the NEWNEWS chris@1: command (see Section 7.4). chris@1: chris@1: The DATE command MUST return a timestamp from the same clock as is chris@1: used for determining article arrival and group creation times (see chris@1: Section 6). This clock SHOULD be monotonic, and adjustments SHOULD chris@1: be made by running it fast or slow compared to "real" time rather chris@1: than by making sudden jumps. A system providing NNTP service SHOULD chris@1: keep the system clock as accurate as possible, either with NTP or by chris@1: some other method. chris@1: chris@1: The server MUST return a 111 response specifying the date and time on chris@1: the server in the form yyyymmddhhmmss. This date and time is in chris@1: Coordinated Universal Time. chris@1: chris@1: 7.1.3. Examples chris@1: chris@1: [C] DATE chris@1: [S] 111 19990623135624 chris@1: chris@1: 7.2. HELP chris@1: chris@1: 7.2.1. Usage chris@1: chris@1: This command is mandatory. chris@1: chris@1: Syntax chris@1: HELP chris@1: chris@1: Responses chris@1: 100 Help text follows (multi-line) chris@1: chris@1: 7.2.2. Description chris@1: chris@1: This command provides a short summary of the commands that are chris@1: understood by this implementation of the server. The help text will chris@1: be presented as a multi-line data block following the 100 response chris@1: code. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 62] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: This text is not guaranteed to be in any particular format (but must chris@1: be UTF-8) and MUST NOT be used by clients as a replacement for the chris@1: CAPABILITIES command described in Section 5.2. chris@1: chris@1: 7.2.3. Examples chris@1: chris@1: [C] HELP chris@1: [S] 100 Help text follows chris@1: [S] This is some help text. There is no specific chris@1: [S] formatting requirement for this test, though chris@1: [S] it is customary for it to list the valid commands chris@1: [S] and give a brief definition of what they do. chris@1: [S] . chris@1: chris@1: 7.3. NEWGROUPS chris@1: chris@1: 7.3.1. Usage chris@1: chris@1: Indicating capability: READER chris@1: chris@1: Syntax chris@1: NEWGROUPS date time [GMT] chris@1: chris@1: Responses chris@1: 231 List of new newsgroups follows (multi-line) chris@1: chris@1: Parameters chris@1: date Date in yymmdd or yyyymmdd format chris@1: time Time in hhmmss format chris@1: chris@1: 7.3.2. Description chris@1: chris@1: This command returns a list of newsgroups created on the server since chris@1: the specified date and time. The results are in the same format as chris@1: the LIST ACTIVE command (see Section 7.6.3). However, they MAY chris@1: include groups not available on the server (and so not returned by chris@1: LIST ACTIVE) and MAY omit groups for which the creation date is not chris@1: available. chris@1: chris@1: The date is specified as 6 or 8 digits in the format [xx]yymmdd, chris@1: where xx is the first two digits of the year (19-99), yy is the last chris@1: two digits of the year (00-99), mm is the month (01-12), and dd is chris@1: the day of the month (01-31). Clients SHOULD specify all four digits chris@1: of the year. If the first two digits of the year are not specified chris@1: (this is supported only for backward compatibility), the year is to chris@1: be taken from the current century if yy is smaller than or equal to chris@1: the current year, and the previous century otherwise. chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 63] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: The time is specified as 6 digits in the format hhmmss, where hh is chris@1: the hours in the 24-hour clock (00-23), mm is the minutes (00-59), chris@1: and ss is the seconds (00-60, to allow for leap seconds). The token chris@1: "GMT" specifies that the date and time are given in Coordinated chris@1: Universal Time [TF.686-1]; if it is omitted, then the date and time chris@1: are specified in the server's local timezone. Note that there is no chris@1: way of using the protocol specified in this document to establish the chris@1: server's local timezone. chris@1: chris@1: Note that an empty list is a possible valid response and indicates chris@1: that there are no new newsgroups since that date-time. chris@1: chris@1: Clients SHOULD make all queries using Coordinated Universal Time chris@1: (i.e., by including the "GMT" argument) when possible. chris@1: chris@1: 7.3.3. Examples chris@1: chris@1: Example where there are new groups: chris@1: chris@1: [C] NEWGROUPS 19990624 000000 GMT chris@1: [S] 231 list of new newsgroups follows chris@1: [S] alt.rfc-writers.recovery 4 1 y chris@1: [S] tx.natives.recovery 89 56 y chris@1: [S] . chris@1: chris@1: Example where there are no new groups: chris@1: chris@1: [C] NEWGROUPS 19990624 000000 GMT chris@1: [S] 231 list of new newsgroups follows chris@1: [S] . chris@1: chris@1: 7.4. NEWNEWS chris@1: chris@1: 7.4.1. Usage chris@1: chris@1: Indicating capability: NEWNEWS chris@1: chris@1: Syntax chris@1: NEWNEWS wildmat date time [GMT] chris@1: chris@1: Responses chris@1: 230 List of new articles follows (multi-line) chris@1: chris@1: Parameters chris@1: wildmat Newsgroups of interest chris@1: date Date in yymmdd or yyyymmdd format chris@1: time Time in hhmmss format chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 64] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 7.4.2. Description chris@1: chris@1: This command returns a list of message-ids of articles posted or chris@1: received on the server, in the newsgroups whose names match the chris@1: wildmat, since the specified date and time. One message-id is sent chris@1: on each line; the order of the response has no specific significance chris@1: and may vary from response to response in the same session. A chris@1: message-id MAY appear more than once; if it does, it has the same chris@1: meaning as if it appeared only once. chris@1: chris@1: Date and time are in the same format as the NEWGROUPS command (see chris@1: Section 7.3). chris@1: chris@1: Note that an empty list is a possible valid response and indicates chris@1: that there is currently no new news in the relevant groups. chris@1: chris@1: Clients SHOULD make all queries in Coordinated Universal Time (i.e., chris@1: by using the "GMT" argument) when possible. chris@1: chris@1: 7.4.3. Examples chris@1: chris@1: Example where there are new articles: chris@1: chris@1: [C] NEWNEWS news.*,sci.* 19990624 000000 GMT chris@1: [S] 230 list of new articles by message-id follows chris@1: [S] chris@1: [S] chris@1: [S] . chris@1: chris@1: Example where there are no new articles: chris@1: chris@1: [C] NEWNEWS alt.* 19990624 000000 GMT chris@1: [S] 230 list of new articles by message-id follows chris@1: [S] . chris@1: chris@1: 7.5. Time chris@1: chris@1: As described in Section 6, each article has an arrival timestamp. chris@1: Each newsgroup also has a creation timestamp. These timestamps are chris@1: used by the NEWNEWS and NEWGROUP commands to construct their chris@1: responses. chris@1: chris@1: Clients can ensure that they do not have gaps in lists of articles or chris@1: groups by using the DATE command in the following manner: chris@1: chris@1: First session: chris@1: Issue DATE command and record result. chris@1: Issue NEWNEWS command using a previously chosen timestamp. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 65] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Subsequent sessions: chris@1: Issue DATE command and hold result in temporary storage. chris@1: Issue NEWNEWS command using timestamp saved from previous session. chris@1: Overwrite saved timestamp with that currently in temporary chris@1: storage. chris@1: chris@1: In order to allow for minor errors, clients MAY want to adjust the chris@1: timestamp back by two or three minutes before using it in NEWNEWS. chris@1: chris@1: 7.5.1. Examples chris@1: chris@1: First session: chris@1: chris@1: [C] DATE chris@1: [S] 111 20010203112233 chris@1: [C] NEWNEWS local.chat 20001231 235959 GMT chris@1: [S] 230 list follows chris@1: [S] chris@1: [S] chris@1: [S] chris@1: [S] . chris@1: chris@1: Second session (the client has subtracted 3 minutes from the chris@1: timestamp returned previously): chris@1: chris@1: [C] DATE chris@1: [S] 111 20010204003344 chris@1: [C] NEWNEWS local.chat 20010203 111933 GMT chris@1: [S] 230 list follows chris@1: [S] chris@1: [S] chris@1: [S] chris@1: [S] . chris@1: chris@1: Note how arrived in the 3 minute gap and so chris@1: is listed in both responses. chris@1: chris@1: 7.6. The LIST Commands chris@1: chris@1: The LIST family of commands all return information that is multi-line chris@1: and that can, in general, be expected not to change during the chris@1: session. Often the information is related to newsgroups, in which chris@1: case the response has one line per newsgroup and a wildmat MAY be chris@1: provided to restrict the groups for which information is returned. chris@1: chris@1: The set of available keywords (including those provided by chris@1: extensions) is given in the capability list with capability label chris@1: LIST. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 66] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 7.6.1. LIST chris@1: chris@1: 7.6.1.1. Usage chris@1: chris@1: Indicating capability: LIST chris@1: chris@1: Syntax chris@1: LIST [keyword [wildmat|argument]] chris@1: chris@1: Responses chris@1: 215 Information follows (multi-line) chris@1: chris@1: Parameters chris@1: keyword Information requested [1] chris@1: argument Specific to keyword chris@1: wildmat Groups of interest chris@1: chris@1: [1] If no keyword is provided, it defaults to ACTIVE. chris@1: chris@1: 7.6.1.2. Description chris@1: chris@1: The LIST command allows the server to provide blocks of information chris@1: to the client. This information may be global or may be related to chris@1: newsgroups; in the latter case, the information may be returned chris@1: either for all groups or only for those matching a wildmat. Each chris@1: block of information is represented by a different keyword. The chris@1: command returns the specific information identified by the keyword. chris@1: chris@1: If the information is available, it is returned as a multi-line data chris@1: block following the 215 response code. The format of the information chris@1: depends on the keyword. The information MAY be affected by the chris@1: additional argument, but the format MUST NOT be. chris@1: chris@1: If the information is based on newsgroups and the optional wildmat chris@1: argument is specified, the response is limited to only the groups (if chris@1: any) whose names match the wildmat and for which the information is chris@1: available. chris@1: chris@1: Note that an empty list is a possible valid response; for a chris@1: newsgroup-based keyword, it indicates that there are no groups chris@1: meeting the above criteria. chris@1: chris@1: If the keyword is not recognised, or if an argument is specified and chris@1: the keyword does not expect one, a 501 response code MUST BE chris@1: returned. If the keyword is recognised but the server does not chris@1: maintain the information, a 503 response code MUST BE returned. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 67] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: The LIST command MUST NOT change the visible state of the server in chris@1: any way; that is, the behaviour of subsequent commands MUST NOT be chris@1: affected by whether the LIST command was issued. For example, it chris@1: MUST NOT make groups available that otherwise would not have been. chris@1: chris@1: 7.6.1.3. Examples chris@1: chris@1: Example of LIST with the ACTIVE keyword: chris@1: chris@1: [C] LIST ACTIVE chris@1: [S] 215 list of newsgroups follows chris@1: [S] misc.test 3002322 3000234 y chris@1: [S] comp.risks 442001 441099 m chris@1: [S] alt.rfc-writers.recovery 4 1 y chris@1: [S] tx.natives.recovery 89 56 y chris@1: [S] tx.natives.recovery.d 11 9 n chris@1: [S] . chris@1: chris@1: Example of LIST with no keyword: chris@1: chris@1: [C] LIST chris@1: [S] 215 list of newsgroups follows chris@1: [S] misc.test 3002322 3000234 y chris@1: [S] comp.risks 442001 441099 m chris@1: [S] alt.rfc-writers.recovery 4 1 y chris@1: [S] tx.natives.recovery 89 56 y chris@1: [S] tx.natives.recovery.d 11 9 n chris@1: [S] . chris@1: chris@1: The output is identical to that of the previous example. chris@1: chris@1: Example of LIST on a newsgroup-based keyword with and without chris@1: wildmat: chris@1: chris@1: [C] LIST ACTIVE.TIMES chris@1: [S] 215 information follows chris@1: [S] misc.test 930445408 chris@1: [S] alt.rfc-writers.recovery 930562309 chris@1: [S] tx.natives.recovery 930678923 chris@1: [S] . chris@1: [C] LIST ACTIVE.TIMES tx.* chris@1: [S] 215 information follows chris@1: [S] tx.natives.recovery 930678923 chris@1: [S] . chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 68] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of LIST returning an error where the keyword is recognized chris@1: but the software does not maintain this information: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA chris@1: [S] . chris@1: [C] LIST XTRA.DATA chris@1: [S] 503 Data item not stored chris@1: chris@1: Example of LIST where the keyword is not recognised: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA chris@1: [S] . chris@1: [C] LIST DISTRIB.PATS chris@1: [S] 501 Syntax Error chris@1: chris@1: 7.6.2. Standard LIST Keywords chris@1: chris@1: This specification defines the following LIST keywords: chris@1: chris@1: +--------------+---------------+------------------------------------+ chris@1: | Keyword | Definition | Status | chris@1: +--------------+---------------+------------------------------------+ chris@1: | ACTIVE | Section 7.6.3 | Mandatory if the READER capability | chris@1: | | | is advertised | chris@1: | | | | chris@1: | ACTIVE.TIMES | Section 7.6.4 | Optional | chris@1: | | | | chris@1: | DISTRIB.PATS | Section 7.6.5 | Optional | chris@1: | | | | chris@1: | HEADERS | Section 8.6 | Mandatory if the HDR capability is | chris@1: | | | advertised | chris@1: | | | | chris@1: | NEWSGROUPS | Section 7.6.6 | Mandatory if the READER capability | chris@1: | | | is advertised | chris@1: | | | | chris@1: | OVERVIEW.FMT | Section 8.4 | Mandatory if the OVER capability | chris@1: | | | is advertised | chris@1: +--------------+---------------+------------------------------------+ chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 69] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Where one of these LIST keywords is supported by a server, it MUST chris@1: have the meaning given in the relevant sub-section. chris@1: chris@1: 7.6.3. LIST ACTIVE chris@1: chris@1: This keyword MUST be supported by servers advertising the READER chris@1: capability. chris@1: chris@1: LIST ACTIVE returns a list of valid newsgroups and associated chris@1: information. If no wildmat is specified, the server MUST include chris@1: every group that the client is permitted to select with the GROUP chris@1: command (Section 6.1.1). Each line of this list consists of four chris@1: fields separated from each other by one or more spaces: chris@1: chris@1: o The name of the newsgroup. chris@1: o The reported high water mark for the group. chris@1: o The reported low water mark for the group. chris@1: o The current status of the group on this server. chris@1: chris@1: The reported high and low water marks are as described in the GROUP chris@1: command (see Section 6.1.1), but note that they are in the opposite chris@1: order to the 211 response to that command. chris@1: chris@1: The status field is typically one of the following: chris@1: chris@1: "y" Posting is permitted. chris@1: chris@1: "n" Posting is not permitted. chris@1: chris@1: "m" Postings will be forwarded to the newsgroup moderator. chris@1: chris@1: The server SHOULD use these values when these meanings are required chris@1: and MUST NOT use them with any other meaning. Other values for the chris@1: status may exist; the definition of these other values and the chris@1: circumstances under which they are returned may be specified in an chris@1: extension or may be private to the server. A client SHOULD treat an chris@1: unrecognized status as giving no information. chris@1: chris@1: The status of a newsgroup only indicates how posts to that newsgroup chris@1: are normally processed and is not necessarily customised to the chris@1: specific client. For example, if the current client is forbidden chris@1: from posting, then this will apply equally to groups with status "y". chris@1: Conversely, a client with special privileges (not defined by this chris@1: specification) might be able to post to a group with status "n". chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 70] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: For example: chris@1: chris@1: [C] LIST ACTIVE chris@1: [S] 215 list of newsgroups follows chris@1: [S] misc.test 3002322 3000234 y chris@1: [S] comp.risks 442001 441099 m chris@1: [S] alt.rfc-writers.recovery 4 1 y chris@1: [S] tx.natives.recovery 89 56 y chris@1: [S] tx.natives.recovery.d 11 9 n chris@1: [S] . chris@1: chris@1: or, on an implementation that includes leading zeroes: chris@1: chris@1: [C] LIST ACTIVE chris@1: [S] 215 list of newsgroups follows chris@1: [S] misc.test 0003002322 0003000234 y chris@1: [S] comp.risks 0000442001 0000441099 m chris@1: [S] alt.rfc-writers.recovery 0000000004 0000000001 y chris@1: [S] tx.natives.recovery 0000000089 0000000056 y chris@1: [S] tx.natives.recovery.d 0000000011 0000000009 n chris@1: [S] . chris@1: chris@1: The information is newsgroup based, and a wildmat MAY be specified, chris@1: in which case the response is limited to only the groups (if any) chris@1: whose names match the wildmat. For example: chris@1: chris@1: [C] LIST ACTIVE *.recovery chris@1: [S] 215 list of newsgroups follows chris@1: [S] alt.rfc-writers.recovery 4 1 y chris@1: [S] tx.natives.recovery 89 56 y chris@1: [S] . chris@1: chris@1: 7.6.4. LIST ACTIVE.TIMES chris@1: chris@1: This keyword is optional. chris@1: chris@1: The active.times list is maintained by some NNTP servers to contain chris@1: information about who created a particular newsgroup and when. Each chris@1: line of this list consists of three fields separated from each other chris@1: by one or more spaces. The first field is the name of the newsgroup. chris@1: The second is the time when this group was created on this news chris@1: server, measured in seconds since the start of January 1, 1970. The chris@1: third is plain text intended to describe the entity that created the chris@1: newsgroup; it is often a mailbox as defined in RFC 2822 [RFC2822]. chris@1: For example: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 71] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: [C] LIST ACTIVE.TIMES chris@1: [S] 215 information follows chris@1: [S] misc.test 930445408 chris@1: [S] alt.rfc-writers.recovery 930562309 chris@1: [S] tx.natives.recovery 930678923 chris@1: [S] . chris@1: chris@1: The list MAY omit newsgroups for which the information is unavailable chris@1: and MAY include groups not available on the server; in particular, it chris@1: MAY omit all groups created before the date and time of the oldest chris@1: entry. The client MUST NOT assume that the list is complete or that chris@1: it matches the list returned by the LIST ACTIVE command chris@1: (Section 7.6.3). The NEWGROUPS command (Section 7.3) may provide a chris@1: better way to access this information, and the results of the two chris@1: commands SHOULD be consistent except that, if the latter is invoked chris@1: with a date and time earlier than the oldest entry in active.times chris@1: list, its result may include extra groups. chris@1: chris@1: The information is newsgroup based, and a wildmat MAY be specified, chris@1: in which case the response is limited to only the groups (if any) chris@1: whose names match the wildmat. chris@1: chris@1: 7.6.5. LIST DISTRIB.PATS chris@1: chris@1: This keyword is optional. chris@1: chris@1: The distrib.pats list is maintained by some NNTP servers to assist chris@1: clients to choose a value for the content of the Distribution header chris@1: of a news article being posted. Each line of this list consists of chris@1: three fields separated from each other by a colon (":"). The first chris@1: field is a weight, the second field is a wildmat (which may be a chris@1: simple newsgroup name), and the third field is a value for the chris@1: Distribution header content. For example: chris@1: chris@1: [C] LIST DISTRIB.PATS chris@1: [S] 215 information follows chris@1: [S] 10:local.*:local chris@1: [S] 5:*:world chris@1: [S] 20:local.here.*:thissite chris@1: [S] . chris@1: chris@1: The client MAY use this information to construct an appropriate chris@1: Distribution header given the name of a newsgroup. To do so, it chris@1: should determine the lines whose second field matches the newsgroup chris@1: name, select from among them the line with the highest weight (with 0 chris@1: being the lowest), and use the value of the third field to construct chris@1: the Distribution header. chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 72] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: The information is not newsgroup based, and an argument MUST NOT be chris@1: specified. chris@1: chris@1: 7.6.6. LIST NEWSGROUPS chris@1: chris@1: This keyword MUST be supported by servers advertising the READER chris@1: capability. chris@1: chris@1: The newsgroups list is maintained by NNTP servers to contain the name chris@1: of each newsgroup that is available on the server and a short chris@1: description about the purpose of the group. Each line of this list chris@1: consists of two fields separated from each other by one or more space chris@1: or TAB characters (the usual practice is a single TAB). The first chris@1: field is the name of the newsgroup, and the second is a short chris@1: description of the group. For example: chris@1: chris@1: [C] LIST NEWSGROUPS chris@1: [S] 215 information follows chris@1: [S] misc.test General Usenet testing chris@1: [S] alt.rfc-writers.recovery RFC Writers Recovery chris@1: [S] tx.natives.recovery Texas Natives Recovery chris@1: [S] . chris@1: chris@1: The list MAY omit newsgroups for which the information is unavailable chris@1: and MAY include groups not available on the server. The client MUST chris@1: NOT assume that the list is complete or that it matches the list chris@1: returned by LIST ACTIVE. chris@1: chris@1: The description SHOULD be in UTF-8. However, servers often obtain chris@1: the information from external sources. These sources may have used chris@1: different encodings (ones that use octets in the range 128 to 255 in chris@1: some other manner) and, in that case, the server MAY pass it on chris@1: unchanged. Therefore, clients MUST be prepared to receive such chris@1: descriptions. chris@1: chris@1: The information is newsgroup based, and a wildmat MAY be specified, chris@1: in which case the response is limited to only the groups (if any) chris@1: whose names match the wildmat. chris@1: chris@1: 8. Article Field Access Commands chris@1: chris@1: This section lists commands that may be used to access specific chris@1: article fields; that is, headers of articles and metadata about chris@1: articles. These commands typically fetch data from an "overview chris@1: database", which is a database of headers extracted from incoming chris@1: articles plus metadata determined as the article arrives. Only chris@1: certain fields are included in the database. chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 73] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: This section is based on the Overview/NOV database [ROBE1995] chris@1: developed by Geoff Collyer. chris@1: chris@1: 8.1. Article Metadata chris@1: chris@1: Article "metadata" is data about articles that does not occur within chris@1: the article itself. Each metadata item has a name that MUST begin chris@1: with a colon (and that MUST NOT contain a colon elsewhere within it). chris@1: As with header names, metadata item names are not case sensitive. chris@1: chris@1: When generating a metadata item, the server MUST compute it for chris@1: itself and MUST NOT trust any related value provided in the article. chris@1: (In particular, a Lines or Bytes header in the article MUST NOT be chris@1: assumed to specify the correct number of lines or bytes in the chris@1: article.) If the server has access to several non-identical copies chris@1: of an article, the value returned MUST be correct for any copy of chris@1: that article retrieved during the same session. chris@1: chris@1: This specification defines two metadata items: ":bytes" and ":lines". chris@1: Other metadata items may be defined by extensions. The names of chris@1: metadata items defined by registered extensions MUST NOT begin with chris@1: ":x-". To avoid the risk of a clash with a future registered chris@1: extension, the names of metadata items defined by private extensions chris@1: SHOULD begin with ":x-". chris@1: chris@1: 8.1.1. The :bytes Metadata Item chris@1: chris@1: The :bytes metadata item for an article is a decimal integer. It chris@1: SHOULD equal the number of octets in the entire article: headers, chris@1: body, and separating empty line (counting a CRLF pair as two octets, chris@1: and excluding both the "." CRLF terminating the response and any "." chris@1: added for "dot-stuffing" purposes). chris@1: chris@1: Note to client implementers: some existing servers return a value chris@1: different from that above. The commonest reasons for this are as chris@1: follows: chris@1: chris@1: o Counting a CRLF pair as one octet. chris@1: chris@1: o Including the "." character used for dot-stuffing in the number. chris@1: chris@1: o Including the terminating "." CRLF in the number. chris@1: chris@1: o Using one copy of an article for counting the octets but then chris@1: returning another one that differs in some (permitted) manner. chris@1: chris@1: Implementations should be prepared for such variation and MUST NOT chris@1: rely on the value being accurate. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 74] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 8.1.2. The :lines Metadata Item chris@1: chris@1: The :lines metadata item for an article is a decimal integer. It chris@1: MUST equal the number of lines in the article body (excluding the chris@1: empty line separating headers and body). Equivalently, it is two chris@1: less than the number of CRLF pairs that the BODY command would return chris@1: for that article (the extra two are those following the response code chris@1: and the termination octet). chris@1: chris@1: 8.2. Database Consistency chris@1: chris@1: The information stored in the overview database may change over time. chris@1: If the database records the content or absence of a given field (that chris@1: is, a header or metadata item) for all articles, it is said to be chris@1: "consistent" for that field. If it records the content of a header chris@1: for some articles but not for others that nevertheless included that chris@1: header, or if it records a metadata item for some articles but not chris@1: for others to which that item applies, it is said to be chris@1: "inconsistent" for that field. chris@1: chris@1: The LIST OVERVIEW.FMT command SHOULD list all the fields for which chris@1: the database is consistent at that moment. It MAY omit such fields chris@1: (for example, if it is not known whether the database is consistent chris@1: or inconsistent). It MUST NOT include fields for which the database chris@1: is inconsistent or that are not stored in the database. Therefore, chris@1: if a header appears in the LIST OVERVIEW.FMT output but not in the chris@1: OVER output for a given article, that header does not appear in the chris@1: article (similarly for metadata items). chris@1: chris@1: These rules assume that the fields being stored in the database chris@1: remain constant for long periods of time, and therefore the database chris@1: will be consistent. When the set of fields to be stored is changed, chris@1: it will be inconsistent until either the database is rebuilt or the chris@1: only articles remaining are those received since the change. chris@1: Therefore, the output from LIST OVERVIEW.FMT needs to be altered chris@1: twice. Firstly, before any fields stop being stored they MUST be chris@1: removed from the output; then, when the database is once more known chris@1: to be consistent, the new fields SHOULD be added to the output. chris@1: chris@1: If the HDR command uses the overview database rather than taking chris@1: information directly from the articles, the same issues of chris@1: consistency and inconsistency apply, and the LIST HEADERS command chris@1: SHOULD take the same approach as the LIST OVERVIEW.FMT command in chris@1: resolving them. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 75] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 8.3. OVER chris@1: chris@1: 8.3.1. Usage chris@1: chris@1: Indicating capability: OVER chris@1: chris@1: Syntax chris@1: OVER message-id chris@1: OVER range chris@1: OVER chris@1: chris@1: Responses chris@1: chris@1: First form (message-id specified) chris@1: 224 Overview information follows (multi-line) chris@1: 430 No article with that message-id chris@1: chris@1: Second form (range specified) chris@1: 224 Overview information follows (multi-line) chris@1: 412 No newsgroup selected chris@1: 423 No articles in that range chris@1: chris@1: Third form (current article number used) chris@1: 224 Overview information follows (multi-line) chris@1: 412 No newsgroup selected chris@1: 420 Current article number is invalid chris@1: chris@1: Parameters chris@1: range Number(s) of articles chris@1: message-id Message-id of article chris@1: chris@1: 8.3.2. Description chris@1: chris@1: The OVER command returns the contents of all the fields in the chris@1: database for an article specified by message-id, or from a specified chris@1: article or range of articles in the currently selected newsgroup. chris@1: chris@1: The message-id argument indicates a specific article. The range chris@1: argument may be any of the following: chris@1: chris@1: o An article number. chris@1: chris@1: o An article number followed by a dash to indicate all following. chris@1: chris@1: o An article number followed by a dash followed by another article chris@1: number. chris@1: chris@1: If neither is specified, the current article number is used. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 76] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Support for the first (message-id) form is optional. If it is chris@1: supported, the OVER capability line MUST include the argument chris@1: "MSGID". Otherwise, the capability line MUST NOT include this chris@1: argument, and the OVER command MUST return the generic response code chris@1: 503 when this form is used. chris@1: chris@1: If the information is available, it is returned as a multi-line data chris@1: block following the 224 response code and contains one line per chris@1: article, sorted in numerical order of article number. (Note that chris@1: unless the argument is a range including a dash, there will be chris@1: exactly one line in the data block.) Each line consists of a number chris@1: of fields separated by a TAB. A field may be empty (in which case chris@1: there will be two adjacent TABs), and a sequence of trailing TABs may chris@1: be omitted. chris@1: chris@1: The first 8 fields MUST be the following, in order: chris@1: chris@1: "0" or article number (see below) chris@1: Subject header content chris@1: From header content chris@1: Date header content chris@1: Message-ID header content chris@1: References header content chris@1: :bytes metadata item chris@1: :lines metadata item chris@1: chris@1: If the article is specified by message-id (the first form of the chris@1: command), the article number MUST be replaced with zero, except that chris@1: if there is a currently selected newsgroup and the article is present chris@1: in that group, the server MAY use the article's number in that group. chris@1: (See the ARTICLE command (Section 6.2.1) and STAT examples chris@1: (Section 6.2.4.3) for more details.) In the other two forms of the chris@1: command, the article number MUST be returned. chris@1: chris@1: Any subsequent fields are the contents of the other headers and chris@1: metadata held in the database. chris@1: chris@1: For the five mandatory headers, the content of each field MUST be chris@1: based on the content of the header (that is, with the header name and chris@1: following colon and space removed). If the article does not contain chris@1: that header, or if the content is empty, the field MUST be empty. chris@1: For the two mandatory metadata items, the content of the field MUST chris@1: be just the value, with no other text. chris@1: chris@1: For all subsequent fields that contain headers, the content MUST be chris@1: the entire header line other than the trailing CRLF. For all chris@1: subsequent fields that contain metadata, the field consists of the chris@1: metadata name, a single space, and then the value. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 77] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: For all fields, the value is processed by first removing all CRLF chris@1: pairs (that is, undoing any folding and removing the terminating chris@1: CRLF) and then replacing each TAB with a single space. If there is chris@1: no such header in the article, no such metadata item, or no header or chris@1: item stored in the database for that article, the corresponding field chris@1: MUST be empty. chris@1: chris@1: Note that, after unfolding, the characters NUL, LF, and CR cannot chris@1: occur in the header of an article offered by a conformant server. chris@1: Nevertheless, servers SHOULD check for these characters and replace chris@1: each one by a single space (so that, for example, CR LF LF TAB will chris@1: become two spaces, since the CR and first LF will be removed by the chris@1: unfolding process). This will encourage robustness in the face of chris@1: non-conforming data; it is also possible that future versions of this chris@1: specification could permit these characters to appear in articles. chris@1: chris@1: The server SHOULD NOT produce output for articles that no longer chris@1: exist. chris@1: chris@1: If the argument is a message-id and no such article exists, a 430 chris@1: response MUST be returned. If the argument is a range or is omitted chris@1: and the currently selected newsgroup is invalid, a 412 response MUST chris@1: be returned. If the argument is a range and no articles in that chris@1: number range exist in the currently selected newsgroup, including the chris@1: case where the second number is less than the first one, a 423 chris@1: response MUST be returned. If the argument is omitted and the chris@1: current article number is invalid, a 420 response MUST be returned. chris@1: chris@1: 8.3.3. Examples chris@1: chris@1: In the first four examples, TAB has been replaced by vertical bar and chris@1: some lines have been folded for readability. chris@1: chris@1: Example of a successful retrieval of overview information for an chris@1: article (explicitly not using an article number): chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] OVER chris@1: [S] 224 Overview information follows chris@1: [S] 3000234|I am just a test article|"Demo User" chris@1: |6 Oct 1998 04:38:40 -0500| chris@1: <45223423@example.com>|<45454@example.net>|1234| chris@1: 17|Xref: news.example.com misc.test:3000363 chris@1: [S] . chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 78] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of a successful retrieval of overview information for an chris@1: article by message-id: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] OVER MSGID chris@1: [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT chris@1: [S] . chris@1: [C] OVER <45223423@example.com> chris@1: [S] 224 Overview information follows chris@1: [S] 0|I am just a test article|"Demo User" chris@1: |6 Oct 1998 04:38:40 -0500| chris@1: <45223423@example.com>|<45454@example.net>|1234| chris@1: 17|Xref: news.example.com misc.test:3000363 chris@1: [S] . chris@1: chris@1: Note that the article number has been replaced by "0". chris@1: chris@1: Example of the same commands on a system that does not implement chris@1: retrieval by message-id: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] OVER chris@1: [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT chris@1: [S] . chris@1: [C] OVER <45223423@example.com> chris@1: [S] 503 Overview by message-id unsupported chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 79] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of a successful retrieval of overview information for a range chris@1: of articles: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] OVER 3000234-3000240 chris@1: [S] 224 Overview information follows chris@1: [S] 3000234|I am just a test article|"Demo User" chris@1: |6 Oct 1998 04:38:40 -0500| chris@1: <45223423@example.com>|<45454@example.net>|1234| chris@1: 17|Xref: news.example.com misc.test:3000363 chris@1: [S] 3000235|Another test article|nobody@nowhere.to chris@1: (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>|| chris@1: 4818|37||Distribution: fi chris@1: [S] 3000238|Re: I am just a test article|somebody@elsewhere.to| chris@1: 7 Oct 1998 11:38:40 +1200|| chris@1: <45223423@to.to>|9234|51 chris@1: [S] . chris@1: chris@1: Note the missing "References" and Xref headers in the second line, chris@1: the missing trailing fields in the first and last lines, and that chris@1: there are only results for those articles that still exist. chris@1: chris@1: Example of an unsuccessful retrieval of overview information on an chris@1: article by number: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] OVER 300256 chris@1: [S] 423 No such article in this group chris@1: chris@1: Example of an invalid range: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] OVER 3000444-3000222 chris@1: [S] 423 Empty range chris@1: chris@1: Example of an unsuccessful retrieval of overview information by chris@1: number because no newsgroup was selected first: chris@1: chris@1: [Assumes currently selected newsgroup is invalid.] chris@1: [C] OVER chris@1: [S] 412 No newsgroup selected chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 80] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of an attempt to retrieve information when the currently chris@1: selected newsgroup is empty: chris@1: chris@1: [C] GROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup chris@1: [C] OVER chris@1: [S] 420 No current article selected chris@1: chris@1: 8.4. LIST OVERVIEW.FMT chris@1: chris@1: 8.4.1. Usage chris@1: chris@1: Indicating capability: OVER chris@1: chris@1: Syntax chris@1: LIST OVERVIEW.FMT chris@1: chris@1: Responses chris@1: 215 Information follows (multi-line) chris@1: chris@1: 8.4.2. Description chris@1: chris@1: See Section 7.6.1 for general requirements of the LIST command. chris@1: chris@1: The LIST OVERVIEW.FMT command returns a description of the fields in chris@1: the database for which it is consistent (as described above). The chris@1: information is returned as a multi-line data block following the 215 chris@1: response code. The information contains one line per field in the chris@1: order in which they are returned by the OVER command; the first 7 chris@1: lines MUST (except for the case of letters) be exactly as follows: chris@1: chris@1: Subject: chris@1: From: chris@1: Date: chris@1: Message-ID: chris@1: References: chris@1: :bytes chris@1: :lines chris@1: chris@1: For compatibility with existing implementations, the last two lines chris@1: MAY instead be: chris@1: chris@1: Bytes: chris@1: Lines: chris@1: chris@1: even though they refer to metadata, not headers. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 81] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: All subsequent lines MUST consist of either a header name followed by chris@1: ":full", or the name of a piece of metadata. chris@1: chris@1: There are no leading or trailing spaces in the output. chris@1: chris@1: Note that the 7 fixed lines describe the 2nd to 8th fields of the chris@1: OVER output. The "full" suffix (which may use either uppercase, chris@1: lowercase, or a mix) is a reminder that the corresponding fields chris@1: include the header name. chris@1: chris@1: This command MAY generate different results if it is used more than chris@1: once in a session. chris@1: chris@1: If the OVER command is not implemented, the meaning of the output chris@1: from this command is not specified, but it must still meet the above chris@1: syntactic requirements. chris@1: chris@1: 8.4.3. Examples chris@1: chris@1: Example of LIST OVERVIEW.FMT output corresponding to the example OVER chris@1: output above, in the preferred format: chris@1: chris@1: [C] LIST OVERVIEW.FMT chris@1: [S] 215 Order of fields in overview database. chris@1: [S] Subject: chris@1: [S] From: chris@1: [S] Date: chris@1: [S] Message-ID: chris@1: [S] References: chris@1: [S] :bytes chris@1: [S] :lines chris@1: [S] Xref:full chris@1: [S] Distribution:full chris@1: [S] . chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 82] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of LIST OVERVIEW.FMT output corresponding to the example OVER chris@1: output above, in the alternative format: chris@1: chris@1: [C] LIST OVERVIEW.FMT chris@1: [S] 215 Order of fields in overview database. chris@1: [S] Subject: chris@1: [S] From: chris@1: [S] Date: chris@1: [S] Message-ID: chris@1: [S] References: chris@1: [S] Bytes: chris@1: [S] Lines: chris@1: [S] Xref:FULL chris@1: [S] Distribution:FULL chris@1: [S] . chris@1: chris@1: 8.5. HDR chris@1: chris@1: 8.5.1. Usage chris@1: chris@1: Indicating capability: HDR chris@1: chris@1: Syntax chris@1: HDR field message-id chris@1: HDR field range chris@1: HDR field chris@1: chris@1: Responses chris@1: chris@1: First form (message-id specified) chris@1: 225 Headers follow (multi-line) chris@1: 430 No article with that message-id chris@1: chris@1: Second form (range specified) chris@1: 225 Headers follow (multi-line) chris@1: 412 No newsgroup selected chris@1: 423 No articles in that range chris@1: chris@1: Third form (current article number used) chris@1: 225 Headers follow (multi-line) chris@1: 412 No newsgroup selected chris@1: 420 Current article number is invalid chris@1: chris@1: Parameters chris@1: field Name of field chris@1: range Number(s) of articles chris@1: message-id Message-id of article chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 83] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 8.5.2. Description chris@1: chris@1: The HDR command provides access to specific fields from an article chris@1: specified by message-id, or from a specified article or range of chris@1: articles in the currently selected newsgroup. It MAY take the chris@1: information directly from the articles or from the overview database. chris@1: In the case of headers, an implementation MAY restrict the use of chris@1: this command to a specific list of headers or MAY allow it to be used chris@1: with any header; it may behave differently when it is used with a chris@1: message-id argument and when it is used with a range or no argument. chris@1: chris@1: The required field argument is the name of a header with the colon chris@1: omitted (e.g., "subject") or the name of a metadata item including chris@1: the leading colon (e.g., ":bytes"), and is case insensitive. chris@1: chris@1: The message-id argument indicates a specific article. The range chris@1: argument may be any of the following: chris@1: chris@1: o An article number. chris@1: chris@1: o An article number followed by a dash to indicate all following. chris@1: chris@1: o An article number followed by a dash followed by another article chris@1: number. chris@1: chris@1: If neither is specified, the current article number is used. chris@1: chris@1: If the information is available, it is returned as a multi-line data chris@1: block following the 225 response code and contains one line for each chris@1: article in the range that exists. (Note that unless the argument is chris@1: a range including a dash, there will be exactly one line in the data chris@1: block.) The line consists of the article number, a space, and then chris@1: the contents of the field. In the case of a header, the header name, chris@1: the colon, and the first space after the colon are all omitted. chris@1: chris@1: If the article is specified by message-id (the first form of the chris@1: command), the article number MUST be replaced with zero, except that chris@1: if there is a currently selected newsgroup and the article is present chris@1: in that group, the server MAY use the article's number in that group. chris@1: (See the ARTICLE command (Section 6.2.1) and STAT examples chris@1: (Section 6.2.4.3) for more details.) In the other two forms of the chris@1: command, the article number MUST be returned. chris@1: chris@1: Header contents are modified as follows: all CRLF pairs are removed, chris@1: and then each TAB is replaced with a single space. (Note that this chris@1: is the same transformation as is performed by the OVER command chris@1: (Section 8.3.2), and the same comment concerning NUL, CR, and LF chris@1: applies.) chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 84] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Note the distinction between headers and metadata appearing to have chris@1: the same meaning. Headers are always taken unchanged from the chris@1: article; metadata are always calculated. For example, a request for chris@1: "Lines" returns the contents of the "Lines" header of the specified chris@1: articles, if any, no matter whether they accurately state the number chris@1: of lines, while a request for ":lines" returns the line count chris@1: metadata, which is always the actual number of lines irrespective of chris@1: what any header may state. chris@1: chris@1: If the requested header is not present in the article, or if it is chris@1: present but empty, a line for that article is included in the output, chris@1: but the header content portion of the line is empty (the space after chris@1: the article number MAY be retained or omitted). If the header occurs chris@1: in a given article more than once, only the content of the first chris@1: occurrence is returned by HDR. If any article number in the provided chris@1: range does not exist in the group, no line for that article number is chris@1: included in the output. chris@1: chris@1: If the second argument is a message-id and no such article exists, a chris@1: 430 response MUST be returned. If the second argument is a range or chris@1: is omitted and the currently selected newsgroup is invalid, a 412 chris@1: response MUST be returned. If the second argument is a range and no chris@1: articles in that number range exist in the currently selected chris@1: newsgroup, including the case where the second number is less than chris@1: the first one, a 423 response MUST be returned. If the second chris@1: argument is omitted and the current article number is invalid, a 420 chris@1: response MUST be returned. chris@1: chris@1: A server MAY only allow HDR commands for a limited set of fields; it chris@1: may behave differently in this respect for the first (message-id) chris@1: form from how it would for the other forms. If so, it MUST respond chris@1: with the generic 503 response to attempts to request other fields, chris@1: rather than return erroneous results, such as a successful empty chris@1: response. chris@1: chris@1: If HDR uses the overview database and it is inconsistent for the chris@1: requested field, the server MAY return what results it can, or it MAY chris@1: respond with the generic 503 response. In the latter case, the field chris@1: MUST NOT appear in the output from LIST HEADERS. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 85] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 8.5.3. Examples chris@1: chris@1: Example of a successful retrieval of subject lines from a range of chris@1: articles (3000235 has no Subject header, and 3000236 is missing): chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] HDR Subject 3000234-3000238 chris@1: [S] 225 Headers follow chris@1: [S] 3000234 I am just a test article chris@1: [S] 3000235 chris@1: [S] 3000237 Re: I am just a test article chris@1: [S] 3000238 Ditto chris@1: [S] . chris@1: chris@1: Example of a successful retrieval of line counts from a range of chris@1: articles: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] HDR :lines 3000234-3000238 chris@1: [S] 225 Headers follow chris@1: [S] 3000234 42 chris@1: [S] 3000235 5 chris@1: [S] 3000237 11 chris@1: [S] 3000238 2378 chris@1: [S] . chris@1: chris@1: Example of a successful retrieval of the subject line from an article chris@1: by message-id: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] HDR subject chris@1: [S] 225 Header information follows chris@1: [S] 0 I am just a test article chris@1: [S] . chris@1: chris@1: Example of a successful retrieval of the subject line from the chris@1: current article: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] HDR subject chris@1: [S] 225 Header information follows chris@1: [S] 3000234 I am just a test article chris@1: [S] . chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 86] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of an unsuccessful retrieval of a header from an article by chris@1: message-id: chris@1: chris@1: [C] HDR subject chris@1: [S] 430 No Such Article Found chris@1: chris@1: Example of an unsuccessful retrieval of headers from articles by chris@1: number because no newsgroup was selected first: chris@1: chris@1: [Assumes currently selected newsgroup is invalid.] chris@1: [C] HDR subject 300256- chris@1: [S] 412 No newsgroup selected chris@1: chris@1: Example of an unsuccessful retrieval of headers because the currently chris@1: selected newsgroup is empty: chris@1: chris@1: [C] GROUP example.empty.newsgroup chris@1: [S] 211 0 0 0 example.empty.newsgroup chris@1: [C] HDR subject 1- chris@1: [S] 423 No articles in that range chris@1: chris@1: Example of an unsuccessful retrieval of headers because the server chris@1: does not allow HDR commands for that header: chris@1: chris@1: [C] GROUP misc.test chris@1: [S] 211 1234 3000234 3002322 misc.test chris@1: [C] HDR Content-Type 3000234-3000238 chris@1: [S] 503 HDR not permitted on Content-Type chris@1: chris@1: 8.6. LIST HEADERS chris@1: chris@1: 8.6.1. Usage chris@1: chris@1: Indicating capability: HDR chris@1: chris@1: Syntax chris@1: LIST HEADERS [MSGID|RANGE] chris@1: chris@1: Responses chris@1: 215 Field list follows (multi-line) chris@1: chris@1: Parameters chris@1: MSGID Requests list for access by message-id chris@1: RANGE Requests list for access by range chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 87] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 8.6.2. Description chris@1: chris@1: See Section 7.6.1 for general requirements of the LIST command. chris@1: chris@1: The LIST HEADERS command returns a list of fields that may be chris@1: retrieved using the HDR command. chris@1: chris@1: The information is returned as a multi-line data block following the chris@1: 215 response code and contains one line for each field name chris@1: (excluding the trailing colon for headers and including the leading chris@1: colon for metadata items). If the implementation allows any header chris@1: to be retrieved, it MUST NOT include any header names in the list but chris@1: MUST include the special entry ":" (a single colon on its own). It chris@1: MUST still explicitly list any metadata items that are available. chris@1: The order of items in the list is not significant; the server need chris@1: not even consistently return the same order. The list MAY be empty chris@1: (though in this circumstance there is little point in providing the chris@1: HDR command). chris@1: chris@1: An implementation that also supports the OVER command SHOULD at least chris@1: permit all the headers and metadata items listed in the output from chris@1: the LIST OVERVIEW.FMT command. chris@1: chris@1: If the server treats the first form of the HDR command (message-id chris@1: specified) differently from the other two forms (range specified or chris@1: current article number used) in respect of which headers or metadata chris@1: items are available, then the following apply: chris@1: chris@1: o If the MSGID argument is specified, the results MUST be those chris@1: available for the first form of the HDR command. chris@1: chris@1: o If the RANGE argument is specified, the results MUST be those chris@1: available for the second and third forms of the HDR command. chris@1: chris@1: o If no argument is specified, the results MUST be those available chris@1: in all forms of the HDR command (that is, it MUST only list those chris@1: items listed in both the previous cases). chris@1: chris@1: If the server does not treat the various forms differently, then it chris@1: MUST ignore any argument and always produce the same results (though chris@1: not necessarily always in the same order). chris@1: chris@1: If the HDR command is not implemented, the meaning of the output from chris@1: this command is not specified, but it must still meet the above chris@1: syntactic requirements. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 88] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 8.6.3. Examples chris@1: chris@1: Example of an implementation providing access to only a few headers: chris@1: chris@1: [C] LIST HEADERS chris@1: [S] 215 headers supported: chris@1: [S] Subject chris@1: [S] Message-ID chris@1: [S] Xref chris@1: [S] . chris@1: chris@1: Example of an implementation providing access to the same fields as chris@1: the first example in Section 8.4.3: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] OVER chris@1: [S] HDR chris@1: [S] LIST ACTIVE NEWSGROUPS HEADERS OVERVIEW.FMT chris@1: [S] . chris@1: [C] LIST HEADERS chris@1: [S] 215 headers and metadata items supported: chris@1: [S] Date chris@1: [S] Distribution chris@1: [S] From chris@1: [S] Message-ID chris@1: [S] References chris@1: [S] Subject chris@1: [S] Xref chris@1: [S] :bytes chris@1: [S] :lines chris@1: [S] . chris@1: chris@1: Example of an implementation providing access to all headers: chris@1: chris@1: [C] LIST HEADERS chris@1: [S] 215 metadata items supported: chris@1: [S] : chris@1: [S] :lines chris@1: [S] :bytes chris@1: [S] :x-article-number chris@1: [S] . chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 89] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Example of an implementation distinguishing the first form of the HDR chris@1: command from the other two forms: chris@1: chris@1: [C] LIST HEADERS RANGE chris@1: [S] 215 metadata items supported: chris@1: [S] : chris@1: [S] :lines chris@1: [S] :bytes chris@1: [S] . chris@1: [C] LIST HEADERS MSGID chris@1: [S] 215 headers and metadata items supported: chris@1: [S] Date chris@1: [S] Distribution chris@1: [S] From chris@1: [S] Message-ID chris@1: [S] References chris@1: [S] Subject chris@1: [S] :lines chris@1: [S] :bytes chris@1: [S] :x-article-number chris@1: [S] . chris@1: [C] LIST HEADERS chris@1: [S] 215 headers and metadata items supported: chris@1: [S] Date chris@1: [S] Distribution chris@1: [S] From chris@1: [S] Message-ID chris@1: [S] References chris@1: [S] Subject chris@1: [S] :lines chris@1: [S] :bytes chris@1: [S] . chris@1: chris@1: Note that :x-article-number does not appear in the last set of chris@1: output. chris@1: chris@1: 9. Augmented BNF Syntax for NNTP chris@1: chris@1: 9.1. Introduction chris@1: chris@1: Each of the following sections describes the syntax of a major chris@1: element of NNTP. This syntax extends and refines the descriptions chris@1: elsewhere in this specification and should be given precedence when chris@1: resolving apparent conflicts. Note that ABNF [RFC4234] strings are chris@1: case insensitive. Non-terminals used in several places are defined chris@1: in a separate section at the end. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 90] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Between them, the non-terminals , , chris@1: , and specify the text that flows chris@1: between client and server. A consistent naming scheme is used in chris@1: this document for the non-terminals relating to each command, and chris@1: SHOULD be used by the specification of registered extensions. chris@1: chris@1: For each command, the sequence is as follows: chris@1: chris@1: o The client sends an instance of ; the syntax for the chris@1: EXAMPLE command is . chris@1: chris@1: o If the client is one that immediately streams data, it sends an chris@1: instance of ; the syntax for the EXAMPLE chris@1: command is . chris@1: chris@1: o The server sends an instance of . chris@1: chris@1: * The initial response line is independent of the command that chris@1: generated it; if the 000 response has arguments, the syntax of chris@1: the initial line is . chris@1: chris@1: * If the response is multi-line, the initial line is followed by chris@1: a . The syntax for the contents of this chris@1: block after "dot-stuffing" has been removed is (for the 000 chris@1: response to the EXAMPLE command) and chris@1: is an instance of . chris@1: chris@1: o While the latest response is one that indicates more data is chris@1: required (in general, a 3xx response): chris@1: chris@1: * the client sends an instance of ; the chris@1: syntax for the EXAMPLE continuation following a 333 response is chris@1: ; chris@1: chris@1: * the server sends another instance of , as above. chris@1: chris@1: (There are no commands in this specification that immediately stream chris@1: data, but this non-terminal is defined for the convenience of chris@1: extensions.) chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 91] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 9.2. Commands chris@1: chris@1: This syntax defines the non-terminal , which represents chris@1: what is sent from the client to the server (see section 3.1 for chris@1: limits on lengths). chris@1: chris@1: command-line = command EOL chris@1: command = X-command chris@1: X-command = keyword *(WS token) chris@1: chris@1: command =/ article-command / chris@1: body-command / chris@1: capabilities-command / chris@1: date-command / chris@1: group-command / chris@1: hdr-command / chris@1: head-command / chris@1: help-command / chris@1: ihave-command / chris@1: last-command / chris@1: list-command / chris@1: listgroup-command / chris@1: mode-reader-command / chris@1: newgroups-command / chris@1: newnews-command / chris@1: next-command / chris@1: over-command / chris@1: post-command / chris@1: quit-command / chris@1: stat-command chris@1: chris@1: article-command = "ARTICLE" [WS article-ref] chris@1: body-command = "BODY" [WS article-ref] chris@1: capabilities-command = "CAPABILITIES" [WS keyword] chris@1: date-command = "DATE" chris@1: group-command = "GROUP" [WS newsgroup-name] chris@1: hdr-command = "HDR" WS header-meta-name [WS range-ref] chris@1: head-command = "HEAD" [WS article-ref] chris@1: help-command = "HELP" chris@1: ihave-command = "IHAVE" WS message-id chris@1: last-command = "LAST" chris@1: list-command = "LIST" [WS list-arguments] chris@1: listgroup-command = "LISTGROUP" [WS newsgroup-name [WS range]] chris@1: mode-reader-command = "MODE" WS "READER" chris@1: newgroups-command = "NEWGROUPS" WS date-time chris@1: newnews-command = "NEWNEWS" WS wildmat WS date-time chris@1: next-command = "NEXT" chris@1: over-command = "OVER" [WS range-ref] chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 92] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: post-command = "POST" chris@1: quit-command = "QUIT" chris@1: stat-command = "STAT" [WS article-ref] chris@1: chris@1: article-ref = article-number / message-id chris@1: date = date2y / date4y chris@1: date4y = 4DIGIT 2DIGIT 2DIGIT chris@1: date2y = 2DIGIT 2DIGIT 2DIGIT chris@1: date-time = date WS time [WS "GMT"] chris@1: header-meta-name = header-name / metadata-name chris@1: list-arguments = keyword [WS token] chris@1: metadata-name = ":" 1*A-NOTCOLON chris@1: range = article-number ["-" [article-number]] chris@1: range-ref = range / message-id chris@1: time = 2DIGIT 2DIGIT 2DIGIT chris@1: chris@1: 9.3. Command Continuation chris@1: chris@1: This syntax defines the further material sent by the client in the chris@1: case of multi-stage commands and those that stream data. chris@1: chris@1: command-datastream = UNDEFINED chris@1: ; not used, provided as a hook for extensions chris@1: command-continuation = ihave-335-continuation / chris@1: post-340-continuation chris@1: chris@1: ihave-335-continuation = encoded-article chris@1: post-340-continuation = encoded-article chris@1: chris@1: encoded-article = multi-line-data-block chris@1: ; after undoing the "dot-stuffing", this MUST match
chris@1: chris@1: 9.4. Responses chris@1: chris@1: 9.4.1. Generic Responses chris@1: chris@1: This syntax defines the non-terminal , which represents the chris@1: generic form of responses; that is, what is sent from the server to chris@1: the client in response to a or a . chris@1: chris@1: response = simple-response / multi-line-response chris@1: simple-response = initial-response-line chris@1: multi-line-response = initial-response-line multi-line-data-block chris@1: chris@1: initial-response-line = chris@1: initial-response-content [SP trailing-comment] CRLF chris@1: initial-response-content = X-initial-response-content chris@1: X-initial-response-content = 3DIGIT *(SP response-argument) chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 93] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: response-argument = 1*A-CHAR chris@1: trailing-comment = *U-CHAR chris@1: chris@1: 9.4.2. Initial Response Line Contents chris@1: chris@1: This syntax defines the specific initial response lines for the chris@1: various commands in this specification (see section 3.1 for limits on chris@1: lengths). Only those response codes with arguments are listed. chris@1: chris@1: initial-response-content =/ response-111-content / chris@1: response-211-content / chris@1: response-220-content / chris@1: response-221-content / chris@1: response-222-content / chris@1: response-223-content / chris@1: response-401-content chris@1: chris@1: response-111-content = "111" SP date4y time chris@1: response-211-content = "211" 3(SP article-number) SP newsgroup-name chris@1: response-220-content = "220" SP article-number SP message-id chris@1: response-221-content = "221" SP article-number SP message-id chris@1: response-222-content = "222" SP article-number SP message-id chris@1: response-223-content = "223" SP article-number SP message-id chris@1: response-401-content = "401" SP capability-label chris@1: chris@1: 9.4.3. Multi-line Response Contents chris@1: chris@1: This syntax defines the content of the various multi-line responses; chris@1: more precisely, it defines the part of the response in the multi-line chris@1: data block after any "dot-stuffing" has been undone. The numeric chris@1: portion of each non-terminal name indicates the response code that is chris@1: followed by this data. chris@1: chris@1: multi-line-response-content = article-220-ml-content / chris@1: body-222-ml-content / chris@1: capabilities-101-ml-content / chris@1: hdr-225-ml-content / chris@1: head-221-ml-content / chris@1: help-100-ml-content / chris@1: list-215-ml-content / chris@1: listgroup-211-ml-content / chris@1: newgroups-231-ml-content / chris@1: newnews-230-ml-content / chris@1: over-224-ml-content chris@1: chris@1: article-220-ml-content = article chris@1: body-222-ml-content = body chris@1: capabilities-101-ml-content = version-line CRLF chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 94] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: *(capability-line CRLF) chris@1: hdr-225-ml-content = *(article-number SP hdr-content CRLF) chris@1: head-221-ml-content = 1*header chris@1: help-100-ml-content = *(*U-CHAR CRLF) chris@1: list-215-ml-content = list-content chris@1: listgroup-211-ml-content = *(article-number CRLF) chris@1: newgroups-231-ml-content = active-groups-list chris@1: newnews-230-ml-content = *(message-id CRLF) chris@1: over-224-ml-content = *(article-number over-content CRLF) chris@1: chris@1: active-groups-list = *(newsgroup-name SPA article-number chris@1: SPA article-number SPA newsgroup-status CRLF) chris@1: hdr-content = *S-NONTAB chris@1: hdr-n-content = [(header-name ":" / metadata-name) SP hdr-content] chris@1: list-content = body chris@1: newsgroup-status = %x79 / %x6E / %x6D / private-status chris@1: over-content = 1*6(TAB hdr-content) / chris@1: 7(TAB hdr-content) *(TAB hdr-n-content) chris@1: private-status = token ; except the values in newsgroup-status chris@1: chris@1: 9.5. Capability Lines chris@1: chris@1: This syntax defines the generic form of a capability line in the chris@1: capabilities list (see Section 3.3.1). chris@1: chris@1: capability-line = capability-entry chris@1: capability-entry = X-capability-entry chris@1: X-capability-entry = capability-label *(WS capability-argument) chris@1: capability-label = keyword chris@1: capability-argument = token chris@1: chris@1: This syntax defines the specific capability entries for the chris@1: capabilities in this specification. chris@1: chris@1: capability-entry =/ chris@1: hdr-capability / chris@1: ihave-capability / chris@1: implementation-capability / chris@1: list-capability / chris@1: mode-reader-capability / chris@1: newnews-capability / chris@1: over-capability / chris@1: post-capability / chris@1: reader-capability chris@1: chris@1: hdr-capability = "HDR" chris@1: ihave-capability = "IHAVE" chris@1: implementation-capability = "IMPLEMENTATION" *(WS token) chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 95] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: list-capability = "LIST" 1*(WS keyword) chris@1: mode-reader-capability = "MODE-READER" chris@1: newnews-capability = "NEWNEWS" chris@1: over-capability = "OVER" [WS "MSGID"] chris@1: post-capability = "POST" chris@1: reader-capability = "READER" chris@1: chris@1: version-line = "VERSION" 1*(WS version-number) chris@1: version-number = nzDIGIT *5DIGIT chris@1: chris@1: 9.6. LIST Variants chris@1: chris@1: This section defines more specifically the keywords for the LIST chris@1: command and the syntax of the corresponding response contents. chris@1: chris@1: ; active chris@1: list-arguments =/ "ACTIVE" [WS wildmat] chris@1: list-content =/ list-active-content chris@1: list-active-content = active-groups-list chris@1: chris@1: chris@1: ; active.times chris@1: list-arguments =/ "ACTIVE.TIMES" [WS wildmat] chris@1: list-content =/ list-active-times-content chris@1: list-active-times-content = chris@1: *(newsgroup-name SPA 1*DIGIT SPA newsgroup-creator CRLF) chris@1: newsgroup-creator = U-TEXT chris@1: chris@1: chris@1: ; distrib.pats chris@1: list-arguments =/ "DISTRIB.PATS" chris@1: list-content =/ list-distrib-pats-content chris@1: list-distrib-pats-content = chris@1: *(1*DIGIT ":" wildmat ":" distribution CRLF) chris@1: distribution = token chris@1: chris@1: chris@1: ; headers chris@1: list-arguments =/ "HEADERS" [WS ("MSGID" / "RANGE")] chris@1: list-content =/ list-headers-content chris@1: list-headers-content = *(header-meta-name CRLF) / chris@1: *((metadata-name / ":") CRLF) chris@1: chris@1: chris@1: ; newsgroups chris@1: list-arguments =/ "NEWSGROUPS" [WS wildmat] chris@1: list-content =/ list-newsgroups-content chris@1: list-newsgroups-content = chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 96] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: *(newsgroup-name WS newsgroup-description CRLF) chris@1: newsgroup-description = S-TEXT chris@1: chris@1: chris@1: ; overview.fmt chris@1: list-arguments =/ "OVERVIEW.FMT" chris@1: list-content =/ list-overview-fmt-content chris@1: list-overview-fmt-content = "Subject:" CRLF chris@1: "From:" CRLF chris@1: "Date:" CRLF chris@1: "Message-ID:" CRLF chris@1: "References:" CRLF chris@1: ( ":bytes" CRLF ":lines" / "Bytes:" CRLF "Lines:") CRLF chris@1: *((header-name ":full" / metadata-name) CRLF) chris@1: chris@1: 9.7. Articles chris@1: chris@1: This syntax defines the non-terminal
, which represents the chris@1: format of an article as described in Section 3.6. chris@1: chris@1: article = 1*header CRLF body chris@1: header = header-name ":" [CRLF] SP header-content CRLF chris@1: header-content = *(S-CHAR / [CRLF] WS) chris@1: body = *(*B-CHAR CRLF) chris@1: chris@1: 9.8. General Non-terminals chris@1: chris@1: These non-terminals are used at various places in the syntax and are chris@1: collected here for convenience. A few of these non-terminals are not chris@1: used in this specification but are provided for the consistency and chris@1: convenience of extension authors. chris@1: chris@1: multi-line-data-block = content-lines termination chris@1: content-lines = *([content-text] CRLF) chris@1: content-text = (".." / B-NONDOT) *B-CHAR chris@1: termination = "." CRLF chris@1: chris@1: article-number = 1*16DIGIT chris@1: header-name = 1*A-NOTCOLON chris@1: keyword = ALPHA 2*(ALPHA / DIGIT / "." / "-") chris@1: message-id = "<" 1*248A-NOTGT ">" chris@1: newsgroup-name = 1*wildmat-exact chris@1: token = 1*P-CHAR chris@1: chris@1: wildmat = wildmat-pattern *("," ["!"] wildmat-pattern) chris@1: wildmat-pattern = 1*wildmat-item chris@1: wildmat-item = wildmat-exact / wildmat-wild chris@1: wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E / chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 97] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: UTF8-non-ascii ; exclude ! * , ? [ \ ] chris@1: wildmat-wild = "*" / "?" chris@1: chris@1: base64 = *(4base64-char) [base64-terminal] chris@1: base64-char = UPPER / LOWER / DIGIT / "+" / "/" chris@1: base64-terminal = 2base64-char "==" / 3base64-char "=" chris@1: chris@1: ; Assorted special character sets chris@1: ; A- means based on US-ASCII, excluding controls and SP chris@1: ; P- means based on UTF-8, excluding controls and SP chris@1: ; U- means based on UTF-8, excluding NUL CR and LF chris@1: ; B- means based on bytes, excluding NUL CR and LF chris@1: A-CHAR = %x21-7E chris@1: A-NOTCOLON = %x21-39 / %x3B-7E ; exclude ":" chris@1: A-NOTGT = %x21-3D / %x3F-7E ; exclude ">" chris@1: P-CHAR = A-CHAR / UTF8-non-ascii chris@1: U-CHAR = CTRL / TAB / SP / A-CHAR / UTF8-non-ascii chris@1: U-NONTAB = CTRL / SP / A-CHAR / UTF8-non-ascii chris@1: U-TEXT = P-CHAR *U-CHAR chris@1: B-CHAR = CTRL / TAB / SP / %x21-FF chris@1: B-NONDOT = CTRL / TAB / SP / %x21-2D / %x2F-FF ; exclude "." chris@1: chris@1: ALPHA = UPPER / LOWER ; use only when case-insensitive chris@1: CR = %x0D chris@1: CRLF = CR LF chris@1: CTRL = %x01-08 / %x0B-0C / %x0E-1F chris@1: DIGIT = %x30-39 chris@1: nzDIGIT = %x31-39 chris@1: EOL = *(SP / TAB) CRLF chris@1: LF = %x0A chris@1: LOWER = %x61-7A chris@1: SP = %x20 chris@1: SPA = 1*SP chris@1: TAB = %x09 chris@1: UPPER = %x41-5A chris@1: UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4 chris@1: UTF8-2 = %xC2-DF UTF8-tail chris@1: UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail / chris@1: %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail chris@1: UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail / chris@1: %xF4 %x80-8F 2UTF8-tail chris@1: UTF8-tail = %x80-BF chris@1: WS = 1*(SP / TAB) chris@1: chris@1: The following non-terminals require special consideration. They chris@1: represent situations where material SHOULD be restricted to UTF-8, chris@1: but implementations MUST be able to cope with other character chris@1: encodings. Therefore, there are two sets of definitions for them. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 98] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Implementations MUST accept any content that meets this syntax: chris@1: chris@1: S-CHAR = %x21-FF chris@1: S-NONTAB = CTRL / SP / S-CHAR chris@1: S-TEXT = (CTRL / S-CHAR) *B-CHAR chris@1: chris@1: and MAY pass such content on unaltered. chris@1: chris@1: When generating new content or re-encoding existing content, chris@1: implementations SHOULD conform to this syntax: chris@1: chris@1: S-CHAR = P-CHAR chris@1: S-NONTAB = U-NONTAB chris@1: S-TEXT = U-TEXT chris@1: chris@1: 9.9. Extensions and Validation chris@1: chris@1: The specification of a registered extension MUST include formal chris@1: syntax that defines additional forms for the following non-terminals: chris@1: chris@1: command chris@1: for each new command other than a variant of the LIST command - chris@1: the syntax of each command MUST be compatible with the definition chris@1: of ; chris@1: chris@1: command-datastream chris@1: for each new command that immediately streams data; chris@1: chris@1: command-continuation chris@1: for each new command that sends further material after the initial chris@1: command line - the syntax of each continuation MUST be exactly chris@1: what is sent to the server, including any escape mechanisms such chris@1: as "dot-stuffing"; chris@1: chris@1: initial-response-content chris@1: for each new response code that has arguments - the syntax of each chris@1: response MUST be compatible with the definition of ; chris@1: chris@1: multi-line-response-content chris@1: for each new response code that has a multi-line response - the chris@1: syntax MUST show the response after the lines containing the chris@1: response code and the terminating octet have been removed and any chris@1: "dot-stuffing" undone; chris@1: chris@1: capability-entry chris@1: for each new capability label - the syntax of each entry MUST be chris@1: compatible with the definition of ; chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 99] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: list-arguments chris@1: for each new variant of the LIST command - the syntax of each chris@1: entry MUST be compatible with the definition of ; chris@1: chris@1: list-content chris@1: for each new variant of the LIST command - the syntax MUST show chris@1: the response after the lines containing the 215 response code and chris@1: the terminating octet have been removed and any "dot-stuffing" chris@1: undone. chris@1: chris@1: The =/ notation of ABNF [RFC4234] and the naming conventions chris@1: described in Section 9.1 SHOULD be used for this. chris@1: chris@1: When the syntax in this specification, or syntax based on it, is chris@1: validated, it should be noted that: chris@1: chris@1: o the non-terminals , , chris@1: , , and chris@1: describe basic concepts of the chris@1: protocol and are not referred to by any other rule; chris@1: chris@1: o the non-terminal is provided for the convenience of chris@1: extension authors and is not referred to by any rule in this chris@1: specification; chris@1: chris@1: o for the reasons given above, the non-terminals , chris@1: , and each have two definitions; and chris@1: chris@1: o the non-terminal is deliberately not defined. chris@1: chris@1: 10. Internationalisation Considerations chris@1: chris@1: 10.1. Introduction and Historical Situation chris@1: chris@1: RFC 977 [RFC977] was written at a time when internationalisation was chris@1: not seen as a significant issue. As such, it was written on the chris@1: assumption that all communication would be in ASCII and use only a chris@1: 7-bit transport layer, although in practice just about all known chris@1: implementations are 8-bit clean. chris@1: chris@1: Since then, Usenet and NNTP have spread throughout the world. In the chris@1: absence of standards for handling the issues of language and chris@1: character sets, countries, newsgroup hierarchies, and individuals chris@1: have found a variety of solutions that work for them but that are not chris@1: necessarily appropriate elsewhere. For example, some have adopted a chris@1: default 8-bit character set appropriate to their needs (such as chris@1: ISO/IEC 8859-1 in Western Europe or KOI-8 in Russia), others have chris@1: used ASCII (either US-ASCII or national variants) in headers but chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 100] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: local 16-bit character sets in article bodies, and still others have chris@1: gone for a combination of MIME [RFC2045] and UTF-8. With the chris@1: increased use of MIME in email, it is becoming more common to find chris@1: NNTP articles containing MIME headers that identify the character set chris@1: of the body, but this is far from universal. chris@1: chris@1: The resulting confusion does not help interoperability. chris@1: chris@1: One point that has been generally accepted is that articles can chris@1: contain octets with the top bit set, and NNTP is only expected to chris@1: operate on 8-bit clean transport paths. chris@1: chris@1: 10.2. This Specification chris@1: chris@1: Part of the role of this present specification is to eliminate this chris@1: confusion and promote interoperability as far as possible. At the chris@1: same time, it is necessary to accept the existence of the present chris@1: situation and not break existing implementations and arrangements chris@1: gratuitously, even if they are less than optimal. Therefore, the chris@1: current practice described above has been taken into consideration in chris@1: producing this specification. chris@1: chris@1: This specification extends NNTP from US-ASCII [ANSI1986] to UTF-8 chris@1: [RFC3629]. Except in the two areas discussed below, UTF-8 (which is chris@1: a superset of US-ASCII) is mandatory, and implementations MUST NOT chris@1: use any other encoding. chris@1: chris@1: Firstly, the use of MIME for article headers and bodies is strongly chris@1: recommended. However, given widely divergent existing practices, an chris@1: attempt to require a particular encoding and tagging standard would chris@1: be premature at this time. Accordingly, this specification allows chris@1: the use of arbitrary 8-bit data in articles subject to the following chris@1: requirements and recommendations. chris@1: chris@1: o The names of headers (e.g., "From" or "Subject") MUST be in chris@1: US-ASCII. chris@1: chris@1: o Header values SHOULD use US-ASCII or an encoding based on it, such chris@1: as RFC 2047 [RFC2047], until such time as another approach has chris@1: been standardised. At present, 8-bit encodings (including UTF-8) chris@1: SHOULD NOT be used because they are likely to cause chris@1: interoperability problems. chris@1: chris@1: o The character set of article bodies SHOULD be indicated in the chris@1: article headers, and this SHOULD be done in accordance with MIME. chris@1: chris@1: o Where an article is obtained from an external source, an chris@1: implementation MAY pass it on and derive data from it (such as the chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 101] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: response to the HDR command), even though the article or the data chris@1: does not meet the above requirements. Implementations MUST chris@1: transfer such articles and data correctly and unchanged; they MUST chris@1: NOT attempt to convert or re-encode the article or derived data. chris@1: (Nevertheless, a client or server MAY elect not to post or forward chris@1: the article if, after further examination of the article, it deems chris@1: it inappropriate to do so.) chris@1: chris@1: This requirement affects the ARTICLE (Section 6.2.1), BODY chris@1: (Section 6.2.3), HDR (Section 8.5), HEAD (Section 6.2.2), IHAVE chris@1: (Section 6.3.2), OVER (Section 8.3), and POST (Section 6.3.1) chris@1: commands. chris@1: chris@1: Secondly, the following requirements are placed on the newsgroups chris@1: list returned by the LIST NEWSGROUPS command (Section 7.6.6): chris@1: chris@1: o Although this specification allows UTF-8 for newsgroup names, they chris@1: SHOULD be restricted to US-ASCII until a successor to RFC 1036 chris@1: [RFC1036] standardises another approach. 8-bit encodings SHOULD chris@1: NOT be used because they are likely to cause interoperability chris@1: problems. chris@1: chris@1: o The newsgroup description SHOULD be in US-ASCII or UTF-8 unless chris@1: and until a successor to RFC 1036 standardises other encoding chris@1: arrangements. 8-bit encodings other than UTF-8 SHOULD NOT be used chris@1: because they are likely to cause interoperability problems. chris@1: chris@1: o Implementations that obtain this data from an external source MUST chris@1: handle it correctly even if it does not meet the above chris@1: requirements. Implementations (in particular, clients) MUST chris@1: handle such data correctly. chris@1: chris@1: 10.3. Outstanding Issues chris@1: chris@1: While the primary use of NNTP is for transmitting articles that chris@1: conform to RFC 1036 (Netnews articles), it is also used for other chris@1: formats (see Appendix A). It is therefore most appropriate that chris@1: internationalisation issues related to article formats be addressed chris@1: in the relevant specifications. For Netnews articles, this is any chris@1: successor to RFC 1036. For email messages, it is RFC 2822 [RFC2822]. chris@1: chris@1: Of course, any article transmitted via NNTP needs to conform to this chris@1: specification as well. chris@1: chris@1: Restricting newsgroup names to UTF-8 is not a complete solution. In chris@1: particular, when new newsgroup names are created or a user is asked chris@1: to enter a newsgroup name, some scheme of canonicalisation will need chris@1: to take place. This specification does not attempt to define that chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 102] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: canonicalization; further work is needed in this area, in conjunction chris@1: with the article format specifications. Until such specifications chris@1: are published, implementations SHOULD match newsgroup names octet by chris@1: octet. It is anticipated that any approved scheme will be applied chris@1: "at the edges", and therefore octet-by-octet comparison will continue chris@1: to apply to most, if not all, uses of newsgroup names in NNTP. chris@1: chris@1: In the meantime, any implementation experimenting with UTF-8 chris@1: newsgroup names is strongly cautioned that a future specification may chris@1: require that those names be canonicalized when used with NNTP in a chris@1: way that is not compatible with their experiments. chris@1: chris@1: Since the primary use of NNTP is with Netnews, and since newsgroup chris@1: descriptions are normally distributed through specially formatted chris@1: articles, it is recommended that the internationalisation issues chris@1: related to them be addressed in any successor to RFC 1036. chris@1: chris@1: 11. IANA Considerations chris@1: chris@1: This specification requires IANA to keep a registry of capability chris@1: labels. The initial contents of this registry are specified in chris@1: Section 3.3.4. As described in Section 3.3.3, labels beginning with chris@1: X are reserved for private use, while all other names are expected to chris@1: be associated with a specification in an RFC on the standards track chris@1: or defining an IESG-approved experimental protocol. chris@1: chris@1: Different entries in the registry MUST use different capability chris@1: labels. chris@1: chris@1: Different entries in the registry MUST NOT use the same command name. chris@1: For this purpose, variants distinguished by a second or subsequent chris@1: keyword (e.g., "LIST HEADERS" and "LIST OVERVIEW.FMT") count as chris@1: different commands. If there is a need for two extensions to use the chris@1: same command, a single harmonised specification MUST be registered. chris@1: chris@1: 12. Security Considerations chris@1: chris@1: This section is meant to inform application developers, information chris@1: providers, and users of the security limitations in NNTP as described chris@1: by this document. The discussion does not include definitive chris@1: solutions to the problems revealed, though it does make some chris@1: suggestions for reducing security risks. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 103] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 12.1. Personal and Proprietary Information chris@1: chris@1: NNTP, because it was created to distribute network news articles, chris@1: will forward whatever information is stored in those articles. chris@1: Specification of that information is outside this scope of this chris@1: document, but it is likely that some personal and/or proprietary chris@1: information is available in some of those articles. It is very chris@1: important that designers and implementers provide informative chris@1: warnings to users so that personal and/or proprietary information in chris@1: material that is added automatically to articles (e.g., in headers) chris@1: is not disclosed inadvertently. Additionally, effective and easily chris@1: understood mechanisms to manage the distribution of news articles chris@1: SHOULD be provided to NNTP Server administrators, so that they are chris@1: able to report with confidence the likely spread of any particular chris@1: set of news articles. chris@1: chris@1: 12.2. Abuse of Server Log Information chris@1: chris@1: A server is in the position to save session data about a user's chris@1: requests that might identify their reading patterns or subjects of chris@1: interest. This information is clearly confidential in nature, and chris@1: its handling can be constrained by law in certain countries. People chris@1: using this protocol to provide data are responsible for ensuring that chris@1: such material is not distributed without the permission of any chris@1: individuals that are identifiable by the published results. chris@1: chris@1: 12.3. Weak Authentication and Access Control chris@1: chris@1: There is no user-based or token-based authentication in the basic chris@1: NNTP specification. Access is normally controlled by server chris@1: configuration files. Those files specify access by using domain chris@1: names or IP addresses. However, this specification does permit the chris@1: creation of extensions to NNTP for such purposes; one such extension chris@1: is [NNTP-AUTH]. While including such mechanisms is optional, doing chris@1: so is strongly encouraged. chris@1: chris@1: Other mechanisms are also available. For example, a proxy server chris@1: could be put in place that requires authentication before connecting chris@1: via the proxy to the NNTP server. chris@1: chris@1: 12.4. DNS Spoofing chris@1: chris@1: Many existing NNTP implementations authorize incoming connections by chris@1: checking the IP address of that connection against the IP addresses chris@1: obtained via DNS lookups of lists of domain names given in local chris@1: configuration files. Servers that use this type of authentication chris@1: and clients that find a server by doing a DNS lookup of the server chris@1: name rely very heavily on the Domain Name Service, and are thus chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 104] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: generally prone to security attacks based on the deliberate chris@1: misassociation of IP addresses and DNS names. Clients and servers chris@1: need to be cautious in assuming the continuing validity of an IP chris@1: number/DNS name association. chris@1: chris@1: In particular, NNTP clients and servers SHOULD rely on their name chris@1: resolver for confirmation of an IP number/DNS name association, chris@1: rather than cache the result of previous host name lookups. Many chris@1: platforms already can cache host name lookups locally when chris@1: appropriate, and they SHOULD be configured to do so. It is proper chris@1: for these lookups to be cached, however, only when the TTL (Time To chris@1: Live) information reported by the name server makes it likely that chris@1: the cached information will remain useful. chris@1: chris@1: If NNTP clients or servers cache the results of host name lookups in chris@1: order to achieve a performance improvement, they MUST observe the TTL chris@1: information reported by DNS. If NNTP clients or servers do not chris@1: observe this rule, they could be spoofed when a previously accessed chris@1: server's IP address changes. As network renumbering is expected to chris@1: become increasingly common, the possibility of this form of attack chris@1: will increase. Observing this requirement thus reduces this chris@1: potential security vulnerability. chris@1: chris@1: This requirement also improves the load-balancing behaviour of chris@1: clients for replicated servers using the same DNS name and reduces chris@1: the likelihood of a user's experiencing failure in accessing sites chris@1: that use that strategy. chris@1: chris@1: 12.5. UTF-8 Issues chris@1: chris@1: UTF-8 [RFC3629] permits only certain sequences of octets and chris@1: designates others as either malformed or "illegal". The Unicode chris@1: standard identifies a number of security issues related to illegal chris@1: sequences and forbids their generation by conforming implementations. chris@1: chris@1: Implementations of this specification MUST NOT generate malformed or chris@1: illegal sequences and SHOULD detect them and take some appropriate chris@1: action. This could include the following: chris@1: chris@1: o Generating a 501 response code. chris@1: chris@1: o Replacing such sequences by the sequence %xEF.BF.BD, which encodes chris@1: the "replacement character" U+FFFD. chris@1: chris@1: o Closing the connection. chris@1: chris@1: o Replacing such sequences by a "guessed" valid sequence (based on chris@1: properties of the UTF-8 encoding). chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 105] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: In the last case, the implementation MUST ensure that any replacement chris@1: cannot be used to bypass validity or security checks. For example, chris@1: the illegal sequence %xC0.A0 is an over-long encoding for space chris@1: (%x20). If it is replaced by the correct encoding in a command line, chris@1: this needs to happen before the command line is parsed into chris@1: individual arguments. If the replacement came after parsing, it chris@1: would be possible to generate an argument with an embedded space, chris@1: which is forbidden. Use of the "replacement character" does not have chris@1: this problem, since it is permitted wherever non-US-ASCII characters chris@1: are. Implementations SHOULD use one of the first two solutions where chris@1: the general structure of the NNTP stream remains intact and SHOULD chris@1: close the connection if it is no longer possible to parse it chris@1: sensibly. chris@1: chris@1: 12.6. Caching of Capability Lists chris@1: chris@1: The CAPABILITIES command provides a capability list, which is chris@1: information about the current capabilities of the server. Whenever chris@1: there is a relevant change to the server state, the results of this chris@1: command are required to change accordingly. chris@1: chris@1: In most situations, the capabilities list in a given server state chris@1: will not change from session to session; for example, a given chris@1: extension will be installed permanently on a server. Some clients chris@1: may therefore wish to remember which extensions a server supports to chris@1: avoid the delay of an additional command and response, particularly chris@1: if they open multiple connections in the same session. chris@1: chris@1: However, information about extensions related to security and privacy chris@1: MUST NOT be cached, since this could allow a variety of attacks. chris@1: chris@1: For example, consider a server that permits the use of cleartext chris@1: passwords on links that are encrypted but not otherwise: chris@1: chris@1: [Initial connection set-up completed.] chris@1: [S] 200 NNTP Service Ready, posting permitted chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] NEWNEWS chris@1: [S] POST chris@1: [S] XENCRYPT chris@1: [S] LIST ACTIVE NEWSGROUPS chris@1: [S] . chris@1: [C] XENCRYPT chris@1: [Client and server negotiate encryption on the link] chris@1: [S] 283 Encrypted link established chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 106] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: [C] CAPABILITIES chris@1: [S] 101 Capability list: chris@1: [S] VERSION 2 chris@1: [S] READER chris@1: [S] NEWNEWS chris@1: [S] POST chris@1: [S] XSECRET chris@1: [S] LIST ACTIVE NEWSGROUPS chris@1: [S] . chris@1: [C] XSECRET fred flintstone chris@1: [S] 290 Password for fred accepted chris@1: chris@1: If the client caches the last capabilities list, then on the next chris@1: session it will attempt to use XSECRET on an unencrypted link: chris@1: chris@1: [Initial connection set-up completed.] chris@1: [S] 200 NNTP Service Ready, posting permitted chris@1: [C] XSECRET fred flintstone chris@1: [S] 483 Only permitted on secure links chris@1: chris@1: This exposes the password to any eavesdropper. While the primary chris@1: cause of this is passing a secret without first checking the security chris@1: of the link, caching of capability lists can increase the risk. chris@1: chris@1: Any security extension should include requirements to check the chris@1: security state of the link in a manner appropriate to that extension. chris@1: chris@1: Caching should normally only be considered for anonymous clients that chris@1: do not use any security or privacy extensions and for which the time chris@1: required for an additional command and response is a noticeable chris@1: issue. chris@1: chris@1: 13. Acknowledgements chris@1: chris@1: This document is the result of much effort by the present and past chris@1: members of the NNTP Working Group, chaired by Russ Allbery and Ned chris@1: Freed. It could not have been produced without them. chris@1: chris@1: The author acknowledges the original authors of NNTP as documented in chris@1: RFC 977 [RFC977]: Brian Kantor and Phil Lapsey. chris@1: chris@1: The author gratefully acknowledges the following: chris@1: chris@1: o The work of the NNTP committee chaired by Eliot Lear. The chris@1: organization of this document was influenced by the last available chris@1: version from this working group. A special thanks to Eliot for chris@1: generously providing the original machine-readable sources for chris@1: that document. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 107] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: o The work of the DRUMS working group, specifically RFC 1869 chris@1: [RFC1869], that drove the original thinking that led to the chris@1: CAPABILITIES command and the extensions mechanism detailed in this chris@1: document. chris@1: chris@1: o The authors of RFC 2616 [RFC2616] for providing specific and chris@1: relevant examples of security issues that should be considered for chris@1: HTTP. Since many of the same considerations exist for NNTP, those chris@1: examples that are relevant have been included here with some minor chris@1: rewrites. chris@1: chris@1: o The comments and additional information provided by the following chris@1: individuals in preparing one or more of the progenitors of this chris@1: document: chris@1: chris@1: Russ Allbery chris@1: Wayne Davison chris@1: Chris Lewis chris@1: Tom Limoncelli chris@1: Eric Schnoebelen chris@1: Rich Salz chris@1: chris@1: This work was motivated by the work of various news reader authors chris@1: and news server authors, including those listed below: chris@1: chris@1: Rick Adams chris@1: Original author of the NNTP extensions to the RN news reader and chris@1: last maintainer of Bnews. chris@1: chris@1: Stan Barber chris@1: Original author of the NNTP extensions to the news readers that chris@1: are part of Bnews. chris@1: chris@1: Geoff Collyer chris@1: Original author of the OVERVIEW database proposal and one of the chris@1: original authors of CNEWS. chris@1: chris@1: Dan Curry chris@1: Original author of the xvnews news reader. chris@1: chris@1: Wayne Davison chris@1: Author of the first threading extensions to the RN news reader chris@1: (commonly called TRN). chris@1: chris@1: Geoff Huston chris@1: Original author of ANU NEWS. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 108] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Phil Lapsey chris@1: Original author of the UNIX reference implementation for NNTP. chris@1: chris@1: Iain Lea chris@1: Original maintainer of the TIN news reader. chris@1: chris@1: Chris Lewis chris@1: First known implementer of the AUTHINFO GENERIC extension. chris@1: chris@1: Rich Salz chris@1: Original author of INN. chris@1: chris@1: Henry Spencer chris@1: One of the original authors of CNEWS. chris@1: chris@1: Kim Storm chris@1: Original author of the NN news reader. chris@1: chris@1: Other people who contributed to this document include: chris@1: chris@1: Matthias Andree chris@1: Greg Andruk chris@1: Daniel Barclay chris@1: Maurizio Codogno chris@1: Mark Crispin chris@1: Andrew Gierth chris@1: Juergen Helbing chris@1: Scott Hollenbeck chris@1: Urs Janssen chris@1: Charles Lindsey chris@1: Ade Lovett chris@1: David Magda chris@1: Ken Murchison chris@1: Francois Petillon chris@1: Peter Robinson chris@1: Rob Siemborski chris@1: Howard Swinehart chris@1: Ruud van Tol chris@1: Jeffrey Vinocur chris@1: Erik Warmelink chris@1: chris@1: The author thanks them all and apologises to anyone omitted. chris@1: chris@1: Finally, the present author gratefully acknowledges the vast amount chris@1: of work put into previous versions by the previous author: chris@1: chris@1: Stan Barber chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 109] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: 14. References chris@1: chris@1: 14.1. Normative References chris@1: chris@1: [ANSI1986] American National Standards Institute, "Coded Character chris@1: Set - 7-bit American Standard Code for Information chris@1: Interchange", ANSI X3.4, 1986. chris@1: chris@1: [RFC977] Kantor, B. and P. Lapsley, "Network News Transfer chris@1: Protocol", RFC 977, February 1986. chris@1: chris@1: [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet chris@1: Mail Extensions (MIME) Part One: Format of Internet chris@1: Message Bodies", RFC 2045, November 1996. chris@1: chris@1: [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail chris@1: Extensions) Part Three: Message Header Extensions for chris@1: Non-ASCII Text", RFC 2047, November 1996. chris@1: chris@1: [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate chris@1: Requirement Levels", BCP 14, RFC 2119, March 1997. chris@1: chris@1: [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO chris@1: 10646", STD 63, RFC 3629, November 2003. chris@1: chris@1: [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for chris@1: Syntax Specifications: ABNF", RFC 4234, October 2005. chris@1: chris@1: [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data chris@1: Encodings", RFC 4648, October 2006. chris@1: chris@1: [TF.686-1] International Telecommunications Union - Radio, chris@1: "Glossary, ITU-R Recommendation TF.686-1", chris@1: ITU-R Recommendation TF.686-1, October 1997. chris@1: chris@1: 14.2. Informative References chris@1: chris@1: [NNTP-AUTH] Vinocur, J., Murchison, K., and C. Newman, "Network chris@1: News Transfer Protocol (NNTP) Extension for chris@1: Authentication", chris@1: RFC 4643, October 2006. chris@1: chris@1: [NNTP-STREAM] Vinocur, J. and K. Murchison, "Network News Transfer chris@1: Protocol (NNTP) Extension for Streaming Feeds", chris@1: RFC 4644, October 2006. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 110] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: [NNTP-TLS] Murchison, K., Vinocur, J., and C. Newman, "Using chris@1: Transport Layer Security (TLS) with Network News chris@1: Transfer Protocol (NNTP)", RFC 4642, October 2006. chris@1: chris@1: [RFC1036] Horton, M. and R. Adams, "Standard for interchange of chris@1: USENET messages", RFC 1036, December 1987. chris@1: chris@1: [RFC1305] Mills, D., "Network Time Protocol (Version 3) chris@1: Specification, Implementation and Analysis", RFC 1305, chris@1: March 1992. chris@1: chris@1: [RFC1869] Klensin, J., Freed, N., Rose, M., Stefferud, E., and D. chris@1: Crocker, "SMTP Service Extensions", STD 10, RFC 1869, chris@1: November 1995. chris@1: chris@1: [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., chris@1: Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext chris@1: Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. chris@1: chris@1: [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, chris@1: June 1999. chris@1: chris@1: [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April chris@1: 2001. chris@1: chris@1: [RFC2980] Barber, S., "Common NNTP Extensions", RFC 2980, October chris@1: 2000. chris@1: chris@1: [ROBE1995] Robertson, R., "FAQ: Overview database / NOV General chris@1: Information", January 1995. chris@1: chris@1: There is no definitive copy of this document known to chris@1: the author. It was previously posted as the Usenet chris@1: article chris@1: chris@1: [SALZ1992] Salz, R., "Manual Page for wildmat(3) from the INN 1.4 chris@1: distribution, Revision 1.10", April 1992. chris@1: chris@1: There is no definitive copy of this document known to chris@1: the author. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 111] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Appendix A. Interaction with Other Specifications chris@1: chris@1: NNTP is most often used for transferring articles that conform to chris@1: RFC 1036 [RFC1036] (such articles are called "Netnews articles" chris@1: here). It is also sometimes used for transferring email messages chris@1: that conform to RFC 2822 [RFC2822] (such articles are called "email chris@1: articles" here). In this situation, articles must conform both to chris@1: this specification and to that other one; this appendix describes chris@1: some relevant issues. chris@1: chris@1: A.1. Header Folding chris@1: chris@1: NNTP allows a header line to be folded (by inserting a CRLF pair) chris@1: before any space or TAB character. chris@1: chris@1: Both email and Netnews articles are required to have at least one chris@1: octet other than space or TAB on each header line. Thus, folding can chris@1: only happen at one point in each sequence of consecutive spaces or chris@1: TABs. Netnews articles are further required to have the header name, chris@1: colon, and following space all on the first line; folding may only chris@1: happen beyond that space. Finally, some non-conforming software will chris@1: remove trailing spaces and TABs from a line. Therefore, it might be chris@1: inadvisable to fold a header after a space or TAB. chris@1: chris@1: For maximum safety, header lines SHOULD conform to the following chris@1: syntax rather than to that in Section 9.7. chris@1: chris@1: chris@1: header = header-name ":" SP [header-content] CRLF chris@1: header-content = [WS] token *( [CRLF] WS token ) chris@1: chris@1: A.2. Message-IDs chris@1: chris@1: Every article handled by an NNTP server MUST have a unique chris@1: message-id. For the purposes of this specification, a message-id is chris@1: an arbitrary opaque string that merely needs to meet certain chris@1: syntactic requirements and is just a way to refer to the article. chris@1: chris@1: Because there is a significant risk that old articles will be chris@1: reinjected into the global Usenet system, RFC 1036 [RFC1036] requires chris@1: that message-ids are globally unique for all time. chris@1: chris@1: This specification states that message-ids are the same if and only chris@1: if they consist of the same sequence of octets. Other specifications chris@1: may define two different sequences as being equal because they are chris@1: putting an interpretation on particular characters. RFC 2822 chris@1: [RFC2822] has a concept of "quoted" and "escaped" characters. It chris@1: therefore considers the three message-ids: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 112] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: chris@1: <"ab.cd"@example.com> chris@1: <"ab.\cd"@example.com> chris@1: chris@1: as being identical. Therefore, an NNTP implementation handing email chris@1: articles must ensure that only one of these three appears in the chris@1: protocol and that the other two are converted to it as and when chris@1: necessary, such as when a client checks the results of a NEWNEWS chris@1: command against an internal database of message-ids. Note that chris@1: RFC 1036 [RFC1036] never treats two different strings as being chris@1: identical. Its successor (as of the time of writing) restricts the chris@1: syntax of message-ids so that, whenever RFC 2822 would treat two chris@1: strings as equivalent, only one of them is valid (in the above chris@1: example, only the first string is valid). chris@1: chris@1: This specification does not describe how the message-id of an article chris@1: is determined; it may be deduced from the contents of the article or chris@1: derived from some external source. If the server is also conforming chris@1: to another specification that contains a definition of message-id chris@1: compatible with this one, the server SHOULD use those message-ids. A chris@1: common approach, and one that SHOULD be used for email and Netnews chris@1: articles, is to extract the message-id from the contents of a header chris@1: with name "Message-ID". This may not be as simple as copying the chris@1: entire header contents; it may be necessary to strip off comments and chris@1: undo quoting, or to reduce "equivalent" message-ids to a canonical chris@1: form. chris@1: chris@1: If an article is obtained through the IHAVE command, there will be a chris@1: message-id provided with the command. The server MAY either use it chris@1: or determine one from the article contents. However, whichever it chris@1: does, it SHOULD ensure that, if the IHAVE command is repeated with chris@1: the same argument and article, it will be recognized as a duplicate. chris@1: chris@1: If an article does not contain a message-id that the server can chris@1: identify, it MUST synthesize one. This could, for example, be a chris@1: simple sequence number or be based on the date and time when the chris@1: article arrived. When email or Netnews articles are handled, a chris@1: Message-ID header SHOULD be added to ensure global consistency and chris@1: uniqueness. chris@1: chris@1: Note that, because the message-id might not have been derived from chris@1: the Message-ID header in the article, the following example is chris@1: legitimate (though unusual): chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 113] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: [C] HEAD <45223423@example.com> chris@1: [S] 221 0 <45223423@example.com> chris@1: [S] Path: pathost!demo!whitehouse!not-for-mail chris@1: [S] Message-ID: <1234@example.net> chris@1: [S] From: "Demo User" chris@1: [S] Newsgroups: misc.test chris@1: [S] Subject: I am just a test article chris@1: [S] Date: 6 Oct 1998 04:38:40 -0500 chris@1: [S] Organization: An Example Net, Uncertain, Texas chris@1: [S] . chris@1: chris@1: A.3. Article Posting chris@1: chris@1: As far as NNTP is concerned, the POST and IHAVE commands provide the chris@1: same basic facilities in a slightly different way. However, they chris@1: have rather different intentions. chris@1: chris@1: The IHAVE command is intended for transmitting conforming articles chris@1: between a system of NNTP servers, with all articles perhaps also chris@1: conforming to another specification (e.g., all articles are Netnews chris@1: articles). It is expected that the client will already have done any chris@1: necessary validation (or that it has in turn obtained the article chris@1: from a third party that has done so); therefore, the contents SHOULD chris@1: be left unchanged. chris@1: chris@1: In contrast, the POST command is intended for use when an end-user is chris@1: injecting a newly created article into a such a system. The article chris@1: being transferred might not be a conforming email or Netnews article, chris@1: and the server is expected to validate it and, if necessary, to chris@1: convert it to the right form for onward distribution. This is often chris@1: done by a separate piece of software on the server installation; if chris@1: so, the NNTP server SHOULD pass the incoming article to that software chris@1: unaltered, making no attempt to filter characters, to fold or limit chris@1: lines, or to process the incoming text otherwise. chris@1: chris@1: The POST command can fail in various ways, and clients should be chris@1: prepared to re-send an article. When doing so, however, it is often chris@1: important to ensure (as far as possible) that the same message-id is chris@1: allocated to both attempts so that the server, or other servers, can chris@1: recognize the two articles as duplicates. In the case of email or chris@1: Netnews articles, therefore, the posted article SHOULD contain a chris@1: header with the name "Message-ID", and the contents of this header chris@1: SHOULD be identical on each attempt. The server SHOULD ensure that chris@1: two POSTed articles with the same contents for this header are chris@1: recognized as identical and that the same message-id is allocated, chris@1: whether or not those contents are suitable for use as the message-id. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 114] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Appendix B. Summary of Commands chris@1: chris@1: This section contains a list of every command defined in this chris@1: document, ordered by command name and by indicating capability. chris@1: chris@1: Ordered by command name: chris@1: chris@1: +-------------------+-----------------------+---------------+ chris@1: | Command | Indicating capability | Definition | chris@1: +-------------------+-----------------------+---------------+ chris@1: | ARTICLE | READER | Section 6.2.1 | chris@1: | BODY | READER | Section 6.2.3 | chris@1: | CAPABILITIES | mandatory | Section 5.2 | chris@1: | DATE | READER | Section 7.1 | chris@1: | GROUP | READER | Section 6.1.1 | chris@1: | HDR | HDR | Section 8.5 | chris@1: | HEAD | mandatory | Section 6.2.2 | chris@1: | HELP | mandatory | Section 7.2 | chris@1: | IHAVE | IHAVE | Section 6.3.2 | chris@1: | LAST | READER | Section 6.1.3 | chris@1: | LIST | LIST | Section 7.6.1 | chris@1: | LIST ACTIVE.TIMES | LIST | Section 7.6.4 | chris@1: | LIST ACTIVE | LIST | Section 7.6.3 | chris@1: | LIST DISTRIB.PATS | LIST | Section 7.6.5 | chris@1: | LIST HEADERS | HDR | Section 8.6 | chris@1: | LIST NEWSGROUPS | LIST | Section 7.6.6 | chris@1: | LIST OVERVIEW.FMT | OVER | Section 8.4 | chris@1: | LISTGROUP | READER | Section 6.1.2 | chris@1: | MODE READER | MODE-READER | Section 5.3 | chris@1: | NEWGROUPS | READER | Section 7.3 | chris@1: | NEWNEWS | NEWNEWS | Section 7.4 | chris@1: | NEXT | READER | Section 6.1.4 | chris@1: | OVER | OVER | Section 8.3 | chris@1: | POST | POST | Section 6.3.1 | chris@1: | QUIT | mandatory | Section 5.4 | chris@1: | STAT | mandatory | Section 6.2.4 | chris@1: +-------------------+-----------------------+---------------+ chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 115] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Ordered by indicating capability: chris@1: chris@1: +-------------------+-----------------------+---------------+ chris@1: | Command | Indicating capability | Definition | chris@1: +-------------------+-----------------------+---------------+ chris@1: | CAPABILITIES | mandatory | Section 5.2 | chris@1: | HEAD | mandatory | Section 6.2.2 | chris@1: | HELP | mandatory | Section 7.2 | chris@1: | QUIT | mandatory | Section 5.4 | chris@1: | STAT | mandatory | Section 6.2.4 | chris@1: | HDR | HDR | Section 8.5 | chris@1: | LIST HEADERS | HDR | Section 8.6 | chris@1: | IHAVE | IHAVE | Section 6.3.2 | chris@1: | LIST | LIST | Section 7.6.1 | chris@1: | LIST ACTIVE | LIST | Section 7.6.3 | chris@1: | LIST ACTIVE.TIMES | LIST | Section 7.6.4 | chris@1: | LIST DISTRIB.PATS | LIST | Section 7.6.5 | chris@1: | LIST NEWSGROUPS | LIST | Section 7.6.6 | chris@1: | MODE READER | MODE-READER | Section 5.3 | chris@1: | NEWNEWS | NEWNEWS | Section 7.4 | chris@1: | OVER | OVER | Section 8.3 | chris@1: | LIST OVERVIEW.FMT | OVER | Section 8.4 | chris@1: | POST | POST | Section 6.3.1 | chris@1: | ARTICLE | READER | Section 6.2.1 | chris@1: | BODY | READER | Section 6.2.3 | chris@1: | DATE | READER | Section 7.1 | chris@1: | GROUP | READER | Section 6.1.1 | chris@1: | LAST | READER | Section 6.1.3 | chris@1: | LISTGROUP | READER | Section 6.1.2 | chris@1: | NEWGROUPS | READER | Section 7.3 | chris@1: | NEXT | READER | Section 6.1.4 | chris@1: +-------------------+-----------------------+---------------+ chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 116] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Appendix C. Summary of Response Codes chris@1: chris@1: This section contains a list of every response code defined in this chris@1: document and indicates whether it is multi-line, which commands can chris@1: generate it, what arguments it has, and what its meaning is. chris@1: chris@1: Response code 100 (multi-line) chris@1: Generated by: HELP chris@1: Meaning: help text follows. chris@1: chris@1: Response code 101 (multi-line) chris@1: Generated by: CAPABILITIES chris@1: Meaning: capabilities list follows. chris@1: chris@1: Response code 111 chris@1: Generated by: DATE chris@1: 1 argument: yyyymmddhhmmss chris@1: Meaning: server date and time. chris@1: chris@1: Response code 200 chris@1: Generated by: initial connection, MODE READER chris@1: Meaning: service available, posting allowed. chris@1: chris@1: Response code 201 chris@1: Generated by: initial connection, MODE READER chris@1: Meaning: service available, posting prohibited. chris@1: chris@1: Response code 205 chris@1: Generated by: QUIT chris@1: Meaning: connection closing (the server immediately closes the chris@1: connection). chris@1: chris@1: Response code 211 chris@1: The 211 response code has two completely different forms, chris@1: depending on which command generated it: chris@1: chris@1: (not multi-line) chris@1: Generated by: GROUP chris@1: 4 arguments: number low high group chris@1: Meaning: group selected. chris@1: chris@1: (multi-line) chris@1: Generated by: LISTGROUP chris@1: 4 arguments: number low high group chris@1: Meaning: article numbers follow. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 117] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Response code 215 (multi-line) chris@1: Generated by: LIST chris@1: Meaning: information follows. chris@1: chris@1: Response code 220 (multi-line) chris@1: Generated by: ARTICLE chris@1: 2 arguments: n message-id chris@1: Meaning: article follows. chris@1: chris@1: Response code 221 (multi-line) chris@1: Generated by: HEAD chris@1: 2 arguments: n message-id chris@1: Meaning: article headers follow. chris@1: chris@1: Response code 222 (multi-line) chris@1: Generated by: BODY chris@1: 2 arguments: n message-id chris@1: Meaning: article body follows. chris@1: chris@1: Response code 223 chris@1: Generated by: LAST, NEXT, STAT chris@1: 2 arguments: n message-id chris@1: Meaning: article exists and selected. chris@1: chris@1: Response code 224 (multi-line) chris@1: Generated by: OVER chris@1: Meaning: overview information follows. chris@1: chris@1: Response code 225 (multi-line) chris@1: Generated by: HDR chris@1: Meaning: headers follow. chris@1: chris@1: Response code 230 (multi-line) chris@1: Generated by: NEWNEWS chris@1: Meaning: list of new articles follows. chris@1: chris@1: Response code 231 (multi-line) chris@1: Generated by: NEWGROUPS chris@1: Meaning: list of new newsgroups follows. chris@1: chris@1: Response code 235 chris@1: Generated by: IHAVE (second stage) chris@1: Meaning: article transferred OK. chris@1: chris@1: Response code 240 chris@1: Generated by: POST (second stage) chris@1: Meaning: article received OK. chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 118] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Response code 335 chris@1: Generated by: IHAVE (first stage) chris@1: Meaning: send article to be transferred. chris@1: chris@1: Response code 340 chris@1: Generated by: POST (first stage) chris@1: Meaning: send article to be posted. chris@1: chris@1: Response code 400 chris@1: Generic response and generated by initial connection chris@1: Meaning: service not available or no longer available (the server chris@1: immediately closes the connection). chris@1: chris@1: Response code 401 chris@1: Generic response chris@1: 1 argument: capability-label chris@1: Meaning: the server is in the wrong mode; the indicated capability chris@1: should be used to change the mode. chris@1: chris@1: Response code 403 chris@1: Generic response chris@1: Meaning: internal fault or problem preventing action being taken. chris@1: chris@1: Response code 411 chris@1: Generated by: GROUP, LISTGROUP chris@1: Meaning: no such newsgroup. chris@1: chris@1: Response code 412 chris@1: Generated by: ARTICLE, BODY, GROUP, HDR, HEAD, LAST, LISTGROUP, chris@1: NEXT, OVER, STAT chris@1: Meaning: no newsgroup selected. chris@1: chris@1: Response code 420 chris@1: Generated by: ARTICLE, BODY, HDR, HEAD, LAST, NEXT, OVER, STAT chris@1: Meaning: current article number is invalid. chris@1: chris@1: Response code 421 chris@1: Generated by: NEXT chris@1: Meaning: no next article in this group. chris@1: chris@1: Response code 422 chris@1: Generated by: LAST chris@1: Meaning: no previous article in this group. chris@1: chris@1: Response code 423 chris@1: Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT chris@1: Meaning: no article with that number or in that range. chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 119] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Response code 430 chris@1: Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT chris@1: Meaning: no article with that message-id. chris@1: chris@1: Response code 435 chris@1: Generated by: IHAVE (first stage) chris@1: Meaning: article not wanted. chris@1: chris@1: Response code 436 chris@1: Generated by: IHAVE (either stage) chris@1: Meaning: transfer not possible (first stage) or failed (second chris@1: stage); try again later. chris@1: chris@1: Response code 437 chris@1: Generated by: IHAVE (second stage) chris@1: Meaning: transfer rejected; do not retry. chris@1: chris@1: Response code 440 chris@1: Generated by: POST (first stage) chris@1: Meaning: posting not permitted. chris@1: chris@1: Response code 441 chris@1: Generated by: POST (second stage) chris@1: Meaning: posting failed. chris@1: chris@1: Response code 480 chris@1: Generic response chris@1: Meaning: command unavailable until the client has authenticated chris@1: itself. chris@1: chris@1: Response code 483 chris@1: Generic response chris@1: Meaning: command unavailable until suitable privacy has been chris@1: arranged. chris@1: chris@1: Response code 500 chris@1: Generic response chris@1: Meaning: unknown command. chris@1: chris@1: Response code 501 chris@1: Generic response chris@1: Meaning: syntax error in command. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 120] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Response code 502 chris@1: Generic response and generated by initial connection chris@1: chris@1: Meaning for the initial connection and the MODE READER command: chris@1: service permanently unavailable (the server immediately closes the chris@1: connection). chris@1: chris@1: Meaning for all other commands: command not permitted (and there chris@1: is no way for the client to change this). chris@1: chris@1: Response code 503 chris@1: Generic response chris@1: Meaning: feature not supported. chris@1: chris@1: Response code 504 chris@1: Generic response chris@1: Meaning: error in base64-encoding [RFC4648] of an argument. chris@1: chris@1: Appendix D. Changes from RFC 977 chris@1: chris@1: In general every attempt has been made to ensure that the protocol chris@1: specification in this document is compatible with the version chris@1: specified in RFC 977 [RFC977] and the various facilities adopted from chris@1: RFC 2980 [RFC2980]. However, there have been a number of changes, chris@1: some compatible and some not. chris@1: chris@1: This appendix lists these changes. It is not guaranteed to be chris@1: exhaustive or correct and MUST NOT be relied on. chris@1: chris@1: o A formal syntax specification (Section 9) has been added. chris@1: chris@1: o The default character set is changed from US-ASCII [ANSI1986] to chris@1: UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8). This chris@1: matter is discussed further in Section 10. chris@1: chris@1: o All articles are required to have a message-id, eliminating the chris@1: "<0>" placeholder used in RFC 977 in some responses. chris@1: chris@1: o The newsgroup name matching capabilities already documented in chris@1: RFC 977 ("wildmats", Section 4) are clarified and extended. The chris@1: new facilities (e.g., the use of commas and exclamation marks) are chris@1: allowed wherever wildmats appear in the protocol. chris@1: chris@1: o Support for pipelining of commands (Section 3.5) is made chris@1: mandatory. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 121] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: o The principles behind response codes (Section 3.2) have been chris@1: tidied up. In particular: chris@1: chris@1: * the x8x response code family, formerly used for private chris@1: extensions, is now reserved for authentication and privacy chris@1: extensions; chris@1: chris@1: * the x9x response code family, formerly intended for debugging chris@1: facilities, are now reserved for private extensions; chris@1: chris@1: * the 502 and 503 generic response codes (Section 3.2.1) have chris@1: been redefined; chris@1: chris@1: * new 401, 403, 480, 483, and 504 generic response codes have chris@1: been added. chris@1: chris@1: o The rules for article numbering (Section 6) have been clarified chris@1: (also see Section 6.1.1.2). chris@1: chris@1: o The SLAVE command (which was ill-defined) is removed from the chris@1: protocol. chris@1: chris@1: o Four-digit years are permitted in the NEWNEWS (Section 7.4) and chris@1: NEWGROUPS (Section 7.3) commands (two-digit years are still chris@1: permitted). The optional distribution parameter to these commands chris@1: has been removed. chris@1: chris@1: o The LIST command (Section 7.6.1) is greatly extended; the original chris@1: is available as LIST ACTIVE, while new variants include chris@1: ACTIVE.TIMES, DISTRIB.PATS, and NEWSGROUPS. A new "m" status flag chris@1: is added to the LIST ACTIVE response. chris@1: chris@1: o A new CAPABILITIES command (Section 5.2) allows clients to chris@1: determine what facilities are supported by a server. chris@1: chris@1: o The DATE command (Section 7.1) is adopted from RFC 2980 chris@1: effectively unchanged. chris@1: chris@1: o The LISTGROUP command (Section 6.1.2) is adopted from RFC 2980. chris@1: An optional range argument has been added, and the 211 initial chris@1: response line now has the same format as the 211 response from the chris@1: GROUP command. chris@1: chris@1: o The MODE READER command (Section 5.3) is adopted from RFC 2980 and chris@1: its meaning and effects clarified. chris@1: chris@1: o The XHDR command in RFC 2980 has been formalised as the new HDR chris@1: (Section 8.5) and LIST HEADERS (Section 8.6) commands. chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 122] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: o The XOVER command in RFC 2980 has been formalised as the new OVER chris@1: (Section 8.3) and LIST OVERVIEW.FMT (Section 8.4) commands. The chris@1: former can be applied to a message-id as well as to a range. chris@1: chris@1: o The concept of article metadata (Section 8.1) has been formalised, chris@1: allowing the Bytes and Lines pseudo-headers to be deprecated. chris@1: chris@1: Client authors should note in particular that lack of support for the chris@1: CAPABILITIES command is a good indication that the server does not chris@1: support this specification. chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 123] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Author's Address chris@1: chris@1: Clive D.W. Feather chris@1: THUS plc chris@1: 322 Regents Park Road chris@1: London chris@1: N3 2QQ chris@1: United Kingdom chris@1: chris@1: Phone: +44 20 8495 6138 chris@1: Fax: +44 870 051 9937 chris@1: EMail: clive@demon.net chris@1: URI: http://www.davros.org/ chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 124] chris@1: chris@1: RFC 3977 Network News Transfer Protocol (NNTP) October 2006 chris@1: chris@1: chris@1: Full Copyright Statement chris@1: chris@1: Copyright (C) The Internet Society (2006). chris@1: chris@1: This document is subject to the rights, licenses and restrictions chris@1: contained in BCP 78, and except as set forth therein, the authors chris@1: retain all their rights. chris@1: chris@1: This document and the information contained herein are provided on an chris@1: "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS chris@1: OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET chris@1: ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, chris@1: INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE chris@1: INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED chris@1: WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. chris@1: chris@1: Intellectual Property chris@1: chris@1: The IETF takes no position regarding the validity or scope of any chris@1: Intellectual Property Rights or other rights that might be claimed to chris@1: pertain to the implementation or use of the technology described in chris@1: this document or the extent to which any license under such rights chris@1: might or might not be available; nor does it represent that it has chris@1: made any independent effort to identify any such rights. Information chris@1: on the procedures with respect to rights in RFC documents can be chris@1: found in BCP 78 and BCP 79. chris@1: chris@1: Copies of IPR disclosures made to the IETF Secretariat and any chris@1: assurances of licenses to be made available, or the result of an chris@1: attempt made to obtain a general license or permission for the use of chris@1: such proprietary rights by implementers or users of this chris@1: specification can be obtained from the IETF on-line IPR repository at chris@1: http://www.ietf.org/ipr. chris@1: chris@1: The IETF invites any interested party to bring to its attention any chris@1: copyrights, patents or patent applications, or other proprietary chris@1: rights that may cover technology that may be required to implement chris@1: this standard. Please address the information to the IETF at ietf- chris@1: ipr@ietf.org. chris@1: chris@1: Acknowledgement chris@1: chris@1: Funding for the RFC Editor function is provided by the IETF chris@1: Administrative Support Activity (IASA). chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: chris@1: Feather Standards Track [Page 125] chris@1: