Network Working Group                                         C. Feather

Request for Comments: 3977                                      THUS plc

Obsoletes: 977                                              October 2006

Updates: 2980

Category: Standards Track

                 Network News Transfer Protocol (NNTP)

Status of This Memo

   This document specifies an Internet standards track protocol for the

   Internet community, and requests discussion and suggestions for

   improvements.  Please refer to the current edition of the "Internet

   Official Protocol Standards" (STD 1) for the standardization state

   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   The Network News Transfer Protocol (NNTP) has been in use in the

   Internet for a decade, and remains one of the most popular protocols

   (by volume) in use today.  This document is a replacement for

   RFC 977, and officially updates the protocol specification.  It

   clarifies some vagueness in RFC 977, includes some new base

   functionality, and provides a specific mechanism to add standardized

   extensions to NNTP.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .  3

     1.1.  Author's Note . . . . . . . . . . . . . . . . . . . . . .  4

   2.  Notation  . . . . . . . . . . . . . . . . . . . . . . . . . .  5

   3.  Basic Concepts  . . . . . . . . . . . . . . . . . . . . . . .  6

     3.1.  Commands and Responses  . . . . . . . . . . . . . . . . .  6

       3.1.1.  Multi-line Data Blocks . . . . . . . . . . . . . . . . 8

     3.2.  Response Codes  . . . . . . . . . . . . . . . . . . . . .  9

       3.2.1.  Generic Response Codes  . . . . . . . . . . . . . . . 10

         3.2.1.1.  Examples  . . . . . . . . . . . . . . . . . . . . 12

     3.3.  Capabilities and Extensions . . . . . . . . . . . . . . . 14

       3.3.1.  Capability Descriptions . . . . . . . . . . . . . . . 14

       3.3.2.  Standard Capabilities . . . . . . . . . . . . . . . . 15

       3.3.3.  Extensions  . . . . . . . . . . . . . . . . . . . . . 16

       3.3.4.  Initial IANA Register . . . . . . . . . . . . . . . . 18

     3.4.  Mandatory and Optional Commands . . . . . . . . . . . . . 20

Feather                     Standards Track                     [Page 1]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

       3.4.1.  Reading and Transit Servers . . . . . . . . . . . . . 21

       3.4.2.  Mode Switching  . . . . . . . . . . . . . . . . . . . 21

     3.5.  Pipelining  . . . . . . . . . . . . . . . . . . . . . . . 22

       3.5.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . 23

     3.6.  Articles  . . . . . . . . . . . . . . . . . . . . . . . . 24

   4.  The WILDMAT Format  . . . . . . . . . . . . . . . . . . . . . 25

     4.1.  Wildmat Syntax  . . . . . . . . . . . . . . . . . . . . . 26

     4.2.  Wildmat Semantics . . . . . . . . . . . . . . . . . . . . 26

     4.3.  Extensions  . . . . . . . . . . . . . . . . . . . . . . . 27

     4.4.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . 27

   5.  Session Administration Commands . . . . . . . . . . . . . . . 28

     5.1.  Initial Connection  . . . . . . . . . . . . . . . . . . . 28

     5.2.  CAPABILITIES  . . . . . . . . . . . . . . . . . . . . . . 29

     5.3.  MODE READER . . . . . . . . . . . . . . . . . . . . . . . 32

     5.4.  QUIT  . . . . . . . . . . . . . . . . . . . . . . . . . . 34

   6.  Article Posting and Retrieval . . . . . . . . . . . . . . . . 35

     6.1.  Group and Article Selection . . . . . . . . . . . . . . . 36

       6.1.1.  GROUP . . . . . . . . . . . . . . . . . . . . . . . . 36

       6.1.2.  LISTGROUP . . . . . . . . . . . . . . . . . . . . . . 39

       6.1.3.  LAST  . . . . . . . . . . . . . . . . . . . . . . . . 42

       6.1.4.  NEXT  . . . . . . . . . . . . . . . . . . . . . . . . 44

     6.2.  Retrieval of Articles and Article Sections  . . . . . . . 45

       6.2.1.  ARTICLE . . . . . . . . . . . . . . . . . . . . . . . 46

       6.2.2.  HEAD  . . . . . . . . . . . . . . . . . . . . . . . . 49

       6.2.3.  BODY  . . . . . . . . . . . . . . . . . . . . . . . . 51

       6.2.4.  STAT  . . . . . . . . . . . . . . . . . . . . . . . . 53

     6.3.  Article Posting . . . . . . . . . . . . . . . . . . . . . 56

       6.3.1.  POST  . . . . . . . . . . . . . . . . . . . . . . . . 56

       6.3.2.  IHAVE . . . . . . . . . . . . . . . . . . . . . . . . 58

   7.  Information Commands  . . . . . . . . . . . . . . . . . . . . 61

     7.1.  DATE  . . . . . . . . . . . . . . . . . . . . . . . . . . 61

     7.2.  HELP  . . . . . . . . . . . . . . . . . . . . . . . . . . 62

     7.3.  NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 63

     7.4.  NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 64

     7.5.  Time  . . . . . . . . . . . . . . . . . . . . . . . . . . 65

       7.5.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . 66

     7.6.  The LIST Commands . . . . . . . . . . . . . . . . . . . . 66

       7.6.1.  LIST  . . . . . . . . . . . . . . . . . . . . . . . . 67

       7.6.2.  Standard LIST Keywords  . . . . . . . . . . . . . . . 69

       7.6.3.  LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . 70

       7.6.4.  LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . 71

       7.6.5.  LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . 72

       7.6.6.  LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . 73

   8.  Article Field Access Commands . . . . . . . . . . . . . . . . 73

     8.1.  Article Metadata  . . . . . . . . . . . . . . . . . . . . 74

       8.1.1.  The :bytes Metadata Item  . . . . . . . . . . . . . . 74

       8.1.2.  The :lines Metadata Item  . . . . . . . . . . . . . . 75

     8.2.  Database Consistency  . . . . . . . . . . . . . . . . . . 75

