RFC 3977
Network News Transfer Protocol (NNTP)
Network News Transfer Protocol (NNTP) 🎀
okay bestie, this is RFC 3977 and it is the NNTP spec 💅 Here's the tea from the title block:
- Written by: C. Feather of THUS plc ✨
- Dated: October 2006 🦋
- Category: Standards Track 👑
- Obsoletes: RFC 977 (so this one replaces it 🫶)
- Updates: RFC 2980 🌸
Status of This Memo 📜
This doc is an Internet standards track protocol for the Internet community 🌈 It also asks for discussion and suggestions for improvements 💜 For the standardization state and status of this protocol, go check the current edition of the "Internet Official Protocol Standards" (STD 1) 🧚 Distribution of this memo is unlimited 🎉
Copyright Notice ⭐
Copyright (C) The Internet Society (2006). 🔥
Abstract 🍓
NNTP has been running on the Internet for a decade and is still one of the most popular protocols by volume, which is honestly iconic 😭 This document replaces RFC 977 and officially updates the protocol spec ✨ It clears up some vagueness from RFC 977, adds some new base functionality, and gives a specific mechanism for adding standardized extensions to NNTP 🦋
Table of Contents 📚
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Author's Note . . . . . . . . . . . . . . . . . . . . . . 4
2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Commands and Responses . . . . . . . . . . . . . . . . . 6
3.1.1. Multi-line Data Blocks . . . . . . . . . . . . . . . . 8
3.2. Response Codes . . . . . . . . . . . . . . . . . . . . . 9
3.2.1. Generic Response Codes . . . . . . . . . . . . . . . 10
3.2.1.1. Examples . . . . . . . . . . . . . . . . . . . . 12
3.3. Capabilities and Extensions . . . . . . . . . . . . . . . 14
3.3.1. Capability Descriptions . . . . . . . . . . . . . . . 14
3.3.2. Standard Capabilities . . . . . . . . . . . . . . . . 15
3.3.3. Extensions . . . . . . . . . . . . . . . . . . . . . 16
3.3.4. Initial IANA Register . . . . . . . . . . . . . . . . 18
3.4. Mandatory and Optional Commands . . . . . . . . . . . . . 20
3.4.1. Reading and Transit Servers . . . . . . . . . . . . . 21
3.4.2. Mode Switching . . . . . . . . . . . . . . . . . . . 21
3.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 22
3.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 23
3.6. Articles . . . . . . . . . . . . . . . . . . . . . . . . 24
4. The WILDMAT Format . . . . . . . . . . . . . . . . . . . . . 25
4.1. Wildmat Syntax . . . . . . . . . . . . . . . . . . . . . 26
4.2. Wildmat Semantics . . . . . . . . . . . . . . . . . . . . 26
4.3. Extensions . . . . . . . . . . . . . . . . . . . . . . . 27
4.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 27
5. Session Administration Commands . . . . . . . . . . . . . . . 28
5.1. Initial Connection . . . . . . . . . . . . . . . . . . . 28
5.2. CAPABILITIES . . . . . . . . . . . . . . . . . . . . . . 29
5.3. MODE READER . . . . . . . . . . . . . . . . . . . . . . . 32
5.4. QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6. Article Posting and Retrieval . . . . . . . . . . . . . . . . 35
6.1. Group and Article Selection . . . . . . . . . . . . . . . 36
6.1.1. GROUP . . . . . . . . . . . . . . . . . . . . . . . . 36
6.1.2. LISTGROUP . . . . . . . . . . . . . . . . . . . . . . 39
6.1.3. LAST . . . . . . . . . . . . . . . . . . . . . . . . 42
6.1.4. NEXT . . . . . . . . . . . . . . . . . . . . . . . . 44
6.2. Retrieval of Articles and Article Sections . . . . . . . 45
6.2.1. ARTICLE . . . . . . . . . . . . . . . . . . . . . . . 46
6.2.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 49
6.2.3. BODY . . . . . . . . . . . . . . . . . . . . . . . . 51
6.2.4. STAT . . . . . . . . . . . . . . . . . . . . . . . . 53
6.3. Article Posting . . . . . . . . . . . . . . . . . . . . . 56
6.3.1. POST . . . . . . . . . . . . . . . . . . . . . . . . 56
6.3.2. IHAVE . . . . . . . . . . . . . . . . . . . . . . . . 58
7. Information Commands . . . . . . . . . . . . . . . . . . . . 61
7.1. DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7.2. HELP . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.3. NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 63
7.4. NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 64
7.5. Time . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . 66
7.6. The LIST Commands . . . . . . . . . . . . . . . . . . . . 66
7.6.1. LIST . . . . . . . . . . . . . . . . . . . . . . . . 67
7.6.2. Standard LIST Keywords . . . . . . . . . . . . . . . 69
7.6.3. LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . 70
7.6.4. LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . 71
7.6.5. LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . 72
7.6.6. LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . 73
8. Article Field Access Commands . . . . . . . . . . . . . . . . 73
8.1. Article Metadata . . . . . . . . . . . . . . . . . . . . 74
8.1.1. The :bytes Metadata Item . . . . . . . . . . . . . . 74
8.1.2. The :lines Metadata Item . . . . . . . . . . . . . . 75
8.2. Database Consistency . . . . . . . . . . . . . . . . . . 75
8.3. OVER . . . . . . . . . . . . . . . . . . . . . . . . . . 76
8.4. LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 81
8.5. HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
8.6. LIST HEADERS . . . . . . . . . . . . . . . . . . . . . . 87
9. Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . . . 90
9.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 90
9.2. Commands . . . . . . . . . . . . . . . . . . . . . . . . 92
9.3. Command Continuation . . . . . . . . . . . . . . . . . . 93
9.4. Responses . . . . . . . . . . . . . . . . . . . . . . . . 93
9.4.1. Generic Responses . . . . . . . . . . . . . . . . . . 93
9.4.2. Initial Response Line Contents . . . . . . . . . . . 94
9.4.3. Multi-line Response Contents . . . . . . . . . . . . 94
9.5. Capability Lines . . . . . . . . . . . . . . . . . . . . 95
9.6. LIST Variants . . . . . . . . . . . . . . . . . . . . . . 96
9.7. Articles . . . . . . . . . . . . . . . . . . . . . . . . 97
9.8. General Non-terminals . . . . . . . . . . . . . . . . . . 97
9.9. Extensions and Validation . . . . . . . . . . . . . . . . 99
10. Internationalisation Considerations . . . . . . . . . . . . .100
10.1. Introduction and Historical Situation . . . . . . . . . .100
10.2. This Specification . . . . . . . . . . . . . . . . . . .101
10.3. Outstanding Issues . . . . . . . . . . . . . . . . . . .102
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . .103
12. Security Considerations . . . . . . . . . . . . . . . . . . .103
12.1. Personal and Proprietary Information . . . . . . . . . .104
12.2. Abuse of Server Log Information . . . . . . . . . . . . .104
12.3. Weak Authentication and Access Control . . . . . . . . .104
12.4. DNS Spoofing . . . . . . . . . . . . . . . . . . . . . .104
12.5. UTF-8 Issues . . . . . . . . . . . . . . . . . . . . . .105
12.6. Caching of Capability Lists . . . . . . . . . . . . . . .106
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . .107
14. References . . . . . . . . . . . . . . . . . . . . . . . . .110
14.1. Normative References . . . . . . . . . . . . . . . . . .110
14.2. Informative References . . . . . . . . . . . . . . . . .110
A. Interaction with Other Specifications . . . . . . . . . . . .112
A.1. Header Folding . . . . . . . . . . . . . . . . . . . . .112
A.2. Message-IDs . . . . . . . . . . . . . . . . . . . . . . .112
A.3. Article Posting . . . . . . . . . . . . . . . . . . . . .114
B. Summary of Commands . . . . . . . . . . . . . . . . . . . . .115
C. Summary of Response Codes . . . . . . . . . . . . . . . . . .117
D. Changes from RFC 977 . . . . . . . . . . . . . . . . . . . .1211. Introduction ✨
This doc specifies the Network News Transfer Protocol (NNTP) 🌸 It's used for distributing, inquiring about, retrieving, and posting Netnews articles over a reliable stream-based mechanism 💅 For news-reading clients, NNTP lets you grab news articles stored in a central database, so subscribers can pick out just the ones they actually want to read 📖
The Netnews model handles indexing, cross-referencing, and expiration of aged messages 🕰️ NNTP is built to transmit Netnews articles efficiently over a reliable full duplex communication channel 🦋
Okay so, this is largely compatible with the version in RFC 977 [RFC977] 🫶 but there are a bunch of changes summarised in Appendix D. The big ones are:
- the default character set changed from US-ASCII [ANSI1986] to UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8) 🌈
- a number of commands that were optional in RFC 977 or that have been taken from RFC 2980 [RFC2980] are now mandatory 🔥
- a CAPABILITIES command was added so clients can figure out what functionality a server offers 👑
Now the key words 🎀 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] 💜
Compliance time 🧚 An implementation is not compliant if it fails to satisfy one or more of the MUST requirements for this protocol. An implementation that satisfies all the MUST and all the SHOULD requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST requirements but not all the SHOULD requirements for NNTP is said to be "conditionally compliant". 😭
For the rest of this document, the terms "client" and "client host" refer to a host making use of the NNTP service, while the terms "server" and "server host" refer to a host that offers the NNTP service 🍓
1.1. Author's Note 🙈
This document is written in XML using an NNTP-specific DTD. Custom software is used to convert this to RFC 2629 [RFC2629] format, and then the public "xml2rfc" package reduces it further to text, nroff source, and HTML 🌈
No perl was used in producing this document. 💀
2. Notation ✨
okay bestie, let's get into the notation stuff 🤓 this is the part where the doc tells you how to read its own shorthand. it's giving secret decoder ring 🔐
Here's the decoder ring, from the original notation table:
UPPERCASE indicates literal text to be included in the
command.
lowercase indicates a token described elsewhere.
[brackets] indicate that the enclosed material is optional.
elliptical indicates that the argument may be repeated any
... marks number of times (it must occur at least once).
vertical|bar indicates a choice of two mutually exclusive
arguments (exactly one must be provided).The name "message-id" for a command or response argument means the message-id of an article as described in Section 3.6, angle brackets included. Iconic 🫶
The name "wildmat" for an argument means it's a wildmat as defined in Section 4. If the argument doesn't meet the requirements of that section (like if it doesn't fit the grammar of Section 4.1), the NNTP server MAY place some interpretation on it (not specified by this document) or otherwise MUST treat it as a syntax error. Not me hitting a syntax error on a wildmat 💀
Responses for each command get described in tables. Each table lists the required format of a response, followed by the meaning that should be given to that response 📊
The terms "NUL", "TAB", "LF", "CR", and "space" refer to the octets %x00, %x09, %x0A, %x0D, and %x20, respectively. That's the octets with those codes in US-ASCII [ANSI1986], and therefore in UTF-8 [RFC3629] too. 🌸 The term "CRLF" or "CRLF pair" means CR immediately followed by LF (that's %x0D.0A). A "printable US-ASCII character" is an octet in the range %x21-7E. Quoted characters refer to the octets with those codes in US-ASCII (so "." and "<" refer to %x2E and %x3C), and they will always be printable US-ASCII characters. Similarly, "digit" refers to the octets %x30-39. Lowkey the best little lookup table 🧚
A "keyword" MUST consist only of US-ASCII letters, digits, and the characters dot (".") and dash ("-"), and it MUST begin with a letter. Keywords MUST be at least three characters in length. Keywords only, no vibes-based naming 🙅♀️
Examples in this document are not normative. They're there to illustrate usages, arguments, and responses 🎀 In the examples, a "[C]" represents the client host and an "[S]" represents the server host. Most of the examples don't rely on a particular server state. In some cases, though, they assume the currently selected newsgroup (see the GROUP command, Section 6.1.1) is invalid, and when that's the case, the example says so at the start. Examples may use commands or other keywords that aren't defined in this specification (like an XENCRYPT command). These show up to make a point, and they don't imply that any such command is defined elsewhere or needs to exist in any particular implementation. Just examples, not a guest list 💅
Terms that might sound like they describe details of a client or server implementation, like "database", are only used to make the description easier to read. As long as implementations conform to the protocol and format specifications in this document, no specific technique is mandated. You do you, boo 🦋
3. Basic Concepts 💜
3.1. Commands and Responses 💬
okay so NNTP runs over any reliable bi-directional 8-bit-wide data stream channel 🌊 When the connection is established, the NNTP server host MUST send a greeting. After that, the client host and server host exchange commands and responses (respectively) until the connection is closed or aborted. If the connection is TCP, the server host starts the NNTP service by listening on a TCP port. When a client host wants to use the service, it MUST establish a TCP connection with the server host by connecting to that host on the same port the server is listening on. Main character energy for the server, honestly ✨
The character set for all NNTP commands is UTF-8 [RFC3629]. Commands in NNTP MUST consist of a keyword, which MAY be followed by one or more arguments. A CRLF pair MUST terminate all commands. Multiple commands MUST NOT be on the same line. Unless otherwise noted elsewhere in this document, arguments SHOULD consist of printable US-ASCII characters. Keywords and arguments MUST each be separated by one or more space or TAB characters. Command lines MUST NOT exceed 512 octets, which includes the terminating CRLF pair. The arguments MUST NOT exceed 497 octets. A server MAY relax these limits for commands defined in an extension. Limits with some flexibility, iykyk 🙈
Where this specification permits UTF-8 characters outside the range of U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark (U+FEFF, encoding %xEF.BB.BF). They MUST use the Word Joiner (U+2060, encoding %xE2.91.A0) for the meaning Zero Width No-Break Space in command lines and in the initial lines of responses. Implementations SHOULD apply these same principles throughout. Don't let the BOM crash the party 🍓
The term "character" means a single Unicode code point. Implementations are not required to carry out Unicode normalisation. So, U+0084 (A-dieresis) is one character, while U+0041 U+0308 (A composed with dieresis) is two, and the two need not be treated as equivalent. Not the same vibe, not the same character 🌈
Commands may have variants. If they do, they use a second keyword immediately after the first to show which variant is needed. The only such commands in this specification are LIST and MODE. Note that these variants are sometimes talked about as if they were commands in their own right: "the LIST ACTIVE" command should be read as shorthand for "the ACTIVE variant of the LIST command". Lowkey a sub-category situation 🗂️
Keywords are case insensitive, so the server MUST ignore the case of keywords for commands. Command and response arguments are only case or language specific when stated, either in this document or in other relevant specifications. Case matters only when the doc says it does 🫠
In some cases, a command involves more data than just a single line. That further data may be sent either immediately after the command line (there are none of these in this specification, but there are in extensions such as [NNTP-STREAM]), or following a request from the server (indicated by a 3xx response). Sometimes the server has to ask nicely first 🥹
Each response MUST start with a three-digit response code that is enough to tell all responses apart. Certain valid responses are defined to be multi-line. For all the others, the response is contained in a single line. The initial line of the response MUST NOT exceed 512 octets, which includes the response code and the terminating CRLF pair. An extension MAY specify a greater maximum for commands that it defines, but not for any other command. Single-line responses consist of an initial line only. Multi-line responses consist of an initial line followed by a multi-line data block. Three digits, zero drama 🔢
An NNTP server MAY have an inactivity autologout timer. If it does, the timer SHOULD be at least three minutes' duration. The one exception: there MAY be a shorter limit on how long the server is willing to wait for the first command from the client. Receiving any command from the client during the timer interval SHOULD be enough to reset the autologout timer. Similarly, receiving any significant amount of data from a client that's sending a multi-line data block (such as during a POST or IHAVE command) SHOULD be enough to reset the autologout timer. When the timer expires, the server SHOULD close the connection without sending any response to the client. Ghosting the client, but make it polite 👻
3.1.1. Multi-line Data Blocks 📦
A multi-line data block is used in certain commands and responses. It MUST follow these rules:
- The block is a sequence of zero or more "lines", each one a stream of octets ending with a CRLF pair. Apart from those line endings, the stream MUST NOT include the octets NUL, LF, or CR.
- In a multi-line response, the block comes right after the CRLF at the end of the initial line of the response. When it's used in any other context, the specific command defines when the block gets sent.
- If any line of the data block begins with the "termination octet" ("." or
%x2E), that line MUST be "dot-stuffed" by prepending an additional termination octet to it. - The lines of the block MUST be followed by a terminating line made of a single termination octet followed by a CRLF pair, in the normal way. So, unless it's empty, a multi-line block always ends with the five octets CRLF "." CRLF (
%x0D.0A.2E.0D.0A). Every block gets its goodbye 👋 - When a multi-line block is interpreted, the "dot-stuffing" MUST be undone. In other words, the recipient MUST make sure that, in any line starting with the termination octet followed by octets other than a CRLF pair, that initial termination octet is disregarded. Undo the stuff, get the tea ☕
- Likewise, the terminating line ("." CRLF or
%x2E.0D.0A) MUST NOT be considered part of the multi-line block. The recipient MUST make sure that any line starting with the termination octet followed immediately by a CRLF pair is disregarded. (The first CRLF pair of the terminating CRLF "." CRLF of a non-empty block is, of course, part of the last line of the block.) The end marker is not part of the content, period 🛑
Note that texts using an encoding (like UTF-16 or UTF-32) that may contain the octets NUL, LF, or CR other than as a CRLF pair can't be reliably conveyed in the above format. That means they break the MUST requirement above. However, except when stated otherwise, this specification does not require the content to be UTF-8. So, subject to that same requirement, it MAY include octets above and below 128 mixed in arbitrarily. Encoding chaos, but make it structured 🌀
This document doesn't place any limit on the length of a line in a multi-line block. However, the standards that define the format of articles may do so. Long lines are between you and the article spec 📜✨
3.2. Response Codes ✨
Okay bestie, every single response MUST begin with a three-digit status indicator 💅. It's the server's little receipt for the last command you sent, so you know how it went 🧾.
The first digit tells you the big picture: success, failure, or still in progress ✨.
1xx - Informative message
2xx - Command completed OK
3xx - Command OK so far; send the rest of it
4xx - Command was syntactically correct but failed for some reason
5xx - Command unknown, unsupported, unavailable, or syntax errorThe next digit is the function response category 🎀.
x0x - Connection, setup, and miscellaneous messages
x1x - Newsgroup selection
x2x - Article selection
x3x - Distribution functions
x4x - Posting
x8x - Reserved for authentication and privacy extensions
x9x - Reserved for private use (non-standard extensions)Some responses come with extra bits like numbers and names after the status indicator 🔢. To keep the client sane, the number and type of those arguments is locked in for each response code, and so is whether the response is single-line or multi-line 📏. Any extension MUST follow this principle as well 🫶. Now for the messy history 🙈: the 211 response code is the exception, because it can be single-line or multi-line depending on whether the command was GROUP or LISTGROUP. Everywhere else, the client MUST only use the status indicator itself to figure out what kind of response it's looking at 🔍. Want to know which exact codes a command can return? Check that command's own description 📖.
Arguments MUST be separated from the numeric status indicator and from each other by a single space, no fancy spacing 📐. Numeric arguments MUST be in base 10 (decimal) format and MAY have leading zeros 🔢. String arguments MUST contain at least one character and MUST NOT contain TAB, LF, CR, or space 🚫. The server MAY add any text after the response code or last argument, as appropriate, but the client MUST NOT make decisions based on this text 🙅♀️. That extra text MUST be separated from the numeric status indicator or the last argument by at least one space 💖.
The server MUST respond to any command with the appropriate generic response (given in Section 3.2.1) if it represents the situation. Otherwise, each recognized command MUST return one of the response codes specifically listed in its description or in an extension. A server MAY provide extensions to this specification, like new commands, new variants or features of existing commands, and other ways of changing the internal state of the server. Still, the server MUST NOT produce any other responses to a client that doesn't invoke any of the additional features. (So a client that sticks to this specification will only get the responses that are listed 🦋.)
If a client gets an unexpected response, it SHOULD use the first digit of the response to decide the result. For example, an unexpected 2xx should be taken as success, and an unexpected 4xx or 5xx as failure 🌈.
Response codes not specified in this document MAY be used for any installation-specific additional commands that also aren't specified. These SHOULD be chosen to fit the x9x pattern from above 🧚.
Neither this document nor any registered extension (see Section 3.3.3) will specify any response codes of the x9x pattern. (Implementers of extensions are accordingly cautioned not to use such responses for extensions that may later be submitted for registration 🙈.)
3.2.1. Generic Response Codes 🌸
The server MUST respond to any command with the appropriate one of the following generic responses if it represents the situation.
If the command isn't recognized, or if it's an optional command that the server doesn't implement, the response code 500 MUST be returned.
If there's a syntax error in the arguments of a recognized command, including when more arguments are provided than the command specifies, or when the command line is longer than the server accepts, the response code 501 MUST be returned. The line MUST NOT be truncated or split and then interpreted. Note that when a command has variants that depend on a second keyword (like LIST ACTIVE and LIST NEWSGROUPS), 501 MUST be used when the base command is implemented but the requested variant isn't, and 500 MUST be used only when the base command itself isn't implemented 🔥.
If an argument is required to be a base64-encoded string [RFC4648] (there are no such arguments in this specification, but there may be in extensions) and it isn't validly encoded, the response code 504 MUST be returned.
If the server hits an internal fault or problem that means it can't carry out the command (for example, a necessary file is missing or a necessary service couldn't be contacted), the response code 403 MUST be returned. If the server recognizes the command but doesn't provide an optional feature (for example, because it doesn't store the required information), or if it only handles a subset of legitimate cases (see the HDR command, Section 8.5, for an example), the response code 503 MUST be returned 💀.
If the client isn't authorized to use the specified facility in the server's current state, then the appropriate one of the following response codes MUST be used 🔐.
502: It's necessary to terminate the connection and start a new one with the appropriate authority before the command can be used. Historically, some mode-switching servers (see Section 3.4.1) used this response to say that the command will become available after the MODE READER command (Section 5.3) is used, but this usage doesn't conform to this specification and MUST NOT be used. Note that the server MUST NOT close the connection immediately after a 502 response, except at the initial connection (Section 5.1) and with the MODE READER command.480: The client must authenticate itself to the server (that is, it must provide information as to the identity of the client) before the facility can be used on this connection. This will involve the use of an authentication extension such as [NNTP-AUTH].483: The client must negotiate appropriate privacy protection on the connection. This will involve the use of a privacy extension such as [NNTP-TLS].401: The client must change the state of the connection in some other manner. The first argument of the response MUST be the capability label (see Section 5.2) of the facility that provides the necessary mechanism (usually an extension, which may be a private extension). The server MUST NOT use this response code except as specified by the definition of the capability in question 🗝️.
If the server has to terminate the connection for some reason, it MUST give a 400 response code to the next command and then immediately close the connection.
Heads up bestie: after a 400 response, clients SHOULD NOT just reconnect immediately and retry the same actions 🚫. Instead, a client SHOULD either use an exponentially increasing delay between retries (for example, double the waiting time after each 400 response), or present any associated text to the user so they can decide whether and when to retry ⏳.
The client MUST be prepared to receive any of these responses for any command (except, of course, that the server MUST NOT generate a 500 response code for mandatory commands) 💜.
3.2.1.1. Examples 🍓
Example of an unknown command:
[C] MAIL
[S] 500 Unknown commandExample of an unsupported command:
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] NEWNEWS
[S] LIST ACTIVE NEWSGROUPS
[S] .
[C] OVER
[S] 500 Unknown commandExample of an unsupported variant:
[C] MODE POSTER
[S] 501 Unknown MODE optionExample of a syntax error:
[C] ARTICLE a.message.id@no.angle.brackets
[S] 501 Syntax errorExample of an overlong command line:
[C] HEAD 53 54 55
[S] 501 Too many argumentsExample of a bad wildmat:
[C] LIST ACTIVE u[ks].*
[S] 501 Syntax errorExample of a base64-encoding error (the second argument is meant to be base64 encoded):
[C] XENCRYPT RSA abcd=efg
[S] 504 Base64 encoding errorExample of an attempt to access a facility not available to this connection:
[C] MODE READER
[S] 200 Reader mode, posting permitted
[C] IHAVE <i.am.an.article.you.will.want@example.com>
[S] 500 Permission deniedExample of an attempt to access a facility requiring authentication:
[C] GROUP secret.group
[S] 480 Permission deniedExample of a successful attempt following such authentication:
[C] XSECRET fred flintstone
[S] 290 Password for fred accepted
[C] GROUP secret.group
[S] 211 5 1 20 secret.group selectedExample of an attempt to access a facility requiring privacy:
[C] GROUP secret.group
[S] 483 Secure connection required
[C] XENCRYPT
[Client and server negotiate encryption on the link]
[S] 283 Encrypted link established
[C] GROUP secret.group
[S] 211 5 1 20 secret.group selectedExample of a need to change mode before a facility is used:
[C] GROUP binary.group
[S] 401 XHOST Not on this virtual host
[C] XHOST binary.news.example.org
[S] 290 binary.news.example.org virtual host selected
[C] GROUP binary.group
[S] 211 5 1 77 binary.group selectedExample of a temporary failure:
[C] GROUP archive.local
[S] 403 Archive server temporarily offlineExample of the server needing to close down immediately:
[C] ARTICLE 123
[S] 400 Power supply failed, running on UPS
[Server closes connection.]3.3. Capabilities and Extensions 🦋
Not all NNTP servers offer exactly the same facilities 🌈. That's partly because this specification allows variation, and partly because servers may provide extensions. A set of related facilities is called a "capability" 💅. This specification gives you a way to find out which capabilities are available, includes a list of standard capabilities, and includes a mechanism (the extension mechanism) for defining new capabilities ✨.
3.3.1. Capability Descriptions 💖
okay bestie, so a client can figure out what the server can do by using the CAPABILITIES command (see Section 5.2) 💅. The server sends back a capability list, which is basically a list of capability lines, and each line describes one thing the server can do 🦋.
Each capability line is made of one or more tokens, and they MUST be separated by one or more space or TAB characters 🎀. A token is a string of 1 or more printable UTF-8 characters. That means printable US-ASCII characters, or any UTF-8 sequence outside the US-ASCII range, but not space or TAB 🫶. Unless it says otherwise, tokens are case insensitive 🌸. Each capability line has the following parts:
- The capability label, which is a keyword that tells you what the capability is. A capability label may be defined by this specification or a successor, or by an extension.
- The label is followed by zero or more tokens, which are arguments of the capability. What these tokens look like and what they mean depends on each capability 🧚.
The server MUST make sure the capability list accurately reflects the capabilities (including extensions) that are currently available 👑. If a capability is only available in a certain state (for example, only after authentication), the list MUST only include the capability label when the server is in that state ✨. Same vibe for extensions: if only some of the commands in an extension will be available, or if the behaviour of the extension changes in some other way depending on the state of the server, this MUST be shown with different arguments in the capability line 💜.
Heads up, a capability line can only begin with a letter 🙈. Lines starting with other characters are reserved for future versions of this specification. So to play nicely with those future versions, clients MUST be prepared to receive lines that begin with other characters, and MUST ignore any they do not understand 🫶.
3.3.2. Standard Capabilities 🎀
The following capabilities are defined by this specification 🌈.
VERSION This capability MUST be advertised by all servers, and MUST be the first capability in the capability list 👑. It shows which version(s) of NNTP the server supports. There must be at least one argument. Each argument is a decimal number and MUST NOT have a leading zero 💅. Version numbers are only assigned in RFCs that update or replace this specification, so servers MUST NOT create their own version numbers 🙅♀️.
The version number of this specification is 2 🦋.
READER This capability shows that the server implements the various commands useful for reading clients 📖.
IHAVE This capability shows that the server implements the IHAVE command 🍓.
POST This capability shows that the server implements the POST command 💌.
NEWNEWS This capability shows that the server implements the NEWNEWS command 🌸.
HDR This capability shows that the server implements the header access commands (HDR and LIST HEADERS) 🧠.
OVER This capability shows that the server implements the overview access commands (OVER and LIST OVERVIEW.FMT). If and only if the server supports the message-id form of the OVER command, there must be a single argument MSGID 🔥.
LIST This capability shows that the server implements at least one variant of the LIST command. There MUST be one argument for each variant of the LIST command the server supports, giving the keyword for that variant 📋.
IMPLEMENTATION This capability MAY be provided by a server. If it is, the arguments SHOULD be used to share things like the server software name and version number 🛠️. The client MUST NOT use this line to figure out the server's capabilities 🙅♀️. (Servers often give this info in the initial greeting, but clients have to guess whether that's the case. This capability makes it crystal clear what the info is 💀.)
MODE-READER This capability shows that the server is mode-switching (Section 3.4.2), and that the MODE READER command needs to be used to turn on the READER capability 🔀.
3.3.3. Extensions 🧚
Okay, so NNTP is super widely and robustly deployed, but some parts of the Internet community might want to extend the NNTP service 🌍. It must be emphasized that any extension to NNTP should not be considered lightly 🚨. NNTP's strength comes mainly from its simplicity 💖. Experience with lots of protocols has shown that:
Protocols with few options tend towards ubiquity, whilst protocols with many options tend towards obscurity. 🌷
So each and every extension, no matter how good its benefits are, must be carefully scrutinized for its implementation, deployment, and interoperability costs 🔍. In lots of cases, the cost of extending the NNTP service will likely outweigh the benefit 😭.
An extension is a package of associated facilities. It often, but not always, includes one or more new commands 🎁. Each extension MUST define at least one new capability label (this will often, but need not, be the name of one of these new commands) 🏷️. Any extra capability info can normally be given using arguments to that label, but an extension MAY define more than one capability label. However, this SHOULD be limited to exceptional circumstances 🫣.
An extension is either a private extension, or its capabilities are listed in the IANA registry of capabilities (see Section 3.3.4) and it is defined in an RFC. In the second case it's called a "registered extension". Those RFCs either must be on the standards track, or must define an IESG-approved experimental protocol 🎓.
The definition of an extension must include the following:
- a descriptive name for the extension 🏷️.
- the capability label or labels defined by the extension (the capability label of a registered extension MUST NOT begin with "X") ❌.
- The syntax, values, and meanings of any arguments for each capability label defined by the extension 📐.
- Any new NNTP commands associated with the extension (the names of commands associated with registered extensions MUST NOT begin with "X") 🙅♀️.
- The syntax and possible values of arguments associated with the new NNTP commands 🔤.
- The response codes and possible values of arguments for the responses of the new NNTP commands 📬.
- Any new arguments the extension associates with any other pre-existing NNTP commands 🧩.
- Any increase in the maximum length of commands and initial response lines over the value specified in this document 📏.
- A specific statement about the effect on pipelining that this extension may have (if any) 🚀.
- A specific statement about the circumstances when use of this extension can change the contents of the capabilities list (other than the new capability labels it defines) 🔄.
- A specific statement about the circumstances under which the extension can cause any pre-existing command to produce a 401, 480, or 483 response ⚠️.
- A description of how the use of
MODE READERon a mode-switching server interacts with the extension 🔀. - A description of how support for the extension affects the behaviour of a server and NNTP client in any other way not outlined above 🎀.
- Formal syntax as described in Section 9.9 📜.
A private extension MAY or MAY NOT be included in the capabilities list 🤷♀️. If it is, the capability label MUST begin with "X" ✖️. A server MAY give additional keywords (for new commands and also for new variants of existing commands) as part of a private extension 🎁. To avoid a clash with a future registered extension, these keywords SHOULD begin with "X" 💅.
If the server advertises a capability defined by a registered extension, it MUST implement the extension so that it fully conforms with the specification (for example, it MUST implement all the commands that the extension describes as mandatory) 💯. If it does not implement the extension as specified, it MUST NOT list the extension in the capabilities list under its registered name. In that case, it MAY, but SHOULD NOT, provide a private extension (not listed, or listed with a different name) that implements part of the extension, or implements the commands of the extension with a different meaning 🙈.
A server MUST NOT send different response codes to basic NNTP commands documented here, or to commands documented in registered extensions, in response to the availability or use of a private extension 🛡️✨.
3.3.4. Initial IANA Register 🎀
okay so IANA keeps a registry of NNTP capability labels 📋 and bestie, every label in there MUST be a keyword and MUST NOT start with X 🙅♀️ no exceptions, periodt 💅
the starting list looks like this 👇
+-------------------+--------------------------+--------------------+
| Label | Meaning | Definition |
+-------------------+--------------------------+--------------------+
| AUTHINFO | Authentication | [NNTP-AUTH] |
| | | |
| HDR | Batched header retrieval | Section 3.3.2, |
| | | Section 8.5, and |
| | | Section 8.6 |
| | | |
| IHAVE | IHAVE command available | Section 3.3.2 and |
| | | Section 6.3.2 |
| | | |
| IMPLEMENTATION | Server | Section 3.3.2 |
| | implementation-specific | |
| | information | |
| | | |
| LIST | LIST command variants | Section 3.3.2 and |
| | | Section 7.6.1 |
| | | |
| MODE-READER | Mode-switching server | Section 3.4.2 |
| | and MODE READER command | |
| | available | |
| | | |
| NEWNEWS | NEWNEWS command | Section 3.3.2 and |
| | available | Section 7.4 |
| | | |
| OVER | Overview support | Section 3.3.2, |
| | | Section 8.3, and |
| | | Section 8.4 |
| | | |
| POST | POST command available | Section 3.3.2 and |
| | | Section 6.3.1 |
| | | |
| READER | Reader commands | Section 3.3.2 |
| | available | |
| | | |
| SASL | Supported SASL | [NNTP-AUTH] |
| | mechanisms | |
| | | |
| STARTTLS | Transport layer security | [NNTP-TLS] |
| | | |
| STREAMING | Streaming feeds | [NNTP-STREAM] |
| | | |
| VERSION | Supported NNTP versions | Section 3.3.2 |
+-------------------+--------------------------+--------------------+3.4. Mandatory and Optional Commands 🌸
ngl this one is so fair 🥹 not every command is mandatory, but it's also giving chaos if EVERY command is optional, because then a client has zero clue what's available 😭 so the compromise is that some commands are mandatory (every server MUST support them) and the rest are optional and grouped into bundles, each bundle named by one capability label ✨
- if the label shows up in the capability list the server sends back, the server MUST support every command in that bundle 🫶
- if the label is missing, the server MAY support none or some of the commands but SHOULD NOT support all of them 🙈 and honestly a client usually can't tell which ones work without just trying them 💀
the bundles are picked to be actually useful, so server authors are discouraged from doing only part of a bundle 🎀
each command's description either says it's mandatory, or uses the phrase "indicating capability" to name the label that tells you whether its bundle is there 🔍
if a server doesn't implement a command, it MUST always send back a 500 generic response code (or a 501 generic response code when it's a variant of a command that depends on a second keyword and the base command is recognised) 😤 otherwise the command MUST be fully implemented as specified, and a server MUST NOT only partially implement any of the commands here 🚫 (client authors, heads up: some servers that don't follow this spec will send a 502 generic response code for commands they don't implement 👀)
Note: some commands need other commands to be run first 🧩 if the first one is implemented but the second one isn't, the first one MUST still produce the relevant specific response code 💜 for example, if ARTICLE (Section 6.2.1) is implemented but GROUP (Section 6.1.1) isn't, the right response to "ARTICLE 1234" is still 412 ✨
3.4.1. Reading and Transit Servers 📚
NNTP has traditionally been used in two different ways 🦋 the first is "reading", where a client grabs articles from a big store the server keeps so a user can read them now or later, and also sends the articles that user writes back to the server (that's "posting") so they can be stored and passed along to other stores and users 💅 the second is bulk transfer of articles from one store to another 🚚 since the hosts doing that are usually peers passing articles between each other rather than end-user machines, this is called "peering" or "transit" 🌐 (even so, one host is still the client and the other is the server, just so we're clear 🫶)
in practice these two jobs are SO different that some servers are built for reading or for transit, and so they skip the other job or only offer limited features 😭 other servers are more general and do both 🌈 the spec handles this by bundling the relevant commands: IHAVE is designed for transit, while the commands under the READER capability are designed for reading clients 🎀
except when the MODE READER command (Section 5.3) switches a mode-switching server, once a server advertises IHAVE or READER (or both), it MUST keep advertising them for the whole session 🔒
a server MAY give different connections different modes (transit, reader, or a mix) 🧚 and it MAY use outside info, like the client's IP address, to decide which mode a given connection gets 👀
the official TCP port for NNTP is 119 🔌 but if a host wants separate servers for transit and reading clients, port 433 SHOULD be used for the transit server and 119 for the reading server 💖
3.4.2. Mode Switching 🔀
an implementation MAY provide both transit and reader facilities on the same server, but SHOULD NOT, and instead makes the client pick which one it wants 🙃 a server like that is called a "mode-switching" server 🫧
a mode-switching server has two modes:
- Transit mode, which applies after the initial connection 🚚
- it MUST advertise the MODE-READER capability 📣
- it MUST NOT advertise the READER capability 🚫
however, the server MAY stop advertising the MODE-READER capability once the client uses any command except CAPABILITIES 🙈
- Reading mode, after a successful MODE READER command (see Section 5.3) 📖
- it MUST NOT advertise the MODE-READER capability 🙅♀️
- it MUST advertise the READER capability 💅
- it MAY NOT advertise the IHAVE capability, even if it was advertising it in transit mode 🫠
a client SHOULD only send a MODE READER command to a server that's advertising the MODE-READER capability 🎯 if the server doesn't support CAPABILITIES (so it isn't following this spec), the client MAY use this heuristic 🧠:
- if the client wants any "reader" commands, it SHOULD use the MODE READER command right after the initial connection 📚
- otherwise, it SHOULD NOT use the MODE READER command 🙅♀️
either way, it should be ready for some commands to be unavailable that would've worked if it had made the other choice 🥺
3.5. Pipelining 🚀
NNTP is designed to run over a reliable two-way connection like TCP 🛤️ so if a command doesn't depend on the response to the previous one, it shouldn't matter if it's sent before that response arrives 💨 doing this is called "pipelining" 🎀 but some server implementations throw away all the text the client sent after certain commands before they reply, and then pipelining gets messed up because commands get ignored or misread, and the client starts matching the wrong responses to the wrong commands 😩 pipelining has huge benefits, but servers sometimes behave like that, so this document puts certain requirements on both clients and servers 🫶
except where stated otherwise, a client MAY use pipelining 💫 that means it can send a command before getting the response to the previous one ✨ the server MUST allow pipelining and MUST NOT throw away any text it receives after a command 🙌 whether or not pipelining is used, the server MUST process commands in the order they were sent 📋
if a command's description says it "MUST NOT be pipelined", that command MUST end any pipeline 🛑 so the client MUST NOT send any following command until it receives the CRLF at the end of that command's response 🙅♀️ the server MAY ignore any data it gets after the command and before the CRLF at the end of the response is sent to the client 🫠
the initial connection must not be part of a pipeline, so the client MUST NOT send any command until it receives the CRLF at the end of the greeting 👑
if the client uses blocking system calls to send commands, it MUST make sure the amount of text it pipelines doesn't cause a deadlock between sending and receiving 🔐 how much text that is depends on the window sizes in the transmission layer, and it's typically 4k octets for TCP 📏 (since the server only sends data in response to the client's commands, the reverse problem doesn't happen 🥳)
3.5.1. Examples
Okay so here's how pipelining looks when it's done right 🫶:
[C] GROUP misc.test
[C] STAT
[C] NEXT
[S] 211 1234 3000234 3002322 misc.test
[S] 223 3000234 <45223423@example.com> retrieved
[S] 223 3000237 <668929@example.org> retrievedAnd here's a messy one 💀. MODE READER is not allowed to be pipelined, so this is a no-go:
[C] MODE READER
[C] DATE
[C] NEXT
[S] 200 Server ready, posting allowed
[S] 223 3000237 <668929@example.org> retrievedThe server threw away the DATE command completely 🗑️, so there's no 111 response to match it with. Bestie, that's the drama 😭.
3.6. Articles
NNTP is built for moving articles between clients and servers 📰✨. For this spec, articles have to follow the rules in this section, and clients and servers MUST correctly process any article they get from the other side as long as it follows those rules. This only covers what goes over NNTP, though. It doesn't stop a client or server from rejecting an article later because of its own local policy 🙅♀️. Also check out Appendix A for extra rules on article format in some NNTP setups 📚.
An article has two parts, the headers and the body 🎀. They're split by a single empty line, which is really two CRLF pairs in a row. (If there's more than one empty line, the second and later ones belong to the body.) To keep NNTP happy, an article MUST NOT include the octet NUL 🚫, MUST NOT contain the octets LF and CR unless they're part of a CRLF pair, and MUST end with a CRLF pair. The spec doesn't add any other limits on the body, so it MAY be empty 🫧.
The headers are one or more header lines. Each header line is a header name, then a colon, then a space, then the header content, then a CRLF, in that exact order 💅. The name is one or more printable US-ASCII characters (no colons allowed) and it is not case sensitive for this spec 🔤. There MAY be more than one header line with the same name. The content MUST NOT contain CRLF, and it MAY be empty.
Headers can be "folded," which means you can put a CRLF pair right before any TAB or space in the line 🌀. There MUST still be some other octet between any two CRLF pairs in a header line. (Folding makes the header line take up more than one line when it's shown or sent, but it's still called "a" header line, so don't get confused 😅.) Folding doesn't change what the header means, because the CRLF pairs from folding aren't part of the header content.
Header lines SHOULD NOT be folded before the space after the colon that comes after the header name, and they SHOULD include at least one octet other than %x09 or %x20 between CRLF pairs. BUT, if you get an article from somewhere else that breaks this rule, clients and servers MAY pass it along to each other without re-folding it 🫠.
The content of a header SHOULD be in UTF-8 💖. Still, if an implementation gets an article from elsewhere that uses octets from 128 to 255 in some other way, it MAY pass that article to a client or server without changing it. So implementations MUST be ready to receive headers like that, and the data made from them (like the responses from the OVER command, Section 8.3) 📦. They MUST NOT assume those headers are always UTF-8. Any outside processing of those headers, including figuring out which encoding was used, is outside the scope of this document 🙈.
Every article MUST have a unique message-id, and two articles offered by an NNTP server MUST NOT have the same message-id 🆔. For this spec, message-ids are opaque strings, and they have to meet these rules:
- A message-id MUST begin with
<, end with>, and MUST NOT contain the latter except at the end. - A message-id MUST be between 3 and 250 octets in length.
- A message-id MUST NOT contain octets other than printable US-ASCII characters.
Two message-ids are the same if and only if they're made of the same sequence of octets 👯♀️.
This spec doesn't say how an article's message-id gets decided ✋. If the server can't figure out a message-id from the article itself, it MUST make one up (and the article doesn't have to be changed because of it). Check Appendix A.2 for more 📖.
4. The WILDMAT Format 🎀
The WILDMAT format here is based on the version first made by Rich Salz [SALZ1992] 🧠. That version came from the pattern style of the UNIX "find" command, which is used to name files. It was made to give a single, consistent way to match patterns, the same way the UNIX shell matches filenames 🐚.
4.1. Wildmat Syntax
A wildmat is written in the ABNF [RFC4234] syntax below. It's a piece pulled from Section 9.8 ✂️.
wildmat = wildmat-pattern *("," ["!"] wildmat-pattern)
wildmat-pattern = 1*wildmat-item
wildmat-item = wildmat-exact / wildmat-wild
wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E /
UTF8-non-ascii ; exclude ! * , ? [ \ ]
wildmat-wild = "*" / "?"Note: the characters ",", "", "[", and "]" aren't allowed in wildmats 🚧, while * and ? are always wildcards 🃏. That's totally fine, because those characters can't show up in newsgroup names, which is the only thing wildmats are used for right now 📰. Backslash is often used to turn off the special meaning of a character, and brackets are used to make sets. But those tricks aren't universal, and working out what they mean in UTF-8 strings can get really complicated and doesn't match what people already do 🤯. So they were left out. A future extension to this spec might give them meaning 🔮.
4.2. Wildmat Semantics
A wildmat gets tested against a string, and the result is either a match or not 🎯. To do that, each <wildmat-pattern> gets matched against the string, and the rightmost pattern that matches is the one that counts. If that <wildmat-pattern> doesn't start with "!", the whole wildmat matches. If it does start with "!", or if no <wildmat-pattern> matches at all, the whole wildmat does not match 🙅♀️.
Let's try the wildmat "a*,!b,c*" 👀:
- The string "aaa" matches, because the rightmost match is with "a*".
- The string "abb" does not match, because the rightmost match is with "*b".
- The string "ccb" matches, because the rightmost match is with "c".
- The string "xxx" does not match, because no
<wildmat-pattern>matches.
A <wildmat-pattern> matches a string if the string can be cut into pieces, and each piece matches the matching <wildmat-item> in the pattern 🧩. The matches have to be in the same order, and the whole string has to be used up. The pattern is "anchored," which means the first and last characters of the string have to match the first and last items, respectively. (The exception is when that item is an asterisk matching zero characters 🙃.)
A <wildmat-exact> matches the same character, which might be more than one octet in UTF-8 ✨.
"?" matches exactly one character, which might also be more than one octet 🎯.
"*" matches zero or more characters 🌊. It can match an empty string, but it can't match part of a UTF-8 sequence that doesn't line up with the character boundaries 🚫.
4.3. Extensions
An NNTP server or extension MAY extend the syntax or semantics of wildmats 🦋, as long as every wildmat that meets the requirements of Section 4.1 still means what Section 4.2 says it means 💜. Future editions of this document may also extend wildmats 🔮.
4.4. Examples
In these examples, $ and @ stand for the two octets %xC2 and %xA3 🪙. Put together, $@ is the UTF-8 encoding for the pound sterling symbol, which is shown as # in the descriptions 💷.
Wildmat Description of strings that match
abc The one string "abc"
abc,def The two strings "abc" and "def"
$@ The one character string "#"
a* Any string that begins with "a"
a*b Any string that begins with "a" and ends with "b"
a*,*b Any string that begins with "a" or ends with "b"
a*,!*b Any string that begins with "a" and does not end with
"b"
a*,!*b,c* Any string that begins with "a" and does not end with
"b", and any string that begins with "c" no matter
what it ends with
a*,c*,!*b Any string that begins with "a" or "c" and does not
end with "b"
?a* Any string with "a" as its second character
??a* Any string with "a" as its third character
*a? Any string with "a" as its penultimate character
*a?? Any string with "a" as its antepenultimate character5. Session Administration Commands 💅
5.1. Initial Connection
5.1.1. Usage
This command MUST NOT be pipelined 🚫.
Responses [1]
200 Service available, posting allowed
201 Service available, posting prohibited
400 Service temporarily unavailable [2]
502 Service permanently unavailable [2][1] These are the only valid response codes for the initial greeting; the server MUST not return any other generic response code.
[2] Following a 400 or 502 response, the server MUST immediately close the connection.
5.1.2. Description
When you first connect, the client doesn't send any command 🙌. The server MUST send an appropriate response code as its greeting. That greeting tells the client two things: whether service is available, and whether the client is allowed to post 📬.
If the server will take more commands from the client, including POST, the server MUST send a 200 greeting code 💚. If the server will take more commands from the client, but the client isn't allowed to post articles with the POST command, the server MUST send a 201 greeting code 🩷.
Otherwise, the server MUST send a 400 or 502 greeting code and then immediately close the connection 🔌. 400 SHOULD be used if the problem is only temporary (like because of load), and the client can expect to connect successfully at some point later without changing anything 🕐. 502 MUST be used if the client is never allowed to interact with the server under any circumstances 🙅♀️. It MAY be used if the server doesn't have enough info to tell whether the problem is temporary or permanent 🤷♀️.
Note: the difference between the 200 and 201 codes turned out to be not enough in practice 😩. For example, some servers don't allow posting until the client has logged in, while other clients assume a 201 means posting will never be possible, even after authentication. So clients SHOULD use the CAPABILITIES command (Section 5.2) instead of relying on this response 🫶.
5.1.3. Examples 🎀
okay so first up, a normal connection from an authorized client that then ends the session (see Section 5.4) 💅:
[Initial connection set-up completed.]
[S] 200 NNTP Service Ready, posting permitted
[C] QUIT
[S] 205 NNTP Service exits normally
[Server closes connection.]next, a normal connection from an authorized client that is not permitted to post, and it also ends right away 🙈:
[Initial connection set-up completed.]
[S] 201 NNTP Service Ready, posting prohibited
[C] QUIT
[S] 205 NNTP Service exits normally
[Server closes connection.]a normal connection from an unauthorized client 💀:
[Initial connection set-up completed.]
[S] 502 NNTP Service permanently unavailable
[Server closes connection.]and a connection where the server just can't provide service right now 😭:
[Initial connection set-up completed.]
[S] 400 NNTP Service temporarily unavailable
[Server closes connection.]5.2. CAPABILITIES 🦋
5.2.1. Usage
This command is mandatory ✨.
Syntax
CAPABILITIES [keyword]
Responses
101 Capability list follows (multi-line)
Parameters
keyword additional feature, see description5.2.2. Description
the CAPABILITIES command lets a client check what the server can do at any given moment 🔮. You MAY send this command at any time, and the server MUST NOT make you send it before you're allowed to use any capability 🙅. The answer MAY change during a session, because other state information can shift (and that can happen because of other commands or because of outside events). So the only way to get the current, correct info about what's available is to send CAPABILITIES at that exact point in the session and actually process what comes back ✅.
The capability list comes back as a multi-line data block after the 101 response code 📜. Each capability gets its own capability line. The server MUST NOT list the same capability twice in the response, even with different arguments 🚫. The one exception is that the VERSION capability MUST be the first line. Other than that, the order of the capability lines doesn't matter, and the server doesn't even need to return the same order every time 🌀.
Some capabilities are pretty much always on or always off 💤, but others (especially extensions) can pop in and out 🎢 because server state changes mid-session or outside stuff happens between sessions. A client MAY cache the results of this command, but it MUST NOT rely on cached results being correct, whether they're from earlier in this session or an older one. It MUST cope gracefully when the cached status is out of date, and it SHOULD (if it's caching results) give itself a way to force a refresh 🔄. Furthermore, a client MUST NOT use cached results for security, privacy, and authentication extensions 🔐. See Section 12.6 for more on this.
The keyword argument isn't used by this specification 🧩. It's there so that extensions or revisions can add extra features to this command without needing CAPABILITIES to be sent twice (once to check whether the extra features are available, and again to actually use them). If the server doesn't recognise the argument (and it is a keyword), it MUST respond with the 101 response code as if the argument had been omitted. If an argument is provided that the server does recognise, it MAY use the 101 response code, or it MAY use some other response code (which will be defined in the specification of that feature). If the argument is not a keyword, the 501 generic response code MUST be returned. The server MUST NOT generate any other response code to the CAPABILITIES command 🙃.
5.2.3. Examples
here's a minimal response from a read-only server 📖:
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] LIST ACTIVE NEWSGROUPS
[S] .and a response from a server with a whole range of facilities that also describes itself 🌈:
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] IHAVE
[S] POST
[S] NEWNEWS
[S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES OVERVIEW.FMT
[S] IMPLEMENTATION INN 4.2 2004-12-25
[S] OVER MSGID
[S] STREAMING
[S] XSECRET
[S] .a server that supports more than one version of NNTP 👯:
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2 3
[S] READER
[S] LIST ACTIVE NEWSGROUPS
[S] .and a client trying to use a feature of the CAPABILITIES command that the server doesn't support 🙈:
[C] CAPABILITIES AUTOUPDATE
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] IHAVE
[S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT HEADERS
[S] OVER MSGID
[S] HDR
[S] NEWNEWS
[S] .5.3. MODE READER 🪄
5.3.1. Usage
Indicating capability: MODE-READER 🏷️
This command MUST NOT be pipelined 🚧.
Syntax
MODE READER
Responses
200 Posting allowed
201 Posting prohibited
502 Reading service permanently unavailable [1]
[1] Following a 502 response the server MUST immediately close the
connection.5.3.2. Description
the MODE READER command tells a mode-switching server to switch modes, as described in Section 3.4.2 🔁.
If the server is mode-switching, it switches from its transit mode to its reader mode, and it shows this by changing its capability list to match 📋. It MUST then return a 200 or 201 response with the same meaning as for the initial greeting (as described in Section 5.1.1). Note that this response doesn't need to match the one from the initial greeting 🤷. The client MUST NOT issue MODE READER more than once in a session, or after any security or privacy commands are issued. When MODE READER is issued, the server MAY reset its state to what it was immediately after the initial connection, before switching mode.
If the server is not mode-switching, then the following apply:
- If it advertises the READER capability, it MUST return a 200 or 201 response with the same meaning as for the initial greeting. In this case, the command MUST NOT affect the server state in any way 🫶.
- If it does not advertise the READER capability, it MUST return a 502 response and then immediately close the connection 👋.
5.3.3. Examples
first, MODE READER on a transit-only server (which therefore doesn't provide reading facilities) 🚚:
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] IHAVE
[S] .
[C] MODE READER
[S] 502 Transit service only
[Server closes connection.]next, MODE READER on a server that provides reading facilities 📚:
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] LIST ACTIVE NEWSGROUPS
[S] .
[C] MODE READER
[S] 200 Reader mode, posting permitted
[C] IHAVE <i.am.an.article.you.have@example.com>
[S] 500 Permission denied
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.testNote that in both of these situations, the client SHOULD NOT use MODE READER 🙅.
and MODE READER on a mode-switching server 🦋:
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] IHAVE
[S] MODE-READER
[S] .
[C] MODE READER
[S] 200 Reader mode, posting permitted
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] NEWNEWS
[S] LIST ACTIVE NEWSGROUPS
[S] STARTTLS
[S] .In this case, the server offers (but does not require) TLS privacy in its reading mode, but not in its transit mode 🔒.
and finally, MODE READER where the client isn't permitted to post 📵:
[C] MODE READER
[S] 201 NNTP Service Ready, posting prohibited5.4. QUIT 👋
5.4.1. Usage
This command is mandatory 💜.
Syntax
QUIT
Responses
205 Connection closing5.4.2. Description
clients use the QUIT command to end the session 👋. The server MUST acknowledge the QUIT command and then close the connection to the client. This is the preferred way for a client to say it has finished all of its transactions with the NNTP server 🎀.
If a client simply disconnects (or the connection times out, or some other fault happens), the server MUST gracefully stop trying to serve that client, disconnecting from its end if necessary 🫧.
The server MUST NOT generate any response code to the QUIT command other than 205 or, if any arguments are provided, 501. 🚫
5.4.3. Examples
[C] QUIT
[S] 205 closing connection
[Server closes connection.]6. Article Posting and Retrieval ✨
News-reading clients have a whole bunch of ways to grab articles over NNTP 📰. The articles are stored and indexed using three types of keys 🗝️. The first type is the message-id of an article, and it's globally unique. The second type is a newsgroup name plus an article number within that newsgroup. On a particular server, there MUST only be one article with a given number within any newsgroup, and an article MUST NOT have two different numbers in the same newsgroup. An article can be cross-posted to multiple newsgroups, so there may be multiple keys pointing at the same article on the same server, and these MAY have different numbers in each newsgroup. However, this type of key is not required to be globally unique, so the same key MAY refer to different articles on different servers 🌍. (Note that the terms "group" and "newsgroup" are equivalent.)
The final type of key is the arrival timestamp, which gives the time the article reached the server ⏰. The server MUST ensure that article numbers are issued in order of arrival timestamp. That means articles arriving later MUST have higher numbers than those that arrive earlier. The server SHOULD allocate the next sequential unused number to each new article 🔢.
Article numbers MUST lie between 1 and 2,147,483,647, inclusive 🎯. The client and server MAY use leading zeroes when specifying article numbers, but they MUST NOT use more than 16 digits. In some situations, the value zero stands in for an article number to show some special situation 🙃.
Note that it is likely the article number limit of 2,147,483,647 will be increased by a future revision or extension to this specification 📈. While servers MUST NOT send article numbers greater than this current limit, client and server developers are advised to use internal structures and datatypes that can handle larger values, in anticipation of such a change 🧠.
6.1. Group and Article Selection 🎯
The following commands are used to set the "currently selected newsgroup" and the "current article number", which various commands rely on 🫶. At the start of an NNTP session, both of these values are set to the special value "invalid" 🙅.
6.1.1. GROUP
6.1.1.1. Usage 🎀
Indicating capability: READER
Syntax
GROUP group
Responses
211 number low high group Group successfully selected
411 No such newsgroup
Parameters
group Name of newsgroup
number Estimated number of articles in the group
low Reported low water mark
high Reported high water mark6.1.1.2. Description 💖
okay so the GROUP command is how you pick a newsgroup as your currently selected newsgroup and get the summary tea on it ✨ bestie this one is lowkey the foundation of everything in 6.1 so pay attention 🫶
The argument you give it is the name of the newsgroup you want (like "news.software.nntp"). If you need the list of valid newsgroups, you can use LIST ACTIVE (see Section 7.6.3) 🌸
When it works, the server sends back the article numbers of the first and last articles in the group right at that moment, which are called the "reported low water mark" and the "reported high water mark" 🦋 It also sends an estimate of how many articles are currently in the group.
If the group is not empty, the estimate MUST be at least the actual number of articles available and MUST be no greater than one more than the difference between the reported low and high water marks. (Some implementations will actually count the number of articles currently stored. Others will just subtract the low water mark from the high water mark and add one to get an estimate.) 🧮
If the group is empty, one of three situations will happen 🍓 Clients MUST accept all three cases, and servers MUST NOT represent an empty group in any other way, no exceptions periodt 💅
- The high water mark will be one less than the low water mark, and the estimated article count will be zero. Servers SHOULD use this method to show an empty group. This is the only time that the high water mark can be less than the low water mark.
- All three numbers will be zero.
- The high water mark is greater than or equal to the low water mark. The estimated article count might be zero or non-zero; if it is non-zero, the same requirements apply as for a non-empty group.
The set of articles in a group can change after you run GROUP, so here's the drama 🎭
- Articles may be removed from the group.
- Articles may be reinstated in the group with the same article number, but those articles MUST have numbers no less than the reported low water mark (note that this is a reinstatement of the previous article, not a new article reusing the number). 👑
- New articles may be added with article numbers greater than the reported high water mark. (If an article that was the one with the highest number has been removed and the high water mark has been adjusted accordingly, the next new article will not have the number one greater than the reported high water mark.)
Except when the group is empty and all three numbers are zero, whenever a later GROUP command for the same newsgroup is issued, whether by the same client or a different client, the reported low water mark in the response MUST be no less than that in any previous response for that newsgroup in this session. It SHOULD be no less than that in any previous response for that newsgroup ever sent to any client, and any failure to meet that latter condition SHOULD be transient only. The client may use the low water mark to remove all remembered information about articles with lower numbers, since those will never recur 🧹 This includes the situation when the high water mark is one less than the low water mark. No similar assumption can be made about the high water mark, because it can decrease if an article is removed and then increase again if the article is reinstated or if new articles arrive. Not me being confused by that 😭
When a valid group is selected with this command, the currently selected newsgroup MUST be set to that group, and the current article number MUST be set to the first article in the group. This applies even if the group is already the currently selected newsgroup. If an empty newsgroup is selected, the current article number is made invalid. If an invalid group is specified, the currently selected newsgroup and current article number MUST NOT be changed. ✨
The GROUP or LISTGROUP command (see Section 6.1.2) MUST be used by a client, and a successful response received, before any other command is used that depends on the value of the currently selected newsgroup or current article number. Main character energy, the order matters 🌈
If the group specified is not available on the server, a 411 response MUST be returned. 🙈
6.1.1.3. Examples 🧚
Example for a group known to the server:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.testExample for a group unknown to the server:
[C] GROUP example.is.sob.bradner.or.barber
[S] 411 example.is.sob.bradner.or.barber is unknownExample of an empty group using the preferred response:
[C] GROUP example.currently.empty.newsgroup
[S] 211 0 4000 3999 example.currently.empty.newsgroupExample of an empty group using an alternative response:
[C] GROUP example.currently.empty.newsgroup
[S] 211 0 0 0 example.currently.empty.newsgroupExample of an empty group using a different alternative response:
[C] GROUP example.currently.empty.newsgroup
[S] 211 0 4000 4321 example.currently.empty.newsgroupExample reselecting the currently selected newsgroup:
[C] GROUP misc.test
[S] 211 1234 234 567 misc.test
[C] STAT 444
[S] 223 444 <123456@example.net> retrieved
[C] GROUP misc.test
[S] 211 1234 234 567 misc.test
[C] STAT
[S] 223 234 <different@example.net> retrieved6.1.2. LISTGROUP 🦋
6.1.2.1. Usage 💜
Indicating capability: READER
Syntax
LISTGROUP [group [range]]
Responses
211 number low high group Article numbers follow (multi-line)
411 No such newsgroup
412 No newsgroup selected [1]
Parameters
group Name of newsgroup
range Range of articles to report
number Estimated number of articles in the group
low Reported low water mark
high Reported high water mark
[1] The 412 response can only occur if no group has been specified.6.1.2.2. Description 🌷
LISTGROUP selects a newsgroup in the same way GROUP does (see Section 6.1.1), but it also gives you a list of article numbers in that newsgroup 🎀 If you don't name a group, the currently selected newsgroup gets used.
On success, you get a list of article numbers as a multi-line data block after the 211 response code. (The arguments on the initial response line are the same as for the GROUP command.) The list has one number per line, in numerical order. It lists precisely the articles that exist in the group at the moment of selection, so an empty group gives you an empty list 🫧 If the optional range argument is specified, only articles within that range are included, so the list MAY be empty even if the group is not.
The range argument can be any of these:
- An article number.
- An article number followed by a dash to indicate all following.
- An article number followed by a dash followed by another article number.
In that last case, if the second number is less than the first, the range contains no articles. Leaving the range out is the same as specifying the range 1-. 🍭
If the group specified is not available on the server, a 411 response MUST be returned. If no group is specified and the currently selected newsgroup is invalid, a 412 response MUST be returned. 🙅♀️
Apart from the group argument being optional, a range argument being allowed, and a multi-line data block following the 211 response code, LISTGROUP is identical to GROUP. Most importantly, when it succeeds, the command sets the current article number to the first article in the group, if there is one, even if that article is not within the range given by the second argument. 🧠
Note that the range argument is a new feature in this specification. Servers that do not support CAPABILITIES (and therefore do not conform to this specification) are unlikely to support it 💀
6.1.2.3. Examples 🍓
Example of LISTGROUP being used to select a group:
[C] LISTGROUP misc.test
[S] 211 2000 3000234 3002322 misc.test list follows
[S] 3000234
[S] 3000237
[S] 3000238
[S] 3000239
[S] 3002322
[S] .Example of LISTGROUP on an empty group:
[C] LISTGROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup list follows
[S] .Example of LISTGROUP on a valid, currently selected newsgroup:
[C] GROUP misc.test
[S] 211 2000 3000234 3002322 misc.test
[C] LISTGROUP
[S] 211 2000 3000234 3002322 misc.test list follows
[S] 3000234
[S] 3000237
[S] 3000238
[S] 3000239
[S] 3002322
[S] .Example of LISTGROUP with a range:
[C] LISTGROUP misc.test 3000238-3000248
[S] 211 2000 3000234 3002322 misc.test list follows
[S] 3000238
[S] 3000239
[S] .Example of LISTGROUP with an empty range:
[C] LISTGROUP misc.test 12345678-
[S] 211 2000 3000234 3002322 misc.test list follows
[S] .Example of LISTGROUP with an invalid range:
[C] LISTGROUP misc.test 9999-111
[S] 211 2000 3000234 3002322 misc.test list follows
[S] .6.1.3. LAST 🌸
6.1.3.1. Usage ✨
Indicating capability: READER
Syntax
LAST
Responses
223 n message-id Article found
412 No newsgroup selected
420 Current article number is invalid
422 No previous article in this group
Parameters
n Article number
message-id Article message-id6.1.3.2. Description 🦋
If the currently selected newsgroup is valid, the current article number MUST be set to the previous article in that newsgroup. That means the highest existing article number that is less than the current article number. If it works, you get a response with the new current article number and the message-id of that article, and that response MUST be returned 🎯 No article text gets sent back for this command.
There MAY be no previous article in the group, even though the current article number is not the reported low water mark. There MUST NOT be a previous article when the current article number is the reported low water mark. 🫣
Because articles can be removed and added, the results of multiple LAST and NEXT commands MAY not be consistent over the life of a particular NNTP session. Plot twist, but it's giving unpredictable 🌀
If the current article number is already the first article of the newsgroup, a 422 response MUST be returned. If the current article number is invalid, a 420 response MUST be returned. If the currently selected newsgroup is invalid, a 412 response MUST be returned. In all three cases, the currently selected newsgroup and current article number MUST NOT be altered. Hands off, bestie 🙌💖
6.1.3.3. Examples ✨
Okay bestie, here are the examples for LAST 💖
Example of a successful article retrieval using LAST:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] NEXT
[S] 223 3000237 <668929@example.org> retrieved
[C] LAST
[S] 223 3000234 <45223423@example.com> retrievedExample of an attempt to retrieve an article without having selected a group (via the GROUP command) first:
[Assumes currently selected newsgroup is invalid.]
[C] LAST
[S] 412 no newsgroup selectedExample of an attempt to retrieve an article using the LAST command when the current article number is that of the first article in the group:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] LAST
[S] 422 No previous article to retrieveExample of an attempt to retrieve an article using the LAST command when the currently selected newsgroup is empty:
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] LAST
[S] 420 No current article selected6.1.4. NEXT 🦋
6.1.4.1. Usage
Indicating capability: READER
Syntax
NEXT
Responses
223 n message-id Article found
412 No newsgroup selected
420 Current article number is invalid
421 No next article in this group
Parameters
n Article number
message-id Article message-id6.1.4.2. Description
Okay so, if the currently selected newsgroup is valid, the current article number MUST be set to the next article in that newsgroup. That means the lowest existing article number that's greater than the current article number 🌸 If it works, a response showing the new current article number and that article's message-id MUST be returned. No article text gets sent back for this command, so don't expect a body 💅
If the current article number is already the last article of the newsgroup, a 421 response MUST be returned. Otherwise, NEXT is basically the same as LAST (Section 6.1.3), except obviously it doesn't have the 422 response. Iconic consistency 🎀
6.1.4.3. Examples
Example of a successful article retrieval using NEXT:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] NEXT
[S] 223 3000237 <668929@example.org> retrievedExample of an attempt to retrieve an article without having selected a group (via the GROUP command) first:
[Assumes currently selected newsgroup is invalid.]
[C] NEXT
[S] 412 no newsgroup selectedExample of an attempt to retrieve an article using the NEXT command when the current article number is that of the last article in the group:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] STAT 3002322
[S] 223 3002322 <411@example.net> retrieved
[C] NEXT
[S] 421 No next article to retrieveExample of an attempt to retrieve an article using the NEXT command when the currently selected newsgroup is empty:
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] NEXT
[S] 420 No current article selected6.2. Retrieval of Articles and Article Sections 📚
ARTICLE, BODY, HEAD, and STAT are super similar, bestie 💜 They only differ in which part of the article gets shown to the client and in the successful response code. ARTICLE gets the full explanation here, and the other three get described as "how they differ from ARTICLE." As Section 3.6 says, an article has two parts: the article headers and the article body.
When the server responds to one of these commands, it MUST present the entire article or the appropriate part, and it MUST NOT attempt to alter or translate it in any way. No edits, no vibes-based rewrites 🙅♀️
6.2.1. ARTICLE 💌
6.2.1.1. Usage
Indicating capability: READER
Syntax
ARTICLE message-id
ARTICLE number
ARTICLE
Responses
First form (message-id specified)
220 0|n message-id Article follows (multi-line)
430 No article with that message-id
Second form (article number specified)
220 n message-id Article follows (multi-line)
412 No newsgroup selected
423 No article with that number
Third form (current article number used)
220 n message-id Article follows (multi-line)
412 No newsgroup selected
420 Current article number is invalid
Parameters
number Requested article number
n Returned article number
message-id Article message-id6.2.1.2. Description
The ARTICLE command picks an article based on its arguments and then shows the client the whole thing: the headers, an empty line, and then the body, in that order ✨ There are three forms.
In the first form, you give a message-id and the server presents the article with that message-id. In this case the server MUST NOT alter the currently selected newsgroup or the current article number. This is so you can look up articles that get mentioned inside another article you're reading, and also because it's really hard to figure out the right order and membership of an article that got cross-posted to more than one newsgroup 🥺
In the response, the article number MUST be replaced with zero, unless there's a currently selected newsgroup and the article is actually in that group. Then the server MAY use the article's number in that group. (The server doesn't have to figure out whether the article is in the selected group or what number it has there, so the client MUST always be prepared for zero to show up 🫶) The server MUST NOT provide an article number unless using that number in a second ARTICLE command right after this one would return the same article. Even when the server does return article numbers in these situations, it doesn't have to be consistent about it. It MAY return zero to any such command. (Also see the STAT examples, Section 6.2.4.3.)
In the second form, you give an article number. If there's an article with that number in the currently selected newsgroup, the server MUST set the current article number to that number.
In the third form, the article that the current article number points to in the currently selected newsgroup is the one that gets used.
Heads up, though: a previously valid article number MAY become invalid if the article has been removed. And a previously invalid article number MAY become valid if the article has been reinstated, but that article number MUST be no less than the reported low water mark for that group 👀
The server MUST NOT change the currently selected newsgroup as a result of this command. The server MUST NOT change the current article number except when an article number argument was provided and the article exists. Most importantly, it MUST NOT change it after an unsuccessful response 🚫
Since each message-id is unique to one article, a client can use it to skip showing duplicate articles that got posted more than once, or posted to more than one newsgroup. Very efficient, very iconic 🧚
The article comes back as a multi-line data block after the 220 response code.
If the argument is a message-id and no such article exists, a 430 response MUST be returned. If the argument is a number or is left out and the currently selected newsgroup is invalid, a 412 response MUST be returned. If the argument is a number and that article doesn't exist in the currently selected newsgroup, a 423 response MUST be returned. If the argument is left out and the current article number is invalid, a 420 response MUST be returned 💀
6.2.1.3. Examples
Example of a successful retrieval of an article (explicitly not using an article number):
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] ARTICLE
[S] 220 3000234 <45223423@example.com>
[S] Path: pathost!demo!whitehouse!not-for-mail
[S] From: "Demo User" <nobody@example.net>
[S] Newsgroups: misc.test
[S] Subject: I am just a test article
[S] Date: 6 Oct 1998 04:38:40 -0500
[S] Organization: An Example Net, Uncertain, Texas
[S] Message-ID: <45223423@example.com>
[S]
[S] This is just a test article.
[S] .Example of a successful retrieval of an article by message-id:
[C] ARTICLE <45223423@example.com>
[S] 220 0 <45223423@example.com>
[S] Path: pathost!demo!whitehouse!not-for-mail
[S] From: "Demo User" <nobody@example.net>
[S] Newsgroups: misc.test
[S] Subject: I am just a test article
[S] Date: 6 Oct 1998 04:38:40 -0500
[S] Organization: An Example Net, Uncertain, Texas
[S] Message-ID: <45223423@example.com>
[S]
[S] This is just a test article.
[S] .Example of an unsuccessful retrieval of an article by message-id:
[C] ARTICLE <i.am.not.there@example.com>
[S] 430 No Such Article FoundExample of an unsuccessful retrieval of an article by number:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 news.groups
[C] ARTICLE 300256
[S] 423 No article with that numberExample of an unsuccessful retrieval of an article by number because no newsgroup was selected first:
[Assumes currently selected newsgroup is invalid.]
[C] ARTICLE 300256
[S] 412 No newsgroup selectedExample of an attempt to retrieve an article when the currently selected newsgroup is empty:
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] ARTICLE
[S] 420 No current article selected6.2.2. HEAD 🌈
6.2.2.1. Usage
This command is mandatory.
Syntax
HEAD message-id
HEAD number
HEAD
Responses
First form (message-id specified)
221 0|n message-id Headers follow (multi-line)
430 No article with that message-id
Second form (article number specified)
221 n message-id Headers follow (multi-line)
412 No newsgroup selected
423 No article with that number
Third form (current article number used)
221 n message-id Headers follow (multi-line)
412 No newsgroup selected
420 Current article number is invalid
Parameters
number Requested article number
n Returned article number
message-id Article message-id6.2.2.2. Description
HEAD acts exactly like ARTICLE, with two differences 🍓 If the article exists, the response code is 221 instead of 220, and only the headers get presented. The empty line that separates the headers from the body MUST NOT be included. Just the headers, no body, no empty line, a cute little header-only moment 🎀
6.2.2.3. Examples 📚
okay bestie, here are the HEAD examples 🎀 first up is a successful headers grab when you don't use an article number 🦋
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HEAD
[S] 221 3000234 <45223423@example.com>
[S] Path: pathost!demo!whitehouse!not-for-mail
[S] From: "Demo User" <nobody@example.net>
[S] Newsgroups: misc.test
[S] Subject: I am just a test article
[S] Date: 6 Oct 1998 04:38:40 -0500
[S] Organization: An Example Net, Uncertain, Texas
[S] Message-ID: <45223423@example.com>
[S] .next, the same successful headers retrieval but by message-id 💖
[C] HEAD <45223423@example.com>
[S] 221 0 <45223423@example.com>
[S] Path: pathost!demo!whitehouse!not-for-mail
[S] From: "Demo User" <nobody@example.net>
[S] Newsgroups: misc.test
[S] Subject: I am just a test article
[S] Date: 6 Oct 1998 04:38:40 -0500
[S] Organization: An Example Net, Uncertain, Texas
[S] Message-ID: <45223423@example.com>
[S] .now the message-id lookup that flops 💀
[C] HEAD <i.am.not.there@example.com>
[S] 430 No Such Article Foundand the number lookup that flops too, because that number isn't in the group 🙈
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HEAD 300256
[S] 423 No article with that numberthis one fails because no newsgroup got selected first 🫠
[Assumes currently selected newsgroup is invalid.]
[C] HEAD 300256
[S] 412 No newsgroup selectedand last but not least, asking for headers when the selected group is empty 🌸
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] HEAD
[S] 420 No current article selected6.2.3. BODY 🫧
6.2.3.1. Usage 💅
Here's the vibe: BODY is basically ARTICLE's cousin, so the layout is the same ✨
Indicating capability: READER
Syntax
BODY message-id
BODY number
BODY
Responses
First form (message-id specified)
222 0|n message-id Body follows (multi-line)
430 No article with that message-id
Second form (article number specified)
222 n message-id Body follows (multi-line)
412 No newsgroup selected
423 No article with that number
Third form (current article number used)
222 n message-id Body follows (multi-line)
412 No newsgroup selected
420 Current article number is invalid
Parameters
number Requested article number
n Returned article number
message-id Article message-id6.2.3.2. Description 🎀
BODY acts exactly like ARTICLE 💖 with two little differences. If the article exists, the response code is 222 instead of 220, and you only get the body. The empty line that separates the headers from the body MUST NOT be included 🙈
6.2.3.3. Examples 🦋
the body-only retrieval, no article number needed 📦
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] BODY
[S] 222 3000234 <45223423@example.com>
[S] This is just a test article.
[S] .same thing, but grabbed by message-id 🫶
[C] BODY <45223423@example.com>
[S] 222 0 <45223423@example.com>
[S] This is just a test article.
[S] .message-id that doesn't exist, so it's a no-go 😭
[C] BODY <i.am.not.there@example.com>
[S] 430 No Such Article Foundnumber that isn't in the group 🙃
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] BODY 300256
[S] 423 No article with that numberno newsgroup selected first, so it fails 🙅
[Assumes currently selected newsgroup is invalid.]
[C] BODY 300256
[S] 412 No newsgroup selectedand the empty group situation 🌈
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] BODY
[S] 420 No current article selected6.2.4. STAT 🔍
6.2.4.1. Usage 📋
this one is mandatory, so every server has to have it 👑
This command is mandatory.
Syntax
STAT message-id
STAT number
STAT
Responses
First form (message-id specified)
223 0|n message-id Article exists
430 No article with that message-id
Second form (article number specified)
223 n message-id Article exists
412 No newsgroup selected
423 No article with that number
Third form (current article number used)
223 n message-id Article exists
412 No newsgroup selected
420 Current article number is invalid
Parameters
number Requested article number
n Returned article number
message-id Article message-id6.2.4.2. Description 🧚
STAT is basically the ARTICLE command minus the drama 💅 If the article exists, it is NOT presented to the client, and you get 223 instead of 220. The response is NOT multi-line, so no endless wall of text 🙌
This is the best part: the client can check whether an article exists, and in the second and third forms find out its message-id, without processing an arbitrary amount of text 🫶
6.2.4.3. Examples 🌸
checking an existing article by not using a number 🌷
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] STAT
[S] 223 3000234 <45223423@example.com>checking an existing article by message-id 💜
[C] STAT <45223423@example.com>
[S] 223 0 <45223423@example.com>checking a message-id the server doesn't have 😭
[C] STAT <i.am.not.there@example.com>
[S] 430 No Such Article Foundchecking a number that isn't in the server 🙈
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] STAT 300256
[S] 423 No article with that numberchecking by number when no newsgroup got selected first 💀
[Assumes currently selected newsgroup is invalid.]
[C] STAT 300256
[S] 412 No newsgroup selectedchecking an article while the selected group is empty 🫠
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] STAT
[S] 420 No current article selectedand now the one where the server sometimes shares the real article number when you use a message-id 🦋
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] STAT
[S] 223 3000234 <45223423@example.com>
[C] STAT <45223423@example.com>
[S] 223 0 <45223423@example.com>
[C] STAT <45223423@example.com>
[S] 223 3000234 <45223423@example.com>
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] STAT <45223423@example.com>
[S] 223 0 <45223423@example.com>
[C] GROUP alt.crossposts
[S] 211 9999 111111 222222 alt.crossposts
[C] STAT <45223423@example.com>
[S] 223 123456 <45223423@example.com>
[C] STAT
[S] 223 111111 <23894720@example.com>so the breakdown 🧠✨: the first STAT sets up the article's identity in the group. The second and third show the server may, but need not, give the article number when you use a message-id. The fourth shows that zero must be specified if the article isn't in the currently selected newsgroup. The fifth shows that the number, if you give one, must be the one for the currently selected newsgroup. The last one shows that the current article number doesn't change just because you used STAT with a message-id, even if it returns an article number 💅
6.3. Article Posting 📮
okay so posting happens in one of two ways 💌 either a news-reading client posts one article at a time with POST, or another news server transfers articles over with IHAVE 🫶
6.3.1. POST 🎀
6.3.1.1. Usage 💖
POST is the one command that can't be pipelined 🙅 Here's the layout:
Indicating capability: POST
This command MUST NOT be pipelined.
Syntax
POST
Responses
Initial responses
340 Send article to be posted
440 Posting not permitted
Subsequent responses
240 Article received OK
441 Posting failed6.3.1.2. Description ✨
if posting is allowed, the server MUST return a 340 response so the client knows to send the article 📝 if posting is blocked for some installation-dependent reason, a 440 response MUST be returned instead 🚫
if posting is permitted, the article MUST be in the format from Section 3.6, and the client MUST send it as a multi-line data block (see Section 3.1.1). so a single dot (".") on its own line marks the end, and any line that starts with a dot gets that dot doubled during transmission 🦋
once the client sends the termination sequence, the server MUST return a response saying whether the article transfer worked 🎉 quick note: 340 and 440 are the replies to the POST command itself, while 240 and 441 come after the article gets sent 📬
a 240 SHOULD mean that, barring unforeseen server errors, the posted article will be made available on the server and/or transferred to other servers, as appropriate, possibly after further processing. in other words, articles the server doesn't want SHOULD be rejected with a 441, not accepted and then quietly thrown away 🗑️ but the client SHOULD NOT assume the article got transferred unless it gets a yes from the server, and it SHOULD NOT assume other clients can see it without checking explicitly (for example, with the STAT command) 👀
if the session gets interrupted before the response arrives, an affirmative response might have been sent and then lost 😱 so in any later session, the client SHOULD either check whether the article was posted successfully before resending, or make sure the server gives the new attempt the same message-id (see Appendix A.2). the second option is the one preferred, since the article might not be readable yet (for example, if it has to go through a moderation process) 🧐
6.3.1.3. Examples 📚
a successful post 🥰
[C] POST
[S] 340 Input article; end with <CR-LF>.<CR-LF>
[C] From: "Demo User" <nobody@example.net>
[C] Newsgroups: misc.test
[C] Subject: I am just a test article
[C] Organization: An Example Net
[C]
[C] This is just a test article.
[C] .
[S] 240 Article received OKan unsuccessful post 😤
[C] POST
[S] 340 Input article; end with <CR-LF>.<CR-LF>
[C] From: "Demo User" <nobody@example.net>
[C] Newsgroups: misc.test
[C] Subject: I am just a test article
[C] Organization: An Example Net
[C]
[C] This is just a test article.
[C] .
[S] 441 Posting faileda post attempt when posting isn't allowed 🚷
[Initial connection set-up completed.]
[S] 201 NNTP Service Ready, posting prohibited
[C] POST
[S] 440 Posting not permitted6.3.2. IHAVE 📮
6.3.2.1. Usage
Indicating capability: IHAVE
okay so this one is a no-pipelining zone 🙅♀️ This command MUST NOT be pipelined. 💅
Syntax
IHAVE message-id
Responses
Initial responses
335 Send article to be transferred
435 Article not wanted
436 Transfer not possible; try again later
Subsequent responses
235 Article transferred OK
436 Transfer failed; try again later
437 Transfer rejected; do not retry
Parameters
message-id Article message-id6.3.2.2. Description
okay bestie, IHAVE is basically the server going "hey, I already know about this article, do you have a copy?" ✨ If the server wants a copy, it MUST return a 335 response, which tells the client to send the entire article 📨 If the server doesn't want it (say it already has a copy, rude but fair 💀), it MUST return a 435 response saying the article is not wanted. And if it's a "not right now, maybe later" situation (like another client is already sending the same article 🙈), it MUST return a 436 response.
If the server asked for the article, the client MUST send the entire article, headers and body included, as a multi-line data block (see Section 3.1.1). So a single dot (".") on its own line means "the end of the text," and any line that starts with a dot in the original text gets that dot doubled during transmission 🦋 The server MUST return a 235 response if the article transfer went through OK ✅, a 436 response if it failed but should be tried again later, or a 437 response if the article was rejected 🙅♀️
this one is NOT the same as POST 🫶 IHAVE is for moving articles that have already been posted between hosts. It SHOULD NOT be used when the client is a personal news-reading program, because using it means the article was already posted somewhere else and is just getting forwarded from another host 📬 Even so, the server MAY still choose not to post or forward the article if it looks at the article more closely and decides it's not appropriate. Stuff like inappropriate newsgroups or distributions, disk space limits, article lengths, garbled headers, and so on can get an article turned away. Those are usually rules set by the server host's news software, not necessarily by the NNTP server itself 🧚
The client SHOULD NOT assume the article made it unless it gets a clear yes from the server 🙈 And if there's no response at all (like a dropped connection or a timeout), that SHOULD be treated the same as a 436 response.
Also, some news server software can't always tell right away whether an article is good to post or forward. So an NNTP server MAY send back a 235 response saying the transfer worked, and then quietly discard the article later 😭 the audacity, but it's allowed 🌸
6.3.2.3. Examples
Example of successfully sending an article to another site:
[C] IHAVE <i.am.an.article.you.will.want@example.com>
[S] 335 Send it; end with <CR-LF>.<CR-LF>
[C] Path: pathost!demo!somewhere!not-for-mail
[C] From: "Demo User" <nobody@example.com>
[C] Newsgroups: misc.test
[C] Subject: I am just a test article
[C] Date: 6 Oct 1998 04:38:40 -0500
[C] Organization: An Example Com, San Jose, CA
[C] Message-ID: <i.am.an.article.you.will.want@example.com>
[C]
[C] This is just a test article.
[C] .
[S] 235 Article transferred OKExample of sending an article to another site that rejects it. Heads up: the message-id in the IHAVE command is NOT the same as the one in the article headers. That's bad practice and it SHOULD NOT be done 🙅♀️ but it's not forbidden, so it's a vibe, not a crime 🙃
[C] IHAVE <i.am.an.article.you.will.want@example.com>
[S] 335 Send it; end with <CR-LF>.<CR-LF>
[C] Path: pathost!demo!somewhere!not-for-mail
[C] From: "Demo User" <nobody@example.com>
[C] Newsgroups: misc.test
[C] Subject: I am just a test article
[C] Date: 6 Oct 1998 04:38:40 -0500
[C] Organization: An Example Com, San Jose, CA
[C] Message-ID: <i.am.an.article.you.have@example.com>
[C]
[C] This is just a test article.
[C] .
[S] 437 Article rejected; don't send againExample of sending an article to another site where the transfer fails:
[C] IHAVE <i.am.an.article.you.will.want@example.com>
[S] 335 Send it; end with <CR-LF>.<CR-LF>
[C] Path: pathost!demo!somewhere!not-for-mail
[C] From: "Demo User" <nobody@example.com>
[C] Newsgroups: misc.test
[C] Subject: I am just a test article
[C] Date: 6 Oct 1998 04:38:40 -0500
[C] Organization: An Example Com, San Jose, CA
[C] Message-ID: <i.am.an.article.you.will.want@example.com>
[C]
[C] This is just a test article.
[C] .
[S] 436 Transfer failedExample of sending an article to a site that already has it:
[C] IHAVE <i.am.an.article.you.have@example.com>
[S] 435 DuplicateExample of sending an article to a site that requests that the article be tried again later:
[C] IHAVE <i.am.an.article.you.defer@example.com>
[S] 436 Retry later7. Information Commands 🔮
This section is all about the other commands you can use at any point between starting a session and ending it 💜 Using these doesn't change any state info, but the responses can still give clients some really useful intel 👀
7.1. DATE
7.1.1. Usage
Indicating capability: READER
Syntax:
DATEResponses:
111 yyyymmddhhmmss Server date and timeParameters:
yyyymmddhhmmss Current UTC date and time on server7.1.2. Description
This command helps clients find out the current Coordinated Universal Time [TF.686-1] from the server's point of view ⏰ It SHOULD NOT be used as a substitute for NTP [RFC1305]. It's more for giving you info that's handy when you're using the NEWNEWS command (see Section 7.4).
The DATE command MUST return a timestamp from the same clock used for figuring out article arrival and group creation times (see Section 6). That clock SHOULD be monotonic, and when it needs adjusting, it SHOULD be done by running it fast or slow compared to "real" time instead of making sudden jumps ✨ A system providing NNTP service SHOULD keep its clock as accurate as possible, either with NTP or some other method 🎀
The server MUST return a 111 response with the date and time on the server in the form yyyymmddhhmmss. That date and time is in Coordinated Universal Time 🌍
7.1.3. Examples
[C] DATE
[S] 111 199906231356247.2. HELP
7.2.1. Usage
This command is mandatory. 💖
Syntax:
HELPResponses:
100 Help text follows (multi-line)7.2.2. Description
This command gives a short summary of the commands this implementation of the server understands 📖 The help text comes as a multi-line data block right after the 100 response code.
The text isn't guaranteed to be in any particular format (but must be UTF-8), and it MUST NOT be used by clients as a replacement for the CAPABILITIES command described in Section 5.2. Don't be that client 🙅♀️
7.2.3. Examples
[C] HELP
[S] 100 Help text follows
[S] This is some help text. There is no specific
[S] formatting requirement for this test, though
[S] it is customary for it to list the valid commands
[S] and give a brief definition of what they do.
[S] .7.3. NEWGROUPS
7.3.1. Usage
Indicating capability: READER
Syntax:
NEWGROUPS date time [GMT]Responses:
231 List of new newsgroups follows (multi-line)Parameters:
date Date in yymmdd or yyyymmdd format
time Time in hhmmss format7.3.2. Description
This command returns a list of newsgroups created on the server since the date and time you give it 📚 The results use the same format as the LIST ACTIVE command (see Section 7.6.3). However, they MAY include groups that aren't available on the server (so LIST ACTIVE wouldn't return them), and they MAY leave out groups whose creation date isn't available 🌸
The date is 6 or 8 digits in the format [xx]yymmdd. Here, xx is the first two digits of the year (19-99), yy is the last two digits of the year (00-99), mm is the month (01-12), and dd is the day of the month (01-31). Clients SHOULD specify all four digits of the year 💅 If the first two digits aren't specified (that's only supported for backward compatibility, so it's a legacy thing 🦖), the year is taken from the current century if yy is smaller than or equal to the current year, and from the previous century otherwise.
The time is 6 digits in the format hhmmss. hh is the hours on the 24-hour clock (00-23), mm is the minutes (00-59), and ss is the seconds (00-60, to allow for leap seconds ⏱️). The token "GMT" says the date and time are in Coordinated Universal Time [TF.686-1]. If you leave it out, the date and time are in the server's local timezone. Heads up: there's no way to use the protocol in this document to figure out the server's local timezone 🤷♀️
An empty list is a totally valid response, and it just means there are no new newsgroups since that date-time 🫙
Clients SHOULD make all queries using Coordinated Universal Time (i.e., by including the "GMT" argument) when they can 🌍
7.3.3. Examples
Example where there are new groups:
[C] NEWGROUPS 19990624 000000 GMT
[S] 231 list of new newsgroups follows
[S] alt.rfc-writers.recovery 4 1 y
[S] tx.natives.recovery 89 56 y
[S] .Example where there are no new groups:
[C] NEWGROUPS 19990624 000000 GMT
[S] 231 list of new newsgroups follows
[S] .7.4. NEWNEWS
7.4.1. Usage
Indicating capability: NEWNEWS
Syntax:
NEWNEWS wildmat date time [GMT]Responses:
230 List of new articles follows (multi-line)Parameters:
wildmat Newsgroups of interest
date Date in yymmdd or yyyymmdd format
time Time in hhmmss format7.4.2. Description
This command returns a list of message-ids for articles posted or received on the server, in newsgroups whose names match the wildmat, since the date and time you specify 📬 One message-id goes on each line. The order doesn't mean anything and can change from response to response in the same session 🎲 A message-id MAY show up more than once, and if it does, it means exactly the same thing as if it showed up once ✨
Date and time use the same format as the NEWGROUPS command (see Section 7.3).
An empty list is a valid response too, and it just means there's no new news in the relevant groups right now 🦋
Clients SHOULD make all queries in Coordinated Universal Time (i.e., by using the "GMT" argument) when they can 🫶
7.4.3. Examples
Example where there are new articles:
[C] NEWNEWS news.*,sci.* 19990624 000000 GMT
[S] 230 list of new articles by message-id follows
[S] <i.am.a.new.article@example.com>
[S] <i.am.another.new.article@example.com>
[S] .Example where there are no new articles:
[C] NEWNEWS alt.* 19990624 000000 GMT
[S] 230 list of new articles by message-id follows
[S] .7.5. Time ⏰
Okay so remember how every article gets an arrival timestamp? 🕰️ Each newsgroup has a creation timestamp too, and the NEWNEWS and NEWGROUP commands use these to build their responses. 💖
Bestie, here's the trick to never having gaps in your article or group lists 🫶 Clients can use the DATE command like this:
- First session:
- Issue the DATE command and record the result.
- Issue the NEWNEWS command using a previously chosen timestamp.
- Subsequent sessions:
- Issue the DATE command and hold the result in temporary storage.
- Issue the NEWNEWS command using the timestamp saved from the previous session.
- Overwrite the saved timestamp with the one currently in temporary storage.
To cover minor errors, clients MAY want to adjust the timestamp back by two or three minutes before using it in NEWNEWS. 🧚
7.5.1. Examples
First session:
[C] DATE
[S] 111 20010203112233
[C] NEWNEWS local.chat 20001231 235959 GMT
[S] 230 list follows
[S] <article.1@local.service>
[S] <article.2@local.service>
[S] <article.3@local.service>
[S] .Second session (the client has subtracted 3 minutes from the timestamp returned previously):
[C] DATE
[S] 111 20010204003344
[C] NEWNEWS local.chat 20010203 111933 GMT
[S] 230 list follows
[S] <article.3@local.service>
[S] <article.4@local.service>
[S] <article.5@local.service>
[S] .Note how <article.3@local.service> arrived in the 3 minute gap, so it's listed in both responses. 👀✨
7.6. The LIST Commands 📋
The LIST family all return multi-line info that, in general, shouldn't change during the session 💅 A lot of it is about newsgroups, so the response has one line per newsgroup, and a wildmat MAY be provided to filter which groups you get back. 🌸
The full set of available keywords (including ones from extensions) is in the capability list under the capability label LIST. 🎀
7.6.1. LIST
7.6.1.1. Usage
Indicating capability: LIST
Syntax:
LIST [keyword [wildmat|argument]]Responses:
215 Information follows (multi-line)Parameters:
keyword Information requested [1]
argument Specific to keyword
wildmat Groups of interest[1] If no keyword is provided, it defaults to ACTIVE. 🫧
7.6.1.2. Description
The LIST command lets the server send blocks of info to the client 🎁 This info can be global or newsgroup-related. If it's newsgroup-related, you get it for all groups or only for the ones matching a wildmat. Each block has its own keyword, and the command returns whatever info that keyword points to. 💜
If the info is available, it comes back as a multi-line data block after the 215 response code. The format depends on the keyword. The info MAY be affected by the extra argument, but the format MUST NOT be. 🙈
If the info is newsgroup-based and you included the optional wildmat argument, the response is limited to only the groups (if any) whose names match the wildmat and that have the info available. 🔍
Note that an empty list is a valid response! For a newsgroup-based keyword, it just means no groups met the criteria. 🫠
If the keyword isn't recognised, or if you give an argument and the keyword doesn't expect one, a 501 response code MUST BE returned. If the keyword is recognised but the server doesn't keep that info, a 503 response code MUST BE returned. 🚫
The LIST command MUST NOT change the visible state of the server in any way. The behaviour of later commands MUST NOT be affected by whether LIST was issued. For example, it MUST NOT make groups available that otherwise wouldn't be. 🔒✨
7.6.1.3. Examples
Example of LIST with the ACTIVE keyword:
[C] LIST ACTIVE
[S] 215 list of newsgroups follows
[S] misc.test 3002322 3000234 y
[S] comp.risks 442001 441099 m
[S] alt.rfc-writers.recovery 4 1 y
[S] tx.natives.recovery 89 56 y
[S] tx.natives.recovery.d 11 9 n
[S] .Example of LIST with no keyword:
[C] LIST
[S] 215 list of newsgroups follows
[S] misc.test 3002322 3000234 y
[S] comp.risks 442001 441099 m
[S] alt.rfc-writers.recovery 4 1 y
[S] tx.natives.recovery 89 56 y
[S] tx.natives.recovery.d 11 9 n
[S] .The output is identical to the previous example. 🥰
Example of LIST on a newsgroup-based keyword with and without wildmat:
[C] LIST ACTIVE.TIMES
[S] 215 information follows
[S] misc.test 930445408 <creatme@isc.org>
[S] alt.rfc-writers.recovery 930562309 <m@example.com>
[S] tx.natives.recovery 930678923 <sob@academ.com>
[S] .
[C] LIST ACTIVE.TIMES tx.*
[S] 215 information follows
[S] tx.natives.recovery 930678923 <sob@academ.com>
[S] .Example of LIST returning an error where the keyword is recognised but the software doesn't maintain that info:
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
[S] .
[C] LIST XTRA.DATA
[S] 503 Data item not storedExample of LIST where the keyword isn't recognised:
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
[S] .
[C] LIST DISTRIB.PATS
[S] 501 Syntax Error7.6.2. Standard LIST Keywords 🌈
This spec defines the following LIST keywords:
+--------------+---------------+------------------------------------+
| Keyword | Definition | Status |
+--------------+---------------+------------------------------------+
| ACTIVE | Section 7.6.3 | Mandatory if the READER capability |
| | | is advertised |
| | | |
| ACTIVE.TIMES | Section 7.6.4 | Optional |
| | | |
| DISTRIB.PATS | Section 7.6.5 | Optional |
| | | |
| HEADERS | Section 8.6 | Mandatory if the HDR capability is |
| | | advertised |
| | | |
| NEWSGROUPS | Section 7.6.6 | Mandatory if the READER capability |
| | | is advertised |
| | | |
| OVERVIEW.FMT | Section 8.4 | Mandatory if the OVER capability |
| | | is advertised |
+--------------+---------------+------------------------------------+If a server supports one of these LIST keywords, it MUST have the meaning given in the relevant sub-section. 💯
7.6.3. LIST ACTIVE 🗂️
This keyword MUST be supported by servers that advertise the READER capability. 👑
LIST ACTIVE returns a list of valid newsgroups plus their associated info. If no wildmat is given, the server MUST include every group the client is permitted to select with the GROUP command (Section 6.1.1). Each line has four fields, separated from each other by one or more spaces:
- The name of the newsgroup.
- The reported high water mark for the group.
- The reported low water mark for the group.
- The current status of the group on this server.
The reported high and low water marks work the same as in the GROUP command (see Section 6.1.1), but heads up, they're in the opposite order from the 211 response to that command 🙃
The status field is typically one of these:
"y" Posting is permitted.
"n" Posting is not permitted.
"m" Postings will be forwarded to the newsgroup moderator.
The server SHOULD use these values when these meanings are needed and MUST NOT use them with any other meaning. Other status values may exist. Their definitions and when they're returned might be in an extension, or private to the server. A client SHOULD treat an unrecognised status as giving no information. 🤷♀️
The status of a newsgroup only shows how posts to it are normally processed. It isn't necessarily customised for the specific client. For example, if the current client is forbidden from posting, that applies equally to groups with status "y". Conversely, a client with special privileges (not defined by this specification) might be able to post to a group with status "n". 🦋
For example:
[C] LIST ACTIVE
[S] 215 list of newsgroups follows
[S] misc.test 3002322 3000234 y
[S] comp.risks 442001 441099 m
[S] alt.rfc-writers.recovery 4 1 y
[S] tx.natives.recovery 89 56 y
[S] tx.natives.recovery.d 11 9 n
[S] .Or, on an implementation that includes leading zeroes:
[C] LIST ACTIVE
[S] 215 list of newsgroups follows
[S] misc.test 0003002322 0003000234 y
[S] comp.risks 0000442001 0000441099 m
[S] alt.rfc-writers.recovery 0000000004 0000000001 y
[S] tx.natives.recovery 0000000089 0000000056 y
[S] tx.natives.recovery.d 0000000011 0000000009 n
[S] .The info is newsgroup-based, and a wildmat MAY be specified. If it is, the response is limited to only the groups (if any) whose names match the wildmat. For example:
[C] LIST ACTIVE *.recovery
[S] 215 list of newsgroups follows
[S] alt.rfc-writers.recovery 4 1 y
[S] tx.natives.recovery 89 56 y
[S] .7.6.4. LIST ACTIVE.TIMES ✨
This keyword is optional. 🫶
Some NNTP servers keep a little diary called the active.times list, which records who made each newsgroup and when 📖 Each line has three fields separated by one or more spaces. The first field is the newsgroup name. The second is the time the group was created on this server, measured in seconds since the start of January 1, 1970. The third is plain text describing the creator, and it's often a mailbox as defined in RFC 2822 [RFC2822]. Here's how it looks:
[C] LIST ACTIVE.TIMES
[S] 215 information follows
[S] misc.test 930445408 <creatme@isc.org>
[S] alt.rfc-writers.recovery 930562309 <m@example.com>
[S] tx.natives.recovery 930678923 <sob@academ.com>
[S] .The list MAY leave out newsgroups where the info isn't available, and it MAY include groups that aren't actually on the server. Like, it MAY skip every group created before the date and time of the oldest entry 🙈 The client MUST NOT assume the list is complete, or that it matches what the LIST ACTIVE command gives back (Section 7.6.3). The NEWGROUPS command (Section 7.3) may be a better way to get this info, and the results of the two commands SHOULD be consistent. The one exception: if the NEWGROUPS command is run with a date and time earlier than the oldest entry in the active.times list, its result may include extra groups.
The information is newsgroup based, and a wildmat MAY be specified. If one is, the response is limited to only the groups (if any) whose names match the wildmat. 💜
7.6.5. LIST DISTRIB.PATS 🌈
This keyword is optional. 🌸
The distrib.pats list is kept by some NNTP servers to help clients pick a value for the Distribution header of a news article being posted. Each line has three fields separated by a colon (":"). The first field is a weight, the second is a wildmat (which can just be a simple newsgroup name), and the third is the value to use for the Distribution header. Example time:
[C] LIST DISTRIB.PATS
[S] 215 information follows
[S] 10:local.*:local
[S] 5:*:world
[S] 20:local.here.*:thissite
[S] .The client MAY use this info to build a proper Distribution header from a newsgroup name. To do that, it should look at the lines whose second field matches the newsgroup name, pick the line with the highest weight (0 is the lowest), and then use the value of the third field to build the header. 🧚
The information is not newsgroup based, so an argument MUST NOT be specified. 🙅♀️
7.6.6. LIST NEWSGROUPS 💖
This keyword MUST be supported by servers advertising the READER capability. Non-negotiable, bestie 👑
The newsgroups list is maintained by NNTP servers to hold the name of each newsgroup available on the server, plus a short description of what the group is for. Each line has two fields separated by one or more space or TAB characters (the usual practice is a single TAB). The first field is the newsgroup name, and the second is a short description of the group. Like this:
[C] LIST NEWSGROUPS
[S] 215 information follows
[S] misc.test General Usenet testing
[S] alt.rfc-writers.recovery RFC Writers Recovery
[S] tx.natives.recovery Texas Natives Recovery
[S] .The list MAY leave out newsgroups where the info isn't available, and it MAY include groups that aren't available on the server. The client MUST NOT assume the list is complete or that it matches what LIST ACTIVE returns.
The description SHOULD be in UTF-8. Lowkey though, servers often grab this info from external sources, and those sources may have used other encodings (ones that use octets in the range 128 to 255 in some other way). In that case, the server MAY pass it on unchanged. So clients MUST be prepared to receive these descriptions 🍓
The information is newsgroup based, and a wildmat MAY be specified. If one is, the response is limited to only the groups (if any) whose names match the wildmat. ✨
8. Article Field Access Commands 🎀
This section lists commands that may be used to access specific article fields, which means headers of articles and metadata about articles. These commands usually pull from an "overview database", a database of headers taken from incoming articles, plus metadata worked out as each article arrives. Only certain fields are included in the database. 🦋
This section is based on the Overview/NOV database [ROBE1995], developed by Geoff Collyer. Shoutout to Geoff 🫶
8.1. Article Metadata
Article "metadata" is data about articles that does not live inside the article itself. Each metadata item has a name that MUST begin with a colon (and that MUST NOT contain a colon anywhere else in it). Just like header names, metadata item names are not case sensitive. 💅
When generating a metadata item, the server MUST compute it for itself and MUST NOT trust any related value provided in the article. (In particular, a Lines or Bytes header in the article MUST NOT be assumed to specify the correct number of lines or bytes in the article.) If the server has access to several non-identical copies of an article, the value returned MUST be correct for any copy of that article retrieved during the same session. 🔥
This specification defines two metadata items: ":bytes" and ":lines". Other metadata items may be defined by extensions. The names of metadata items defined by registered extensions MUST NOT begin with ":x-". To avoid a clash with a future registered extension, the names of metadata items defined by private extensions SHOULD begin with ":x-". 🌈
8.1.1. The :bytes Metadata Item
The :bytes metadata item for an article is a decimal integer. It SHOULD equal the number of octets in the entire article: headers, body, and the separating empty line. (A CRLF pair counts as two octets, and you exclude both the "." CRLF that ends the response and any "." added for "dot-stuffing" purposes.) 🧮
Note to client implementers: some existing servers return a value different from that. The commonest reasons are these:
- Counting a CRLF pair as one octet.
- Including the "." character used for dot-stuffing in the number.
- Including the terminating "." CRLF in the number.
- Using one copy of an article for counting the octets, but then returning another one that differs in some (permitted) manner.
Implementations should be prepared for this variation, and they MUST NOT rely on the value being accurate. Be prepared, not trusting 🙈
8.1.2. The :lines Metadata Item
The :lines metadata item for an article is a decimal integer. It MUST equal the number of lines in the article body (not counting the empty line that separates headers and body). Equivalently, it is two less than the number of CRLF pairs that the BODY command would return for that article. The extra two are the ones following the response code and the termination octet. 📏
8.2. Database Consistency
The information stored in the overview database may change over time. If the database records the content (or absence) of a given field, meaning a header or metadata item, for all articles, it is said to be "consistent" for that field. If it records the content of a header for some articles but not for others that still included that header, or if it records a metadata item for some articles but not for others the item applies to, it is said to be "inconsistent" for that field. 🧩
The LIST OVERVIEW.FMT command SHOULD list all the fields the database is consistent for at that moment. It MAY leave such fields out (for example, if it isn't known whether the database is consistent or inconsistent). It MUST NOT include fields the database is inconsistent for, or fields that aren't stored in the database at all. So if a header shows up in the LIST OVERVIEW.FMT output but not in the OVER output for a given article, that header does not appear in that article. Same goes for metadata items. 👀
These rules assume the fields being stored stay the same for long stretches, so the database stays consistent. When the set of fields to be stored changes, the database becomes inconsistent until either it gets rebuilt or the only articles left are the ones received since the change. That means the LIST OVERVIEW.FMT output needs changing twice. First, before any fields stop being stored, they MUST be removed from the output. Then, once the database is known to be consistent again, the new fields SHOULD be added to the output. Two-step glow-up 💖
If the HDR command uses the overview database instead of taking info straight from the articles, the same consistency issues apply. The LIST HEADERS command SHOULD take the same approach as LIST OVERVIEW.FMT for resolving them. 🌸
8.3. OVER
8.3.1. Usage
Indicating capability: OVER
Syntax
OVER message-id
OVER range
OVER
Responses
First form (message-id specified)
224 Overview information follows (multi-line)
430 No article with that message-id
Second form (range specified)
224 Overview information follows (multi-line)
412 No newsgroup selected
423 No articles in that range
Third form (current article number used)
224 Overview information follows (multi-line)
412 No newsgroup selected
420 Current article number is invalid
Parameters
range Number(s) of articles
message-id Message-id of article8.3.2. Description ✨
okay so OVER is literally the command that spills all the tea 🍵 on what's stored in the database for an article. You can ask for one article by message-id, or for an article (or a whole range of them) in the newsgroup you've currently selected 💅
The message-id argument points at one specific article. The range argument can be any of these:
- An article number.
- An article number followed by a dash to indicate all following.
- An article number followed by a dash followed by another article number.
If neither is specified, the current article number is used 🎀
Okay, this bit is important bestie 🫶 Support for the first (message-id) form is optional. If a server does support it, the OVER capability line MUST include the argument "MSGID". If it doesn't, the capability line MUST NOT include this argument, and the OVER command MUST return the generic response code 503 when this form is used.
If the info is available, it comes back as a multi-line data block after the 224 response code 📦 It has one line per article, sorted in numerical order of article number. (Fun fact: unless your argument is a range with a dash, you'll get exactly one line in the block 🦋) Each line is a bunch of fields separated by a TAB. A field can be empty (so you'd see two TABs right next to each other), and any trailing TABs are allowed to be dropped 💖
The first 8 fields MUST be the following, in order:
"0" or article number (see below)
Subject header content
From header content
Date header content
Message-ID header content
References header content
:bytes metadata item
:lines metadata itemNow, if the article was specified by message-id (the first form of the command), the article number MUST be replaced with zero. The one exception: if you have a newsgroup selected and the article is in that group, the server MAY use the article's number in that group 🌸 (Check the ARTICLE command (Section 6.2.1) and STAT examples (Section 6.2.4.3) for more deets.) In the other two forms of the command, the article number MUST be returned.
Any fields after those are the contents of the other headers and metadata held in the database 🧚
For the five mandatory headers, the content of each field MUST be based on the content of the header. That means the header name, plus the following colon and space, gets removed. If the article doesn't contain that header, or the content is empty, the field MUST be empty. For the two mandatory metadata items, the field MUST be just the value, with no other text 💜
For all subsequent fields that contain headers, the content MUST be the entire header line other than the trailing CRLF. For all subsequent fields that contain metadata, the field is the metadata name, a single space, and then the value ✨
For every field, the value gets processed in two steps. First, all CRLF pairs are removed (this undoes any folding and removes the terminating CRLF). Then each TAB gets swapped for a single space. If there's no such header in the article, no such metadata item, or no header or item stored in the database for that article, the matching field MUST be empty 🙈
Heads up bestie 🚨 After unfolding, the characters NUL, LF, and CR cannot occur in the header of an article offered by a conformant server. Still, servers SHOULD check for these characters and replace each one with a single space. For example, CR LF LF TAB becomes two spaces, since the CR and first LF get removed by the unfolding process. This encourages robustness when the data isn't conformant 🛡️ It's also possible that future versions of this specification could allow these characters to show up in articles, so stay tuned 👀
The server SHOULD NOT produce output for articles that no longer exist 🫥
Now the error codes, which are very important 😭 If the argument is a message-id and no such article exists, a 430 response MUST be returned. If the argument is a range or is omitted and the currently selected newsgroup is invalid, a 412 response MUST be returned. If the argument is a range and no articles in that number range exist in the currently selected newsgroup, a 423 response MUST be returned. This includes the case where the second number is less than the first one 💀 If the argument is omitted and the current article number is invalid, a 420 response MUST be returned.
8.3.3. Examples 🎀
In the first four examples, TAB has been swapped for a vertical bar, and some lines are folded so they're easier to read ✨
Here's a successful retrieval of overview info for an article, where the client doesn't name an article number:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER
[S] 224 Overview information follows
[S] 3000234|I am just a test article|"Demo User"
<nobody@example.com>|6 Oct 1998 04:38:40 -0500|
<45223423@example.com>|<45454@example.net>|1234|
17|Xref: news.example.com misc.test:3000363
[S] .Next, a successful retrieval of overview info for an article by message-id 🦋
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] OVER MSGID
[S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
[S] .
[C] OVER <45223423@example.com>
[S] 224 Overview information follows
[S] 0|I am just a test article|"Demo User"
<nobody@example.com>|6 Oct 1998 04:38:40 -0500|
<45223423@example.com>|<45454@example.net>|1234|
17|Xref: news.example.com misc.test:3000363
[S] .Notice the article number got replaced with "0" 👀
Here's the same commands on a system that doesn't do retrieval by message-id 🙅♀️
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] OVER
[S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
[S] .
[C] OVER <45223423@example.com>
[S] 503 Overview by message-id unsupportedA successful retrieval of overview info for a range of articles 📚
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER 3000234-3000240
[S] 224 Overview information follows
[S] 3000234|I am just a test article|"Demo User"
<nobody@example.com>|6 Oct 1998 04:38:40 -0500|
<45223423@example.com>|<45454@example.net>|1234|
17|Xref: news.example.com misc.test:3000363
[S] 3000235|Another test article|nobody@nowhere.to
(Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>||
4818|37||Distribution: fi
[S] 3000238|Re: I am just a test article|somebody@elsewhere.to|
7 Oct 1998 11:38:40 +1200|<kfwer3v@elsewhere.to>|
<45223423@to.to>|9234|51
[S] .Look at that second line missing its "References" and Xref headers 🙈 The first and last lines are missing their trailing fields too. Also, only the articles that still exist show up in the results ✨
An unsuccessful retrieval of overview info by number ❌
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER 300256
[S] 423 No such article in this groupAn invalid range 🤨
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER 3000444-3000222
[S] 423 Empty rangeAn unsuccessful retrieval by number, because no newsgroup was selected first 🙃
[Assumes currently selected newsgroup is invalid.]
[C] OVER
[S] 412 No newsgroup selectedAnd an attempt to retrieve info when the currently selected newsgroup is empty 🫙
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] OVER
[S] 420 No current article selected8.4. LIST OVERVIEW.FMT 🌈
8.4.1. Usage
Indicating capability: OVER
Syntax
LIST OVERVIEW.FMT
Responses
215 Information follows (multi-line)8.4.2. Description
See Section 7.6.1 for general requirements of the LIST command 📖
The LIST OVERVIEW.FMT command tells you what the fields in the database are, as long as they're consistent (as described above) 🧾 The info comes back as a multi-line data block after the 215 response code. There's one line per field, in the same order the OVER command returns them. The first 7 lines MUST (except for the case of letters) be exactly as follows:
Subject:
From:
Date:
Message-ID:
References:
:bytes
:linesFor compatibility with existing implementations, the last two lines MAY instead be:
Bytes:
Lines:Even though they refer to metadata, not headers 🤷♀️
All subsequent lines MUST consist of either a header name followed by ":full", or the name of a piece of metadata 💅
There are no leading or trailing spaces in the output ✨
Quick note: the 7 fixed lines describe the 2nd to 8th fields of the OVER output. The "full" suffix (which can be uppercase, lowercase, or a mix) is a little reminder that the matching fields include the header name 🎀
This command MAY generate different results if it's used more than once in a session 🦋
And if the OVER command isn't implemented, the meaning of the output from this command is not specified, but it must still meet the above syntactic requirements 🫶
8.4.3. Examples
Here's the LIST OVERVIEW.FMT output matching the example OVER output above, in the preferred format 🌸
[C] LIST OVERVIEW.FMT
[S] 215 Order of fields in overview database.
[S] Subject:
[S] From:
[S] Date:
[S] Message-ID:
[S] References:
[S] :bytes
[S] :lines
[S] Xref:full
[S] Distribution:full
[S] .And here's the same output in the alternative format 🍓
[C] LIST OVERVIEW.FMT
[S] 215 Order of fields in overview database.
[S] Subject:
[S] From:
[S] Date:
[S] Message-ID:
[S] References:
[S] Bytes:
[S] Lines:
[S] Xref:FULL
[S] Distribution:FULL
[S] .8.5. HDR 🧚
8.5.1. Usage
Indicating capability: HDR
Syntax
HDR field message-id
HDR field range
HDR field
Responses
First form (message-id specified)
225 Headers follow (multi-line)
430 No article with that message-id
Second form (range specified)
225 Headers follow (multi-line)
412 No newsgroup selected
423 No articles in that range
Third form (current article number used)
225 Headers follow (multi-line)
412 No newsgroup selected
420 Current article number is invalid
Parameters
field Name of field
range Number(s) of articles
message-id Message-id of article8.5.2. Description ✨
okay so the HDR command is basically your go-to for grabbing specific fields 🎀 from an article. You can point it at an article by message-id, or at an article or a whole range of them in the group you've selected 💖. It MAY grab the info straight from the articles, or it MAY use the overview database instead 🦋. For headers, an implementation MAY restrict the command to a specific list of headers, or MAY let you use any header at all 💅. It might also act differently depending on whether you gave it a message-id, a range, or nothing 🙈.
The required field argument is either a header name with the colon left off (like subject) or a metadata item name with the leading colon on (like :bytes). It's case insensitive 🌸.
The message-id argument picks out one specific article. The range argument can be any of these:
- An article number.
- An article number followed by a dash, which means "everything from here on" 🧚
- An article number, a dash, and then another article number.
If you don't give either one, the current article number gets used 🦋.
If the info is there, it comes back as a multi-line data block after the 225 response code, with one line for each article in the range that actually exists 🍓. (Heads up: unless your range includes a dash, you'll only get exactly one line back 🙈.) Each line is the article number, a space, and then the field contents. For a header, the header name, the colon, and the first space after the colon all get dropped 💅.
If you asked by message-id (the first form), the article number MUST be replaced with zero, but there's a twist 🔥. If you have a newsgroup selected and the article is in that group, the server MAY use the article's number in that group instead. (Check out the ARTICLE command (Section 6.2.1) and the STAT examples (Section 6.2.4.3) for more details 📚.) In the other two forms, the article number MUST be returned 💜.
Header contents get cleaned up like this: all CRLF pairs are removed, and then each TAB becomes a single space 🧹. (This is the exact same transformation the OVER command does (Section 8.3.2), and the same note about NUL, CR, and LF applies too ✨.)
Now, this is the part that's lowkey so important 👑. Headers and metadata can sound like the same thing, but they're not. Headers are always taken unchanged from the article, while metadata is always calculated 🧠. So asking for "Lines" gives you whatever the "Lines" header says, even if it's wrong, while asking for ":lines" gives you the real line count, no matter what any header claims 🙅♀️.
If the header isn't in the article, or it's there but empty, you still get a line for that article. The header part is just empty (the space after the article number MAY be kept or dropped) 🌈. If a header shows up more than once in an article, HDR only returns the first one 🥇. And if any article number in your range doesn't exist in the group, that number just doesn't get a line at all 🫥.
Errors are very real, bestie 😭. If the second argument is a message-id and no such article exists, a 430 response MUST be returned. If the second argument is a range or is left out and the selected newsgroup is invalid, a 412 response MUST be returned. If it's a range and no articles exist in that number range in the selected newsgroup (including when the second number is smaller than the first one), a 423 response MUST be returned. If the second argument is left out and the current article number is invalid, a 420 response MUST be returned 💀.
A server MAY only allow HDR for a limited set of fields, and it could act differently about this for the message-id form than for the others 🎭. If that's the case, it MUST respond with the generic 503 response when you ask for other fields, instead of giving back something wrong, like a successful empty response 🚫.
If HDR uses the overview database and the data is inconsistent for the field you asked for, the server MAY return whatever results it can, or it MAY respond with the generic 503 response 🌀. In that second case, the field MUST NOT appear in the output from LIST HEADERS 🙈.
8.5.3. Examples 🎀
Here's a successful retrieval of subject lines from a range of articles. (3000235 has no Subject header, and 3000236 is missing 🙈.)
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR Subject 3000234-3000238
[S] 225 Headers follow
[S] 3000234 I am just a test article
[S] 3000235
[S] 3000237 Re: I am just a test article
[S] 3000238 Ditto
[S] .Here's a successful retrieval of line counts from a range of articles 📏.
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR :lines 3000234-3000238
[S] 225 Headers follow
[S] 3000234 42
[S] 3000235 5
[S] 3000237 11
[S] 3000238 2378
[S] .Here's a successful retrieval of the subject line from an article by message-id 💌.
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR subject <i.am.a.test.article@example.com>
[S] 225 Header information follows
[S] 0 I am just a test article
[S] .Here's a successful retrieval of the subject line from the current article 🦋.
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR subject
[S] 225 Header information follows
[S] 3000234 I am just a test article
[S] .Here's an unsuccessful retrieval of a header by message-id, because the article isn't there 😵.
[C] HDR subject <i.am.not.there@example.com>
[S] 430 No Such Article FoundHere's an unsuccessful retrieval of headers by number, because no newsgroup got selected first 🙃.
[Assumes currently selected newsgroup is invalid.]
[C] HDR subject 300256-
[S] 412 No newsgroup selectedHere's an unsuccessful retrieval because the selected newsgroup is empty 🫙.
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] HDR subject 1-
[S] 423 No articles in that rangeHere's an unsuccessful retrieval because the server doesn't allow HDR for that header 🚫.
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR Content-Type 3000234-3000238
[S] 503 HDR not permitted on Content-Type8.6. LIST HEADERS 💜
8.6.1. Usage 🧾
Indicating capability: HDR
Syntax
LIST HEADERS [MSGID|RANGE]
Responses
215 Field list follows (multi-line)
Parameters
MSGID Requests list for access by message-id
RANGE Requests list for access by range8.6.2. Description 🌟
Quick reminder: the general rules for the LIST command live in Section 7.6.1 📖.
LIST HEADERS gives you a list of the fields you're allowed to fetch with HDR 🧃. You get a multi-line data block after the 215 response code, with one line per field name. Headers come without the trailing colon, and metadata items keep their leading colon 🎀. If the implementation lets you grab any header at all, it MUST NOT list individual header names. Instead, it MUST include the special entry : (just a single colon on its own) ✨. It MUST still explicitly list any metadata items that are available 💅. The order doesn't matter, and the server doesn't even have to give you the same order every time 🌀. The list MAY be empty, although then there's not much point in having HDR at all 🙃.
If you also support OVER, you SHOULD at least allow all the headers and metadata items that show up in the LIST OVERVIEW.FMT output 🫶.
Now for the tricky case. If the server treats the message-id form of HDR differently from the range and current-article forms, here's how LIST HEADERS has to behave 🦋:
- If MSGID is specified, the results MUST be the ones available for the first form of HDR.
- If RANGE is specified, the results MUST be the ones available for the second and third forms of HDR.
- If no argument is specified, the results MUST be the ones available in all forms of HDR. In other words, it MUST only list the items that appear in both of the previous cases 👑.
If the server doesn't treat the forms differently, then it MUST ignore any argument and always give the same results (though not necessarily in the same order) 🙌.
If HDR isn't implemented, the meaning of this command's output isn't specified, but it still has to meet the syntax rules above 🤷♀️.
8.6.3. Examples 🧚
Here's an implementation that only gives access to a few headers 🌸.
[C] LIST HEADERS
[S] 215 headers supported:
[S] Subject
[S] Message-ID
[S] Xref
[S] .Here's an implementation that gives access to the same fields as the first example in Section 8.4.3 🍓.
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] OVER
[S] HDR
[S] LIST ACTIVE NEWSGROUPS HEADERS OVERVIEW.FMT
[S] .
[C] LIST HEADERS
[S] 215 headers and metadata items supported:
[S] Date
[S] Distribution
[S] From
[S] Message-ID
[S] References
[S] Subject
[S] Xref
[S] :bytes
[S] :lines
[S] .Here's an implementation that gives access to all headers 🌈.
[C] LIST HEADERS
[S] 215 metadata items supported:
[S] :
[S] :lines
[S] :bytes
[S] :x-article-number
[S] .Here's an implementation that treats the message-id form of HDR differently from the other two forms 🔮.
[C] LIST HEADERS RANGE
[S] 215 metadata items supported:
[S] :
[S] :lines
[S] :bytes
[S] .
[C] LIST HEADERS MSGID
[S] 215 headers and metadata items supported:
[S] Date
[S] Distribution
[S] From
[S] Message-ID
[S] References
[S] Subject
[S] :lines
[S] :bytes
[S] :x-article-number
[S] .
[C] LIST HEADERS
[S] 215 headers and metadata items supported:
[S] Date
[S] Distribution
[S] From
[S] Message-ID
[S] References
[S] Subject
[S] :lines
[S] :bytes
[S] .Notice that :x-article-number doesn't show up in that last set of output 👀.
9. Augmented BNF Syntax for NNTP ✨
9.1. Introduction 💖
okay so each of these next sections is the official rulebook for one major piece of NNTP. this syntax builds on and sharpens what we said earlier, so if anything ever seems to clash, THIS is the one that wins 💅. also, ABNF [RFC4234] strings are case insensitive, and the bits that get used all over the place live in their own little section at the end 🎀
Between them, the non-terminals <command-line>, <command-datastream>, <command-continuation>, and <response> cover the text that flows between client and server. there's a consistent naming scheme for the non-terminals about each command, and whoever writes specs for registered extensions SHOULD follow it too ✨
For each command, the flow goes like this 🦋:
- the client sends an instance of
<command-line>, and the syntax for theEXAMPLEcommand is<example-command>. - if the client is one that immediately streams data, it sends an instance of
<command-datastream>, and the syntax for theEXAMPLEcommand is<example-datastream>. - the server sends an instance of
<response>.- the initial response line doesn't depend on the command that made it. if the 000 response has arguments, the syntax of the initial line is
<response-000-content>. - if the response is multi-line, the initial line is followed by a
<multi-line-data-block>. once the "dot-stuffing" is removed, the contents of that block follow the syntax<example-000-ml-content>(for the 000 response to theEXAMPLEcommand), which is an instance of<multi-line-response-content>.
- the initial response line doesn't depend on the command that made it. if the 000 response has arguments, the syntax of the initial line is
- while the latest response says more data is needed (usually a 3xx response) 🌸:
- the client sends an instance of
<command-continuation>. the syntax for theEXAMPLEcontinuation after a 333 response is<example-333-continuation>. - the server sends another instance of
<response>, same as before.
- the client sends an instance of
(there are no commands in this spec that immediately stream data, but that non-terminal is defined anyway, for the convenience of extensions 🧚)
9.2. Commands 🎀
this syntax defines <command-line>, which is what the client sends to the server (see section 3.1 for limits on lengths) 💅
command-line = command EOL
command = X-command
X-command = keyword *(WS token)
command =/ article-command /
body-command /
capabilities-command /
date-command /
group-command /
hdr-command /
head-command /
help-command /
ihave-command /
last-command /
list-command /
listgroup-command /
mode-reader-command /
newgroups-command /
newnews-command /
next-command /
over-command /
post-command /
quit-command /
stat-command
article-command = "ARTICLE" [WS article-ref]
body-command = "BODY" [WS article-ref]
capabilities-command = "CAPABILITIES" [WS keyword]
date-command = "DATE"
group-command = "GROUP" [WS newsgroup-name]
hdr-command = "HDR" WS header-meta-name [WS range-ref]
head-command = "HEAD" [WS article-ref]
help-command = "HELP"
ihave-command = "IHAVE" WS message-id
last-command = "LAST"
list-command = "LIST" [WS list-arguments]
listgroup-command = "LISTGROUP" [WS newsgroup-name [WS range]]
mode-reader-command = "MODE" WS "READER"
newgroups-command = "NEWGROUPS" WS date-time
newnews-command = "NEWNEWS" WS wildmat WS date-time
next-command = "NEXT"
over-command = "OVER" [WS range-ref]
post-command = "POST"
quit-command = "QUIT"
stat-command = "STAT" [WS article-ref]
article-ref = article-number / message-id
date = date2y / date4y
date4y = 4DIGIT 2DIGIT 2DIGIT
date2y = 2DIGIT 2DIGIT 2DIGIT
date-time = date WS time [WS "GMT"]
header-meta-name = header-name / metadata-name
list-arguments = keyword [WS token]
metadata-name = ":" 1*A-NOTCOLON
range = article-number ["-" [article-number]]
range-ref = range / message-id
time = 2DIGIT 2DIGIT 2DIGIT9.3. Command Continuation 🌈
this bit defines the extra stuff the client sends for multi-stage commands and the ones that stream data 🚀
command-datastream = UNDEFINED
; not used, provided as a hook for extensions
command-continuation = ihave-335-continuation /
post-340-continuation
ihave-335-continuation = encoded-article
post-340-continuation = encoded-article
encoded-article = multi-line-data-block
; after undoing the "dot-stuffing", this MUST match <article>9.4. Responses 💜
9.4.1. Generic Responses 🦋
this syntax defines <response>, the generic form of responses. basically it's what the server sends back to the client after a <command> or a <command-continuation> 💅
response = simple-response / multi-line-response
simple-response = initial-response-line
multi-line-response = initial-response-line multi-line-data-block
initial-response-line =
initial-response-content [SP trailing-comment] CRLF
initial-response-content = X-initial-response-content
X-initial-response-content = 3DIGIT *(SP response-argument)
response-argument = 1*A-CHAR
trailing-comment = *U-CHAR9.4.2. Initial Response Line Contents ✨
this one defines the specific initial response lines for each command in this spec (see section 3.1 for limits on lengths). only the response codes that come with arguments are listed here 🎀
initial-response-content =/ response-111-content /
response-211-content /
response-220-content /
response-221-content /
response-222-content /
response-223-content /
response-401-content
response-111-content = "111" SP date4y time
response-211-content = "211" 3(SP article-number) SP newsgroup-name
response-220-content = "220" SP article-number SP message-id
response-221-content = "221" SP article-number SP message-id
response-222-content = "222" SP article-number SP message-id
response-223-content = "223" SP article-number SP message-id
response-401-content = "401" SP capability-label9.4.3. Multi-line Response Contents 🌸
this defines what goes inside each multi-line response. more precisely, it's the part of the multi-line data block after any "dot-stuffing" has been undone. the number in each non-terminal's name tells you which response code that data comes after 🧚
multi-line-response-content = article-220-ml-content /
body-222-ml-content /
capabilities-101-ml-content /
hdr-225-ml-content /
head-221-ml-content /
help-100-ml-content /
list-215-ml-content /
listgroup-211-ml-content /
newgroups-231-ml-content /
newnews-230-ml-content /
over-224-ml-content
article-220-ml-content = article
body-222-ml-content = body
capabilities-101-ml-content = version-line CRLF
*(capability-line CRLF)
hdr-225-ml-content = *(article-number SP hdr-content CRLF)
head-221-ml-content = 1*header
help-100-ml-content = *(*U-CHAR CRLF)
list-215-ml-content = list-content
listgroup-211-ml-content = *(article-number CRLF)
newgroups-231-ml-content = active-groups-list
newnews-230-ml-content = *(message-id CRLF)
over-224-ml-content = *(article-number over-content CRLF)
active-groups-list = *(newsgroup-name SPA article-number
SPA article-number SPA newsgroup-status CRLF)
hdr-content = *S-NONTAB
hdr-n-content = [(header-name ":" / metadata-name) SP hdr-content]
list-content = body
newsgroup-status = %x79 / %x6E / %x6D / private-status
over-content = 1*6(TAB hdr-content) /
7(TAB hdr-content) *(TAB hdr-n-content)
private-status = token ; except the values in newsgroup-status9.5. Capability Lines 🫶
this syntax defines the generic form of a capability line in the capabilities list (see Section 3.3.1) 💖
capability-line = capability-entry
capability-entry = X-capability-entry
X-capability-entry = capability-label *(WS capability-argument)
capability-label = keyword
capability-argument = tokenthis one defines the specific capability entries for the capabilities in this spec 🔥
capability-entry =/
hdr-capability /
ihave-capability /
implementation-capability /
list-capability /
mode-reader-capability /
newnews-capability /
over-capability /
post-capability /
reader-capability
hdr-capability = "HDR"
ihave-capability = "IHAVE"
implementation-capability = "IMPLEMENTATION" *(WS token)
list-capability = "LIST" 1*(WS keyword)
mode-reader-capability = "MODE-READER"
newnews-capability = "NEWNEWS"
over-capability = "OVER" [WS "MSGID"]
post-capability = "POST"
reader-capability = "READER"
version-line = "VERSION" 1*(WS version-number)
version-number = nzDIGIT *5DIGIT9.6. LIST Variants 👑
this section gets specific about the keywords for the LIST command and the syntax of the response contents that go with each one 🍓
; active
list-arguments =/ "ACTIVE" [WS wildmat]
list-content =/ list-active-content
list-active-content = active-groups-list
; active.times
list-arguments =/ "ACTIVE.TIMES" [WS wildmat]
list-content =/ list-active-times-content
list-active-times-content =
*(newsgroup-name SPA 1*DIGIT SPA newsgroup-creator CRLF)
newsgroup-creator = U-TEXT
; distrib.pats
list-arguments =/ "DISTRIB.PATS"
list-content =/ list-distrib-pats-content
list-distrib-pats-content =
*(1*DIGIT ":" wildmat ":" distribution CRLF)
distribution = token
; headers
list-arguments =/ "HEADERS" [WS ("MSGID" / "RANGE")]
list-content =/ list-headers-content
list-headers-content = *(header-meta-name CRLF) /
*((metadata-name / ":") CRLF)
; newsgroups
list-arguments =/ "NEWSGROUPS" [WS wildmat]
list-content =/ list-newsgroups-content
list-newsgroups-content =
*(newsgroup-name WS newsgroup-description CRLF)
newsgroup-description = S-TEXT
; overview.fmt
list-arguments =/ "OVERVIEW.FMT"
list-content =/ list-overview-fmt-content
list-overview-fmt-content = "Subject:" CRLF
"From:" CRLF
"Date:" CRLF
"Message-ID:" CRLF
"References:" CRLF
( ":bytes" CRLF ":lines" / "Bytes:" CRLF "Lines:") CRLF
*((header-name ":full" / metadata-name) CRLF)9.7. Articles 🦋
this syntax defines <article>, which is the format of an article as described in Section 3.6 ✨
article = 1*header CRLF body
header = header-name ":" [CRLF] SP header-content CRLF
header-content = *(S-CHAR / [CRLF] WS)
body = *(*B-CHAR CRLF)9.8. General Non-terminals ✨
okay bestie, this is the grab bag 🧺 these little grammar bits pop up all over the place, so the spec gathers them in one spot for convenience. a few of them aren't actually used in this spec, but they're here so extension authors have them ready 🎀
multi-line-data-block = content-lines termination
content-lines = *([content-text] CRLF)
content-text = (".." / B-NONDOT) *B-CHAR
termination = "." CRLF
article-number = 1*16DIGIT
header-name = 1*A-NOTCOLON
keyword = ALPHA 2*(ALPHA / DIGIT / "." / "-")
message-id = "<" 1*248A-NOTGT ">"
newsgroup-name = 1*wildmat-exact
token = 1*P-CHAR
wildmat = wildmat-pattern *("," ["!"] wildmat-pattern)
wildmat-pattern = 1*wildmat-item
wildmat-item = wildmat-exact / wildmat-wild
wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E /
UTF8-non-ascii ; exclude ! * , ? [ \ ]
wildmat-wild = "*" / "?"
base64 = *(4base64-char) [base64-terminal]
base64-char = UPPER / LOWER / DIGIT / "+" / "/"
base64-terminal = 2base64-char "==" / 3base64-char "="
; Assorted special character sets
; A- means based on US-ASCII, excluding controls and SP
; P- means based on UTF-8, excluding controls and SP
; U- means based on UTF-8, excluding NUL CR and LF
; B- means based on bytes, excluding NUL CR and LF
A-CHAR = %x21-7E
A-NOTCOLON = %x21-39 / %x3B-7E ; exclude ":"
A-NOTGT = %x21-3D / %x3F-7E ; exclude ">"
P-CHAR = A-CHAR / UTF8-non-ascii
U-CHAR = CTRL / TAB / SP / A-CHAR / UTF8-non-ascii
U-NONTAB = CTRL / SP / A-CHAR / UTF8-non-ascii
U-TEXT = P-CHAR *U-CHAR
B-CHAR = CTRL / TAB / SP / %x21-FF
B-NONDOT = CTRL / TAB / SP / %x21-2D / %x2F-FF ; exclude "."
ALPHA = UPPER / LOWER ; use only when case-insensitive
CR = %x0D
CRLF = CR LF
CTRL = %x01-08 / %x0B-0C / %x0E-1F
DIGIT = %x30-39
nzDIGIT = %x31-39
EOL = *(SP / TAB) CRLF
LF = %x0A
LOWER = %x61-7A
SP = %x20
SPA = 1*SP
TAB = %x09
UPPER = %x41-5A
UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4
UTF8-2 = %xC2-DF UTF8-tail
UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail /
%xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail
UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail /
%xF4 %x80-8F 2UTF8-tail
UTF8-tail = %x80-BF
WS = 1*(SP / TAB)these next non-terminals need some extra care 🥺 they're the spots where material SHOULD be restricted to UTF-8, BUT implementations MUST be able to cope with other character encodings. so there are two sets of definitions for them, and here's the first one. implementations MUST accept any content that meets this syntax:
S-CHAR = %x21-FF
S-NONTAB = CTRL / SP / S-CHAR
S-TEXT = (CTRL / S-CHAR) *B-CHARand they MAY pass that content on totally unaltered 🫶
when you're generating brand new content, or re-encoding what's already there, implementations SHOULD conform to this one instead:
S-CHAR = P-CHAR
S-NONTAB = U-NONTAB
S-TEXT = U-TEXT9.9. Extensions and Validation 🧩
okay so if you're registering an extension, your spec MUST include formal syntax that defines additional forms for these non-terminals:
command- for each new command other than a variant of the LIST command, the syntax of each command MUST be compatible with the definition of
<X-command>;
- for each new command other than a variant of the LIST command, the syntax of each command MUST be compatible with the definition of
command-datastream- for each new command that immediately streams data;
command-continuation- for each new command that sends further material after the initial command line, the syntax of each continuation MUST be exactly what is sent to the server, including any escape mechanisms such as "dot-stuffing";
initial-response-content- for each new response code that has arguments, the syntax of each response MUST be compatible with the definition of
<X-initial-response-content>;
- for each new response code that has arguments, the syntax of each response MUST be compatible with the definition of
multi-line-response-content- for each new response code that has a multi-line response, the syntax MUST show the response after the lines containing the response code and the terminating octet have been removed and any "dot-stuffing" undone;
capability-entry- for each new capability label, the syntax of each entry MUST be compatible with the definition of
<X-capability-entry>;
- for each new capability label, the syntax of each entry MUST be compatible with the definition of
list-arguments- for each new variant of the LIST command, the syntax of each entry MUST be compatible with the definition of
<X-command>;
- for each new variant of the LIST command, the syntax of each entry MUST be compatible with the definition of
list-content- for each new variant of the LIST command, the syntax MUST show the response after the lines containing the 215 response code and the terminating octet have been removed and any "dot-stuffing" undone.
the =/ notation of ABNF [RFC4234] and the naming conventions from Section 9.1 SHOULD be used for this 💅
when somebody validates the syntax in this specification, or syntax based on it, it should be noted that:
- the non-terminals
<command-line>,<command-datastream>,<command-continuation>,<response>, and<multi-line-response-content>describe basic concepts of the protocol and are not referred to by any other rule; - the non-terminal
<base64>is provided for the convenience of extension authors and is not referred to by any rule in this specification; - for the reasons given above, the non-terminals
<S-CHAR>,<S-NONTAB>, and<S-TEXT>each have two definitions; and - the non-terminal
<UNDEFINED>is deliberately not defined.
10. Internationalisation Considerations 🌍
10.1. Introduction and Historical Situation
okay history time, and it's kinda messy 🙈 [RFC977] was written back when internationalisation wasn't seen as a big deal. so it assumed everything would be ASCII over a 7-bit transport layer, even though basically every implementation out there is actually 8-bit clean in practice.
then Usenet and NNTP spread all over the world, and without standards for language and character sets, countries, newsgroup hierarchies, and individuals each came up with their own fixes 🌏 some picked a default 8-bit character set for their region (like ISO/IEC 8859-1 in Western Europe or KOI-8 in Russia), some used ASCII (US-ASCII or national variants) in headers with local 16-bit character sets in bodies, and others went with a combo of MIME [RFC2045] and UTF-8. as MIME gets more popular in email, you're seeing more NNTP articles with MIME headers that say what character set the body uses, but it's still far from universal.
the result is a lot of confusion, and that does not help interoperability 😭
one thing that's been pretty much accepted is that articles can contain octets with the top bit set, and NNTP is only expected to work over 8-bit clean transport paths.
10.2. This Specification
this spec's whole job is to clear up that confusion and make interoperability better as far as possible 🦋 but it also has to accept that the current situation exists and not break existing implementations and setups for no good reason, even if they're less than optimal. so the current practice described above got taken into account when writing this.
this specification extends NNTP from US-ASCII [ANSI1986] to UTF-8 [RFC3629]. except for the two areas discussed below, UTF-8 (which is a superset of US-ASCII) is mandatory, and implementations MUST NOT use any other encoding 🚫
first up, using MIME for article headers and bodies is strongly recommended. but with existing practices all over the place, forcing one particular encoding and tagging standard would be premature right now. so this spec lets arbitrary 8-bit data show up in articles, as long as these requirements and recommendations are followed:
- The names of headers (e.g., "From" or "Subject") MUST be in US-ASCII.
- Header values SHOULD use US-ASCII or an encoding based on it, such as RFC 2047 [RFC2047], until another approach has been standardised. at present, 8-bit encodings (including UTF-8) SHOULD NOT be used because they're likely to cause interoperability problems 😬
- The character set of article bodies SHOULD be indicated in the article headers, and this SHOULD be done in accordance with MIME.
- Where an article is obtained from an external source, an implementation MAY pass it on and derive data from it (such as the response to the HDR command), even though the article or the data does not meet the above requirements. implementations MUST transfer such articles and data correctly and unchanged; they MUST NOT attempt to convert or re-encode the article or derived data. (nevertheless, a client or server MAY elect not to post or forward the article if, after further examination of the article, it deems it inappropriate to do so.)
this requirement affects the ARTICLE (Section 6.2.1), BODY (Section 6.2.3), HDR (Section 8.5), HEAD (Section 6.2.2), IHAVE (Section 6.3.2), OVER (Section 8.3), and POST (Section 6.3.1) commands 🌸
second, these requirements apply to the newsgroups list returned by the LIST NEWSGROUPS command (Section 7.6.6):
- Although this specification allows UTF-8 for newsgroup names, they SHOULD be restricted to US-ASCII until a successor to RFC 1036 [RFC1036] standardises another approach. 8-bit encodings SHOULD NOT be used because they're likely to cause interoperability problems.
- The newsgroup description SHOULD be in US-ASCII or UTF-8 unless and until a successor to RFC 1036 standardises other encoding arrangements. 8-bit encodings other than UTF-8 SHOULD NOT be used because they're likely to cause interoperability problems.
- Implementations that obtain this data from an external source MUST handle it correctly even if it does not meet the above requirements. Implementations (in particular, clients) MUST handle such data correctly. 🫶
10.3. Outstanding Issues ✨
okay so, NNTP is mainly for shipping articles that follow RFC 1036 (Netnews articles) 📰, but it also carries other formats (see Appendix A) 💅. So the internationalisation stuff for article formats really belongs in the relevant specs. For Netnews articles that's any successor to RFC 1036, and for email messages it's RFC 2822 [RFC2822] 💌.
Obviously any article sent over NNTP still has to follow this spec too 🫶.
Restricting newsgroup names to UTF-8 is not the whole story, ngl 🙈. When somebody creates a new newsgroup name, or a user is asked to type one in, some kind of canonicalisation scheme is going to be needed 🔍. This spec does not try to define that canonicalization, so more work is needed here, together with the article format specs 📝. Until those specs get published, implementations SHOULD match newsgroup names octet by octet 🔢. The expectation is that any approved scheme gets applied "at the edges", which means octet-by-octet comparison keeps working for most, if not all, uses of newsgroup names in NNTP 🌸.
In the meantime, anyone experimenting with UTF-8 newsgroup names gets a strong warning 🚨: a future specification may require those names to be canonicalized when used with NNTP, and that might not be compatible with what you've been testing 😭.
Since NNTP is mostly used with Netnews, and newsgroup descriptions are normally distributed through specially formatted articles, it is recommended that the internationalisation issues for those descriptions get addressed in any successor to RFC 1036 🌈.
11. IANA Considerations 🦋
This specification requires IANA to keep a registry of capability labels 📋. The initial contents of that registry are specified in Section 3.3.4. As described in Section 3.3.3, labels that begin with X are reserved for private use, while every other name is expected to be tied to a specification in an RFC on the standards track or one that defines an IESG-approved experimental protocol 🧚.
Different entries in the registry MUST use different capability labels 🏷️.
Different entries in the registry MUST NOT use the same command name 🙅♀️. For this purpose, variants told apart by a second or subsequent keyword (for example, "LIST HEADERS" and "LIST OVERVIEW.FMT") count as different commands 💡. If two extensions need to use the same command, a single harmonised specification MUST be registered 🤝.
12. Security Considerations 💀
This section is serious business, bestie 😭🔥. It's meant to inform application developers, information providers, and users about the security limitations of NNTP as described by this document. It does NOT contain definitive solutions to the problems revealed 🙈, but it does offer some suggestions for reducing security risks 🛡️.
12.1. Personal and Proprietary Information 🕵️♀️
NNTP was built to distribute network news articles, so it will forward whatever information is stored in those articles 📬. What that information looks like is outside the scope of this document, but it's very likely that some personal and/or proprietary information shows up in some of those articles 👀. It is super important that designers and implementers give users informative warnings, so that personal and/or proprietary information in material added automatically to articles (for example, in headers) doesn't get disclosed by accident 🚨. Also, effective and easily understood mechanisms to manage the distribution of news articles SHOULD be provided to NNTP Server administrators, so they can confidently report the likely spread of any particular set of news articles 📊.
12.2. Abuse of Server Log Information 📜
A server is in a position to save session data about a user's requests, and that data could reveal their reading patterns or subjects of interest 👁️. This information is clearly confidential, and in some countries the law can restrict how it's handled ⚖️. People using this protocol to provide data are responsible for making sure that such material is not distributed without the permission of any individuals who could be identified from the published results 🙏.
12.3. Weak Authentication and Access Control 🔐
The basic NNTP specification has no user-based or token-based authentication 🙃. Access is normally controlled by server configuration files, which specify access using domain names or IP addresses 🗂️. However, this specification does allow extensions to NNTP for these purposes, and one such extension is [NNTP-AUTH] ✨. Including such mechanisms is optional, but doing so is strongly encouraged 💜.
Other mechanisms are also available 🌸. For example, a proxy server could be set up that requires authentication before it connects you through the proxy to the NNTP server 🚪.
12.4. DNS Spoofing 🎭
Many existing NNTP implementations authorize incoming connections by checking the connection's IP address against the IP addresses obtained from DNS lookups of lists of domain names in local configuration files 🔎. Servers that use this kind of authentication, and clients that find a server by doing a DNS lookup of the server name, rely very heavily on the Domain Name Service 🥺. That makes them generally prone to security attacks based on the deliberate misassociation of IP addresses and DNS names 😱. Clients and servers need to be cautious about assuming that an IP number/DNS name association is still valid 🧐.
In particular, NNTP clients and servers SHOULD rely on their name resolver to confirm an IP number/DNS name association, rather than caching the result of previous host name lookups 🔁. Many platforms can already cache host name lookups locally when appropriate, and they SHOULD be configured to do so ⚙️. It is only proper to cache these lookups, though, when the TTL (Time To Live) information reported by the name server makes it likely the cached information will stay useful ⏳.
If NNTP clients or servers cache host name lookup results to get a performance boost, they MUST observe the TTL information reported by DNS ⏰. If they don't follow this rule, they could be spoofed when a previously accessed server's IP address changes 💀. Network renumbering is expected to become more common, so the chance of this kind of attack will go up 📈. Following this requirement cuts down on that potential security vulnerability 🛡️.
This requirement also improves load-balancing for clients of replicated servers using the same DNS name, and it lowers the chance that a user has trouble reaching sites that use that strategy 💖.
12.5. UTF-8 Issues 🌈
UTF-8 [RFC3629] allows only certain sequences of octets and labels others as either malformed or "illegal" 🙅. The Unicode standard identifies a number of security issues related to illegal sequences and forbids conforming implementations from generating them 🚫.
Implementations of this specification MUST NOT generate malformed or illegal sequences, and they SHOULD detect them and take some appropriate action 🚨. That could include the following:
- Generating a 501 response code.
- Replacing such sequences by the sequence
%xEF.BF.BD, which encodes the "replacement character" U+FFFD. - Closing the connection.
- Replacing such sequences by a "guessed" valid sequence (based on properties of the UTF-8 encoding).
In the last case, the implementation MUST ensure that no replacement can be used to bypass validity or security checks 🧠. For example, the illegal sequence %xC0.A0 is an over-long encoding for space (%x20) 🙈. If it gets replaced by the correct encoding in a command line, that has to happen before the command line is parsed into individual arguments 🧩. If the replacement came after parsing, it would be possible to generate an argument with an embedded space, which is forbidden 😤. The "replacement character" doesn't have this problem, since it's permitted wherever non-US-ASCII characters are 💅. Implementations SHOULD use one of the first two solutions where the general structure of the NNTP stream remains intact, and SHOULD close the connection if it is no longer possible to parse it sensibly 🎀.
12.6. Caching of Capability Lists 📋
The CAPABILITIES command gives you a capability list, which is information about the server's current capabilities 🧾. Whenever there's a relevant change to the server state, the results of this command are required to change to match 🔄.
Most of the time, the capabilities list in a given server state won't change from session to session 🙌. For example, a given extension will be installed permanently on a server 🏠. So some clients may want to remember which extensions a server supports, to skip the delay of an extra command and response 🏃♀️💨, especially if they open multiple connections in the same session 🔗.
However, information about extensions related to security and privacy MUST NOT be cached, since that could allow a variety of attacks 🚨😱.
For example, consider a server that permits cleartext passwords on links that are encrypted but not otherwise 🔑:
[Initial connection set-up completed.]
[S] 200 NNTP Service Ready, posting permitted
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] NEWNEWS
[S] POST
[S] XENCRYPT
[S] LIST ACTIVE NEWSGROUPS
[S] .
[C] XENCRYPT
[Client and server negotiate encryption on the link]
[S] 283 Encrypted link established
[C] CAPABILITIES
[S] 101 Capability list:
[S] VERSION 2
[S] READER
[S] NEWNEWS
[S] POST
[S] XSECRET
[S] LIST ACTIVE NEWSGROUPS
[S] .
[C] XSECRET fred flintstone
[S] 290 Password for fred acceptedIf the client caches the last capabilities list, then next session it will try to use XSECRET on an unencrypted link 😬:
[Initial connection set-up completed.]
[S] 200 NNTP Service Ready, posting permitted
[C] XSECRET fred flintstone
[S] 483 Only permitted on secure linksThis exposes the password to any eavesdropper 👂💀. The main cause is passing a secret before checking the security of the link, but caching capability lists can make the risk worse 😭.
Any security extension should include requirements to check the security state of the link in a way that's right for that extension 🔒.
Caching should normally only be considered for anonymous clients that don't use any security or privacy extensions, and for which the time required for an additional command and response is a noticeable issue ⭐.
13. Acknowledgements 🙏✨
okay so this doc is the result of SO much effort from the present and past members of the NNTP Working Group, chaired by Russ Allbery and Ned Freed 🫶 it literally could not exist without them, periodt 💖
The author acknowledges the original authors of NNTP as documented in [RFC977]: Brian Kantor and Phil Lapsey 🌸
The author gratefully acknowledges the following:
- The work of the NNTP committee chaired by Eliot Lear. The organization of this document was influenced by the last available version from this working group. Huge thanks to Eliot for generously sharing the original machine-readable sources for that document 🧚
- The work of the DRUMS working group, specifically RFC 1869 [RFC1869], which drove the original thinking that led to the CAPABILITIES command and the extensions mechanism detailed in this document 🦋
- The authors of RFC 2616 [RFC2616] for providing specific and relevant examples of security issues that should be considered for HTTP. Since a lot of the same considerations exist for NNTP, the relevant examples have been included here with some minor rewrites 💅
The comments and additional info provided by these individuals while preparing one or more of the progenitors of this document are so appreciated:
Russ Allbery <rra@stanford.edu>
Wayne Davison <davison@armory.com>
Chris Lewis <clewis@bnr.ca>
Tom Limoncelli <tal@mars.superlink.net>
Eric Schnoebelen <eric@egsner.cirr.com>
Rich Salz <rsalz@osf.org>This work was motivated by the work of various news reader authors and news server authors, the legends listed below 👑
- Rick Adams: original author of the NNTP extensions to the RN news reader, and last maintainer of Bnews.
- Stan Barber: original author of the NNTP extensions to the news readers that are part of Bnews.
- Geoff Collyer: original author of the OVERVIEW database proposal, and one of the original authors of CNEWS.
- Dan Curry: original author of the xvnews news reader.
- Wayne Davison: author of the first threading extensions to the RN news reader (commonly called TRN).
- Geoff Huston: original author of ANU NEWS.
- Phil Lapsey: original author of the UNIX reference implementation for NNTP.
- Iain Lea: original maintainer of the TIN news reader.
- Chris Lewis: first known implementer of the AUTHINFO GENERIC extension.
- Rich Salz: original author of INN.
- Henry Spencer: one of the original authors of CNEWS.
- Kim Storm: original author of the NN news reader.
Other people who contributed to this document include:
Matthias Andree
Greg Andruk
Daniel Barclay
Maurizio Codogno
Mark Crispin
Andrew Gierth
Juergen Helbing
Scott Hollenbeck
Urs Janssen
Charles Lindsey
Ade Lovett
David Magda
Ken Murchison
Francois Petillon
Peter Robinson
Rob Siemborski
Howard Swinehart
Ruud van Tol
Jeffrey Vinocur
Erik WarmelinkThe author thanks them all and apologises to anyone omitted 🥹
Finally, the present author gratefully acknowledges the vast amount of work put into previous versions by the previous author:
Stan Barber <sob@academ.com>14. References 📚
14.1. Normative References
[ANSI1986] American National Standards Institute, "Coded Character
Set - 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986.
[RFC977] Kantor, B. and P. Lapsley, "Network News Transfer
Protocol", RFC 977, February 1986.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet
Mail Extensions (MIME) Part One: Format of Internet
Message Bodies", RFC 2045, November 1996.
[RFC2047] Moore, K., "MIME (Multipurpose Internet Mail
Extensions) Part Three: Message Header Extensions for
Non-ASCII Text", RFC 2047, November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", RFC 4234, October 2005.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
[TF.686-1] International Telecommunications Union - Radio,
"Glossary, ITU-R Recommendation TF.686-1",
ITU-R Recommendation TF.686-1, October 1997.14.2. Informative References
[NNTP-AUTH] Vinocur, J., Murchison, K., and C. Newman, "Network
News Transfer Protocol (NNTP) Extension for
Authentication",
RFC 4643, October 2006.
[NNTP-STREAM] Vinocur, J. and K. Murchison, "Network News Transfer
Protocol (NNTP) Extension for Streaming Feeds",
RFC 4644, October 2006.
[NNTP-TLS] Murchison, K., Vinocur, J., and C. Newman, "Using
Transport Layer Security (TLS) with Network News
Transfer Protocol (NNTP)", RFC 4642, October 2006.
[RFC1036] Horton, M. and R. Adams, "Standard for interchange of
USENET messages", RFC 1036, December 1987.
[RFC1305] Mills, D., "Network Time Protocol (Version 3)
Specification, Implementation and Analysis", RFC 1305,
March 1992.
[RFC1869] Klensin, J., Freed, N., Rose, M., Stefferud, E., and D.
Crocker, "SMTP Service Extensions", STD 10, RFC 1869,
November 1995.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
June 1999.
[RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April
2001.
[RFC2980] Barber, S., "Common NNTP Extensions", RFC 2980, October
2000.
[ROBE1995] Robertson, R., "FAQ: Overview database / NOV General
Information", January 1995.
There is no definitive copy of this document known to
the author. It was previously posted as the Usenet
article <news:nov-faq-1-930909720@agate.Berkeley.EDU>
[SALZ1992] Salz, R., "Manual Page for wildmat(3) from the INN 1.4
distribution, Revision 1.10", April 1992.
There is no definitive copy of this document known to
the author.Appendix A. Interaction with Other Specifications 🦋
NNTP is most often used for transferring articles that conform to RFC 1036 [RFC1036] (these articles are called "Netnews articles" here). It's also sometimes used for transferring email messages that conform to RFC 2822 [RFC2822] (these are called "email articles" here). In this situation, articles must conform to both this specification and that other one, so this appendix covers some of the relevant issues 💖
A.1. Header Folding
NNTP allows a header line to be folded (by inserting a CRLF pair) before any space or TAB character 🎀
Both email and Netnews articles are required to have at least one octet other than space or TAB on each header line. So folding can only happen at one point in each sequence of consecutive spaces or TABs. Netnews articles are further required to have the header name, colon, and following space all on the first line, so folding may only happen beyond that space. Finally, some non-conforming software will remove trailing spaces and TABs from a line 💀 Therefore, it might be inadvisable to fold a header after a space or TAB.
For maximum safety, header lines SHOULD conform to the following syntax rather than to the one in Section 9.7. 🫶
header = header-name ":" SP [header-content] CRLF
header-content = [WS] token *( [CRLF] WS token )A.2. Message-IDs ✨
Okay so, every article an NNTP server handles MUST have a unique message-id 💖 For this spec, a message-id is basically an arbitrary opaque string. It just has to pass some syntax checks, and it's really only a label so you can refer to the article 🎀
Here's the tea: old articles can get reinjected into the global Usenet system, which is a huge risk 💀 So RFC 1036 [RFC1036] says message-ids have to be globally unique for all time. Iconic commitment 👑
This spec says two message-ids are the same only if they're made of the exact same sequence of octets 🦋 Other specs can decide two different sequences count as equal, because they give certain characters a special meaning. RFC 2822 [RFC2822] has "quoted" and "escaped" characters, so it sees these three message-ids as identical:
<ab.cd@example.com>
<"ab.cd"@example.com>
<"ab.\cd"@example.com>So an NNTP implementation that handles email articles has to make sure only one of those three shows up in the protocol, and it converts the other two to that one whenever it needs to. For example, when a client checks the results of a NEWNEWS command against an internal database of message-ids 🧚 Also, RFC 1036 [RFC1036] never treats two different strings as identical. Its successor (as of the time of writing) tightens up the syntax so that, whenever RFC 2822 would treat two strings as equivalent, only one of them is valid. In the example above, only the first string is valid 🙈
This spec doesn't say how an article's message-id gets determined. It could be pulled from the contents of the article, or it could come from some external source 🌸 If the server also follows another spec that defines a message-id compatible with this one, the server SHOULD use those message-ids. A common approach, and one that SHOULD be used for email and Netnews articles, is to pull the message-id out of the contents of a header named "Message-ID". Honestly this isn't always as simple as copying the whole header. You might need to strip off comments and undo quoting, or squish "equivalent" message-ids down to a canonical form 💅
If an article comes in through the IHAVE command, the command comes with a message-id. The server MAY either use it or work one out from the article contents. Whichever route it picks, it SHOULD make sure that if the IHAVE command is repeated with the same argument and article, it gets recognized as a duplicate 🔥
If an article doesn't have a message-id the server can identify, the server MUST synthesize one. That could be something simple like a sequence number, or it could be based on the date and time the article arrived ⭐ When email or Netnews articles are handled, a Message-ID header SHOULD be added so everything stays globally consistent and unique 🫶
Also, the message-id might not have come from the Message-ID header in the article, so the following example is legit (though kinda unusual) 🦋
[C] HEAD <45223423@example.com>
[S] 221 0 <45223423@example.com>
[S] Path: pathost!demo!whitehouse!not-for-mail
[S] Message-ID: <1234@example.net>
[S] From: "Demo User" <nobody@example.net>
[S] Newsgroups: misc.test
[S] Subject: I am just a test article
[S] Date: 6 Oct 1998 04:38:40 -0500
[S] Organization: An Example Net, Uncertain, Texas
[S] .A.3. Article Posting 📮
Okay, so as far as NNTP is concerned, POST and IHAVE give you the same basic stuff, just in slightly different ways. But their vibes are super different 💜
IHAVE is for moving conforming articles around between a system of NNTP servers 🌈 All those articles might also follow another spec (like, every article is a Netnews article). The client is expected to have already done any validation it needs, or it got the article from a third party that already did. So the contents SHOULD be left unchanged 🍓
POST is different. It's for when an end-user is dropping a brand new article into a system like that 🎀 The article might not be a conforming email or Netnews article, so the server is expected to check it and, if needed, convert it to the right form before sending it onward. A lot of the time that work is done by a separate piece of software on the server. If that's the case, the NNTP server SHOULD hand the incoming article to that software unaltered. No filtering characters, no folding or limiting lines, no processing the text in any other way 💅
POST can fail in all sorts of ways, so clients should be ready to resend an article 😭 When they do, it's often really important to keep the same message-id for both attempts, as far as possible. That way the server, or other servers, can tell the two articles are duplicates. So for email or Netnews articles, the posted article SHOULD contain a header named "Message-ID", and the contents of that header SHOULD be identical on each attempt. The server SHOULD also make sure two POSTed articles with the same contents for this header get recognized as identical and get the same message-id, whether or not those contents are good enough to use as the message-id itself ✨
Appendix B. Summary of Commands 📋
This section is your cheat sheet 🧚 It lists every command defined in this document, sorted two ways: by command name, and by the capability that indicates them.
Ordered by command name:
+-------------------+-----------------------+---------------+
| Command | Indicating capability | Definition |
+-------------------+-----------------------+---------------+
| ARTICLE | READER | Section 6.2.1 |
| BODY | READER | Section 6.2.3 |
| CAPABILITIES | mandatory | Section 5.2 |
| DATE | READER | Section 7.1 |
| GROUP | READER | Section 6.1.1 |
| HDR | HDR | Section 8.5 |
| HEAD | mandatory | Section 6.2.2 |
| HELP | mandatory | Section 7.2 |
| IHAVE | IHAVE | Section 6.3.2 |
| LAST | READER | Section 6.1.3 |
| LIST | LIST | Section 7.6.1 |
| LIST ACTIVE.TIMES | LIST | Section 7.6.4 |
| LIST ACTIVE | LIST | Section 7.6.3 |
| LIST DISTRIB.PATS | LIST | Section 7.6.5 |
| LIST HEADERS | HDR | Section 8.6 |
| LIST NEWSGROUPS | LIST | Section 7.6.6 |
| LIST OVERVIEW.FMT | OVER | Section 8.4 |
| LISTGROUP | READER | Section 6.1.2 |
| MODE READER | MODE-READER | Section 5.3 |
| NEWGROUPS | READER | Section 7.3 |
| NEWNEWS | NEWNEWS | Section 7.4 |
| NEXT | READER | Section 6.1.4 |
| OVER | OVER | Section 8.3 |
| POST | POST | Section 6.3.1 |
| QUIT | mandatory | Section 5.4 |
| STAT | mandatory | Section 6.2.4 |
+-------------------+-----------------------+---------------+Ordered by indicating capability:
+-------------------+-----------------------+---------------+
| Command | Indicating capability | Definition |
+-------------------+-----------------------+---------------+
| CAPABILITIES | mandatory | Section 5.2 |
| HEAD | mandatory | Section 6.2.2 |
| HELP | mandatory | Section 7.2 |
| QUIT | mandatory | Section 5.4 |
| STAT | mandatory | Section 6.2.4 |
| HDR | HDR | Section 8.5 |
| LIST HEADERS | HDR | Section 8.6 |
| IHAVE | IHAVE | Section 6.3.2 |
| LIST | LIST | Section 7.6.1 |
| LIST ACTIVE | LIST | Section 7.6.3 |
| LIST ACTIVE.TIMES | LIST | Section 7.6.4 |
| LIST DISTRIB.PATS | LIST | Section 7.6.5 |
| LIST NEWSGROUPS | LIST | Section 7.6.6 |
| MODE READER | MODE-READER | Section 5.3 |
| NEWNEWS | NEWNEWS | Section 7.4 |
| OVER | OVER | Section 8.3 |
| LIST OVERVIEW.FMT | OVER | Section 8.4 |
| POST | POST | Section 6.3.1 |
| ARTICLE | READER | Section 6.2.1 |
| BODY | READER | Section 6.2.3 |
| DATE | READER | Section 7.1 |
| GROUP | READER | Section 6.1.1 |
| LAST | READER | Section 6.1.3 |
| LISTGROUP | READER | Section 6.1.2 |
| NEWGROUPS | READER | Section 7.3 |
| NEXT | READER | Section 6.1.4 |
+-------------------+-----------------------+---------------+Appendix C. Summary of Response Codes ✨
okay bestie, this is the cheat sheet 📋 every response code defined in this document, whether it's multi-line, which commands can summon it, what arguments come along for the ride, and what it actually means. I kept the listing exactly as the spec has it so nothing gets lost 💅
Response code 100 (multi-line)
Generated by: HELP
Meaning: help text follows.
Response code 101 (multi-line)
Generated by: CAPABILITIES
Meaning: capabilities list follows.
Response code 111
Generated by: DATE
1 argument: yyyymmddhhmmss
Meaning: server date and time.
Response code 200
Generated by: initial connection, MODE READER
Meaning: service available, posting allowed.
Response code 201
Generated by: initial connection, MODE READER
Meaning: service available, posting prohibited.
Response code 205
Generated by: QUIT
Meaning: connection closing (the server immediately closes the
connection).
Response code 211
The 211 response code has two completely different forms,
depending on which command generated it:
(not multi-line)
Generated by: GROUP
4 arguments: number low high group
Meaning: group selected.
(multi-line)
Generated by: LISTGROUP
4 arguments: number low high group
Meaning: article numbers follow.
Response code 215 (multi-line)
Generated by: LIST
Meaning: information follows.
Response code 220 (multi-line)
Generated by: ARTICLE
2 arguments: n message-id
Meaning: article follows.
Response code 221 (multi-line)
Generated by: HEAD
2 arguments: n message-id
Meaning: article headers follow.
Response code 222 (multi-line)
Generated by: BODY
2 arguments: n message-id
Meaning: article body follows.
Response code 223
Generated by: LAST, NEXT, STAT
2 arguments: n message-id
Meaning: article exists and selected.
Response code 224 (multi-line)
Generated by: OVER
Meaning: overview information follows.
Response code 225 (multi-line)
Generated by: HDR
Meaning: headers follow.
Response code 230 (multi-line)
Generated by: NEWNEWS
Meaning: list of new articles follows.
Response code 231 (multi-line)
Generated by: NEWGROUPS
Meaning: list of new newsgroups follows.
Response code 235
Generated by: IHAVE (second stage)
Meaning: article transferred OK.
Response code 240
Generated by: POST (second stage)
Meaning: article received OK.
Response code 335
Generated by: IHAVE (first stage)
Meaning: send article to be transferred.
Response code 340
Generated by: POST (first stage)
Meaning: send article to be posted.
Response code 400
Generic response and generated by initial connection
Meaning: service not available or no longer available (the server
immediately closes the connection).
Response code 401
Generic response
1 argument: capability-label
Meaning: the server is in the wrong mode; the indicated capability
should be used to change the mode.
Response code 403
Generic response
Meaning: internal fault or problem preventing action being taken.
Response code 411
Generated by: GROUP, LISTGROUP
Meaning: no such newsgroup.
Response code 412
Generated by: ARTICLE, BODY, GROUP, HDR, HEAD, LAST, LISTGROUP,
NEXT, OVER, STAT
Meaning: no newsgroup selected.
Response code 420
Generated by: ARTICLE, BODY, HDR, HEAD, LAST, NEXT, OVER, STAT
Meaning: current article number is invalid.
Response code 421
Generated by: NEXT
Meaning: no next article in this group.
Response code 422
Generated by: LAST
Meaning: no previous article in this group.
Response code 423
Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT
Meaning: no article with that number or in that range.
Response code 430
Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT
Meaning: no article with that message-id.
Response code 435
Generated by: IHAVE (first stage)
Meaning: article not wanted.
Response code 436
Generated by: IHAVE (either stage)
Meaning: transfer not possible (first stage) or failed (second
stage); try again later.
Response code 437
Generated by: IHAVE (second stage)
Meaning: transfer rejected; do not retry.
Response code 440
Generated by: POST (first stage)
Meaning: posting not permitted.
Response code 441
Generated by: POST (second stage)
Meaning: posting failed.
Response code 480
Generic response
Meaning: command unavailable until the client has authenticated
itself.
Response code 483
Generic response
Meaning: command unavailable until suitable privacy has been
arranged.
Response code 500
Generic response
Meaning: unknown command.
Response code 501
Generic response
Meaning: syntax error in command.
Response code 502
Generic response and generated by initial connection
Meaning for the initial connection and the MODE READER command:
service permanently unavailable (the server immediately closes the
connection).
Meaning for all other commands: command not permitted (and there
is no way for the client to change this).
Response code 503
Generic response
Meaning: feature not supported.
Response code 504
Generic response
Meaning: error in base64-encoding [RFC4648] of an argument.Appendix D. Changes from RFC 977 🦋
okay so this appendix is the glow-up story 🌸 how this spec differs from the old RFC 977 and the RFC 2980 bits it borrowed from. The general goal was compatibility with both, but there are a bunch of changes, some compatible and some not. Here's the tea:
This list is not guaranteed to be exhaustive or correct, so it MUST NOT be relied on 🙈
- A formal syntax specification (Section 9) has been added. ✨
- The default character set is changed from US-ASCII [ANSI1986] to UTF-8 [RFC3629]. Yes, US-ASCII is a subset of UTF-8, so it's still giving compatible 💜 Section 10 talks about this more.
- All articles are required to have a message-id, which kicks out the
<0>placeholder that RFC 977 used in some responses 👋 - The newsgroup name matching stuff from RFC 977 ("wildmats", Section 4) got clarified and extended. The new bits, like commas and exclamation marks, are allowed wherever wildmats show up in the protocol 🎀
- Support for pipelining of commands (Section 3.5) is now mandatory. 🫶
- The principles behind response codes (Section 3.2) got tidied up, and in particular:
- the x8x response code family, which used to be for private extensions, is now reserved for authentication and privacy extensions 🔐
- the x9x response code family, which was once meant for debugging facilities, is now reserved for private extensions 🧚
- the 502 and 503 generic response codes (Section 3.2.1) got redefined 🔄
- new 401, 403, 480, 483, and 504 generic response codes were added 🌈
- The rules for article numbering (Section 6) are clarified, and you can also check Section 6.1.1.2 for more 📚
- The SLAVE command was ill-defined, so it's been removed from the protocol. Bye bestie 👋
- Four-digit years are now allowed in NEWNEWS (Section 7.4) and NEWGROUPS (Section 7.3), though two-digit years still work too 📅 The optional distribution parameter got removed from both.
- The LIST command (Section 7.6.1) got a massive glow-up. The original is still there as LIST ACTIVE, and the new variants are ACTIVE.TIMES, DISTRIB.PATS, and NEWSGROUPS. There's also a new "m" status flag in the LIST ACTIVE response 💅
- There's a brand new CAPABILITIES command (Section 5.2) so clients can figure out what a server supports 🔍
- The DATE command (Section 7.1) was adopted from RFC 2980 basically unchanged 🕰️
- The LISTGROUP command (Section 6.1.2) was adopted from RFC 2980. It got an optional range argument, and the 211 initial response line now matches the 211 response from the GROUP command 📋
- The MODE READER command (Section 5.3) was adopted from RFC 2980, and its meaning and effects got clarified 🎯
- The XHDR command from RFC 2980 got formalised into the new HDR (Section 8.5) and LIST HEADERS (Section 8.6) commands 📝
- The XOVER command from RFC 2980 got formalised into the new OVER (Section 8.3) and LIST OVERVIEW.FMT (Section 8.4) commands. OVER can also be applied to a message-id, not just a range 🔥
- The concept of article metadata (Section 8.1) got formalised, which means the Bytes and Lines pseudo-headers can be deprecated 🧾
Client authors, listen up 👑 lack of support for the CAPABILITIES command is a good sign that the server doesn't support this specification. Don't say I didn't warn you 💀
Author's Address 🎀
Clive D.W. Feather
THUS plc
322 Regents Park Road
London
N3 2QQ
United Kingdom
Phone: +44 20 8495 6138
Fax: +44 870 051 9937
EMail: clive@demon.net
URI: http://www.davros.org/Full Copyright Statement ©
Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. 💜
This document and the information in it are provided on an "AS IS" basis, and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED. That includes, but isn't limited to, any warranty that using the information won't infringe any rights, and any implied warranties of merchantability or fitness for a particular purpose. No cap, that's a lot of disclaimers 😭
Intellectual Property 🔐
The IETF takes no position on the validity or scope of any Intellectual Property Rights or other rights that might be claimed to apply to implementing or using the technology in this document. It also doesn't say whether any license under those rights is or isn't available, and it hasn't independently gone looking for such rights either. You can find the procedures for rights in RFC documents in BCP 78 and BCP 79 📚
Copies of IPR disclosures made to the IETF Secretariat, along with any assurances of licenses to be made available, or the results of any attempt to get a general license or permission for implementers or users of this specification to use the proprietary rights, can be found in the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology needed to implement this standard. Send that information to the IETF at ietf-ipr@ietf.org. 🫶
Acknowledgement 🌷
Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Thank you, IASA, for keeping the lights on ✨
📦 where this page comes from
- ietf: rfc3977 2006-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms