| TOC |
|
By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
This Internet-Draft will expire on November 16, 2004.
Copyright (C) The Internet Society (2004). All Rights Reserved.
RFC YYYY specifies the Network News Transport Protocol (NNTP), which is used for the distribution, inquiry, retrieval, and posting of Netnews articles using a reliable stream-based mechanism. That specification includes a mechanism to allow extensions to the protocol to be provided by a server.
This document specifies a number of generally useful extensions to NNTP, including listing the specific article numbers in a newsgroup, overview database support, and batched header retrieval.
This document is a product of the NNTP Working Group, chaired by Russ Allbery and Ned Freed.
This is draft 00 pre-publication version 1.
This document is written in XML using an NNTP-specific DTD. Custom software is used to convert this to RFC 2629Rose, M., Writing I-Ds and RFCs using XML, June 1999.[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.
UNIX is a registered trademark of The Open Group.
1.
Introduction
2.
Notation
3.
The LISTGROUP extension
3.1
Formal specification
3.2
LISTGROUP
4.
Article metadata
4.1
The :bytes metadata item
4.2
The :lines metadata item
5.
The OVER extension
5.1
Formal specification
5.2
The Overview Database
5.3
OVER
5.4
LIST OVERVIEW.FMT
6.
The HDR extension
6.1
Formal specification
6.2
Scope and limitations
6.3
HDR
6.4
LIST HEADERS
7.
Augmented BNF Syntax for NNTP
7.1
Commands
7.2
LIST EXTENSIONS responses
7.3
Multi-line response contents
7.4
Imported non-terminals
8.
IANA Considerations
9.
Security Considerations
10.
Acknowledgements
§.
Normative References
§.
Informative References
§
Author's Address
A.
Summary of Response Codes
§
Intellectual Property and Copyright Statements
| TOC |
[NNTP]Feather, C., Network News Transport Protocol, . specifies the Network News Transport Protocol (NNTP), which is used for the distribution, inquiry, retrieval, and posting of Netnews articles using a reliable stream-based mechanism. That specification includes a mechanism to allow extensions to the protocol to be provided by a server.
This document specifies a number of generally useful extensions to NNTP, including listing the specific article numbers in a newsgroup, overview database support, and batched header retrieval. These are known as the "NNTP core extensions". Many of these extensions are based on ones described RFC 2980Barber, S., Common NNTP Extensions, October 2000.[RFC2980].
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 2119Bradner, S., Key words for use in RFCs to Indicate Requirement Levels, March 1997.[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 term "client" or "client host" refers to a host making use of the NNTP service, while the term "server" or "server host" refers to a host that offers the NNTP service.
This specification is to be read in conjunction with the NNTP base specificationFeather, C., Network News Transport Protocol, .[NNTP]. Except where specifically stated otherwise, in the case of a conflict between these two documents [NNTP]Feather, C., Network News Transport Protocol, . takes precedence over this one.
A server MAY provide each of these extensions, independently of any other. If the server provides the extension, it MUST include the appropriate extension label in the response to LIST EXTENSIONS. If it does not provide it, it MUST NOT include the appropriate extension label. The descriptions of facilities in each section are written as if the extension is provided. If it is not provided, the entire section should be ignored.
If the server provides an extension, it MUST implement all of the commands in the specification of the extension except for those marked as optional. If it does not provide an extension, it MUST NOT implement any of the commands in the specification of that extension.
| TOC |
The notational conventions used in this document are the same as those in [NNTP]Feather, C., Network News Transport Protocol, ., and any term not defined in this document has the same meaning as in that one.
In particular:
UPPERCASE indicates literal text to be included in the
command;
lowercase indicates a token described elsewhere;
[brackets] indicate that the argument is optional;
ellipsis... indicates that the argument may be repeated any
number of times (it must occur at least once);
vertical|bar indicates a choice of two mutually exclusive
arguments (exactly one must be provided).
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 a "[S]" will be used to represent the server host.
| TOC |
- Syntax
- LISTGROUP [group]
- Responses
- 211 number low high group Article numbers follow (multiline)
411 No such newsgroup
412 No newsgroup selected [1]- Parameters
- group = name of newsgroup
number = estimated number of articles in the group
low = reported low water mark
high = reported high water mark- [1]
- The 412 response can only occur if no group has been specified.
The LISTGROUP command is used to get a listing of all the article numbers in a particular newsgroup. As a side effect, it also selects the group in the same way as the GROUP command in [NNTP]Feather, C., Network News Transport Protocol, ..
The optional argument is the name of the newsgroup to be selected (e.g. "news.software.misc"). A list of valid newsgroups may be obtained from the LIST ACTIVE command. If no group is specified, the current selected newsgroup is used.
On success, the list of article numbers is returned as a multi-line response following the 211 response code. The list contains one number per line, is in numerical order, and lists precisely those articles that exist in the group. The arguments on the initial response line include the group name, the article numbers of the first and last articles in the group, and an estimate of the number of articles in the group. These arguments are the same as for the GROUP command, and are described in more detail in [NNTP]Feather, C., Network News Transport Protocol, ..
When a valid group is selected by means of this command, the current selected newsgroup MUST be set to that group and the current article number MUST be set to the first article in the group. If an empty newsgroup is selected, the current article pointer is made invalid. If an invalid group is specified, the current selected newsgroup and current article number MUST NOT be changed.
The LISTGROUP command MAY be used by a client as a replacement for the GROUP command in establishing a valid current selected newsgroup and current article number.
If the group specified is not available on the server, a 411 response MUST be returned. If no group is specified and the current selected newsgroup is invalid, a 412 response MUST be returned.
Example of LISTGROUP on an empty group:
[C] LISTGROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup list follows
[S] .
Example of LISTGROUP on a valid current selected newsgroup:
[C] GROUP misc.test
[S] 211 2000 3000234 3002322 misc.test
[C] LISTGROUP
[S] 211 2000 3000234 3002322 misc.test list follows
[S] 3000234
[S] 3000237
[S] 3000238
[S] 3000239
[S] 3002322
[S] .
Example of LISTGROUP failing because no group has been selected:
[Assumes current selected newsgroup is invalid.]
[C] LISTGROUP
[S] 412 no current group
[C] GROUP example.is.sob.bradner.or.barber
[S] 411 no such group
[C] LISTGROUP
[S] 412 no current group
| TOC |
The OVER and HDR extensions refer to the concept of "article metadata". This is data about articles that does not occur within the article itself. Each metadata item has a name which MUST begin with a colon (and which MUST NOT contain a colon elsewhere within it). As with header names, metadata item names are not case-sensitive.
When generating a metadata item, the server MUST compute it for itself and MUST NOT trust any related value provided in the article. (In particular, a Lines or Bytes header in the article MUST NOT be assumed to specify the correct number of lines or bytes in the article.) If the server has access to several non-identical copies of an article, the value returned MUST be correct for any copy of that article retrieved during the same session.
This specification defines two metadata items: ":bytes" and ":lines". Other metadata items may be defined by extensions. The names of metadata items defined by registered extensions MUST NOT begin with ":x-". To avoid the risk of a clash with a future registered extension, the names of metadata items defined by private extensions SHOULD begin with ":x-".
The :bytes metadata item for an article is a decimal integer. It SHOULD equal the number of octets in the entire article - headers, body, and separating empty line (counting a CRLF pair as two octets, and excluding both the "." CRLF terminating the response and any "." added for "byte-stuffing" purposes).
Note to client implementers: some existing servers return a value different to that above. The commonest reasons for this are:
Implementations should be prepared for such variation and MUST NOT rely on the value being accurate.
The :lines metadata item for an article is a decimal integer. It MUST equal the number of lines in the article body (excluding the empty line separating headers and body); equivalently, it is two less than the number of CRLF pairs that the BODY command would return for that article (the extra two are those following the response code and the termination octet).
| TOC |
The OVER extension provides access to the "overview database", which is a database of headers extracted from incoming articles. Only certain headers are included in the database. The database also includes some article metadata.
The information stored in the database may change over time. If the database records the content or absence of a given field (that is, a header or metadata item) for all articles, it is said to be "consistent" for that field. If it records the content of a header for some articles but not for others that nevertheless included that header, or records a metadata item for some articles but not others to which that item applies, it is said to be "inconsistent" for that field.
The LIST OVERVIEW.FMT command SHOULD list all the fields for which the database is consistent at that moment. It MAY omit such fields (for example if it is not known whether the database is consistent or inconsistent). It MUST NOT include fields for which the database is inconsistent or which are not stored in the database. Therefore if a header appears in the LIST OVERVIEW.FMT output but not the OVER output for a given article, that header does not appear in the article, and similarly for metadata items.
These rules assume the fields being stored in the database remain constant for long periods of time, with the database therefore being consistent. When the set of fields to be stored is changed, it will be inconsistent until either the database is rebuilt or the only articles remaining are those received since the change. Therefore the output from LIST OVERVIEW.FMT needs to be altered twice: before any fields stop being stored, they MUST be removed from the output, then when the database is once more known to be consistent, the new fields SHOULD be added to the output.
Support for the message-id form of the OVER command is optional. If an implementation supports this form, it MUST use the argument "MSGID" following the extension label in the output of LIST EXTENSIONS; if not, it MUST NOT use any argument.
This extension is based on the Overview/NOV databaseRobertson, R., FAQ: Overview database / NOV General Information, January 1995.[ROBE1995] developed by Geoff Collyer.
- Syntax
- OVER message-id
OVER range
OVER- Responses
- First form (message-id specified)
- 224 Overview information follows (multiline)
430 No article with that message-id- Second form (range specified)
- 224 Overview information follows (multiline)
412 No newsgroup selected
423 No articles in that range- Third form (current article number used)
- 224 Overview information follows (multiline)
412 No newsgroup selected
420 Current article number is invalid- Parameters
- range = number(s) of articles
message-id = message-id of article
The OVER command returns the contents of the headers and metadata in the database for an article specified by message-id, or from a specified article or range of articles in the current selected newsgroup.
The message-id argument indicates a specific article. The range argument may be any of the following:
If neither is specified, the current article number is used. Support for the first (message-id) form is optional. If it is not supported, the generic response code 503 MUST be returned.
If the information is available, it is returned as a multi-line response following the 224 response code and contains one line per article, sorted in numerical order of article number (note that unless the argument is a range including a dash, there will only be one line but it will still be in multi-line format). Each line consists of a number of fields separated by a TAB. A field may be empty (in which case there will be two adjacent TABs), and a sequence of trailing TABs may be omitted.
The first 8 fields MUST be the following, in order:
"0" or article number (see below)
Subject header content
From header content
Date header content
Message-ID header content
References header content
:bytes metadata item
:lines metadata item
If the article is specified by message-id (the first form of the command), the article number MUST be replaced with zero, except that if there is a current selected group and the article is present in that group, the server MAY use that article number (see the ARTICLE command in [NNTP]Feather, C., Network News Transport Protocol, . for more details). In the other two forms of the command, the article number MUST be returned.
Any subsequent fields are the contents of the other headers and metadata held in the database.
For the five mandatory headers, the content of each field MUST be based on the content of the header (that is, with the header name and following colon and space removed). If the article does not contain that header, or if the content is empty, the field MUST be empty. For the two mandatory metadata items, the content of the field MUST be just the value, with no other text.
For all subsequent fields that contain headers, the content MUST be the entire header line other than the trailing CRLF. For all subsequent fields that contain metadata, the field consists of the metadata name, a single space, and then the value.
For all fields, the value is processed by first removing all CRLF pairs (that is, undoing any folding and removing the terminating CRLF) and then replacing each TAB with a single space. If there is no such header in the article, or no such metadata item, or no header or item stored in the database for that article, the corresponding field MUST be empty.
Note that, after unfolding, the characters NUL, LF, and CR cannot occur in the header of an article offered by a conformant server. Nevertheless, servers SHOULD check for these characters and replace each one by a single space (so that, for example, CR LF LF TAB will become two spaces, since the CR and first LF will be removed by the unfolding process). This will encourage robustness in the face of non-conforming data; it is also possible that future versions of this specification could permit these characters to appear in articles.
The server SHOULD NOT produce output for articles that no longer exist.
If the argument is a message-id and no such article exists, a 430 response MUST be returned. If the argument is a range or is omitted and the current selected newsgroup is invalid, a 412 response MUST be returned. If the argument is a range and no articles in that number range exist in the current selected newsgroup, a 423 response MUST be returned. If the argument is omitted and the current article number is invalid, a 420 response MUST be returned.
In the first three examples, TAB has been replaced by vertical bar and some lines have been folded for readability.
Example of a successful retrieval of overview information for an article (using no article number):
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER
[S] 224 Overview information follows
[S] 300234|I am just a test article|"Demo User"
<nobody@example.com>|6 Oct 1998 04:38:40 -0500|
<45223423@example.com>|<45454@example.net>|1234|
17|Xref: news.example.com misc.test:3000363
[S] .
Example of a successful retrieval of overview information for an article by message-id:
[C] LIST EXTENSIONS
[S] 202 extensions supported:
[S] OVER MSGID
[S] .
[C] OVER <45223423@example.com>
[S] 224 Overview information follows
[S] 0|I am just a test article|"Demo User"
<nobody@example.com>|6 Oct 1998 04:38:40 -0500|
<45223423@example.com>|<45454@example.net>|1234|
17|Xref: news.example.com misc.test:3000363
[S] .
Note that the article number has been replaced by "0".
Example of the same commands on a system that does not implement retrieval by message-id:
[C] LIST EXTENSIONS
[S] 202 extensions supported:
[S] OVER
[S] .
[C] OVER <45223423@example.com>
[S] 503 Overview by message-id unsupported
Example of a successful retrieval of overview information for a range of articles:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER 3000234-3000240
[S] 224 Overview information follows
[S] 300234|I am just a test article|"Demo User"
<nobody@example.com>|6 Oct 1998 04:38:40 -0500|
<45223423@example.com>|<45454@example.net>|1234|
17|Xref: news.example.com misc.test:3000363
[S] 3000235|Another test article|nobody@nowhere.to
(Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>||
4818|37||Distribution: fi
[S] 3000238|Re: I am just a test article|somebody@elsewhere.to|
7 Oct 1998 11:38:40 +1200|<kfwer3v@elsewhere.to>|
<45223423@to.to>|9234|51
[S] .
Note the missing "References" and Xref headers in the second line, the missing trailing field(s) in the first and last lines, and that there are only results for those articles that still exist.
Example of an unsuccessful retrieval of overview information on an article by number:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] OVER 300256
[S] 420 No such article in this group
Example of an unsuccessful retrieval of overview information by number because no newsgroup was selected first:
[Assumes current selected newsgroup is invalid.]
[C] OVER
[S] 412 No newsgroup selected
Example of an attempt to retrieve information when the current selected newsgroup is empty:
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] OVER
[S] 420 No current article selected
- This command is optional.
- Syntax
- LIST OVERVIEW.FMT
- Responses
- 215 Information follows (multiline)
The LIST OVERVIEW.FMT command returns a description of the fields in the database for which it is consistent (as described above).
If the information is available, it is returned as a multi-line response following the 215 response code. The information contains one line per field in the order they are returned by the OVER command; the first 7 lines MUST (except for the case of letters) be exactly:
Subject:
From:
Date:
Message-ID:
References:
:bytes
:lines
except that, for compatibility with existing implementations, the last two lines MAY instead be:
Bytes:
Lines:
even though they refer to metadata, not headers.
All subsequent lines MUST consist of either a header name followed by ":full", or the name of a piece of metadata.
There are no leading or trailing spaces in the output.
Note that the 7 fixed lines describe the 2nd to 8th fields of the OVER output. The "full" suffix (which may use either uppercase, lowercase, or a mix) is a reminder that the corresponding fields include the header name.
This command MAY generate different results if used more than once in a session.
Example of LIST OVERVIEW.FMT output corresponding to the example OVER output above, using the preferred format:
[C] LIST OVERVIEW.FMT
[S] 215 Order of fields in overview database.
[S] Subject:
[S] From:
[S] Date:
[S] Message-ID:
[S] References:
[S] :bytes
[S] :lines
[S] Xref:full
[S] Distribution:full
[S] .
Example of LIST OVERVIEW.FMT output corresponding to the example OVER output above, using the alternative format:
[C] LIST OVERVIEW.FMT
[S] 215 Order of fields in overview database.
[S] Subject:
[S] From:
[S] Date:
[S] Message-ID:
[S] References:
[S] Bytes:
[S] Lines:
[S] Xref:FULL
[S] Distribution:FULL
[S] .
Example of LIST OVERVIEW.FMT returning an error where the command is recognized but the software does not maintain this information:
[C] LIST OVERVIEW.FMT
[S] 503 overview.fmt not available
| TOC |
The HDR extension provides access to specific headers and metadata items (collectively "fields") of articles or groups of articles. In the case of headers, an implementation MAY restrict the use of this extension to a specific list of headers or MAY allow it to be used with any header; it may behave differently when the HDR command is used with a message-id argument and when it is used with a range or no argument.
The HDR command may take information from a database rather than directly from the articles. If so, the same issues of consistency and inconsistency apply as with the OVER extensionThe Overview Database and the LIST HEADERS command SHOULD take the same approach as the LIST OVERVIEW.FMT command in resolving them.
- Syntax
- HDR header message-id
HDR header range
HDR header- Responses
- First form (message-id specified)
- 225 Headers follow (multiline)
430 No article with that message-id- Second form (range specified)
- 225 Headers follow (multiline)
412 No newsgroup selected
423 No articles in that range- Third form (current article number used)
- 225 Headers follow (multiline)
412 No newsgroup selected
420 Current article number is invalid- Parameters
- header = name of header, without the colon
range = number(s) of articles
message-id = message-id of article
The HDR command retrieves specific headers from an article specified by message-id, or from a specified article or range of articles in the current selected newsgroup. It can also return certain metadata about the article or articles.
The required header argument is the name of a header (e.g. "subject") in an article, or the name of a metadata item, and is case-insensitive. Names of metadata items always begin with a colon. Except where stated otherwise, metadata items are treated as if they were header contents, and references to headers in this description apply equally to metadata items.
The message-id argument indicates a specific article. The range argument may be any of the following:
If neither is specified, the current article number is used.
If the information is available, it is returned as a multi-line response following the 225 response code and contains one line for each article in the range that exists (note that unless the argument is a range including a dash, there will be at most one line but it will still be in multi-line format). The line consists of the article number, a space, and then the contents of the header or metadata item. In the case of a header, the header name, colon, and the first space after the colon are all omitted.
If the article is specified by message-id (the first form of the command), the article number MUST be replaced with zero, except that if there is a current selected group and the article is present in that group, the server MAY use that article number (see the ARTICLE command in [NNTP]Feather, C., Network News Transport Protocol, . for more details). In the other two forms of the command, the article number MUST be returned.
Header contents are modified as follows: all CRLF pairs are removed, and then each TAB is replaced with a single space (note that this is the same transformation as is performed by the OVER extensionDescription, and the same comment concerning NUL, CR, and LF applies).
The header content is in all cases taken from the article. This means that, for example, a request for the header "Lines" returns the contents of the "Lines" header of the specified articles, if any, not the line count metadata or any other server-generated value. If the header occurs in a given article multiple times, only the content of the first occurrence is returned by HDR.
If the requested header is not present in the article or if it is present but empty, a line for that article is included in the output but the header content portion of the line is empty (the space after the article number MAY be retained or omitted). If any article number in the provided range does not exist in the group, no line for that article number is included in the output.
If the second argument is a message-id and no such article exists, a 430 response MUST be returned. If the second argument is a range or is omitted and the current selected newsgroup is invalid, a 412 response MUST be returned. If the second argument is a range and no articles in that number range exist in the current selected newsgroup, a 423 response MUST be returned. If the second argument is omitted and the current article number is invalid, a 420 response MUST be returned.
A server MAY only allow HDR commands for a limited set of headers and metadata items; it may behave differently in this respect for the first (message-id) form than for the other forms. If so, it MUST respond with the generic 503 response to attempts to request other headers, rather than returning erroneous results such as a successful empty response.
If HDR uses a separate database and it is inconsistent for the requested header or metadata item, the server MAY return what results it can or it MAY respond with the generic 503 response; in the latter case, the field MUST NOT appear in the output from LIST HEADERS.
Example of a successful retrieval of subject lines from a range of articles (3000235 has no Subject header, and 3000236 is missing):
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR Subject 3000234-300238
[S] 225 Headers follow
[S] 3000234 I am just a test article
[S] 3000235
[S] 3000237 Re: I am just a test article
[S] 3000238 Ditto
[S] .
Example of a successful retrieval of line counts from a range of articles:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR :lines 3000234-300238
[S] 225 Headers follow
[S] 3000234 42
[S] 3000235 5
[S] 3000237 11
[S] 3000238 2378
[S] .
Example of a successful retrieval of the subject line from an article by message-id:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR subject <i.am.a.test.article@example.com>
[S] 225 Header information follows
[S] 0 I am just a test article
[S] .
Example of a successful retrieval of the subject line from the current article:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR subject
[S] 225 Header information follows
[S] 3000234 I am just a test article
[S] .
Example of an unsuccessful retrieval of a header from an article by message-id:
[C] HDR subject <i.am.not.there@example.com>
[S] 430 No Such Article Found
Example of an unsuccessful retrieval of headers from articles by number because no newsgroup was selected first:
[Assumes current selected newsgroup is invalid.]
[C] HDR subject 300256-
[S] 412 No newsgroup selected
Example of an unsuccessful retrieval of headers because the current selected newsgroup is empty:
[C] GROUP example.empty.newsgroup
[S] 211 0 0 0 example.empty.newsgroup
[C] HDR subject 1-
[S] 423 No articles in that range
Example of an unsuccessful retrieval of headers because the server does not allow HDR commands for that header:
[C] GROUP misc.test
[S] 211 1234 3000234 3002322 misc.test
[C] HDR Content-Type 3000234-300238
[S] 503 HDR not permitted on Content-Type
- Syntax
- LIST HEADERS [MSGID|RANGE]
- Responses
- 215 Header and metadata list follows (multiline)
- Parameters
- MSGID = requests list for access by message-id
RANGE = requests list for access by range
The LIST HEADERS command returns a list of headers and metadata items that may be retrieved using the HDR command.
The information is returned as a multi-line response following the 215 response code and contains one line for each header or metadata item name (excluding the colon in the former case). If the implementation allows any header to be retrieved, it MUST NOT include any header names in the list but MUST include the special entry ":" (a single colon on its own); it MUST still list any metadata items that are available. The order of items in the list is not significant; the server need not even consistently return the same order. The list MAY be empty (though in this circumstance there is little point in providing the extension).
An implementation that also supports the OVER extension SHOULD at least permit all the headers and metadata items listed in the output from the LIST OVERVIEW.FMT command.
If the server treats the first form of the HDR command (message-id specified) differently to the other two forms (range specified or current article number used) in respect of which headers or metadata items are available, then:
If the server does not treat the various forms differently, then it MUST always produce the same results and ignore any argument.
Example of an implementation providing access to only a few headers:
[C] LIST HEADERS
[S] 215 headers supported:
[S] Subject
[S] Message-ID
[S] Xref
[S] .
Example of an implementation providing access to the same fields as the first example in Section 5.4.3Examples:
[C] LIST EXTENSIONS
[S] 202 extensions supported:
[S] OVER
[S] HDR
[S] .
[C] LIST HEADERS
[S] 215 headers and metadata items supported:
[S] Date
[S] Distribution
[S] From
[S] Message-ID
[S] References
[S] Subject
[S] Xref
[S] :bytes
[S] :lines
[S] .
Example of an implementation providing access to all headers:
[C] LIST HEADERS
[S] 215 metadata items supported:
[S] :
[S] :lines
[S] :bytes
[S] :x-article-number
[S] .
Example of an implementation distinguishing the first form of the HDR command from the other two forms:
[C] LIST HEADERS RANGE
[S] 215 metadata items supported:
[S] :
[S] :lines
[S] :bytes
[S] .
[C] LIST HEADERS MSGID
[S] 215 headers and metadata items supported:
[S] Date
[S] Distribution
[S] From
[S] Message-ID
[S] References
[S] Subject
[S] :lines
[S] :bytes
[S] :x-article-number
[S] .
[C] LIST HEADERS
[S] 215 headers and metadata items supported:
[S] Date
[S] Distribution
[S] From
[S] Message-ID
[S] References
[S] Subject
[S] :lines
[S] :bytes
[S] .
Note how :x-article-number does not appear in the last set of output.
| TOC |
This section describes the syntax of these extensions. It extends the syntax in [NNTP]Feather, C., Network News Transport Protocol, ., and non-terminals not defined in this document are defined there. This syntax extends and refines the descriptions elsewhere in this specification, and should be given precedence when resolving apparent conflicts. Note that ABNFCrocker, D. and P. Overell, Augmented BNF for Syntax Specifications: ABNF, November 1997.[RFC2234] strings are case-insensitive.
This syntax extends the non-terminal "command", which represents an NNTP command.
command /= hdr-command
list-headers-command /
list-overview-fmt-command /
listgroup-command /
over-command
hdr-command = "HDR" WS header-meta-name [range-ref]
list-headers-command = "LIST" WS "HEADERS" WS ["MSGID" / "RANGE"]
list-overview-fmt-command = "LIST" WS "OVERVIEW.FMT"
listgroup-command = "LISTGROUP" [WS newsgroup-name]
over-command = "OVER" [WS range-ref]
header-meta-name = header-name / metadata-name
metadata-name = ":" 1*A-NOTCOLON
range = article-number ["-" [article-number]]
range-ref = WS (range / message-id)
This syntax extends the non-terminal "extension-descriptor", which represents the description of one extension in the response from the LIST EXTENSIONS command.
extension-descriptor /= hdr-extension
listgroup-extension
over-extension
hdr-extension = %x48.44.52 ; "HDR"
listgroup-extension = %x4C.49.53.54.47.52.4F.55.50 ; "LISTGROUP"
over-extension = %x4F.56.45.52 [SPA "MSGID"] ; "OVER"
This syntax extends the non-terminal "multiline-response-content", which represents the contents of a multi-line response after any "byte-stuffing" has been undone.
multiline-response-content /= hdr-response /
list-headers-response /
list-overview-fmt-response /
listgroup-response /
over-response
hdr-response = *(article-number SP hdr-content CRLF)
list-headers-response = *(header-meta-name CRLF) /
*((metadata-name / ":") CRLF)
list-overview-fmt-response = list-overview-fmt-text
listgroup-response = *(article-number CRLF)
over-response = *(article-number over-content CRLF)
list-overview-fmt-text =
"Subject:" CRLF
"From:" CRLF
"Date:" CRLF
"Message-ID:" CRLF
"References:" CRLF
( ":bytes" CRLF ":lines" / "Bytes:" CRLF "Lines:") CRLF
*((header-name ":full" / metadata-name) CRLF)
hdr-content = *S-NONTAB
hdr-n-content = [(header-name ":" / metadata-name) SP hdr-content]
over-content = 1*6(TAB hdr-content) /
7(TAB hdr-content) *(TAB hdr-n-content)
These definitions are copied from [NNTP]Feather, C., Network News Transport Protocol, .. Any difference between the documents is an error in this one.
article-number = 1*16DIGIT
header-name = 1*A-NOTCOLON
message-id = "<" 1*248A-NOTGT ">"
newsgroup-name = 1*wildmat-exact
wildmat-exact = %x21-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E /
UTF8-non-ascii ; exclude * , ? [ \ ]
; Assorted special character sets
; A- means based on US-ASCII, excluding controls and SP
; P- means based on UTF-8, excluding controls and SP
; U- means based on UTF-8, excluding NUL CR and LF
; B- means based on bytes, excluding NUL CR and LF
A-CHAR = %x21-7E
A-NOTCOLON = %x21-39 / %x3B-7E ; exclude ":"
A-NOTGT = %x21-3D / %x3F-7E ; exclude ">"
P-CHAR = A-CHAR / UTF8-non-ascii
U-CHAR = CTRL / TAB / SP / A-CHAR / UTF8-non-ascii
U-NONTAB = CTRL / SP / A-CHAR / UTF8-non-ascii
U-TEXT = P-CHAR *U-CHAR
B-CHAR = CTRL / TAB / SP / %x21-FF
CR = %x0D
CRLF = CR LF
CTRL = %x01-08 / %x0B-0C / %x0E-1F
DIGIT = %x30-39
LF = %x0A
SP = %x20
SPA = 1*SP
TAB = %x09
UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4
UTF8-2 = %xC2-DF UTF8-tail
UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail /
%xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail
UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail /
%xF4 %x80-8F 2UTF8-tail
UTF8-tail = %x80-BF
WS = 1*(SP / TAB)
The following non-terminals require special consideration. They represent situations where material SHOULD be restricted to UTF-8, but implementations MUST be able to cope with other character encodings. Therefore there are two sets of definitions for them.
Implementations MUST accept any content that meets this syntax:
S-CHAR = %x21-FF S-NONTAB = CTRL / SP / S-CHAR S-TEXT = (CTRL / S-CHAR) *B-CHAR
Implementations SHOULD only generate content that meets this syntax:
S-CHAR = P-CHAR S-NONTAB = U-NONTAB S-TEXT = U-TEXT
| TOC |
[NNTP]Feather, C., Network News Transport Protocol, . requires IANA to keep a registry of extension-labels. The initial contents of this registry are the following entries, describing the extensions specified by this document:
| Extension | Label | Added behaviour |
|---|---|---|
| Specific article numbers | LISTGROUP | Defined in Section 3The LISTGROUP extension |
| Overview support | OVER | Defined in Section 5The OVER extension |
| Batched header retrieval | HDR | Defined in Section 6The HDR extension |
| TOC |
[NNTP]Feather, C., Network News Transport Protocol, . discusses many of the the security limitations in NNTP. That discussion applies equally to these extensions.
| TOC |
Much of this document started as a part of the main NNTP specificationFeather, C., Network News Transport Protocol, .[NNTP]. The author gratefully acknowledges all those people who contributed to that document.
The author also gratefully acknowledges all the members of the NNTP Working Group who contributed to the final form of this document.
| TOC |
| TOC |
| [NNTP] | Feather, C., "Network News Transport Protocol", RFC YYYY. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
| [RFC2234] | Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. |
| [RFC2980] | Barber, S., "Common NNTP Extensions", RFC 2980, October 2000. |
| TOC |
| [RFC2629] | Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999 (TXT, HTML, XML). |
| [ROBE1995] | Robertson, R., "FAQ: Overview database / NOV General Information", January 1995 (TXT, TXT). |
| TOC |
| Clive D.W. Feather | |
| Thus plc | |
| 322 Regents Park Road | |
| London N3 2QQ | |
| GB | |
| Phone: | +44 20 8495 6138 |
| Fax: | +44 870 051 9937 |
| EMail: | clive@demon.net |
| URI: | http://www.davros.org/ |
| TOC |
This section contains a list of every response code defined in this document, whether it is multi-line, which commands can generate it, what arguments it has, and what its meaning is.
The text "Also generated by" indicates that the code is also defined in [NNTP]Feather, C., Network News Transport Protocol, .. Generic response codes are not listed in this section.
- Response code 211
- (multi-line) Also generated by: LISTGROUPLISTGROUP
4 arguments: number low high group
Meaning: article numbers follow.- Note that this response is multi-line when generated by LISTGROUP but not when generated by the GROUP command.
- Response code 215
- (multi-line) Also generated by: LIST HEADERSLIST HEADERS, LIST OVERVIEW.FMTLIST OVERVIEW.FMT
Meaning: information follows.- Response code 224
- (multi-line) Generated by: OVEROVER
Meaning: overview information follows.- Response code 225
- (multi-line) Generated by: HDRHDR
Meaning: headers follow.- Response code 411
- Also generated by: LISTGROUPLISTGROUP
Meaning: no such newsgroup.- Response code 412
- Also generated by: HDRHDR, LISTGROUPLISTGROUP, OVEROVER
Meaning: no newsgroup selected.- Response code 420
- Also generated by: HDRHDR, OVEROVER
Meaning: current article number is invalid.- Response code 423
- Also generated by: HDRHDR, OVEROVER
Meaning: no articles in that range.- Response code 430
- Also generated by: HDRHDR, OVEROVER
Meaning: no article with that message-id.
| TOC |
The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
Funding for the RFC Editor function is currently provided by the Internet Society.