=pod

=head1 NAME

B<lmtp2nntp> - mail to news gateway

=head1 SYNOPSIS

B<lmtp2nntp>
[B<-V>]
[B<-d> I<deliverymode>]
[B<-g> I<groupmode>]
[B<-h> I<host>[I<:port>][,I<host>[I<:port>], ...]]
[B<-m> I<maxmessagesize>]
[B<-n> I<hostname>]
[B<-t> I<tracefile>]
[B<-v>]
[B<-w> I<waittime>]
I<newsgroup> [I<newsgroup> ...]

B<FIXME NOT YET IMPLEMENTED>
[B<-o> I<origin>]
[B<-i> I<messageid>]
[B<-l> I<logtarget>]

=head1 DESCRIPTION

The B<lmtp2nntp> program is a LMTP service which is usually invoked by a MTA.
Input messages get their headers slightly reformatted to match network news
article format. The article is then posted or fed into a NNTP service.
Delivery must take place immediately or the transaction fails.  A LMTP service
relies on the queuing capabilities of its MTA. To support this, the program
returns proper delivery status notification which indicates successful
completed action, persistent transient failure or permanent failure.

The following options are available:

=over 4

=item B<-V>

Print version information.

=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 and headers 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<-h> I<host>[I<:port>][,I<host>[I<: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 and it is possible to specify more
than one host/ port per option as a comma-separated list. 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<-m> I<maxmessagesize>

Maximum message size in bytes. Default is 8388608 (8M). Values below 64 are
considered unacceptable small.

=item B<-n> I<nodename>

Own FQDN used in LMTP and NNTP protocols. This overrides the nodename returned
by uname(3).

=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 B<-w> I<waittime>

Specify the time the NNTP client waits for the initial connect to complete and
the time to wait for every server's response. Value is given in seconds and
must be greater than or equal to 1 second. The default is OS dependent for the
connect and a 3 second timeout waiting for a server's response.

=item I<newsgroup> [I<newsgroup> ...]

Newsgroup to post the message to or filter, depending on groupmode.  Multiple
groups can be specified.  Crosspostings succeed if delivery to I<any> group
succeeds.

B<FIXME NOT YET IMPLEMENTED>

=item B<-o> I<origin>

Outgoing network IP address or hostname to bind to.

=item B<-i> I<messageid>

Message id of MTA (for logging purposes only).

=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>.

=back

=head1 SENDMAIL INTEGRATION

t.virtusertable

    # mail to news gateway
    posting+*@first.gateway.example %2@lmtp2nntp

t.mailertable

    # mail to news gateway
    lmtp2nntp       lmtp2nntp:second.gateway.example

sendmail.m4

    dnl #  Mailer: LMTP2NNTP (mail to news gateway)
    define(`LMTP2NNTP_MAILER_PATH',         `confMYBINDIR/lmtp2nntp')
    define(`LMTP2NNTP_MAILER_MAX',          `100000')
    define(`LMTP2NNTP_MAILER_DELIVERYMODE', `post')
    define(`LMTP2NNTP_MAILER_GROUPMODE',    `envelope')
    define(`LMTP2NNTP_MAILER_ARGS',         `-t confMYVARDIR/lmtp2nntp.log')
    define(`LMTP2NNTP_MAILER_GROUPS',       `alt.test.\* alt.binaries.test')
    MAILER(lmtp2nntp)

=head1 DIAGNOSTICS

when invoked as LMTP server

 0 = successful execution
 1 = execution failed

Returning proper delivery status notification is part of the LMTP protocol.

=head1 STANDARDS

=over 4

=item RFC0821

Simple Mail Transfer Protocol.  J. Postel. Aug-01-1982. (Format: TXT=124482
bytes) (Obsoletes RFC0788 ) (Obsoleted by RFC2821) (Also STD0010) (Status:
STANDARD )

=item RFC0822

Standard for the format of ARPA Internet text messages.  D. Crocker.
Aug-13-1982. (Format: TXT=109200 bytes) (Obsoletes RFC0733) (Obsoleted by
RFC2822) (Updated by RFC1123, RFC1138, RFC1148, RFC1327, RFC2156) (Also
STD0011) (Status: STANDARD)

=item RFC0977

Network News Transfer Protocol.  B. Kantor, P. Lapsley. Feb-01-1986. (Format:
TXT=55062 bytes) (Status: PROPOSED STANDARD)

=item RFC1035

Domain names - implementation and specification.  P.V. Mockapetris.
Nov-01-1987. (Format: TXT=125626 bytes) (Obsoletes RFC0973, RFC0882, RFC0883)
(Updated by RFC1101, RFC1183, RFC1348, RFC1876, RFC1982, RFC1995, RFC1996,
RFC2065, RFC2136, RFC2181, RFC2137, RFC2308, RFC2535, RFC2845) (Also STD0013)
(Status: STANDARD)

=item RFC1652

SMTP Service Extension for 8bit-MIMEtransport.  J. Klensin, N. Freed, M. Rose,
E. Stefferud, D. Crocker. July 1994.  (Format: TXT=11842 bytes) (Obsoletes
RFC1426) (Status: DRAFT STANDARD)

=item RFC1854

SMTP Service Extension for Command Pipelining.  N. Freed. October 1995.
(Format: TXT=14097 bytes) (Obsoleted by RFC2197) (Status: PROPOSED STANDARD)

=item RFC1893

Enhanced Mail System Status Codes.  G. Vaudreuil. January 1996. (Format:
TXT=28218 bytes) (Status: PROPOSED STANDARD)

=item RFC1894

An Extensible Message Format for Delivery Status Notifications.  K. Moore, G.
Vaudreuil. January 1996. (Format: TXT=77462 bytes) (Updated by RFC2852)
(Status: PROPOSED STANDARD)

=item RFC2034

SMTP Service Extension for Returning Enhanced Error Codes.  N. Freed. October
1996. (Format: TXT=10460 bytes) (Status: PROPOSED STANDARD)

=item RFC2606

Reserved Top Level DNS Names.  D. Eastlake, A. Panitz. June 1999. (Format:
TXT=8008 bytes) (Also BCP0032) (Status: BEST CURRENT PRACTICE)

=item RFC2821

Simple Mail Transfer Protocol.  J. Klensin, Editor. April 2001.  (Format:
TXT=192504 bytes) (Obsoletes RFC0821, RFC0974, RFC1869) (Status: PROPOSED
STANDARD)

=item RFC2980

Common NNTP Extensions.  S. Barber. October 2000. (Format: TXT=57165 bytes)
(Status: INFORMATIONAL)

=back

=head1 AUTHOR

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

=cut