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