Feather                     Standards Track                     [Page 2]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

     8.3.  OVER  . . . . . . . . . . . . . . . . . . . . . . . . . . 76

     8.4.  LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 81

     8.5.  HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

     8.6.  LIST HEADERS  . . . . . . . . . . . . . . . . . . . . . . 87

   9.  Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . . . 90

     9.1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . 90

     9.2.  Commands  . . . . . . . . . . . . . . . . . . . . . . . . 92

     9.3.  Command Continuation  . . . . . . . . . . . . . . . . . . 93

     9.4.  Responses . . . . . . . . . . . . . . . . . . . . . . . . 93

       9.4.1.  Generic Responses . . . . . . . . . . . . . . . . . . 93

       9.4.2.  Initial Response Line Contents  . . . . . . . . . . . 94

       9.4.3.  Multi-line Response Contents  . . . . . . . . . . . . 94

     9.5.  Capability Lines  . . . . . . . . . . . . . . . . . . . . 95

     9.6.  LIST Variants . . . . . . . . . . . . . . . . . . . . . . 96

     9.7.  Articles  . . . . . . . . . . . . . . . . . . . . . . . . 97

     9.8.  General Non-terminals . . . . . . . . . . . . . . . . . . 97

     9.9.  Extensions and Validation . . . . . . . . . . . . . . . . 99

   10. Internationalisation Considerations . . . . . . . . . . . . .100

     10.1. Introduction and Historical Situation . . . . . . . . . .100

     10.2. This Specification  . . . . . . . . . . . . . . . . . . .101

     10.3. Outstanding Issues  . . . . . . . . . . . . . . . . . . .102

   11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .103

   12. Security Considerations . . . . . . . . . . . . . . . . . . .103

     12.1. Personal and Proprietary Information  . . . . . . . . . .104

     12.2. Abuse of Server Log Information . . . . . . . . . . . . .104

     12.3. Weak Authentication and Access Control  . . . . . . . . .104

     12.4. DNS Spoofing  . . . . . . . . . . . . . . . . . . . . . .104

     12.5. UTF-8 Issues  . . . . . . . . . . . . . . . . . . . . . .105

     12.6. Caching of Capability Lists . . . . . . . . . . . . . . .106

   13. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .107

   14. References  . . . . . . . . . . . . . . . . . . . . . . . . .110

     14.1. Normative References  . . . . . . . . . . . . . . . . . .110

     14.2. Informative References  . . . . . . . . . . . . . . . . .110

   A.  Interaction with Other Specifications . . . . . . . . . . . .112

     A.1.  Header Folding  . . . . . . . . . . . . . . . . . . . . .112

     A.2.  Message-IDs . . . . . . . . . . . . . . . . . . . . . . .112

     A.3.  Article Posting . . . . . . . . . . . . . . . . . . . . .114

   B.  Summary of Commands . . . . . . . . . . . . . . . . . . . . .115

   C.  Summary of Response Codes . . . . . . . . . . . . . . . . . .117

   D.  Changes from RFC 977  . . . . . . . . . . . . . . . . . . . .121

1.  Introduction

   This document specifies the Network News Transfer Protocol (NNTP),

   which is used for the distribution, inquiry, retrieval, and posting

   of Netnews articles using a reliable stream-based mechanism.  For

   news-reading clients, NNTP enables retrieval of news articles that

Feather                     Standards Track                     [Page 3]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   are stored in a central database, giving subscribers the ability to

   select only those articles they wish to read.

   The Netnews model provides for indexing, cross-referencing, and

   expiration of aged messages.  NNTP is designed for efficient

   transmission of Netnews articles over a reliable full duplex

   communication channel.

   Although the protocol specification in this document is largely

   compatible with the version specified in RFC 977 [RFC977], a number

   of changes are summarised in Appendix D.  In particular:

   o  the default character set is changed from US-ASCII [ANSI1986] to

      UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8);

   o  a number of commands that were optional in RFC 977 or that have

      been taken from RFC 2980 [RFC2980] are now mandatory; and

   o  a CAPABILITIES command has been added to allow clients to

      determine what functionality is available from a server.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",

   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this

   document are to be interpreted as described in RFC 2119 [RFC2119].

   An implementation is not compliant if it fails to satisfy one or more

   of the MUST requirements for this protocol.  An implementation that

   satisfies all the MUST and all the SHOULD requirements for its

   protocols is said to be "unconditionally compliant"; one that

   satisfies all the MUST requirements but not all the SHOULD

   requirements for NNTP is said to be "conditionally compliant".

   For the remainder of this document, the terms "client" and "client

   host" refer to a host making use of the NNTP service, while the terms

   "server" and "server host" refer to a host that offers the NNTP

   service.

1.1.  Author's Note

   This document is written in XML using an NNTP-specific DTD.  Custom

   software is used to convert this to RFC 2629 [RFC2629] format, and

   then the public "xml2rfc" package to further reduce this to text,

   nroff source, and HTML.

   No perl was used in producing this document.

Feather                     Standards Track                     [Page 4]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

2.  Notation

   The following notational conventions are used in this document.

     UPPERCASE     indicates literal text to be included in the

                   command.

     lowercase     indicates a token described elsewhere.

     [brackets]    indicate that the enclosed material is optional.

     elliptical    indicates that the argument may be repeated any

     ... marks     number of times (it must occur at least once).

     vertical|bar  indicates a choice of two mutually exclusive

                   arguments (exactly one must be provided).

   The name "message-id" for a command or response argument indicates

   that it is the message-id of an article as described in Section 3.6,

   including the angle brackets.

   The name "wildmat" for an argument indicates that it is a wildmat as

   defined in Section 4.  If the argument does not meet the requirements

   of that section (for example, if it does not fit the grammar of

   Section 4.1), the NNTP server MAY place some interpretation on it

   (not specified by this document) or otherwise MUST treat it as a

   syntax error.

   Responses for each command will be described in tables listing the

   required format of a response followed by the meaning that should be

   ascribed to that response.

   The terms "NUL", "TAB", "LF", "CR, and "space" refer to the octets

   %x00, %x09, %x0A, %x0D, and %x20, respectively (that is, the octets

   with those codes in US-ASCII [ANSI1986] and thus in UTF-8 [RFC3629]).

   The term "CRLF" or "CRLF pair" means the sequence CR immediately

   followed by LF (that is, %x0D.0A).  A "printable US-ASCII character"

   is an octet in the range %x21-7E.  Quoted characters refer to the

   octets with those codes in US-ASCII (so "." and "<" refer to %x2E and

   %x3C) and will always be printable US-ASCII characters; similarly,

   "digit" refers to the octets %x30-39.

   A "keyword" MUST consist only of US-ASCII letters, digits, and the

   characters dot (".") and dash ("-") and MUST begin with a letter.

   Keywords MUST be at least three characters in length.

Feather                     Standards Track                     [Page 5]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   Examples in this document are not normative but serve to illustrate

   usages, arguments, and responses.  In the examples, a "[C]" will be

   used to represent the client host and an "[S]" will be used to

   represent the server host.  Most of the examples do not rely on a

   particular server state.  In some cases, however, they do assume that

   the currently selected newsgroup (see the GROUP command,

   Section 6.1.1) is invalid; when so, this is indicated at the start of

   the example.  Examples may use commands or other keywords not defined

   in this specification (such as an XENCRYPT command).  These will be

   used to illustrate some point and do not imply that any such command

   is defined elsewhere or needs to exist in any particular

   implementation.

   Terms that might be read as specifying details of a client or server

   implementation, such as "database", are used simply to ease

   description.  Provided that implementations conform to the protocol

   and format specifications in this document, no specific technique is

   mandated.

