GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


rfc:rfc6048

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

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

 This syntax extends the non-terminals <newsgroup-status> and
 <list-content>, 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 <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 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]

/data/webs/external/dokuwiki/data/pages/rfc/rfc6048.txt · Last modified: 2010/11/22 17:17 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki