RFC 6048

Network News Transfer Protocol (NNTP) Additions to LIST Command

📅 published November 2010, from ietf

RFC 6048 💖 Network News Transfer Protocol (NNTP) Additions to LIST Command

  • Author: J. Elie 🎀
  • Category: Standards Track ✨
  • Date: November 2010 🌸
  • Updates: 2980, 3977 💅
  • ISSN: 2070-1721
  • Published by: Internet Engineering Task Force (IETF) 🦋

Abstract

okay so this doc is all about giving news clients a way to ask NNTP servers for extra info about server status, policy, and how the local setup is configured 🧚 it's giving information superhighway. The new stuff comes in as new keywords on the existing LIST capability from RFC 3977 💜

It also updates and formalizes LIST DISTRIBUTIONS and LIST SUBSCRIPTIONS from RFC 2980 🔥 and adds LIST COUNTS, LIST MODERATORS, and LIST MOTD. It also gives the LIST ACTIVE command more status values for a newsgroup ✨ slay.

Status of This Memo

This is an Internet Standards Track document 👑

It's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community 🫶 It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). More on Internet Standards is in Section 2 of RFC 5741 🌈

For the current status, any errata, and how to give feedback, check http://www.rfc-editor.org/info/rfc6048 🍓

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. Please read these carefully, bestie, because they spell out your rights and restrictions for this document 📜 Code Components pulled out of this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come 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

1. Introduction 🌸

okay so the NNTP spec in [RFC3977] defines the LIST capability and a handful of keywords you can use with it: ACTIVE, ACTIVE.TIMES, DISTRIB.PATS, HEADERS, NEWSGROUPS, and OVERVIEW.FMT. Other LIST variants are out in the wild too, but the docs for them are limited or totally missing 😭 so this document formalizes them 💅

DISTRIBUTIONS and SUBSCRIPTIONS were first written up in [RFC2980]. The LIST DISTRIBUTIONS command is how a news client gets a list of relevant distributions the news server knows about, plus their descriptions ✨ LIST SUBSCRIPTIONS is what a news client sends when it first connects, so it can grab a list of recommended newsgroups on that server 🧚 Both are meant to replace hard-coding clients to use specific distributions or look for specific default newsgroups. no more hard-coded vibes 🙅‍♀️

The MOTD variant was first documented in [NNTP_LIST], which also covers SUBSCRIPTIONS. LIST MOTD is how a news client asks for the "message of the day" from the server administrator about the current state of the news server 📣

COUNTS and MODERATORS have never been documented before 👀 LIST COUNTS works like LIST ACTIVE, except it also returns an estimated number of articles in each newsgroup 🔢 LIST MODERATORS is how a news client gets a list of associations between a moderated newsgroup and its submission address template 💌

The ACTIVE variant was formalized in [RFC3977], but only three status field values in LIST ACTIVE responses have meanings specified: "y", "n", and "m". These are super useful for readers because they tell you your local posting rights 🙌 But a bunch of other statuses are in use that mostly matter to peers, since they describe how remote articles coming from peers get handled locally by a given news server 🤓 This memo defines three more status field values for LIST ACTIVE responses: "x", "j", and "=" followed by the name of a newsgroup 🦋

This spec should be read alongside the NNTP base spec [RFC3977]. If the two ever conflict, [RFC3977] wins 👑

1.1. Conventions Used in This Document

The notation conventions here are the same as in [RFC3977], and any term not defined in this document means the same thing it does there 📚

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 value is given for an octet in this document, the value is in US-ASCII [ASCII]. For example, "." is noted as %x2E 🔤

In the examples, commands from the client are marked with [C] and responses from the server are marked with [S]. The client is the initiator of the NNTP connection, and 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's U+00C9, which is É in XML 🎀 iconic.

2. New LIST Variants 🧚

The LIST capability is defined in Section 7.6 of [RFC3977]. It lets the server give the client useful info in multi-line blocks 📦

This document adds five new keywords to the LIST capability: COUNTS, DISTRIBUTIONS, MODERATORS, MOTD, and SUBSCRIPTIONS 🌈

Each keyword is OPTIONAL and matches the same-named variant of the LIST command 💜

2.1. Advertising the New LIST Variants

When a news server implements one of the LIST variants described in this spec, it advertises the matching feature in the LIST capability. And when one of these new LIST keywords is advertised, it MUST have the meaning given in this specification. no wiggle room, periodt 💅

