INTERNET DRAFT S.Barber
Expires: February 1, 1997 Academ Consulting Services
September 1996
Network News Transport Protocol
<draft-barber-nntp-news-00.txt>
1. Status of this Document
This document is an Internet-Draft. 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 made
obsolete 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.''
To learn the current status of any Internet-Draft, please
check the ``1id-abstracts.txt'' listing contained in the
Internet-Drafts Shadow Directories on ftp.is.co.za
(Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific
Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US
West Coast).
This document is the first product of the NNTP Working
Group, chaired by Erik Fair.
2. Abstract
The Network News Transport Protocol 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.
3. Introduction
This document specifies the Network News Transport
Protocol (NNTP), which is used for the distribution,
inquiry, retrieval, and posting of Usenet articles using
a reliable stream-based mechanism. For news reading
clients, NNTP enables retrieval of news articles that are
stored in a central database, giving subscribers the
ability to select only those articles they wish to read.
INTERNET DRAFT NNTP September 1996
The netnews model provides for indexing, cross-
referencing, and expiration of aged messages. For server-
to-server interaction, NNTP is designed for efficient
transmission of Usenet articles over a reliable full
duplex communication method.
Every attempt is made to insure that the protocol
specification in this document is compatible with the
version specified in RFC 977[1].
Generally, new functionality is available through the use
of new keywords. Part of that new functionality involves
a mechanism to discover what new functionality is
available to clients from a server.
This mechanism can also be used to add more functionality
as needs merit such additions.
In this document, the words that are used to define the
significance of each particular requirement are
capitalized.
These words are:
. "MUST"
This word or the adjective "REQUIRED" means that the
item is an absolute requirement of the specification.
. "SHOULD"
This word or the adjective "RECOMMENDED" means that
there may exist valid reasons in particular
circumstances to ignore this item, but the full
implications should be understood and the case
carefully weighed before choosing a different course.
. "MAY"
This word or the adjective "OPTIONAL" means that this
item is truly optional. One vendor may choose to
include the item because a particular marketplace
requires it or because it enhances the product, for
example; another vendor may omit the same item.
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".
[Page 2]
INTERNET DRAFT NNTP September 1996
For the remainder of this memo, the term "client host"
refers to a host making use of the NNTP service, while
the term "server host" refers to a host which offers the
NNTP service.
4. Basic Operation.
Every NNTP session MUST involve the following steps,
though possibly not in this order:
CONNECTION
GREETING
CAPABILITIES DISCOVERY
AUTHENTICATION
NEWS TRANSFER
CONCLUSION
DISCONNECTION
Initially, the server host MUST start the NNTP service by
listening on TCP port 119. When a client host wishes to
make use of the service, it MUST establish a TCP
connection with the server host. This is the CONNECTION
step. When the connection is established, the NNTP
server host MUST send a greeting. This is the GREETING
step. The client host and server host then MUST exchange
commands and responses (respectively)until the connection
is closed or aborted. This is the DISCONNECTION step. An
NNTP session MUST be started by a CONNECTION step
followed by a GREETING step and MUST be terminated by a
DISCONNECTION step.
If there is a CONCLUSION step, it MUST immediately
precede the DISCONNECTION step. There MUST be only one
CONNECTION, CONCLUSION and DISCONNECTION step for each
NNTP session. All other steps MAY be repeated as needed.
Commands in the NNTP MUST consist of a case-insensitive
keyword, which MAY be followed by one or more arguments.
All commands MUST be terminated by a CRLF pair. Multiple
commands MUST not be permitted on the same line. Keywords
and arguments MUST consist of printable ASCII characters.
Keywords and arguments MUST be each separated by one or
more SPACE or TAB characters. Keywords MUST be at least
three characters and MUST NOT exceed 12 characters.
Command lines MUST not exceed a total of 512 characters
which includes the terminating CRLF pair.
Each response MUST start with a three digit status
indicator which is sufficient to distinguish all
responses. Responses to certain commands MAY be multi-
line. In these cases, which are clearly indicated below,
after sending the first line of the response and a CRLF,
[Page 3]
INTERNET DRAFT NNTP September 1996
any additional lines are sent, each terminated by a CRLF
pair. When all lines of the response have been sent, a
final line MUST be sent, consisting of a termination
octet (ASCII decimal code 046, ".") and a CRLF pair. If
any line of the multi-line response begins with the
termination octet, the line MUST be "byte-stuffed" by
pre-pending the termination octet to that line of the
response. Hence a multi-line response is terminated with
the five octets "CRLF.CRLF". When examining a multi-line
response, the client MUST check to see if the line begins
with the termination octet. If so and if octets other
than CRLF follow, the first octet of the line (the
termination octet) MUST be stripped away. If so and if
CRLF immediately follows the termination character, then
the response from the NNTP server is ended and the line
containing ".CRLF" MUST not considered part of the multi-
line response.
A NNTP server MAY have an inactivity autologout timer.
Such a timer MUST be of at least 10 minutes' duration.
The receipt of any command from the client during that
interval should suffice to reset the autologout timer.
When the timer expires, the server should close the TCP
connection without sending any response to the client.
4.1 Responses Codes
Each response MUST begin with a three digit response
code. 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 ok
3xx - Command ok so far, send the rest of it.
4xx - Command was correct, but couldn't be performed for
some reason.
5xx - Command unimplemented, or incorrect, or a serious
program error occurred.
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
x5x - Authentication and Authorization
x8x - Nonstandard (private implementation) extensions
[Page 4]
INTERNET DRAFT NNTP September 1996
x9x - Debugging output
The exact response codes that MUST be expected from each
command are detailed in the description of the keyword
that is the first part of the command. In addition, below
is listed a general set of response codes that MAY be
received at any time.
Certain status responses contain parameters such as
numbers and names. The number and type of such parameters
is fixed for each response code to simplify
interpretation of the response.
Parameters MUST be separated from the numeric response
code and from each other by a single space. All numeric
parameters MUST be in base 10 (decimal) format, and may
have leading zeros. All string parameters MUST begin
after the separating space, and MUST end before the
following separating space or the CR-LF pair at the end
of the line.(String parameters MUST not, therefore,
contain spaces.) All text, if any, in the response which
is not a parameter of the response must follow and be
separated from the last parameter by a space. Also, note
that the text following a response number may vary in
different implementations of the server. The 3-digit
numeric code should be used to determine what response
was sent.
Response codes not specified in this standard MAY be used
for any installation-specific additional commands also
not specified. These SHOULD be chosen to fit the pattern
of x8x specified above.(Note that debugging is provided
for explicitly in the x9x response codes.)
The use of unspecified response codes for standard
commands is prohibited.
The response pattern x9x is provided for debugging.
Since much debugging output may be classed as
"informative messages", it MUST be the case that
responses 190 through 199 WILL be used for various
debugging outputs. There is no requirement in this
specification for debugging output, but if such is
provided over the connected stream, it MUST use these
response codes. If appropriate to a specific
implementation, other x9x codes MAY be used for
debugging. (An example MAY be to use e.g., 290 to
acknowledge a remote debugging request.)
A server MUST respond to an unrecognized, unimplemented,
or syntactically invalid command by responding with a
negative status indicator (response codes of the form
5XX). A server MUST respond to a command issued when the
session is in an incorrect state by responding with a
[Page 5]
INTERNET DRAFT NNTP September 1996
negative status indicator. This may be from either the
4XX or 5XX group as appropriate.
5. The WILDMAT format
The WILDMAT format[2] was first developed by Rich Salz
based on the format used in the UNIX "find" command to
articulate file names. It was developed to provide a
uniform mechanism for matching patterns in the same
manner that the UNIX shell matches filenames. Patterns
are implicitly anchored at the beginning and end of each
string when testing for a match. There are five pattern
matching operations other than a strict one-to-one match
between the pattern and the source to be checked for a
match. The first is an asterisk (*) to match any sequence
of zero or more characters. The second is a question mark
(?) to match any single character. The third specifies a
specific set of characters. The set is specified as a
list of characters, or as a range of characters where the
beginning and end of the range are separated by a minus
(or dash) character, or as any combination of lists and
ranges. The dash can also be included in the set as a
character it if is the beginning or end of the set. This
set is enclosed in square brackets. The close square
bracket (]) may be used in a set if it is the first
character in the set. The fourth operation is the same as
the logical not of the third operation and is specified
the same way as the third with the addition of a caret
character (^) at the beginning of the test string just
inside the open square bracket. The final operation uses
the backslash character to invalidate the special meaning
of the a open square bracket ([), the asterisk, backslash
or the question mark. Two backslashes in sequence will
result in the evaluation of the backslash as a character
with no special meaning.
5.1.1 Examples
a) [^]-] -- matches any single character other than a
close square bracket or a minus sign/dash.
b) *bdc -- matches any string that ends with the string
"bdc" including the string "bdc" (without quotes).
c) 0-9a-zA-Z] -- matches any single printable alphanumeric
ASCII character.
d) a??d -- matches any four character string which
begins with a and ends with d.
6. Format for Keyword Descriptions
On the following pages are descriptions of each keyword
recognized by the NNTP server and the responses which
[Page 6]
INTERNET DRAFT NNTP September 1996
will be returned by those commands. These keywords are
grouped by the functional step in which they are used.
Each keyword is shown in upper case for clarity, although
case is ignored in the interpretation of commands by the
NNTP server. Any parameters are shown in lower case. A
parameter shown in [square brackets] is optional. For
example, [GMT] indicates that the triglyph GMT may
present or omitted. A parameter that may be repeated is
followed by an ellipsis. Mutually exclusive parameters
are separated by a vertical bar (|) character. For
example, ggg|<message-id> indicates that a group name or
a <message-id> may be specified, but not both. Some
parameters, notably <message-id>, are case specific. See
RFC 1036[3] for these details.
Also, certain commands make use of a pattern for
selection of multiple news groups. The pattern in all
cases is based on the WILDMAT format introduced by Rich
Salz in 1986. Arguments expected to be in wildmat format
will be represented by the string wildmat. This format is
discussed in detail in section 3.3 of this memo.
7. The GREETING Step
7.1 Initial Connection
There is no keyword presented by the client upon initial
connection to the server. The server MUST present an
appropriate response code as a greeting to the client.
This response informs the client about what steps the
client should take to reach the news exchange step.
The server must present a 200 greeting code if the client
is authorized to post articles though the use of the POST
keyword on this server.
The server must present a 201 greeting code if the client
is not authorized to post articles through the use of the
POST keyword, but no other authentication is required.
The server must present a 205 greeting code if the client
is required to present authentication before it is
permitted to use any keywords available in the news
exchange step.
The server must present a 502 greeting code if the client
is not permitted under any circumstances from interacting
with the server. The server should immediately close the
connection with the client after presenting this code.
[Page 7]
INTERNET DRAFT NNTP September 1996
In all other cases, the server must present a 400
greeting code.
7.1.1 MODE READER
MODE READER
MODE READER MAY be used by the client to indicate to the
server that it is a news reading client. This command may
be entered at any time. The server must present a
greeting code (as described in section 5.1) appropriate
to the server's ability to provide service to this client
in this mode.
7.1.1.1 Responses
200 Hello, you can post
201 Hello, you can't post
205 Authentication required
400 Service temporarily unavailable
502 Service unavailable
8. The CAPABILITIES DISCOVERY Step
A client NNTP supporting NNTP service extensions should
query a server early in the session for extensions
session by issuing the LIST EXTENSIONS command. If the
NNTP server supports the NNTP service extensions it MUST
give a successful response (see section 8.1.1), a failure
response (see section 8.1.2), or an error response ( see
section 8.1.3). If the NNTP server does not support any
NNTP service extensions it MUST generate an error
response (see section 8.1.4).
8.1 LIST EXTENSIONS
If successful, the server NNTP MUST respond with code
205. On failure, the server NNTP MUST respond with code
503. On error, the server NNTP MUST respond with one of
codes 400, 405, 500 and 501.
This command MAY be issued at anytime during a session.
It is not required that the client issue this command
before attempting to make use of any extension. The
response generated by this command MAY change during a
session because of other state information (e.g.
authentication or server administration). However, client
NNTP MUST not cache (for use in another session) any
information returned if the LIST EXTENSIONS command
succeeds. That is, a client NNTP MUST issue the LIST
EXTENSIONS command at least once during each session to
[Page 8]
INTERNET DRAFT NNTP September 1996
get the current and correct information concerning
available extensions during that session.
8.1.1 Successful response
If the server NNTP implements and is able to perform the
LIST EXTENSIONS command, it MUST return code 205.
This response MUST be a multi-line reply. Each line of
the response MUST contain a keyword and, optionally, one
or more parameters. The list MUST end with a period on a
line by itself.
Although LIST EXTENSIONS keywords may be specified in
upper, lower, or mixed case, they must always be
recognized and processed in a case-insensitive manner.
8.1.2 Failure response
If for some reason the server NNTP is unable to list the
service extensions it supports, it MUST return code 503.
In the case of a failure response, the client NNTP may
either try the extensions as the need arises or configure
itself for the basic NNTP functionality defined in this
document.
8.1.3 Error responses from extended servers
If the server NNTP recognizes the LIST EXTENSIONS
command, but due to various conditions cannot make any
extensions available to the client at the time the client
issued the LIST EXTENSIONS command, it MUST return code
405. No list (even an empty one) will be returned.
The client NNTP should configure itself for the basic
NNTP functionality defined in this document, or issue
commands that might change the state of the server
(authentication, for example), or issue the QUIT command
(see section 11.1) if a particular extension is required
for the client to properly operate.
If the server NNTP determines that the NNTP service is no
longer available (e.g., due to imminent system shutdown),
it must return code 400.
In the case of a error response, the client NNTP should
issue the QUIT command (see section 11.1).
8.1.4 Responses from servers without extensions
A server NNTP that conforms to this RFC but does not
support the extensions specified here will not recognize
the LIST EXTENSIONS command and MUST consequently return
[Page 9]
INTERNET DRAFT NNTP September 1996
code 500 or code 501. The server NNTP SHALL stay in the
same state after returning this code. The client NNTP may
either try the extensions as the need arises or configure
itself for the basic NNTP functionality defined in this
document.
8.1.5 Responses from improperly implemented servers
A server NNTP that improperly implements the LIST
EXTENSIONS command may return an empty list. Clients
SHALL accommodate this protocol violation and interpret
it as a response code 405.
9. The AUTHENTICATION Step
9.1 AUTHINFO
AUTHINFO is used to inform a server about the identity of
a user of the server. In all cases, clients MUST provide
this information when requested by the server. Servers
are not required to accept authentication information
that is volunteered by the client. Clients MUST
accommodate servers that reject any authentication
information volunteered by the client
9.1.1 AUTHINFO SIMPLE
AUTHINFO SIMPLE
user password
When authorization is required, the server MUST send a
450 response requesting authorization from the client.
The client MUST enter AUTHINFO SIMPLE in order to make
use of the AUTHINFO SIMPLE authentication step. If the
server will accept this form of authentication, the
server MUST respond with a 350 response. The client must
then send the username followed by one or more space
characters followed by the password. If accepted, the
server MUST return a 250 response and the client should
then retry the original command to which the server
responded with the 450 response. The command SHALL then
be processed by the server normally. If the combination
is not valid, the server MUST return a 452 response.
If the server returns 501, this means that the
authenticator invocation was syntactically incorrect, or
that AUTHINFO SIMPLE is not supported.
If the requested authenticator capability is not found or
there is some other unspecified server program error, the
server MUST return the 503 response code.
[Page 10]
INTERNET DRAFT NNTP September 1996
9.1.1.1 Responses
250 Authorization accepted
350 Continue with authorization sequence
450 Authorization required for this command
452 Authorization rejected
501 Command not supported or Command Syntax Error
502 Program error, function not performed
9.1.2 AUTHINFO GENERIC
AUTHINFO GENERIC authenticator arguments...
AUTHINFO GENERIC is used to identify a specific entity to
the server using arbitrary authentication or
identification protocols. The desired protocol is
indicated by the authenticator parameter, and any number
of parameters can be passed to the authenticator.
When authorization is required, the server will send a
350 response requesting authorization from the client.
The client should enter AUTHINFO GENERIC followed by the
authenticator name, and the arguments if any. The
authenticator and arguments must not contain the sequence
"..".
The server will attempt to engage the server end
authenticator, similarly, the client should engage the
client end authenticator. The server end authenticator
will then initiate authentication using the NNTP sockets
(if appropriate for that authentication protocol), using
the protocol specified by the authenticator name. These
authentication protocols are not included in this
document, but are similar in structure to those
referenced in RFC 1731[4] for the IMAP-4 protocol.
If the server returns 501, this means that the
authenticator invocation was syntactically incorrect, or
that AUTHINFO GENERIC is not supported. The client
should retry using the AUTHINFO SIMPLE command.
If the requested authenticator capability is not found or
there is some other unspecified server program error, the
server returns the 503 response code.
The authenticators converse using their protocol until
complete. If the authentication succeeds, the server
authenticator will terminate with a 250, and the client
can continue by reissuing the command that prompted the
350. If the authentication fails, the server will respond
with a 452.
[Page 11]
INTERNET DRAFT NNTP September 1996
The client must provide authentication when requested by
the server. The server may request authentication at any
time. Servers may request authentication more than once
during a single session.
When the server authenticator completes, it provides to
the server (by a mechanism herein undefined) the email
address of the user, and potentially what the user is
allowed to access. Once authenticated, the server shall
generate a Sender: line using the email address provided
by the authenticator if it does not match the user-
supplied From: line. Additionally, the server should log
the event, including the user's authenticated email
address (if available). This will provide a means by
which subsequent statistics generation can associate news
group references with unique entities - not necessarily
by name.
9.1.2.1 Responses
250 Authorization accepted
350 Continue with authorization sequence
450 Authorization required for this command
452 Authorization rejected
501 Command not supported or Command Syntax Error
502 Program error, function not performed
nnn authenticator-specific protocol.
10. The NEWS EXCHANGE Step
During this step, two basic types of transactions occur:
article retrieval from the server and article posting to
the server.
10.1 Article Retrieval
News reading clients have available a wide variety of
mechanisms to retrieve articles via NNTP. The news
articles are stored and indexed using two types of keys.
One key is the message id of an article.
According to RFC 1036, this identifier should be globally
unique. The other key is composed of the news group name
and the article number within that news group. That key
will be unique to a particular server(there will be only
one article with that number within a particular news
group), but is not required to be globally unique.
Additionally, because the same article can be cross-
posted to multiple news groups, there may be multiple
keys that point to the same article on the same server.
[Page 12]
INTERNET DRAFT NNTP September 1996
10.1.1 Article Retrieval by News Group Name and Article
Number
The following commands are used to set the current news
group name and the "current article pointer" which is
used by other commands for article retrieval.
10.1.1.1 GROUP
GROUP ggg
The required parameter ggg is the name of the news group
to be selected (e.g. "news.software.b").A list of valid
news groups may be obtained by using the LIST keyword.
See section 10.4 for more information on the LIST
keyword.
The successful selection response MUST return the article
numbers of the first and last articles in the group, and
an estimate of the number of articles on file in the
group. It is not necessary that the estimate be correct,
although that is helpful; it must only be equal to or
larger than the actual number of articles on file.
When a valid group is selected by means of this command,
the internally maintained "current article pointer" MUST
be set to the first article in the group and the name of
the current news group MUST be set to the selected news
group name. If an invalid group is specified, the
previously selected group and article MUST remain
selected. If an empty news group is selected, the
"current article pointer" is in an indeterminate state
and MUST not be used.
The GROUP keyword MUST be used by a client and a
successful response received before the any other command
is used that depends on having the "current article
pointer" be valid.
Note that the name of the news group is not case-
dependent. It must otherwise match a news group obtained
from the LIST keyword or an error will result.
10.1.1.1.1 Responses
211 n f l s group selected
(n = estimated number of articles in group,
f = first article number in the group,
l = last article number in the group,
s = name of the group.)
411 no such news group
10.1.1.2 LAST
LAST
[Page 13]
INTERNET DRAFT NNTP September 1996
The internally maintained "current article pointer" MUST
be set to the previous article in the current news group.
If already positioned at the first article of the news
group, an error message MUST be returned and the current
article MUST remain selected.
The internally-maintained "current article pointer" MUST
be set by this command.
A response indicating the current article number, and a
message-id string MUST be returned. No text is sent in
response to this command.
10.1.1.2.1 Responses
223 n a article retrieved - request text separately
(n = article number, a = unique article id)
412 no news group selected
420 no current article has been selected
422 no previous article in this group
10.1.1.3 NEXT
NEXT
The internally maintained "current article pointer" MUST
be advanced to the next article in the current news
group. If no more articles remain in the current group,
an error message MUST be returned and the current article
MUST remain selected.
The internally-maintained "current article pointer" MUST
be set by this command.
A response indicating the current article number, and the
message-id string MUST be returned. No text is sent in
response to this command.
10.1.1.3.1 Responses
223 n a article retrieved - request text separately
(n = article number, a = unique article id)
412 no news group selected
420 no current article has been selected
421 no next article in this group
10.2 Retrieval of Articles and Article Sections
There are two forms to the ARTICLE command (and the
related BODY, HEAD, and STAT commands), each using a
[Page 14]
INTERNET DRAFT NNTP September 1996
different method of specifying which article is to be
retrieved. When the ARTICLE keyword is followed by a
message-id in angle brackets ("<" and ">"), the first
form of the command MUST be used; when a numeric
parameter or no parameter is supplied, the second form
MUST be invoked.
The text of the article MUST be returned as a textual
response, as described earlier in this document.
The HEAD and BODY commands are identical to the ARTICLE
command except that they respectively return only the
header lines or text body of the article.
The STAT command is similar to the ARTICLE command except
that no text is returned. When selecting by message
number within a group, the STAT command MUST set the
current article pointer without sending text. The
returned acknowledgment response MUST contain the
message-id, which may be of some value. Using the STAT
command to select by message-id is valid but of
questionable value, since a selection by message-id MUST
NOT alter the "current article pointer".
10.2.1 ARTICLE
ARTICLE [<message-id>|nnn]
This response displays the header, a blank line, then the
body (text) of the specified article. The optional
parameter nnn is the numeric id of an article in the
current news group and MUST be chosen from the range of
articles provided when the news group was selected. If
it is omitted, the current article is assumed. Message-id
is the message id of an article as shown in that
article's header.
Please note that the internally-maintained "current
article pointer" MUST NOT be altered when the message-id
argument is used. This is both to facilitate the
presentation of articles that may be referenced within an
article being read, and because of the semantic
difficulties of determining the proper sequence and
membership of an article which may have been posted to
more than one news group.
The internally-maintained "current article pointer" MUST
be set when a valid article number is specified as the
argument. This includes the case when a article number is
implied by the use of no argument.
A response indicating the current article number, a
message-id string, and that text is to follow MUST be
returned.
[Page 15]
INTERNET DRAFT NNTP September 1996
The message-id string returned is an identification
string contained within angle brackets ("<" and ">"),
which is derived from the header of the article itself.
The Message-ID header line (required by RFC 1036) from
the article must be used to supply this information. If
the message-id header line is missing from the article, a
single digit "0" (zero) should be supplied within the
angle brackets.
Since the message-id field is unique with each article,
it may be used by a news reading program to skip
duplicate displays of articles that have been posted more
than once, or to more than one news group.
10.2.1.1 Responses
220 n <a> article retrieved - head and body follow
(n = article number, <a> = message-id)
221 n <a> article retrieved - head follows
222 n <a> article retrieved - body follows
223 n <a> article retrieved - request text separately
412 no news group has been selected
420 no current article has been selected
423 no such article number in this group
430 no such article found
10.3 Article Posting
Article posting is done in one of two modes: individual
article posting from news reading clients and article
transfer from other news servers.
10.3.1 POST
POST
If posting is allowed, response code 340 MUST be returned
to indicate that the article to be posted should be sent.
Response code 440 MUST be sent if that posting is
prohibited for some installation-dependent reason.
If posting is permitted, the article MUST be presented in
the format specified by RFC 1036, and MUST include all
required header lines. After the article's header and
body have been completely sent by the client to the
server, a further response code MUST be returned to
indicate success or failure of the posting attempt.
The text forming the header and body of the message to be
posted MUST be sent by the client using the conventions
for text received from the news server: A single period
(".") on a line indicates the end of the text, with lines
[Page 16]
INTERNET DRAFT NNTP September 1996
starting with a period in the original text having that
period doubled during transmission.
No attempt shall be made by the server to filter
characters, fold or limit lines, or otherwise process
incoming text. The intent is that the server just pass
the incoming message to be posted to the server
installation's news posting software, which is not part
of this specification.
10.3.1.1 Responses
240 article posted ok
340 send article to be posted. End with <CR-LF>.<CR-LF>
440 posting not allowed
441 posting failed
10.3.2 IHAVE
IHAVE <message-id>
The IHAVE command informs the server that the client has
an article whose id is <message-id>. If the server
desires a copy of that article, it MUST return a response
instructing the client to send the entire article. If the
server does not want the article (if, for example, the
server already has a copy of it), a response indicating
that the article is not wanted MUST be returned.
If transmission of the article is requested, the client
MUST send the entire article, including header and body,
in the manner specified for text transmission from the
server. A response code indicating success or failure of
the transferal of the article MUST be returned by the
server.
This function differs from the POST command in that it is
intended for use in transferring already-posted articles
between hosts. Normally it will not be used when the
client is a personal news reading program. In particular,
this function will invoke the server's news posting
program with the appropriate settings (flags, options,
etc.) to indicate that the forthcoming article is being
forwarded from another host.
The server may, however, elect not to post or forward the
article if after further examination of the article it
deems it inappropriate to do so. The 436 or 437 error
codes MUST be returned as appropriate to the situation.
Reasons for such subsequent rejection of an article may
include such problems as inappropriate news groups or
distributions, disk space limitations, article lengths,
[Page 17]
INTERNET DRAFT NNTP September 1996
garbled headers, and the like. These are typically
restrictions enforced by the server host's news software
and not necessarily the NNTP server itself.
10.3.2.1 Responses
235 article transferred ok
335 send article to be transferred. End with <CR-
LF>.<CR-LF>
435 article not wanted - do not send it
436 transfer failed - try again later
437 article rejected - do not try again
Because some host news posting software may not be able
to immediately render status on the whether an article is
inappropriate for posting or forwarding, an NNTP server
MAY acknowledge the successful transfer of the article
and later silently discard it. Thus an NNTP server may
return the 235 acknowledgment code and later discard the
received article.
10.4 The LIST Keyword
10.4.1 LIST
LIST [ACTIVE [wildmat]]
The response to the LIST keyword with no parameters
returns a list of valid news groups and associated
information. Each news group is sent as a line of text
in the following format:
group last first status
where <group> is the name of the news group, <last> is
the number of the last known article currently in that
news group, <first> is the number of the first article
currently in the news group, and <status> indicates the
current status of the group on this server. Typically,
the <status> will be consist of the ASCII character `y'
where posting is permitted, `n' where posting is not
permitted and `m' where postings will be forwarded to the
news group moderator by the news server. Other status
strings exist and their definition is outside the scope
of this specification.
The <first> and <last> fields will always be numeric.
They may have leading zeros. If the <last> field
evaluates to less than the <first> field, there are no
articles currently on file in the news group.
[Page 18]
INTERNET DRAFT NNTP September 1996
Note that posting may still be prohibited to a client
even though the LIST command indicates that posting is
permitted to a particular news group. See the POST
command for an explanation of client prohibitions. The
posting flag exists for each news group because some news
groups are moderated or are digests, and therefore cannot
be posted to; that is, articles posted to them must be
mailed to a moderator who will post them for the original
poster. This is independent of the posting permission
granted to a client by the NNTP server.
Please note that an empty list (i.e., the text body
returned by this command consists only of the terminating
period) is a possible valid response, and indicates that
there are currently no valid news groups.
If the optional matching parameter is specified, the list
is limited to only the groups that match the pattern.
Specifying a single group is usually very efficient for
the server, and multiple groups may be specified by using
wildmat patterns (described in section 5), not regular
expression
10.4.1.1 Responses
215 list of news groups follows
10.4.2 LIST ACTIVE.TIMES
LIST ACTIVE.TIMES [wildmat]
The active.times file is maintained by some news
transports systems to contain information about the when
and who created a particular news group. The format of
this file generally include three fields. The first field
is the name of the news group. The second is the time
when this group was created on this news server measured
in seconds since January 1, 1970. The third is the email
address of the entity that created the news group. When
executed, the information is displayed following the 215
response. When display is completed, the server will send
a period on a line by itself. If the information is not
available, the server will return the 503 error response.
If the optional matching parameter is specified, the list
is limited to only the groups that match the pattern.
Specifying a single group is usually very efficient for
the server, and multiple groups may be specified by using
wildmat patterns (described in section 5), not regular
expression
[Page 19]
INTERNET DRAFT NNTP September 1996
10.4.2.1 Responses
215 information follows
503 program error, function not performed
10.4.3 LIST DISTRIBUTIONS
LIST DISTRIBUTIONS
The distributions file is maintained by some news
transport systems to contain information about valid
values for the Distribution: line in a news article
header and about what the values mean. Each line contains
two fields, the value and a short explanation on the
meaning of the value. When executed, the information is
displayed following the 215 response. When display is
completed, the server will send a period on a line by
itself. If the information is not available, the server
will return the 503 error response.
10.4.3.1 Responses
215 information follows
503 program error, function not performed
10.4.4 LIST DISTRIB.PATS
LIST DISTRIB.PATS
The distrib.pats file is maintained by some news
transport systems to contain default values for the
Distribution: line in a news article header when posting
to particular news groups. This information could be used
to provide a default value for the Distribution: line in
the header when posting an article. The information
returned contains three fields separated by colons. The
first column is a weight. The second is a group name or
a wildmat pattern that can be used to match a group name.
The third is the value of the Distribution: line that
should be used when the group name matches and the weight
value is the highest. All this processing is done by the
news posting client and not by the server itself. The
server provides this information to the client for it to
use or ignore as it chooses. When executed, the
information is displayed following the 215 response.
When display is completed, the server will send a period
on a line by itself. If the information is not available,
the server will return the 503 error response.
10.4.4.1 Responses
215 information follows
503 program error, function not performed
[Page 20]
INTERNET DRAFT NNTP September 1996
10.4.5 LIST NEWSGROUPS
LIST NEWSGROUPS [wildmat]
The newsgroups file is maintained by some news transport
systems to contain the name of each news group which is
active on the server and a short description about the
purpose of each news group. Each line in the file
contains two fields, the news group name and a short
explanation of the purpose of that news group. When
executed, the information is displayed following the 215
response. When display is completed, the server will send
a period on a line by itself. If the information is not
available, the server will return the 503 response. If
the optional matching parameter is specified, the list is
limited to only the groups that match the pattern (no
matching is done on the group descriptions). Specifying
a single group is usually very efficient for the server,
and multiple groups may be specified by using wildmat
patterns (see section 5), not regular expressions. If
nothing is matched an empty list is returned, not an
error.
10.4.5.1 Responses
215 information follows
503 program error, function not performed
10.4.6 LIST OVERVIEW.FMT
LIST OVERVIEW.FMT
The overview.fmt file is maintained by some news
transport systems to contain the order in which header
information is stored in the overview databases for each
news group. When executed, news article header fields
are displayed one line at a time in the order in which
they are stored in the overview database[5] following the
215 response. When display is completed, the server will
send a period on a line by itself. If the information is
not available, the server will return the 503 response.
Please note that if the header has the word "full"
(without quotes) after the colon, the header's name is
prepended to its field in the output returned by the
server.
10.4.6.1 Responses
215 information follows
503 program error, function not performed
10.4.7 LIST SUBSCRIPTIONS
LIST SUBSCRIPTIONS
[Page 21]
INTERNET DRAFT NNTP September 1996
This command is used to get a default subscription list
for new users of this server. The order of groups is
significant.
When this list is available, it is preceded by the 215
response and followed by a period on a line by itself.
When this list is not available, the server returns a 503
response code.
10.4.7.1 Responses
215 information follows
503 program error, function not performed
10.4.8 LISTGROUP
LISTGROUP [ggg]
The LISTGROUP command is used to get a listing of all the
article numbers in a particular news group.
The optional parameter ggg is the name of the news group
to be selected (e.g. "news.software.b"). A list of valid
news groups may be obtained from the LIST command. If no
group is specified, the current group is used as the
default argument.
The successful selection response will be a list of the
article numbers in the group followed by a period on a
line by itself.
When a valid group is selected by means of this command,
the internally maintained "current article pointer" MUST
be set to the first article in the group. If an invalid
group is specified, the previously selected group and
article remain selected. If an empty news group is
selected, the "current article pointer" is in an
indeterminate state and should not be used.
Note that the name of the news group is not case-
dependent. It must otherwise match a news group obtained
from the LIST command or an error will result.
10.4.8.1 Responses
211 list of article numbers follow
412 Not currently in news group
502 no permission
[Page 22]
INTERNET DRAFT NNTP September 1996
10.4.9 OVER
OVER [range]
The OVER command returns information from the overview
database for the article(s) specified. The information
returned in the response to this command can be used by
clients to follow discussion threads.
The optional range argument may be any of the following:
. an article number
. an article number followed by a dash to indicate all
following
. an article number followed by a dash followed by
another article number
If no argument is specified, then information from the
current article is displayed. Successful responses start
with a 224 response followed by the overview information
for all matched messages. Once the output is complete, a
period is sent on a line by itself. If no argument is
specified, the information for the current article is
returned. A news group must have been selected earlier,
else a 412 error response is returned. If no articles are
in the range specified, a 420 error response is returned
by the server. A 502 response will be returned if the
client only has permission to transfer articles.
Each line of output MUST be formatted with the article
number, followed by each of the headers in the overview
database or the article itself (when the data is not
available in the overview database) for that article
separated by a tab character. The sequence of fields
must be in this order: subject, author, date, message-id,
references, byte count, and line count. Other optional
fields may follow line count. Where no data exists, a
null field must be provided (i.e. the output will have
two tab characters adjacent to each other). Servers
should not output fields for articles that have been
removed since the overview database was created.
10.4.9.1 Responses
224 Overview information follows
412 No news group current selected
420 No article(s) selected
502 no permission
10.4.10 PAT
PAT header range|<message-id> pat [pat...]
[Page 23]
INTERNET DRAFT NNTP September 1996
The PAT command is used to retrieve specific headers from
specific articles, based on pattern matching on the
contents of the header.
The required header parameter is the name of a header
line (e.g. "subject") in a news group article. See RFC-
1036 for a list of valid header lines. The required range
argument may be any of the following:
. an article number
. an article number followed by a dash to indicate all
following
. an article number followed by a dash followed by
another article number.
The required message-id argument indicates a specific
article. The range and message-id arguments are mutually
exclusive. At least one pattern in wildmat must be
specified as well. If there are additional arguments the
are joined together separated by a single space to form
one complete pattern. Successful responses start with a
221 response followed by the headers from all messages in
which the pattern matched the contents of the specified
header line. This includes an empty list. Once the output
is complete, a period is sent on a line by itself. If the
optional argument is a message-id and no such article
exists, the 430 error response shall be returned. A 502
response shall be returned if the client only has
permission to transfer articles.
10.4.10.1 Responses
221 Header follows
430 no such article
502 no permission
11. The CONCLUSION Step
11.1 QUIT
QUIT
The server process MUST acknowledge the QUIT command and
then closes the connection to the client. This is the
preferred method for a client to indicate that it has
finished all its transactions with the NNTP server.
If a client simply disconnects (or the connection times
out, or some other fault occurs), the server SHALL
gracefully cease its attempts to service the client.
[Page 24]
INTERNET DRAFT NNTP September 1996
11.1.1 Responses
205 closing connection - goodbye!
12. Other Keywords
There are other Keywords that may be used at any time
between the beginning of a session and its termination.
Using these keywords do not alter any state information,
but the response generated from the use of these keywords
may provide useful information to clients that use them.
12.1 DATE
DATE
This command exists to help clients find out the current
time from the server's perspective. This command should
not be used as a substitute for NTP[6], but to provide
information that might be useful when using the NEWNEWS
command (see section 12.4).
This command returns a one-line response code of 111
followed by the GMT date and time on the server in the
form YYYYMMDDhhmmss.
12.1.1 Responses
111 YYYYMMDDhhmmss
12.2 The HELP Command
HELP
This command provides a short summary of commands that
are understood by this implementation of the server. The
help text will be presented as a textual response,
terminated by a single period on a line by itself.
This text is not guaranteed to be in any particular
format and shall not be used by clients as a replacement
for the LIST EXTENSIONS command described in section 8.1.
12.2.1 Responses
100 help text follows
12.3 NEWGROUPS
NEWGROUPS date time [GMT] [<wildmat>]
[Page 25]
INTERNET DRAFT NNTP September 1996
A list of newsgroups created since <date and time> MUST
be listed in the same format as the LIST command.
The date is sent as 6 digits in the format YYMMDD, where
YY is the last two digits of the year, MM is the two
digits of the month (with leading zero, if appropriate),
and DD is the day of the month (with leading zero, if
appropriate). The closest century is assumed as part of
the year (i.e., 86 specifies 1986, 30 specifies 2030, 99
is 1999, 00 is 2000).
Time must also be specified. It must be as 6 digits
HHMMSS with HH being hours on the 24-hour clock, MM
minutes 00-59, and SS seconds 00-59. The time is assumed
to be in the server's timezone unless the token "GMT"
appears, in which case both time and date are evaluated
at the 0 meridian.
An optional parameter may be specified at the end of the
command line consisting of a wildmat pattern against
which new newsgroup names can be matched enclosed in
angle brackets. Only those news groups which have names
that match the pattern (and any other criteria specified
in the command) will be returned.
Please note that an empty list (i.e., the text body
returned by this command consists only of the terminating
period) is a possible valid response, and indicates that
there are currently no new newsgroups.
12.3.1 Responses
231 list of new newsgroups follows
12.4 NEWNEWS
NEWNEWS newsgroups date time [GMT] [<distributions>]
A list of message-ids of articles posted or received to
the specified news group since "date" will be listed. The
format of the listing will be one message-id per line, as
though text were being sent. A single line consisting
solely of one period followed by CR-LF will terminate the
list.
Date and time are in the same format as the NEWGROUPS
command. The newsgroups parameter must be in wildmat
format.
The optional parameter "distributions" is a list of
distribution groups, enclosed in angle brackets. If
specified, the distribution portion of an article's
[Page 26]
INTERNET DRAFT NNTP September 1996
header will be examined for a match with the distribution
categories listed, and only those articles which have a
distribution in the list will be listed. If more than
one distribution is to be supplied, they must be
separated by commas within the angle brackets.
The use of the IHAVE, NEWNEWS, and NEWGROUPS commands to
distribute news is discussed in an earlier part of this
document.
Please note that an empty list (i.e., the text body
returned by this command consists only of the terminating
period) is a possible valid response, and indicates that
there is currently no new news.
12.4.1 Responses
230 list of new articles by message-id follows
13. Framework for NNTP Extensions
Although NNTP is widely and robustly deployed, some parts
of the Internet community might wish to extend the NNTP
service. This memo defines a means whereby both an
extended NNTP client may query the server to determine
the service extensions that it supports.
It must be emphasized that any extension to the NNTP
service 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.
Given this environment, the framework for the extensions
described in this memo consists of:
a) a mechanism for clients to determine a server's
available extensions
b) a registry of NNTP service extensions
The LIST EXTENSIONS command was described in section 6.1
of this memo and is the mechanism used for clients to
determine what extensions are available for client use.
The IANA shall maintains a registry of NNTP service
extensions.
[Page 27]
INTERNET DRAFT NNTP September 1996
Associated with each such extension is a corresponding
NNTP keyword value. Each service extension registered
with the IANA MUST be defined in an RFC. Such RFCs must
either be on the standards-track or must define an IESG-
approved experimental protocol. The definition must
include:
1. the textual name of the NNTP service extension;
2. the NNTP keyword value associated with the extension;
3. the syntax and possible values of parameters associated
with the NNTP keyword value;
4.any additional NNTP verbs associated with the extension
(additional verbs will usually be, but are not required
to be, the same as the NNTP keyword value);
5. any new parameters the extension associated with any
other NNTP verbs;
6. how support for the extension affects the behavior of a
server and client NNTP; and,
7. the increment by which the extension is increasing the
maximum length of the any commands over that specified
in this document.
In addition, any NNTP keyword value that starts with an
upper or lower case "X" refers to a local NNTP service
extension, which is used through bilateral, rather than
standardized, agreement. Keywords beginning with "X" may
not be used in a registered service extension.
Any keyword values presented in the NNTP response that do
not begin with "X" must correspond to a standard,
standards-track, or IESG-approved experimental NNTP
service extension registered with IANA. A conforming
server must not offer non "X" prefixed keyword values
that are not described in a registered extension.
Additional verbs are bound by the same rules as NNTP
keywords; specifically, verbs beginning with "X" are
local extensions that may not be registered or
standardized and verbs not beginning with "X" must always
be registered.
13.1 Initial IANA Registry
The IANA's initial registry of NNTP service extensions
consists of these entries:
Service Extension NNTP Keyword(s) Added Behavior
------------------ -------------- --------------
Overview Support OVER defined in this
document
LIST OVERVIEW.FMT
[Page 28]
INTERNET DRAFT NNTP September 1996
Service Extension NNTP Keyword(s) Added Behavior
----------------- --------------- --------------
Specific Article LISTGROUP defined in this
Numbers document
Header Pattern PAT defined in this
Matching document
14. Security Considerations
The use of the AUTHINFO is optional. This command as
documented has a number of security implications. In the
original and simple forms, all passwords are passed in
plain text and could be discovered by various forms of
network or system surveillance. The AUTHINFO GENERIC
command has the potential for the same problems if a
mechanism is used that also passes clear text passwords.
RFC 1731 discusses these issues in greater detail.
15. References
[1] Kantor, B and P. Lapsley, "Network News Transfer
Protocol", RFC-977, U.C. San Diego and U.C. Berkeley,
[2] Salz, Rich, Manual Page for wildmat(3) from the INN
1.4 distribution, UUNET Technologies, Revision 1.10,
April, 1992.
[3] Horton, M.R. and R. Adams, "Standard for interchange
of USENET messages", RFC-1036, AT&T Bell Laboratories
and Center for Seismic Studies, December, 1987.
[4] Meyers, J, "IMAP4 Authentication Mechanisms", RFC-
1731, Carnegie Mellon, December, 1994.
[5]Robertson, Rob, "FAQ: Overview database / NOV General
Information",
ftp://ftp.uu.net/networking/news/nntp/inn/faq-nov.Z,
January, 1995.
[6] Mills, David L., "Network Time Protocol (Version 3),
Specification,Implementation and Analysis", RFC-1305,
University of Delaware, March 1992.
15.1 Notes
DEC is a registered trademark of Digital Equipment
Corporation.
UNIX is a registered trademark of the X/Open Consortium.
VMS is a registered trademark of Digital Equipment
Corporation.
[Page 29]
INTERNET DRAFT NNTP September 1996
15.2 Acknowledgments
The author acknowledges the original authors of NNTP as
documented in RFC 977: Brian Kantor and Phil Lapsey.
The author gratefully acknowledges the work of the NNTP
committee chaired by Eliot Lear. The organization of this
document was influenced by the last available draft from
this working group. A special thanks to Eliot for
generously providing the original machine sources for
that document.
The author gratefully acknowledges the work of the
Marshall Rose & John G. Meyers in RFC 1939 and the work
of the DRUMS working group, specifically RFC 1869, which
is the basis of the NNTP extensions mechanism detailed in
this document.
The author gratefully acknowledges the comments and
additional information provided by the following
individuals in preparing one of the progenitors of this
document:
. Wayne Davison <davison@armory.com>
. Chris Lewis <clewis@bnr.ca>
. Tom Limoncelli <tal@mars.superlink.net>
. Eric Schnoebelen <eric@egsner.cirr.com>
. Rich Salz <rsalz@osf.org>
This work was precipitated by the work of various
newsreader authors and newsserver authors which includes
those listed below:
. Rick Adams -- Original author of the NNTP extensions to
the RN newsreader and last maintainer of Bnews
. Stan Barber -- Original author of the NNTP extensions
to the newsreaders that are part of Bnews.
. Geoff Collyer -- Original author of the OVERVIEW
database proposal and one of the original authors of
CNEWS
. Dan Curry -- Original author of the xvnews newsreader
. Wayne Davision -- Author of the first threading
extensions to the RN newsreader (commonly called TRN).
. Geoff Huston -- Original author of ANU NEWS
. Phil Lapsey -- Original author of the UNIX reference
implementation
. Ian Lea -- Maintainer of the TIN newsreader
. Chris Lewis -- First known implementor of the AUTHINFO
GENERIC extension
. Rich Salz -- Original author of INN
. Henry Spencer -- One of the original authors of CNEWS
. Kim Storm -- Original author of the NN newsreader
[Page 30]
INTERNET DRAFT NNTP September 1996
15.3 Author's Address
Stan Barber
P.O. Box 300481
Houston, Texas, 77230
Email: <sob@academ.com>
This document expires February 1, 1997.
[Page 31]