3.  Basic Concepts

3.1.  Commands and Responses

   NNTP operates over any reliable bi-directional 8-bit-wide data stream

   channel.  When the connection is established, the NNTP server host

   MUST send a greeting.  The client host and server host then exchange

   commands and responses (respectively) until the connection is closed

   or aborted.  If the connection used is TCP, then the server host

   starts the NNTP service by listening on a TCP port.  When a client

   host wishes to make use of the service, it MUST establish a TCP

   connection with the server host by connecting to that host on the

   same port on which the server is listening.

   The character set for all NNTP commands is UTF-8 [RFC3629].  Commands

   in NNTP MUST consist of a keyword, which MAY be followed by one or

   more arguments.  A CRLF pair MUST terminate all commands.  Multiple

   commands MUST NOT be on the same line.  Unless otherwise noted

   elsewhere in this document, arguments SHOULD consist of printable US-

   ASCII characters.  Keywords and arguments MUST each be separated by

   one or more space or TAB characters.  Command lines MUST NOT exceed

   512 octets, which includes the terminating CRLF pair.  The arguments

   MUST NOT exceed 497 octets.  A server MAY relax these limits for

   commands defined in an extension.

   Where this specification permits UTF-8 characters outside the range

   of U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark

   (U+FEFF, encoding %xEF.BB.BF) and MUST use the Word Joiner (U+2060,

   encoding %xE2.91.A0) for the meaning Zero Width No-Break Space in

Feather                     Standards Track                     [Page 6]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   command lines and the initial lines of responses.  Implementations

   SHOULD apply these same principles throughout.

   The term "character" means a single Unicode code point.

   Implementations are not required to carry out Unicode normalisation.

   Thus, U+0084 (A-dieresis) is one character, while U+0041 U+0308 (A

   composed with dieresis) is two; the two need not be treated as

   equivalent.

   Commands may have variants; if so, they use a second keyword

   immediately after the first to indicate which variant is required.

   The only such commands in this specification are LIST and MODE.  Note

   that such variants are sometimes referred to as if they were commands

   in their own right: "the LIST ACTIVE" command should be read as

   shorthand for "the ACTIVE variant of the LIST command".

   Keywords are case insensitive; the case of keywords for commands MUST

   be ignored by the server.  Command and response arguments are case or

   language specific only when stated, either in this document or in

   other relevant specifications.

   In some cases, a command involves more data than just a single line.

   The further data may be sent either immediately after the command

   line (there are no instances of this in this specification, but there

   are in extensions such as [NNTP-STREAM]) or following a request from

   the server (indicated by a 3xx response).

   Each response MUST start with a three-digit response code that is

   sufficient to distinguish all responses.  Certain valid responses are

   defined to be multi-line; for all others, the response is contained

   in a single line.  The initial line of the response MUST NOT exceed

   512 octets, which includes the response code and the terminating CRLF

   pair; an extension MAY specify a greater maximum for commands that it

   defines, but not for any other command.  Single-line responses

   consist of an initial line only.  Multi-line responses consist of an

   initial line followed by a multi-line data block.

   An NNTP server MAY have an inactivity autologout timer.  Such a timer

   SHOULD be of at least three minutes' duration, with the exception

   that there MAY be a shorter limit on how long the server is willing

   to wait for the first command from the client.  The receipt of any

   command from the client during the timer interval SHOULD suffice to

   reset the autologout timer.  Similarly, the receipt of any

   significant amount of data from a client that is sending a multi-line

   data block (such as during a POST or IHAVE command) SHOULD suffice to

   reset the autologout timer.  When the timer expires, the server

   SHOULD close the connection without sending any response to the

   client.

Feather                     Standards Track                     [Page 7]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

