=pod

=head1 NAME

B<lmtp2nntp> - mail to nntp gateway

=head1 SYNOPSIS

B<lmtp2nntp> 
[B<-o> I<origin>]
[B<-j> I<hostname>]
[B<-i> I<messageid>]
[B<-t> I<timeout>]
[B<-p> I<protocol>]
[B<-l> I<logtarget>]
[B<-h> I<host>[I<:port>]]
[B<-d> I<deliverymode>]
[B<-g> I<groupmode>]
[B<-t> I<tracefile>]
[B<-v>]
I<newsgroup> 
[I<newsgroup> ...]

=head1 DESCRIPTION

The B<lmtp2nntp> program reads mail from stdin and posts it to one or more
newsgroups using NNTP. It delivers the message immediately or fails.
If queuing is desired it can operate as a LMTP server.

The following options are available:

=over 4

=item B<-o> I<origin>

Outgoing network IP address or hostname to bind to.

=item B<-j> I<hostname>

Own FQDN used in LMTP and NNTP protocols.

=item B<-i> I<messageid>

Message id of MTA (for logging purposes only).

=item B<-t> I<timeout>

LMTP and NNTP protocol timeouts (in seconds).
 
=item B<-p> I<protocol>

Incoming protocol. Default is C<stdin> which means B<lmtp2nntp>
reads the incoming mail from F<stdin> in RFC822 message format and reports errors to F<stderr>.
Alternatively if I<protocol> is C<LMTP>, B<lmtp2nntp> speaks Local Mail
Transport Protocol (LMTP) according to RFC 2033 on F<stdin>/F<stdout>.

=item B<-l> C<stderr>

=item B<-l> C<syslog>[C<:>I<facility>]

=item B<-l> C<file:>I<localfile>

Logging target. This option can be specified more than once. Default is no
logging. Default I<facility> for C<syslog:> is C<lmtp2nntp>.

=item B<-h> I<host>[:<port>]

Hostname or address and optional TCP port of a NNTP service. Unless a port is
specified, getserbyname(nntp) is queried with fallback to 119/tcp. If C<-h>
option is ommited, the environment variable C<NNTPSERVER> is read, if this is
undefined or empty C<news> is used and if this doesn't resolve, C<localhost>
is assumed.

This option can be specified more than once. It is assumed that multiple
servers are used to increase the reliability of the news system and to speed
up distribution by posting the same article to more than one server. In regard
to this program they must provide the same groups and talk to each other. 

=item B<-d> I<deliverymode>

Possible values for I<deliverymode> are C<post>, C<feed> or a string used to
fake a LMTP return code and DSN in "LLL/D.D.D" format. The slash is replaced
by a space internally. The default is "553/5.7.1" meaning "Requested action
not taken: mailbox name not allowed/ Delivery not authorized, message
refused". In C<post> mode articles are sent to the NNTP server(s) using POST
command. Before posting, a duplicate check using STAT command is issued. In
C<feed> mode articles are sent to the NNTP server(s) using IHAVE command.
Specifying a return code/ DSN replaces the post/ feed logic by a noop and
assumes the given string must be returned to the LMTP side. This is useful for
debugging LMTP setups without engaging NNTP.

=item B<-g> I<groupmode>

Possible values for I<groupmode> are C<arg> (default), C<envelope> and
C<header>. In C<arg> mode, the C<newsgroup>s specified as command line
arguments are ultimate destinations for the received messages.  Addresses from
envelope are ignored.  In C<envelope> mode the newsgroup(s) are taken from the
LMTP envelope, in C<header> mode the newsgroup(s) are taken from the header.
In all modes C<Newsgroups:> header is rewritten. In C<envelope> and C<header>
mode groups must still be specified as command line arguments. However, in
these modes the command line arguments are filters representing allowed
groups. Filters can be specified as wildmat's.

=item B<-t> I<tracefile>

Enable LMTP and NNTP protocol tracing into tracefile. When using C<syslog:>
these messages are logged with C<debug> level.

=item B<-v>

Enable verbose processing messages in logfile.  When using C<syslog:> these
messages are logged with C<info> level.

=item I<newsgroup> 

Newsgroup to post the message to. Multiple groups can be specified.
Crosspostings only succeed if delivery to I<all> groups succeed.

=back

=head1 SENDMAIL INTEGRATION

  Mlmtp2nntp, P=/... /*FIXME*/

=head1 EXAMPLE

 $ cat rfc822.message | lmtp2nntp -l /tmp/log -v -h mynews foo.bar

reads rfc822.message and posts it into group "foo.bar" using NNTP service on
host "mynews". Activity is logged to /tmp/log. If posting is
successful, the exit status is 0.

 $ cat rfc822.message | lmtp2nntp -h news1 -h news2 -h news3 foo.bar

reads rfc822.message and posts it into group "foo.bar" using NNTP service on
all hosts "news1", "news2" and "news3". Activtiy is not logged.
If at least one posting is successful, the exit status is 0.

 $ cat rfc822.message | lmtp2nntp -l stderr foo.bar quux.bar test.bar

reads rfc822.message and posts it into groups "foo.bar", "quux.bar" and
"test.bar" using NNTP service on host C<${NNTPSERVER:-news}>. Activity
is logged to stderr. Only if all three crosspostings succeed, the exit
status is 0.

=head1 DIAGNOSTICS

when invoked from command line

 0 = successful execution and delivery
 1 = execution failed
 2 = cannot deliver to any nntpserver

when invoked as LMTP server

 0 = successful execution
 1 = execution failed

delivery status is part of the LMTP protocol

=head1 STANDARDS

 RFC1891 Delivery Status Notification (DSN)
 FIXME

=head1 AUTHOR

 The OSSP Project
 Cable & Wireless Deutschland GmbH
 Thomas Lotterer
 <thomas.lotterer@cw.com>

=cut