=head1 NAME

send-ihave - Send ihave control messages to remote sites

=head1 SYNOPSIS

B<send-ihave> [B<-d>] I<sitename>[B<:>I<hostname>]
[I<sitename>[B<:>I<hostname>] ...]

=head1 DESCRIPTION

Using B<send-ihave> is discouraged; the ihave and sendme control messages
implement a predecessor of the NNTP protocol, and are now largely obsolete on
the Internet but still see use in conjunction with some transport protocols
such as UUCP.

In case you really need using ihave and sendme control messages, and follow
these instructions to set them up, please inform the INN maintainers of any
documentation improvements that would have made the installation easier,
notably missing or unclear steps.

The basic idea behind the ihave and sendme control messages is that you tell
your UUCP peers what articles you have available via ihave control messages,
and you respond with a sendme control message for the articles that you want.

B<send-ihave> processes the batch files written by B<innd> to send ihave
control messages to remote NNTP sites.  The sites to be fed are specified
by giving C<sitename:hostname> pairs on the command line.  The I<sitename>
is the label the site has in the F<newsfeeds> file, without its C<.ihave>
suffix.  The I<hostname> is the real hostname of the remote site, a FQDN
(Fully Qualified Domain Name).  Normally, the I<sitename> and the I<hostname>
are the same, and as such don't have to be specified as C<sitename:hostname>
pairs but just as C<sitename>.

B<send-ihave> encapsulates Message-IDs in an ihave control message and uses
B<inews> to send the control message to a C<to.hostname> pseudo-newsgroup.

The batch file generated by B<send-ihave> for a given site is named
F<sitename.ihave> in the I<pathoutgoing> directory.  To prevent batch file
corruption, shlock(8) is used ensure these files are not processed by two
running instances in parallel.

For instance, to generate ihave control messages for F<news.server.com>
when receiving articles in the comp.* hierarchy, just add the following
line in your F<newsfeeds> file (and reload it):

    news.server.com.ihave:comp.*:Tf,Wm:

(Note that if you send C<*> to C<news.server.com>, you should add C<@to,@to.*>
to the end of the newsgroup pattern so that the ihave control message
generated by B<send-ihave> isn't, itself, included in the list of articles
in an ihave control message.  You may also want to add that pattern to
the end of any entry processing control articles, like B<controlchan>,
or being fed a C<*> pattern.)

Then, periodically run out of cron(8) the following command:

    send-ihave news.server.com

B<send-ihave> will then post to the C<to.news.server.com> pseudo-newsgroup
an ihave control article containing a list of Message-IDs.  Several control
articles may be posted, each one containing up to 1000 Message-IDs.

Make sure the C<to.news.server.com> pseudo-newsgroup exists on your server (or
the C<to> pseudo-newsgroup if I<mergetogroups> is set to true in F<inn.conf>),
and that ihave control articles are not filtered (the default Cleanfeed
configuration rejects them).  These control articles will be filed in the
C<control> pseudo-newsgroup (or C<control.ihave> if it exists), or C<to>
if I<mergetogroups> is set to true.

You now have to propagate them with any method you want to the remote server.
You probably already had one set up, in which case you only have to add
the C<to.news.server.com> newsgroup in the list of groups to feed it.
(See how send-uucp(8) works to set up a UUCP feed.)

Besides sending ihave control messages, your news server needs processing the
sendme control messages it receives from remote peers.  You have to add a
C<sendme> entry in F<control.ctl.local> with a B<doit> action to allow the
processing of these messages matching a given From address.  B<controlchan>
will then generate a batch file named F<pathname.work> in I<pathoutgoing>,
containing a list of storage tokens (I<pathname> is taken from the Path header
field body or the IP address of the remote peer, depending on the value
of I<logipaddr> in F<inn.conf>).  Finally, you'll have to set up batcher(8)
or send-uucp(8) to send the news batches to your remote peers.

Similarly, your news server needs processing the ihave control messages it
receives from remote peers.  This step is the easiest to do.  Just add an
C<ihave> entry in F<control.ctl.local> like the one you added for C<sendme>.
B<controlchan> will process these ihave control messages, and generate a
sendme control article for each article present in the ihave control message
but not in your local news server.  These sendme control articles are posted
to the C<to.pathname> pseudo-newsgroup, and will be propagated as described
before.  (Note that there may be two different C<to> groups to create because
the I<sitename> used in F<newsfeeds> may not be the same as I<pathname>.)

Beware that the ihave and sendme control messages are not signed.  You should
enforce restrictions on who can send articles to C<to.*> groups, either
via F<readers.conf> or special rules in filter hooks, and on the C<ihave>
and C<sendme> lines in F<control.ctl.local>.

=head1 OPTIONS

=over 4

=item B<-d>

The B<-d> flag causes B<send-ihave> to send output to stdout rather than
the F<send-ihave.log> log file in I<pathlog>.

=back

=head1 HISTORY

Rewritten into POD by Julien Elie.

=head1 SEE ALSO

batcher(8), controlchan(8), control.ctl(5), inews(1), newsfeeds(5),
send-uucp(8).

=cut