3.1.1.  Multi-line Data Blocks

   A multi-line data block is used in certain commands and responses.

   It MUST adhere to the following rules:

   1.  The block consists of a sequence of zero or more "lines", each

       being a stream of octets ending with a CRLF pair.  Apart from

       those line endings, the stream MUST NOT include the octets NUL,

       LF, or CR.

   2.  In a multi-line response, the block immediately follows the CRLF

       at the end of the initial line of the response.  When used in any

       other context, the specific command will define when the block is

       sent.

   3.  If any line of the data block begins with the "termination octet"

       ("." or %x2E), that line MUST be "dot-stuffed" by prepending an

       additional termination octet to that line of the block.

   4.  The lines of the block MUST be followed by a terminating line

       consisting of a single termination octet followed by a CRLF pair

       in the normal way.  Thus, unless it is empty, a multi-line block

       is always terminated with the five octets CRLF "." CRLF

       (%x0D.0A.2E.0D.0A).

   5.  When a multi-line block is interpreted, the "dot-stuffing" MUST

       be undone; i.e., the recipient MUST ensure that, in any line

       beginning with the termination octet followed by octets other

       than a CRLF pair, that initial termination octet is disregarded.

   6.  Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT

       be considered part of the multi-line block; i.e., the recipient

       MUST ensure that any line beginning with the termination octet

       followed immediately by a CRLF pair is disregarded.  (The first

       CRLF pair of the terminating CRLF "." CRLF of a non-empty block

       is, of course, part of the last line of the block.)

   Note that texts using an encoding (such as UTF-16 or UTF-32) that may

   contain the octets NUL, LF, or CR other than a CRLF pair cannot be

   reliably conveyed in the above format (that is, they violate the MUST

   requirement above).  However, except when stated otherwise, this

   specification does not require the content to be UTF-8, and therefore

   (subject to that same requirement) it MAY include octets above and

   below 128 mixed arbitrarily.

   This document does not place any limit on the length of a line in a

   multi-line block.  However, the standards that define the format of

   articles may do so.

Feather                     Standards Track                     [Page 8]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

3.2.  Response Codes

   Each response MUST begin with a three-digit status indicator.  These

   are status reports from the server and indicate the response to the

   last command received from the client.

   The first digit of the response broadly indicates the success,

   failure, or progress of the previous command:

      1xx - Informative message

      2xx - Command completed OK

      3xx - Command OK so far; send the rest of it

      4xx - Command was syntactically correct but failed for some reason

      5xx - Command unknown, unsupported, unavailable, or syntax error

   The next digit in the code indicates the function response category:

      x0x - Connection, setup, and miscellaneous messages

      x1x - Newsgroup selection

      x2x - Article selection

      x3x - Distribution functions

      x4x - Posting

      x8x - Reserved for authentication and privacy extensions

      x9x - Reserved for private use (non-standard extensions)

   Certain responses contain arguments such as numbers and names in

   addition to the status indicator.  In those cases, to simplify

   interpretation by the client, the number and type of such arguments

   is fixed for each response code, as is whether the code is

   single-line or multi-line.  Any extension MUST follow this principle

   as well.  Note that, for historical reasons, the 211 response code is

   an exception to this in that the response may be single-line or

   multi-line depending on the command (GROUP or LISTGROUP) that

   generated it.  In all other cases, the client MUST only use the

   status indicator itself to determine the nature of the response.  The

   exact response codes that can be returned by any given command are

   detailed in the description of that command.

   Arguments MUST be separated from the numeric status indicator and

   from each other by a single space.  All numeric arguments MUST be in

   base 10 (decimal) format and MAY have leading zeros.  String

   arguments MUST contain at least one character and MUST NOT contain

   TAB, LF, CR, or space.  The server MAY add any text after the

   response code or last argument, as appropriate, and the client MUST

   NOT make decisions based on this text.  Such text MUST be separated

   from the numeric status indicator or the last argument by at least

   one space.

Feather                     Standards Track                     [Page 9]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   The server MUST respond to any command with the appropriate generic

   response (given in Section 3.2.1) if it represents the situation.

   Otherwise, each recognized command MUST return one of the response

   codes specifically listed in its description or in an extension.  A

   server MAY provide extensions to this specification, including new

   commands, new variants or features of existing commands, and other

   ways of changing the internal state of the server.  However, the

   server MUST NOT produce any other responses to a client that does not

   invoke any of the additional features.  (Therefore, a client that

   restricts itself to this specification will only receive the

   responses that are listed.)

   If a client receives an unexpected response, it SHOULD use the first

   digit of the response to determine the result.  For example, an

   unexpected 2xx should be taken as success, and an unexpected 4xx or

   5xx as failure.

   Response codes not specified in this document MAY be used for any

   installation-specific additional commands also not specified.  These

   SHOULD be chosen to fit the pattern of x9x specified above.

   Neither this document nor any registered extension (see

   Section 3.3.3) will specify any response codes of the x9x pattern.

   (Implementers of extensions are accordingly cautioned not to use such

   responses for extensions that may subsequently be submitted for

   registration.)

