mirror of https://github.com/tLDP/LDP
890 lines
36 KiB
Plaintext
890 lines
36 KiB
Plaintext
<chapter id="X-087-2-nntp"><title>NNTP and the<?lb>nntpd Daemon</title>
|
|
|
|
<indexterm id="idx-configuringNNTP-1" class="startofrange"><primary>configuring</primary><secondary>NNTP</secondary></indexterm>
|
|
<indexterm><primary>servers</primary><secondary>NNTP</secondary></indexterm>
|
|
<INDEXTERM id="protocols.NNTP" class=startofrange><PRIMARY>protocols</PRIMARY><SECONDARY>NNTP</SECONDARY></INDEXTERM>
|
|
<indexterm id="ch18.nntp.desc" class="startofrange"><primary>NNTP (Network News Transfer Protocol)</primary></indexterm>
|
|
|
|
<para>
|
|
Network News Transfer Protocol (NNTP) provides for a vastly different
|
|
approach to news exchange from C News and other news servers without native
|
|
NNTP support. Rather than rely on a batch technology like UUCP to transfer
|
|
news articles between machines, it allows articles to be exchanged via an
|
|
interactive network connection. NNTP is not a particular software package,
|
|
but an Internet standard described in RFC-977. It is based on a
|
|
stream-oriented connection, usually over TCP, between a client anywhere in
|
|
the network and a server on a host that keeps Netnews on disk storage. The
|
|
stream connection allows the client and server to interactively negotiate
|
|
article transfer with nearly no turnaround delay, thus keeping the number of
|
|
duplicate articles low. Together with the Internet's high-transfer rates,
|
|
this adds up to a news transport that surpasses the original UUCP networks by
|
|
far. While some years ago it was not uncommon for an article to take two
|
|
weeks or more before it arrived in the last corner of Usenet; it is now often
|
|
less than two days. On the Internet itself, it is even within the range of
|
|
minutes.
|
|
</para>
|
|
|
|
<para>
|
|
Various commands allow clients to retrieve, send, and post articles. The
|
|
difference between sending and posting is that the latter may involve articles
|
|
with incomplete header information; it generally means that the user has just
|
|
written the article.<footnote id="X-087-2-FNNN01"><para> When posting an
|
|
article over NNTP, the server always adds at least one header field, <literal>NNTP-Posting-Host:</literal>. The field contains the client's hostname.
|
|
</para>
|
|
</footnote>
|
|
Article retrieval may be used by news transfer clients as well as newsreaders.
|
|
This makes NNTP an excellent tool for providing news access to many clients on
|
|
a local network without going through the contortions that are necessary when
|
|
using NFS.
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm><primary>news (network)</primary><secondary>pushing</secondary></indexterm>
|
|
<indexterm><primary>news (network)</primary><secondary>pulling</secondary></indexterm>
|
|
<indexterm><primary>pushing news</primary></indexterm>
|
|
<indexterm><primary>pulling news</primary></indexterm>
|
|
<INDEXTERM><PRIMARY>ihave command (NNTP)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>ihave command</SECONDARY></INDEXTERM>
|
|
NNTP also provides for an active and a passive way to transfer news,
|
|
colloquially called “pushing” and “pulling.” Pushing
|
|
is basically the same as the ihave/sendme protocol used by C News (described in
|
|
<xref linkend="X-087-2-cnews">). The client offers an article to the server
|
|
through the <command>IHAVE msgid</command>
|
|
command, and the server returns a response code that indicates whether
|
|
it already has the article or if it wants it. If the server wants the
|
|
article, the client sends the article, terminated by a single dot on a
|
|
separate line.
|
|
</para>
|
|
|
|
<para>
|
|
Pushing news has the single disadvantage that it places a heavy load on
|
|
the server system, since the system has to search its history database for
|
|
every single article.
|
|
</para>
|
|
|
|
<para>
|
|
<INDEXTERM><PRIMARY>newnews command (NNTP)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>newnews command</SECONDARY></INDEXTERM>
|
|
The opposite technique is pulling news, in which the client requests a
|
|
list of all (available) articles from a group that have arrived after a
|
|
specified date. This query is performed by the
|
|
<command>NEWNEWS</command> command. From the returned
|
|
list of message IDs, the client selects those articles it does not yet have,
|
|
using the <command>ARTICLE</command> command for
|
|
each of them in turn.
|
|
</para>
|
|
|
|
<para>
|
|
Pulling news needs tight control by the server over which groups and
|
|
distributions it allows a client to request. For example, it has to make
|
|
sure that no confidential material from newsgroups local to the site is sent
|
|
to unauthorized clients.
|
|
</para>
|
|
|
|
<para>
|
|
There are also a number of convenience commands for newsreaders that
|
|
permit them to retrieve the article header and body separately, or even
|
|
single header lines from a range of articles. This lets you keep all
|
|
news on a central host, with all users on the (presumably local) network
|
|
using NNTP-based client programs for reading and posting. This is an
|
|
alternative to exporting the news directories via NFS, as described
|
|
in <xref linkend="X-087-2-cnews">.
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm><primary>news (network)</primary><secondary>faking</secondary></indexterm>
|
|
<indexterm><primary>news faking</primary></indexterm>
|
|
An overall problem of NNTP is that it allows a knowledgeable person to insert
|
|
articles into the news stream with false sender specification. This is
|
|
called <emphasis>news faking</emphasis> or
|
|
<emphasis>spoofing</emphasis>.<footnote id="X-087-2-FNNN02"><para>
|
|
The same problem exists with the Simple Mail Transfer Protocol (SMTP), although
|
|
most mail transport agents now provide mechanisms to prevent spoofing.
|
|
</para>
|
|
</footnote>
|
|
An extension to NNTP allows you to require user authentication for
|
|
certain commands, providing some measure of protection against people abusing
|
|
your news server in this way.
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm><primary>nntpd</primary><secondary>components</secondary></indexterm>
|
|
<indexterm><primary>Lapsley, Phil</primary></indexterm>
|
|
<indexterm><primary>Barber, Stan</primary></indexterm>
|
|
There are a number of NNTP packages. One of the more widely known is
|
|
the NNTP daemon, also known as the
|
|
<emphasis>reference implementation</emphasis>.
|
|
Originally, it was written by Stan Barber and Phil Lapsley to illustrate the
|
|
details of RFC-977. As with much of the good software available today, you may
|
|
find it prepackaged for your Linux distribution, or you can obtain the source
|
|
and compile it yourself. If you choose to compile it yourself, you will need to
|
|
be quite familiar with your distribution to ensure you configure all of the
|
|
file paths correctly.
|
|
</para>
|
|
|
|
<para>
|
|
The <command>nntpd</command> package has a server, two clients for
|
|
pulling and pushing news, and an <command>inews</command>
|
|
replacement. They live in a B News environment, but with a little
|
|
tweaking, they will be happy with C News, too. However, if you plan to
|
|
use NNTP for more than offering newsreaders access to your news server,
|
|
the reference implementation is not really an option. We will therefore
|
|
discuss only the NNTP daemon contained in the <command>nntpd</command> package
|
|
and leave out the client programs.
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm><primary>Salz, Rich</primary></indexterm>
|
|
<indexterm><primary>INN (Internet News)</primary><secondary>NNTP and</secondary></indexterm>
|
|
If you wish to run a large news site, you should look at
|
|
the <emphasis>InterNet News</emphasis> package, or INN, that was written by
|
|
Rich Salz. It provides both NNTP and UUCP-based news transport. News transport is definitely better than
|
|
<command>nntpd</command>. We discuss INN in detail in
|
|
<xref linkend="X-087-2-inn">.
|
|
</para>
|
|
|
|
<sect1 id="X-087-2-nntp.protocol"><title>The NNTP Protocol</title>
|
|
<para>
|
|
We've mentioned two NNTP commands that are key to how news articles are pushed
|
|
or pulled between servers. Now we'll look at these in the context of an actual
|
|
NNTP session to show you how simple the protocol is. For the purposes of our
|
|
illustration, we'll use a simple <command>telnet</command> client to connect to
|
|
an INN-based news server at the Virtual Brewery called
|
|
<emphasis role="bold">news.vbrew.com</emphasis>. The server is running
|
|
a minimal configuration to keep the examples short. We'll look at how to
|
|
complete the configuration of this server in <xref linkend="X-087-2-inn">.
|
|
In our testing we'll be very careful to generate articles in the
|
|
<emphasis>junk</emphasis> newsgroup only, to avoid
|
|
disturbing anyone else.
|
|
</para>
|
|
|
|
<sect2><title>Connecting to the News Server</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>connecting to a news server</SECONDARY></INDEXTERM>
|
|
Connecting to the news server is a simple as opening a TCP connection to
|
|
its NNTP port. When you are connected, you will be greeted with a welcome
|
|
banner. One of the first commands you might try is <systemitem role="keyword">help</systemitem>. The response you get generally depends upon whether
|
|
the server believes you are a remote NNTP server or a newsreader, as there are
|
|
different command sets required. You can change your operating mode using the
|
|
<command>mode</command> command; we'll look at that in a
|
|
moment:
|
|
</para>
|
|
|
|
<screen>
|
|
$ <userinput>telnet news.vbrew.com nntp</userinput>
|
|
Trying 172.16.1.1...
|
|
Connected to localhost.
|
|
Escape character is '^]'.
|
|
200 news.vbrew.com InterNetNews server INN 1.7.2 08-Dec-1997 ready
|
|
<userinput>help</userinput>
|
|
100 Legal commands
|
|
authinfo
|
|
help
|
|
ihave
|
|
check
|
|
takethis
|
|
list
|
|
mode
|
|
xmode
|
|
quit
|
|
head
|
|
stat
|
|
xbatch
|
|
xpath
|
|
xreplic
|
|
For more information, contact "usenet" at this machine.
|
|
.
|
|
</screen>
|
|
|
|
<para>
|
|
The responses to NNTP commands always end with a period (.) on a
|
|
line by itself. The numbers you see in the output listing are
|
|
<emphasis>response codes</emphasis> and are used by the server to indicate success or
|
|
failure of a command. The response codes are described in RFC-977; we'll talk
|
|
about the most important ones as we proceed.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2><title>Pushing a News Article onto a Server</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>ihave command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>ihave command (NNTP)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>news (network)</PRIMARY><SECONDARY>articles</SECONDARY><TERTIARY>pushing news</TERTIARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>pushing news</PRIMARY></INDEXTERM>
|
|
We mentioned the <command>IHAVE</command> command
|
|
when we talked about pushing news articles onto a news server. Let's
|
|
now have a look at how the <command>IHAVE</command> command actually works:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>ihave <123456@gw.vk2ktj.ampr.org></userinput>
|
|
335
|
|
<userinput>From: terry@gw.vk2ktj.ampr.org
|
|
Subject: test message sent with ihave
|
|
Newsgroups: junk
|
|
Distribution: world
|
|
Path: gw.vk2ktj.ampr.org
|
|
Date: 26 April 1999
|
|
Message-ID: <123456@gw.vk2ktj.ampr.org>
|
|
Body:
|
|
|
|
This is a test message sent using the NNTP IHAVE command.
|
|
|
|
.</userinput>
|
|
235
|
|
</screen>
|
|
|
|
<para>
|
|
All NNTP commands are case insensitive, so you may enter them in
|
|
either upper- or lowercase. The <command>IHAVE</command> command takes one
|
|
mandatory argument, it being the Message ID of the article that is being pushed. Every news article is assigned a unique message ID when
|
|
it is created. The <command>IHAVE</command> command provides a way of the NNTP server to say which articles it has
|
|
when it wants to push articles to another server. The sending server
|
|
will issue an <command>IHAVE</command> command
|
|
for each article it wishes to push. If the command response code
|
|
generated by the receiving NNTP server is in the “3xx”
|
|
range, the sending NNTP server will transmit the complete article,
|
|
including it's full header, terminating the article with a period on a
|
|
line by itself. If the response code was in the “4xx”
|
|
range, the receiving server has chosen not to accept this article,
|
|
possibly because it already has it, or because of some problem, such
|
|
as running out of disk space.
|
|
</para>
|
|
|
|
<para>
|
|
When the article has been transmitted, the receiving serve issues another
|
|
response code indicating whether the article transmission was successful.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2><title>Changing to NNRP Reader Mode</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>changing to NNRP reader mode</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>newsreaders</PRIMARY><SECONDARY>changing to NNRP reader mode</SECONDARY></INDEXTERM>
|
|
Newsreaders use their own set of commands when talking to a
|
|
news server. To activate these commands, the news server has to be
|
|
operating in <emphasis>reader</emphasis> mode. Most news servers default
|
|
to reader mode, unless the IP address of the connecting host is listed
|
|
as a news-forwarding peer. In any case, NNTP provides a command to
|
|
explicitly switch into reader mode:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>mode reader</userinput>
|
|
200 news.vbrew.com InterNetNews NNRP server INN 1.7.2 08-Dec-1997 ready/
|
|
(posting ok).
|
|
<userinput>help</userinput>
|
|
100 Legal commands
|
|
authinfo user Name|pass Password|generic <prog> <args>
|
|
article [MessageID|Number]
|
|
body [MessageID|Number]
|
|
date
|
|
group newsgroup
|
|
head [MessageID|Number]
|
|
help
|
|
ihave
|
|
last
|
|
list [active|active.times|newsgroups|distributions|distrib.pats|/
|
|
overview.fmt|subscriptions]
|
|
listgroup newsgroup
|
|
mode reader
|
|
newgroups yymmdd hhmmss ["GMT"] [<distributions>]
|
|
newnews newsgroups yymmddhhmmss ["GMT"] [<distributions>]
|
|
next
|
|
post
|
|
slave
|
|
stat [MessageID|Number]
|
|
xgtitle [group_pattern]
|
|
xhdr header [range|MessageID]
|
|
xover [range]
|
|
xpat header range|MessageID pat [morepat...]
|
|
xpath MessageID
|
|
Report problems to <usenet@vlager.vbrew.com>
|
|
.
|
|
</screen>
|
|
|
|
<para>
|
|
NNTP reader mode has a lot of commands. Many of these are designed to
|
|
make the life of a newsreader easier. We mentioned earlier that there are
|
|
commands that instruct the server to send the head and the body of articles
|
|
separately. There are also commands that list the available groups and
|
|
articles, and others that allow posting, an alternate means of sending news
|
|
articles to the server.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2><title>Listing Available Groups</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>listing groups</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>list command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>list command (NNTP)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>newsgroups</PRIMARY><SECONDARY>listing</SECONDARY></INDEXTERM>
|
|
The <command>list</command> command lists a number
|
|
of different types of information; notably the groups supported by the server:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>list newsgroups</userinput>
|
|
215 Descriptions in form "group description".
|
|
control News server internal group
|
|
junk News server internal group
|
|
local.general General local stuff
|
|
local.test Local test group
|
|
.
|
|
</screen>
|
|
</sect2>
|
|
|
|
<sect2><title>Listing Active Groups</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>list active command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>list active command (NNTP)</PRIMARY></INDEXTERM>
|
|
<option>list active</option> shows each supported group and provides information
|
|
about them. The two numbers in each line of the output are the high-water
|
|
mark and the low-water mark—that is, the highest numbered article and
|
|
lowest numbered article in each group. The newsreader is able to form an
|
|
idea of the number of articles in the group from these. We'll talk a little
|
|
more about these numbers in a moment. The last field in the output displays flags
|
|
that control whether posting is allowed to the group, whether the group is
|
|
moderated, and whether articles posted are actually stored or
|
|
just passed on. These flags are described in detail in <xref linkend="X-087-2-inn">.
|
|
An example looks like this:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>list active</userinput>
|
|
215 Newsgroups in form "group high low flags".
|
|
control 0000000000 0000000001 y
|
|
junk 0000000003 0000000001 y
|
|
alt.test 0000000000 0000000001 y
|
|
.
|
|
</screen>
|
|
</sect2>
|
|
|
|
<sect2><title>Posting an Article</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>post command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>post command (NNTP)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>news (network)</PRIMARY><SECONDARY>articles</SECONDARY><TERTIARY>posting</TERTIARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>articles (news)</PRIMARY><SECONDARY>posting</SECONDARY></INDEXTERM>
|
|
We mentioned there was a difference between pushing an article and posting
|
|
an article. When you are pushing an article, there is an implicit assumption
|
|
that the article already exists, that it has a message identifier that has
|
|
been uniquely assigned to it by the server to which it was originally posted,
|
|
and that it has a complete set of headers. When posting an article, you are
|
|
creating the article for the first time and the only headers you supply are
|
|
those that are meaningful to you, such as the Subject and the Newgroups to
|
|
which you are posting the article. The news server you post the article on
|
|
will add all the other headers for you and create a message ID that it will
|
|
use when pushing the article onto other servers.
|
|
</para>
|
|
|
|
<para>
|
|
All of this means that posting an article is even easier than pushing one.
|
|
An example posting looks like this:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>post</userinput>
|
|
340 Ok
|
|
<userinput>From: terry@richard.geek.org.au
|
|
Subject: test message number 1
|
|
Newsgroups: junk
|
|
Body:
|
|
|
|
This is a test message, please feel free to ignore it.
|
|
|
|
.</userinput>
|
|
240 Article posted
|
|
</screen>
|
|
|
|
<para>
|
|
We've generated two more messages like this one to give our following examples
|
|
some realism.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2><title>Listing New Articles</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>newnews command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>newnews command (NNTP)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>news (network)</PRIMARY><SECONDARY>articles</SECONDARY><TERTIARY>listing</TERTIARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>articles (news)</PRIMARY><SECONDARY>listing</SECONDARY></INDEXTERM>
|
|
When a newsreader first connects to a new server and the user chooses a
|
|
newsgroup to browse, the newsreader will want to retrieve a list of new
|
|
articles, those posted or received since the last login by the user. The
|
|
<option>newnews</option> command is used for this
|
|
purpose. Three mandatory arguments must be supplied: the name of
|
|
the group or groups to query, the start date, and the start time from which
|
|
to list. The date and time are each specified as six-digit numbers, with the
|
|
most significant information first;
|
|
<replaceable>yymmdd</replaceable> and
|
|
<replaceable>hhmmss</replaceable>, respectively:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>newnews junk 990101 000000</userinput>
|
|
230 New news follows
|
|
<7g2o5r$aa$6@news.vbrew.com>
|
|
<7g5bhm$8f$2@news.vbrew.com>
|
|
<7g5bk5$8f$3@news.vbrew.com>
|
|
.
|
|
</screen>
|
|
</sect2>
|
|
|
|
<sect2><title>Selecting a Group on Which to Operate</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>newsgroups</PRIMARY><SECONDARY>selecting</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>group command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>group command (NNTP)</PRIMARY></INDEXTERM>
|
|
When the user selects a newsgroup to browse, the newsreader may tell the
|
|
news server that the group was selected. This simplifies the interaction
|
|
between newsreader and news server; it removes the need to constantly
|
|
send the name of the newsgroup with each command. The
|
|
<option>group</option> command simply takes the name of the selected group as
|
|
an argument. Many following commands use the group selected as the
|
|
default, unless another newsgroup is specified explicitly:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>group junk</userinput>
|
|
211 3 1 3 junk
|
|
</screen>
|
|
|
|
<para>
|
|
The <option>group</option> command returns a message
|
|
indicating the number of active messages, the low-water mark, the high-water
|
|
mark, and the name of the group, respectively. Note that while the number of
|
|
active messages and the high-water mark are the same in our example, this is
|
|
not often the case; in an active news server, some articles may have expired
|
|
or been deleted, lowering the number of active messages but leaving the
|
|
high-water mark untouched.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2><title>Listing Articles in a Group</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>listgroup command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>listgroup command (NNTP)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>newsgroups</PRIMARY><SECONDARY>listing articles</SECONDARY></INDEXTERM>
|
|
To address newsgroup articles, the newsreader must know
|
|
which article numbers represent active articles. The
|
|
<option>listgroup</option> command offers a list of the active
|
|
article numbers in the current group, or an explicit group if the group name is
|
|
supplied:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>listgroup junk</userinput>
|
|
211 Article list follows
|
|
1
|
|
2
|
|
3
|
|
.
|
|
</screen>
|
|
</sect2>
|
|
|
|
<sect2><title>Retrieving an Article Header Only</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>head command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>head command (NNTP)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>articles (news)</PRIMARY><SECONDARY>retrieving headers/message body</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>news (network)</PRIMARY><SECONDARY>articles</SECONDARY><TERTIARY>retrieving headers/message body</TERTIARY></INDEXTERM>
|
|
The user must have some information about an article before she can know
|
|
whether she wishes to read it. We mentioned earlier that some commands allow the article header and body to be transferred separately. The
|
|
<option>head</option> command is used to request that the server transmit
|
|
just the header of the specified article to the newsreader. If the user
|
|
doesn't want to read this article, we haven't wasted time and network
|
|
bandwidth transferring a potentially large article body unnecessarily.
|
|
</para>
|
|
|
|
<para>
|
|
Articles may be referenced using either their number (from the
|
|
<option>listgroup</option> command) or their message identifier:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>head 2</userinput>
|
|
221 2 <7g5bhm$8f$2@news.vbrew.com> head
|
|
Path: news.vbrew.com!not-for-mail
|
|
From: terry@richard.geek.org.au
|
|
Newsgroups: junk
|
|
Subject: test message number 2
|
|
Date: 27 Apr 1999 21:51:50 GMT
|
|
Organization: The Virtual brewery
|
|
Lines: 2
|
|
Message-ID: <7g5bhm$8f$2@news.vbrew.com>
|
|
NNTP-Posting-Host: localhost
|
|
X-Server-Date: 27 Apr 1999 21:51:50 GMT
|
|
Body:
|
|
Xref: news.vbrew.com junk:2
|
|
.
|
|
</screen>
|
|
</sect2>
|
|
|
|
<sect2><title>Retrieving an Article Body Only</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>body command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>body command (NNTP)</PRIMARY></INDEXTERM>
|
|
If, on the other hand, the user decides she does want to read the article, her
|
|
newsreader needs a way of requesting that the message body be transmitted. The
|
|
<option>body</option> command is used for this purpose. It operates in much
|
|
the same way as the <option>head</option> command, except that only the message
|
|
body is returned:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>body 2</userinput>
|
|
222 2 <7g5bhm$8f$2@news.vbrew.com> body
|
|
This is another test message, please feel free to ignore it too.
|
|
|
|
.
|
|
</screen>
|
|
</sect2>
|
|
|
|
<sect2><title>Reading an Article from a Group</title>
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>article command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>article command (NNTP)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>leafnode (NNTP cache program)</PRIMARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>leafnode</SECONDARY></INDEXTERM>
|
|
While it is normally most efficient to separately transfer the headers
|
|
and bodies of selected articles, there are occasions when we are better off
|
|
transferring the complete article. A good example of this is in applications
|
|
through which we want to transfer all of the artices in a group without any sort of
|
|
preselection, such as when we are using an NNTP cache program like
|
|
<command>leafnode</command>.<footnote id="X-087-2-FNNN03">
|
|
<para>
|
|
<emphasis>leafnode</emphasis> is available by anonymous FTP from
|
|
<emphasis role="bold">wpxx02.toxi.uni-wuerzburg.de</emphasis>
|
|
in the <filename>/pub/</filename> directory.
|
|
</para>
|
|
</footnote>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
Naturally, NNTP provides a means of doing this, and not surprisingly, it
|
|
operates almost identically to the <option>head</option> command as well.
|
|
The <option>article</option> command also accepts an article number or
|
|
message ID as an argument, but returns the whole article including its header:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>article 1</userinput>
|
|
220 1 <7g2o5r$aa$6@news.vbrew.com> article
|
|
Path: news.vbrew.com!not-for-mail
|
|
From: terry@richard.geek.org.au
|
|
Newsgroups: junk
|
|
Subject: test message number 1
|
|
Date: 26 Apr 1999 22:08:59 GMT
|
|
Organization: The Virtual brewery
|
|
Lines: 2
|
|
Message-ID: <7g2o5r$aa$6@news.vbrew.com>
|
|
NNTP-Posting-Host: localhost
|
|
X-Server-Date: 26 Apr 1999 22:08:59 GMT
|
|
Body:
|
|
Xref: news.vbrew.com junk:1
|
|
|
|
This is a test message, please feel free to ignore it.
|
|
|
|
.
|
|
</screen>
|
|
|
|
<para>
|
|
If you attempt to retrieve an unknown article, the server will return
|
|
a message with an appropriately coded response code and perhaps a readable
|
|
text message:
|
|
</para>
|
|
|
|
<screen>
|
|
<userinput>article 4</userinput>
|
|
423 Bad article number
|
|
</screen>
|
|
|
|
<para>
|
|
We've described how the most important NNTP commands are used in this section.
|
|
If you're interested in developing software that implements the NNTP protocol,
|
|
you should refer to the relevant RFC documents; they provide a great deal of
|
|
detail that we couldn't include here.
|
|
</para>
|
|
|
|
<para>
|
|
Let's now look at NNTP in action through the <emphasis role="bold">nntpd</emphasis> server.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="X-087-2-nntp.nntpd"><title>Installing the NNTP Server</title>
|
|
|
|
<para>
|
|
<indexterm><primary>nntpd</primary><secondary>installing the server</secondary></indexterm>
|
|
The NNTP server (<emphasis role="bold">nntpd</emphasis>) may be compiled in
|
|
two ways, depending on the expected load on the news system. There are no
|
|
compiled versions available, because of some site-specific defaults that are
|
|
hardcoded into the executable. All configuration is done through
|
|
macros defined in <filename>common/conf.h</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis role="bold">nntpd</emphasis> may be configured as either a standalone server that
|
|
is started at system boot time from an <command>rc</command> file, or a daemon
|
|
managed by <command>inetd</command>. In the latter case, you have to have the
|
|
following entry in <filename>/etc/inetd.conf</filename>:
|
|
|
|
<screen>
|
|
nntp stream tcp nowait news /usr/etc/in.nntpd nntpd
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
The <filename>inetd.conf</filename> syntax is described in detail in <xref linkend="X-087-2-appl">. If you configure <command>nntpd</command> as standalone,
|
|
make sure that any such line in <command>inetd.conf</command> is commented
|
|
out. In either case, you have to make sure the following line appears in
|
|
<filename>/etc/services</filename>:
|
|
|
|
<screen>
|
|
nntp 119/tcp readnews untp # Network News Transfer Protocol
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To temporarily store any incoming articles, <command>nntpd</command> also needs
|
|
a <filename>.tmp</filename> directory in your news spool. You should create it
|
|
using the following commands:
|
|
|
|
<screen>
|
|
# <userinput>mkdir /var/spool/news/.tmp</userinput>
|
|
# <userinput>chown news.news /var/spool/news/.tmp</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="X-087-2-nntp.access"><title>Restricting NNTP Access</title>
|
|
|
|
<para>
|
|
<indexterm><primary>NNTP (Network News Transfer Protocol)</primary><secondary>restricting access in</secondary></indexterm>
|
|
<indexterm><primary>nntp_access file</primary></indexterm>
|
|
<indexterm><primary>access</primary><secondary>NNTP</secondary></indexterm>
|
|
Access to NNTP resources is governed by the file
|
|
<filename>nntp_access</filename> in <filename>/etc/news</filename>. Lines
|
|
in this file describe the access rights granted to foreign hosts. Each line
|
|
has the following format:
|
|
|
|
<screen width=110>
|
|
<replaceable>site</replaceable> read|xfer|both|no post|no [!<replaceable>exceptgroups</replaceable>]
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
If a client connects to the NNTP port, <emphasis role="bold">nntpd</emphasis> attempts to
|
|
obtain the host's fully qualified domain name from its IP address using reverse
|
|
lookup. The client's hostname and IP address are checked against the
|
|
<replaceable>site</replaceable> field of each entry in the order in which they
|
|
appear in the file. Matches may be either partial or exact. If an entry
|
|
matches exactly, it applies; if the match is partial, it applies only if there
|
|
is no other match following it that is at least as good.
|
|
<replaceable>site</replaceable> may be specified in one of the following ways:
|
|
|
|
<variablelist>
|
|
<varlistentry><term>Hostname</term>
|
|
<listitem><para>
|
|
This is a fully qualified domain name of a host. If this matches the client's
|
|
canonical hostname literally, the entry applies, and all following entries are
|
|
ignored.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>IP address</term>
|
|
<listitem><para>
|
|
This is an IP address in dotted quad notation. If the client's IP address
|
|
matches this, the entry applies, and all following entries are ignored.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>Domain name</term>
|
|
<listitem><para>
|
|
This is a domain name, specified as
|
|
<systemitem role="sitename">*.</systemitem><replaceable>domain</replaceable>.
|
|
If the client's hostname matches the domain name, the entry matches.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>Network name</term>
|
|
<listitem><para>
|
|
This is the name of a network as specified in
|
|
<filename>/etc/networks</filename>. If the network number of the client's
|
|
IP address matches the network number associated with the network name, the
|
|
entry matches.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>Default</term>
|
|
<listitem><para>
|
|
The string <literal>default</literal> matches any client.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Entries with a more general site specification should be specified earlier,
|
|
because any matches will be overridden by later, more exact matches.
|
|
</para>
|
|
|
|
<para>
|
|
The second and third fields describe the access rights granted to the
|
|
client. The second field details the permissions to retrieve news by pulling
|
|
(<systemitem role="keyword">read</systemitem>), and transmit news by pushing
|
|
(<systemitem role="keyword">xfer</systemitem>). A value of
|
|
<systemitem role="keyword">both</systemitem> enables both;
|
|
<systemitem role="keyword">no</systemitem> denies access
|
|
altogether. The third field grants the client the right to post
|
|
articles, i.e., deliver articles with incomplete header information,
|
|
which is completed by the news software. If the second field contains
|
|
<systemitem role="keyword">no</systemitem>, the third field is ignored.
|
|
</para>
|
|
|
|
<para>
|
|
The fourth field is optional and contains a comma-separated list of groups to
|
|
which the client is denied access.
|
|
</para>
|
|
|
|
<para>
|
|
This is a sample <filename>nntp_access</filename> file:
|
|
|
|
<screen>
|
|
#
|
|
# by default, anyone may transfer news, but not read or post
|
|
default xfer no
|
|
#
|
|
# public.vbrew.com offers public access via modem. We allow
|
|
# them to read and post to any but the local.* groups
|
|
public.vbrew.com read post !local
|
|
#
|
|
# all other hosts at the brewery may read and post
|
|
*.vbrew.com read post
|
|
</screen>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="X-087-2-nntp.authorize"><title>NNTP Authorization</title>
|
|
|
|
<para>
|
|
<indexterm><primary>NNTP (Network News Transfer Protocol)</primary><secondary>authorization</secondary></indexterm>
|
|
<indexterm><primary>NNTP (Network News Transfer Protocol)</primary><secondary>restricting access in</secondary></indexterm>
|
|
<indexterm><primary>access</primary><secondary>NNTP</secondary></indexterm>
|
|
<indexterm><primary>authorization</primary><secondary>with NNTP</secondary></indexterm>
|
|
The <command>nntpd</command> daemon provides a simple authorization scheme.
|
|
If you capitalize any of the access tokens in the
|
|
<filename>nntp_access</filename> file, <command>nntpd</command> requires
|
|
authorization from the client for the respective operation. For instance,
|
|
when specifying a permission of <systemitem role="keyword">Xfer</systemitem> or
|
|
<systemitem role="keyword">XFER</systemitem>, (as opposed to
|
|
<systemitem role="keyword">xfer</systemitem>), <command>nntpd</command> will not
|
|
let the client transfer articles to your site unless it passes authorization.
|
|
</para>
|
|
|
|
<para>
|
|
The authorization procedure is implemented by means of a new NNTP command
|
|
named <command>AUTHINFO</command>. Using this command, the
|
|
client transmits a username and a password to the NNTP server.
|
|
<command>nntpd</command> validates them by checking them against the
|
|
<filename>/etc/passwd</filename> database and verifies that the user belongs to
|
|
the <systemitem role="userid">nntp</systemitem> group.
|
|
</para>
|
|
|
|
<para>
|
|
The current implementation of NNTP authorization is only experimental
|
|
and has therefore not been implemented very portably. The result of
|
|
this is that it works only with plain-style password databases; shadow
|
|
passwords are not recognized. If you are compiling from source and
|
|
have the PAM package installed, the password check is fairly simple to
|
|
change.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="X-087-2-nntp.interact"><title>nntpd Interaction with C News</title>
|
|
|
|
<para>
|
|
<indexterm><primary>C News</primary><secondary>NNTP support</secondary></indexterm>
|
|
<indexterm><primary>NNTP (Network News Transfer Protocol)</primary><secondary>C News and</secondary></indexterm>
|
|
When <command>nntpd</command> receives an article, it has to deliver
|
|
it to the news subsystem. Depending on whether it was received as a
|
|
result of an <command>IHAVE</command> or <command
|
|
role="keyword">POST</command> command, the article is handed to
|
|
<command>rnews</command> or <command>inews</command>,
|
|
respectively. Instead of invoking <command>rnews</command>, you may
|
|
also configure it (at compile time), to batch the incoming articles
|
|
and move the resulting batches to
|
|
<filename>/var/spool/news/in.coming</filename>, where they are left
|
|
for <command>relaynews</command> to pick them up at the next queue
|
|
run.
|
|
</para>
|
|
|
|
<para>
|
|
<INDEXTERM><PRIMARY>NNTP (Network News Transfer Protocol)</PRIMARY><SECONDARY>ihave command</SECONDARY></INDEXTERM>
|
|
<INDEXTERM><PRIMARY>ihave command (NNTP)</PRIMARY></INDEXTERM>
|
|
<command>nntpd</command> has to have access to the
|
|
<filename>history</filename> file to be able to properly perform the
|
|
ihave/sendme protocol. At compile time, you have to
|
|
make sure the path to that file is set correctly. If you use C News, make
|
|
sure that C News and <command>nntpd</command> agree on the format of your
|
|
history file. C News uses <filename>dbm</filename> hashing functions to
|
|
access it; however, there are quite a number of different and slightly
|
|
incompatible implementations of the <filename>dbm</filename> library. If
|
|
C News has been linked with a different <filename>dbm</filename> library
|
|
than you have in your standard <filename>libc</filename>, you have to
|
|
link <command>nntpd</command> with this library, too.
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm><primary>checking</primary><secondary>NNTP</secondary></indexterm>
|
|
<command>nntpd</command> and C news disagreement sometimes produces error
|
|
messages in the system log that <command>nntpd</command> can not open it
|
|
properly, or you might see duplicate articles being received via NNTP. A
|
|
good test of a malfunctioning news transfer is to pick an article from your
|
|
spool area, telnet to the <emphasis role="bold">nntp</emphasis> port,
|
|
and offer it to <command>nntpd</command> as shown in the next example. Of
|
|
course, you have to replace <replaceable>msg@id</replaceable> with the
|
|
message ID of the article you want to feed to <command>nntpd</command>:
|
|
</para>
|
|
|
|
<screen>
|
|
$ <userinput>telnet localhost nntp</userinput>
|
|
Trying 127.0.0.1...
|
|
Connected to localhost
|
|
Escape characters is '^ ]'.
|
|
201 vstout NNTP[auth] server version 1.5.11t (16 November 1991) ready at
|
|
Sun Feb 6 16:02:32 1194 (no posting)
|
|
<userinput>IHAVE</userinput> <replaceable>msg@id</replaceable>
|
|
435 Got it.
|
|
<userinput>QUIT</userinput>
|
|
</screen>
|
|
|
|
<para>
|
|
This conversation shows <command>nntpd</command>'s proper reaction;
|
|
the message <literal>Got it</literal> tells you that it already
|
|
has this article. If you get a message of
|
|
<command>335 Ok</command> instead, the lookup in the history
|
|
file failed for some reason. Terminate the conversation by typing Ctrl-D.
|
|
You can check what has gone wrong by checking the system log;
|
|
<command>nntpd</command> logs all kinds of messages to the
|
|
<systemitem role="keyword">daemon</systemitem> facility of
|
|
<command>syslog</command>. An incompatible <filename>dbm</filename> library
|
|
usually manifests itself in a message complaining that
|
|
<function>dbminit</function> failed.
|
|
</para>
|
|
|
|
<indexterm class="endofrange" startref="ch18.nntp.desc">
|
|
<indexterm class="endofrange" startref="idx-configuringNNTP-1">
|
|
<INDEXTERM startref="protocols.NNTP" class=endofrange>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
|