For example, if a news server implements the SUBSCRIPTIONS variant, it adds the SUBSCRIPTIONS keyword to the LIST capability in response to the CAPABILITIES command (see Section 5.2 of [RFC3977]) ✨

[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 in this spec, the server can send an empty response to the client 🫧

[C] LIST SUBSCRIPTIONS
[S] 215 List of recommended newsgroups follows
[S] .

This means the server does maintain the information, but it's voluntarily empty 🙈 Usually the server keeps this info in a configuration file. That file can be empty, or it can contain only commented or blank lines, which signals a voluntary absence of information 📝

When the server software implements one of these LIST variants, but a particular server doesn't maintain the information (say, because the configuration file doesn't exist), the 503 response code MUST be returned 🚨 yikes, no skipping it:

[C] LIST SUBSCRIPTIONS
[S] 503 No list of recommended newsgroups available

2.2. LIST COUNTS

2.2.1. Usage

Here's the shape of it, bestie 💖

   Syntax
      LIST COUNTS [wildmat]

   Responses
      215    List of newsgroups follows (multi-line)

   Parameters
      wildmat    Groups of interest

2.2.2. Description 🎀

okay bestie, first things first: the general rules for every LIST command live in Section 7.6.1 of [RFC3977], so go check those too 📚

the LIST COUNTS command gives you back a list of the valid newsgroups the news server carries, along with some info about each one. that's the "counts list" 🦋 and honestly it's giving LIST ACTIVE energy ✨

the info comes back as a multi-line data block after the 215 response code, with one line per newsgroup. each line MUST consist of five fields, separated from each other by one or more spaces (the usual practice is a single space), in this order:

  • The name of the newsgroup.
  • The reported high water mark for the group.
  • The reported low water mark for the group.
  • The estimated number of articles in the group.
  • The current status of the group on this server.

the high and low water marks and the estimated number of articles work the same way as in the GROUP command (see Section 6.1.1 of [RFC3977]), but be careful 🙈 they're in the opposite order to the 211 response, which goes number low high group. the current status of the group works the way it does in the LIST ACTIVE command (see Section 7.6.3 of [RFC3977], as well as Section 3 of this document). also, just like LIST ACTIVE, TAB characters are not valid separators for LIST COUNTS 🚫

the order of newsgroups in the counts list is not significant 💅 the server doesn't have to keep returning the same order or the same results if you run this command more than once in a session 🌀

the same newsgroup SHOULD NOT appear twice in the output of this command. no duplicate groups, periodt 💀

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]). no skipping allowed, it's giving completeness 👑

the counts list MAY be empty. if the server does not maintain the information, a 503 response code MUST be returned. (lowkey, though, a news server that supports this command usually maintains the information anyway 🧚)

the client MAY use LIST COUNTS to get an estimate of the number of articles in every newsgroup the server carries, which lets it show that info to the end user 🌸 this is way simpler than sending a bunch of individual GROUP commands to get the same estimates. main character energy ✨

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] .

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 doesn't start with leading zeroes, but it 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 ✨

same deal as before: Section 7.6.1 of [RFC3977] has the general requirements for the LIST command 📚

a "distributions list" is maintained by some NNTP servers to hold the name of each distribution the news server knows about, plus a short description of what that distribution means 🍓 clients use distributions as possible 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). it's giving organization 💅

the info comes back as a multi-line data block after the 215 response code, with one line per distribution. each line 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 is its short description. there are no leading or trailing whitespaces in a line. the description MAY contain whitespaces 🫧

the order of distributions in the distributions list is not significant. the server doesn't have to return the same order or the same results if you use this command 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]. no exceptions, bestie 🌈

the distributions list is not newsgroup-based, so 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 build or top up a list of known distributions that it shows to the user 🦋 and 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]). it should also describe in the distributions list all the distributions present in the distrib.pats list, so the client can use both commands together. (naturally, the distributions list can also describe distributions that aren't in the distrib.pats list, because why not 🎀) the two commands don't need to return distributions in the same order, so don't panic if they don't match 😭

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 💖

Section 7.6.1 of [RFC3977] covers the general requirements for the LIST command, so check there too 📚

the "moderators list" is kept by some NNTP servers so clients know how the news server will generate a submission e-mail address when an article is posted locally to a moderated newsgroup 💌

the info comes back as a multi-line data block after 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 just be a simple newsgroup name), and the second field is the submission address template for newsgroups that match that wildmat. there are no leading or trailing whitespaces in a line. the submission template MAY contain colons (":") 🎀