3.2.1.  Generic Response Codes

   The server MUST respond to any command with the appropriate one of

   the following generic responses if it represents the situation.

   If the command is not recognized, or if it is an optional command

   that is not implemented by the server, the response code 500 MUST be

   returned.

   If there is a syntax error in the arguments of a recognized command,

   including the case where more arguments are provided than the command

   specifies or the command line is longer than the server accepts, the

   response code 501 MUST be returned.  The line MUST NOT be truncated

   or split and then interpreted.  Note that where a command has

   variants depending on a second keyword (e.g., LIST ACTIVE and LIST

   NEWSGROUPS), 501 MUST be used when the base command is implemented

   but the requested variant is not, and 500 MUST be used only when the

   base command itself is not implemented.

   If an argument is required to be a base64-encoded string [RFC4648]

   (there are no such arguments in this specification, but there may be

Feather                     Standards Track                    [Page 10]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   in extensions) and is not validly encoded, the response code 504 MUST

   be returned.

   If the server experiences an internal fault or problem that means it

   is unable to carry out the command (for example, a necessary file is

   missing or a necessary service could not be contacted), the response

   code 403 MUST be returned.  If the server recognizes the command but

   does not provide an optional feature (for example, because it does

   not store the required information), or if it only handles a subset

   of legitimate cases (see the HDR command, Section 8.5, for an

   example), the response code 503 MUST be returned.

   If the client is not authorized to use the specified facility when

   the server is in its current state, then the appropriate one of the

   following response codes MUST be used.

   502: It is necessary to terminate the connection and to start a new

      one with the appropriate authority before the command can be used.

      Historically, some mode-switching servers (see Section 3.4.1) used

      this response to indicate that this command will become available

      after the MODE READER command (Section 5.3) is used, but this

      usage does not conform to this specification and MUST NOT be used.

      Note that the server MUST NOT close the connection immediately

      after a 502 response except at the initial connection

      (Section 5.1) and with the MODE READER command.

   480: The client must authenticate itself to the server (that is, it

      must provide information as to the identity of the client) before

      the facility can be used on this connection.  This will involve

      the use of an authentication extension such as [NNTP-AUTH].

   483: The client must negotiate appropriate privacy protection on the

      connection.  This will involve the use of a privacy extension such

      as [NNTP-TLS].

   401: The client must change the state of the connection in some other

      manner.  The first argument of the response MUST be the capability

      label (see Section 5.2) of the facility that provides the

      necessary mechanism (usually an extension, which may be a private

      extension).  The server MUST NOT use this response code except as

      specified by the definition of the capability in question.

   If the server has to terminate the connection for some reason, it

   MUST give a 400 response code to the next command and then

   immediately close the connection.  Following a 400 response, clients

   SHOULD NOT simply reconnect immediately and retry the same actions.

   Rather, a client SHOULD either use an exponentially increasing delay

   between retries (e.g., double the waiting time after each 400

Feather                     Standards Track                    [Page 11]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   response) or present any associated text to the user for them to

   decide whether and when to retry.

   The client MUST be prepared to receive any of these responses for any

   command (except, of course, that the server MUST NOT generate a 500

   response code for mandatory commands).

3.2.1.1.  Examples

   Example of an unknown command:

      [C] MAIL

      [S] 500 Unknown command

   Example of an unsupported command:

      [C] CAPABILITIES

      [S] 101 Capability list:

      [S] VERSION 2

      [S] READER

      [S] NEWNEWS

      [S] LIST ACTIVE NEWSGROUPS

      [S] .

      [C] OVER

      [S] 500 Unknown command

   Example of an unsupported variant:

      [C] MODE POSTER

      [S] 501 Unknown MODE option

   Example of a syntax error:

      [C] ARTICLE a.message.id@no.angle.brackets

      [S] 501 Syntax error

   Example of an overlong command line:

      [C] HEAD 53 54 55

      [S] 501 Too many arguments

   Example of a bad wildmat:

      [C] LIST ACTIVE u[ks].*

      [S] 501 Syntax error

