From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc6048.txt | 1403 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1403 insertions(+) create mode 100644 doc/rfc/rfc6048.txt (limited to 'doc/rfc/rfc6048.txt') diff --git a/doc/rfc/rfc6048.txt b/doc/rfc/rfc6048.txt new file mode 100644 index 0000000..96249e6 --- /dev/null +++ b/doc/rfc/rfc6048.txt @@ -0,0 +1,1403 @@ + + + + + + +Internet Engineering Task Force (IETF) J. Elie +Request for Comments: 6048 November 2010 +Updates: 2980, 3977 +Category: Standards Track +ISSN: 2070-1721 + + + Network News Transfer Protocol (NNTP) Additions to LIST Command + +Abstract + + This document defines a set of enhancements to the Network News + Transfer Protocol (NNTP) that allow a client to request extended + information from NNTP servers regarding server status, policy, and + other aspects of local configuration. These enhancements are made as + new keywords to the existing LIST capability described in RFC 3977. + + This memo updates and formalizes the LIST DISTRIBUTIONS and LIST + SUBSCRIPTIONS commands defined in RFC 2980. It also adds the LIST + COUNTS, LIST MODERATORS, and LIST MOTD commands, and specifies + additional values returned by the existing LIST ACTIVE command for + the status of a newsgroup. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6048. + +Copyright Notice + + Copyright (c) 2010 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + + + +Elie Standards Track [Page 1] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Conventions Used in This Document . . . . . . . . . . . . 4 + 1.2. Author's Note . . . . . . . . . . . . . . . . . . . . . . 4 + 2. New LIST Variants . . . . . . . . . . . . . . . . . . . . . . 4 + 2.1. Advertising the New LIST Variants . . . . . . . . . . . . 4 + 2.2. LIST COUNTS . . . . . . . . . . . . . . . . . . . . . . . 5 + 2.2.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 5 + 2.2.2. Description . . . . . . . . . . . . . . . . . . . . . 6 + 2.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . . 7 + 2.3. LIST DISTRIBUTIONS . . . . . . . . . . . . . . . . . . . . 8 + 2.3.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 8 + 2.3.2. Description . . . . . . . . . . . . . . . . . . . . . 8 + 2.3.3. Example . . . . . . . . . . . . . . . . . . . . . . . 10 + 2.4. LIST MODERATORS . . . . . . . . . . . . . . . . . . . . . 10 + 2.4.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 10 + 2.4.2. Description . . . . . . . . . . . . . . . . . . . . . 10 + 2.4.3. Example . . . . . . . . . . . . . . . . . . . . . . . 12 + 2.5. LIST MOTD . . . . . . . . . . . . . . . . . . . . . . . . 13 + 2.5.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 13 + 2.5.2. Description . . . . . . . . . . . . . . . . . . . . . 13 + 2.5.3. Example . . . . . . . . . . . . . . . . . . . . . . . 14 + 2.6. LIST SUBSCRIPTIONS . . . . . . . . . . . . . . . . . . . . 14 + 2.6.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . 14 + 2.6.2. Description . . . . . . . . . . . . . . . . . . . . . 15 + 2.6.3. Examples . . . . . . . . . . . . . . . . . . . . . . . 16 + 3. Additions to LIST ACTIVE . . . . . . . . . . . . . . . . . . . 16 + 3.1. New Status Field Values . . . . . . . . . . . . . . . . . 16 + 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 4. Augmented BNF Syntax for These Additions to the LIST + Command . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 4.1. Commands . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 4.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 21 + 5. Internationalization Considerations . . . . . . . . . . . . . 22 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 23 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 + 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 24 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 24 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 25 + + + + + + +Elie Standards Track [Page 2] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +1. Introduction + + The NNTP specification [RFC3977] defines the LIST capability and a + few keywords that can be used with that command: ACTIVE, + ACTIVE.TIMES, DISTRIB.PATS, HEADERS, NEWSGROUPS, and OVERVIEW.FMT. + Other variants of the LIST command are in use, but with limited or + absent documentation. These variants are formalized in this + document. + + The DISTRIBUTIONS and SUBSCRIPTIONS variants were originally + documented in [RFC2980]. The LIST DISTRIBUTIONS command is sent by a + news client to obtain a list of relevant distributions known by a + news server along with their descriptions. The LIST SUBSCRIPTIONS + command is sent by a news client when first connecting to a news + server so as to obtain a list of recommended newsgroups available on + it. Both of these commands are intended to be used in place of hard- + coding news clients to use specific distributions or look for + specific default newsgroups. + + The MOTD variant was originally documented in [NNTP_LIST] (which also + describes the SUBSCRIPTIONS variant). The LIST MOTD command is sent + by a news client to obtain a "message of the day" from the server + administrator regarding the current state of a news server. + + The COUNTS and MODERATORS variants have not been documented before. + The LIST COUNTS command is similar to LIST ACTIVE, except that it + also returns an estimated number of articles in each newsgroup. The + LIST MODERATORS command is sent by a news client to obtain a list of + associations between a moderated newsgroup and its submission address + template. + + The ACTIVE variant was formalized in [RFC3977], but the meanings of + only three status field values in LIST ACTIVE responses have been + specified: "y", "n", and "m". These statuses are particularly useful + for readers, since they describe local posting rights. However, + several other statuses are in use that are primarily useful for peers + as they mainly describe how remote articles coming from peers are + locally handled by a given news server. This memo defines three + other values for the status field in LIST ACTIVE responses: "x", "j", + and "=" followed by the name of a newsgroup. + + This specification should be read in conjunction with the NNTP base + specification [RFC3977]. In the case of a conflict between these two + documents, [RFC3977] takes precedence. + + + + + + + +Elie Standards Track [Page 3] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +1.1. Conventions Used in This Document + + The notational conventions used in this document are the same as + those in [RFC3977], and any term not defined in this document has the + same meaning as it does in that one. + + 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 [RFC2119]. + + When a hexadecimal correspondence is given to an octet in this + document, the value is in US-ASCII [ASCII] (for instance, ".", noted + %x2E). + + In the examples, commands from the client are indicated with [C], and + responses from the server are indicated with [S]. The client is the + initiator of the NNTP connection; the server is the other endpoint. + +1.2. Author's Note + + Please write the first letter of "Elie" with an acute accent wherever + possible -- it is U+00C9, that is to say "É" in XML. + +2. New LIST Variants + + The LIST capability is defined in Section 7.6 of [RFC3977]. It + allows the server to provide useful information to the client in + multi-line blocks. + + This document provides five new keywords to the LIST capability: + COUNTS, DISTRIBUTIONS, MODERATORS, MOTD, and SUBSCRIPTIONS. + + Each keyword is OPTIONAL and corresponds to the same-named variant of + the LIST command. + +2.1. Advertising the New LIST Variants + + When a news server implements a variant of the LIST command as + described in this specification, it advertises the corresponding + feature in the LIST capability. Where one of these new LIST keywords + is advertised, it MUST have the meaning given in this specification. + + For instance, if a news server implements the SUBSCRIPTIONS variant, + it will add the SUBSCRIPTIONS keyword to the LIST capability in + response to the CAPABILITIES command (see Section 5.2 of [RFC3977]): + + + + + + +Elie Standards Track [Page 4] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + [C] CAPABILITIES + [S] 101 Capability list: + [S] VERSION 2 + [S] READER + [S] LIST ACTIVE NEWSGROUPS SUBSCRIPTIONS + [S] . + [C] LIST SUBSCRIPTIONS + [S] 215 List of recommended newsgroups follows + [S] local.welcome + [S] local.test + [S] news.newusers.questions + [S] news.announce.newusers + [S] . + + For each of the new LIST variants described in this specification, an + empty response can be sent to the client: + + [C] LIST SUBSCRIPTIONS + [S] 215 List of recommended newsgroups follows + [S] . + + This means that the information is maintained by the news server but + that it is voluntarily empty. Frequently, the news server maintains + the information in a configuration file. This file can be empty or + contain only commented or blank lines, indicating a voluntary absence + of information. + + When the news server software implements one of these LIST variants + but a particular server does not maintain the information (for + instance, when the configuration file does not exist), the 503 + response code MUST be returned: + + [C] LIST SUBSCRIPTIONS + [S] 503 No list of recommended newsgroups available + +2.2. LIST COUNTS + +2.2.1. Usage + + Syntax + LIST COUNTS [wildmat] + + Responses + 215 List of newsgroups follows (multi-line) + + Parameters + wildmat Groups of interest + + + + +Elie Standards Track [Page 5] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +2.2.2. Description + + See Section 7.6.1 of [RFC3977] for general requirements of the LIST + command. + + The LIST COUNTS command returns a list of valid newsgroups carried by + the news server along with associated information, the "counts list", + and is similar to LIST ACTIVE. + + The information is returned as a multi-line data block following the + 215 response code and contains one line per newsgroup. Each line of + this list MUST consist of five fields separated from each other by + one or more spaces (the usual practice is a single space) in the + following order: + + o The name of the newsgroup. + + o The reported high water mark for the group. + + o The reported low water mark for the group. + + o The estimated number of articles in the group. + + o The current status of the group on this server. + + The reported high and low water marks, and the estimated number of + articles, are as described in the GROUP command (see Section 6.1.1 of + [RFC3977]), but note that they are in the opposite order to the 211 + response (that is, number low high group) to the GROUP command. The + current status of the group is as described in the LIST ACTIVE + command (see Section 7.6.3 of [RFC3977], as well as Section 3 of this + document). Also note that, similarly to the LIST ACTIVE command, TAB + characters are not valid separators for the LIST COUNTS command. + + The order of newsgroups in the counts list is not significant. The + server need not consistently return the same order or the same + results if this command is used more than once in a session. + + The same newsgroup SHOULD NOT appear twice in the output of this + command. + + The counts list is newsgroup-based, and a wildmat MAY be specified, + in which case the response is limited to only the groups, if any, + whose names match the wildmat. If no wildmat is specified, the + server MUST include every newsgroup that the client is permitted to + select with the GROUP command (see Section 6.1.1 of [RFC3977]). + + + + + +Elie Standards Track [Page 6] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + The counts list MAY be empty. If the server does not maintain the + information, a 503 response code MUST be returned. (However, note + that a news server that supports this command usually maintains the + information.) + + The client MAY use LIST COUNTS in order to obtain an estimate of the + number of articles in every newsgroup the server carries, which + enables it to provide the end user with this information. This + provides a simpler mechanism for a client to obtain the estimated + number of articles in newsgroups, compared with a sequence of + individual GROUP commands. + +2.2.3. Examples + + Example of output with no argument: + + [C] CAPABILITIES + [S] 101 Capability list: + [S] VERSION 2 + [S] READER + [S] LIST ACTIVE COUNTS NEWSGROUPS + [S] . + [C] LIST COUNTS + [S] 215 List of newsgroups follows + [S] misc.test 3002322 3000234 1234 y + [S] comp.risks 442001 441099 742 m + [S] rec.food.drink.tea 100 51 3 y + [S] local.empty 7 8 0 y + [S] local.tea 2004 1504 301 y + [S] . + + Example of output with a wildmat: + + [C] LIST COUNTS *.tea,misc.*,!local.* + [S] 215 List of newsgroups follows + [S] misc.test 3002322 3000234 1234 y + [S] rec.food.drink.tea 100 51 3 y + [S] . + + + + + + + + + + + + + +Elie Standards Track [Page 7] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + Example of output on an implementation that includes leading zeroes: + + [C] LIST COUNTS + [S] 215 List of newsgroups follows + [S] misc.test 0003002322 0003000234 1234 y + [S] comp.risks 0000442001 0000441099 742 m + [S] rec.food.drink.tea 0000000100 0000000051 3 y + [S] local.empty 0000000007 0000000008 0 y + [S] local.tea 0000002004 0000001504 301 y + [S] . + + The estimated number of articles usually does not start with leading + zeroes, but MAY start with such zeroes. + +2.3. LIST DISTRIBUTIONS + +2.3.1. Usage + + Syntax + LIST DISTRIBUTIONS + + Responses + 215 Distributions list follows (multi-line) + +2.3.2. Description + + See Section 7.6.1 of [RFC3977] for general requirements of the LIST + command. + + A "distributions list" is maintained by some NNTP servers to contain + the name of each distribution that is known by the news server and a + short description about the meaning of the distribution. + Distributions are used by clients as potential values for the + Distribution header field body of a news article being posted (see + Section 3.2.4 of [RFC5536] for the definition of this header field). + + The information is returned as a multi-line data block following the + 215 response code and contains one line per distribution. Each line + of this list MUST consist of two fields separated from each other by + one or more space or TAB characters (the usual practice is a single + TAB). The first field is the name of the distribution, and the + second field is a short description of the distribution. There are + no leading or trailing whitespaces in a line. The description MAY + contain whitespaces. + + + + + + + +Elie Standards Track [Page 8] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + The order of distributions in the distributions list is not + significant; the server need not consistently return the same order + or the same results if this command is used more than once in a + session. + + The same distribution SHOULD NOT appear twice in the output of this + command. + + The description MUST be in UTF-8 [RFC3629]. + + The distributions list is not newsgroup-based, and an argument MUST + NOT be specified. Otherwise, a 501 response code MUST be returned. + + The distributions list MAY be empty. If the server does not maintain + the information, a 503 response code MUST be returned. + + The client MAY use this information to generate or supplement a list + of known distributions provided to the user. If the news server + implements the LIST DISTRIBUTIONS command, it SHOULD also implement + the LIST DISTRIB.PATS command (defined in Section 7.6.5 of [RFC3977]) + and describe in the distributions list all the distributions present + in the distrib.pats list so that the client can use both of these + commands jointly (naturally, the distributions list can also describe + distributions that are not present in the distrib.pats list). Note + that the two commands need not return distributions in the same + order. + + + + + + + + + + + + + + + + + + + + + + + + + +Elie Standards Track [Page 9] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +2.3.3. Example + + Example of a joint use of LIST DISTRIB.PATS and LIST DISTRIBUTIONS: + + [C] CAPABILITIES + [S] 101 Capability list: + [S] VERSION 2 + [S] READER + [S] LIST ACTIVE DISTRIB.PATS DISTRIBUTIONS NEWSGROUPS + [S] . + [C] LIST DISTRIB.PATS + [S] 215 Information follows + [S] 10:local.*:local + [S] 5:france.*:fr + [S] 20:local.here.*:thissite + [S] . + [C] LIST DISTRIBUTIONS + [S] 215 List of distributions follows + [S] fr Local to France. + [S] local Local to this news server. + [S] thissite Local to this site. + [S] usa Local to the United States of America. + [S] . + +2.4. LIST MODERATORS + +2.4.1. Usage + + Syntax + LIST MODERATORS + + Responses + 215 Moderators list follows (multi-line) + +2.4.2. Description + + See Section 7.6.1 of [RFC3977] for general requirements of the LIST + command. + + The "moderators list" is maintained by some NNTP servers to make + clients aware of how the news server will generate a submission + e-mail address when an article is locally posted to a moderated + newsgroup. + + The information is returned as a multi-line data block following the + 215 response code. Each line of this list MUST consist of two fields + separated from each other by a colon (":" or %x3A). The first field + is a wildmat (which may be a simple newsgroup name), and the second + + + +Elie Standards Track [Page 10] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + field is the submission address template for newsgroups matching that + wildmat. There are no leading or trailing whitespaces in a line. + The submission template MAY contain colons (":"). + + The submission template is essentially an e-mail address (see the + definition of "addr-spec" in Section 3.4.1 of [RFC5322]), except with + certain modifications. The case-sensitive string "%s" (%x25.73) MUST + occur either zero or one time in the template. If there is to be a + literal "%" in the submission address, it MUST be written as "%%" in + the template, even if not followed by an "s". The character "%" MUST + NOT occur in the submission template, except as part of "%s" or "%%". + + The order of lines in the moderators list is significant: the first + matching line is used. Consequently, specific patterns should be + listed before general patterns. Every moderated newsgroup name + SHOULD be matched by at least one line in the list; often this is + achieved by having a default pattern at the bottom, but other + approaches are acceptable, and news server software MAY leave this up + to the server administrator rather than enforcing it + programmatically. + + When an article without an Approved header field is locally posted to + a moderated newsgroup, the server generates a submission address from + the corresponding submission template (that is, the second field of + the first matching line in the moderators list) by replacing the + "%s", if present, with the name of the matching newsgroup after each + period ("." or %x2E) in the name has been changed to a dash ("-" or + %x2D). In addition, any "%%" is changed back to "%". The server + then forwards the submitted article to the moderator at the resulting + submission address (see Section 3.5.1 of [RFC5537]). + + NOTE: The creation and maintenance of submission addresses is + outside the scope of this specification. + + The moderators list is not newsgroup-based, and an argument MUST NOT + be specified. Otherwise, a 501 response code MUST be returned. + + The moderators list MAY be empty. If the server does not maintain + the information, a 503 response code MUST be returned, although these + situations should not occur if the news server is an injecting agent + that carries moderated newsgroups. + + + + + + + + + + +Elie Standards Track [Page 11] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +2.4.3. Example + + Example of output: + + [C] CAPABILITIES + [S] 101 Capability list: + [S] VERSION 2 + [S] READER + [S] POST + [S] LIST ACTIVE MODERATORS NEWSGROUPS + [S] . + [C] LIST MODERATORS + [S] 215 List of submission address templates follows + [S] foo.bar:announce@example.com + [S] local.*:%s@localhost + [S] *:%s@moderators.example.com + [S] . + + The following table describes a few examples associating a moderated + newsgroup and its submission address on a news server whose + moderators list is the one in the previous example: + + +-----------------------------+-------------------------------------+ + | Name of the moderated | Submission address | + | newsgroup | | + +-----------------------------+-------------------------------------+ + | foo.bar | announce@example.com | + | local.test | local-test@localhost | + | alt.dev.null | alt-dev-null@moderators.example.com | + | alt.test-me | alt-test-me@moderators.example.com | + +-----------------------------+-------------------------------------+ + + NOTE: When "%s" is used, periods are changed to dashes, and dashes + are left alone. This implies that two moderated newsgroups whose + names differ only by changing a period to a dash would have the + same submission address. Therefore, if a server carries such + moderated newsgroup pairs but posts should go to different + submission addresses, a "%s" pattern template cannot be used for + the moderation submission addresses for those groups, and explicit + entries without a pattern will be required. + + Similarly, it is not recommended to use a "%s" pattern rule for + the moderation submission template for two moderated newsgroups + whose names differ only by the case of their characters, because + e-mail systems frequently treat the left-hand side of e-mail + addresses as case-sensitive. See also Section 3.1.4 of [RFC5536] + and Section 7.2 of [USEAGE] for the syntax of a newsgroup name. + + + + +Elie Standards Track [Page 12] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +2.5. LIST MOTD + +2.5.1. Usage + + Syntax + LIST MOTD + + Responses + 215 Information follows (multi-line) + +2.5.2. Description + + See Section 7.6.1 of [RFC3977] for general requirements of the LIST + command. + + The "motd" contains a "message of the day" relevant to the news + server. It is intended to provide notification and communication + between the news administrator and the news user. For instance, + notification of upcoming downtime or information about new facilities + available on the news server can be communicated via the LIST MOTD + command. + + The information is returned as a multi-line data block following the + 215 response code. This text is not guaranteed to be in any + particular format although, like all multi-line data blocks, it is + "dot-stuffed". + + The server need not return the same information if this command is + used more than once in a session. It MAY indeed send a different + message of the day depending on the state of the session. For + instance, on a mode-switching news server, the information can be + different between its transit mode and its reader mode, or between an + authenticated session and an unauthenticated session. + + The information MUST be in UTF-8 [RFC3629]. + + The motd is not newsgroup-based, and an argument MUST NOT be + specified. Otherwise, a 501 response code MUST be returned. + + The motd MAY be empty. If the server does not maintain the + information, a 503 response code MUST be returned. + + It is up to the client to decide when and how to display this message + to the user. No timestamp or date of last modification is provided + programmatically, although the news administrator may include one in + the text of the motd. The client MAY cache a local copy or + fingerprint of the motd so that it can display the message to the + user only upon modification. If the client caches the information, + + + +Elie Standards Track [Page 13] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + it MAY take into account only the motd obtained after reaching the + intended state of the session. Nonetheless, in case a privacy + extension is used, the client MUST NOT cache any motd obtained before + that extension took effect. + + NOTE: Though the client MAY cache the results of this command, it + MUST NOT rely on the correctness of any cached results, whether + from earlier in the session or from a previous session. If the + motd is cached, the client SHOULD provide a way to force the + cached information to be refreshed. + +2.5.3. Example + + Example of output: + + [C] CAPABILITIES + [S] 101 Capability list: + [S] VERSION 2 + [S] READER + [S] LIST ACTIVE MOTD NEWSGROUPS + [S] . + [C] LIST MOTD + [S] 215 Message of the day follows + [S] Attention all users, + [S] + [S] This server will be down for scheduled upgrades on February 1st. + [S] It should be back up by 8:00 a.m. February 2nd. + [S] Any questions should be e-mailed to . + [S] + [S] Apologies for the disturbance. + [S] . + +2.6. LIST SUBSCRIPTIONS + +2.6.1. Usage + + Syntax + LIST SUBSCRIPTIONS [wildmat] + + Responses + 215 Subscriptions list follows (multi-line) + + Parameters + wildmat Groups of interest + + + + + + + +Elie Standards Track [Page 14] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +2.6.2. Description + + See Section 7.6.1 of [RFC3977] for general requirements of the LIST + command. + + The "subscriptions list" is maintained by some NNTP servers to + provide the client with a list of recommended newsgroups. + + The information is returned as a multi-line data block following the + 215 response code. Each line of this list MUST consist of a + newsgroup name. There are no leading or trailing whitespaces in a + line. + + The order of newsgroups in the subscriptions list is significant: + they are listed by order of importance, the first newsgroup being the + most important to subscribe to. + + The same newsgroup name SHOULD NOT appear twice in the output of this + command. The subscriptions list SHOULD contain only newsgroups the + news server carries. + + The subscriptions list is newsgroup-based, and a wildmat MAY be + specified, in which case the response is limited to only the groups, + if any, whose names match the wildmat. Note that the wildmat + argument is a new feature in this specification, and servers that do + not support CAPABILITIES or do not advertise the SUBSCRIPTIONS + keyword in the LIST capability (and therefore do not conform to this + specification) are unlikely to support it. + + The subscriptions list MAY be empty. If the server does not maintain + the information, a 503 response code MUST be returned. + + The client MAY use this information the first time it connects to the + news server so as to initialize the list of default subscribed + newsgroups. This list should therefore contain groups intended for + new users on the news server or Usenet in general (for instance, + newsgroups dedicated to testing, support, announcement, or FAQs). + The client MAY present the groups in the order of appearance in the + list to the user. When the subscriptions list is maintained and + non-empty, the news client SHOULD use it, instead of a hard-coded + default list, if any. + + + + + + + + + + +Elie Standards Track [Page 15] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +2.6.3. Examples + + Example of output with no argument: + + [C] CAPABILITIES + [S] 101 Capability list: + [S] VERSION 2 + [S] READER + [S] LIST ACTIVE NEWSGROUPS SUBSCRIPTIONS + [S] . + [C] LIST SUBSCRIPTIONS + [S] 215 List of recommended newsgroups follows + [S] local.welcome + [S] local.test + [S] news.newusers.questions + [S] news.announce.newusers + [S] . + + Example of output with a wildmat: + + [C] LIST SUBSCRIPTIONS local.* + [S] 215 List of recommended newsgroups follows + [S] local.welcome + [S] local.test + [S] . + +3. Additions to LIST ACTIVE + + This document specifies three new status field values that can be + used in the answers to LIST ACTIVE: "x", "j", and "=" followed by the + name of a newsgroup. + +3.1. New Status Field Values + + The LIST ACTIVE command is defined in Section 7.6.3 of [RFC3977]. + The fourth field of each line of this list indicates the current + status of the newsgroup whose name is specified in the first field. + Three status field values are defined in [RFC3977]: + + "y" Posting is permitted. + + "n" Posting is not permitted. + + "m" Postings will be forwarded to the newsgroup moderator. + + + + + + + +Elie Standards Track [Page 16] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + This document defines three other case-sensitive status field values + that can also be used: + + "x" Postings and articles from peers are not permitted. + + "j" Only articles from peers are permitted; no articles are locally + filed. + + "=other.group" Only articles from peers are permitted, and are filed + under the newsgroup named "other.group". + + The server SHOULD use these values when these meanings are required + and MUST NOT use them with any other meaning. + + A newsgroup with status "x" is a newsgroup with status "n", except + that articles from peers are not accepted. A newsgroup with status + "x" is considered as closed: no new articles will arrive in such a + group. On the contrary, articles from peers will arrive in a + newsgroup with status "n". Local postings are not allowed in a + newsgroup with either of these two status field values. + + A newsgroup with status "j" is a newsgroup with status "y", except + that (1) local postings are not accepted, (2) articles received from + a peer that are crossposted to one or more valid groups are filed + only into those valid groups, and (3) articles received from a peer + that are not crossposted to any valid groups are not filed into any + newsgroup, but are still propagated to other peers, if appropriate. + + NOTE: Instead of not filing at all an article posted to a + newsgroup with status "j", a news server MAY file it under a + catch-all group if no valid group is applicable. When a news + server uses a catch-all group to file the articles posted to + newsgroups with status "j", this catch-all group SHOULD be named + "junk". (The first letter of the "junk" newsgroup explains why + this status has been called "j".) + + Consequently, when a news server carries the "junk" newsgroup and + uses it for the purpose of the "j" status, the "junk" newsgroup + contains all postings not filed under another newsgroup, + regardless of the status of the "junk" newsgroup. (However, an + article posted explicitly to "junk" is treated according to the + status of the "junk" newsgroup.) + + The "junk" newsgroup may be available to news readers and is often + used by a news server as a way to locally store an article that + will be transmitted to peers (which may carry some of the + newsgroups the article was posted to even if the local server does + not). In addition, instead of rejecting an article that contains + + + +Elie Standards Track [Page 17] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + an invalid Newsgroups header field or that is posted to newsgroups + it does not carry, a news server may accept such an article and + file it under the catch-all newsgroup. + + Depending on the configuration of the news server, mentioning a + newsgroup with status "j" is different than simply not listing the + group, since articles arriving for unknown newsgroups may be + rejected. + + When the status field value begins with an equal sign ("=" or %x3D), + a newsgroup name on the news server MUST immediately follow the sign. + If the status of "foo.bar" is "=other.group", it means that "foo.bar" + is an alias for "other.group". These two newsgroups are distinct; + they do not share their articles or their article numbers. Local + postings to "foo.bar" are not allowed, but articles from peers are + accepted for "foo.bar" and filed into "other.group", regardless of + the status of "other.group". The contents of their Newsgroups header + fields MUST NOT be altered. + + Alias groups are typically used during a transition between two + newsgroups, including but not limited to a renaming of a group, or a + correction of a misspelled group name. + + The status of the newsgroup an alias points to MUST NOT be taken into + account when an article arrives in an alias newsgroup. In + particular, it means that unapproved articles arriving from peers in + an alias pointing to a moderated newsgroup are accepted and filed + into this moderated newsgroup. Therefore, an alias SHOULD NOT point + to a moderated newsgroup, since it allows bypassing of the + moderation. + + An alias SHOULD NOT point to itself or another alias group. The + newsgroup an alias points to SHOULD exist on the news server, and be + visible to any client that can see the original group. However, when + a client issues a LIST ACTIVE command with a wildmat including the + original group, the newsgroup it points to is not listed in the + response (unless of course the second newsgroup also matches the + wildmat). + + NOTE: If a server files newsgroups with status "j" into "junk", a + newsgroup with status "j" and a newsgroup with status "=junk" are + different. An article fed by a peer, and crossposted to a group + with status "j", will result in the article being filed only in + "junk" if there are no other groups with which to file it, or + otherwise only in other valid newsgroups it is crossposted to. On + the other hand, an article fed by a peer, and crossposted to a + group with status "=junk", will result in the article being filed + in "junk" and in other valid newsgroups it is crossposted to. + + + +Elie Standards Track [Page 18] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + The following table summarizes what usually happens to an article + posted to only the newsgroup "foo.bar", depending on its status field + value on the news server: + + +---------------+------------+-----------+------------+-------------+ + | Status field | Accepted | Accepted | Moderation | Destination | + | value of | if local | from | needed? | if accepted | + | "foo.bar" | posting? | peers? | | | + +---------------+------------+-----------+------------+-------------+ + | y | Yes | Yes | No | foo.bar | + | n | No | Yes | No | foo.bar | + | m | Yes | Yes | Yes | foo.bar | + | x | No | No | No | | + | j | No | Yes | No | junk (if | + | | | | | filed) | + | =other.group | No | Yes | No | other.group | + +---------------+------------+-----------+------------+-------------+ + + The following table summarizes what usually happens to an article + crossposted to the newsgroup "foo.bar" and a valid newsgroup + "misc.test" (whose status field is "y") known by the news server, + depending on the status field value of "foo.bar" on the news server: + + +---------------+-----------+-----------+------------+--------------+ + | Status field | Accepted | Accepted | Moderation | Destination | + | value of | if local | from | needed? | if accepted | + | "foo.bar" | posting? | peers? | | | + +---------------+-----------+-----------+------------+--------------+ + | y | Yes | Yes | No | foo.bar, | + | | | | | misc.test | + | n | No | Yes | No | foo.bar, | + | | | | | misc.test | + | m | Yes | Yes | Yes | foo.bar, | + | | | | | misc.test | + | x | No | Yes | No | misc.test | + | j | No | Yes | No | misc.test | + | =other.group | No | Yes | No | other.group, | + | | | | | misc.test | + +---------------+-----------+-----------+------------+--------------+ + + NOTE: The status of a newsgroup only indicates how articles + arriving for that newsgroup are normally processed; news servers + MAY provide clients with special privileges to allow or disallow + some rights in these newsgroups. This specification defines + neither these rights nor whether or not articles posted to these + groups should be propagated to other peers. + + + + + +Elie Standards Track [Page 19] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +3.2. Examples + + Example of an article posted to an alias group by a peer: + + [C] LIST ACTIVE + [S] 215 List of newsgroups follows + [S] foo.bar 21 12 y + [S] misc.test 3002322 3000234 =foo.bar + [S] . + [C] IHAVE + [S] 335 Send it; end with . + [C] Path: demo!.POSTED.somewhere!not-for-mail + [C] From: "Demo User" + [C] Newsgroups: misc.test + [C] Subject: I am just a test article + [C] Date: 18 Oct 2008 16:02:45 +0200 + [C] Organization: An example, Paris, FR. + [C] Message-ID: + [C] MIME-Version: 1.0 + [C] + [C] This is just a test article. + [C] . + [S] 235 Article transferred OK + [C] LIST ACTIVE + [S] 215 List of newsgroups follows + [S] foo.bar 22 12 y + [S] misc.test 3002322 3000234 =foo.bar + [S] . + [C] HDR Xref + [S] 225 Header information follows + [S] 0 news.example.com foo.bar:22 + [S] . + [C] HDR Newsgroups + [S] 225 Header information follows + [S] 0 misc.test + [S] . + + The Newsgroups header field of this article is kept untouched. This + article is filed under "foo.bar" even though it has originally been + posted to the newsgroup "misc.test". Yet, it still propagates to + peers that have been configured to receive articles posted to + "misc.text". + + + + + + + + + +Elie Standards Track [Page 20] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + Example of an article locally posted to an alias group: + + [C] LIST ACTIVE + [S] 215 List of newsgroups follows + [S] foo.bar 22 12 y + [S] misc.test 3002322 3000234 =foo.bar + [S] . + [C] POST + [S] 340 Input article; end with . + [C] From: "Demo User" + [C] Newsgroups: misc.test + [C] Subject: I am just a test article + [C] MIME-Version: 1.0 + [C] + [C] This is just a test article. + [C] . + [S] 441 Newsgroup "misc.test" has been renamed to "foo.bar" + + The article is rejected, with a detailed error. + +4. Augmented BNF Syntax for These Additions to the LIST Command + + This section describes the formal syntax of the new LIST variants + defined in this document using [RFC5234]. It extends the syntax in + Section 9 of [RFC3977], and non-terminals not defined in this + document are defined there. The [RFC3977] ABNF should be imported + first, before attempting to validate these rules. + +4.1. Commands + + This syntax extends the non-terminal , which + represents the variants of the LIST command. + + ; counts + list-arguments =/ "COUNTS" [WS wildmat] + + ; distributions, moderators, motd + list-arguments =/ "DISTRIBUTIONS" / "MODERATORS" / "MOTD" + + ; subscriptions + list-arguments =/ "SUBSCRIPTIONS" [WS wildmat] + +4.2. Responses + + This syntax extends the non-terminals and + , which represent the status field value returned by + the LIST ACTIVE command and the response contents for the LIST + command, respectively. + + + +Elie Standards Track [Page 21] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + ; active + newsgroup-status =/ newsgroup-alias / + %x78 / %x6a ; case-sensitive "x" and "j" + newsgroup-alias = "=" newsgroup-name + + ; counts + list-content =/ list-counts-content + list-counts-content = + *(newsgroup-name 3(SPA article-number) + SPA newsgroup-status CRLF) + + ; distributions + list-content =/ list-distributions-content + list-distributions-content = + *(distribution WS distribution-description CRLF) + distribution-description = U-TEXT + + ; moderators + list-content =/ list-moderators-content + list-moderators-content = + *(wildmat ":" moderators-address CRLF) + moderators-address = S-TEXT + + ; motd + list-content =/ list-motd-content + list-motd-content = *(*U-CHAR CRLF) + + ; subscriptions + list-content =/ list-subscriptions-content + list-subscriptions-content = *(newsgroup-name CRLF) + +5. Internationalization Considerations + + No new internationalization considerations are introduced by this + extension, beyond those already described in the core specification + [RFC3977]. + + In particular, newsgroup names SHOULD be restricted to US-ASCII + [ASCII] until a successor to [RFC5536] standardizes another approach. + + Distribution descriptions and the message of the day MUST be in UTF-8 + [RFC3629]. + + + + + + + + + +Elie Standards Track [Page 22] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + +6. Security Considerations + + No new security considerations are introduced by this extension, + beyond those already described in the core specification [RFC3977] + and the Netnews Architecture and Protocols specification [RFC5537] + (especially distribution leakage and e-mail Denial of Service during + the moderation process). + +7. IANA Considerations + + This section gives a formal definition of this extension as required + by Section 3.3.3 of [RFC3977] for the IANA registry. It extends the + LIST capability label defined in Section 7.6 of [RFC3977]. + + o This extension provides additional keywords to the pre-existing + LIST capability defined in Section 7.6 of [RFC3977]. New status + field values are also added to the ACTIVE variant of the LIST + command. + + o The capability label that this extension extends is "LIST". + + o This extension adds five optional arguments to the "LIST" + capability label: "COUNTS", "DISTRIBUTIONS", "MODERATORS", "MOTD", + and "SUBSCRIPTIONS", indicating which new variants of the LIST + command are supported. Consequently, this extension associates + these new arguments with the pre-existing "LIST" NNTP command. + + o This extension defines five new commands, LIST COUNTS, LIST + DISTRIBUTIONS, LIST MODERATORS, LIST MOTD, and LIST SUBSCRIPTIONS, + whose behavior, arguments, and responses are defined in + Sections 2.2, 2.3, 2.4, 2.5, and 2.6, respectively. + + o This extension does not associate any new responses with pre- + existing NNTP commands. + + o This extension does not affect the maximum length of commands or + initial response lines. + + o This extension does not alter pipelining. The LIST COUNTS, LIST + DISTRIBUTIONS, LIST MODERATORS, LIST MOTD, and LIST SUBSCRIPTIONS + commands can be pipelined. + + o Use of this extension does not alter the capabilities list. + + o This extension does not cause any pre-existing command to produce + a 401, 480, or 483 response. + + + + + +Elie Standards Track [Page 23] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + o This extension is unaffected by any use of the MODE READER + command. + + o This extension does not affect the overall behavior of a server or + client other than via the new commands. + + o Published Specification: This document. + + o Contact for Further Information: Author of this document. + + o Change Controller: IESG . + +8. Acknowledgements + + The author gratefully acknowledges the comments and additional + information provided by Russ Allbery, Urs Janssen, Antti-Juhani + Kaijanaho, Alexey Melnikov, Peter Saint-Andre, Dieter Stussy, and + Sean Turner on this document. + + The author would particularly like to thank Jeffrey M. Vinocur for + having reread, improved, and patiently fixed the English wording and + the quality of this document. + + Special thanks are due to: + + Stan Barber, whose text in [RFC2980] served as the initial basis + for the DISTRIBUTIONS and SUBSCRIPTIONS variants of the LIST + command. + + Brian Hernacki, whose text in [NNTP_LIST] served as the initial + basis for the MOTD and also the SUBSCRIPTIONS variants of the LIST + command. + + The authors of the documentation of a few sample files of the + InterNetNews news server ("active", "distributions", "moderators", + "motd.news", and "subscriptions"): Russ Allbery, Bettina Fink, + Rich Salz, and a few other people to whom I am also grateful. + +9. References + +9.1. Normative References + + [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. + + + + +Elie Standards Track [Page 24] + +RFC 6048 NNTP Additions to LIST Command November 2010 + + + [RFC3977] Feather, C., "Network News Transfer Protocol (NNTP)", + RFC 3977, October 2006. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, + October 2008. + +9.2. Informative References + + [ASCII] American National Standards Institute, "Coded Character + Sets - 7-Bit American Standard Code for Information + Interchange (7-Bit ASCII), ANSI X3.4", 1986. + + [NNTP_LIST] Hernacki, B., "NNTP LIST Additions", Work in Progress, + July 1997. + + [RFC2980] Barber, S., "Common NNTP Extensions", RFC 2980, + October 2000. + + [RFC5536] Murchison, K., Lindsey, C., and D. Kohn, "Netnews + Article Format", RFC 5536, November 2009. + + [RFC5537] Allbery, R. and C. Lindsey, "Netnews Architecture and + Protocols", RFC 5537, November 2009. + + [USEAGE] Lindsey, C., "Usenet Best Practice", Work in Progress, + March 2005. + +Author's Address + + Julien Elie + 13 rue Marx Dormoy + Noisy-le-Grand 93160 + France + + EMail: julien@trigofacile.com + URI: http://www.trigofacile.com/ + + + + + + + + + + + + +Elie Standards Track [Page 25] + -- cgit v1.2.3