the submission template is basically an e-mail address (see the definition of "addr-spec" in Section 3.4.1 of [RFC5322]), but with some special modifications 🧚 the case-sensitive string "%s" (%x25.73) MUST occur either zero or one time in the template. if there is going to be a literal % in the submission address, it MUST be written as "%%" in the template, even if it's not followed by an s. the character % MUST NOT occur in the submission template, except as part of "%s" or "%%". be careful with those percent signs, they're so picky 🙃

the order of lines in the moderators list IS significant: the first matching line is used. so specific patterns should be listed before general patterns, bestie 🔥 every moderated newsgroup name SHOULD be matched by at least one line in the list. this is often done with a default pattern at the bottom, but other approaches are fine too, and news server software MAY leave this up to the server administrator instead of enforcing it programmatically 🌸

when an article without an Approved header field is posted locally to a moderated newsgroup, the server generates a submission address from the matching submission template (that is, the second field of the first matching line in the moderators list). it does this 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). then any "%%" gets 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, so 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, so it's lowkey a rare vibe 🥹

2.4.3. Example

okay so here's what the output actually looks like 🎀

[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 table below shows a few moderated newsgroups and where their submissions go on a server whose moderators list is the one from the example above 💅

+-----------------------------+-------------------------------------+
| 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. 💀

2.5. LIST MOTD

2.5.1. Usage

Syntax

LIST MOTD

Responses

215    Information follows (multi-line)

2.5.2. Description

bestie, this one's a quick one ✨ See Section 7.6.1 of [RFC3977] for the general requirements that apply to every LIST command.

The "motd" is a "message of the day" that's relevant to the news server 🌸 It's basically how the news administrator chats with the news users. Stuff like an upcoming downtime or a shiny new facility on the server can be shared through LIST MOTD.

The info comes back as a multi-line data block right after the 215 response code. The text isn't guaranteed to follow any particular format, but like every multi-line data block, it is "dot-stuffed" 🧚

The server doesn't have to return the same thing if you run this command more than once in a session. It MAY indeed send a different message of the day depending on the state of the session. For example, on a mode-switching news server, the message can be different between transit mode and reader mode, or between an authenticated session and an unauthenticated one 🦋

The information MUST be in UTF-8 [RFC3629] 💜

The motd isn't newsgroup-based, so an argument MUST NOT be specified. If one is, the server MUST return a 501 response code 🙅‍♀️

The motd MAY be empty. If the server doesn't keep track of this information, a 503 response code MUST be returned.

It's up to the client to decide when and how the message gets shown to the user. No timestamp or last-modified date is provided programmatically, although the news administrator can put one in the text of the motd if they want. The client MAY cache a local copy or fingerprint of the motd so it only displays the message when it has changed ✨ If the client caches the information, it MAY take into account only the motd obtained after reaching the intended state of the session. Still, if a privacy extension is in use, the client MUST NOT cache any motd obtained before that extension took effect 🔥

NOTE: Even though the client MAY cache the results of this command, it MUST NOT rely on the correctness of any cached results, whether they're 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

here's the 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 <newsmaster@example.com>.
 [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

2.6.2. Description

ok this one is giving "starter pack" energy 🍓 See Section 7.6.1 of [RFC3977] for the general requirements of the LIST command.

The "subscriptions list" is kept by some NNTP servers to give the client a list of recommended newsgroups 💖

The info comes back as a multi-line data block after 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 matters here! The newsgroups are listed by importance, so the first one is 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. If you do send one, the response is limited to only the groups, if any, whose names match the wildmat. Heads up: the wildmat argument is a new feature in this specification, and servers that don't support CAPABILITIES, or don't advertise the SUBSCRIPTIONS keyword in the LIST capability (and so don't conform to this specification), are unlikely to support it 😬

The subscriptions list MAY be empty. If the server doesn't 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 to set up its initial list of default subscribed newsgroups. This list should therefore contain groups meant for new users on the news server or Usenet in general, like newsgroups for testing, support, announcements, or FAQs 🌈 The client MAY show the groups to the user in the order they appear in the list. When the subscriptions list is maintained and non-empty, the news client SHOULD use it instead of a hard-coded default list, if one exists ✨

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 part is short but important 🦋 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 💖

Okay so, the LIST ACTIVE command is defined in Section 7.6.3 of [RFC3977] 🎀. The fourth field of each line tells you the current status of the newsgroup named in the first field ✨. [RFC3977] already defines three status values:

  • y: Posting is permitted.
  • n: Posting is not permitted.
  • m: Postings will be forwarded to the newsgroup moderator.

This document adds three more case-sensitive status field values 🦋:

  • 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. Don't go making up your own vibes for them, bestie 🙅‍♀️.

A newsgroup with status x is basically a newsgroup with status n, except articles from peers are not accepted 💀. A newsgroup with status x is considered closed: no new articles will arrive in it. Meanwhile, 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 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 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 renaming a group or correcting 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. This means unapproved articles arriving from peers in an alias pointing to a moderated newsgroup are accepted and filed into that moderated newsgroup. Therefore, an alias SHOULD NOT point to a moderated newsgroup, since it allows bypassing of the moderation 🚨. Not cute, not cute.

An alias SHOULD NOT point to itself or to 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.

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 🧚.

3.2. Examples 🎀

Here's an 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 <for.misc.test@example.com>
   [S] 335 Send it; end with <CR-LF>.<CR-LF>
   [C] Path: demo!.POSTED.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: 18 Oct 2008 16:02:45 +0200
   [C] Organization: An example, Paris, FR.
   [C] Message-ID: <for.misc.test@example.com>
   [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 <for.misc.test@example.com>
   [S] 225 Header information follows
   [S] 0 news.example.com foo.bar:22
   [S] .
   [C] HDR Newsgroups <for.misc.test@example.com>
   [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 was originally posted to the newsgroup "misc.test". Yet it still propagates to peers that have been configured to receive articles posted to "misc.text" 🤭.

Here's an 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 <CR-LF>.<CR-LF>
   [C] From: "Demo User" <nobody@example.com>
   [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 <list-arguments>, 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 ✨

okay so this part extends two non-terminals, <newsgroup-status> and <list-content> 💅. Those are the bits that show what the LIST ACTIVE command sends back in its status field, and what the LIST command sends in its response contents. Here's the full syntax:

; 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 come with this extension 🫶. Everything you need is already covered in the core spec, [RFC3977].

Still, 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]. No cap, these are the rules to remember 💜.

6. Security Considerations 🔐

No new security considerations are introduced by this extension, bestie 💀. The stuff from the core spec [RFC3977] still applies, and so does the Netnews Architecture and Protocols spec [RFC5537]. The big ones to keep in mind are distribution leakage and e-mail Denial of Service during the moderation process 😭. Those are the security drama moments to watch out for.

7. IANA Considerations 📋

This section is the formal definition of this extension that the IANA registry needs, as required by Section 3.3.3 of [RFC3977]. It extends the LIST capability label that's defined in Section 7.6 of [RFC3977] 🎀.

  • This extension adds new keywords to the existing LIST capability from Section 7.6 of [RFC3977]. It also adds new status field values to the ACTIVE variant of the LIST command ✨.
  • The capability label being extended is "LIST" 🏷️.
  • This extension adds five optional arguments to the "LIST" capability label: "COUNTS", "DISTRIBUTIONS", "MODERATORS", "MOTD", and "SUBSCRIPTIONS". Each one shows which new LIST variant is supported. So this extension links those arguments to the existing "LIST" NNTP command 🔗.
  • This extension defines five new commands: LIST COUNTS, LIST DISTRIBUTIONS, LIST MODERATORS, LIST MOTD, and LIST SUBSCRIPTIONS. Their behaviour, arguments, and responses are in Sections 2.2, 2.3, 2.4, 2.5, and 2.6, in that order 🧚.
  • This extension doesn't link any new responses to existing NNTP commands 🙅‍♀️.
  • This extension doesn't change the maximum length of commands or initial response lines 📏.
  • This extension doesn't alter pipelining. The LIST COUNTS, LIST DISTRIBUTIONS, LIST MODERATORS, LIST MOTD, and LIST SUBSCRIPTIONS commands can all be pipelined 🦋.
  • Using this extension doesn't alter the capabilities list 📜.
  • This extension doesn't make any existing command produce a 401, 480, or 483 response 🙈.
  • The MODE READER command doesn't affect this extension at all 🌸.
  • Apart from the new commands, this extension doesn't change how a server or client overall behaves 💅.
  • Published Specification: This document.
  • Contact for Further Information: Author of this document.
  • Change Controller: IESG <iesg@ietf.org>.

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 especially like to thank Jeffrey M. Vinocur for rereading, improving, and patiently fixing the English wording and the quality of this document 👑.

Special thanks go 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 for 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 the author is also grateful to ⭐.

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.

[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/

That's the whole spec, bestie! 🌈✨ You made it through all five parts 🎀💜

📦 where this page comes from