Feather                     Standards Track                    [Page 12]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   Example of a base64-encoding error (the second argument is meant to

   be base64 encoded):

      [C] XENCRYPT RSA abcd=efg

      [S] 504 Base64 encoding error

   Example of an attempt to access a facility not available to this

   connection:

      [C] MODE READER

      [S] 200 Reader mode, posting permitted

      [C] IHAVE <i.am.an.article.you.will.want@example.com>

      [S] 500 Permission denied

   Example of an attempt to access a facility requiring authentication:

      [C] GROUP secret.group

      [S] 480 Permission denied

   Example of a successful attempt following such authentication:

      [C] XSECRET fred flintstone

      [S] 290 Password for fred accepted

      [C] GROUP secret.group

      [S] 211 5 1 20 secret.group selected

   Example of an attempt to access a facility requiring privacy:

      [C] GROUP secret.group

      [S] 483 Secure connection required

      [C] XENCRYPT

      [Client and server negotiate encryption on the link]

      [S] 283 Encrypted link established

      [C] GROUP secret.group

      [S] 211 5 1 20 secret.group selected

   Example of a need to change mode before a facility is used:

      [C] GROUP binary.group

      [S] 401 XHOST Not on this virtual host

      [C] XHOST binary.news.example.org

      [S] 290 binary.news.example.org virtual host selected

      [C] GROUP binary.group

      [S] 211 5 1 77 binary.group selected

Feather                     Standards Track                    [Page 13]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   Example of a temporary failure:

      [C] GROUP archive.local

      [S] 403 Archive server temporarily offline

   Example of the server needing to close down immediately:

      [C] ARTICLE 123

      [S] 400 Power supply failed, running on UPS

      [Server closes connection.]

3.3.  Capabilities and Extensions

   Not all NNTP servers provide exactly the same facilities, both

   because this specification allows variation and because servers may

   provide extensions.  A set of facilities that are related are called

   a "capability".  This specification provides a way to determine what

   capabilities are available, includes a list of standard capabilities,

   and includes a mechanism (the extension mechanism) for defining new

   capabilities.

3.3.1.  Capability Descriptions

   A client can determine the available capabilities of the server by

   using the CAPABILITIES command (Section 5.2).  This returns a

   capability list, which is a list of capability lines.  Each line

   describes one available capability.

   Each capability line consists of one or more tokens, which MUST be

   separated by one or more space or TAB characters.  A token is a

   string of 1 or more printable UTF-8 characters (that is, either

   printable US-ASCII characters or any UTF-8 sequence outside the US-

   ASCII range, but not space or TAB).  Unless stated otherwise, tokens

   are case insensitive.  Each capability line consists of the

   following:

   o  The capability label, which is a keyword indicating the

      capability.  A capability label may be defined by this

      specification or a successor, or by an extension.

   o  The label is then followed by zero or more tokens, which are

      arguments of the capability.  The form and meaning of these tokens

      is specific to each capability.

   The server MUST ensure that the capability list accurately reflects

   the capabilities (including extensions) currently available.  If a

   capability is only available with the server in a certain state (for

   example, only after authentication), the list MUST only include the

Feather                     Standards Track                    [Page 14]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   capability label when the server is in that state.  Similarly, if

   only some of the commands in an extension will be available, or if

   the behaviour of the extension will change in some other manner,

   according to the state of the server, this MUST be indicated by

   different arguments in the capability line.

   Note that a capability line can only begin with a letter.  Lines

   beginning with other characters are reserved for future versions of

   this specification.  In order to interoperate with such versions,

   clients MUST be prepared to receive lines beginning with other

   characters and MUST ignore any they do not understand.

3.3.2.  Standard Capabilities

   The following capabilities are defined by this specification.

   VERSION

      This capability MUST be advertised by all servers and MUST be the

      first capability in the capability list; it indicates the

      version(s) of NNTP that the server supports.  There must be at

      least one argument; each argument is a decimal number and MUST NOT

      have a leading zero.  Version numbers are assigned only in RFCs

      that update or replace this specification; servers MUST NOT create

      their own version numbers.

      The version number of this specification is 2.

   READER

      This capability indicates that the server implements the various

      commands useful for reading clients.

   IHAVE

      This capability indicates that the server implements the IHAVE

      command.

   POST

      This capability indicates that the server implements the POST

      command.

   NEWNEWS

      This capability indicates that the server implements the NEWNEWS

      command.

   HDR

      This capability indicates that the server implements the header

      access commands (HDR and LIST HEADERS).

