
   _           _        ____              _         
  | |_ __ ___ | |_ _ __|___ \ _ __  _ __ | |_ _ __  
  | | '_ ` _ \| __| '_ \ __) | '_ \| '_ \| __| '_ \ 
  | | | | | | | |_| |_) / __/| | | | | | | |_| |_) |
  |_|_| |_| |_|\__| .__/_____|_| |_|_| |_|\__| .__/ 
                  |_|                        |_|    

  OSSP lmtp2nntp - Mail to News Gateway

  INSTALLATION
  ============

  To install OSSP lmtp2nntp into /path/to/lmtp2nntp/{bin,man}/ perform
  the following steps in your shell:
      
    $ ./configure --prefix=/path/to/lmtp2nntp
    $ make
    $ make check
    $ make install

  CONFIGURATION
  =============

  In order to use OSSP lmtp2nntp, the program has to be integrated into
  a Mail Transfer Agent (MTA) which speaks Local Mail Transfer Protocol
  (LMTP). OSSP lmtp2nntp was developed with Sendmail 8.11 and tested
  with Sendmail 8.11 and Postfix 20010228, but should also work with
  other MTAs who provide an LMTP interface. The detailed integration
  into Sendmail 8.11 and Postfix 20010228 is shown below.

  Sendmail Integration
  --------------------

  1. Create a "cf/mailer/lmtp2nntp.m4" macro file with the following contents:

     | PUSHDIVERT(-1)
     | _DEFIFNOT(`LMTP2NNTP_MAILER_PATH',          `/usr/local/bin/lmtp2nntp')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_FLAGS',         `mDFMuXz')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_ARGS',          `')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_CLIENTBIND',    `0.0.0.0')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_GROUPMODE',     `envelope')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_LOGLEVEL',      `notice:/var/log/lmtp2nntp')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_MAILFROM',      `^.+@(?:[^.]+\.)+[^.]+$')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_NODENAME',      `confDOMAIN_NAME')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_OPERATIONMODE', `post')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_SIZE',          `800000')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_TIMEOUT',       `nntp:connect=60')
     | _DEFIFNOT(`LMTP2NNTP_MAILER_NEWSGROUP',     `\*')
     | POPDIVERT
     |   
     | #########################################
     | ###   LMTP2NNTP Mailer specification  ###
     | #########################################
     | 
     | Mlmtp2nntp, P=LMTP2NNTP_MAILER_PATH, F=LMTP2NNTP_MAILER_FLAGS,
     |             S=EnvFromSMTP/HdrFromSMTP, R=MasqSMTP, E=\r\n,
     |             L=990, T=DNS/RFC822/SMTP, M=LMTP2NNTP_MAILER_SIZE,
     |             A=lmtp2nntp LMTP2NNTP_MAILER_ARGS dnl
     |                         -c LMTP2NNTP_MAILER_CLIENTBIND dnl
     |                         -d $h dnl
     |                         -g LMTP2NNTP_MAILER_GROUPMODE dnl
     |                         -l LMTP2NNTP_MAILER_LOGLEVEL dnl
     |                         -m LMTP2NNTP_MAILER_MAILFROM dnl
     |                         -n LMTP2NNTP_MAILER_NODENAME dnl
     |                         -o LMTP2NNTP_MAILER_OPERATIONMODE dnl
     |                         -s LMTP2NNTP_MAILER_SIZE dnl
     |                         -t LMTP2NNTP_MAILER_TIMEOUT dnl
     |                         LMTP2NNTP_MAILER_NEWSGROUP

     This changes nothing in your Sendmail configuration, but just adds
     a new mailer named "lmtp2nntp" to Sendmail.

  2. Add to your Sendmail M4 configuration (file "sendmail.m4" or
     "sendmail.mc" according to your installation) the following entry:

     sendmail.m4:

     | dnl #  Mailer: LMTP2NNTP (mail to news gateway)
     | define(`LMTP2NNTP_MAILER_PATH', `/path/to/lmtp2nntp/bin/lmtp2nntp')
     | MAILER(lmtp2nntp)

     This defines the new "lmtp2nntp" mailer in your Sendmail
     configuration, but still does not activate it. Additionally feel
     free to overwrite more LMTP2NNTP_MAILER_XXXX variables in order
     to adjust the run-time behaviour of OSSP lmtp2nntp. See the
     lmtp2nntp(1) manual page for more details about the commmand line
     parameters.

  3. Activate in your Sendmail M4 configuration (file "sendmail.m4" or
     "sendmail.mc" according to your installation) the virtual user
     and mailer table:

     sendmail.m4:

     | FEATURE(mailertable,   `hash -o /path/to/mailertable')
     | FEATURE(virtusertable, `hash -o /path/to/virtusertable')

  4. Add the following entries to both your virtual user table (file
     "virtusertable") and your mailer table (file "mailertable") in order
     to finally activate the mail to news gateway:

     virtusertable:

     | posting+*@gateway.example.com  %2@lmtp2nntp.invalid

     mailertable:

     | lmtp2nntp.invalid              lmtp2nntp:news.example.com

     Notice that we use the RFC2606 top-level domain name ".invalid"
     for the internal mapping between virtual user table and the
     mailer table. This is neccessary because Sendmail cannot directly
     map individual recipient mailbox addresses to outgoing mailers.

     In this example configrution we assumed that the machine
     "gateway.example.com" is the FQDN of machine running Sendmail
     and OSSP lmtp2nntp and "news.example.com" is the remote Usenet
     News server speaking NNTP. This means that mails addressed to
     "posting+foo.bar@gateway.example.com" are posted via NNTP as news
     articles into the newsgroup foo.bar on "news.example.com".

     Additionally, if just the MX DNS record for "news.example.com"
     points to the address of "gateway.example.com" you can add the
     following additional entry to your virtual user table in order
     to let "news.example.com" virtually provide mail to news gateway
     functionality:

     virtusertable:

     | @news.example.com              %1@lmtp2nntp.invalid

     Notice that there are more delivery modes supported by OSSP
     lmtp2nntp. Refer to the lmtp2nntp(1) manual page for more details.

  Postfix Integration
  -------------------

  1. Make sure that Postfix was built with PCRE map support
     (see README.PCRE in the original Postfix source distribution).
     It basically means building and installing PCRE from
     ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/ and
     configuring Postfix with at least:

     | make makefiles \
     |     CCARGS="-I/path/to/pcre/include -DHAS_PCRE"
     |     AUXLIBS="-L/path/to/pcre/lib -lpcre"

  2. In the Postfix main configuration file (main.cf) you have
     enable the virtual user and transport mapping tables:

     main.cf:

     | virtual_maps   = pcre:/path/to/virtual
     | transport_maps = hash:/path/to/transport

  3. Add the following entry to the Postfix virtual user mapping table:

     /path/to/virtual:

     | /^posting\+(.*)@gateway\.example\.com$/ $1@lmtp2nntp.invalid

  4. Add the following entry to the Postfix transport mapping table:

     /path/to/transport:

     | lmtp2nntp.invalid  lmtp:unix:/path/to/lmtp2nntp.news.example.com

     Additionally convert the transport mapping table into the hash
     table format Postfix reads (not required for the virtual user
     mapping table above, because it is PCRE based).

     $ postmap /path/to/transport

  5. Start lmtp2nntp as a stand-alone daemon for delivering to
     news.example.com. This is required because in contrast to Sendmail,
     Postfix can speak LMTP only via Unix Domain and Internet Domain
     sockets (but not via a Unix pipe). Use the following script:

     lmtp2nntpd:

     | #!/bin/sh
     | LMTP2NNTP_PATH='/usr/local/bin/lmtp2nntp'
     | LMTP2NNTP_ARGS=''
     | LMTP2NNTP_CLIENTBIND='/path/to/lmtp2nntp.news.example.com'
     | LMTP2NNTP_GROUPMODE='envelope'
     | LMTP2NNTP_LOGLEVEL='notice:/var/log/lmtp2nntp'
     | LMTP2NNTP_MAILFROM='^.+@(?:[^.]+\.)+[^.]+$'
     | LMTP2NNTP_NODENAME=`hostname`
     | LMTP2NNTP_OPERATIONMODE='post'
     | LMTP2NNTP_SIZE='800000'
     | LMTP2NNTP_TIMEOUT='nntp:connect=60'
     | LMTP2NNTP_NEWSGROUP='*'
     | case $1 in
     |     start )
     |         $LMTP2NNTP_PATH -D -P "/path/to/lmtp2nntp.pid" \
     |             -c "$LMTP2NNTP_CLIENTBIND" \
     |             -d "news.example.com" \
     |             -g "$LMTP2NNTP_GROUPMODE" \
     |             -l "$LMTP2NNTP_LOGLEVEL" \
     |             -m "$LMTP2NNTP_MAILFROM" \
     |             -n "$LMTP2NNTP_NODENAME" \
     |             -o "$LMTP2NNTP_OPERATIONMODE" \
     |             -s "$LMTP2NNTP_SIZE" \
     |             -t "$LMTP2NNTP_TIMEOUT" \
     |             "$LMTP2NNTP_NEWSGROUP"
     |         ;;
     |     stop )
     |         $LMTP2NNTP_PATH -K -P "/path/to/lmtp2nntp.pid"
     |         ;;
     | esac

  5. start lmtp2nntp daemon and reload Postfix to activate the new setup:

     $ lmtp2nntpd start
     $ postfix reload

