File: INSTALL

-------
INSTALL
-------


Requirements
------------
php                    Ver. => 4
mysql                  Ver. => 4
smtp.php               http://www.phpclasses.org/browse/download/1/file/30/name/smtp.php
mime_parser.php        http://www.phpclasses.org/browse/download/1/file/14670/name/mime_parser.php
rfc822_addresses.php   http://www.phpclasses.org/browse/download/1/file/21704/name/rfc822_addresses.php
pop3.php               http://www.phpclasses.org/browse/download/1/file/3/name/pop3.php
sasl.php               http://www.phpclasses.org/browse/download/1/file/7491/name/sasl.php (if you use smtp servers like gmail)
login_sasl_client.php  http://www.phpclasses.org/browse/download/1/file/7493/name/login_sasl_client.php
ntlm_sasl_client.php   http://www.phpclasses.org/browse/download/1/file/7495/name/ntlm_sasl_client.php

optional
--------
test_smtp.php          http://www.phpclasses.org/browse/download/1/file/31/name/test_smtp.php
                       (for outgoing smtp server test. run it before configure mltable smtp values)


How to install Pop3ml
---------------------
- Uncompress zip/tgz file (ie. /tmp/pop3ml.tgz) into your http server DOCUMENT_ROOT (ie. /srv/www/htdocs)

   cd /srv/www/htdocs
   tar xzvf /tmp/pop3ml.tgz
   cd pop3ml

- create ml database

   mysqladmin -u username -p create pop3ml
   mysql -u username -p pop3ml <./sql/pop3ml.sql

- create mltable record

   mysql -u username -p pop3ml <./sql/mltable.sql

   for italian version:

   mysql -u username -p pop3ml <./sql/mltable-it.sql

- download all required php scripts (if URL's have changed search 'phpclasses.org' for new location)
  (check file owner and permissions)

- run your browser to http://yourserver.com/phpMyAdmin, select database 'pop3ml' and table 'mltable'.
  adjust mltable record filling all field (see below for explanation).
  You better add subscribers list after some tests.

- edit config.php file and adjust some variables (mlinfo->listname with listname, user/password...)

- test installation. Run your browser:

   http://yourserver.com/pop3ml/mlsend.php
 
   if you receive a message like this:
      2009/01/29 11:31:34. mylistname: 0 mess.
   you can go on with smtp test, otherwise there is a problem with pop3 account.

- make smtp test. Send an email message to ML address (i.e. a message without subject and body
  only with 'subscribe' for subscription test). Be aware, messages could delay (queue,
  slow smtp server,lan traffic,..). Run your browser:

   http://yourserver.com/pop3ml/mlsend.php

   if you don't receive a message like this:
      2009/01/29 11:37:22. mylistname: 1 mess. total size [1738] # 1, size [1738]: subscribe [myaccount@myserver.it]. require confirmation:
   there is a problem sending message to smtp server. You can use "test_smtp.php" or "test_gmail.php"
   for gmail accounts.

- after succesfully ML test, copy the shell script to an excecutable directory
  and adjust it (user and password if required). you can use other programs/shell scripts
  to run php script (lynx for example)

   cp ./template/mlsend.sh /usr/local/bin

   or

   cp ./template/mlsend-lynx.sh /usr/local/bin/mlsend.sh

- edit your crontab file and add your personal data 

   crontab -e

   (this example run Pop3ml every 10 minutes, from 8:00 AM to 20:00 PM, and from monday to saturday)

    0,10,20,30,40,50 8-20 * * 1-6 /usr/local/bin/mlsend.sh

- check periodically log files


How to configure lists (database 'pop3ml' table 'mltable')
----------------------------------

field list

- id
   autoincrement primary key

- typology
   used only with 'goshweb', do not touch

- listname
   ml list name. Put it into 'config.php' to run this list

- hostname
   pop3 data (format 'hostname:port:tls', ie 'pop.gmail.com:995:1') set tls to '1' if smtp server require TLS

- listaddr
   ML address corresponding to pop3 account (ie. 'mylist@gmail.com')

- listuser
   pop3 user account

- listpoppass
   pop3 password

- listowneremail
   list owner for contacts

- parentlist
   if ML has parent (not enabled yet)

- msgsize
  max size for messages

- smtpserver
   outgoing smtp server for message delivery. you can add more then one smtp server in this form:
    smtpserver:port:tls:pop3port:popuser:poppassword
    smtpserver1:port:tls:pop3port:popuser:poppassword
   (ie.)
    smtp.gmail.com:465:1:995:popuser:poppass
    anothersmtp.com:25:0

- mltype
   'm' for mailinglist. Only 'allowed' or 'subscribed' users can post. Only 'allowed' users will receive messages
       delivered by ML
   'n' for newsletter. Only 'allowed' users can post. Only 'subscribed' user will receive messages

- confirmsub
   'yes' new subscribers will receive mail request to confirm subscription
   'no'  no request will be sent to subscribers (deprecated)
   
- confirmunsub
   'yes' new subscribers will recerive mail request to confirm unsubscription
   'no'  no request will be sent to unsubscribers (deprecated)
   
- moderatedlist
   'yes' new messages from subscribers need approvation from moderator(s)
   'no'  no moderation for messages
   
- subscriptionmod (not enabled yet)
   'yes' new confirmation request have to be confirmed from moderator(s)
   'no'  no moderation form subscription
   
- subscribersonly
   'yes' ml is private, only 'allowed' and 'subscribed' users can post
   'no'  ml is public, everybody can post but only 'subscribed' will receive messages
   
- removeafterpop
   'yes' delete message after delivery
   'no'  messages won't be removed after delivery
   
- shutdown
   'yes' ml is (temporarily) disabled
   'no'  ml is active
   
- sublist
   subscribers list. add addresses separated by CR
   (ie.)
    me@gmail.com
    you@yahoo.com

- modsublist
   moderator(s) list. as subscribers list. add addresses separated by CR
   
- denysublist
   rejected address list. addresses will be REGEXP(ed)
   
- allowsublist
   allowed address list. addresses will be REGEXP(ed) and will not receive messages (post only)
   
- digestsublist (not implemented yet)
   
- mimeremove (not implemented yet)
   
- headerchange
   put here header(s) you want to add or remove from messages sent to subscribers. format: HeaderDef::HeaderValue
   for example:

   Reply-To::__LISTADDRESS__			(__LISTADDRESS__ will be replaced with pop3ml->mltable->listadd)
   return-receipt-to::				(this header row will be removed from message header)
   Mailing-List::contact <__LISTOWNER__>	(__LISTWONER__ will be replaced with pop3ml->mltable->listowneremail)
   
- submsg
   body text sent to new subscribers request confirmation
   
- unsubmsg
   body text sent to subscribers unsubscription confirmation
   
- welcome
   body text sent to new subscribed addresses
   
- goodbye
   body text sent to removed addresses
   
- trailerfile
   body text appended to every message delivered by ML (only for "text/plain" messages format)
   
- rowlock
   '' ML is not busy and ready to accepting messages
   'user_remoteserveraddress-date' ML is busy for delivery or data administration. if you are using phpMyAdmin
                                     or similar programs set this value not equal to '', to block 
                                     momentarily ML delivery, or set 'shutdown' to 'yes'
   ie.
   'root@127.0.0.1-2008/12/12-09:10:33'
   

/* WARNING! Be careful with messages! You can easily reach max size for a
* php script (normally 10M) or (for example) max_allowed_packet for mysql.
*/

enjoy