Feather                     Standards Track                    [Page 15]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   OVER

      This capability indicates that the server implements the overview

      access commands (OVER and LIST OVERVIEW.FMT).  If and only if the

      server supports the message-id form of the OVER command, there

      must be a single argument MSGID.

   LIST

      This capability indicates that the server implements at least one

      variant of the LIST command.  There MUST be one argument for each

      variant of the LIST command supported by the server, giving the

      keyword for that variant.

   IMPLEMENTATION

      This capability MAY be provided by a server.  If so, the arguments

      SHOULD be used to provide information such as the server software

      name and version number.  The client MUST NOT use this line to

      determine capabilities of the server.  (While servers often

      provide this information in the initial greeting, clients need to

      guess whether this is the case; this capability makes it clear

      what the information is.)

   MODE-READER

      This capability indicates that the server is mode-switching

      (Section 3.4.2) and that the MODE READER command needs to be used

      to enable the READER capability.

3.3.3.  Extensions

   Although NNTP is widely and robustly deployed, some parts of the

   Internet community might wish to extend the NNTP service.  It must be

   emphasized that any extension to NNTP should not be considered

   lightly.  NNTP's strength comes primarily from its simplicity.

   Experience with many protocols has shown that:

      Protocols with few options tend towards ubiquity, whilst protocols

      with many options tend towards obscurity.

   This means that each and every extension, regardless of its benefits,

   must be carefully scrutinized with respect to its implementation,

   deployment, and interoperability costs.  In many cases, the cost of

   extending the NNTP service will likely outweigh the benefit.

   An extension is a package of associated facilities, often but not

   always including one or more new commands.  Each extension MUST

   define at least one new capability label (this will often, but need

   not, be the name of one of these new commands).  While any additional

   capability information can normally be specified using arguments to

Feather                     Standards Track                    [Page 16]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   that label, an extension MAY define more than one capability label.

   However, this SHOULD be limited to exceptional circumstances.

   An extension is either a private extension, or its capabilities are

   included in the IANA registry of capabilities (see Section 3.3.4) and

   it is defined in an RFC (in which case it is a "registered

   extension").  Such RFCs either must be on the standards track or must

   define an IESG-approved experimental protocol.

   The definition of an extension must include the following:

   o  a descriptive name for the extension.

   o  the capability label or labels defined by the extension (the

      capability label of a registered extension MUST NOT begin with

      "X").

   o  The syntax, values, and meanings of any arguments for each

      capability label defined by the extension.

   o  Any new NNTP commands associated with the extension (the names of

      commands associated with registered extensions MUST NOT begin with

      "X").

   o  The syntax and possible values of arguments associated with the

      new NNTP commands.

   o  The response codes and possible values of arguments for the

      responses of the new NNTP commands.

   o  Any new arguments the extension associates with any other

      pre-existing NNTP commands.

   o  Any increase in the maximum length of commands and initial

      response lines over the value specified in this document.

   o  A specific statement about the effect on pipelining that this

      extension may have (if any).

   o  A specific statement about the circumstances when use of this

      extension can alter the contents of the capabilities list (other

      than the new capability labels it defines).

   o  A specific statement about the circumstances under which the

      extension can cause any pre-existing command to produce a 401,

      480, or 483 response.

Feather                     Standards Track                    [Page 17]

RFC 3977         Network News Transfer Protocol (NNTP)      October 2006

   o  A description of how the use of MODE READER on a mode-switching

      server interacts with the extension.

   o  A description of how support for the extension affects the

      behaviour of a server and NNTP client in any other manner not

      outlined above.

   o  Formal syntax as described in Section 9.9.

   A private extension MAY or MAY NOT be included in the capabilities

   list.  If it is, the capability label MUST begin with "X".  A server

   MAY provide additional keywords (for new commands and also for new

   variants of existing commands) as part of a private extension.  To

   avoid the risk of a clash with a future registered extension, these

   keywords SHOULD begin with "X".

   If the server advertises a capability defined by a registered

   extension, it MUST implement the extension so as to fully conform

   with the specification (for example, it MUST implement all the

   commands that the extension describes as mandatory).  If it does not

   implement the extension as specified, it MUST NOT list the extension

   in the capabilities list under its registered name.  In that case, it

   MAY, but SHOULD NOT, provide a private extension (not listed, or

   listed with a different name) that implements part of the extension

   or implements the commands of the extension with a different meaning.

   A server MUST NOT send different response codes to basic NNTP

   commands documented here or to commands documented in registered

   extensions in response to the availability or use of a private

   extension.

3.3.4.  Initial IANA Register

   IANA will maintain a registry of NNTP capability labels.  All

   capability labels in the registry MUST be keywords and MUST NOT begin

   with X.