doc/RFC3977
author František Kučera <franta-hg@frantovo.cz>
Mon Nov 07 17:47:10 2011 +0100 (2011-11-07)
changeset 118 ba7ea56fd672
parent 1 6fceb66e1ad7
permissions -rwxr-xr-x
drobnosti, TODO
     1 
     2 Network Working Group                                         C. Feather
     3 Request for Comments: 3977                                      THUS plc
     4 Obsoletes: 977                                              October 2006
     5 Updates: 2980
     6 Category: Standards Track
     7 
     8 
     9                  Network News Transfer Protocol (NNTP)
    10 
    11 Status of This Memo
    12 
    13    This document specifies an Internet standards track protocol for the
    14    Internet community, and requests discussion and suggestions for
    15    improvements.  Please refer to the current edition of the "Internet
    16    Official Protocol Standards" (STD 1) for the standardization state
    17    and status of this protocol.  Distribution of this memo is unlimited.
    18 
    19 Copyright Notice
    20 
    21    Copyright (C) The Internet Society (2006).
    22 
    23 Abstract
    24 
    25    The Network News Transfer Protocol (NNTP) has been in use in the
    26    Internet for a decade, and remains one of the most popular protocols
    27    (by volume) in use today.  This document is a replacement for
    28    RFC 977, and officially updates the protocol specification.  It
    29    clarifies some vagueness in RFC 977, includes some new base
    30    functionality, and provides a specific mechanism to add standardized
    31    extensions to NNTP.
    32 
    33 Table of Contents
    34 
    35    1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .  3
    36      1.1.  Author's Note . . . . . . . . . . . . . . . . . . . . . .  4
    37    2.  Notation  . . . . . . . . . . . . . . . . . . . . . . . . . .  5
    38    3.  Basic Concepts  . . . . . . . . . . . . . . . . . . . . . . .  6
    39      3.1.  Commands and Responses  . . . . . . . . . . . . . . . . .  6
    40        3.1.1.  Multi-line Data Blocks . . . . . . . . . . . . . . . . 8
    41      3.2.  Response Codes  . . . . . . . . . . . . . . . . . . . . .  9
    42        3.2.1.  Generic Response Codes  . . . . . . . . . . . . . . . 10
    43          3.2.1.1.  Examples  . . . . . . . . . . . . . . . . . . . . 12
    44      3.3.  Capabilities and Extensions . . . . . . . . . . . . . . . 14
    45        3.3.1.  Capability Descriptions . . . . . . . . . . . . . . . 14
    46        3.3.2.  Standard Capabilities . . . . . . . . . . . . . . . . 15
    47        3.3.3.  Extensions  . . . . . . . . . . . . . . . . . . . . . 16
    48        3.3.4.  Initial IANA Register . . . . . . . . . . . . . . . . 18
    49      3.4.  Mandatory and Optional Commands . . . . . . . . . . . . . 20
    50 
    51 
    52 
    53 Feather                     Standards Track                     [Page 1]
    54 
    55 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
    56 
    57 
    58        3.4.1.  Reading and Transit Servers . . . . . . . . . . . . . 21
    59        3.4.2.  Mode Switching  . . . . . . . . . . . . . . . . . . . 21
    60      3.5.  Pipelining  . . . . . . . . . . . . . . . . . . . . . . . 22
    61        3.5.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . 23
    62      3.6.  Articles  . . . . . . . . . . . . . . . . . . . . . . . . 24
    63    4.  The WILDMAT Format  . . . . . . . . . . . . . . . . . . . . . 25
    64      4.1.  Wildmat Syntax  . . . . . . . . . . . . . . . . . . . . . 26
    65      4.2.  Wildmat Semantics . . . . . . . . . . . . . . . . . . . . 26
    66      4.3.  Extensions  . . . . . . . . . . . . . . . . . . . . . . . 27
    67      4.4.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . 27
    68    5.  Session Administration Commands . . . . . . . . . . . . . . . 28
    69      5.1.  Initial Connection  . . . . . . . . . . . . . . . . . . . 28
    70      5.2.  CAPABILITIES  . . . . . . . . . . . . . . . . . . . . . . 29
    71      5.3.  MODE READER . . . . . . . . . . . . . . . . . . . . . . . 32
    72      5.4.  QUIT  . . . . . . . . . . . . . . . . . . . . . . . . . . 34
    73    6.  Article Posting and Retrieval . . . . . . . . . . . . . . . . 35
    74      6.1.  Group and Article Selection . . . . . . . . . . . . . . . 36
    75        6.1.1.  GROUP . . . . . . . . . . . . . . . . . . . . . . . . 36
    76        6.1.2.  LISTGROUP . . . . . . . . . . . . . . . . . . . . . . 39
    77        6.1.3.  LAST  . . . . . . . . . . . . . . . . . . . . . . . . 42
    78        6.1.4.  NEXT  . . . . . . . . . . . . . . . . . . . . . . . . 44
    79      6.2.  Retrieval of Articles and Article Sections  . . . . . . . 45
    80        6.2.1.  ARTICLE . . . . . . . . . . . . . . . . . . . . . . . 46
    81        6.2.2.  HEAD  . . . . . . . . . . . . . . . . . . . . . . . . 49
    82        6.2.3.  BODY  . . . . . . . . . . . . . . . . . . . . . . . . 51
    83        6.2.4.  STAT  . . . . . . . . . . . . . . . . . . . . . . . . 53
    84      6.3.  Article Posting . . . . . . . . . . . . . . . . . . . . . 56
    85        6.3.1.  POST  . . . . . . . . . . . . . . . . . . . . . . . . 56
    86        6.3.2.  IHAVE . . . . . . . . . . . . . . . . . . . . . . . . 58
    87    7.  Information Commands  . . . . . . . . . . . . . . . . . . . . 61
    88      7.1.  DATE  . . . . . . . . . . . . . . . . . . . . . . . . . . 61
    89      7.2.  HELP  . . . . . . . . . . . . . . . . . . . . . . . . . . 62
    90      7.3.  NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 63
    91      7.4.  NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 64
    92      7.5.  Time  . . . . . . . . . . . . . . . . . . . . . . . . . . 65
    93        7.5.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . 66
    94      7.6.  The LIST Commands . . . . . . . . . . . . . . . . . . . . 66
    95        7.6.1.  LIST  . . . . . . . . . . . . . . . . . . . . . . . . 67
    96        7.6.2.  Standard LIST Keywords  . . . . . . . . . . . . . . . 69
    97        7.6.3.  LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . 70
    98        7.6.4.  LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . 71
    99        7.6.5.  LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . 72
   100        7.6.6.  LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . 73
   101    8.  Article Field Access Commands . . . . . . . . . . . . . . . . 73
   102      8.1.  Article Metadata  . . . . . . . . . . . . . . . . . . . . 74
   103        8.1.1.  The :bytes Metadata Item  . . . . . . . . . . . . . . 74
   104        8.1.2.  The :lines Metadata Item  . . . . . . . . . . . . . . 75
   105      8.2.  Database Consistency  . . . . . . . . . . . . . . . . . . 75
   106 
   107 
   108 
   109 Feather                     Standards Track                     [Page 2]
   110 
   111 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   112 
   113 
   114      8.3.  OVER  . . . . . . . . . . . . . . . . . . . . . . . . . . 76
   115      8.4.  LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 81
   116      8.5.  HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
   117      8.6.  LIST HEADERS  . . . . . . . . . . . . . . . . . . . . . . 87
   118    9.  Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . . . 90
   119      9.1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . 90
   120      9.2.  Commands  . . . . . . . . . . . . . . . . . . . . . . . . 92
   121      9.3.  Command Continuation  . . . . . . . . . . . . . . . . . . 93
   122      9.4.  Responses . . . . . . . . . . . . . . . . . . . . . . . . 93
   123        9.4.1.  Generic Responses . . . . . . . . . . . . . . . . . . 93
   124        9.4.2.  Initial Response Line Contents  . . . . . . . . . . . 94
   125        9.4.3.  Multi-line Response Contents  . . . . . . . . . . . . 94
   126      9.5.  Capability Lines  . . . . . . . . . . . . . . . . . . . . 95
   127      9.6.  LIST Variants . . . . . . . . . . . . . . . . . . . . . . 96
   128      9.7.  Articles  . . . . . . . . . . . . . . . . . . . . . . . . 97
   129      9.8.  General Non-terminals . . . . . . . . . . . . . . . . . . 97
   130      9.9.  Extensions and Validation . . . . . . . . . . . . . . . . 99
   131    10. Internationalisation Considerations . . . . . . . . . . . . .100
   132      10.1. Introduction and Historical Situation . . . . . . . . . .100
   133      10.2. This Specification  . . . . . . . . . . . . . . . . . . .101
   134      10.3. Outstanding Issues  . . . . . . . . . . . . . . . . . . .102
   135    11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .103
   136    12. Security Considerations . . . . . . . . . . . . . . . . . . .103
   137      12.1. Personal and Proprietary Information  . . . . . . . . . .104
   138      12.2. Abuse of Server Log Information . . . . . . . . . . . . .104
   139      12.3. Weak Authentication and Access Control  . . . . . . . . .104
   140      12.4. DNS Spoofing  . . . . . . . . . . . . . . . . . . . . . .104
   141      12.5. UTF-8 Issues  . . . . . . . . . . . . . . . . . . . . . .105
   142      12.6. Caching of Capability Lists . . . . . . . . . . . . . . .106
   143    13. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .107
   144    14. References  . . . . . . . . . . . . . . . . . . . . . . . . .110
   145      14.1. Normative References  . . . . . . . . . . . . . . . . . .110
   146      14.2. Informative References  . . . . . . . . . . . . . . . . .110
   147    A.  Interaction with Other Specifications . . . . . . . . . . . .112
   148      A.1.  Header Folding  . . . . . . . . . . . . . . . . . . . . .112
   149      A.2.  Message-IDs . . . . . . . . . . . . . . . . . . . . . . .112
   150      A.3.  Article Posting . . . . . . . . . . . . . . . . . . . . .114
   151    B.  Summary of Commands . . . . . . . . . . . . . . . . . . . . .115
   152    C.  Summary of Response Codes . . . . . . . . . . . . . . . . . .117
   153    D.  Changes from RFC 977  . . . . . . . . . . . . . . . . . . . .121
   154 
   155 1.  Introduction
   156 
   157    This document specifies the Network News Transfer Protocol (NNTP),
   158    which is used for the distribution, inquiry, retrieval, and posting
   159    of Netnews articles using a reliable stream-based mechanism.  For
   160    news-reading clients, NNTP enables retrieval of news articles that
   161 
   162 
   163 
   164 
   165 Feather                     Standards Track                     [Page 3]
   166 
   167 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   168 
   169 
   170    are stored in a central database, giving subscribers the ability to
   171    select only those articles they wish to read.
   172 
   173    The Netnews model provides for indexing, cross-referencing, and
   174    expiration of aged messages.  NNTP is designed for efficient
   175    transmission of Netnews articles over a reliable full duplex
   176    communication channel.
   177 
   178    Although the protocol specification in this document is largely
   179    compatible with the version specified in RFC 977 [RFC977], a number
   180    of changes are summarised in Appendix D.  In particular:
   181 
   182    o  the default character set is changed from US-ASCII [ANSI1986] to
   183       UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8);
   184 
   185    o  a number of commands that were optional in RFC 977 or that have
   186       been taken from RFC 2980 [RFC2980] are now mandatory; and
   187 
   188    o  a CAPABILITIES command has been added to allow clients to
   189       determine what functionality is available from a server.
   190 
   191    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   192    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   193    document are to be interpreted as described in RFC 2119 [RFC2119].
   194 
   195    An implementation is not compliant if it fails to satisfy one or more
   196    of the MUST requirements for this protocol.  An implementation that
   197    satisfies all the MUST and all the SHOULD requirements for its
   198    protocols is said to be "unconditionally compliant"; one that
   199    satisfies all the MUST requirements but not all the SHOULD
   200    requirements for NNTP is said to be "conditionally compliant".
   201 
   202    For the remainder of this document, the terms "client" and "client
   203    host" refer to a host making use of the NNTP service, while the terms
   204    "server" and "server host" refer to a host that offers the NNTP
   205    service.
   206 
   207 1.1.  Author's Note
   208 
   209    This document is written in XML using an NNTP-specific DTD.  Custom
   210    software is used to convert this to RFC 2629 [RFC2629] format, and
   211    then the public "xml2rfc" package to further reduce this to text,
   212    nroff source, and HTML.
   213 
   214    No perl was used in producing this document.
   215 
   216 
   217 
   218 
   219 
   220 
   221 Feather                     Standards Track                     [Page 4]
   222 
   223 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   224 
   225 
   226 2.  Notation
   227 
   228    The following notational conventions are used in this document.
   229 
   230      UPPERCASE     indicates literal text to be included in the
   231                    command.
   232 
   233      lowercase     indicates a token described elsewhere.
   234 
   235      [brackets]    indicate that the enclosed material is optional.
   236 
   237      elliptical    indicates that the argument may be repeated any
   238      ... marks     number of times (it must occur at least once).
   239 
   240      vertical|bar  indicates a choice of two mutually exclusive
   241                    arguments (exactly one must be provided).
   242 
   243    The name "message-id" for a command or response argument indicates
   244    that it is the message-id of an article as described in Section 3.6,
   245    including the angle brackets.
   246 
   247    The name "wildmat" for an argument indicates that it is a wildmat as
   248    defined in Section 4.  If the argument does not meet the requirements
   249    of that section (for example, if it does not fit the grammar of
   250    Section 4.1), the NNTP server MAY place some interpretation on it
   251    (not specified by this document) or otherwise MUST treat it as a
   252    syntax error.
   253 
   254    Responses for each command will be described in tables listing the
   255    required format of a response followed by the meaning that should be
   256    ascribed to that response.
   257 
   258    The terms "NUL", "TAB", "LF", "CR, and "space" refer to the octets
   259    %x00, %x09, %x0A, %x0D, and %x20, respectively (that is, the octets
   260    with those codes in US-ASCII [ANSI1986] and thus in UTF-8 [RFC3629]).
   261    The term "CRLF" or "CRLF pair" means the sequence CR immediately
   262    followed by LF (that is, %x0D.0A).  A "printable US-ASCII character"
   263    is an octet in the range %x21-7E.  Quoted characters refer to the
   264    octets with those codes in US-ASCII (so "." and "<" refer to %x2E and
   265    %x3C) and will always be printable US-ASCII characters; similarly,
   266    "digit" refers to the octets %x30-39.
   267 
   268    A "keyword" MUST consist only of US-ASCII letters, digits, and the
   269    characters dot (".") and dash ("-") and MUST begin with a letter.
   270    Keywords MUST be at least three characters in length.
   271 
   272 
   273 
   274 
   275 
   276 
   277 Feather                     Standards Track                     [Page 5]
   278 
   279 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   280 
   281 
   282    Examples in this document are not normative but serve to illustrate
   283    usages, arguments, and responses.  In the examples, a "[C]" will be
   284    used to represent the client host and an "[S]" will be used to
   285    represent the server host.  Most of the examples do not rely on a
   286    particular server state.  In some cases, however, they do assume that
   287    the currently selected newsgroup (see the GROUP command,
   288    Section 6.1.1) is invalid; when so, this is indicated at the start of
   289    the example.  Examples may use commands or other keywords not defined
   290    in this specification (such as an XENCRYPT command).  These will be
   291    used to illustrate some point and do not imply that any such command
   292    is defined elsewhere or needs to exist in any particular
   293    implementation.
   294 
   295    Terms that might be read as specifying details of a client or server
   296    implementation, such as "database", are used simply to ease
   297    description.  Provided that implementations conform to the protocol
   298    and format specifications in this document, no specific technique is
   299    mandated.
   300 
   301 3.  Basic Concepts
   302 
   303 3.1.  Commands and Responses
   304 
   305    NNTP operates over any reliable bi-directional 8-bit-wide data stream
   306    channel.  When the connection is established, the NNTP server host
   307    MUST send a greeting.  The client host and server host then exchange
   308    commands and responses (respectively) until the connection is closed
   309    or aborted.  If the connection used is TCP, then the server host
   310    starts the NNTP service by listening on a TCP port.  When a client
   311    host wishes to make use of the service, it MUST establish a TCP
   312    connection with the server host by connecting to that host on the
   313    same port on which the server is listening.
   314 
   315    The character set for all NNTP commands is UTF-8 [RFC3629].  Commands
   316    in NNTP MUST consist of a keyword, which MAY be followed by one or
   317    more arguments.  A CRLF pair MUST terminate all commands.  Multiple
   318    commands MUST NOT be on the same line.  Unless otherwise noted
   319    elsewhere in this document, arguments SHOULD consist of printable US-
   320    ASCII characters.  Keywords and arguments MUST each be separated by
   321    one or more space or TAB characters.  Command lines MUST NOT exceed
   322    512 octets, which includes the terminating CRLF pair.  The arguments
   323    MUST NOT exceed 497 octets.  A server MAY relax these limits for
   324    commands defined in an extension.
   325 
   326    Where this specification permits UTF-8 characters outside the range
   327    of U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark
   328    (U+FEFF, encoding %xEF.BB.BF) and MUST use the Word Joiner (U+2060,
   329    encoding %xE2.91.A0) for the meaning Zero Width No-Break Space in
   330 
   331 
   332 
   333 Feather                     Standards Track                     [Page 6]
   334 
   335 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   336 
   337 
   338    command lines and the initial lines of responses.  Implementations
   339    SHOULD apply these same principles throughout.
   340 
   341    The term "character" means a single Unicode code point.
   342    Implementations are not required to carry out Unicode normalisation.
   343    Thus, U+0084 (A-dieresis) is one character, while U+0041 U+0308 (A
   344    composed with dieresis) is two; the two need not be treated as
   345    equivalent.
   346 
   347    Commands may have variants; if so, they use a second keyword
   348    immediately after the first to indicate which variant is required.
   349    The only such commands in this specification are LIST and MODE.  Note
   350    that such variants are sometimes referred to as if they were commands
   351    in their own right: "the LIST ACTIVE" command should be read as
   352    shorthand for "the ACTIVE variant of the LIST command".
   353 
   354    Keywords are case insensitive; the case of keywords for commands MUST
   355    be ignored by the server.  Command and response arguments are case or
   356    language specific only when stated, either in this document or in
   357    other relevant specifications.
   358 
   359    In some cases, a command involves more data than just a single line.
   360    The further data may be sent either immediately after the command
   361    line (there are no instances of this in this specification, but there
   362    are in extensions such as [NNTP-STREAM]) or following a request from
   363    the server (indicated by a 3xx response).
   364 
   365    Each response MUST start with a three-digit response code that is
   366    sufficient to distinguish all responses.  Certain valid responses are
   367    defined to be multi-line; for all others, the response is contained
   368    in a single line.  The initial line of the response MUST NOT exceed
   369    512 octets, which includes the response code and the terminating CRLF
   370    pair; an extension MAY specify a greater maximum for commands that it
   371    defines, but not for any other command.  Single-line responses
   372    consist of an initial line only.  Multi-line responses consist of an
   373    initial line followed by a multi-line data block.
   374 
   375    An NNTP server MAY have an inactivity autologout timer.  Such a timer
   376    SHOULD be of at least three minutes' duration, with the exception
   377    that there MAY be a shorter limit on how long the server is willing
   378    to wait for the first command from the client.  The receipt of any
   379    command from the client during the timer interval SHOULD suffice to
   380    reset the autologout timer.  Similarly, the receipt of any
   381    significant amount of data from a client that is sending a multi-line
   382    data block (such as during a POST or IHAVE command) SHOULD suffice to
   383    reset the autologout timer.  When the timer expires, the server
   384    SHOULD close the connection without sending any response to the
   385    client.
   386 
   387 
   388 
   389 Feather                     Standards Track                     [Page 7]
   390 
   391 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   392 
   393 
   394 3.1.1.  Multi-line Data Blocks
   395 
   396    A multi-line data block is used in certain commands and responses.
   397    It MUST adhere to the following rules:
   398 
   399    1.  The block consists of a sequence of zero or more "lines", each
   400        being a stream of octets ending with a CRLF pair.  Apart from
   401        those line endings, the stream MUST NOT include the octets NUL,
   402        LF, or CR.
   403 
   404    2.  In a multi-line response, the block immediately follows the CRLF
   405        at the end of the initial line of the response.  When used in any
   406        other context, the specific command will define when the block is
   407        sent.
   408 
   409    3.  If any line of the data block begins with the "termination octet"
   410        ("." or %x2E), that line MUST be "dot-stuffed" by prepending an
   411        additional termination octet to that line of the block.
   412 
   413    4.  The lines of the block MUST be followed by a terminating line
   414        consisting of a single termination octet followed by a CRLF pair
   415        in the normal way.  Thus, unless it is empty, a multi-line block
   416        is always terminated with the five octets CRLF "." CRLF
   417        (%x0D.0A.2E.0D.0A).
   418 
   419    5.  When a multi-line block is interpreted, the "dot-stuffing" MUST
   420        be undone; i.e., the recipient MUST ensure that, in any line
   421        beginning with the termination octet followed by octets other
   422        than a CRLF pair, that initial termination octet is disregarded.
   423 
   424    6.  Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT
   425        be considered part of the multi-line block; i.e., the recipient
   426        MUST ensure that any line beginning with the termination octet
   427        followed immediately by a CRLF pair is disregarded.  (The first
   428        CRLF pair of the terminating CRLF "." CRLF of a non-empty block
   429        is, of course, part of the last line of the block.)
   430 
   431    Note that texts using an encoding (such as UTF-16 or UTF-32) that may
   432    contain the octets NUL, LF, or CR other than a CRLF pair cannot be
   433    reliably conveyed in the above format (that is, they violate the MUST
   434    requirement above).  However, except when stated otherwise, this
   435    specification does not require the content to be UTF-8, and therefore
   436    (subject to that same requirement) it MAY include octets above and
   437    below 128 mixed arbitrarily.
   438 
   439    This document does not place any limit on the length of a line in a
   440    multi-line block.  However, the standards that define the format of
   441    articles may do so.
   442 
   443 
   444 
   445 Feather                     Standards Track                     [Page 8]
   446 
   447 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   448 
   449 
   450 3.2.  Response Codes
   451 
   452    Each response MUST begin with a three-digit status indicator.  These
   453    are status reports from the server and indicate the response to the
   454    last command received from the client.
   455 
   456    The first digit of the response broadly indicates the success,
   457    failure, or progress of the previous command:
   458 
   459       1xx - Informative message
   460       2xx - Command completed OK
   461       3xx - Command OK so far; send the rest of it
   462       4xx - Command was syntactically correct but failed for some reason
   463       5xx - Command unknown, unsupported, unavailable, or syntax error
   464 
   465    The next digit in the code indicates the function response category:
   466 
   467       x0x - Connection, setup, and miscellaneous messages
   468       x1x - Newsgroup selection
   469       x2x - Article selection
   470       x3x - Distribution functions
   471       x4x - Posting
   472       x8x - Reserved for authentication and privacy extensions
   473       x9x - Reserved for private use (non-standard extensions)
   474 
   475    Certain responses contain arguments such as numbers and names in
   476    addition to the status indicator.  In those cases, to simplify
   477    interpretation by the client, the number and type of such arguments
   478    is fixed for each response code, as is whether the code is
   479    single-line or multi-line.  Any extension MUST follow this principle
   480    as well.  Note that, for historical reasons, the 211 response code is
   481    an exception to this in that the response may be single-line or
   482    multi-line depending on the command (GROUP or LISTGROUP) that
   483    generated it.  In all other cases, the client MUST only use the
   484    status indicator itself to determine the nature of the response.  The
   485    exact response codes that can be returned by any given command are
   486    detailed in the description of that command.
   487 
   488    Arguments MUST be separated from the numeric status indicator and
   489    from each other by a single space.  All numeric arguments MUST be in
   490    base 10 (decimal) format and MAY have leading zeros.  String
   491    arguments MUST contain at least one character and MUST NOT contain
   492    TAB, LF, CR, or space.  The server MAY add any text after the
   493    response code or last argument, as appropriate, and the client MUST
   494    NOT make decisions based on this text.  Such text MUST be separated
   495    from the numeric status indicator or the last argument by at least
   496    one space.
   497 
   498 
   499 
   500 
   501 Feather                     Standards Track                     [Page 9]
   502 
   503 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   504 
   505 
   506    The server MUST respond to any command with the appropriate generic
   507    response (given in Section 3.2.1) if it represents the situation.
   508    Otherwise, each recognized command MUST return one of the response
   509    codes specifically listed in its description or in an extension.  A
   510    server MAY provide extensions to this specification, including new
   511    commands, new variants or features of existing commands, and other
   512    ways of changing the internal state of the server.  However, the
   513    server MUST NOT produce any other responses to a client that does not
   514    invoke any of the additional features.  (Therefore, a client that
   515    restricts itself to this specification will only receive the
   516    responses that are listed.)
   517 
   518    If a client receives an unexpected response, it SHOULD use the first
   519    digit of the response to determine the result.  For example, an
   520    unexpected 2xx should be taken as success, and an unexpected 4xx or
   521    5xx as failure.
   522 
   523    Response codes not specified in this document MAY be used for any
   524    installation-specific additional commands also not specified.  These
   525    SHOULD be chosen to fit the pattern of x9x specified above.
   526 
   527    Neither this document nor any registered extension (see
   528    Section 3.3.3) will specify any response codes of the x9x pattern.
   529    (Implementers of extensions are accordingly cautioned not to use such
   530    responses for extensions that may subsequently be submitted for
   531    registration.)
   532 
   533 3.2.1.  Generic Response Codes
   534 
   535    The server MUST respond to any command with the appropriate one of
   536    the following generic responses if it represents the situation.
   537 
   538    If the command is not recognized, or if it is an optional command
   539    that is not implemented by the server, the response code 500 MUST be
   540    returned.
   541 
   542    If there is a syntax error in the arguments of a recognized command,
   543    including the case where more arguments are provided than the command
   544    specifies or the command line is longer than the server accepts, the
   545    response code 501 MUST be returned.  The line MUST NOT be truncated
   546    or split and then interpreted.  Note that where a command has
   547    variants depending on a second keyword (e.g., LIST ACTIVE and LIST
   548    NEWSGROUPS), 501 MUST be used when the base command is implemented
   549    but the requested variant is not, and 500 MUST be used only when the
   550    base command itself is not implemented.
   551 
   552    If an argument is required to be a base64-encoded string [RFC4648]
   553    (there are no such arguments in this specification, but there may be
   554 
   555 
   556 
   557 Feather                     Standards Track                    [Page 10]
   558 
   559 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   560 
   561 
   562    in extensions) and is not validly encoded, the response code 504 MUST
   563    be returned.
   564 
   565    If the server experiences an internal fault or problem that means it
   566    is unable to carry out the command (for example, a necessary file is
   567    missing or a necessary service could not be contacted), the response
   568    code 403 MUST be returned.  If the server recognizes the command but
   569    does not provide an optional feature (for example, because it does
   570    not store the required information), or if it only handles a subset
   571    of legitimate cases (see the HDR command, Section 8.5, for an
   572    example), the response code 503 MUST be returned.
   573 
   574    If the client is not authorized to use the specified facility when
   575    the server is in its current state, then the appropriate one of the
   576    following response codes MUST be used.
   577 
   578    502: It is necessary to terminate the connection and to start a new
   579       one with the appropriate authority before the command can be used.
   580       Historically, some mode-switching servers (see Section 3.4.1) used
   581       this response to indicate that this command will become available
   582       after the MODE READER command (Section 5.3) is used, but this
   583       usage does not conform to this specification and MUST NOT be used.
   584       Note that the server MUST NOT close the connection immediately
   585       after a 502 response except at the initial connection
   586       (Section 5.1) and with the MODE READER command.
   587 
   588    480: The client must authenticate itself to the server (that is, it
   589       must provide information as to the identity of the client) before
   590       the facility can be used on this connection.  This will involve
   591       the use of an authentication extension such as [NNTP-AUTH].
   592 
   593    483: The client must negotiate appropriate privacy protection on the
   594       connection.  This will involve the use of a privacy extension such
   595       as [NNTP-TLS].
   596 
   597    401: The client must change the state of the connection in some other
   598       manner.  The first argument of the response MUST be the capability
   599       label (see Section 5.2) of the facility that provides the
   600       necessary mechanism (usually an extension, which may be a private
   601       extension).  The server MUST NOT use this response code except as
   602       specified by the definition of the capability in question.
   603 
   604    If the server has to terminate the connection for some reason, it
   605    MUST give a 400 response code to the next command and then
   606    immediately close the connection.  Following a 400 response, clients
   607    SHOULD NOT simply reconnect immediately and retry the same actions.
   608    Rather, a client SHOULD either use an exponentially increasing delay
   609    between retries (e.g., double the waiting time after each 400
   610 
   611 
   612 
   613 Feather                     Standards Track                    [Page 11]
   614 
   615 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   616 
   617 
   618    response) or present any associated text to the user for them to
   619    decide whether and when to retry.
   620 
   621    The client MUST be prepared to receive any of these responses for any
   622    command (except, of course, that the server MUST NOT generate a 500
   623    response code for mandatory commands).
   624 
   625 3.2.1.1.  Examples
   626 
   627    Example of an unknown command:
   628 
   629       [C] MAIL
   630       [S] 500 Unknown command
   631 
   632    Example of an unsupported command:
   633 
   634       [C] CAPABILITIES
   635       [S] 101 Capability list:
   636       [S] VERSION 2
   637       [S] READER
   638       [S] NEWNEWS
   639       [S] LIST ACTIVE NEWSGROUPS
   640       [S] .
   641       [C] OVER
   642       [S] 500 Unknown command
   643 
   644    Example of an unsupported variant:
   645 
   646       [C] MODE POSTER
   647       [S] 501 Unknown MODE option
   648 
   649    Example of a syntax error:
   650 
   651       [C] ARTICLE a.message.id@no.angle.brackets
   652       [S] 501 Syntax error
   653 
   654    Example of an overlong command line:
   655 
   656       [C] HEAD 53 54 55
   657       [S] 501 Too many arguments
   658 
   659    Example of a bad wildmat:
   660 
   661       [C] LIST ACTIVE u[ks].*
   662       [S] 501 Syntax error
   663 
   664 
   665 
   666 
   667 
   668 
   669 Feather                     Standards Track                    [Page 12]
   670 
   671 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   672 
   673 
   674    Example of a base64-encoding error (the second argument is meant to
   675    be base64 encoded):
   676 
   677       [C] XENCRYPT RSA abcd=efg
   678       [S] 504 Base64 encoding error
   679 
   680    Example of an attempt to access a facility not available to this
   681    connection:
   682 
   683       [C] MODE READER
   684       [S] 200 Reader mode, posting permitted
   685       [C] IHAVE <i.am.an.article.you.will.want@example.com>
   686       [S] 500 Permission denied
   687 
   688    Example of an attempt to access a facility requiring authentication:
   689 
   690       [C] GROUP secret.group
   691       [S] 480 Permission denied
   692 
   693    Example of a successful attempt following such authentication:
   694 
   695       [C] XSECRET fred flintstone
   696       [S] 290 Password for fred accepted
   697       [C] GROUP secret.group
   698       [S] 211 5 1 20 secret.group selected
   699 
   700    Example of an attempt to access a facility requiring privacy:
   701 
   702       [C] GROUP secret.group
   703       [S] 483 Secure connection required
   704       [C] XENCRYPT
   705       [Client and server negotiate encryption on the link]
   706       [S] 283 Encrypted link established
   707       [C] GROUP secret.group
   708       [S] 211 5 1 20 secret.group selected
   709 
   710    Example of a need to change mode before a facility is used:
   711 
   712       [C] GROUP binary.group
   713       [S] 401 XHOST Not on this virtual host
   714       [C] XHOST binary.news.example.org
   715       [S] 290 binary.news.example.org virtual host selected
   716       [C] GROUP binary.group
   717       [S] 211 5 1 77 binary.group selected
   718 
   719 
   720 
   721 
   722 
   723 
   724 
   725 Feather                     Standards Track                    [Page 13]
   726 
   727 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   728 
   729 
   730    Example of a temporary failure:
   731 
   732       [C] GROUP archive.local
   733       [S] 403 Archive server temporarily offline
   734 
   735    Example of the server needing to close down immediately:
   736 
   737       [C] ARTICLE 123
   738       [S] 400 Power supply failed, running on UPS
   739       [Server closes connection.]
   740 
   741 3.3.  Capabilities and Extensions
   742 
   743    Not all NNTP servers provide exactly the same facilities, both
   744    because this specification allows variation and because servers may
   745    provide extensions.  A set of facilities that are related are called
   746    a "capability".  This specification provides a way to determine what
   747    capabilities are available, includes a list of standard capabilities,
   748    and includes a mechanism (the extension mechanism) for defining new
   749    capabilities.
   750 
   751 3.3.1.  Capability Descriptions
   752 
   753    A client can determine the available capabilities of the server by
   754    using the CAPABILITIES command (Section 5.2).  This returns a
   755    capability list, which is a list of capability lines.  Each line
   756    describes one available capability.
   757 
   758    Each capability line consists of one or more tokens, which MUST be
   759    separated by one or more space or TAB characters.  A token is a
   760    string of 1 or more printable UTF-8 characters (that is, either
   761    printable US-ASCII characters or any UTF-8 sequence outside the US-
   762    ASCII range, but not space or TAB).  Unless stated otherwise, tokens
   763    are case insensitive.  Each capability line consists of the
   764    following:
   765 
   766    o  The capability label, which is a keyword indicating the
   767       capability.  A capability label may be defined by this
   768       specification or a successor, or by an extension.
   769 
   770    o  The label is then followed by zero or more tokens, which are
   771       arguments of the capability.  The form and meaning of these tokens
   772       is specific to each capability.
   773 
   774    The server MUST ensure that the capability list accurately reflects
   775    the capabilities (including extensions) currently available.  If a
   776    capability is only available with the server in a certain state (for
   777    example, only after authentication), the list MUST only include the
   778 
   779 
   780 
   781 Feather                     Standards Track                    [Page 14]
   782 
   783 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   784 
   785 
   786    capability label when the server is in that state.  Similarly, if
   787    only some of the commands in an extension will be available, or if
   788    the behaviour of the extension will change in some other manner,
   789    according to the state of the server, this MUST be indicated by
   790    different arguments in the capability line.
   791 
   792    Note that a capability line can only begin with a letter.  Lines
   793    beginning with other characters are reserved for future versions of
   794    this specification.  In order to interoperate with such versions,
   795    clients MUST be prepared to receive lines beginning with other
   796    characters and MUST ignore any they do not understand.
   797 
   798 3.3.2.  Standard Capabilities
   799 
   800    The following capabilities are defined by this specification.
   801 
   802    VERSION
   803       This capability MUST be advertised by all servers and MUST be the
   804       first capability in the capability list; it indicates the
   805       version(s) of NNTP that the server supports.  There must be at
   806       least one argument; each argument is a decimal number and MUST NOT
   807       have a leading zero.  Version numbers are assigned only in RFCs
   808       that update or replace this specification; servers MUST NOT create
   809       their own version numbers.
   810 
   811       The version number of this specification is 2.
   812 
   813    READER
   814       This capability indicates that the server implements the various
   815       commands useful for reading clients.
   816 
   817    IHAVE
   818       This capability indicates that the server implements the IHAVE
   819       command.
   820 
   821    POST
   822       This capability indicates that the server implements the POST
   823       command.
   824 
   825    NEWNEWS
   826       This capability indicates that the server implements the NEWNEWS
   827       command.
   828 
   829    HDR
   830       This capability indicates that the server implements the header
   831       access commands (HDR and LIST HEADERS).
   832 
   833 
   834 
   835 
   836 
   837 Feather                     Standards Track                    [Page 15]
   838 
   839 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   840 
   841 
   842    OVER
   843       This capability indicates that the server implements the overview
   844       access commands (OVER and LIST OVERVIEW.FMT).  If and only if the
   845       server supports the message-id form of the OVER command, there
   846       must be a single argument MSGID.
   847 
   848    LIST
   849       This capability indicates that the server implements at least one
   850       variant of the LIST command.  There MUST be one argument for each
   851       variant of the LIST command supported by the server, giving the
   852       keyword for that variant.
   853 
   854    IMPLEMENTATION
   855       This capability MAY be provided by a server.  If so, the arguments
   856       SHOULD be used to provide information such as the server software
   857       name and version number.  The client MUST NOT use this line to
   858       determine capabilities of the server.  (While servers often
   859       provide this information in the initial greeting, clients need to
   860       guess whether this is the case; this capability makes it clear
   861       what the information is.)
   862 
   863    MODE-READER
   864       This capability indicates that the server is mode-switching
   865       (Section 3.4.2) and that the MODE READER command needs to be used
   866       to enable the READER capability.
   867 
   868 3.3.3.  Extensions
   869 
   870    Although NNTP is widely and robustly deployed, some parts of the
   871    Internet community might wish to extend the NNTP service.  It must be
   872    emphasized that any extension to NNTP should not be considered
   873    lightly.  NNTP's strength comes primarily from its simplicity.
   874    Experience with many protocols has shown that:
   875 
   876       Protocols with few options tend towards ubiquity, whilst protocols
   877       with many options tend towards obscurity.
   878 
   879    This means that each and every extension, regardless of its benefits,
   880    must be carefully scrutinized with respect to its implementation,
   881    deployment, and interoperability costs.  In many cases, the cost of
   882    extending the NNTP service will likely outweigh the benefit.
   883 
   884    An extension is a package of associated facilities, often but not
   885    always including one or more new commands.  Each extension MUST
   886    define at least one new capability label (this will often, but need
   887    not, be the name of one of these new commands).  While any additional
   888    capability information can normally be specified using arguments to
   889 
   890 
   891 
   892 
   893 Feather                     Standards Track                    [Page 16]
   894 
   895 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   896 
   897 
   898    that label, an extension MAY define more than one capability label.
   899    However, this SHOULD be limited to exceptional circumstances.
   900 
   901    An extension is either a private extension, or its capabilities are
   902    included in the IANA registry of capabilities (see Section 3.3.4) and
   903    it is defined in an RFC (in which case it is a "registered
   904    extension").  Such RFCs either must be on the standards track or must
   905    define an IESG-approved experimental protocol.
   906 
   907    The definition of an extension must include the following:
   908 
   909    o  a descriptive name for the extension.
   910 
   911    o  the capability label or labels defined by the extension (the
   912       capability label of a registered extension MUST NOT begin with
   913       "X").
   914 
   915    o  The syntax, values, and meanings of any arguments for each
   916       capability label defined by the extension.
   917 
   918    o  Any new NNTP commands associated with the extension (the names of
   919       commands associated with registered extensions MUST NOT begin with
   920       "X").
   921 
   922    o  The syntax and possible values of arguments associated with the
   923       new NNTP commands.
   924 
   925    o  The response codes and possible values of arguments for the
   926       responses of the new NNTP commands.
   927 
   928    o  Any new arguments the extension associates with any other
   929       pre-existing NNTP commands.
   930 
   931    o  Any increase in the maximum length of commands and initial
   932       response lines over the value specified in this document.
   933 
   934    o  A specific statement about the effect on pipelining that this
   935       extension may have (if any).
   936 
   937    o  A specific statement about the circumstances when use of this
   938       extension can alter the contents of the capabilities list (other
   939       than the new capability labels it defines).
   940 
   941    o  A specific statement about the circumstances under which the
   942       extension can cause any pre-existing command to produce a 401,
   943       480, or 483 response.
   944 
   945 
   946 
   947 
   948 
   949 Feather                     Standards Track                    [Page 17]
   950 
   951 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   952 
   953 
   954    o  A description of how the use of MODE READER on a mode-switching
   955       server interacts with the extension.
   956 
   957    o  A description of how support for the extension affects the
   958       behaviour of a server and NNTP client in any other manner not
   959       outlined above.
   960 
   961    o  Formal syntax as described in Section 9.9.
   962 
   963    A private extension MAY or MAY NOT be included in the capabilities
   964    list.  If it is, the capability label MUST begin with "X".  A server
   965    MAY provide additional keywords (for new commands and also for new
   966    variants of existing commands) as part of a private extension.  To
   967    avoid the risk of a clash with a future registered extension, these
   968    keywords SHOULD begin with "X".
   969 
   970    If the server advertises a capability defined by a registered
   971    extension, it MUST implement the extension so as to fully conform
   972    with the specification (for example, it MUST implement all the
   973    commands that the extension describes as mandatory).  If it does not
   974    implement the extension as specified, it MUST NOT list the extension
   975    in the capabilities list under its registered name.  In that case, it
   976    MAY, but SHOULD NOT, provide a private extension (not listed, or
   977    listed with a different name) that implements part of the extension
   978    or implements the commands of the extension with a different meaning.
   979 
   980    A server MUST NOT send different response codes to basic NNTP
   981    commands documented here or to commands documented in registered
   982    extensions in response to the availability or use of a private
   983    extension.
   984 
   985 3.3.4.  Initial IANA Register
   986 
   987    IANA will maintain a registry of NNTP capability labels.  All
   988    capability labels in the registry MUST be keywords and MUST NOT begin
   989    with X.
   990 
   991 
   992 
   993 
   994 
   995 
   996 
   997 
   998 
   999 
  1000 
  1001 
  1002 
  1003 
  1004 
  1005 Feather                     Standards Track                    [Page 18]
  1006 
  1007 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1008 
  1009 
  1010    The initial content of the registry consists of these entries:
  1011 
  1012    +-------------------+--------------------------+--------------------+
  1013    | Label             | Meaning                  | Definition         |
  1014    +-------------------+--------------------------+--------------------+
  1015    | AUTHINFO          | Authentication           | [NNTP-AUTH]        |
  1016    |                   |                          |                    |
  1017    | HDR               | Batched header retrieval | Section 3.3.2,     |
  1018    |                   |                          | Section 8.5, and   |
  1019    |                   |                          | Section 8.6        |
  1020    |                   |                          |                    |
  1021    | IHAVE             | IHAVE command available  | Section 3.3.2 and  |
  1022    |                   |                          | Section 6.3.2      |
  1023    |                   |                          |                    |
  1024    | IMPLEMENTATION    | Server                   | Section 3.3.2      |
  1025    |                   | implementation-specific  |                    |
  1026    |                   | information              |                    |
  1027    |                   |                          |                    |
  1028    | LIST              | LIST command variants    | Section 3.3.2 and  |
  1029    |                   |                          | Section 7.6.1      |
  1030    |                   |                          |                    |
  1031    | MODE-READER       | Mode-switching server    | Section 3.4.2      |
  1032    |                   | and MODE READER command  |                    |
  1033    |                   | available                |                    |
  1034    |                   |                          |                    |
  1035    | NEWNEWS           | NEWNEWS command          | Section 3.3.2 and  |
  1036    |                   | available                | Section 7.4        |
  1037    |                   |                          |                    |
  1038    | OVER              | Overview support         | Section 3.3.2,     |
  1039    |                   |                          | Section 8.3, and   |
  1040    |                   |                          | Section 8.4        |
  1041    |                   |                          |                    |
  1042    | POST              | POST command available   | Section 3.3.2 and  |
  1043    |                   |                          | Section 6.3.1      |
  1044    |                   |                          |                    |
  1045    | READER            | Reader commands          | Section 3.3.2      |
  1046    |                   | available                |                    |
  1047    |                   |                          |                    |
  1048    | SASL              | Supported SASL           | [NNTP-AUTH]        |
  1049    |                   | mechanisms               |                    |
  1050    |                   |                          |                    |
  1051    | STARTTLS          | Transport layer security | [NNTP-TLS]         |
  1052    |                   |                          |                    |
  1053    | STREAMING         | Streaming feeds          | [NNTP-STREAM]      |
  1054    |                   |                          |                    |
  1055    | VERSION           | Supported NNTP versions  | Section 3.3.2      |
  1056    +-------------------+--------------------------+--------------------+
  1057 
  1058 
  1059 
  1060 
  1061 Feather                     Standards Track                    [Page 19]
  1062 
  1063 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1064 
  1065 
  1066 3.4.  Mandatory and Optional Commands
  1067 
  1068    For a number of reasons, not all the commands in this specification
  1069    are mandatory.  However, it is equally undesirable for every command
  1070    to be optional, since this means that a client will have no idea what
  1071    facilities are available.  Therefore, as a compromise, some of the
  1072    commands in this specification are mandatory (they must be supported
  1073    by all servers) while the remainder are not.  The latter are then
  1074    subdivided into bundles, each indicated by a single capability label.
  1075 
  1076    o  If the label is included in the capability list returned by the
  1077       server, the server MUST support all commands in that bundle.
  1078 
  1079    o  If the label is not included, the server MAY support none or some
  1080       of the commands but SHOULD NOT support all of them.  In general,
  1081       there will be no way for a client to determine which commands are
  1082       supported without trying them.
  1083 
  1084    The bundles have been chosen to provide useful functionality, and
  1085    therefore server authors are discouraged from implementing only part
  1086    of a bundle.
  1087 
  1088    The description of each command will either indicate that it is
  1089    mandatory, or will give, using the term "indicating capability", the
  1090    capability label indicating whether the bundle including this command
  1091    is available.
  1092 
  1093    Where a server does not implement a command, it MUST always generate
  1094    a 500 generic response code (or a 501 generic response code in the
  1095    case of a variant of a command depending on a second keyword where
  1096    the base command is recognised).  Otherwise, the command MUST be
  1097    fully implemented as specified; a server MUST NOT only partially
  1098    implement any of the commands in this specification.  (Client authors
  1099    should note that some servers not conforming to this specification
  1100    will return a 502 generic response code to some commands that are not
  1101    implemented.)
  1102 
  1103    Note: some commands have cases that require other commands to be used
  1104    first.  If the former command is implemented but the latter is not,
  1105    the former MUST still generate the relevant specific response code.
  1106    For example, if ARTICLE (Section 6.2.1) is implemented but GROUP
  1107    (Section 6.1.1) is not, the correct response to "ARTICLE 1234"
  1108    remains 412.
  1109 
  1110 
  1111 
  1112 
  1113 
  1114 
  1115 
  1116 
  1117 Feather                     Standards Track                    [Page 20]
  1118 
  1119 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1120 
  1121 
  1122 3.4.1.  Reading and Transit Servers
  1123 
  1124    NNTP is traditionally used in two different ways.  The first use is
  1125    "reading", where the client fetches articles from a large store
  1126    maintained by the server for immediate or later presentation to a
  1127    user and sends articles created by that user back to the server (an
  1128    action called "posting") to be stored and distributed to other stores
  1129    and users.  The second use is for the bulk transfer of articles from
  1130    one store to another.  Since the hosts making this transfer tend to
  1131    be peers in a network that transmit articles among one another, and
  1132    not end-user systems, this process is called "peering" or "transit".
  1133    (Even so, one host is still the client and the other is the server).
  1134 
  1135    In practice, these two uses are so different that some server
  1136    implementations are optimised for reading or for transit and, as a
  1137    result, do not offer the other facility or only offer limited
  1138    features.  Other implementations are more general and offer both.
  1139    This specification allows for this by bundling the relevant commands
  1140    accordingly: the IHAVE command is designed for transit, while the
  1141    commands indicated by the READER capability are designed for reading
  1142    clients.
  1143 
  1144    Except as an effect of the MODE READER command (Section 5.3) on a
  1145    mode-switching server, once a server advertises either or both of the
  1146    IHAVE or READER capabilities, it MUST continue to advertise them for
  1147    the entire session.
  1148 
  1149    A server MAY provide different modes of behaviour (transit, reader,
  1150    or a combination) to different client connections and MAY use
  1151    external information, such as the IP address of the client, to
  1152    determine which mode to provide to any given connection.
  1153 
  1154    The official TCP port for the NNTP service is 119.  However, if a
  1155    host wishes to offer separate servers for transit and reading
  1156    clients, port 433 SHOULD be used for the transit server and 119 for
  1157    the reading server.
  1158 
  1159 3.4.2.  Mode Switching
  1160 
  1161    An implementation MAY, but SHOULD NOT, provide both transit and
  1162    reader facilities on the same server but require the client to select
  1163    which it wishes to use.  Such an arrangement is called a
  1164    "mode-switching" server.
  1165 
  1166 
  1167 
  1168 
  1169 
  1170 
  1171 
  1172 
  1173 Feather                     Standards Track                    [Page 21]
  1174 
  1175 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1176 
  1177 
  1178    A mode-switching server has two modes:
  1179 
  1180    o  Transit mode, which applies after the initial connection.
  1181 
  1182       *  It MUST advertise the MODE-READER capability.
  1183 
  1184       *  It MUST NOT advertise the READER capability.
  1185 
  1186       However, the server MAY cease to advertise the MODE-READER
  1187       capability after the client uses any command except CAPABILITIES.
  1188 
  1189    o  Reading mode, after a successful MODE READER command (see Section
  1190       5.3).
  1191 
  1192       *  It MUST NOT advertise the MODE-READER capability.
  1193 
  1194       *  It MUST advertise the READER capability.
  1195 
  1196       *  It MAY NOT advertise the IHAVE capability, even if it was
  1197          advertising it in transit mode.
  1198 
  1199    A client SHOULD only issue a MODE READER command to a server if it is
  1200    advertising the MODE-READER capability.  If the server does not
  1201    support CAPABILITIES (and therefore does not conform to this
  1202    specification), the client MAY use the following heuristic:
  1203 
  1204    o  If the client wishes to use any "reader" commands, it SHOULD use
  1205       the MODE READER command immediately after the initial connection.
  1206 
  1207    o  Otherwise, it SHOULD NOT use the MODE READER command.
  1208 
  1209    In each case, it should be prepared for some commands to be
  1210    unavailable that would have been available if it had made the other
  1211    choice.
  1212 
  1213 3.5.  Pipelining
  1214 
  1215    NNTP is designed to operate over a reliable bi-directional
  1216    connection, such as TCP.  Therefore, if a command does not depend on
  1217    the response to the previous one, it should not matter if it is sent
  1218    before that response is received.  Doing this is called "pipelining".
  1219    However, certain server implementations throw away all text received
  1220    from the client following certain commands before sending their
  1221    response.  If this happens, pipelining will be affected because one
  1222    or more commands will have been ignored or misinterpreted, and the
  1223    client will be matching the wrong responses to each command.  Since
  1224    there are significant benefits to pipelining, but also circumstances
  1225    where it is reasonable or common for servers to behave in the above
  1226 
  1227 
  1228 
  1229 Feather                     Standards Track                    [Page 22]
  1230 
  1231 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1232 
  1233 
  1234    manner, this document puts certain requirements on both clients and
  1235    servers.
  1236 
  1237    Except where stated otherwise, a client MAY use pipelining.  That is,
  1238    it may send a command before receiving the response for the previous
  1239    command.  The server MUST allow pipelining and MUST NOT throw away
  1240    any text received after a command.  Irrespective of whether
  1241    pipelining is used, the server MUST process commands in the order
  1242    they are sent.
  1243 
  1244    If the specific description of a command says it "MUST NOT be
  1245    pipelined", that command MUST end any pipeline of commands.  That is,
  1246    the client MUST NOT send any following command until it receives the
  1247    CRLF at the end of the response from the command.  The server MAY
  1248    ignore any data received after the command and before the CRLF at the
  1249    end of the response is sent to the client.
  1250 
  1251    The initial connection must not be part of a pipeline; that is, the
  1252    client MUST NOT send any command until it receives the CRLF at the
  1253    end of the greeting.
  1254 
  1255    If the client uses blocking system calls to send commands, it MUST
  1256    ensure that the amount of text sent in pipelining does not cause a
  1257    deadlock between transmission and reception.  The amount of text
  1258    involved will depend on window sizes in the transmission layer;
  1259    typically, it is 4k octets for TCP.  (Since the server only sends
  1260    data in response to commands from the client, the converse problem
  1261    does not occur.)
  1262 
  1263 3.5.1.  Examples
  1264 
  1265    Example of correct use of pipelining:
  1266 
  1267       [C] GROUP misc.test
  1268       [C] STAT
  1269       [C] NEXT
  1270       [S] 211 1234 3000234 3002322 misc.test
  1271       [S] 223 3000234 <45223423@example.com> retrieved
  1272       [S] 223 3000237 <668929@example.org> retrieved
  1273 
  1274    Example of incorrect use of pipelining (the MODE READER command may
  1275    not be pipelined):
  1276 
  1277       [C] MODE READER
  1278       [C] DATE
  1279       [C] NEXT
  1280       [S] 200 Server ready, posting allowed
  1281       [S] 223 3000237 <668929@example.org> retrieved
  1282 
  1283 
  1284 
  1285 Feather                     Standards Track                    [Page 23]
  1286 
  1287 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1288 
  1289 
  1290    The DATE command has been thrown away by the server, so there is no
  1291    111 response to match it.
  1292 
  1293 3.6.  Articles
  1294 
  1295    NNTP is intended to transfer articles between clients and servers.
  1296    For the purposes of this specification, articles are required to
  1297    conform to the rules in this section, and clients and servers MUST
  1298    correctly process any article received from the other that does so.
  1299    Note that this requirement applies only to the contents of
  1300    communications over NNTP; it does not prevent the client or server
  1301    from subsequently rejecting an article for reasons of local policy.
  1302    Also see Appendix A for further restrictions on the format of
  1303    articles in some uses of NNTP.
  1304 
  1305    An article consists of two parts: the headers and the body.  They are
  1306    separated by a single empty line, or in other words by two
  1307    consecutive CRLF pairs (if there is more than one empty line, the
  1308    second and subsequent ones are part of the body).  In order to meet
  1309    the general requirements of NNTP, an article MUST NOT include the
  1310    octet NUL, MUST NOT contain the octets LF and CR other than as part
  1311    of a CRLF pair, and MUST end with a CRLF pair.  This specification
  1312    puts no further restrictions on the body; in particular, it MAY be
  1313    empty.
  1314 
  1315    The headers of an article consist of one or more header lines.  Each
  1316    header line consists of a header name, a colon, a space, the header
  1317    content, and a CRLF, in that order.  The name consists of one or more
  1318    printable US-ASCII characters other than colon and, for the purposes
  1319    of this specification, is not case sensitive.  There MAY be more than
  1320    one header line with the same name.  The content MUST NOT contain
  1321    CRLF; it MAY be empty.  A header may be "folded"; that is, a CRLF
  1322    pair may be placed before any TAB or space in the line.  There MUST
  1323    still be some other octet between any two CRLF pairs in a header
  1324    line.  (Note that folding means that the header line occupies more
  1325    than one line when displayed or transmitted; nevertheless, it is
  1326    still referred to as "a" header line.)  The presence or absence of
  1327    folding does not affect the meaning of the header line; that is, the
  1328    CRLF pairs introduced by folding are not considered part of the
  1329    header content.  Header lines SHOULD NOT be folded before the space
  1330    after the colon that follows the header name and SHOULD include at
  1331    least one octet other than %x09 or %x20 between CRLF pairs.  However,
  1332    if an article that fails to satisfy this requirement has been
  1333    received from elsewhere, clients and servers MAY transfer it to each
  1334    other without re-folding it.
  1335 
  1336 
  1337 
  1338 
  1339 
  1340 
  1341 Feather                     Standards Track                    [Page 24]
  1342 
  1343 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1344 
  1345 
  1346    The content of a header SHOULD be in UTF-8.  However, if an
  1347    implementation receives an article from elsewhere that uses octets in
  1348    the range 128 to 255 in some other manner, it MAY pass it to a client
  1349    or server without modification.  Therefore, implementations MUST be
  1350    prepared to receive such headers, and data derived from them (e.g.,
  1351    in the responses from the OVER command, Section 8.3), and MUST NOT
  1352    assume that they are always UTF-8.  Any external processing of those
  1353    headers, including identifying the encoding used, is outside the
  1354    scope of this document.
  1355 
  1356    Each article MUST have a unique message-id; two articles offered by
  1357    an NNTP server MUST NOT have the same message-id.  For the purposes
  1358    of this specification, message-ids are opaque strings that MUST meet
  1359    the following requirements:
  1360 
  1361    o  A message-id MUST begin with "<", end with ">", and MUST NOT
  1362       contain the latter except at the end.
  1363 
  1364    o  A message-id MUST be between 3 and 250 octets in length.
  1365 
  1366    o  A message-id MUST NOT contain octets other than printable US-ASCII
  1367       characters.
  1368 
  1369    Two message-ids are the same if and only if they consist of the same
  1370    sequence of octets.
  1371 
  1372    This specification does not describe how the message-id of an article
  1373    is determined.  If the server does not have any way to determine a
  1374    message-id from the article itself, it MUST synthesize one (this
  1375    specification does not require that the article be changed as a
  1376    result).  See also Appendix A.2.
  1377 
  1378 4.  The WILDMAT Format
  1379 
  1380    The WILDMAT format described here is based on the version first
  1381    developed by Rich Salz [SALZ1992], which was in turn derived from the
  1382    format used in the UNIX "find" command to articulate file names.  It
  1383    was developed to provide a uniform mechanism for matching patterns in
  1384    the same manner that the UNIX shell matches filenames.
  1385 
  1386 
  1387 
  1388 
  1389 
  1390 
  1391 
  1392 
  1393 
  1394 
  1395 
  1396 
  1397 Feather                     Standards Track                    [Page 25]
  1398 
  1399 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1400 
  1401 
  1402 4.1.  Wildmat Syntax
  1403 
  1404    A wildmat is described by the following ABNF [RFC4234] syntax, which
  1405    is an extract of that in Section 9.8.
  1406 
  1407      wildmat = wildmat-pattern *("," ["!"] wildmat-pattern)
  1408      wildmat-pattern = 1*wildmat-item
  1409      wildmat-item = wildmat-exact / wildmat-wild
  1410      wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E /
  1411           UTF8-non-ascii ; exclude ! * , ? [ \ ]
  1412      wildmat-wild = "*" / "?"
  1413 
  1414    Note: the characters ",", "\", "[", and "]" are not allowed in
  1415    wildmats, while * and ? are always wildcards.  This should not be a
  1416    problem, since these characters cannot occur in newsgroup names,
  1417    which is the only current use of wildmats.  Backslash is commonly
  1418    used to suppress the special meaning of characters, whereas brackets
  1419    are used to introduce sets.  However, these usages are not universal,
  1420    and interpretation of these characters in the context of UTF-8
  1421    strings is potentially complex and differs from existing practice, so
  1422    they were omitted from this specification.  A future extension to
  1423    this specification may provide semantics for these characters.
  1424 
  1425 4.2.  Wildmat Semantics
  1426 
  1427    A wildmat is tested against a string and either matches or does not
  1428    match.  To do this, each constituent <wildmat-pattern> is matched
  1429    against the string, and the rightmost pattern that matches is
  1430    identified.  If that <wildmat-pattern> is not preceded with "!", the
  1431    whole wildmat matches.  If it is preceded by "!", or if no <wildmat-
  1432    pattern> matches, the whole wildmat does not match.
  1433 
  1434    For example, consider the wildmat "a*,!*b,*c*":
  1435 
  1436    o  The string "aaa" matches because the rightmost match is with "a*".
  1437 
  1438    o  The string "abb" does not match because the rightmost match is
  1439       with "*b".
  1440 
  1441    o  The string "ccb" matches because the rightmost match is with
  1442       "*c*".
  1443 
  1444    o  The string "xxx" does not match because no <wildmat-pattern>
  1445       matches.
  1446 
  1447    A <wildmat-pattern> matches a string if the string can be broken into
  1448    components, each of which matches the corresponding <wildmat-item> in
  1449    the pattern.  The matches must be in the same order, and the whole
  1450 
  1451 
  1452 
  1453 Feather                     Standards Track                    [Page 26]
  1454 
  1455 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1456 
  1457 
  1458    string must be used in the match.  The pattern is "anchored"; that
  1459    is, the first and last characters in the string must match the first
  1460    and last item, respectively (unless that item is an asterisk matching
  1461    zero characters).
  1462 
  1463    A <wildmat-exact> matches the same character (which may be more than
  1464    one octet in UTF-8).
  1465 
  1466    "?" matches exactly one character (which may be more than one octet).
  1467 
  1468    "*" matches zero or more characters.  It can match an empty string,
  1469    but it cannot match a subsequence of a UTF-8 sequence that is not
  1470    aligned to the character boundaries.
  1471 
  1472 4.3.  Extensions
  1473 
  1474    An NNTP server or extension MAY extend the syntax or semantics of
  1475    wildmats provided that all wildmats that meet the requirements of
  1476    Section 4.1 have the meaning ascribed to them by Section 4.2.  Future
  1477    editions of this document may also extend wildmats.
  1478 
  1479 4.4.  Examples
  1480 
  1481    In these examples, $ and @ are used to represent the two octets %xC2
  1482    and %xA3, respectively; $@ is thus the UTF-8 encoding for the pound
  1483    sterling symbol, shown as # in the descriptions.
  1484 
  1485      Wildmat    Description of strings that match
  1486        abc      The one string "abc"
  1487        abc,def  The two strings "abc" and "def"
  1488        $@       The one character string "#"
  1489        a*       Any string that begins with "a"
  1490        a*b      Any string that begins with "a" and ends with "b"
  1491        a*,*b    Any string that begins with "a" or ends with "b"
  1492        a*,!*b   Any string that begins with "a" and does not end with
  1493                 "b"
  1494      a*,!*b,c*  Any string that begins with "a" and does not end with
  1495                 "b", and any string that begins with "c" no matter
  1496                 what it ends with
  1497      a*,c*,!*b  Any string that begins with "a" or "c" and does not
  1498                 end with "b"
  1499        ?a*      Any string with "a" as its second character
  1500        ??a*     Any string with "a" as its third character
  1501        *a?      Any string with "a" as its penultimate character
  1502        *a??     Any string with "a" as its antepenultimate character
  1503 
  1504 
  1505 
  1506 
  1507 
  1508 
  1509 Feather                     Standards Track                    [Page 27]
  1510 
  1511 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1512 
  1513 
  1514 5.  Session Administration Commands
  1515 
  1516 5.1.  Initial Connection
  1517 
  1518 5.1.1.  Usage
  1519 
  1520    This command MUST NOT be pipelined.
  1521 
  1522    Responses [1]
  1523      200    Service available, posting allowed
  1524      201    Service available, posting prohibited
  1525      400    Service temporarily unavailable [2]
  1526      502    Service permanently unavailable [2]
  1527 
  1528    [1] These are the only valid response codes for the initial greeting;
  1529        the server MUST not return any other generic response code.
  1530 
  1531    [2] Following a 400 or 502 response, the server MUST immediately
  1532        close the connection.
  1533 
  1534 5.1.2.  Description
  1535 
  1536    There is no command presented by the client upon initial connection
  1537    to the server.  The server MUST present an appropriate response code
  1538    as a greeting to the client.  This response informs the client
  1539    whether service is available and whether the client is permitted to
  1540    post.
  1541 
  1542    If the server will accept further commands from the client including
  1543    POST, the server MUST present a 200 greeting code.  If the server
  1544    will accept further commands from the client, but the client is not
  1545    authorized to post articles using the POST command, the server MUST
  1546    present a 201 greeting code.
  1547 
  1548    Otherwise, the server MUST present a 400 or 502 greeting code and
  1549    then immediately close the connection. 400 SHOULD be used if the
  1550    issue is only temporary (for example, because of load) and the client
  1551    can expect to be able to connect successfully at some point in the
  1552    future without making any changes. 502 MUST be used if the client is
  1553    not permitted under any circumstances to interact with the server,
  1554    and MAY be used if the server has insufficient information to
  1555    determine whether the issue is temporary or permanent.
  1556 
  1557    Note: the distinction between the 200 and 201 response codes has
  1558    turned out in practice to be insufficient; for example, some servers
  1559    do not allow posting until the client has authenticated, while other
  1560    clients assume that a 201 response means that posting will never be
  1561    possible even after authentication.  Therefore, clients SHOULD use
  1562 
  1563 
  1564 
  1565 Feather                     Standards Track                    [Page 28]
  1566 
  1567 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1568 
  1569 
  1570    the CAPABILITIES command (Section 5.2) rather than rely on this
  1571    response.
  1572 
  1573 5.1.3.  Examples
  1574 
  1575    Example of a normal connection from an authorized client that then
  1576    terminates the session (see Section 5.4):
  1577 
  1578       [Initial connection set-up completed.]
  1579       [S] 200 NNTP Service Ready, posting permitted
  1580       [C] QUIT
  1581       [S] 205 NNTP Service exits normally
  1582       [Server closes connection.]
  1583 
  1584    Example of a normal connection from an authorized client that is not
  1585    permitted to post, which also immediately terminates the session:
  1586 
  1587       [Initial connection set-up completed.]
  1588       [S] 201 NNTP Service Ready, posting prohibited
  1589       [C] QUIT
  1590       [S] 205 NNTP Service exits normally
  1591       [Server closes connection.]
  1592 
  1593    Example of a normal connection from an unauthorized client:
  1594 
  1595       [Initial connection set-up completed.]
  1596       [S] 502 NNTP Service permanently unavailable
  1597       [Server closes connection.]
  1598 
  1599    Example of a connection from a client if the server is unable to
  1600    provide service:
  1601 
  1602       [Initial connection set-up completed.]
  1603       [S] 400 NNTP Service temporarily unavailable
  1604       [Server closes connection.]
  1605 
  1606 5.2.  CAPABILITIES
  1607 
  1608 5.2.1.  Usage
  1609 
  1610    This command is mandatory.
  1611 
  1612    Syntax
  1613      CAPABILITIES [keyword]
  1614 
  1615    Responses
  1616      101    Capability list follows (multi-line)
  1617 
  1618 
  1619 
  1620 
  1621 Feather                     Standards Track                    [Page 29]
  1622 
  1623 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1624 
  1625 
  1626    Parameters
  1627      keyword    additional feature, see description
  1628 
  1629 5.2.2.  Description
  1630 
  1631    The CAPABILITIES command allows a client to determine the
  1632    capabilities of the server at any given time.
  1633 
  1634    This command MAY be issued at any time; the server MUST NOT require
  1635    it to be issued in order to make use of any capability.  The response
  1636    generated by this command MAY change during a session because of
  1637    other state information (which, in turn, may be changed by the
  1638    effects of other commands or by external events).  An NNTP client is
  1639    only able to get the current and correct information concerning
  1640    available capabilities at any point during a session by issuing a
  1641    CAPABILITIES command at that point of that session and processing the
  1642    response.
  1643 
  1644    The capability list is returned as a multi-line data block following
  1645    the 101 response code.  Each capability is described by a separate
  1646    capability line.  The server MUST NOT list the same capability twice
  1647    in the response, even with different arguments.  Except that the
  1648    VERSION capability MUST be the first line, the order in which the
  1649    capability lines appears is not significant; the server need not even
  1650    consistently return the same order.
  1651 
  1652    While some capabilities are likely to be always available or never
  1653    available, others (notably extensions) will appear and disappear
  1654    depending on server state changes within the session or on external
  1655    events between sessions.  An NNTP client MAY cache the results of
  1656    this command, but MUST NOT rely on the correctness of any cached
  1657    results, whether from earlier in this session or from a previous
  1658    session, MUST cope gracefully with the cached status being out of
  1659    date, and SHOULD (if caching results) provide a way to force the
  1660    cached information to be refreshed.  Furthermore, a client MUST NOT
  1661    use cached results in relation to security, privacy, and
  1662    authentication extensions.  See Section 12.6 for further discussion
  1663    of this topic.
  1664 
  1665    The keyword argument is not used by this specification.  It is
  1666    provided so that extensions or revisions to this specification can
  1667    include extra features for this command without requiring the
  1668    CAPABILITIES command to be used twice (once to determine if the extra
  1669    features are available, and a second time to make use of them).  If
  1670    the server does not recognise the argument (and it is a keyword), it
  1671    MUST respond with the 101 response code as if the argument had been
  1672    omitted.  If an argument is provided that the server does recognise,
  1673    it MAY use the 101 response code or MAY use some other response code
  1674 
  1675 
  1676 
  1677 Feather                     Standards Track                    [Page 30]
  1678 
  1679 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1680 
  1681 
  1682    (which will be defined in the specification of that feature).  If the
  1683    argument is not a keyword, the 501 generic response code MUST be
  1684    returned.  The server MUST NOT generate any other response code to
  1685    the CAPABILITIES command.
  1686 
  1687 5.2.3.  Examples
  1688 
  1689    Example of a minimal response (a read-only server):
  1690 
  1691       [C] CAPABILITIES
  1692       [S] 101 Capability list:
  1693       [S] VERSION 2
  1694       [S] READER
  1695       [S] LIST ACTIVE NEWSGROUPS
  1696       [S] .
  1697 
  1698    Example of a response from a server that has a range of facilities
  1699    and that also describes itself:
  1700 
  1701       [C] CAPABILITIES
  1702       [S] 101 Capability list:
  1703       [S] VERSION 2
  1704       [S] READER
  1705       [S] IHAVE
  1706       [S] POST
  1707       [S] NEWNEWS
  1708       [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES OVERVIEW.FMT
  1709       [S] IMPLEMENTATION INN 4.2 2004-12-25
  1710       [S] OVER MSGID
  1711       [S] STREAMING
  1712       [S] XSECRET
  1713       [S] .
  1714 
  1715    Example of a server that supports more than one version of NNTP:
  1716 
  1717       [C] CAPABILITIES
  1718       [S] 101 Capability list:
  1719       [S] VERSION 2 3
  1720       [S] READER
  1721       [S] LIST ACTIVE NEWSGROUPS
  1722       [S] .
  1723 
  1724 
  1725 
  1726 
  1727 
  1728 
  1729 
  1730 
  1731 
  1732 
  1733 Feather                     Standards Track                    [Page 31]
  1734 
  1735 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1736 
  1737 
  1738    Example of a client attempting to use a feature of the CAPABILITIES
  1739    command that the server does not support:
  1740 
  1741       [C] CAPABILITIES AUTOUPDATE
  1742       [S] 101 Capability list:
  1743       [S] VERSION 2
  1744       [S] READER
  1745       [S] IHAVE
  1746       [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT HEADERS
  1747       [S] OVER MSGID
  1748       [S] HDR
  1749       [S] NEWNEWS
  1750       [S] .
  1751 
  1752 5.3.  MODE READER
  1753 
  1754 5.3.1.  Usage
  1755 
  1756    Indicating capability: MODE-READER
  1757 
  1758    This command MUST NOT be pipelined.
  1759 
  1760    Syntax
  1761      MODE READER
  1762 
  1763    Responses
  1764      200    Posting allowed
  1765      201    Posting prohibited
  1766      502    Reading service permanently unavailable [1]
  1767 
  1768    [1] Following a 502 response the server MUST immediately close the
  1769        connection.
  1770 
  1771 5.3.2.  Description
  1772 
  1773    The MODE READER command instructs a mode-switching server to switch
  1774    modes, as described in Section 3.4.2.
  1775 
  1776    If the server is mode-switching, it switches from its transit mode to
  1777    its reader mode, indicating this by changing the capability list
  1778    accordingly.  It MUST then return a 200 or 201 response with the same
  1779    meaning as for the initial greeting (as described in Section 5.1.1).
  1780    Note that the response need not be the same as that presented during
  1781    the initial greeting.  The client MUST NOT issue MODE READER more
  1782    than once in a session or after any security or privacy commands are
  1783    issued.  When the MODE READER command is issued, the server MAY reset
  1784    its state to that immediately after the initial connection before
  1785    switching mode.
  1786 
  1787 
  1788 
  1789 Feather                     Standards Track                    [Page 32]
  1790 
  1791 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1792 
  1793 
  1794    If the server is not mode-switching, then the following apply:
  1795 
  1796    o  If it advertises the READER capability, it MUST return a 200 or
  1797       201 response with the same meaning as for the initial greeting; in
  1798       this case, the command MUST NOT affect the server state in any
  1799       way.
  1800 
  1801    o  If it does not advertise the READER capability, it MUST return a
  1802       502 response and then immediately close the connection.
  1803 
  1804 5.3.3.  Examples
  1805 
  1806    Example of use of the MODE READER command on a transit-only server
  1807    (which therefore does not providing reading facilities):
  1808 
  1809       [C] CAPABILITIES
  1810       [S] 101 Capability list:
  1811       [S] VERSION 2
  1812       [S] IHAVE
  1813       [S] .
  1814       [C] MODE READER
  1815       [S] 502 Transit service only
  1816       [Server closes connection.]
  1817 
  1818    Example of use of the MODE READER command on a server that provides
  1819    reading facilities:
  1820 
  1821       [C] CAPABILITIES
  1822       [S] 101 Capability list:
  1823       [S] VERSION 2
  1824       [S] READER
  1825       [S] LIST ACTIVE NEWSGROUPS
  1826       [S] .
  1827       [C] MODE READER
  1828       [S] 200 Reader mode, posting permitted
  1829       [C] IHAVE <i.am.an.article.you.have@example.com>
  1830       [S] 500 Permission denied
  1831       [C] GROUP misc.test
  1832       [S] 211 1234 3000234 3002322 misc.test
  1833 
  1834    Note that in both of these situations, the client SHOULD NOT use MODE
  1835    READER.
  1836 
  1837 
  1838 
  1839 
  1840 
  1841 
  1842 
  1843 
  1844 
  1845 Feather                     Standards Track                    [Page 33]
  1846 
  1847 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1848 
  1849 
  1850    Example of use of the MODE READER command on a mode-switching server:
  1851 
  1852       [C] CAPABILITIES
  1853       [S] 101 Capability list:
  1854       [S] VERSION 2
  1855       [S] IHAVE
  1856       [S] MODE-READER
  1857       [S] .
  1858       [C] MODE READER
  1859       [S] 200 Reader mode, posting permitted
  1860       [C] CAPABILITIES
  1861       [S] 101 Capability list:
  1862       [S] VERSION 2
  1863       [S] READER
  1864       [S] NEWNEWS
  1865       [S] LIST ACTIVE NEWSGROUPS
  1866       [S] STARTTLS
  1867       [S] .
  1868 
  1869    In this case, the server offers (but does not require) TLS privacy in
  1870    its reading mode but not in its transit mode.
  1871 
  1872    Example of use of the MODE READER command where the client is not
  1873    permitted to post:
  1874 
  1875       [C] MODE READER
  1876       [S] 201 NNTP Service Ready, posting prohibited
  1877 
  1878 5.4.  QUIT
  1879 
  1880 5.4.1.  Usage
  1881 
  1882    This command is mandatory.
  1883 
  1884    Syntax
  1885      QUIT
  1886 
  1887    Responses
  1888      205    Connection closing
  1889 
  1890 5.4.2.  Description
  1891 
  1892    The client uses the QUIT command to terminate the session.  The
  1893    server MUST acknowledge the QUIT command and then close the
  1894    connection to the client.  This is the preferred method for a client
  1895    to indicate that it has finished all of its transactions with the
  1896    NNTP server.
  1897 
  1898 
  1899 
  1900 
  1901 Feather                     Standards Track                    [Page 34]
  1902 
  1903 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1904 
  1905 
  1906    If a client simply disconnects (or if the connection times out or
  1907    some other fault occurs), the server MUST gracefully cease its
  1908    attempts to service the client, disconnecting from its end if
  1909    necessary.
  1910 
  1911    The server MUST NOT generate any response code to the QUIT command
  1912    other than 205 or, if any arguments are provided, 501.
  1913 
  1914 5.4.3.  Examples
  1915 
  1916       [C] QUIT
  1917       [S] 205 closing connection
  1918       [Server closes connection.]
  1919 
  1920 6.  Article Posting and Retrieval
  1921 
  1922    News-reading clients have available a variety of mechanisms to
  1923    retrieve articles via NNTP.  The news articles are stored and indexed
  1924    using three types of keys.  The first type of key is the message-id
  1925    of an article and is globally unique.  The second type of key is
  1926    composed of a newsgroup name and an article number within that
  1927    newsgroup.  On a particular server, there MUST only be one article
  1928    with a given number within any newsgroup, and an article MUST NOT
  1929    have two different numbers in the same newsgroup.  An article can be
  1930    cross-posted to multiple newsgroups, so there may be multiple keys
  1931    that point to the same article on the same server; these MAY have
  1932    different numbers in each newsgroup.  However, this type of key is
  1933    not required to be globally unique, so the same key MAY refer to
  1934    different articles on different servers.  (Note that the terms
  1935    "group" and "newsgroup" are equivalent.)
  1936 
  1937    The final type of key is the arrival timestamp, giving the time that
  1938    the article arrived at the server.  The server MUST ensure that
  1939    article numbers are issued in order of arrival timestamp; that is,
  1940    articles arriving later MUST have higher numbers than those that
  1941    arrive earlier.  The server SHOULD allocate the next sequential
  1942    unused number to each new article.
  1943 
  1944    Article numbers MUST lie between 1 and 2,147,483,647, inclusive.  The
  1945    client and server MAY use leading zeroes in specifying article
  1946    numbers but MUST NOT use more than 16 digits.  In some situations,
  1947    the value zero replaces an article number to show some special
  1948    situation.
  1949 
  1950    Note that it is likely that the article number limit of 2,147,483,647
  1951    will be increased by a future revision or extension to this
  1952    specification.  While servers MUST NOT send article numbers greater
  1953    than this current limit, client and server developers are advised to
  1954 
  1955 
  1956 
  1957 Feather                     Standards Track                    [Page 35]
  1958 
  1959 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  1960 
  1961 
  1962    use internal structures and datatypes capable of handling larger
  1963    values in anticipation of such a change.
  1964 
  1965 6.1.  Group and Article Selection
  1966 
  1967    The following commands are used to set the "currently selected
  1968    newsgroup" and the "current article number", which are used by
  1969    various commands.  At the start of an NNTP session, both of these
  1970    values are set to the special value "invalid".
  1971 
  1972 6.1.1.  GROUP
  1973 
  1974 6.1.1.1.  Usage
  1975 
  1976    Indicating capability: READER
  1977 
  1978    Syntax
  1979      GROUP group
  1980 
  1981    Responses
  1982      211 number low high group     Group successfully selected
  1983      411                           No such newsgroup
  1984 
  1985    Parameters
  1986      group     Name of newsgroup
  1987      number    Estimated number of articles in the group
  1988      low       Reported low water mark
  1989      high      Reported high water mark
  1990 
  1991 6.1.1.2.  Description
  1992 
  1993    The GROUP command selects a newsgroup as the currently selected
  1994    newsgroup and returns summary information about it.
  1995 
  1996    The required argument is the name of the newsgroup to be selected
  1997    (e.g., "news.software.nntp").  A list of valid newsgroups may be
  1998    obtained by using the LIST ACTIVE command (see Section 7.6.3).
  1999 
  2000    The successful selection response will return the article numbers of
  2001    the first and last articles in the group at the moment of selection
  2002    (these numbers are referred to as the "reported low water mark" and
  2003    the "reported high water mark") and an estimate of the number of
  2004    articles in the group currently available.
  2005 
  2006    If the group is not empty, the estimate MUST be at least the actual
  2007    number of articles available and MUST be no greater than one more
  2008    than the difference between the reported low and high water marks.
  2009    (Some implementations will actually count the number of articles
  2010 
  2011 
  2012 
  2013 Feather                     Standards Track                    [Page 36]
  2014 
  2015 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2016 
  2017 
  2018    currently stored.  Others will just subtract the low water mark from
  2019    the high water mark and add one to get an estimate.)
  2020 
  2021    If the group is empty, one of the following three situations will
  2022    occur.  Clients MUST accept all three cases; servers MUST NOT
  2023    represent an empty group in any other way.
  2024 
  2025    o  The high water mark will be one less than the low water mark, and
  2026       the estimated article count will be zero.  Servers SHOULD use this
  2027       method to show an empty group.  This is the only time that the
  2028       high water mark can be less than the low water mark.
  2029 
  2030    o  All three numbers will be zero.
  2031 
  2032    o  The high water mark is greater than or equal to the low water
  2033       mark.  The estimated article count might be zero or non-zero; if
  2034       it is non-zero, the same requirements apply as for a non-empty
  2035       group.
  2036 
  2037    The set of articles in a group may change after the GROUP command is
  2038    carried out:
  2039 
  2040    o  Articles may be removed from the group.
  2041 
  2042    o  Articles may be reinstated in the group with the same article
  2043       number, but those articles MUST have numbers no less than the
  2044       reported low water mark (note that this is a reinstatement of the
  2045       previous article, not a new article reusing the number).
  2046 
  2047    o  New articles may be added with article numbers greater than the
  2048       reported high water mark.  (If an article that was the one with
  2049       the highest number has been removed and the high water mark has
  2050       been adjusted accordingly, the next new article will not have the
  2051       number one greater than the reported high water mark.)
  2052 
  2053    Except when the group is empty and all three numbers are zero,
  2054    whenever a subsequent GROUP command for the same newsgroup is issued,
  2055    either by the same client or a different client, the reported low
  2056    water mark in the response MUST be no less than that in any previous
  2057    response for that newsgroup in this session, and it SHOULD be no less
  2058    than that in any previous response for that newsgroup ever sent to
  2059    any client.  Any failure to meet the latter condition SHOULD be
  2060    transient only.  The client may make use of the low water mark to
  2061    remove all remembered information about articles with lower numbers,
  2062    as these will never recur.  This includes the situation when the high
  2063    water mark is one less than the low water mark.  No similar
  2064    assumption can be made about the high water mark, as this can
  2065 
  2066 
  2067 
  2068 
  2069 Feather                     Standards Track                    [Page 37]
  2070 
  2071 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2072 
  2073 
  2074    decrease if an article is removed and then increase again if it is
  2075    reinstated or if new articles arrive.
  2076 
  2077    When a valid group is selected by means of this command, the
  2078    currently selected newsgroup MUST be set to that group, and the
  2079    current article number MUST be set to the first article in the group
  2080    (this applies even if the group is already the currently selected
  2081    newsgroup).  If an empty newsgroup is selected, the current article
  2082    number is made invalid.  If an invalid group is specified, the
  2083    currently selected newsgroup and current article number MUST NOT be
  2084    changed.
  2085 
  2086    The GROUP or LISTGROUP command (see Section 6.1.2) MUST be used by a
  2087    client, and a successful response received, before any other command
  2088    is used that depends on the value of the currently selected newsgroup
  2089    or current article number.
  2090 
  2091    If the group specified is not available on the server, a 411 response
  2092    MUST be returned.
  2093 
  2094 6.1.1.3.  Examples
  2095 
  2096    Example for a group known to the server:
  2097 
  2098       [C] GROUP misc.test
  2099       [S] 211 1234 3000234 3002322 misc.test
  2100 
  2101    Example for a group unknown to the server:
  2102 
  2103       [C] GROUP example.is.sob.bradner.or.barber
  2104       [S] 411 example.is.sob.bradner.or.barber is unknown
  2105 
  2106    Example of an empty group using the preferred response:
  2107 
  2108       [C] GROUP example.currently.empty.newsgroup
  2109       [S] 211 0 4000 3999 example.currently.empty.newsgroup
  2110 
  2111    Example of an empty group using an alternative response:
  2112 
  2113       [C] GROUP example.currently.empty.newsgroup
  2114       [S] 211 0 0 0 example.currently.empty.newsgroup
  2115 
  2116    Example of an empty group using a different alternative response:
  2117 
  2118       [C] GROUP example.currently.empty.newsgroup
  2119       [S] 211 0 4000 4321 example.currently.empty.newsgroup
  2120 
  2121 
  2122 
  2123 
  2124 
  2125 Feather                     Standards Track                    [Page 38]
  2126 
  2127 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2128 
  2129 
  2130    Example reselecting the currently selected newsgroup:
  2131 
  2132       [C] GROUP misc.test
  2133       [S] 211 1234 234 567 misc.test
  2134       [C] STAT 444
  2135       [S] 223 444 <123456@example.net> retrieved
  2136       [C] GROUP misc.test
  2137       [S] 211 1234 234 567 misc.test
  2138       [C] STAT
  2139       [S] 223 234 <different@example.net> retrieved
  2140 
  2141 6.1.2.  LISTGROUP
  2142 
  2143 6.1.2.1.  Usage
  2144 
  2145    Indicating capability: READER
  2146 
  2147    Syntax
  2148      LISTGROUP [group [range]]
  2149 
  2150    Responses
  2151      211 number low high group     Article numbers follow (multi-line)
  2152      411                           No such newsgroup
  2153      412                           No newsgroup selected [1]
  2154 
  2155    Parameters
  2156      group     Name of newsgroup
  2157      range     Range of articles to report
  2158      number    Estimated number of articles in the group
  2159      low       Reported low water mark
  2160      high      Reported high water mark
  2161 
  2162    [1] The 412 response can only occur if no group has been specified.
  2163 
  2164 6.1.2.2.  Description
  2165 
  2166    The LISTGROUP command selects a newsgroup in the same manner as the
  2167    GROUP command (see Section 6.1.1) but also provides a list of article
  2168    numbers in the newsgroup.  If no group is specified, the currently
  2169    selected newsgroup is used.
  2170 
  2171    On success, a list of article numbers is returned as a multi-line
  2172    data block following the 211 response code (the arguments on the
  2173    initial response line are the same as for the GROUP command).  The
  2174    list contains one number per line and is in numerical order.  It
  2175    lists precisely those articles that exist in the group at the moment
  2176    of selection (therefore, an empty group produces an empty list).  If
  2177    the optional range argument is specified, only articles within the
  2178 
  2179 
  2180 
  2181 Feather                     Standards Track                    [Page 39]
  2182 
  2183 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2184 
  2185 
  2186    range are included in the list (therefore, the list MAY be empty even
  2187    if the group is not).
  2188 
  2189    The range argument may be any of the following:
  2190 
  2191    o  An article number.
  2192 
  2193    o  An article number followed by a dash to indicate all following.
  2194 
  2195    o  An article number followed by a dash followed by another article
  2196       number.
  2197 
  2198    In the last case, if the second number is less than the first number,
  2199    then the range contains no articles.  Omitting the range is
  2200    equivalent to the range 1- being specified.
  2201 
  2202    If the group specified is not available on the server, a 411 response
  2203    MUST be returned.  If no group is specified and the currently
  2204    selected newsgroup is invalid, a 412 response MUST be returned.
  2205 
  2206    Except that the group argument is optional, that a range argument can
  2207    be specified, and that a multi-line data block follows the 211
  2208    response code, the LISTGROUP command is identical to the GROUP
  2209    command.  In particular, when successful, the command sets the
  2210    current article number to the first article in the group, if any,
  2211    even if this is not within the range specified by the second
  2212    argument.
  2213 
  2214    Note that the range argument is a new feature in this specification
  2215    and servers that do not support CAPABILITIES (and therefore do not
  2216    conform to this specification) are unlikely to support it.
  2217 
  2218 6.1.2.3.  Examples
  2219 
  2220    Example of LISTGROUP being used to select a group:
  2221 
  2222       [C] LISTGROUP misc.test
  2223       [S] 211 2000 3000234 3002322 misc.test list follows
  2224       [S] 3000234
  2225       [S] 3000237
  2226       [S] 3000238
  2227       [S] 3000239
  2228       [S] 3002322
  2229       [S] .
  2230 
  2231 
  2232 
  2233 
  2234 
  2235 
  2236 
  2237 Feather                     Standards Track                    [Page 40]
  2238 
  2239 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2240 
  2241 
  2242    Example of LISTGROUP on an empty group:
  2243 
  2244       [C] LISTGROUP example.empty.newsgroup
  2245       [S] 211 0 0 0 example.empty.newsgroup list follows
  2246       [S] .
  2247 
  2248    Example of LISTGROUP on a valid, currently selected newsgroup:
  2249 
  2250       [C] GROUP misc.test
  2251       [S] 211 2000 3000234 3002322 misc.test
  2252       [C] LISTGROUP
  2253       [S] 211 2000 3000234 3002322 misc.test list follows
  2254       [S] 3000234
  2255       [S] 3000237
  2256       [S] 3000238
  2257       [S] 3000239
  2258       [S] 3002322
  2259       [S] .
  2260 
  2261    Example of LISTGROUP with a range:
  2262 
  2263       [C] LISTGROUP misc.test 3000238-3000248
  2264       [S] 211 2000 3000234 3002322 misc.test list follows
  2265       [S] 3000238
  2266       [S] 3000239
  2267       [S] .
  2268 
  2269    Example of LISTGROUP with an empty range:
  2270 
  2271       [C] LISTGROUP misc.test 12345678-
  2272       [S] 211 2000 3000234 3002322 misc.test list follows
  2273       [S] .
  2274 
  2275    Example of LISTGROUP with an invalid range:
  2276 
  2277       [C] LISTGROUP misc.test 9999-111
  2278       [S] 211 2000 3000234 3002322 misc.test list follows
  2279       [S] .
  2280 
  2281 
  2282 
  2283 
  2284 
  2285 
  2286 
  2287 
  2288 
  2289 
  2290 
  2291 
  2292 
  2293 Feather                     Standards Track                    [Page 41]
  2294 
  2295 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2296 
  2297 
  2298 6.1.3.  LAST
  2299 
  2300 6.1.3.1.  Usage
  2301 
  2302    Indicating capability: READER
  2303 
  2304    Syntax
  2305      LAST
  2306 
  2307    Responses
  2308      223 n message-id    Article found
  2309      412                 No newsgroup selected
  2310      420                 Current article number is invalid
  2311      422                 No previous article in this group
  2312 
  2313    Parameters
  2314      n             Article number
  2315      message-id    Article message-id
  2316 
  2317 6.1.3.2.  Description
  2318 
  2319    If the currently selected newsgroup is valid, the current article
  2320    number MUST be set to the previous article in that newsgroup (that
  2321    is, the highest existing article number less than the current article
  2322    number).  If successful, a response indicating the new current
  2323    article number and the message-id of that article MUST be returned.
  2324    No article text is sent in response to this command.
  2325 
  2326    There MAY be no previous article in the group, although the current
  2327    article number is not the reported low water mark.  There MUST NOT be
  2328    a previous article when the current article number is the reported
  2329    low water mark.
  2330 
  2331    Because articles can be removed and added, the results of multiple
  2332    LAST and NEXT commands MAY not be consistent over the life of a
  2333    particular NNTP session.
  2334 
  2335    If the current article number is already the first article of the
  2336    newsgroup, a 422 response MUST be returned.  If the current article
  2337    number is invalid, a 420 response MUST be returned.  If the currently
  2338    selected newsgroup is invalid, a 412 response MUST be returned.  In
  2339    all three cases, the currently selected newsgroup and current article
  2340    number MUST NOT be altered.
  2341 
  2342 
  2343 
  2344 
  2345 
  2346 
  2347 
  2348 
  2349 Feather                     Standards Track                    [Page 42]
  2350 
  2351 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2352 
  2353 
  2354 6.1.3.3.  Examples
  2355 
  2356    Example of a successful article retrieval using LAST:
  2357 
  2358       [C] GROUP misc.test
  2359       [S] 211 1234 3000234 3002322 misc.test
  2360       [C] NEXT
  2361       [S] 223 3000237 <668929@example.org> retrieved
  2362       [C] LAST
  2363       [S] 223 3000234 <45223423@example.com> retrieved
  2364 
  2365    Example of an attempt to retrieve an article without having selected
  2366    a group (via the GROUP command) first:
  2367 
  2368       [Assumes currently selected newsgroup is invalid.]
  2369       [C] LAST
  2370       [S] 412 no newsgroup selected
  2371 
  2372    Example of an attempt to retrieve an article using the LAST command
  2373    when the current article number is that of the first article in the
  2374    group:
  2375 
  2376       [C] GROUP misc.test
  2377       [S] 211 1234 3000234 3002322 misc.test
  2378       [C] LAST
  2379       [S] 422 No previous article to retrieve
  2380 
  2381    Example of an attempt to retrieve an article using the LAST command
  2382    when the currently selected newsgroup is empty:
  2383 
  2384       [C] GROUP example.empty.newsgroup
  2385       [S] 211 0 0 0 example.empty.newsgroup
  2386       [C] LAST
  2387       [S] 420 No current article selected
  2388 
  2389 
  2390 
  2391 
  2392 
  2393 
  2394 
  2395 
  2396 
  2397 
  2398 
  2399 
  2400 
  2401 
  2402 
  2403 
  2404 
  2405 Feather                     Standards Track                    [Page 43]
  2406 
  2407 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2408 
  2409 
  2410 6.1.4.  NEXT
  2411 
  2412 6.1.4.1.  Usage
  2413 
  2414    Indicating capability: READER
  2415 
  2416    Syntax
  2417      NEXT
  2418 
  2419    Responses
  2420      223 n message-id    Article found
  2421      412                 No newsgroup selected
  2422      420                 Current article number is invalid
  2423      421                 No next article in this group
  2424 
  2425    Parameters
  2426      n             Article number
  2427      message-id    Article message-id
  2428 
  2429 6.1.4.2.  Description
  2430 
  2431    If the currently selected newsgroup is valid, the current article
  2432    number MUST be set to the next article in that newsgroup (that is,
  2433    the lowest existing article number greater than the current article
  2434    number).  If successful, a response indicating the new current
  2435    article number and the message-id of that article MUST be returned.
  2436    No article text is sent in response to this command.
  2437 
  2438    If the current article number is already the last article of the
  2439    newsgroup, a 421 response MUST be returned.  In all other aspects
  2440    (apart, of course, from the lack of 422 response), this command is
  2441    identical to the LAST command (Section 6.1.3).
  2442 
  2443 6.1.4.3.  Examples
  2444 
  2445    Example of a successful article retrieval using NEXT:
  2446 
  2447       [C] GROUP misc.test
  2448       [S] 211 1234 3000234 3002322 misc.test
  2449       [C] NEXT
  2450       [S] 223 3000237 <668929@example.org> retrieved
  2451 
  2452 
  2453 
  2454 
  2455 
  2456 
  2457 
  2458 
  2459 
  2460 
  2461 Feather                     Standards Track                    [Page 44]
  2462 
  2463 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2464 
  2465 
  2466    Example of an attempt to retrieve an article without having selected
  2467    a group (via the GROUP command) first:
  2468 
  2469       [Assumes currently selected newsgroup is invalid.]
  2470       [C] NEXT
  2471       [S] 412 no newsgroup selected
  2472 
  2473    Example of an attempt to retrieve an article using the NEXT command
  2474    when the current article number is that of the last article in the
  2475    group:
  2476 
  2477       [C] GROUP misc.test
  2478       [S] 211 1234 3000234 3002322 misc.test
  2479       [C] STAT 3002322
  2480       [S] 223 3002322 <411@example.net> retrieved
  2481       [C] NEXT
  2482       [S] 421 No next article to retrieve
  2483 
  2484    Example of an attempt to retrieve an article using the NEXT command
  2485    when the currently selected newsgroup is empty:
  2486 
  2487       [C] GROUP example.empty.newsgroup
  2488       [S] 211 0 0 0 example.empty.newsgroup
  2489       [C] NEXT
  2490       [S] 420 No current article selected
  2491 
  2492 6.2.  Retrieval of Articles and Article Sections
  2493 
  2494    The ARTICLE, BODY, HEAD, and STAT commands are very similar.  They
  2495    differ only in the parts of the article that are presented to the
  2496    client and in the successful response code.  The ARTICLE command is
  2497    described here in full, while the other three commands are described
  2498    in terms of the differences.  As specified in Section 3.6, an article
  2499    consists of two parts: the article headers and the article body.
  2500 
  2501    When responding to one of these commands, the server MUST present the
  2502    entire article or appropriate part and MUST NOT attempt to alter or
  2503    translate it in any way.
  2504 
  2505 
  2506 
  2507 
  2508 
  2509 
  2510 
  2511 
  2512 
  2513 
  2514 
  2515 
  2516 
  2517 Feather                     Standards Track                    [Page 45]
  2518 
  2519 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2520 
  2521 
  2522 6.2.1.  ARTICLE
  2523 
  2524 6.2.1.1.  Usage
  2525 
  2526    Indicating capability: READER
  2527 
  2528    Syntax
  2529      ARTICLE message-id
  2530      ARTICLE number
  2531      ARTICLE
  2532 
  2533    Responses
  2534 
  2535    First form (message-id specified)
  2536      220 0|n message-id    Article follows (multi-line)
  2537      430                   No article with that message-id
  2538 
  2539    Second form (article number specified)
  2540      220 n message-id      Article follows (multi-line)
  2541      412                   No newsgroup selected
  2542      423                   No article with that number
  2543 
  2544    Third form (current article number used)
  2545      220 n message-id      Article follows (multi-line)
  2546      412                   No newsgroup selected
  2547      420                   Current article number is invalid
  2548 
  2549    Parameters
  2550      number        Requested article number
  2551      n             Returned article number
  2552      message-id    Article message-id
  2553 
  2554 6.2.1.2.  Description
  2555 
  2556    The ARTICLE command selects an article according to the arguments and
  2557    presents the entire article (that is, the headers, an empty line, and
  2558    the body, in that order) to the client.  The command has three forms.
  2559 
  2560    In the first form, a message-id is specified, and the server presents
  2561    the article with that message-id.  In this case, the server MUST NOT
  2562    alter the currently selected newsgroup or current article number.
  2563    This is both to facilitate the presentation of articles that may be
  2564    referenced within another article being read, and because of the
  2565    semantic difficulties of determining the proper sequence and
  2566    membership of an article that may have been cross-posted to more than
  2567    one newsgroup.
  2568 
  2569 
  2570 
  2571 
  2572 
  2573 Feather                     Standards Track                    [Page 46]
  2574 
  2575 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2576 
  2577 
  2578    In the response, the article number MUST be replaced with zero,
  2579    unless there is a currently selected newsgroup and the article is
  2580    present in that group, in which case the server MAY use the article's
  2581    number in that group.  (The server is not required to determine
  2582    whether the article is in the currently selected newsgroup or, if so,
  2583    what article number it has; the client MUST always be prepared for
  2584    zero to be specified.)  The server MUST NOT provide an article number
  2585    unless use of that number in a second ARTICLE command immediately
  2586    following this one would return the same article.  Even if the server
  2587    chooses to return article numbers in these circumstances, it need not
  2588    do so consistently; it MAY return zero to any such command (also see
  2589    the STAT examples, Section 6.2.4.3).
  2590 
  2591    In the second form, an article number is specified.  If there is an
  2592    article with that number in the currently selected newsgroup, the
  2593    server MUST set the current article number to that number.
  2594 
  2595    In the third form, the article indicated by the current article
  2596    number in the currently selected newsgroup is used.
  2597 
  2598    Note that a previously valid article number MAY become invalid if the
  2599    article has been removed.  A previously invalid article number MAY
  2600    become valid if the article has been reinstated, but this article
  2601    number MUST be no less than the reported low water mark for that
  2602    group.
  2603 
  2604    The server MUST NOT change the currently selected newsgroup as a
  2605    result of this command.  The server MUST NOT change the current
  2606    article number except when an article number argument was provided
  2607    and the article exists; in particular, it MUST NOT change it
  2608    following an unsuccessful response.
  2609 
  2610    Since the message-id is unique for each article, it may be used by a
  2611    client to skip duplicate displays of articles that have been posted
  2612    more than once, or to more than one newsgroup.
  2613 
  2614    The article is returned as a multi-line data block following the 220
  2615    response code.
  2616 
  2617    If the argument is a message-id and no such article exists, a 430
  2618    response MUST be returned.  If the argument is a number or is omitted
  2619    and the currently selected newsgroup is invalid, a 412 response MUST
  2620    be returned.  If the argument is a number and that article does not
  2621    exist in the currently selected newsgroup, a 423 response MUST be
  2622    returned.  If the argument is omitted and the current article number
  2623    is invalid, a 420 response MUST be returned.
  2624 
  2625 
  2626 
  2627 
  2628 
  2629 Feather                     Standards Track                    [Page 47]
  2630 
  2631 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2632 
  2633 
  2634 6.2.1.3.  Examples
  2635 
  2636    Example of a successful retrieval of an article (explicitly not using
  2637    an article number):
  2638 
  2639       [C] GROUP misc.test
  2640       [S] 211 1234 3000234 3002322 misc.test
  2641       [C] ARTICLE
  2642       [S] 220 3000234 <45223423@example.com>
  2643       [S] Path: pathost!demo!whitehouse!not-for-mail
  2644       [S] From: "Demo User" <nobody@example.net>
  2645       [S] Newsgroups: misc.test
  2646       [S] Subject: I am just a test article
  2647       [S] Date: 6 Oct 1998 04:38:40 -0500
  2648       [S] Organization: An Example Net, Uncertain, Texas
  2649       [S] Message-ID: <45223423@example.com>
  2650       [S]
  2651       [S] This is just a test article.
  2652       [S] .
  2653 
  2654    Example of a successful retrieval of an article by message-id:
  2655 
  2656       [C] ARTICLE <45223423@example.com>
  2657       [S] 220 0 <45223423@example.com>
  2658       [S] Path: pathost!demo!whitehouse!not-for-mail
  2659       [S] From: "Demo User" <nobody@example.net>
  2660       [S] Newsgroups: misc.test
  2661       [S] Subject: I am just a test article
  2662       [S] Date: 6 Oct 1998 04:38:40 -0500
  2663       [S] Organization: An Example Net, Uncertain, Texas
  2664       [S] Message-ID: <45223423@example.com>
  2665       [S]
  2666       [S] This is just a test article.
  2667       [S] .
  2668 
  2669    Example of an unsuccessful retrieval of an article by message-id:
  2670 
  2671       [C] ARTICLE <i.am.not.there@example.com>
  2672       [S] 430 No Such Article Found
  2673 
  2674    Example of an unsuccessful retrieval of an article by number:
  2675 
  2676       [C] GROUP misc.test
  2677       [S] 211 1234 3000234 3002322 news.groups
  2678       [C] ARTICLE 300256
  2679       [S] 423 No article with that number
  2680 
  2681 
  2682 
  2683 
  2684 
  2685 Feather                     Standards Track                    [Page 48]
  2686 
  2687 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2688 
  2689 
  2690    Example of an unsuccessful retrieval of an article by number because
  2691    no newsgroup was selected first:
  2692 
  2693       [Assumes currently selected newsgroup is invalid.]
  2694       [C] ARTICLE 300256
  2695       [S] 412 No newsgroup selected
  2696 
  2697    Example of an attempt to retrieve an article when the currently
  2698    selected newsgroup is empty:
  2699 
  2700       [C] GROUP example.empty.newsgroup
  2701       [S] 211 0 0 0 example.empty.newsgroup
  2702       [C] ARTICLE
  2703       [S] 420 No current article selected
  2704 
  2705 6.2.2.  HEAD
  2706 
  2707 6.2.2.1.  Usage
  2708 
  2709    This command is mandatory.
  2710 
  2711    Syntax
  2712      HEAD message-id
  2713      HEAD number
  2714      HEAD
  2715 
  2716    Responses
  2717 
  2718    First form (message-id specified)
  2719      221 0|n message-id    Headers follow (multi-line)
  2720      430                   No article with that message-id
  2721 
  2722    Second form (article number specified)
  2723      221 n message-id      Headers follow (multi-line)
  2724      412                   No newsgroup selected
  2725      423                   No article with that number
  2726 
  2727    Third form (current article number used)
  2728      221 n message-id      Headers follow (multi-line)
  2729      412                   No newsgroup selected
  2730      420                   Current article number is invalid
  2731 
  2732    Parameters
  2733      number        Requested article number
  2734      n             Returned article number
  2735      message-id    Article message-id
  2736 
  2737 
  2738 
  2739 
  2740 
  2741 Feather                     Standards Track                    [Page 49]
  2742 
  2743 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2744 
  2745 
  2746 6.2.2.2.  Description
  2747 
  2748    The HEAD command behaves identically to the ARTICLE command except
  2749    that, if the article exists, the response code is 221 instead of 220
  2750    and only the headers are presented (the empty line separating the
  2751    headers and body MUST NOT be included).
  2752 
  2753 6.2.2.3.  Examples
  2754 
  2755    Example of a successful retrieval of the headers of an article
  2756    (explicitly not using an article number):
  2757 
  2758       [C] GROUP misc.test
  2759       [S] 211 1234 3000234 3002322 misc.test
  2760       [C] HEAD
  2761       [S] 221 3000234 <45223423@example.com>
  2762       [S] Path: pathost!demo!whitehouse!not-for-mail
  2763       [S] From: "Demo User" <nobody@example.net>
  2764       [S] Newsgroups: misc.test
  2765       [S] Subject: I am just a test article
  2766       [S] Date: 6 Oct 1998 04:38:40 -0500
  2767       [S] Organization: An Example Net, Uncertain, Texas
  2768       [S] Message-ID: <45223423@example.com>
  2769       [S] .
  2770 
  2771    Example of a successful retrieval of the headers of an article by
  2772    message-id:
  2773 
  2774       [C] HEAD <45223423@example.com>
  2775       [S] 221 0 <45223423@example.com>
  2776       [S] Path: pathost!demo!whitehouse!not-for-mail
  2777       [S] From: "Demo User" <nobody@example.net>
  2778       [S] Newsgroups: misc.test
  2779       [S] Subject: I am just a test article
  2780       [S] Date: 6 Oct 1998 04:38:40 -0500
  2781       [S] Organization: An Example Net, Uncertain, Texas
  2782       [S] Message-ID: <45223423@example.com>
  2783       [S] .
  2784 
  2785    Example of an unsuccessful retrieval of the headers of an article by
  2786    message-id:
  2787 
  2788       [C] HEAD <i.am.not.there@example.com>
  2789       [S] 430 No Such Article Found
  2790 
  2791 
  2792 
  2793 
  2794 
  2795 
  2796 
  2797 Feather                     Standards Track                    [Page 50]
  2798 
  2799 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2800 
  2801 
  2802    Example of an unsuccessful retrieval of the headers of an article by
  2803    number:
  2804 
  2805       [C] GROUP misc.test
  2806       [S] 211 1234 3000234 3002322 misc.test
  2807       [C] HEAD 300256
  2808       [S] 423 No article with that number
  2809 
  2810    Example of an unsuccessful retrieval of the headers of an article by
  2811    number because no newsgroup was selected first:
  2812 
  2813       [Assumes currently selected newsgroup is invalid.]
  2814       [C] HEAD 300256
  2815       [S] 412 No newsgroup selected
  2816 
  2817    Example of an attempt to retrieve the headers of an article when the
  2818    currently selected newsgroup is empty:
  2819 
  2820       [C] GROUP example.empty.newsgroup
  2821       [S] 211 0 0 0 example.empty.newsgroup
  2822       [C] HEAD
  2823       [S] 420 No current article selected
  2824 
  2825 6.2.3.  BODY
  2826 
  2827 6.2.3.1.  Usage
  2828 
  2829    Indicating capability: READER
  2830 
  2831    Syntax
  2832      BODY message-id
  2833      BODY number
  2834      BODY
  2835 
  2836    Responses
  2837 
  2838    First form (message-id specified)
  2839      222 0|n message-id    Body follows (multi-line)
  2840      430                   No article with that message-id
  2841 
  2842    Second form (article number specified)
  2843      222 n message-id      Body follows (multi-line)
  2844      412                   No newsgroup selected
  2845      423                   No article with that number
  2846 
  2847 
  2848 
  2849 
  2850 
  2851 
  2852 
  2853 Feather                     Standards Track                    [Page 51]
  2854 
  2855 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2856 
  2857 
  2858    Third form (current article number used)
  2859      222 n message-id      Body follows (multi-line)
  2860      412                   No newsgroup selected
  2861      420                   Current article number is invalid
  2862 
  2863    Parameters
  2864      number        Requested article number
  2865      n             Returned article number
  2866      message-id    Article message-id
  2867 
  2868 6.2.3.2.  Description
  2869 
  2870    The BODY command behaves identically to the ARTICLE command except
  2871    that, if the article exists, the response code is 222 instead of 220
  2872    and only the body is presented (the empty line separating the headers
  2873    and body MUST NOT be included).
  2874 
  2875 6.2.3.3.  Examples
  2876 
  2877    Example of a successful retrieval of the body of an article
  2878    (explicitly not using an article number):
  2879 
  2880       [C] GROUP misc.test
  2881       [S] 211 1234 3000234 3002322 misc.test
  2882       [C] BODY
  2883       [S] 222 3000234 <45223423@example.com>
  2884       [S] This is just a test article.
  2885       [S] .
  2886 
  2887    Example of a successful retrieval of the body of an article by
  2888    message-id:
  2889 
  2890       [C] BODY <45223423@example.com>
  2891       [S] 222 0 <45223423@example.com>
  2892       [S] This is just a test article.
  2893       [S] .
  2894 
  2895    Example of an unsuccessful retrieval of the body of an article by
  2896    message-id:
  2897 
  2898       [C] BODY <i.am.not.there@example.com>
  2899       [S] 430 No Such Article Found
  2900 
  2901 
  2902 
  2903 
  2904 
  2905 
  2906 
  2907 
  2908 
  2909 Feather                     Standards Track                    [Page 52]
  2910 
  2911 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2912 
  2913 
  2914    Example of an unsuccessful retrieval of the body of an article by
  2915    number:
  2916 
  2917       [C] GROUP misc.test
  2918       [S] 211 1234 3000234 3002322 misc.test
  2919       [C] BODY 300256
  2920       [S] 423 No article with that number
  2921 
  2922    Example of an unsuccessful retrieval of the body of an article by
  2923    number because no newsgroup was selected first:
  2924 
  2925       [Assumes currently selected newsgroup is invalid.]
  2926       [C] BODY 300256
  2927       [S] 412 No newsgroup selected
  2928 
  2929    Example of an attempt to retrieve the body of an article when the
  2930    currently selected newsgroup is empty:
  2931 
  2932       [C] GROUP example.empty.newsgroup
  2933       [S] 211 0 0 0 example.empty.newsgroup
  2934       [C] BODY
  2935       [S] 420 No current article selected
  2936 
  2937 6.2.4.  STAT
  2938 
  2939 6.2.4.1.  Usage
  2940 
  2941    This command is mandatory.
  2942 
  2943    Syntax
  2944      STAT message-id
  2945      STAT number
  2946      STAT
  2947 
  2948    Responses
  2949 
  2950    First form (message-id specified)
  2951      223 0|n message-id    Article exists
  2952      430                   No article with that message-id
  2953 
  2954    Second form (article number specified)
  2955      223 n message-id      Article exists
  2956      412                   No newsgroup selected
  2957      423                   No article with that number
  2958 
  2959 
  2960 
  2961 
  2962 
  2963 
  2964 
  2965 Feather                     Standards Track                    [Page 53]
  2966 
  2967 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  2968 
  2969 
  2970    Third form (current article number used)
  2971      223 n message-id      Article exists
  2972      412                   No newsgroup selected
  2973      420                   Current article number is invalid
  2974 
  2975    Parameters
  2976      number        Requested article number
  2977      n             Returned article number
  2978      message-id    Article message-id
  2979 
  2980 6.2.4.2.  Description
  2981 
  2982    The STAT command behaves identically to the ARTICLE command except
  2983    that, if the article exists, it is NOT presented to the client and
  2984    the response code is 223 instead of 220.  Note that the response is
  2985    NOT multi-line.
  2986 
  2987    This command allows the client to determine whether an article exists
  2988    and, in the second and third forms, what its message-id is, without
  2989    having to process an arbitrary amount of text.
  2990 
  2991 6.2.4.3.  Examples
  2992 
  2993    Example of STAT on an existing article (explicitly not using an
  2994    article number):
  2995 
  2996       [C] GROUP misc.test
  2997       [S] 211 1234 3000234 3002322 misc.test
  2998       [C] STAT
  2999       [S] 223 3000234 <45223423@example.com>
  3000 
  3001    Example of STAT on an existing article by message-id:
  3002 
  3003       [C] STAT <45223423@example.com>
  3004       [S] 223 0 <45223423@example.com>
  3005 
  3006    Example of STAT on an article not on the server by message-id:
  3007 
  3008       [C] STAT <i.am.not.there@example.com>
  3009       [S] 430 No Such Article Found
  3010 
  3011    Example of STAT on an article not in the server by number:
  3012 
  3013       [C] GROUP misc.test
  3014       [S] 211 1234 3000234 3002322 misc.test
  3015       [C] STAT 300256
  3016       [S] 423 No article with that number
  3017 
  3018 
  3019 
  3020 
  3021 Feather                     Standards Track                    [Page 54]
  3022 
  3023 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3024 
  3025 
  3026    Example of STAT on an article by number when no newsgroup was
  3027    selected first:
  3028 
  3029       [Assumes currently selected newsgroup is invalid.]
  3030       [C] STAT 300256
  3031       [S] 412 No newsgroup selected
  3032 
  3033    Example of STAT on an article when the currently selected newsgroup
  3034    is empty:
  3035 
  3036       [C] GROUP example.empty.newsgroup
  3037       [S] 211 0 0 0 example.empty.newsgroup
  3038       [C] STAT
  3039       [S] 420 No current article selected
  3040 
  3041    Example of STAT by message-id on a server that sometimes reports the
  3042    actual article number:
  3043 
  3044       [C] GROUP misc.test
  3045       [S] 211 1234 3000234 3002322 misc.test
  3046       [C] STAT
  3047       [S] 223 3000234 <45223423@example.com>
  3048       [C] STAT <45223423@example.com>
  3049       [S] 223 0 <45223423@example.com>
  3050       [C] STAT <45223423@example.com>
  3051       [S] 223 3000234 <45223423@example.com>
  3052       [C] GROUP example.empty.newsgroup
  3053       [S] 211 0 0 0 example.empty.newsgroup
  3054       [C] STAT <45223423@example.com>
  3055       [S] 223 0 <45223423@example.com>
  3056       [C] GROUP alt.crossposts
  3057       [S] 211 9999 111111 222222 alt.crossposts
  3058       [C] STAT <45223423@example.com>
  3059       [S] 223 123456 <45223423@example.com>
  3060       [C] STAT
  3061       [S] 223 111111 <23894720@example.com>
  3062 
  3063    The first STAT command establishes the identity of an article in the
  3064    group.  The second and third show that the server may, but need not,
  3065    give the article number when the message-id is specified.  The fourth
  3066    STAT command shows that zero must be specified if the article isn't
  3067    in the currently selected newsgroup.  The fifth shows that the
  3068    number, if provided, must be that relating to the currently selected
  3069    newsgroup.  The last one shows that the current article number is
  3070    still not changed by the use of STAT with a message-id even if it
  3071    returns an article number.
  3072 
  3073 
  3074 
  3075 
  3076 
  3077 Feather                     Standards Track                    [Page 55]
  3078 
  3079 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3080 
  3081 
  3082 6.3.  Article Posting
  3083 
  3084    Article posting is done in one of two ways: individual article
  3085    posting from news-reading clients using POST, and article transfer
  3086    from other news servers using IHAVE.
  3087 
  3088 6.3.1.  POST
  3089 
  3090 6.3.1.1.  Usage
  3091 
  3092    Indicating capability: POST
  3093 
  3094    This command MUST NOT be pipelined.
  3095 
  3096    Syntax
  3097      POST
  3098 
  3099    Responses
  3100 
  3101    Initial responses
  3102      340    Send article to be posted
  3103      440    Posting not permitted
  3104 
  3105    Subsequent responses
  3106      240    Article received OK
  3107      441    Posting failed
  3108 
  3109 6.3.1.2.  Description
  3110 
  3111    If posting is allowed, a 340 response MUST be returned to indicate
  3112    that the article to be posted should be sent.  If posting is
  3113    prohibited for some installation-dependent reason, a 440 response
  3114    MUST be returned.
  3115 
  3116    If posting is permitted, the article MUST be in the format specified
  3117    in Section 3.6 and MUST be sent by the client to the server as a
  3118    multi-line data block (see Section 3.1.1).  Thus a single dot (".")
  3119    on a line indicates the end of the text, and lines starting with a
  3120    dot in the original text have that dot doubled during transmission.
  3121 
  3122    Following the presentation of the termination sequence by the client,
  3123    the server MUST return a response indicating success or failure of
  3124    the article transfer.  Note that response codes 340 and 440 are used
  3125    in direct response to the POST command while 240 and 441 are returned
  3126    after the article is sent.
  3127 
  3128 
  3129 
  3130 
  3131 
  3132 
  3133 Feather                     Standards Track                    [Page 56]
  3134 
  3135 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3136 
  3137 
  3138    A response of 240 SHOULD indicate that, barring unforeseen server
  3139    errors, the posted article will be made available on the server
  3140    and/or transferred to other servers, as appropriate, possibly
  3141    following further processing.  In other words, articles not wanted by
  3142    the server SHOULD be rejected with a 441 response, rather than being
  3143    accepted and then discarded silently.  However, the client SHOULD NOT
  3144    assume that the article has been successfully transferred unless it
  3145    receives an affirmative response from the server and SHOULD NOT
  3146    assume that it is being made available to other clients without
  3147    explicitly checking (for example, using the STAT command).
  3148 
  3149    If the session is interrupted before the response is received, it is
  3150    possible that an affirmative response was sent but has been lost.
  3151    Therefore, in any subsequent session, the client SHOULD either check
  3152    whether the article was successfully posted before resending or
  3153    ensure that the server will allocate the same message-id to the new
  3154    attempt (see Appendix A.2).  The latter approach is preferred since
  3155    the article might not have been made available for reading yet (for
  3156    example, it may have to go through a moderation process).
  3157 
  3158 6.3.1.3.  Examples
  3159 
  3160    Example of a successful posting:
  3161 
  3162       [C] POST
  3163       [S] 340 Input article; end with <CR-LF>.<CR-LF>
  3164       [C] From: "Demo User" <nobody@example.net>
  3165       [C] Newsgroups: misc.test
  3166       [C] Subject: I am just a test article
  3167       [C] Organization: An Example Net
  3168       [C]
  3169       [C] This is just a test article.
  3170       [C] .
  3171       [S] 240 Article received OK
  3172 
  3173    Example of an unsuccessful posting:
  3174 
  3175       [C] POST
  3176       [S] 340 Input article; end with <CR-LF>.<CR-LF>
  3177       [C] From: "Demo User" <nobody@example.net>
  3178       [C] Newsgroups: misc.test
  3179       [C] Subject: I am just a test article
  3180       [C] Organization: An Example Net
  3181       [C]
  3182       [C] This is just a test article.
  3183       [C] .
  3184       [S] 441 Posting failed
  3185 
  3186 
  3187 
  3188 
  3189 Feather                     Standards Track                    [Page 57]
  3190 
  3191 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3192 
  3193 
  3194    Example of an attempt to post when posting is not allowed:
  3195 
  3196       [Initial connection set-up completed.]
  3197       [S] 201 NNTP Service Ready, posting prohibited
  3198       [C] POST
  3199       [S] 440 Posting not permitted
  3200 
  3201 6.3.2.  IHAVE
  3202 
  3203 6.3.2.1.  Usage
  3204 
  3205    Indicating capability: IHAVE
  3206 
  3207    This command MUST NOT be pipelined.
  3208 
  3209    Syntax
  3210      IHAVE message-id
  3211 
  3212    Responses
  3213 
  3214    Initial responses
  3215      335    Send article to be transferred
  3216      435    Article not wanted
  3217      436    Transfer not possible; try again later
  3218 
  3219    Subsequent responses
  3220      235    Article transferred OK
  3221      436    Transfer failed; try again later
  3222      437    Transfer rejected; do not retry
  3223 
  3224    Parameters
  3225      message-id    Article message-id
  3226 
  3227 6.3.2.2.  Description
  3228 
  3229    The IHAVE command informs the server that the client has an article
  3230    with the specified message-id.  If the server desires a copy of that
  3231    article, a 335 response MUST be returned, instructing the client to
  3232    send the entire article.  If the server does not want the article
  3233    (if, for example, the server already has a copy of it), a 435
  3234    response MUST be returned, indicating that the article is not wanted.
  3235    Finally, if the article isn't wanted immediately but the client
  3236    should retry later if possible (if, for example, another client is in
  3237    the process of sending the same article to the server), a 436
  3238    response MUST be returned.
  3239 
  3240 
  3241 
  3242 
  3243 
  3244 
  3245 Feather                     Standards Track                    [Page 58]
  3246 
  3247 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3248 
  3249 
  3250    If transmission of the article is requested, the client MUST send the
  3251    entire article, including headers and body, to the server as a
  3252    multi-line data block (see Section 3.1.1).  Thus, a single dot (".")
  3253    on a line indicates the end of the text, and lines starting with a
  3254    dot in the original text have that dot doubled during transmission.
  3255    The server MUST return a 235 response, indicating that the article
  3256    was successfully transferred; a 436 response, indicating that the
  3257    transfer failed but should be tried again later; or a 437 response,
  3258    indicating that the article was rejected.
  3259 
  3260    This function differs from the POST command in that it is intended
  3261    for use in transferring already-posted articles between hosts.  It
  3262    SHOULD NOT be used when the client is a personal news-reading
  3263    program, since use of this command indicates that the article has
  3264    already been posted at another site and is simply being forwarded
  3265    from another host.  However, despite this, the server MAY elect not
  3266    to post or forward the article if, after further examination of the
  3267    article, it deems it inappropriate to do so.  Reasons for such
  3268    subsequent rejection of an article may include problems such as
  3269    inappropriate newsgroups or distributions, disc space limitations,
  3270    article lengths, garbled headers, and the like.  These are typically
  3271    restrictions enforced by the server host's news software and not
  3272    necessarily by the NNTP server itself.
  3273 
  3274    The client SHOULD NOT assume that the article has been successfully
  3275    transferred unless it receives an affirmative response from the
  3276    server.  A lack of response (such as a dropped network connection or
  3277    a network timeout) SHOULD be treated the same as a 436 response.
  3278 
  3279    Because some news server software may not immediately be able to
  3280    determine whether an article is suitable for posting or forwarding,
  3281    an NNTP server MAY acknowledge the successful transfer of the article
  3282    (with a 235 response) but later silently discard it.
  3283 
  3284 
  3285 
  3286 
  3287 
  3288 
  3289 
  3290 
  3291 
  3292 
  3293 
  3294 
  3295 
  3296 
  3297 
  3298 
  3299 
  3300 
  3301 Feather                     Standards Track                    [Page 59]
  3302 
  3303 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3304 
  3305 
  3306 6.3.2.3.  Examples
  3307 
  3308    Example of successfully sending an article to another site:
  3309 
  3310       [C] IHAVE <i.am.an.article.you.will.want@example.com>
  3311       [S] 335 Send it; end with <CR-LF>.<CR-LF>
  3312       [C] Path: pathost!demo!somewhere!not-for-mail
  3313       [C] From: "Demo User" <nobody@example.com>
  3314       [C] Newsgroups: misc.test
  3315       [C] Subject: I am just a test article
  3316       [C] Date: 6 Oct 1998 04:38:40 -0500
  3317       [C] Organization: An Example Com, San Jose, CA
  3318       [C] Message-ID: <i.am.an.article.you.will.want@example.com>
  3319       [C]
  3320       [C] This is just a test article.
  3321       [C] .
  3322       [S] 235 Article transferred OK
  3323 
  3324    Example of sending an article to another site that rejects it.  Note
  3325    that the message-id in the IHAVE command is not the same as the one
  3326    in the article headers; while this is bad practice and SHOULD NOT be
  3327    done, it is not forbidden.
  3328 
  3329       [C] IHAVE <i.am.an.article.you.will.want@example.com>
  3330       [S] 335 Send it; end with <CR-LF>.<CR-LF>
  3331       [C] Path: pathost!demo!somewhere!not-for-mail
  3332       [C] From: "Demo User" <nobody@example.com>
  3333       [C] Newsgroups: misc.test
  3334       [C] Subject: I am just a test article
  3335       [C] Date: 6 Oct 1998 04:38:40 -0500
  3336       [C] Organization: An Example Com, San Jose, CA
  3337       [C] Message-ID: <i.am.an.article.you.have@example.com>
  3338       [C]
  3339       [C] This is just a test article.
  3340       [C] .
  3341       [S] 437 Article rejected; don't send again
  3342 
  3343 
  3344 
  3345 
  3346 
  3347 
  3348 
  3349 
  3350 
  3351 
  3352 
  3353 
  3354 
  3355 
  3356 
  3357 Feather                     Standards Track                    [Page 60]
  3358 
  3359 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3360 
  3361 
  3362    Example of sending an article to another site where the transfer
  3363    fails:
  3364 
  3365       [C] IHAVE <i.am.an.article.you.will.want@example.com>
  3366       [S] 335 Send it; end with <CR-LF>.<CR-LF>
  3367       [C] Path: pathost!demo!somewhere!not-for-mail
  3368       [C] From: "Demo User" <nobody@example.com>
  3369       [C] Newsgroups: misc.test
  3370       [C] Subject: I am just a test article
  3371       [C] Date: 6 Oct 1998 04:38:40 -0500
  3372       [C] Organization: An Example Com, San Jose, CA
  3373       [C] Message-ID: <i.am.an.article.you.will.want@example.com>
  3374       [C]
  3375       [C] This is just a test article.
  3376       [C] .
  3377       [S] 436 Transfer failed
  3378 
  3379    Example of sending an article to a site that already has it:
  3380 
  3381       [C] IHAVE <i.am.an.article.you.have@example.com>
  3382       [S] 435 Duplicate
  3383 
  3384    Example of sending an article to a site that requests that the
  3385    article be tried again later:
  3386 
  3387       [C] IHAVE <i.am.an.article.you.defer@example.com>
  3388       [S] 436 Retry later
  3389 
  3390 7.  Information Commands
  3391 
  3392    This section lists other commands that may be used at any time
  3393    between the beginning of a session and its termination.  Using these
  3394    commands does not alter any state information, but the response
  3395    generated from their use may provide useful information to clients.
  3396 
  3397 7.1.  DATE
  3398 
  3399 7.1.1.  Usage
  3400 
  3401    Indicating capability: READER
  3402 
  3403    Syntax
  3404      DATE
  3405 
  3406    Responses
  3407      111 yyyymmddhhmmss    Server date and time
  3408 
  3409 
  3410 
  3411 
  3412 
  3413 Feather                     Standards Track                    [Page 61]
  3414 
  3415 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3416 
  3417 
  3418    Parameters
  3419      yyyymmddhhmmss    Current UTC date and time on server
  3420 
  3421 7.1.2.  Description
  3422 
  3423    This command exists to help clients find out the current Coordinated
  3424    Universal Time [TF.686-1] from the server's perspective.  This
  3425    command SHOULD NOT be used as a substitute for NTP [RFC1305] but to
  3426    provide information that might be useful when using the NEWNEWS
  3427    command (see Section 7.4).
  3428 
  3429    The DATE command MUST return a timestamp from the same clock as is
  3430    used for determining article arrival and group creation times (see
  3431    Section 6).  This clock SHOULD be monotonic, and adjustments SHOULD
  3432    be made by running it fast or slow compared to "real" time rather
  3433    than by making sudden jumps.  A system providing NNTP service SHOULD
  3434    keep the system clock as accurate as possible, either with NTP or by
  3435    some other method.
  3436 
  3437    The server MUST return a 111 response specifying the date and time on
  3438    the server in the form yyyymmddhhmmss.  This date and time is in
  3439    Coordinated Universal Time.
  3440 
  3441 7.1.3.  Examples
  3442 
  3443       [C] DATE
  3444       [S] 111 19990623135624
  3445 
  3446 7.2.  HELP
  3447 
  3448 7.2.1.  Usage
  3449 
  3450    This command is mandatory.
  3451 
  3452    Syntax
  3453      HELP
  3454 
  3455    Responses
  3456      100    Help text follows (multi-line)
  3457 
  3458 7.2.2.  Description
  3459 
  3460    This command provides a short summary of the commands that are
  3461    understood by this implementation of the server.  The help text will
  3462    be presented as a multi-line data block following the 100 response
  3463    code.
  3464 
  3465 
  3466 
  3467 
  3468 
  3469 Feather                     Standards Track                    [Page 62]
  3470 
  3471 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3472 
  3473 
  3474    This text is not guaranteed to be in any particular format (but must
  3475    be UTF-8) and MUST NOT be used by clients as a replacement for the
  3476    CAPABILITIES command described in Section 5.2.
  3477 
  3478 7.2.3.  Examples
  3479 
  3480       [C] HELP
  3481       [S] 100 Help text follows
  3482       [S] This is some help text.  There is no specific
  3483       [S] formatting requirement for this test, though
  3484       [S] it is customary for it to list the valid commands
  3485       [S] and give a brief definition of what they do.
  3486       [S] .
  3487 
  3488 7.3.  NEWGROUPS
  3489 
  3490 7.3.1.  Usage
  3491 
  3492    Indicating capability: READER
  3493 
  3494    Syntax
  3495      NEWGROUPS date time [GMT]
  3496 
  3497    Responses
  3498      231    List of new newsgroups follows (multi-line)
  3499 
  3500    Parameters
  3501      date    Date in yymmdd or yyyymmdd format
  3502      time    Time in hhmmss format
  3503 
  3504 7.3.2.  Description
  3505 
  3506    This command returns a list of newsgroups created on the server since
  3507    the specified date and time.  The results are in the same format as
  3508    the LIST ACTIVE command (see Section 7.6.3).  However, they MAY
  3509    include groups not available on the server (and so not returned by
  3510    LIST ACTIVE) and MAY omit groups for which the creation date is not
  3511    available.
  3512 
  3513    The date is specified as 6 or 8 digits in the format [xx]yymmdd,
  3514    where xx is the first two digits of the year (19-99), yy is the last
  3515    two digits of the year (00-99), mm is the month (01-12), and dd is
  3516    the day of the month (01-31).  Clients SHOULD specify all four digits
  3517    of the year.  If the first two digits of the year are not specified
  3518    (this is supported only for backward compatibility), the year is to
  3519    be taken from the current century if yy is smaller than or equal to
  3520    the current year, and the previous century otherwise.
  3521 
  3522 
  3523 
  3524 
  3525 Feather                     Standards Track                    [Page 63]
  3526 
  3527 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3528 
  3529 
  3530    The time is specified as 6 digits in the format hhmmss, where hh is
  3531    the hours in the 24-hour clock (00-23), mm is the minutes (00-59),
  3532    and ss is the seconds (00-60, to allow for leap seconds).  The token
  3533    "GMT" specifies that the date and time are given in Coordinated
  3534    Universal Time [TF.686-1]; if it is omitted, then the date and time
  3535    are specified in the server's local timezone.  Note that there is no
  3536    way of using the protocol specified in this document to establish the
  3537    server's local timezone.
  3538 
  3539    Note that an empty list is a possible valid response and indicates
  3540    that there are no new newsgroups since that date-time.
  3541 
  3542    Clients SHOULD make all queries using Coordinated Universal Time
  3543    (i.e., by including the "GMT" argument) when possible.
  3544 
  3545 7.3.3.  Examples
  3546 
  3547    Example where there are new groups:
  3548 
  3549       [C] NEWGROUPS 19990624 000000 GMT
  3550       [S] 231 list of new newsgroups follows
  3551       [S] alt.rfc-writers.recovery 4 1 y
  3552       [S] tx.natives.recovery 89 56 y
  3553       [S] .
  3554 
  3555    Example where there are no new groups:
  3556 
  3557       [C] NEWGROUPS 19990624 000000 GMT
  3558       [S] 231 list of new newsgroups follows
  3559       [S] .
  3560 
  3561 7.4.  NEWNEWS
  3562 
  3563 7.4.1.  Usage
  3564 
  3565    Indicating capability: NEWNEWS
  3566 
  3567    Syntax
  3568      NEWNEWS wildmat date time [GMT]
  3569 
  3570    Responses
  3571      230    List of new articles follows (multi-line)
  3572 
  3573    Parameters
  3574      wildmat    Newsgroups of interest
  3575      date       Date in yymmdd or yyyymmdd format
  3576      time       Time in hhmmss format
  3577 
  3578 
  3579 
  3580 
  3581 Feather                     Standards Track                    [Page 64]
  3582 
  3583 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3584 
  3585 
  3586 7.4.2.  Description
  3587 
  3588    This command returns a list of message-ids of articles posted or
  3589    received on the server, in the newsgroups whose names match the
  3590    wildmat, since the specified date and time.  One message-id is sent
  3591    on each line; the order of the response has no specific significance
  3592    and may vary from response to response in the same session.  A
  3593    message-id MAY appear more than once; if it does, it has the same
  3594    meaning as if it appeared only once.
  3595 
  3596    Date and time are in the same format as the NEWGROUPS command (see
  3597    Section 7.3).
  3598 
  3599    Note that an empty list is a possible valid response and indicates
  3600    that there is currently no new news in the relevant groups.
  3601 
  3602    Clients SHOULD make all queries in Coordinated Universal Time (i.e.,
  3603    by using the "GMT" argument) when possible.
  3604 
  3605 7.4.3.  Examples
  3606 
  3607    Example where there are new articles:
  3608 
  3609       [C] NEWNEWS news.*,sci.* 19990624 000000 GMT
  3610       [S] 230 list of new articles by message-id follows
  3611       [S] <i.am.a.new.article@example.com>
  3612       [S] <i.am.another.new.article@example.com>
  3613       [S] .
  3614 
  3615    Example where there are no new articles:
  3616 
  3617       [C] NEWNEWS alt.* 19990624 000000 GMT
  3618       [S] 230 list of new articles by message-id follows
  3619       [S] .
  3620 
  3621 7.5.  Time
  3622 
  3623    As described in Section 6, each article has an arrival timestamp.
  3624    Each newsgroup also has a creation timestamp.  These timestamps are
  3625    used by the NEWNEWS and NEWGROUP commands to construct their
  3626    responses.
  3627 
  3628    Clients can ensure that they do not have gaps in lists of articles or
  3629    groups by using the DATE command in the following manner:
  3630 
  3631    First session:
  3632       Issue DATE command and record result.
  3633       Issue NEWNEWS command using a previously chosen timestamp.
  3634 
  3635 
  3636 
  3637 Feather                     Standards Track                    [Page 65]
  3638 
  3639 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3640 
  3641 
  3642    Subsequent sessions:
  3643       Issue DATE command and hold result in temporary storage.
  3644       Issue NEWNEWS command using timestamp saved from previous session.
  3645       Overwrite saved timestamp with that currently in temporary
  3646       storage.
  3647 
  3648    In order to allow for minor errors, clients MAY want to adjust the
  3649    timestamp back by two or three minutes before using it in NEWNEWS.
  3650 
  3651 7.5.1.  Examples
  3652 
  3653    First session:
  3654 
  3655       [C] DATE
  3656       [S] 111 20010203112233
  3657       [C] NEWNEWS local.chat 20001231 235959 GMT
  3658       [S] 230 list follows
  3659       [S] <article.1@local.service>
  3660       [S] <article.2@local.service>
  3661       [S] <article.3@local.service>
  3662       [S] .
  3663 
  3664    Second session (the client has subtracted 3 minutes from the
  3665    timestamp returned previously):
  3666 
  3667       [C] DATE
  3668       [S] 111 20010204003344
  3669       [C] NEWNEWS local.chat 20010203 111933 GMT
  3670       [S] 230 list follows
  3671       [S] <article.3@local.service>
  3672       [S] <article.4@local.service>
  3673       [S] <article.5@local.service>
  3674       [S] .
  3675 
  3676    Note how <article.3@local.service> arrived in the 3 minute gap and so
  3677    is listed in both responses.
  3678 
  3679 7.6.  The LIST Commands
  3680 
  3681    The LIST family of commands all return information that is multi-line
  3682    and that can, in general, be expected not to change during the
  3683    session.  Often the information is related to newsgroups, in which
  3684    case the response has one line per newsgroup and a wildmat MAY be
  3685    provided to restrict the groups for which information is returned.
  3686 
  3687    The set of available keywords (including those provided by
  3688    extensions) is given in the capability list with capability label
  3689    LIST.
  3690 
  3691 
  3692 
  3693 Feather                     Standards Track                    [Page 66]
  3694 
  3695 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3696 
  3697 
  3698 7.6.1.  LIST
  3699 
  3700 7.6.1.1.  Usage
  3701 
  3702    Indicating capability: LIST
  3703 
  3704    Syntax
  3705      LIST [keyword [wildmat|argument]]
  3706 
  3707    Responses
  3708      215    Information follows (multi-line)
  3709 
  3710    Parameters
  3711      keyword     Information requested [1]
  3712      argument    Specific to keyword
  3713      wildmat     Groups of interest
  3714 
  3715    [1] If no keyword is provided, it defaults to ACTIVE.
  3716 
  3717 7.6.1.2.  Description
  3718 
  3719    The LIST command allows the server to provide blocks of information
  3720    to the client.  This information may be global or may be related to
  3721    newsgroups; in the latter case, the information may be returned
  3722    either for all groups or only for those matching a wildmat.  Each
  3723    block of information is represented by a different keyword.  The
  3724    command returns the specific information identified by the keyword.
  3725 
  3726    If the information is available, it is returned as a multi-line data
  3727    block following the 215 response code.  The format of the information
  3728    depends on the keyword.  The information MAY be affected by the
  3729    additional argument, but the format MUST NOT be.
  3730 
  3731    If the information is based on newsgroups and the optional wildmat
  3732    argument is specified, the response is limited to only the groups (if
  3733    any) whose names match the wildmat and for which the information is
  3734    available.
  3735 
  3736    Note that an empty list is a possible valid response; for a
  3737    newsgroup-based keyword, it indicates that there are no groups
  3738    meeting the above criteria.
  3739 
  3740    If the keyword is not recognised, or if an argument is specified and
  3741    the keyword does not expect one, a 501 response code MUST BE
  3742    returned.  If the keyword is recognised but the server does not
  3743    maintain the information, a 503 response code MUST BE returned.
  3744 
  3745 
  3746 
  3747 
  3748 
  3749 Feather                     Standards Track                    [Page 67]
  3750 
  3751 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3752 
  3753 
  3754    The LIST command MUST NOT change the visible state of the server in
  3755    any way; that is, the behaviour of subsequent commands MUST NOT be
  3756    affected by whether the LIST command was issued.  For example, it
  3757    MUST NOT make groups available that otherwise would not have been.
  3758 
  3759 7.6.1.3.  Examples
  3760 
  3761    Example of LIST with the ACTIVE keyword:
  3762 
  3763       [C] LIST ACTIVE
  3764       [S] 215 list of newsgroups follows
  3765       [S] misc.test 3002322 3000234 y
  3766       [S] comp.risks 442001 441099 m
  3767       [S] alt.rfc-writers.recovery 4 1 y
  3768       [S] tx.natives.recovery 89 56 y
  3769       [S] tx.natives.recovery.d 11 9 n
  3770       [S] .
  3771 
  3772    Example of LIST with no keyword:
  3773 
  3774       [C] LIST
  3775       [S] 215 list of newsgroups follows
  3776       [S] misc.test 3002322 3000234 y
  3777       [S] comp.risks 442001 441099 m
  3778       [S] alt.rfc-writers.recovery 4 1 y
  3779       [S] tx.natives.recovery 89 56 y
  3780       [S] tx.natives.recovery.d 11 9 n
  3781       [S] .
  3782 
  3783    The output is identical to that of the previous example.
  3784 
  3785    Example of LIST on a newsgroup-based keyword with and without
  3786    wildmat:
  3787 
  3788       [C] LIST ACTIVE.TIMES
  3789       [S] 215 information follows
  3790       [S] misc.test 930445408 <creatme@isc.org>
  3791       [S] alt.rfc-writers.recovery 930562309 <m@example.com>
  3792       [S] tx.natives.recovery 930678923 <sob@academ.com>
  3793       [S] .
  3794       [C] LIST ACTIVE.TIMES tx.*
  3795       [S] 215 information follows
  3796       [S] tx.natives.recovery 930678923 <sob@academ.com>
  3797       [S] .
  3798 
  3799 
  3800 
  3801 
  3802 
  3803 
  3804 
  3805 Feather                     Standards Track                    [Page 68]
  3806 
  3807 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3808 
  3809 
  3810    Example of LIST returning an error where the keyword is recognized
  3811    but the software does not maintain this information:
  3812 
  3813       [C] CAPABILITIES
  3814       [S] 101 Capability list:
  3815       [S] VERSION 2
  3816       [S] READER
  3817       [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
  3818       [S] .
  3819       [C] LIST XTRA.DATA
  3820       [S] 503 Data item not stored
  3821 
  3822    Example of LIST where the keyword is not recognised:
  3823 
  3824       [C] CAPABILITIES
  3825       [S] 101 Capability list:
  3826       [S] VERSION 2
  3827       [S] READER
  3828       [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
  3829       [S] .
  3830       [C] LIST DISTRIB.PATS
  3831       [S] 501 Syntax Error
  3832 
  3833 7.6.2.  Standard LIST Keywords
  3834 
  3835    This specification defines the following LIST keywords:
  3836 
  3837    +--------------+---------------+------------------------------------+
  3838    | Keyword      | Definition    | Status                             |
  3839    +--------------+---------------+------------------------------------+
  3840    | ACTIVE       | Section 7.6.3 | Mandatory if the READER capability |
  3841    |              |               | is advertised                      |
  3842    |              |               |                                    |
  3843    | ACTIVE.TIMES | Section 7.6.4 | Optional                           |
  3844    |              |               |                                    |
  3845    | DISTRIB.PATS | Section 7.6.5 | Optional                           |
  3846    |              |               |                                    |
  3847    | HEADERS      | Section 8.6   | Mandatory if the HDR capability is |
  3848    |              |               | advertised                         |
  3849    |              |               |                                    |
  3850    | NEWSGROUPS   | Section 7.6.6 | Mandatory if the READER capability |
  3851    |              |               | is advertised                      |
  3852    |              |               |                                    |
  3853    | OVERVIEW.FMT | Section 8.4   | Mandatory if the OVER capability   |
  3854    |              |               | is advertised                      |
  3855    +--------------+---------------+------------------------------------+
  3856 
  3857 
  3858 
  3859 
  3860 
  3861 Feather                     Standards Track                    [Page 69]
  3862 
  3863 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3864 
  3865 
  3866    Where one of these LIST keywords is supported by a server, it MUST
  3867    have the meaning given in the relevant sub-section.
  3868 
  3869 7.6.3.  LIST ACTIVE
  3870 
  3871    This keyword MUST be supported by servers advertising the READER
  3872    capability.
  3873 
  3874    LIST ACTIVE returns a list of valid newsgroups and associated
  3875    information.  If no wildmat is specified, the server MUST include
  3876    every group that the client is permitted to select with the GROUP
  3877    command (Section 6.1.1).  Each line of this list consists of four
  3878    fields separated from each other by one or more spaces:
  3879 
  3880    o  The name of the newsgroup.
  3881    o  The reported high water mark for the group.
  3882    o  The reported low water mark for the group.
  3883    o  The current status of the group on this server.
  3884 
  3885    The reported high and low water marks are as described in the GROUP
  3886    command (see Section 6.1.1), but note that they are in the opposite
  3887    order to the 211 response to that command.
  3888 
  3889    The status field is typically one of the following:
  3890 
  3891    "y" Posting is permitted.
  3892 
  3893    "n" Posting is not permitted.
  3894 
  3895    "m" Postings will be forwarded to the newsgroup moderator.
  3896 
  3897    The server SHOULD use these values when these meanings are required
  3898    and MUST NOT use them with any other meaning.  Other values for the
  3899    status may exist; the definition of these other values and the
  3900    circumstances under which they are returned may be specified in an
  3901    extension or may be private to the server.  A client SHOULD treat an
  3902    unrecognized status as giving no information.
  3903 
  3904    The status of a newsgroup only indicates how posts to that newsgroup
  3905    are normally processed and is not necessarily customised to the
  3906    specific client.  For example, if the current client is forbidden
  3907    from posting, then this will apply equally to groups with status "y".
  3908    Conversely, a client with special privileges (not defined by this
  3909    specification) might be able to post to a group with status "n".
  3910 
  3911 
  3912 
  3913 
  3914 
  3915 
  3916 
  3917 Feather                     Standards Track                    [Page 70]
  3918 
  3919 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3920 
  3921 
  3922    For example:
  3923 
  3924       [C] LIST ACTIVE
  3925       [S] 215 list of newsgroups follows
  3926       [S] misc.test 3002322 3000234 y
  3927       [S] comp.risks 442001 441099 m
  3928       [S] alt.rfc-writers.recovery 4 1 y
  3929       [S] tx.natives.recovery 89 56 y
  3930       [S] tx.natives.recovery.d 11 9 n
  3931       [S] .
  3932 
  3933    or, on an implementation that includes leading zeroes:
  3934 
  3935       [C] LIST ACTIVE
  3936       [S] 215 list of newsgroups follows
  3937       [S] misc.test 0003002322 0003000234 y
  3938       [S] comp.risks 0000442001 0000441099 m
  3939       [S] alt.rfc-writers.recovery 0000000004 0000000001 y
  3940       [S] tx.natives.recovery 0000000089 0000000056 y
  3941       [S] tx.natives.recovery.d 0000000011 0000000009 n
  3942       [S] .
  3943 
  3944    The information is newsgroup based, and a wildmat MAY be specified,
  3945    in which case the response is limited to only the groups (if any)
  3946    whose names match the wildmat.  For example:
  3947 
  3948       [C] LIST ACTIVE *.recovery
  3949       [S] 215 list of newsgroups follows
  3950       [S] alt.rfc-writers.recovery 4 1 y
  3951       [S] tx.natives.recovery 89 56 y
  3952       [S] .
  3953 
  3954 7.6.4.  LIST ACTIVE.TIMES
  3955 
  3956    This keyword is optional.
  3957 
  3958    The active.times list is maintained by some NNTP servers to contain
  3959    information about who created a particular newsgroup and when.  Each
  3960    line of this list consists of three fields separated from each other
  3961    by one or more spaces.  The first field is the name of the newsgroup.
  3962    The second is the time when this group was created on this news
  3963    server, measured in seconds since the start of January 1, 1970.  The
  3964    third is plain text intended to describe the entity that created the
  3965    newsgroup; it is often a mailbox as defined in RFC 2822 [RFC2822].
  3966    For example:
  3967 
  3968 
  3969 
  3970 
  3971 
  3972 
  3973 Feather                     Standards Track                    [Page 71]
  3974 
  3975 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  3976 
  3977 
  3978       [C] LIST ACTIVE.TIMES
  3979       [S] 215 information follows
  3980       [S] misc.test 930445408 <creatme@isc.org>
  3981       [S] alt.rfc-writers.recovery 930562309 <m@example.com>
  3982       [S] tx.natives.recovery 930678923 <sob@academ.com>
  3983       [S] .
  3984 
  3985    The list MAY omit newsgroups for which the information is unavailable
  3986    and MAY include groups not available on the server; in particular, it
  3987    MAY omit all groups created before the date and time of the oldest
  3988    entry.  The client MUST NOT assume that the list is complete or that
  3989    it matches the list returned by the LIST ACTIVE command
  3990    (Section 7.6.3).  The NEWGROUPS command (Section 7.3) may provide a
  3991    better way to access this information, and the results of the two
  3992    commands SHOULD be consistent except that, if the latter is invoked
  3993    with a date and time earlier than the oldest entry in active.times
  3994    list, its result may include extra groups.
  3995 
  3996    The information is newsgroup based, and a wildmat MAY be specified,
  3997    in which case the response is limited to only the groups (if any)
  3998    whose names match the wildmat.
  3999 
  4000 7.6.5.  LIST DISTRIB.PATS
  4001 
  4002    This keyword is optional.
  4003 
  4004    The distrib.pats list is maintained by some NNTP servers to assist
  4005    clients to choose a value for the content of the Distribution header
  4006    of a news article being posted.  Each line of this list consists of
  4007    three fields separated from each other by a colon (":").  The first
  4008    field is a weight, the second field is a wildmat (which may be a
  4009    simple newsgroup name), and the third field is a value for the
  4010    Distribution header content.  For example:
  4011 
  4012       [C] LIST DISTRIB.PATS
  4013       [S] 215 information follows
  4014       [S] 10:local.*:local
  4015       [S] 5:*:world
  4016       [S] 20:local.here.*:thissite
  4017       [S] .
  4018 
  4019    The client MAY use this information to construct an appropriate
  4020    Distribution header given the name of a newsgroup.  To do so, it
  4021    should determine the lines whose second field matches the newsgroup
  4022    name, select from among them the line with the highest weight (with 0
  4023    being the lowest), and use the value of the third field to construct
  4024    the Distribution header.
  4025 
  4026 
  4027 
  4028 
  4029 Feather                     Standards Track                    [Page 72]
  4030 
  4031 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4032 
  4033 
  4034    The information is not newsgroup based, and an argument MUST NOT be
  4035    specified.
  4036 
  4037 7.6.6.  LIST NEWSGROUPS
  4038 
  4039    This keyword MUST be supported by servers advertising the READER
  4040    capability.
  4041 
  4042    The newsgroups list is maintained by NNTP servers to contain the name
  4043    of each newsgroup that is available on the server and a short
  4044    description about the purpose of the group.  Each line of this list
  4045    consists of two fields separated from each other by one or more space
  4046    or TAB characters (the usual practice is a single TAB).  The first
  4047    field is the name of the newsgroup, and the second is a short
  4048    description of the group.  For example:
  4049 
  4050       [C] LIST NEWSGROUPS
  4051       [S] 215 information follows
  4052       [S] misc.test General Usenet testing
  4053       [S] alt.rfc-writers.recovery RFC Writers Recovery
  4054       [S] tx.natives.recovery Texas Natives Recovery
  4055       [S] .
  4056 
  4057    The list MAY omit newsgroups for which the information is unavailable
  4058    and MAY include groups not available on the server.  The client MUST
  4059    NOT assume that the list is complete or that it matches the list
  4060    returned by LIST ACTIVE.
  4061 
  4062    The description SHOULD be in UTF-8.  However, servers often obtain
  4063    the information from external sources.  These sources may have used
  4064    different encodings (ones that use octets in the range 128 to 255 in
  4065    some other manner) and, in that case, the server MAY pass it on
  4066    unchanged.  Therefore, clients MUST be prepared to receive such
  4067    descriptions.
  4068 
  4069    The information is newsgroup based, and a wildmat MAY be specified,
  4070    in which case the response is limited to only the groups (if any)
  4071    whose names match the wildmat.
  4072 
  4073 8.  Article Field Access Commands
  4074 
  4075    This section lists commands that may be used to access specific
  4076    article fields; that is, headers of articles and metadata about
  4077    articles.  These commands typically fetch data from an "overview
  4078    database", which is a database of headers extracted from incoming
  4079    articles plus metadata determined as the article arrives.  Only
  4080    certain fields are included in the database.
  4081 
  4082 
  4083 
  4084 
  4085 Feather                     Standards Track                    [Page 73]
  4086 
  4087 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4088 
  4089 
  4090    This section is based on the Overview/NOV database [ROBE1995]
  4091    developed by Geoff Collyer.
  4092 
  4093 8.1.  Article Metadata
  4094 
  4095    Article "metadata" is data about articles that does not occur within
  4096    the article itself.  Each metadata item has a name that MUST begin
  4097    with a colon (and that MUST NOT contain a colon elsewhere within it).
  4098    As with header names, metadata item names are not case sensitive.
  4099 
  4100    When generating a metadata item, the server MUST compute it for
  4101    itself and MUST NOT trust any related value provided in the article.
  4102    (In particular, a Lines or Bytes header in the article MUST NOT be
  4103    assumed to specify the correct number of lines or bytes in the
  4104    article.)  If the server has access to several non-identical copies
  4105    of an article, the value returned MUST be correct for any copy of
  4106    that article retrieved during the same session.
  4107 
  4108    This specification defines two metadata items: ":bytes" and ":lines".
  4109    Other metadata items may be defined by extensions.  The names of
  4110    metadata items defined by registered extensions MUST NOT begin with
  4111    ":x-".  To avoid the risk of a clash with a future registered
  4112    extension, the names of metadata items defined by private extensions
  4113    SHOULD begin with ":x-".
  4114 
  4115 8.1.1.  The :bytes Metadata Item
  4116 
  4117    The :bytes metadata item for an article is a decimal integer.  It
  4118    SHOULD equal the number of octets in the entire article: headers,
  4119    body, and separating empty line (counting a CRLF pair as two octets,
  4120    and excluding both the "." CRLF terminating the response and any "."
  4121    added for "dot-stuffing" purposes).
  4122 
  4123    Note to client implementers: some existing servers return a value
  4124    different from that above.  The commonest reasons for this are as
  4125    follows:
  4126 
  4127    o  Counting a CRLF pair as one octet.
  4128 
  4129    o  Including the "." character used for dot-stuffing in the number.
  4130 
  4131    o  Including the terminating "." CRLF in the number.
  4132 
  4133    o  Using one copy of an article for counting the octets but then
  4134       returning another one that differs in some (permitted) manner.
  4135 
  4136    Implementations should be prepared for such variation and MUST NOT
  4137    rely on the value being accurate.
  4138 
  4139 
  4140 
  4141 Feather                     Standards Track                    [Page 74]
  4142 
  4143 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4144 
  4145 
  4146 8.1.2.  The :lines Metadata Item
  4147 
  4148    The :lines metadata item for an article is a decimal integer.  It
  4149    MUST equal the number of lines in the article body (excluding the
  4150    empty line separating headers and body).  Equivalently, it is two
  4151    less than the number of CRLF pairs that the BODY command would return
  4152    for that article (the extra two are those following the response code
  4153    and the termination octet).
  4154 
  4155 8.2.  Database Consistency
  4156 
  4157    The information stored in the overview database may change over time.
  4158    If the database records the content or absence of a given field (that
  4159    is, a header or metadata item) for all articles, it is said to be
  4160    "consistent" for that field.  If it records the content of a header
  4161    for some articles but not for others that nevertheless included that
  4162    header, or if it records a metadata item for some articles but not
  4163    for others to which that item applies, it is said to be
  4164    "inconsistent" for that field.
  4165 
  4166    The LIST OVERVIEW.FMT command SHOULD list all the fields for which
  4167    the database is consistent at that moment.  It MAY omit such fields
  4168    (for example, if it is not known whether the database is consistent
  4169    or inconsistent).  It MUST NOT include fields for which the database
  4170    is inconsistent or that are not stored in the database.  Therefore,
  4171    if a header appears in the LIST OVERVIEW.FMT output but not in the
  4172    OVER output for a given article, that header does not appear in the
  4173    article (similarly for metadata items).
  4174 
  4175    These rules assume that the fields being stored in the database
  4176    remain constant for long periods of time, and therefore the database
  4177    will be consistent.  When the set of fields to be stored is changed,
  4178    it will be inconsistent until either the database is rebuilt or the
  4179    only articles remaining are those received since the change.
  4180    Therefore, the output from LIST OVERVIEW.FMT needs to be altered
  4181    twice.  Firstly, before any fields stop being stored they MUST be
  4182    removed from the output; then, when the database is once more known
  4183    to be consistent, the new fields SHOULD be added to the output.
  4184 
  4185    If the HDR command uses the overview database rather than taking
  4186    information directly from the articles, the same issues of
  4187    consistency and inconsistency apply, and the LIST HEADERS command
  4188    SHOULD take the same approach as the LIST OVERVIEW.FMT command in
  4189    resolving them.
  4190 
  4191 
  4192 
  4193 
  4194 
  4195 
  4196 
  4197 Feather                     Standards Track                    [Page 75]
  4198 
  4199 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4200 
  4201 
  4202 8.3.  OVER
  4203 
  4204 8.3.1.  Usage
  4205 
  4206    Indicating capability: OVER
  4207 
  4208    Syntax
  4209      OVER message-id
  4210      OVER range
  4211      OVER
  4212 
  4213    Responses
  4214 
  4215    First form (message-id specified)
  4216      224    Overview information follows (multi-line)
  4217      430    No article with that message-id
  4218 
  4219    Second form (range specified)
  4220      224    Overview information follows (multi-line)
  4221      412    No newsgroup selected
  4222      423    No articles in that range
  4223 
  4224    Third form (current article number used)
  4225      224    Overview information follows (multi-line)
  4226      412    No newsgroup selected
  4227      420    Current article number is invalid
  4228 
  4229    Parameters
  4230      range         Number(s) of articles
  4231      message-id    Message-id of article
  4232 
  4233 8.3.2.  Description
  4234 
  4235    The OVER command returns the contents of all the fields in the
  4236    database for an article specified by message-id, or from a specified
  4237    article or range of articles in the currently selected newsgroup.
  4238 
  4239    The message-id argument indicates a specific article.  The range
  4240    argument may be any of the following:
  4241 
  4242    o  An article number.
  4243 
  4244    o  An article number followed by a dash to indicate all following.
  4245 
  4246    o  An article number followed by a dash followed by another article
  4247       number.
  4248 
  4249    If neither is specified, the current article number is used.
  4250 
  4251 
  4252 
  4253 Feather                     Standards Track                    [Page 76]
  4254 
  4255 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4256 
  4257 
  4258    Support for the first (message-id) form is optional.  If it is
  4259    supported, the OVER capability line MUST include the argument
  4260    "MSGID".  Otherwise, the capability line MUST NOT include this
  4261    argument, and the OVER command MUST return the generic response code
  4262    503 when this form is used.
  4263 
  4264    If the information is available, it is returned as a multi-line data
  4265    block following the 224 response code and contains one line per
  4266    article, sorted in numerical order of article number.  (Note that
  4267    unless the argument is a range including a dash, there will be
  4268    exactly one line in the data block.)  Each line consists of a number
  4269    of fields separated by a TAB.  A field may be empty (in which case
  4270    there will be two adjacent TABs), and a sequence of trailing TABs may
  4271    be omitted.
  4272 
  4273    The first 8 fields MUST be the following, in order:
  4274 
  4275       "0" or article number (see below)
  4276       Subject header content
  4277       From header content
  4278       Date header content
  4279       Message-ID header content
  4280       References header content
  4281       :bytes metadata item
  4282       :lines metadata item
  4283 
  4284    If the article is specified by message-id (the first form of the
  4285    command), the article number MUST be replaced with zero, except that
  4286    if there is a currently selected newsgroup and the article is present
  4287    in that group, the server MAY use the article's number in that group.
  4288    (See the ARTICLE command (Section 6.2.1) and STAT examples
  4289    (Section 6.2.4.3) for more details.)  In the other two forms of the
  4290    command, the article number MUST be returned.
  4291 
  4292    Any subsequent fields are the contents of the other headers and
  4293    metadata held in the database.
  4294 
  4295    For the five mandatory headers, the content of each field MUST be
  4296    based on the content of the header (that is, with the header name and
  4297    following colon and space removed).  If the article does not contain
  4298    that header, or if the content is empty, the field MUST be empty.
  4299    For the two mandatory metadata items, the content of the field MUST
  4300    be just the value, with no other text.
  4301 
  4302    For all subsequent fields that contain headers, the content MUST be
  4303    the entire header line other than the trailing CRLF.  For all
  4304    subsequent fields that contain metadata, the field consists of the
  4305    metadata name, a single space, and then the value.
  4306 
  4307 
  4308 
  4309 Feather                     Standards Track                    [Page 77]
  4310 
  4311 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4312 
  4313 
  4314    For all fields, the value is processed by first removing all CRLF
  4315    pairs (that is, undoing any folding and removing the terminating
  4316    CRLF) and then replacing each TAB with a single space.  If there is
  4317    no such header in the article, no such metadata item, or no header or
  4318    item stored in the database for that article, the corresponding field
  4319    MUST be empty.
  4320 
  4321    Note that, after unfolding, the characters NUL, LF, and CR cannot
  4322    occur in the header of an article offered by a conformant server.
  4323    Nevertheless, servers SHOULD check for these characters and replace
  4324    each one by a single space (so that, for example, CR LF LF TAB will
  4325    become two spaces, since the CR and first LF will be removed by the
  4326    unfolding process).  This will encourage robustness in the face of
  4327    non-conforming data; it is also possible that future versions of this
  4328    specification could permit these characters to appear in articles.
  4329 
  4330    The server SHOULD NOT produce output for articles that no longer
  4331    exist.
  4332 
  4333    If the argument is a message-id and no such article exists, a 430
  4334    response MUST be returned.  If the argument is a range or is omitted
  4335    and the currently selected newsgroup is invalid, a 412 response MUST
  4336    be returned.  If the argument is a range and no articles in that
  4337    number range exist in the currently selected newsgroup, including the
  4338    case where the second number is less than the first one, a 423
  4339    response MUST be returned.  If the argument is omitted and the
  4340    current article number is invalid, a 420 response MUST be returned.
  4341 
  4342 8.3.3.  Examples
  4343 
  4344    In the first four examples, TAB has been replaced by vertical bar and
  4345    some lines have been folded for readability.
  4346 
  4347    Example of a successful retrieval of overview information for an
  4348    article (explicitly not using an article number):
  4349 
  4350       [C] GROUP misc.test
  4351       [S] 211 1234 3000234 3002322 misc.test
  4352       [C] OVER
  4353       [S] 224 Overview information follows
  4354       [S] 3000234|I am just a test article|"Demo User"
  4355           <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
  4356           <45223423@example.com>|<45454@example.net>|1234|
  4357           17|Xref: news.example.com misc.test:3000363
  4358       [S] .
  4359 
  4360 
  4361 
  4362 
  4363 
  4364 
  4365 Feather                     Standards Track                    [Page 78]
  4366 
  4367 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4368 
  4369 
  4370    Example of a successful retrieval of overview information for an
  4371    article by message-id:
  4372 
  4373       [C] CAPABILITIES
  4374       [S] 101 Capability list:
  4375       [S] VERSION 2
  4376       [S] READER
  4377       [S] OVER MSGID
  4378       [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
  4379       [S] .
  4380       [C] OVER <45223423@example.com>
  4381       [S] 224 Overview information follows
  4382       [S] 0|I am just a test article|"Demo User"
  4383           <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
  4384           <45223423@example.com>|<45454@example.net>|1234|
  4385           17|Xref: news.example.com misc.test:3000363
  4386       [S] .
  4387 
  4388    Note that the article number has been replaced by "0".
  4389 
  4390    Example of the same commands on a system that does not implement
  4391    retrieval by message-id:
  4392 
  4393       [C] CAPABILITIES
  4394       [S] 101 Capability list:
  4395       [S] VERSION 2
  4396       [S] READER
  4397       [S] OVER
  4398       [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
  4399       [S] .
  4400       [C] OVER <45223423@example.com>
  4401       [S] 503 Overview by message-id unsupported
  4402 
  4403 
  4404 
  4405 
  4406 
  4407 
  4408 
  4409 
  4410 
  4411 
  4412 
  4413 
  4414 
  4415 
  4416 
  4417 
  4418 
  4419 
  4420 
  4421 Feather                     Standards Track                    [Page 79]
  4422 
  4423 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4424 
  4425 
  4426    Example of a successful retrieval of overview information for a range
  4427    of articles:
  4428 
  4429       [C] GROUP misc.test
  4430       [S] 211 1234 3000234 3002322 misc.test
  4431       [C] OVER 3000234-3000240
  4432       [S] 224 Overview information follows
  4433       [S] 3000234|I am just a test article|"Demo User"
  4434           <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
  4435           <45223423@example.com>|<45454@example.net>|1234|
  4436           17|Xref: news.example.com misc.test:3000363
  4437       [S] 3000235|Another test article|nobody@nowhere.to
  4438           (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>||
  4439           4818|37||Distribution: fi
  4440       [S] 3000238|Re: I am just a test article|somebody@elsewhere.to|
  4441           7 Oct 1998 11:38:40 +1200|<kfwer3v@elsewhere.to>|
  4442           <45223423@to.to>|9234|51
  4443       [S] .
  4444 
  4445    Note the missing "References" and Xref headers in the second line,
  4446    the missing trailing fields in the first and last lines, and that
  4447    there are only results for those articles that still exist.
  4448 
  4449    Example of an unsuccessful retrieval of overview information on an
  4450    article by number:
  4451 
  4452       [C] GROUP misc.test
  4453       [S] 211 1234 3000234 3002322 misc.test
  4454       [C] OVER 300256
  4455       [S] 423 No such article in this group
  4456 
  4457    Example of an invalid range:
  4458 
  4459       [C] GROUP misc.test
  4460       [S] 211 1234 3000234 3002322 misc.test
  4461       [C] OVER 3000444-3000222
  4462       [S] 423 Empty range
  4463 
  4464    Example of an unsuccessful retrieval of overview information by
  4465    number because no newsgroup was selected first:
  4466 
  4467       [Assumes currently selected newsgroup is invalid.]
  4468       [C] OVER
  4469       [S] 412 No newsgroup selected
  4470 
  4471 
  4472 
  4473 
  4474 
  4475 
  4476 
  4477 Feather                     Standards Track                    [Page 80]
  4478 
  4479 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4480 
  4481 
  4482    Example of an attempt to retrieve information when the currently
  4483    selected newsgroup is empty:
  4484 
  4485       [C] GROUP example.empty.newsgroup
  4486       [S] 211 0 0 0 example.empty.newsgroup
  4487       [C] OVER
  4488       [S] 420 No current article selected
  4489 
  4490 8.4.  LIST OVERVIEW.FMT
  4491 
  4492 8.4.1.  Usage
  4493 
  4494    Indicating capability: OVER
  4495 
  4496    Syntax
  4497      LIST OVERVIEW.FMT
  4498 
  4499    Responses
  4500      215    Information follows (multi-line)
  4501 
  4502 8.4.2.  Description
  4503 
  4504    See Section 7.6.1 for general requirements of the LIST command.
  4505 
  4506    The LIST OVERVIEW.FMT command returns a description of the fields in
  4507    the database for which it is consistent (as described above).  The
  4508    information is returned as a multi-line data block following the 215
  4509    response code.  The information contains one line per field in the
  4510    order in which they are returned by the OVER command; the first 7
  4511    lines MUST (except for the case of letters) be exactly as follows:
  4512 
  4513        Subject:
  4514        From:
  4515        Date:
  4516        Message-ID:
  4517        References:
  4518        :bytes
  4519        :lines
  4520 
  4521    For compatibility with existing implementations, the last two lines
  4522    MAY instead be:
  4523 
  4524        Bytes:
  4525        Lines:
  4526 
  4527    even though they refer to metadata, not headers.
  4528 
  4529 
  4530 
  4531 
  4532 
  4533 Feather                     Standards Track                    [Page 81]
  4534 
  4535 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4536 
  4537 
  4538    All subsequent lines MUST consist of either a header name followed by
  4539    ":full", or the name of a piece of metadata.
  4540 
  4541    There are no leading or trailing spaces in the output.
  4542 
  4543    Note that the 7 fixed lines describe the 2nd to 8th fields of the
  4544    OVER output.  The "full" suffix (which may use either uppercase,
  4545    lowercase, or a mix) is a reminder that the corresponding fields
  4546    include the header name.
  4547 
  4548    This command MAY generate different results if it is used more than
  4549    once in a session.
  4550 
  4551    If the OVER command is not implemented, the meaning of the output
  4552    from this command is not specified, but it must still meet the above
  4553    syntactic requirements.
  4554 
  4555 8.4.3.  Examples
  4556 
  4557    Example of LIST OVERVIEW.FMT output corresponding to the example OVER
  4558    output above, in the preferred format:
  4559 
  4560       [C] LIST OVERVIEW.FMT
  4561       [S] 215 Order of fields in overview database.
  4562       [S] Subject:
  4563       [S] From:
  4564       [S] Date:
  4565       [S] Message-ID:
  4566       [S] References:
  4567       [S] :bytes
  4568       [S] :lines
  4569       [S] Xref:full
  4570       [S] Distribution:full
  4571       [S] .
  4572 
  4573 
  4574 
  4575 
  4576 
  4577 
  4578 
  4579 
  4580 
  4581 
  4582 
  4583 
  4584 
  4585 
  4586 
  4587 
  4588 
  4589 Feather                     Standards Track                    [Page 82]
  4590 
  4591 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4592 
  4593 
  4594    Example of LIST OVERVIEW.FMT output corresponding to the example OVER
  4595    output above, in the alternative format:
  4596 
  4597       [C] LIST OVERVIEW.FMT
  4598       [S] 215 Order of fields in overview database.
  4599       [S] Subject:
  4600       [S] From:
  4601       [S] Date:
  4602       [S] Message-ID:
  4603       [S] References:
  4604       [S] Bytes:
  4605       [S] Lines:
  4606       [S] Xref:FULL
  4607       [S] Distribution:FULL
  4608       [S] .
  4609 
  4610 8.5.  HDR
  4611 
  4612 8.5.1.  Usage
  4613 
  4614    Indicating capability: HDR
  4615 
  4616    Syntax
  4617      HDR field message-id
  4618      HDR field range
  4619      HDR field
  4620 
  4621    Responses
  4622 
  4623    First form (message-id specified)
  4624      225    Headers follow (multi-line)
  4625      430    No article with that message-id
  4626 
  4627    Second form (range specified)
  4628      225    Headers follow (multi-line)
  4629      412    No newsgroup selected
  4630      423    No articles in that range
  4631 
  4632    Third form (current article number used)
  4633      225    Headers follow (multi-line)
  4634      412    No newsgroup selected
  4635      420    Current article number is invalid
  4636 
  4637    Parameters
  4638      field         Name of field
  4639      range         Number(s) of articles
  4640      message-id    Message-id of article
  4641 
  4642 
  4643 
  4644 
  4645 Feather                     Standards Track                    [Page 83]
  4646 
  4647 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4648 
  4649 
  4650 8.5.2.  Description
  4651 
  4652    The HDR command provides access to specific fields from an article
  4653    specified by message-id, or from a specified article or range of
  4654    articles in the currently selected newsgroup.  It MAY take the
  4655    information directly from the articles or from the overview database.
  4656    In the case of headers, an implementation MAY restrict the use of
  4657    this command to a specific list of headers or MAY allow it to be used
  4658    with any header; it may behave differently when it is used with a
  4659    message-id argument and when it is used with a range or no argument.
  4660 
  4661    The required field argument is the name of a header with the colon
  4662    omitted (e.g., "subject") or the name of a metadata item including
  4663    the leading colon (e.g., ":bytes"), and is case insensitive.
  4664 
  4665    The message-id argument indicates a specific article.  The range
  4666    argument may be any of the following:
  4667 
  4668    o  An article number.
  4669 
  4670    o  An article number followed by a dash to indicate all following.
  4671 
  4672    o  An article number followed by a dash followed by another article
  4673       number.
  4674 
  4675    If neither is specified, the current article number is used.
  4676 
  4677    If the information is available, it is returned as a multi-line data
  4678    block following the 225 response code and contains one line for each
  4679    article in the range that exists.  (Note that unless the argument is
  4680    a range including a dash, there will be exactly one line in the data
  4681    block.)  The line consists of the article number, a space, and then
  4682    the contents of the field.  In the case of a header, the header name,
  4683    the colon, and the first space after the colon are all omitted.
  4684 
  4685    If the article is specified by message-id (the first form of the
  4686    command), the article number MUST be replaced with zero, except that
  4687    if there is a currently selected newsgroup and the article is present
  4688    in that group, the server MAY use the article's number in that group.
  4689    (See the ARTICLE command (Section 6.2.1) and STAT examples
  4690    (Section 6.2.4.3) for more details.)  In the other two forms of the
  4691    command, the article number MUST be returned.
  4692 
  4693    Header contents are modified as follows: all CRLF pairs are removed,
  4694    and then each TAB is replaced with a single space.  (Note that this
  4695    is the same transformation as is performed by the OVER command
  4696    (Section 8.3.2), and the same comment concerning NUL, CR, and LF
  4697    applies.)
  4698 
  4699 
  4700 
  4701 Feather                     Standards Track                    [Page 84]
  4702 
  4703 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4704 
  4705 
  4706    Note the distinction between headers and metadata appearing to have
  4707    the same meaning.  Headers are always taken unchanged from the
  4708    article; metadata are always calculated.  For example, a request for
  4709    "Lines" returns the contents of the "Lines" header of the specified
  4710    articles, if any, no matter whether they accurately state the number
  4711    of lines, while a request for ":lines" returns the line count
  4712    metadata, which is always the actual number of lines irrespective of
  4713    what any header may state.
  4714 
  4715    If the requested header is not present in the article, or if it is
  4716    present but empty, a line for that article is included in the output,
  4717    but the header content portion of the line is empty (the space after
  4718    the article number MAY be retained or omitted).  If the header occurs
  4719    in a given article more than once, only the content of the first
  4720    occurrence is returned by HDR.  If any article number in the provided
  4721    range does not exist in the group, no line for that article number is
  4722    included in the output.
  4723 
  4724    If the second argument is a message-id and no such article exists, a
  4725    430 response MUST be returned.  If the second argument is a range or
  4726    is omitted and the currently selected newsgroup is invalid, a 412
  4727    response MUST be returned.  If the second argument is a range and no
  4728    articles in that number range exist in the currently selected
  4729    newsgroup, including the case where the second number is less than
  4730    the first one, a 423 response MUST be returned.  If the second
  4731    argument is omitted and the current article number is invalid, a 420
  4732    response MUST be returned.
  4733 
  4734    A server MAY only allow HDR commands for a limited set of fields; it
  4735    may behave differently in this respect for the first (message-id)
  4736    form from how it would for the other forms.  If so, it MUST respond
  4737    with the generic 503 response to attempts to request other fields,
  4738    rather than return erroneous results, such as a successful empty
  4739    response.
  4740 
  4741    If HDR uses the overview database and it is inconsistent for the
  4742    requested field, the server MAY return what results it can, or it MAY
  4743    respond with the generic 503 response.  In the latter case, the field
  4744    MUST NOT appear in the output from LIST HEADERS.
  4745 
  4746 
  4747 
  4748 
  4749 
  4750 
  4751 
  4752 
  4753 
  4754 
  4755 
  4756 
  4757 Feather                     Standards Track                    [Page 85]
  4758 
  4759 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4760 
  4761 
  4762 8.5.3.  Examples
  4763 
  4764    Example of a successful retrieval of subject lines from a range of
  4765    articles (3000235 has no Subject header, and 3000236 is missing):
  4766 
  4767       [C] GROUP misc.test
  4768       [S] 211 1234 3000234 3002322 misc.test
  4769       [C] HDR Subject 3000234-3000238
  4770       [S] 225 Headers follow
  4771       [S] 3000234 I am just a test article
  4772       [S] 3000235
  4773       [S] 3000237 Re: I am just a test article
  4774       [S] 3000238 Ditto
  4775       [S] .
  4776 
  4777    Example of a successful retrieval of line counts from a range of
  4778    articles:
  4779 
  4780       [C] GROUP misc.test
  4781       [S] 211 1234 3000234 3002322 misc.test
  4782       [C] HDR :lines 3000234-3000238
  4783       [S] 225 Headers follow
  4784       [S] 3000234 42
  4785       [S] 3000235 5
  4786       [S] 3000237 11
  4787       [S] 3000238 2378
  4788       [S] .
  4789 
  4790    Example of a successful retrieval of the subject line from an article
  4791    by message-id:
  4792 
  4793       [C] GROUP misc.test
  4794       [S] 211 1234 3000234 3002322 misc.test
  4795       [C] HDR subject <i.am.a.test.article@example.com>
  4796       [S] 225 Header information follows
  4797       [S] 0 I am just a test article
  4798       [S] .
  4799 
  4800    Example of a successful retrieval of the subject line from the
  4801    current article:
  4802 
  4803       [C] GROUP misc.test
  4804       [S] 211 1234 3000234 3002322 misc.test
  4805       [C] HDR subject
  4806       [S] 225 Header information follows
  4807       [S] 3000234 I am just a test article
  4808       [S] .
  4809 
  4810 
  4811 
  4812 
  4813 Feather                     Standards Track                    [Page 86]
  4814 
  4815 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4816 
  4817 
  4818    Example of an unsuccessful retrieval of a header from an article by
  4819    message-id:
  4820 
  4821       [C] HDR subject <i.am.not.there@example.com>
  4822       [S] 430 No Such Article Found
  4823 
  4824    Example of an unsuccessful retrieval of headers from articles by
  4825    number because no newsgroup was selected first:
  4826 
  4827       [Assumes currently selected newsgroup is invalid.]
  4828       [C] HDR subject 300256-
  4829       [S] 412 No newsgroup selected
  4830 
  4831    Example of an unsuccessful retrieval of headers because the currently
  4832    selected newsgroup is empty:
  4833 
  4834       [C] GROUP example.empty.newsgroup
  4835       [S] 211 0 0 0 example.empty.newsgroup
  4836       [C] HDR subject 1-
  4837       [S] 423 No articles in that range
  4838 
  4839    Example of an unsuccessful retrieval of headers because the server
  4840    does not allow HDR commands for that header:
  4841 
  4842       [C] GROUP misc.test
  4843       [S] 211 1234 3000234 3002322 misc.test
  4844       [C] HDR Content-Type 3000234-3000238
  4845       [S] 503 HDR not permitted on Content-Type
  4846 
  4847 8.6.  LIST HEADERS
  4848 
  4849 8.6.1.  Usage
  4850 
  4851    Indicating capability: HDR
  4852 
  4853    Syntax
  4854      LIST HEADERS [MSGID|RANGE]
  4855 
  4856    Responses
  4857      215    Field list follows (multi-line)
  4858 
  4859    Parameters
  4860      MSGID    Requests list for access by message-id
  4861      RANGE    Requests list for access by range
  4862 
  4863 
  4864 
  4865 
  4866 
  4867 
  4868 
  4869 Feather                     Standards Track                    [Page 87]
  4870 
  4871 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4872 
  4873 
  4874 8.6.2.  Description
  4875 
  4876    See Section 7.6.1 for general requirements of the LIST command.
  4877 
  4878    The LIST HEADERS command returns a list of fields that may be
  4879    retrieved using the HDR command.
  4880 
  4881    The information is returned as a multi-line data block following the
  4882    215 response code and contains one line for each field name
  4883    (excluding the trailing colon for headers and including the leading
  4884    colon for metadata items).  If the implementation allows any header
  4885    to be retrieved, it MUST NOT include any header names in the list but
  4886    MUST include the special entry ":" (a single colon on its own).  It
  4887    MUST still explicitly list any metadata items that are available.
  4888    The order of items in the list is not significant; the server need
  4889    not even consistently return the same order.  The list MAY be empty
  4890    (though in this circumstance there is little point in providing the
  4891    HDR command).
  4892 
  4893    An implementation that also supports the OVER command SHOULD at least
  4894    permit all the headers and metadata items listed in the output from
  4895    the LIST OVERVIEW.FMT command.
  4896 
  4897    If the server treats the first form of the HDR command (message-id
  4898    specified) differently from the other two forms (range specified or
  4899    current article number used) in respect of which headers or metadata
  4900    items are available, then the following apply:
  4901 
  4902    o  If the MSGID argument is specified, the results MUST be those
  4903       available for the first form of the HDR command.
  4904 
  4905    o  If the RANGE argument is specified, the results MUST be those
  4906       available for the second and third forms of the HDR command.
  4907 
  4908    o  If no argument is specified, the results MUST be those available
  4909       in all forms of the HDR command (that is, it MUST only list those
  4910       items listed in both the previous cases).
  4911 
  4912    If the server does not treat the various forms differently, then it
  4913    MUST ignore any argument and always produce the same results (though
  4914    not necessarily always in the same order).
  4915 
  4916    If the HDR command is not implemented, the meaning of the output from
  4917    this command is not specified, but it must still meet the above
  4918    syntactic requirements.
  4919 
  4920 
  4921 
  4922 
  4923 
  4924 
  4925 Feather                     Standards Track                    [Page 88]
  4926 
  4927 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4928 
  4929 
  4930 8.6.3.  Examples
  4931 
  4932    Example of an implementation providing access to only a few headers:
  4933 
  4934       [C] LIST HEADERS
  4935       [S] 215 headers supported:
  4936       [S] Subject
  4937       [S] Message-ID
  4938       [S] Xref
  4939       [S] .
  4940 
  4941    Example of an implementation providing access to the same fields as
  4942    the first example in Section 8.4.3:
  4943 
  4944       [C] CAPABILITIES
  4945       [S] 101 Capability list:
  4946       [S] VERSION 2
  4947       [S] READER
  4948       [S] OVER
  4949       [S] HDR
  4950       [S] LIST ACTIVE NEWSGROUPS HEADERS OVERVIEW.FMT
  4951       [S] .
  4952       [C] LIST HEADERS
  4953       [S] 215 headers and metadata items supported:
  4954       [S] Date
  4955       [S] Distribution
  4956       [S] From
  4957       [S] Message-ID
  4958       [S] References
  4959       [S] Subject
  4960       [S] Xref
  4961       [S] :bytes
  4962       [S] :lines
  4963       [S] .
  4964 
  4965    Example of an implementation providing access to all headers:
  4966 
  4967       [C] LIST HEADERS
  4968       [S] 215 metadata items supported:
  4969       [S] :
  4970       [S] :lines
  4971       [S] :bytes
  4972       [S] :x-article-number
  4973       [S] .
  4974 
  4975 
  4976 
  4977 
  4978 
  4979 
  4980 
  4981 Feather                     Standards Track                    [Page 89]
  4982 
  4983 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  4984 
  4985 
  4986    Example of an implementation distinguishing the first form of the HDR
  4987    command from the other two forms:
  4988 
  4989       [C] LIST HEADERS RANGE
  4990       [S] 215 metadata items supported:
  4991       [S] :
  4992       [S] :lines
  4993       [S] :bytes
  4994       [S] .
  4995       [C] LIST HEADERS MSGID
  4996       [S] 215 headers and metadata items supported:
  4997       [S] Date
  4998       [S] Distribution
  4999       [S] From
  5000       [S] Message-ID
  5001       [S] References
  5002       [S] Subject
  5003       [S] :lines
  5004       [S] :bytes
  5005       [S] :x-article-number
  5006       [S] .
  5007       [C] LIST HEADERS
  5008       [S] 215 headers and metadata items supported:
  5009       [S] Date
  5010       [S] Distribution
  5011       [S] From
  5012       [S] Message-ID
  5013       [S] References
  5014       [S] Subject
  5015       [S] :lines
  5016       [S] :bytes
  5017       [S] .
  5018 
  5019    Note that :x-article-number does not appear in the last set of
  5020    output.
  5021 
  5022 9.  Augmented BNF Syntax for NNTP
  5023 
  5024 9.1.  Introduction
  5025 
  5026    Each of the following sections describes the syntax of a major
  5027    element of NNTP.  This syntax extends and refines the descriptions
  5028    elsewhere in this specification and should be given precedence when
  5029    resolving apparent conflicts.  Note that ABNF [RFC4234] strings are
  5030    case insensitive.  Non-terminals used in several places are defined
  5031    in a separate section at the end.
  5032 
  5033 
  5034 
  5035 
  5036 
  5037 Feather                     Standards Track                    [Page 90]
  5038 
  5039 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5040 
  5041 
  5042    Between them, the non-terminals <command-line>, <command-datastream>,
  5043    <command-continuation>, and <response> specify the text that flows
  5044    between client and server.  A consistent naming scheme is used in
  5045    this document for the non-terminals relating to each command, and
  5046    SHOULD be used by the specification of registered extensions.
  5047 
  5048    For each command, the sequence is as follows:
  5049 
  5050    o  The client sends an instance of <command-line>; the syntax for the
  5051       EXAMPLE command is <example-command>.
  5052 
  5053    o  If the client is one that immediately streams data, it sends an
  5054       instance of <command-datastream>; the syntax for the EXAMPLE
  5055       command is <example-datastream>.
  5056 
  5057    o  The server sends an instance of <response>.
  5058 
  5059       *  The initial response line is independent of the command that
  5060          generated it; if the 000 response has arguments, the syntax of
  5061          the initial line is <response-000-content>.
  5062 
  5063       *  If the response is multi-line, the initial line is followed by
  5064          a <multi-line-data-block>.  The syntax for the contents of this
  5065          block after "dot-stuffing" has been removed is (for the 000
  5066          response to the EXAMPLE command) <example-000-ml-content> and
  5067          is an instance of <multi-line-response-content>.
  5068 
  5069    o  While the latest response is one that indicates more data is
  5070       required (in general, a 3xx response):
  5071 
  5072       *  the client sends an instance of <command-continuation>; the
  5073          syntax for the EXAMPLE continuation following a 333 response is
  5074          <example-333-continuation>;
  5075 
  5076       *  the server sends another instance of <response>, as above.
  5077 
  5078    (There are no commands in this specification that immediately stream
  5079    data, but this non-terminal is defined for the convenience of
  5080    extensions.)
  5081 
  5082 
  5083 
  5084 
  5085 
  5086 
  5087 
  5088 
  5089 
  5090 
  5091 
  5092 
  5093 Feather                     Standards Track                    [Page 91]
  5094 
  5095 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5096 
  5097 
  5098 9.2.  Commands
  5099 
  5100    This syntax defines the non-terminal <command-line>, which represents
  5101    what is sent from the client to the server (see section 3.1 for
  5102    limits on lengths).
  5103 
  5104      command-line = command EOL
  5105      command = X-command
  5106      X-command = keyword *(WS token)
  5107 
  5108      command =/ article-command /
  5109            body-command /
  5110            capabilities-command /
  5111            date-command /
  5112            group-command /
  5113            hdr-command /
  5114            head-command /
  5115            help-command /
  5116            ihave-command /
  5117            last-command /
  5118            list-command /
  5119            listgroup-command /
  5120            mode-reader-command /
  5121            newgroups-command /
  5122            newnews-command /
  5123            next-command /
  5124            over-command /
  5125            post-command /
  5126            quit-command /
  5127            stat-command
  5128 
  5129      article-command = "ARTICLE" [WS article-ref]
  5130      body-command = "BODY" [WS article-ref]
  5131      capabilities-command = "CAPABILITIES" [WS keyword]
  5132      date-command = "DATE"
  5133      group-command = "GROUP" [WS newsgroup-name]
  5134      hdr-command = "HDR" WS header-meta-name [WS range-ref]
  5135      head-command = "HEAD" [WS article-ref]
  5136      help-command = "HELP"
  5137      ihave-command = "IHAVE" WS message-id
  5138      last-command = "LAST"
  5139      list-command = "LIST" [WS list-arguments]
  5140      listgroup-command = "LISTGROUP" [WS newsgroup-name [WS range]]
  5141      mode-reader-command = "MODE" WS "READER"
  5142      newgroups-command = "NEWGROUPS" WS date-time
  5143      newnews-command = "NEWNEWS" WS wildmat WS date-time
  5144      next-command = "NEXT"
  5145      over-command = "OVER" [WS range-ref]
  5146 
  5147 
  5148 
  5149 Feather                     Standards Track                    [Page 92]
  5150 
  5151 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5152 
  5153 
  5154      post-command = "POST"
  5155      quit-command = "QUIT"
  5156      stat-command = "STAT" [WS article-ref]
  5157 
  5158      article-ref = article-number / message-id
  5159      date = date2y / date4y
  5160      date4y = 4DIGIT 2DIGIT 2DIGIT
  5161      date2y = 2DIGIT 2DIGIT 2DIGIT
  5162      date-time = date WS time [WS "GMT"]
  5163      header-meta-name = header-name / metadata-name
  5164      list-arguments = keyword [WS token]
  5165      metadata-name = ":" 1*A-NOTCOLON
  5166      range = article-number ["-" [article-number]]
  5167      range-ref = range / message-id
  5168      time = 2DIGIT 2DIGIT 2DIGIT
  5169 
  5170 9.3.  Command Continuation
  5171 
  5172    This syntax defines the further material sent by the client in the
  5173    case of multi-stage commands and those that stream data.
  5174 
  5175      command-datastream = UNDEFINED
  5176        ; not used, provided as a hook for extensions
  5177      command-continuation = ihave-335-continuation /
  5178            post-340-continuation
  5179 
  5180      ihave-335-continuation = encoded-article
  5181      post-340-continuation = encoded-article
  5182 
  5183      encoded-article = multi-line-data-block
  5184        ; after undoing the "dot-stuffing", this MUST match <article>
  5185 
  5186 9.4.  Responses
  5187 
  5188 9.4.1.  Generic Responses
  5189 
  5190    This syntax defines the non-terminal <response>, which represents the
  5191    generic form of responses; that is, what is sent from the server to
  5192    the client in response to a <command> or a <command-continuation>.
  5193 
  5194      response = simple-response / multi-line-response
  5195      simple-response = initial-response-line
  5196      multi-line-response = initial-response-line multi-line-data-block
  5197 
  5198      initial-response-line =
  5199            initial-response-content [SP trailing-comment] CRLF
  5200      initial-response-content = X-initial-response-content
  5201      X-initial-response-content = 3DIGIT *(SP response-argument)
  5202 
  5203 
  5204 
  5205 Feather                     Standards Track                    [Page 93]
  5206 
  5207 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5208 
  5209 
  5210      response-argument = 1*A-CHAR
  5211      trailing-comment = *U-CHAR
  5212 
  5213 9.4.2.  Initial Response Line Contents
  5214 
  5215    This syntax defines the specific initial response lines for the
  5216    various commands in this specification (see section 3.1 for limits on
  5217    lengths).  Only those response codes with arguments are listed.
  5218 
  5219      initial-response-content =/ response-111-content /
  5220            response-211-content /
  5221            response-220-content /
  5222            response-221-content /
  5223            response-222-content /
  5224            response-223-content /
  5225            response-401-content
  5226 
  5227      response-111-content = "111" SP date4y time
  5228      response-211-content = "211" 3(SP article-number) SP newsgroup-name
  5229      response-220-content = "220" SP article-number SP message-id
  5230      response-221-content = "221" SP article-number SP message-id
  5231      response-222-content = "222" SP article-number SP message-id
  5232      response-223-content = "223" SP article-number SP message-id
  5233      response-401-content = "401" SP capability-label
  5234 
  5235 9.4.3.  Multi-line Response Contents
  5236 
  5237    This syntax defines the content of the various multi-line responses;
  5238    more precisely, it defines the part of the response in the multi-line
  5239    data block after any "dot-stuffing" has been undone.  The numeric
  5240    portion of each non-terminal name indicates the response code that is
  5241    followed by this data.
  5242 
  5243      multi-line-response-content = article-220-ml-content /
  5244            body-222-ml-content /
  5245            capabilities-101-ml-content /
  5246            hdr-225-ml-content /
  5247            head-221-ml-content /
  5248            help-100-ml-content /
  5249            list-215-ml-content /
  5250            listgroup-211-ml-content /
  5251            newgroups-231-ml-content /
  5252            newnews-230-ml-content /
  5253            over-224-ml-content
  5254 
  5255      article-220-ml-content = article
  5256      body-222-ml-content = body
  5257      capabilities-101-ml-content = version-line CRLF
  5258 
  5259 
  5260 
  5261 Feather                     Standards Track                    [Page 94]
  5262 
  5263 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5264 
  5265 
  5266            *(capability-line CRLF)
  5267      hdr-225-ml-content = *(article-number SP hdr-content CRLF)
  5268      head-221-ml-content = 1*header
  5269      help-100-ml-content = *(*U-CHAR CRLF)
  5270      list-215-ml-content = list-content
  5271      listgroup-211-ml-content = *(article-number CRLF)
  5272      newgroups-231-ml-content = active-groups-list
  5273      newnews-230-ml-content = *(message-id CRLF)
  5274      over-224-ml-content = *(article-number over-content CRLF)
  5275 
  5276      active-groups-list = *(newsgroup-name SPA article-number
  5277            SPA article-number SPA newsgroup-status CRLF)
  5278      hdr-content = *S-NONTAB
  5279      hdr-n-content = [(header-name ":" / metadata-name) SP hdr-content]
  5280      list-content = body
  5281      newsgroup-status = %x79 / %x6E / %x6D / private-status
  5282      over-content = 1*6(TAB hdr-content) /
  5283            7(TAB hdr-content) *(TAB hdr-n-content)
  5284      private-status = token ; except the values in newsgroup-status
  5285 
  5286 9.5.  Capability Lines
  5287 
  5288    This syntax defines the generic form of a capability line in the
  5289    capabilities list (see Section 3.3.1).
  5290 
  5291      capability-line = capability-entry
  5292      capability-entry = X-capability-entry
  5293      X-capability-entry = capability-label *(WS capability-argument)
  5294      capability-label = keyword
  5295      capability-argument = token
  5296 
  5297    This syntax defines the specific capability entries for the
  5298    capabilities in this specification.
  5299 
  5300      capability-entry =/
  5301            hdr-capability /
  5302            ihave-capability /
  5303            implementation-capability /
  5304            list-capability /
  5305            mode-reader-capability /
  5306            newnews-capability /
  5307            over-capability /
  5308            post-capability /
  5309            reader-capability
  5310 
  5311      hdr-capability = "HDR"
  5312      ihave-capability = "IHAVE"
  5313      implementation-capability = "IMPLEMENTATION" *(WS token)
  5314 
  5315 
  5316 
  5317 Feather                     Standards Track                    [Page 95]
  5318 
  5319 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5320 
  5321 
  5322      list-capability = "LIST" 1*(WS keyword)
  5323      mode-reader-capability = "MODE-READER"
  5324      newnews-capability = "NEWNEWS"
  5325      over-capability = "OVER" [WS "MSGID"]
  5326      post-capability = "POST"
  5327      reader-capability = "READER"
  5328 
  5329      version-line = "VERSION" 1*(WS version-number)
  5330      version-number = nzDIGIT *5DIGIT
  5331 
  5332 9.6.  LIST Variants
  5333 
  5334    This section defines more specifically the keywords for the LIST
  5335    command and the syntax of the corresponding response contents.
  5336 
  5337      ; active
  5338      list-arguments =/ "ACTIVE" [WS wildmat]
  5339      list-content =/ list-active-content
  5340      list-active-content = active-groups-list
  5341 
  5342 
  5343      ; active.times
  5344      list-arguments =/ "ACTIVE.TIMES" [WS wildmat]
  5345      list-content =/ list-active-times-content
  5346      list-active-times-content =
  5347            *(newsgroup-name SPA 1*DIGIT SPA newsgroup-creator CRLF)
  5348      newsgroup-creator = U-TEXT
  5349 
  5350 
  5351      ; distrib.pats
  5352      list-arguments =/ "DISTRIB.PATS"
  5353      list-content =/ list-distrib-pats-content
  5354      list-distrib-pats-content =
  5355            *(1*DIGIT ":" wildmat ":" distribution CRLF)
  5356      distribution = token
  5357 
  5358 
  5359      ; headers
  5360      list-arguments =/ "HEADERS" [WS ("MSGID" / "RANGE")]
  5361      list-content =/ list-headers-content
  5362      list-headers-content = *(header-meta-name CRLF) /
  5363            *((metadata-name / ":") CRLF)
  5364 
  5365 
  5366      ; newsgroups
  5367      list-arguments =/ "NEWSGROUPS" [WS wildmat]
  5368      list-content =/ list-newsgroups-content
  5369      list-newsgroups-content =
  5370 
  5371 
  5372 
  5373 Feather                     Standards Track                    [Page 96]
  5374 
  5375 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5376 
  5377 
  5378            *(newsgroup-name WS newsgroup-description CRLF)
  5379      newsgroup-description = S-TEXT
  5380 
  5381 
  5382      ; overview.fmt
  5383      list-arguments =/ "OVERVIEW.FMT"
  5384      list-content =/ list-overview-fmt-content
  5385      list-overview-fmt-content = "Subject:" CRLF
  5386            "From:" CRLF
  5387            "Date:" CRLF
  5388            "Message-ID:" CRLF
  5389            "References:" CRLF
  5390            ( ":bytes" CRLF ":lines" / "Bytes:" CRLF "Lines:") CRLF
  5391            *((header-name ":full" / metadata-name) CRLF)
  5392 
  5393 9.7.  Articles
  5394 
  5395    This syntax defines the non-terminal <article>, which represents the
  5396    format of an article as described in Section 3.6.
  5397 
  5398      article = 1*header CRLF body
  5399      header = header-name ":" [CRLF] SP header-content CRLF
  5400      header-content = *(S-CHAR / [CRLF] WS)
  5401      body = *(*B-CHAR CRLF)
  5402 
  5403 9.8.  General Non-terminals
  5404 
  5405    These non-terminals are used at various places in the syntax and are
  5406    collected here for convenience.  A few of these non-terminals are not
  5407    used in this specification but are provided for the consistency and
  5408    convenience of extension authors.
  5409 
  5410      multi-line-data-block = content-lines termination
  5411      content-lines = *([content-text] CRLF)
  5412      content-text = (".." / B-NONDOT) *B-CHAR
  5413      termination = "." CRLF
  5414 
  5415      article-number = 1*16DIGIT
  5416      header-name = 1*A-NOTCOLON
  5417      keyword = ALPHA 2*(ALPHA / DIGIT / "." / "-")
  5418      message-id = "<" 1*248A-NOTGT ">"
  5419      newsgroup-name = 1*wildmat-exact
  5420      token = 1*P-CHAR
  5421 
  5422      wildmat = wildmat-pattern *("," ["!"] wildmat-pattern)
  5423      wildmat-pattern = 1*wildmat-item
  5424      wildmat-item = wildmat-exact / wildmat-wild
  5425      wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E /
  5426 
  5427 
  5428 
  5429 Feather                     Standards Track                    [Page 97]
  5430 
  5431 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5432 
  5433 
  5434           UTF8-non-ascii  ; exclude ! * , ? [ \ ]
  5435      wildmat-wild = "*" / "?"
  5436 
  5437      base64 = *(4base64-char) [base64-terminal]
  5438      base64-char = UPPER / LOWER / DIGIT / "+" / "/"
  5439      base64-terminal = 2base64-char "==" / 3base64-char "="
  5440 
  5441      ; Assorted special character sets
  5442      ;   A- means based on US-ASCII, excluding controls and SP
  5443      ;   P- means based on UTF-8, excluding controls and SP
  5444      ;   U- means based on UTF-8, excluding NUL CR and LF
  5445      ;   B- means based on bytes, excluding NUL CR and LF
  5446      A-CHAR     = %x21-7E
  5447      A-NOTCOLON = %x21-39 / %x3B-7E  ; exclude ":"
  5448      A-NOTGT    = %x21-3D / %x3F-7E  ; exclude ">"
  5449      P-CHAR     = A-CHAR / UTF8-non-ascii
  5450      U-CHAR     = CTRL / TAB / SP / A-CHAR / UTF8-non-ascii
  5451      U-NONTAB   = CTRL /       SP / A-CHAR / UTF8-non-ascii
  5452      U-TEXT     = P-CHAR *U-CHAR
  5453      B-CHAR     = CTRL / TAB / SP / %x21-FF
  5454      B-NONDOT   = CTRL / TAB / SP / %x21-2D / %x2F-FF  ; exclude "."
  5455 
  5456      ALPHA = UPPER / LOWER   ; use only when case-insensitive
  5457      CR = %x0D
  5458      CRLF = CR LF
  5459      CTRL = %x01-08 / %x0B-0C / %x0E-1F
  5460      DIGIT = %x30-39
  5461      nzDIGIT = %x31-39
  5462      EOL = *(SP / TAB) CRLF
  5463      LF = %x0A
  5464      LOWER = %x61-7A
  5465      SP = %x20
  5466      SPA = 1*SP
  5467      TAB = %x09
  5468      UPPER = %x41-5A
  5469      UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4
  5470      UTF8-2    = %xC2-DF UTF8-tail
  5471      UTF8-3    = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail /
  5472                  %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail
  5473      UTF8-4    = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail /
  5474                  %xF4 %x80-8F 2UTF8-tail
  5475      UTF8-tail = %x80-BF
  5476      WS = 1*(SP / TAB)
  5477 
  5478    The following non-terminals require special consideration.  They
  5479    represent situations where material SHOULD be restricted to UTF-8,
  5480    but implementations MUST be able to cope with other character
  5481    encodings.  Therefore, there are two sets of definitions for them.
  5482 
  5483 
  5484 
  5485 Feather                     Standards Track                    [Page 98]
  5486 
  5487 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5488 
  5489 
  5490    Implementations MUST accept any content that meets this syntax:
  5491 
  5492      S-CHAR   = %x21-FF
  5493      S-NONTAB = CTRL / SP / S-CHAR
  5494      S-TEXT   = (CTRL / S-CHAR) *B-CHAR
  5495 
  5496    and MAY pass such content on unaltered.
  5497 
  5498    When generating new content or re-encoding existing content,
  5499    implementations SHOULD conform to this syntax:
  5500 
  5501      S-CHAR   = P-CHAR
  5502      S-NONTAB = U-NONTAB
  5503      S-TEXT   = U-TEXT
  5504 
  5505 9.9.  Extensions and Validation
  5506 
  5507    The specification of a registered extension MUST include formal
  5508    syntax that defines additional forms for the following non-terminals:
  5509 
  5510    command
  5511       for each new command other than a variant of the LIST command -
  5512       the syntax of each command MUST be compatible with the definition
  5513       of <X-command>;
  5514 
  5515    command-datastream
  5516       for each new command that immediately streams data;
  5517 
  5518    command-continuation
  5519       for each new command that sends further material after the initial
  5520       command line - the syntax of each continuation MUST be exactly
  5521       what is sent to the server, including any escape mechanisms such
  5522       as "dot-stuffing";
  5523 
  5524    initial-response-content
  5525       for each new response code that has arguments - the syntax of each
  5526       response MUST be compatible with the definition of <X-initial-
  5527       response-content>;
  5528 
  5529    multi-line-response-content
  5530       for each new response code that has a multi-line response - the
  5531       syntax MUST show the response after the lines containing the
  5532       response code and the terminating octet have been removed and any
  5533       "dot-stuffing" undone;
  5534 
  5535    capability-entry
  5536       for each new capability label - the syntax of each entry MUST be
  5537       compatible with the definition of <X-capability-entry>;
  5538 
  5539 
  5540 
  5541 Feather                     Standards Track                    [Page 99]
  5542 
  5543 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5544 
  5545 
  5546    list-arguments
  5547       for each new variant of the LIST command - the syntax of each
  5548       entry MUST be compatible with the definition of <X-command>;
  5549 
  5550    list-content
  5551       for each new variant of the LIST command - the syntax MUST show
  5552       the response after the lines containing the 215 response code and
  5553       the terminating octet have been removed and any "dot-stuffing"
  5554       undone.
  5555 
  5556    The =/ notation of ABNF [RFC4234] and the naming conventions
  5557    described in Section 9.1 SHOULD be used for this.
  5558 
  5559    When the syntax in this specification, or syntax based on it, is
  5560    validated, it should be noted that:
  5561 
  5562    o  the non-terminals <command-line>, <command-datastream>,
  5563       <command-continuation>, <response>, and
  5564       <multi-line-response-content> describe basic concepts of the
  5565       protocol and are not referred to by any other rule;
  5566 
  5567    o  the non-terminal <base64> is provided for the convenience of
  5568       extension authors and is not referred to by any rule in this
  5569       specification;
  5570 
  5571    o  for the reasons given above, the non-terminals <S-CHAR>,
  5572       <S-NONTAB>, and <S-TEXT> each have two definitions; and
  5573 
  5574    o  the non-terminal <UNDEFINED> is deliberately not defined.
  5575 
  5576 10.  Internationalisation Considerations
  5577 
  5578 10.1.  Introduction and Historical Situation
  5579 
  5580    RFC 977 [RFC977] was written at a time when internationalisation was
  5581    not seen as a significant issue.  As such, it was written on the
  5582    assumption that all communication would be in ASCII and use only a
  5583    7-bit transport layer, although in practice just about all known
  5584    implementations are 8-bit clean.
  5585 
  5586    Since then, Usenet and NNTP have spread throughout the world.  In the
  5587    absence of standards for handling the issues of language and
  5588    character sets, countries, newsgroup hierarchies, and individuals
  5589    have found a variety of solutions that work for them but that are not
  5590    necessarily appropriate elsewhere.  For example, some have adopted a
  5591    default 8-bit character set appropriate to their needs (such as
  5592    ISO/IEC 8859-1 in Western Europe or KOI-8 in Russia), others have
  5593    used ASCII (either US-ASCII or national variants) in headers but
  5594 
  5595 
  5596 
  5597 Feather                     Standards Track                   [Page 100]
  5598 
  5599 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5600 
  5601 
  5602    local 16-bit character sets in article bodies, and still others have
  5603    gone for a combination of MIME [RFC2045] and UTF-8.  With the
  5604    increased use of MIME in email, it is becoming more common to find
  5605    NNTP articles containing MIME headers that identify the character set
  5606    of the body, but this is far from universal.
  5607 
  5608    The resulting confusion does not help interoperability.
  5609 
  5610    One point that has been generally accepted is that articles can
  5611    contain octets with the top bit set, and NNTP is only expected to
  5612    operate on 8-bit clean transport paths.
  5613 
  5614 10.2.  This Specification
  5615 
  5616    Part of the role of this present specification is to eliminate this
  5617    confusion and promote interoperability as far as possible.  At the
  5618    same time, it is necessary to accept the existence of the present
  5619    situation and not break existing implementations and arrangements
  5620    gratuitously, even if they are less than optimal.  Therefore, the
  5621    current practice described above has been taken into consideration in
  5622    producing this specification.
  5623 
  5624    This specification extends NNTP from US-ASCII [ANSI1986] to UTF-8
  5625    [RFC3629].  Except in the two areas discussed below, UTF-8 (which is
  5626    a superset of US-ASCII) is mandatory, and implementations MUST NOT
  5627    use any other encoding.
  5628 
  5629    Firstly, the use of MIME for article headers and bodies is strongly
  5630    recommended.  However, given widely divergent existing practices, an
  5631    attempt to require a particular encoding and tagging standard would
  5632    be premature at this time.  Accordingly, this specification allows
  5633    the use of arbitrary 8-bit data in articles subject to the following
  5634    requirements and recommendations.
  5635 
  5636    o  The names of headers (e.g., "From" or "Subject") MUST be in
  5637       US-ASCII.
  5638 
  5639    o  Header values SHOULD use US-ASCII or an encoding based on it, such
  5640       as RFC 2047 [RFC2047], until such time as another approach has
  5641       been standardised.  At present, 8-bit encodings (including UTF-8)
  5642       SHOULD NOT be used because they are likely to cause
  5643       interoperability problems.
  5644 
  5645    o  The character set of article bodies SHOULD be indicated in the
  5646       article headers, and this SHOULD be done in accordance with MIME.
  5647 
  5648    o  Where an article is obtained from an external source, an
  5649       implementation MAY pass it on and derive data from it (such as the
  5650 
  5651 
  5652 
  5653 Feather                     Standards Track                   [Page 101]
  5654 
  5655 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5656 
  5657 
  5658       response to the HDR command), even though the article or the data
  5659       does not meet the above requirements.  Implementations MUST
  5660       transfer such articles and data correctly and unchanged; they MUST
  5661       NOT attempt to convert or re-encode the article or derived data.
  5662       (Nevertheless, a client or server MAY elect not to post or forward
  5663       the article if, after further examination of the article, it deems
  5664       it inappropriate to do so.)
  5665 
  5666    This requirement affects the ARTICLE (Section 6.2.1), BODY
  5667    (Section 6.2.3), HDR (Section 8.5), HEAD (Section 6.2.2), IHAVE
  5668    (Section 6.3.2), OVER (Section 8.3), and POST (Section 6.3.1)
  5669    commands.
  5670 
  5671    Secondly, the following requirements are placed on the newsgroups
  5672    list returned by the LIST NEWSGROUPS command (Section 7.6.6):
  5673 
  5674    o  Although this specification allows UTF-8 for newsgroup names, they
  5675       SHOULD be restricted to US-ASCII until a successor to RFC 1036
  5676       [RFC1036] standardises another approach. 8-bit encodings SHOULD
  5677       NOT be used because they are likely to cause interoperability
  5678       problems.
  5679 
  5680    o  The newsgroup description SHOULD be in US-ASCII or UTF-8 unless
  5681       and until a successor to RFC 1036 standardises other encoding
  5682       arrangements.  8-bit encodings other than UTF-8 SHOULD NOT be used
  5683       because they are likely to cause interoperability problems.
  5684 
  5685    o  Implementations that obtain this data from an external source MUST
  5686       handle it correctly even if it does not meet the above
  5687       requirements.  Implementations (in particular, clients) MUST
  5688       handle such data correctly.
  5689 
  5690 10.3.  Outstanding Issues
  5691 
  5692    While the primary use of NNTP is for transmitting articles that
  5693    conform to RFC 1036 (Netnews articles), it is also used for other
  5694    formats (see Appendix A).  It is therefore most appropriate that
  5695    internationalisation issues related to article formats be addressed
  5696    in the relevant specifications.  For Netnews articles, this is any
  5697    successor to RFC 1036.  For email messages, it is RFC 2822 [RFC2822].
  5698 
  5699    Of course, any article transmitted via NNTP needs to conform to this
  5700    specification as well.
  5701 
  5702    Restricting newsgroup names to UTF-8 is not a complete solution.  In
  5703    particular, when new newsgroup names are created or a user is asked
  5704    to enter a newsgroup name, some scheme of canonicalisation will need
  5705    to take place.  This specification does not attempt to define that
  5706 
  5707 
  5708 
  5709 Feather                     Standards Track                   [Page 102]
  5710 
  5711 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5712 
  5713 
  5714    canonicalization; further work is needed in this area, in conjunction
  5715    with the article format specifications.  Until such specifications
  5716    are published, implementations SHOULD match newsgroup names octet by
  5717    octet.  It is anticipated that any approved scheme will be applied
  5718    "at the edges", and therefore octet-by-octet comparison will continue
  5719    to apply to most, if not all, uses of newsgroup names in NNTP.
  5720 
  5721    In the meantime, any implementation experimenting with UTF-8
  5722    newsgroup names is strongly cautioned that a future specification may
  5723    require that those names be canonicalized when used with NNTP in a
  5724    way that is not compatible with their experiments.
  5725 
  5726    Since the primary use of NNTP is with Netnews, and since newsgroup
  5727    descriptions are normally distributed through specially formatted
  5728    articles, it is recommended that the internationalisation issues
  5729    related to them be addressed in any successor to RFC 1036.
  5730 
  5731 11.  IANA Considerations
  5732 
  5733    This specification requires IANA to keep a registry of capability
  5734    labels.  The initial contents of this registry are specified in
  5735    Section 3.3.4.  As described in Section 3.3.3, labels beginning with
  5736    X are reserved for private use, while all other names are expected to
  5737    be associated with a specification in an RFC on the standards track
  5738    or defining an IESG-approved experimental protocol.
  5739 
  5740    Different entries in the registry MUST use different capability
  5741    labels.
  5742 
  5743    Different entries in the registry MUST NOT use the same command name.
  5744    For this purpose, variants distinguished by a second or subsequent
  5745    keyword (e.g., "LIST HEADERS" and "LIST OVERVIEW.FMT") count as
  5746    different commands.  If there is a need for two extensions to use the
  5747    same command, a single harmonised specification MUST be registered.
  5748 
  5749 12.  Security Considerations
  5750 
  5751    This section is meant to inform application developers, information
  5752    providers, and users of the security limitations in NNTP as described
  5753    by this document.  The discussion does not include definitive
  5754    solutions to the problems revealed, though it does make some
  5755    suggestions for reducing security risks.
  5756 
  5757 
  5758 
  5759 
  5760 
  5761 
  5762 
  5763 
  5764 
  5765 Feather                     Standards Track                   [Page 103]
  5766 
  5767 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5768 
  5769 
  5770 12.1.  Personal and Proprietary Information
  5771 
  5772    NNTP, because it was created to distribute network news articles,
  5773    will forward whatever information is stored in those articles.
  5774    Specification of that information is outside this scope of this
  5775    document, but it is likely that some personal and/or proprietary
  5776    information is available in some of those articles.  It is very
  5777    important that designers and implementers provide informative
  5778    warnings to users so that personal and/or proprietary information in
  5779    material that is added automatically to articles (e.g., in headers)
  5780    is not disclosed inadvertently.  Additionally, effective and easily
  5781    understood mechanisms to manage the distribution of news articles
  5782    SHOULD be provided to NNTP Server administrators, so that they are
  5783    able to report with confidence the likely spread of any particular
  5784    set of news articles.
  5785 
  5786 12.2.  Abuse of Server Log Information
  5787 
  5788    A server is in the position to save session data about a user's
  5789    requests that might identify their reading patterns or subjects of
  5790    interest.  This information is clearly confidential in nature, and
  5791    its handling can be constrained by law in certain countries.  People
  5792    using this protocol to provide data are responsible for ensuring that
  5793    such material is not distributed without the permission of any
  5794    individuals that are identifiable by the published results.
  5795 
  5796 12.3.  Weak Authentication and Access Control
  5797 
  5798    There is no user-based or token-based authentication in the basic
  5799    NNTP specification.  Access is normally controlled by server
  5800    configuration files.  Those files specify access by using domain
  5801    names or IP addresses.  However, this specification does permit the
  5802    creation of extensions to NNTP for such purposes; one such extension
  5803    is [NNTP-AUTH].  While including such mechanisms is optional, doing
  5804    so is strongly encouraged.
  5805 
  5806    Other mechanisms are also available.  For example, a proxy server
  5807    could be put in place that requires authentication before connecting
  5808    via the proxy to the NNTP server.
  5809 
  5810 12.4.  DNS Spoofing
  5811 
  5812    Many existing NNTP implementations authorize incoming connections by
  5813    checking the IP address of that connection against the IP addresses
  5814    obtained via DNS lookups of lists of domain names given in local
  5815    configuration files.  Servers that use this type of authentication
  5816    and clients that find a server by doing a DNS lookup of the server
  5817    name rely very heavily on the Domain Name Service, and are thus
  5818 
  5819 
  5820 
  5821 Feather                     Standards Track                   [Page 104]
  5822 
  5823 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5824 
  5825 
  5826    generally prone to security attacks based on the deliberate
  5827    misassociation of IP addresses and DNS names.  Clients and servers
  5828    need to be cautious in assuming the continuing validity of an IP
  5829    number/DNS name association.
  5830 
  5831    In particular, NNTP clients and servers SHOULD rely on their name
  5832    resolver for confirmation of an IP number/DNS name association,
  5833    rather than cache the result of previous host name lookups.  Many
  5834    platforms already can cache host name lookups locally when
  5835    appropriate, and they SHOULD be configured to do so.  It is proper
  5836    for these lookups to be cached, however, only when the TTL (Time To
  5837    Live) information reported by the name server makes it likely that
  5838    the cached information will remain useful.
  5839 
  5840    If NNTP clients or servers cache the results of host name lookups in
  5841    order to achieve a performance improvement, they MUST observe the TTL
  5842    information reported by DNS.  If NNTP clients or servers do not
  5843    observe this rule, they could be spoofed when a previously accessed
  5844    server's IP address changes.  As network renumbering is expected to
  5845    become increasingly common, the possibility of this form of attack
  5846    will increase.  Observing this requirement thus reduces this
  5847    potential security vulnerability.
  5848 
  5849    This requirement also improves the load-balancing behaviour of
  5850    clients for replicated servers using the same DNS name and reduces
  5851    the likelihood of a user's experiencing failure in accessing sites
  5852    that use that strategy.
  5853 
  5854 12.5.  UTF-8 Issues
  5855 
  5856    UTF-8 [RFC3629] permits only certain sequences of octets and
  5857    designates others as either malformed or "illegal".  The Unicode
  5858    standard identifies a number of security issues related to illegal
  5859    sequences and forbids their generation by conforming implementations.
  5860 
  5861    Implementations of this specification MUST NOT generate malformed or
  5862    illegal sequences and SHOULD detect them and take some appropriate
  5863    action.  This could include the following:
  5864 
  5865    o  Generating a 501 response code.
  5866 
  5867    o  Replacing such sequences by the sequence %xEF.BF.BD, which encodes
  5868       the "replacement character" U+FFFD.
  5869 
  5870    o  Closing the connection.
  5871 
  5872    o  Replacing such sequences by a "guessed" valid sequence (based on
  5873       properties of the UTF-8 encoding).
  5874 
  5875 
  5876 
  5877 Feather                     Standards Track                   [Page 105]
  5878 
  5879 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5880 
  5881 
  5882    In the last case, the implementation MUST ensure that any replacement
  5883    cannot be used to bypass validity or security checks.  For example,
  5884    the illegal sequence %xC0.A0 is an over-long encoding for space
  5885    (%x20).  If it is replaced by the correct encoding in a command line,
  5886    this needs to happen before the command line is parsed into
  5887    individual arguments.  If the replacement came after parsing, it
  5888    would be possible to generate an argument with an embedded space,
  5889    which is forbidden.  Use of the "replacement character" does not have
  5890    this problem, since it is permitted wherever non-US-ASCII characters
  5891    are.  Implementations SHOULD use one of the first two solutions where
  5892    the general structure of the NNTP stream remains intact and SHOULD
  5893    close the connection if it is no longer possible to parse it
  5894    sensibly.
  5895 
  5896 12.6.  Caching of Capability Lists
  5897 
  5898    The CAPABILITIES command provides a capability list, which is
  5899    information about the current capabilities of the server.  Whenever
  5900    there is a relevant change to the server state, the results of this
  5901    command are required to change accordingly.
  5902 
  5903    In most situations, the capabilities list in a given server state
  5904    will not change from session to session; for example, a given
  5905    extension will be installed permanently on a server.  Some clients
  5906    may therefore wish to remember which extensions a server supports to
  5907    avoid the delay of an additional command and response, particularly
  5908    if they open multiple connections in the same session.
  5909 
  5910    However, information about extensions related to security and privacy
  5911    MUST NOT be cached, since this could allow a variety of attacks.
  5912 
  5913    For example, consider a server that permits the use of cleartext
  5914    passwords on links that are encrypted but not otherwise:
  5915 
  5916       [Initial connection set-up completed.]
  5917       [S] 200 NNTP Service Ready, posting permitted
  5918       [C] CAPABILITIES
  5919       [S] 101 Capability list:
  5920       [S] VERSION 2
  5921       [S] READER
  5922       [S] NEWNEWS
  5923       [S] POST
  5924       [S] XENCRYPT
  5925       [S] LIST ACTIVE NEWSGROUPS
  5926       [S] .
  5927       [C] XENCRYPT
  5928       [Client and server negotiate encryption on the link]
  5929       [S] 283 Encrypted link established
  5930 
  5931 
  5932 
  5933 Feather                     Standards Track                   [Page 106]
  5934 
  5935 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5936 
  5937 
  5938       [C] CAPABILITIES
  5939       [S] 101 Capability list:
  5940       [S] VERSION 2
  5941       [S] READER
  5942       [S] NEWNEWS
  5943       [S] POST
  5944       [S] XSECRET
  5945       [S] LIST ACTIVE NEWSGROUPS
  5946       [S] .
  5947       [C] XSECRET fred flintstone
  5948       [S] 290 Password for fred accepted
  5949 
  5950    If the client caches the last capabilities list, then on the next
  5951    session it will attempt to use XSECRET on an unencrypted link:
  5952 
  5953       [Initial connection set-up completed.]
  5954       [S] 200 NNTP Service Ready, posting permitted
  5955       [C] XSECRET fred flintstone
  5956       [S] 483 Only permitted on secure links
  5957 
  5958    This exposes the password to any eavesdropper.  While the primary
  5959    cause of this is passing a secret without first checking the security
  5960    of the link, caching of capability lists can increase the risk.
  5961 
  5962    Any security extension should include requirements to check the
  5963    security state of the link in a manner appropriate to that extension.
  5964 
  5965    Caching should normally only be considered for anonymous clients that
  5966    do not use any security or privacy extensions and for which the time
  5967    required for an additional command and response is a noticeable
  5968    issue.
  5969 
  5970 13.  Acknowledgements
  5971 
  5972    This document is the result of much effort by the present and past
  5973    members of the NNTP Working Group, chaired by Russ Allbery and Ned
  5974    Freed.  It could not have been produced without them.
  5975 
  5976    The author acknowledges the original authors of NNTP as documented in
  5977    RFC 977 [RFC977]: Brian Kantor and Phil Lapsey.
  5978 
  5979    The author gratefully acknowledges the following:
  5980 
  5981    o  The work of the NNTP committee chaired by Eliot Lear.  The
  5982       organization of this document was influenced by the last available
  5983       version from this working group.  A special thanks to Eliot for
  5984       generously providing the original machine-readable sources for
  5985       that document.
  5986 
  5987 
  5988 
  5989 Feather                     Standards Track                   [Page 107]
  5990 
  5991 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  5992 
  5993 
  5994    o  The work of the DRUMS working group, specifically RFC 1869
  5995       [RFC1869], that drove the original thinking that led to the
  5996       CAPABILITIES command and the extensions mechanism detailed in this
  5997       document.
  5998 
  5999    o  The authors of RFC 2616 [RFC2616] for providing specific and
  6000       relevant examples of security issues that should be considered for
  6001       HTTP.  Since many of the same considerations exist for NNTP, those
  6002       examples that are relevant have been included here with some minor
  6003       rewrites.
  6004 
  6005    o  The comments and additional information provided by the following
  6006       individuals in preparing one or more of the progenitors of this
  6007       document:
  6008 
  6009          Russ Allbery <rra@stanford.edu>
  6010          Wayne Davison <davison@armory.com>
  6011          Chris Lewis <clewis@bnr.ca>
  6012          Tom Limoncelli <tal@mars.superlink.net>
  6013          Eric Schnoebelen <eric@egsner.cirr.com>
  6014          Rich Salz <rsalz@osf.org>
  6015 
  6016    This work was motivated by the work of various news reader authors
  6017    and news server authors, including those listed below:
  6018 
  6019    Rick Adams
  6020       Original author of the NNTP extensions to the RN news reader and
  6021       last maintainer of Bnews.
  6022 
  6023    Stan Barber
  6024       Original author of the NNTP extensions to the news readers that
  6025       are part of Bnews.
  6026 
  6027    Geoff Collyer
  6028       Original author of the OVERVIEW database proposal and one of the
  6029       original authors of CNEWS.
  6030 
  6031    Dan Curry
  6032       Original author of the xvnews news reader.
  6033 
  6034    Wayne Davison
  6035       Author of the first threading extensions to the RN news reader
  6036       (commonly called TRN).
  6037 
  6038    Geoff Huston
  6039       Original author of ANU NEWS.
  6040 
  6041 
  6042 
  6043 
  6044 
  6045 Feather                     Standards Track                   [Page 108]
  6046 
  6047 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6048 
  6049 
  6050    Phil Lapsey
  6051       Original author of the UNIX reference implementation for NNTP.
  6052 
  6053    Iain Lea
  6054       Original maintainer of the TIN news reader.
  6055 
  6056    Chris Lewis
  6057       First known implementer of the AUTHINFO GENERIC extension.
  6058 
  6059    Rich Salz
  6060       Original author of INN.
  6061 
  6062    Henry Spencer
  6063       One of the original authors of CNEWS.
  6064 
  6065    Kim Storm
  6066       Original author of the NN news reader.
  6067 
  6068    Other people who contributed to this document include:
  6069 
  6070       Matthias Andree
  6071       Greg Andruk
  6072       Daniel Barclay
  6073       Maurizio Codogno
  6074       Mark Crispin
  6075       Andrew Gierth
  6076       Juergen Helbing
  6077       Scott Hollenbeck
  6078       Urs Janssen
  6079       Charles Lindsey
  6080       Ade Lovett
  6081       David Magda
  6082       Ken Murchison
  6083       Francois Petillon
  6084       Peter Robinson
  6085       Rob Siemborski
  6086       Howard Swinehart
  6087       Ruud van Tol
  6088       Jeffrey Vinocur
  6089       Erik Warmelink
  6090 
  6091    The author thanks them all and apologises to anyone omitted.
  6092 
  6093    Finally, the present author gratefully acknowledges the vast amount
  6094    of work put into previous versions by the previous author:
  6095 
  6096       Stan Barber <sob@academ.com>
  6097 
  6098 
  6099 
  6100 
  6101 Feather                     Standards Track                   [Page 109]
  6102 
  6103 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6104 
  6105 
  6106 14.  References
  6107 
  6108 14.1.  Normative References
  6109 
  6110    [ANSI1986]    American National Standards Institute, "Coded Character
  6111                  Set - 7-bit American Standard Code for Information
  6112                  Interchange", ANSI X3.4, 1986.
  6113 
  6114    [RFC977]      Kantor, B. and P. Lapsley, "Network News Transfer
  6115                  Protocol", RFC 977, February 1986.
  6116 
  6117    [RFC2045]     Freed, N. and N. Borenstein, "Multipurpose Internet
  6118                  Mail Extensions (MIME) Part One: Format of Internet
  6119                  Message Bodies", RFC 2045, November 1996.
  6120 
  6121    [RFC2047]     Moore, K., "MIME (Multipurpose Internet Mail
  6122                  Extensions) Part Three: Message Header Extensions for
  6123                  Non-ASCII Text", RFC 2047, November 1996.
  6124 
  6125    [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
  6126                  Requirement Levels", BCP 14, RFC 2119, March 1997.
  6127 
  6128    [RFC3629]     Yergeau, F., "UTF-8, a transformation format of ISO
  6129                  10646", STD 63, RFC 3629, November 2003.
  6130 
  6131    [RFC4234]     Crocker, D., Ed. and P. Overell, "Augmented BNF for
  6132                  Syntax Specifications: ABNF", RFC 4234, October 2005.
  6133 
  6134    [RFC4648]     Josefsson, S., "The Base16, Base32, and Base64 Data
  6135                  Encodings", RFC 4648, October 2006.
  6136 
  6137    [TF.686-1]    International Telecommunications Union - Radio,
  6138                  "Glossary, ITU-R Recommendation TF.686-1",
  6139                  ITU-R Recommendation TF.686-1, October 1997.
  6140 
  6141 14.2.  Informative References
  6142 
  6143    [NNTP-AUTH]   Vinocur, J., Murchison, K., and C. Newman, "Network
  6144                  News Transfer Protocol (NNTP) Extension for
  6145                  Authentication",
  6146                  RFC 4643, October 2006.
  6147 
  6148    [NNTP-STREAM] Vinocur, J. and K. Murchison, "Network News Transfer
  6149                  Protocol (NNTP) Extension for Streaming Feeds",
  6150                  RFC 4644, October 2006.
  6151 
  6152 
  6153 
  6154 
  6155 
  6156 
  6157 Feather                     Standards Track                   [Page 110]
  6158 
  6159 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6160 
  6161 
  6162    [NNTP-TLS]    Murchison, K., Vinocur, J., and C. Newman, "Using
  6163                  Transport Layer Security (TLS) with Network News
  6164                  Transfer Protocol (NNTP)", RFC 4642, October 2006.
  6165 
  6166    [RFC1036]     Horton, M. and R. Adams, "Standard for interchange of
  6167                  USENET messages", RFC 1036, December 1987.
  6168 
  6169    [RFC1305]     Mills, D., "Network Time Protocol (Version 3)
  6170                  Specification, Implementation and Analysis", RFC 1305,
  6171                  March 1992.
  6172 
  6173    [RFC1869]     Klensin, J., Freed, N., Rose, M., Stefferud, E., and D.
  6174                  Crocker, "SMTP Service Extensions", STD 10, RFC 1869,
  6175                  November 1995.
  6176 
  6177    [RFC2616]     Fielding,  R., Gettys, J., Mogul, J., Frystyk, H.,
  6178                  Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
  6179                  Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
  6180 
  6181    [RFC2629]     Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
  6182                  June 1999.
  6183 
  6184    [RFC2822]     Resnick, P., "Internet Message Format", RFC 2822, April
  6185                  2001.
  6186 
  6187    [RFC2980]     Barber, S., "Common NNTP Extensions", RFC 2980, October
  6188                  2000.
  6189 
  6190    [ROBE1995]    Robertson, R., "FAQ: Overview database / NOV General
  6191                  Information", January 1995.
  6192 
  6193                  There is no definitive copy of this document known to
  6194                  the author.  It was previously posted as the Usenet
  6195                  article <news:nov-faq-1-930909720@agate.Berkeley.EDU>
  6196 
  6197    [SALZ1992]    Salz, R., "Manual Page for wildmat(3) from the INN 1.4
  6198                  distribution, Revision 1.10", April 1992.
  6199 
  6200                  There is no definitive copy of this document known to
  6201                  the author.
  6202 
  6203 
  6204 
  6205 
  6206 
  6207 
  6208 
  6209 
  6210 
  6211 
  6212 
  6213 Feather                     Standards Track                   [Page 111]
  6214 
  6215 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6216 
  6217 
  6218 Appendix A.  Interaction with Other Specifications
  6219 
  6220    NNTP is most often used for transferring articles that conform to
  6221    RFC 1036 [RFC1036] (such articles are called "Netnews articles"
  6222    here).  It is also sometimes used for transferring email messages
  6223    that conform to RFC 2822 [RFC2822] (such articles are called "email
  6224    articles" here).  In this situation, articles must conform both to
  6225    this specification and to that other one; this appendix describes
  6226    some relevant issues.
  6227 
  6228 A.1.  Header Folding
  6229 
  6230    NNTP allows a header line to be folded (by inserting a CRLF pair)
  6231    before any space or TAB character.
  6232 
  6233    Both email and Netnews articles are required to have at least one
  6234    octet other than space or TAB on each header line.  Thus, folding can
  6235    only happen at one point in each sequence of consecutive spaces or
  6236    TABs.  Netnews articles are further required to have the header name,
  6237    colon, and following space all on the first line; folding may only
  6238    happen beyond that space.  Finally, some non-conforming software will
  6239    remove trailing spaces and TABs from a line.  Therefore, it might be
  6240    inadvisable to fold a header after a space or TAB.
  6241 
  6242    For maximum safety, header lines SHOULD conform to the following
  6243    syntax rather than to that in Section 9.7.
  6244 
  6245 
  6246      header = header-name ":" SP [header-content] CRLF
  6247      header-content = [WS] token *( [CRLF] WS token )
  6248 
  6249 A.2.  Message-IDs
  6250 
  6251    Every article handled by an NNTP server MUST have a unique
  6252    message-id.  For the purposes of this specification, a message-id is
  6253    an arbitrary opaque string that merely needs to meet certain
  6254    syntactic requirements and is just a way to refer to the article.
  6255 
  6256    Because there is a significant risk that old articles will be
  6257    reinjected into the global Usenet system, RFC 1036 [RFC1036] requires
  6258    that message-ids are globally unique for all time.
  6259 
  6260    This specification states that message-ids are the same if and only
  6261    if they consist of the same sequence of octets.  Other specifications
  6262    may define two different sequences as being equal because they are
  6263    putting an interpretation on particular characters.  RFC 2822
  6264    [RFC2822] has a concept of "quoted" and "escaped" characters.  It
  6265    therefore considers the three message-ids:
  6266 
  6267 
  6268 
  6269 Feather                     Standards Track                   [Page 112]
  6270 
  6271 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6272 
  6273 
  6274       <ab.cd@example.com>
  6275       <"ab.cd"@example.com>
  6276       <"ab.\cd"@example.com>
  6277 
  6278    as being identical.  Therefore, an NNTP implementation handing email
  6279    articles must ensure that only one of these three appears in the
  6280    protocol and that the other two are converted to it as and when
  6281    necessary, such as when a client checks the results of a NEWNEWS
  6282    command against an internal database of message-ids.  Note that
  6283    RFC 1036 [RFC1036] never treats two different strings as being
  6284    identical.  Its successor (as of the time of writing) restricts the
  6285    syntax of message-ids so that, whenever RFC 2822 would treat two
  6286    strings as equivalent, only one of them is valid (in the above
  6287    example, only the first string is valid).
  6288 
  6289    This specification does not describe how the message-id of an article
  6290    is determined; it may be deduced from the contents of the article or
  6291    derived from some external source.  If the server is also conforming
  6292    to another specification that contains a definition of message-id
  6293    compatible with this one, the server SHOULD use those message-ids.  A
  6294    common approach, and one that SHOULD be used for email and Netnews
  6295    articles, is to extract the message-id from the contents of a header
  6296    with name "Message-ID".  This may not be as simple as copying the
  6297    entire header contents; it may be necessary to strip off comments and
  6298    undo quoting, or to reduce "equivalent" message-ids to a canonical
  6299    form.
  6300 
  6301    If an article is obtained through the IHAVE command, there will be a
  6302    message-id provided with the command.  The server MAY either use it
  6303    or determine one from the article contents.  However, whichever it
  6304    does, it SHOULD ensure that, if the IHAVE command is repeated with
  6305    the same argument and article, it will be recognized as a duplicate.
  6306 
  6307    If an article does not contain a message-id that the server can
  6308    identify, it MUST synthesize one.  This could, for example, be a
  6309    simple sequence number or be based on the date and time when the
  6310    article arrived.  When email or Netnews articles are handled, a
  6311    Message-ID header SHOULD be added to ensure global consistency and
  6312    uniqueness.
  6313 
  6314    Note that, because the message-id might not have been derived from
  6315    the Message-ID header in the article, the following example is
  6316    legitimate (though unusual):
  6317 
  6318 
  6319 
  6320 
  6321 
  6322 
  6323 
  6324 
  6325 Feather                     Standards Track                   [Page 113]
  6326 
  6327 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6328 
  6329 
  6330       [C] HEAD <45223423@example.com>
  6331       [S] 221 0 <45223423@example.com>
  6332       [S] Path: pathost!demo!whitehouse!not-for-mail
  6333       [S] Message-ID: <1234@example.net>
  6334       [S] From: "Demo User" <nobody@example.net>
  6335       [S] Newsgroups: misc.test
  6336       [S] Subject: I am just a test article
  6337       [S] Date: 6 Oct 1998 04:38:40 -0500
  6338       [S] Organization: An Example Net, Uncertain, Texas
  6339       [S] .
  6340 
  6341 A.3.  Article Posting
  6342 
  6343    As far as NNTP is concerned, the POST and IHAVE commands provide the
  6344    same basic facilities in a slightly different way.  However, they
  6345    have rather different intentions.
  6346 
  6347    The IHAVE command is intended for transmitting conforming articles
  6348    between a system of NNTP servers, with all articles perhaps also
  6349    conforming to another specification (e.g., all articles are Netnews
  6350    articles).  It is expected that the client will already have done any
  6351    necessary validation (or that it has in turn obtained the article
  6352    from a third party that has done so); therefore, the contents SHOULD
  6353    be left unchanged.
  6354 
  6355    In contrast, the POST command is intended for use when an end-user is
  6356    injecting a newly created article into a such a system.  The article
  6357    being transferred might not be a conforming email or Netnews article,
  6358    and the server is expected to validate it and, if necessary, to
  6359    convert it to the right form for onward distribution.  This is often
  6360    done by a separate piece of software on the server installation; if
  6361    so, the NNTP server SHOULD pass the incoming article to that software
  6362    unaltered, making no attempt to filter characters, to fold or limit
  6363    lines, or to process the incoming text otherwise.
  6364 
  6365    The POST command can fail in various ways, and clients should be
  6366    prepared to re-send an article.  When doing so, however, it is often
  6367    important to ensure (as far as possible) that the same message-id is
  6368    allocated to both attempts so that the server, or other servers, can
  6369    recognize the two articles as duplicates.  In the case of email or
  6370    Netnews articles, therefore, the posted article SHOULD contain a
  6371    header with the name "Message-ID", and the contents of this header
  6372    SHOULD be identical on each attempt.  The server SHOULD ensure that
  6373    two POSTed articles with the same contents for this header are
  6374    recognized as identical and that the same message-id is allocated,
  6375    whether or not those contents are suitable for use as the message-id.
  6376 
  6377 
  6378 
  6379 
  6380 
  6381 Feather                     Standards Track                   [Page 114]
  6382 
  6383 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6384 
  6385 
  6386 Appendix B.  Summary of Commands
  6387 
  6388    This section contains a list of every command defined in this
  6389    document, ordered by command name and by indicating capability.
  6390 
  6391                          Ordered by command name:
  6392 
  6393        +-------------------+-----------------------+---------------+
  6394        | Command           | Indicating capability | Definition    |
  6395        +-------------------+-----------------------+---------------+
  6396        | ARTICLE           | READER                | Section 6.2.1 |
  6397        | BODY              | READER                | Section 6.2.3 |
  6398        | CAPABILITIES      | mandatory             | Section 5.2   |
  6399        | DATE              | READER                | Section 7.1   |
  6400        | GROUP             | READER                | Section 6.1.1 |
  6401        | HDR               | HDR                   | Section 8.5   |
  6402        | HEAD              | mandatory             | Section 6.2.2 |
  6403        | HELP              | mandatory             | Section 7.2   |
  6404        | IHAVE             | IHAVE                 | Section 6.3.2 |
  6405        | LAST              | READER                | Section 6.1.3 |
  6406        | LIST              | LIST                  | Section 7.6.1 |
  6407        | LIST ACTIVE.TIMES | LIST                  | Section 7.6.4 |
  6408        | LIST ACTIVE       | LIST                  | Section 7.6.3 |
  6409        | LIST DISTRIB.PATS | LIST                  | Section 7.6.5 |
  6410        | LIST HEADERS      | HDR                   | Section 8.6   |
  6411        | LIST NEWSGROUPS   | LIST                  | Section 7.6.6 |
  6412        | LIST OVERVIEW.FMT | OVER                  | Section 8.4   |
  6413        | LISTGROUP         | READER                | Section 6.1.2 |
  6414        | MODE READER       | MODE-READER           | Section 5.3   |
  6415        | NEWGROUPS         | READER                | Section 7.3   |
  6416        | NEWNEWS           | NEWNEWS               | Section 7.4   |
  6417        | NEXT              | READER                | Section 6.1.4 |
  6418        | OVER              | OVER                  | Section 8.3   |
  6419        | POST              | POST                  | Section 6.3.1 |
  6420        | QUIT              | mandatory             | Section 5.4   |
  6421        | STAT              | mandatory             | Section 6.2.4 |
  6422        +-------------------+-----------------------+---------------+
  6423 
  6424 
  6425 
  6426 
  6427 
  6428 
  6429 
  6430 
  6431 
  6432 
  6433 
  6434 
  6435 
  6436 
  6437 Feather                     Standards Track                   [Page 115]
  6438 
  6439 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6440 
  6441 
  6442                      Ordered by indicating capability:
  6443 
  6444        +-------------------+-----------------------+---------------+
  6445        | Command           | Indicating capability | Definition    |
  6446        +-------------------+-----------------------+---------------+
  6447        | CAPABILITIES      | mandatory             | Section 5.2   |
  6448        | HEAD              | mandatory             | Section 6.2.2 |
  6449        | HELP              | mandatory             | Section 7.2   |
  6450        | QUIT              | mandatory             | Section 5.4   |
  6451        | STAT              | mandatory             | Section 6.2.4 |
  6452        | HDR               | HDR                   | Section 8.5   |
  6453        | LIST HEADERS      | HDR                   | Section 8.6   |
  6454        | IHAVE             | IHAVE                 | Section 6.3.2 |
  6455        | LIST              | LIST                  | Section 7.6.1 |
  6456        | LIST ACTIVE       | LIST                  | Section 7.6.3 |
  6457        | LIST ACTIVE.TIMES | LIST                  | Section 7.6.4 |
  6458        | LIST DISTRIB.PATS | LIST                  | Section 7.6.5 |
  6459        | LIST NEWSGROUPS   | LIST                  | Section 7.6.6 |
  6460        | MODE READER       | MODE-READER           | Section 5.3   |
  6461        | NEWNEWS           | NEWNEWS               | Section 7.4   |
  6462        | OVER              | OVER                  | Section 8.3   |
  6463        | LIST OVERVIEW.FMT | OVER                  | Section 8.4   |
  6464        | POST              | POST                  | Section 6.3.1 |
  6465        | ARTICLE           | READER                | Section 6.2.1 |
  6466        | BODY              | READER                | Section 6.2.3 |
  6467        | DATE              | READER                | Section 7.1   |
  6468        | GROUP             | READER                | Section 6.1.1 |
  6469        | LAST              | READER                | Section 6.1.3 |
  6470        | LISTGROUP         | READER                | Section 6.1.2 |
  6471        | NEWGROUPS         | READER                | Section 7.3   |
  6472        | NEXT              | READER                | Section 6.1.4 |
  6473        +-------------------+-----------------------+---------------+
  6474 
  6475 
  6476 
  6477 
  6478 
  6479 
  6480 
  6481 
  6482 
  6483 
  6484 
  6485 
  6486 
  6487 
  6488 
  6489 
  6490 
  6491 
  6492 
  6493 Feather                     Standards Track                   [Page 116]
  6494 
  6495 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6496 
  6497 
  6498 Appendix C.  Summary of Response Codes
  6499 
  6500    This section contains a list of every response code defined in this
  6501    document and indicates whether it is multi-line, which commands can
  6502    generate it, what arguments it has, and what its meaning is.
  6503 
  6504    Response code 100 (multi-line)
  6505       Generated by: HELP
  6506       Meaning: help text follows.
  6507 
  6508    Response code 101 (multi-line)
  6509       Generated by: CAPABILITIES
  6510       Meaning: capabilities list follows.
  6511 
  6512    Response code 111
  6513       Generated by: DATE
  6514       1 argument: yyyymmddhhmmss
  6515       Meaning: server date and time.
  6516 
  6517    Response code 200
  6518       Generated by: initial connection, MODE READER
  6519       Meaning: service available, posting allowed.
  6520 
  6521    Response code 201
  6522       Generated by: initial connection, MODE READER
  6523       Meaning: service available, posting prohibited.
  6524 
  6525    Response code 205
  6526       Generated by: QUIT
  6527       Meaning: connection closing (the server immediately closes the
  6528       connection).
  6529 
  6530    Response code 211
  6531       The 211 response code has two completely different forms,
  6532       depending on which command generated it:
  6533 
  6534          (not multi-line)
  6535          Generated by: GROUP
  6536          4 arguments: number low high group
  6537          Meaning: group selected.
  6538 
  6539          (multi-line)
  6540          Generated by: LISTGROUP
  6541          4 arguments: number low high group
  6542          Meaning: article numbers follow.
  6543 
  6544 
  6545 
  6546 
  6547 
  6548 
  6549 Feather                     Standards Track                   [Page 117]
  6550 
  6551 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6552 
  6553 
  6554    Response code 215 (multi-line)
  6555       Generated by: LIST
  6556       Meaning: information follows.
  6557 
  6558    Response code 220 (multi-line)
  6559       Generated by: ARTICLE
  6560       2 arguments: n message-id
  6561       Meaning: article follows.
  6562 
  6563    Response code 221 (multi-line)
  6564       Generated by: HEAD
  6565       2 arguments: n message-id
  6566       Meaning: article headers follow.
  6567 
  6568    Response code 222 (multi-line)
  6569       Generated by: BODY
  6570       2 arguments: n message-id
  6571       Meaning: article body follows.
  6572 
  6573    Response code 223
  6574       Generated by: LAST, NEXT, STAT
  6575       2 arguments: n message-id
  6576       Meaning: article exists and selected.
  6577 
  6578    Response code 224 (multi-line)
  6579       Generated by: OVER
  6580       Meaning: overview information follows.
  6581 
  6582    Response code 225 (multi-line)
  6583       Generated by: HDR
  6584       Meaning: headers follow.
  6585 
  6586    Response code 230 (multi-line)
  6587       Generated by: NEWNEWS
  6588       Meaning: list of new articles follows.
  6589 
  6590    Response code 231 (multi-line)
  6591       Generated by: NEWGROUPS
  6592       Meaning: list of new newsgroups follows.
  6593 
  6594    Response code 235
  6595       Generated by: IHAVE (second stage)
  6596       Meaning: article transferred OK.
  6597 
  6598    Response code 240
  6599       Generated by: POST (second stage)
  6600       Meaning: article received OK.
  6601 
  6602 
  6603 
  6604 
  6605 Feather                     Standards Track                   [Page 118]
  6606 
  6607 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6608 
  6609 
  6610    Response code 335
  6611       Generated by: IHAVE (first stage)
  6612       Meaning: send article to be transferred.
  6613 
  6614    Response code 340
  6615       Generated by: POST (first stage)
  6616       Meaning: send article to be posted.
  6617 
  6618    Response code 400
  6619       Generic response and generated by initial connection
  6620       Meaning: service not available or no longer available (the server
  6621       immediately closes the connection).
  6622 
  6623    Response code 401
  6624       Generic response
  6625       1 argument: capability-label
  6626       Meaning: the server is in the wrong mode; the indicated capability
  6627       should be used to change the mode.
  6628 
  6629    Response code 403
  6630       Generic response
  6631       Meaning: internal fault or problem preventing action being taken.
  6632 
  6633    Response code 411
  6634       Generated by: GROUP, LISTGROUP
  6635       Meaning: no such newsgroup.
  6636 
  6637    Response code 412
  6638       Generated by: ARTICLE, BODY, GROUP, HDR, HEAD, LAST, LISTGROUP,
  6639       NEXT, OVER, STAT
  6640       Meaning: no newsgroup selected.
  6641 
  6642    Response code 420
  6643       Generated by: ARTICLE, BODY, HDR, HEAD, LAST, NEXT, OVER, STAT
  6644       Meaning: current article number is invalid.
  6645 
  6646    Response code 421
  6647       Generated by: NEXT
  6648       Meaning: no next article in this group.
  6649 
  6650    Response code 422
  6651       Generated by: LAST
  6652       Meaning: no previous article in this group.
  6653 
  6654    Response code 423
  6655       Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT
  6656       Meaning: no article with that number or in that range.
  6657 
  6658 
  6659 
  6660 
  6661 Feather                     Standards Track                   [Page 119]
  6662 
  6663 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6664 
  6665 
  6666    Response code 430
  6667       Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT
  6668       Meaning: no article with that message-id.
  6669 
  6670    Response code 435
  6671       Generated by: IHAVE (first stage)
  6672       Meaning: article not wanted.
  6673 
  6674    Response code 436
  6675       Generated by: IHAVE (either stage)
  6676       Meaning: transfer not possible (first stage) or failed (second
  6677       stage); try again later.
  6678 
  6679    Response code 437
  6680       Generated by: IHAVE (second stage)
  6681       Meaning: transfer rejected; do not retry.
  6682 
  6683    Response code 440
  6684       Generated by: POST (first stage)
  6685       Meaning: posting not permitted.
  6686 
  6687    Response code 441
  6688       Generated by: POST (second stage)
  6689       Meaning: posting failed.
  6690 
  6691    Response code 480
  6692       Generic response
  6693       Meaning: command unavailable until the client has authenticated
  6694       itself.
  6695 
  6696    Response code 483
  6697       Generic response
  6698       Meaning: command unavailable until suitable privacy has been
  6699       arranged.
  6700 
  6701    Response code 500
  6702       Generic response
  6703       Meaning: unknown command.
  6704 
  6705    Response code 501
  6706       Generic response
  6707       Meaning: syntax error in command.
  6708 
  6709 
  6710 
  6711 
  6712 
  6713 
  6714 
  6715 
  6716 
  6717 Feather                     Standards Track                   [Page 120]
  6718 
  6719 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6720 
  6721 
  6722    Response code 502
  6723       Generic response and generated by initial connection
  6724 
  6725       Meaning for the initial connection and the MODE READER command:
  6726       service permanently unavailable (the server immediately closes the
  6727       connection).
  6728 
  6729       Meaning for all other commands: command not permitted (and there
  6730       is no way for the client to change this).
  6731 
  6732    Response code 503
  6733       Generic response
  6734       Meaning: feature not supported.
  6735 
  6736    Response code 504
  6737       Generic response
  6738       Meaning: error in base64-encoding [RFC4648] of an argument.
  6739 
  6740 Appendix D.  Changes from RFC 977
  6741 
  6742    In general every attempt has been made to ensure that the protocol
  6743    specification in this document is compatible with the version
  6744    specified in RFC 977 [RFC977] and the various facilities adopted from
  6745    RFC 2980 [RFC2980].  However, there have been a number of changes,
  6746    some compatible and some not.
  6747 
  6748    This appendix lists these changes.  It is not guaranteed to be
  6749    exhaustive or correct and MUST NOT be relied on.
  6750 
  6751    o  A formal syntax specification (Section 9) has been added.
  6752 
  6753    o  The default character set is changed from US-ASCII [ANSI1986] to
  6754       UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8).  This
  6755       matter is discussed further in Section 10.
  6756 
  6757    o  All articles are required to have a message-id, eliminating the
  6758       "<0>" placeholder used in RFC 977 in some responses.
  6759 
  6760    o  The newsgroup name matching capabilities already documented in
  6761       RFC 977 ("wildmats", Section 4) are clarified and extended.  The
  6762       new facilities (e.g., the use of commas and exclamation marks) are
  6763       allowed wherever wildmats appear in the protocol.
  6764 
  6765    o  Support for pipelining of commands (Section 3.5) is made
  6766       mandatory.
  6767 
  6768 
  6769 
  6770 
  6771 
  6772 
  6773 Feather                     Standards Track                   [Page 121]
  6774 
  6775 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6776 
  6777 
  6778    o  The principles behind response codes (Section 3.2) have been
  6779       tidied up.  In particular:
  6780 
  6781       *  the x8x response code family, formerly used for private
  6782          extensions, is now reserved for authentication and privacy
  6783          extensions;
  6784 
  6785       *  the x9x response code family, formerly intended for debugging
  6786          facilities, are now reserved for private extensions;
  6787 
  6788       *  the 502 and 503 generic response codes (Section 3.2.1) have
  6789          been redefined;
  6790 
  6791       *  new 401, 403, 480, 483, and 504 generic response codes have
  6792          been added.
  6793 
  6794    o  The rules for article numbering (Section 6) have been clarified
  6795       (also see Section 6.1.1.2).
  6796 
  6797    o  The SLAVE command (which was ill-defined) is removed from the
  6798       protocol.
  6799 
  6800    o  Four-digit years are permitted in the NEWNEWS (Section 7.4) and
  6801       NEWGROUPS (Section 7.3) commands (two-digit years are still
  6802       permitted).  The optional distribution parameter to these commands
  6803       has been removed.
  6804 
  6805    o  The LIST command (Section 7.6.1) is greatly extended; the original
  6806       is available as LIST ACTIVE, while new variants include
  6807       ACTIVE.TIMES, DISTRIB.PATS, and NEWSGROUPS.  A new "m" status flag
  6808       is added to the LIST ACTIVE response.
  6809 
  6810    o  A new CAPABILITIES command (Section 5.2) allows clients to
  6811       determine what facilities are supported by a server.
  6812 
  6813    o  The DATE command (Section 7.1) is adopted from RFC 2980
  6814       effectively unchanged.
  6815 
  6816    o  The LISTGROUP command (Section 6.1.2) is adopted from RFC 2980.
  6817       An optional range argument has been added, and the 211 initial
  6818       response line now has the same format as the 211 response from the
  6819       GROUP command.
  6820 
  6821    o  The MODE READER command (Section 5.3) is adopted from RFC 2980 and
  6822       its meaning and effects clarified.
  6823 
  6824    o  The XHDR command in RFC 2980 has been formalised as the new HDR
  6825       (Section 8.5) and LIST HEADERS (Section 8.6) commands.
  6826 
  6827 
  6828 
  6829 Feather                     Standards Track                   [Page 122]
  6830 
  6831 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6832 
  6833 
  6834    o  The XOVER command in RFC 2980 has been formalised as the new OVER
  6835       (Section 8.3) and LIST OVERVIEW.FMT (Section 8.4) commands.  The
  6836       former can be applied to a message-id as well as to a range.
  6837 
  6838    o  The concept of article metadata (Section 8.1) has been formalised,
  6839       allowing the Bytes and Lines pseudo-headers to be deprecated.
  6840 
  6841    Client authors should note in particular that lack of support for the
  6842    CAPABILITIES command is a good indication that the server does not
  6843    support this specification.
  6844 
  6845 
  6846 
  6847 
  6848 
  6849 
  6850 
  6851 
  6852 
  6853 
  6854 
  6855 
  6856 
  6857 
  6858 
  6859 
  6860 
  6861 
  6862 
  6863 
  6864 
  6865 
  6866 
  6867 
  6868 
  6869 
  6870 
  6871 
  6872 
  6873 
  6874 
  6875 
  6876 
  6877 
  6878 
  6879 
  6880 
  6881 
  6882 
  6883 
  6884 
  6885 Feather                     Standards Track                   [Page 123]
  6886 
  6887 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6888 
  6889 
  6890 Author's Address
  6891 
  6892    Clive D.W. Feather
  6893    THUS plc
  6894    322 Regents Park Road
  6895    London
  6896    N3  2QQ
  6897    United Kingdom
  6898 
  6899    Phone: +44 20 8495 6138
  6900    Fax:   +44 870 051 9937
  6901    EMail: clive@demon.net
  6902    URI:   http://www.davros.org/
  6903 
  6904 
  6905 
  6906 
  6907 
  6908 
  6909 
  6910 
  6911 
  6912 
  6913 
  6914 
  6915 
  6916 
  6917 
  6918 
  6919 
  6920 
  6921 
  6922 
  6923 
  6924 
  6925 
  6926 
  6927 
  6928 
  6929 
  6930 
  6931 
  6932 
  6933 
  6934 
  6935 
  6936 
  6937 
  6938 
  6939 
  6940 
  6941 Feather                     Standards Track                   [Page 124]
  6942 
  6943 RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  6944 
  6945 
  6946 Full Copyright Statement
  6947 
  6948 Copyright (C) The Internet Society (2006).
  6949 
  6950    This document is subject to the rights, licenses and restrictions
  6951    contained in BCP 78, and except as set forth therein, the authors
  6952    retain all their rights.
  6953 
  6954    This document and the information contained herein are provided on an
  6955    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
  6956    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
  6957    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
  6958    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
  6959    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
  6960    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  6961 
  6962 Intellectual Property
  6963 
  6964    The IETF takes no position regarding the validity or scope of any
  6965    Intellectual Property Rights or other rights that might be claimed to
  6966    pertain to the implementation or use of the technology described in
  6967    this document or the extent to which any license under such rights
  6968    might or might not be available; nor does it represent that it has
  6969    made any independent effort to identify any such rights.  Information
  6970    on the procedures with respect to rights in RFC documents can be
  6971    found in BCP 78 and BCP 79.
  6972 
  6973    Copies of IPR disclosures made to the IETF Secretariat and any
  6974    assurances of licenses to be made available, or the result of an
  6975    attempt made to obtain a general license or permission for the use of
  6976    such proprietary rights by implementers or users of this
  6977    specification can be obtained from the IETF on-line IPR repository at
  6978    http://www.ietf.org/ipr.
  6979 
  6980    The IETF invites any interested party to bring to its attention any
  6981    copyrights, patents or patent applications, or other proprietary
  6982    rights that may cover technology that may be required to implement
  6983    this standard.  Please address the information to the IETF at ietf-
  6984    ipr@ietf.org.
  6985 
  6986 Acknowledgement
  6987 
  6988    Funding for the RFC Editor function is provided by the IETF
  6989    Administrative Support Activity (IASA).
  6990 
  6991 
  6992 
  6993 
  6994 
  6995 
  6996 
  6997 Feather                     Standards Track                   [Page 125]
  6998