INSTALL

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; Phamm - INSTALL
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

  Copyright (c) 2005-2016 Alessandro De Zorzi, Mirko Grava
  <team@phamm.org> http://www.phamm.org/
  
  Project sponsored by RHX Srl - www.rhx.it

  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.2
  or any later version published by the Free Software Foundation;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

SECTIONS
0.	PRELIMINARY
   0.1 Prepare the files
   0.2 Requirements
     0.2.1 optional requirements required for email
     0.2.2 optional requirements for ftp
   0.3 Contents
1.	LDAP
   1.1 Schema
   1.2 Change phamm password
   1.3 Populate
     1.3.1 populate plugin support
2.	PHAMM CONFIGURATION
   2.1 Config files
3.	MAIL SERVICES
   3.1 config postfix
   3.2 config courier
   3.3 config amavis
   3.4 config gnarwl
   3.5 cleaner.sh script







0. PRELIMINARY
^^^^^^^^^^^^^^

   0.1 Prepare the files

   Untar the archive
   	tar xvfz phamm-X.X.X.tar.gz

   Put the directory phamm-X.X.X in a web accessible directory:
   	(Example: mv phamm /var/www/)
	
   or configure httpd to use Alias.

   You can obtain for make accessible from web only the
   sub-directory phamm/www-data.

   0.2 Requirements
	web server (tested with Apache)
	php4 or php5 with ldap extension enable (php-ldap php4-ldap...)
	OpenLDAP (recommend openldap 2.1 or 2.2)
	Webbrowser (doh!)

     0.2.1 optional requirements required for email
	    postfix email server
	    pop3/imap:	severs (that support ldap)
		examples: cyrus,courier. (tested with apache)
	    gnarwl:	 for autoresponding:(to first user email)
	    amavisd: 	for anti-virus/anti-spam:
	    spamassassain
	    clam-av or similar av-software (tested with Clam-AV)
	    net::ldap cpan modules

     0.2.2 optional requirements for ftp
	    pure-ftpd
	    pure-ftpd-ldap-backend

   0.3 Contents
	
	In the examples folder you can find examples of all the configuration
	files for each server section outlined below. Please remember these
	are examples and they will have to be edited to suit your own personal
	requirements.

1. LDAP
^^^^^^^

   1.1 Schema

   Copy schema/phamm.schema file in your schema directory
   (ex. /etc/ldap/schema/ for Debian).

   Probably you need other schema files, you can copy they from
   respective projects or from http://open.rhx.it/phamm/schema/

   amavis.schema
   dnsdomain2.schema
   ISPEnv2.schema
   pureftpd.schema
   radius.schema
   samba.schema

   Copy examples/conf/slapd/slapd.conf to override your slapd.conf (ex.
   /etc/ldap/ for Debian or /etc/openldap). Add YOUR password for the
   cn admin with the command slappasswd.
   
   The slapd.conf has the loglevel set to 0. For debugging set it to 128
   or start slapd with /usr/sbin/slapd -d1 as this will display to
   screen and save you the trouble of searching your log files for problems.

   For improve security we suggest to use Phamm LDAP ACL definition if
   you do not use already ACL please copy examples/conf/phamm/phamm.acl
   in the same place of the slapd.conf (ex. /etc/ldap/ for Debian or
   /etc/openldap) otherwise comment the line below in your slapd.conf
   # include /etc/ldap/phamm.acl
   
   restart LDAP service

   1.2 Change phamm password

   Create the password you want for the cn phamm with slappasswd and
   amend it in the examples/ldif/sample-mail.ldif (the default is rhx)
   with cut & paste :).
   
   1.3 Populate

   ldapadd -v -x -D "cn=admin,dc=example,dc=tld" -W -h localhost -f examples/ldif/sample-main.ldif
   
   The password is the first one you created.

     1.3.1 populate plugin support

	 If you wish to use mail and DNS plugin:
	 
	 ldapadd -v -x -D "cn=admin,dc=example,dc=tld" -W -h localhost -f examples/ldif/sample-mail.ldif


2.	PHAMM CONFIGURATION
^^^^^^^^^^^^^^^^^^^^^^^

   2.1 Config files

   Create the main config file in phamm directory from the sample:
   
   	cp config.inc.example.php config.inc.php

   Then edit config.inc.php.

	  2.1.1 Config file (plugin support)

	  If you wish to use the plugin, please decomment each line you
	  want in $plugins[] lines

	  Example:

	  $plugins = array();
	  $plugins[] = "mail";
	  $plugins[] = "alias";
	  //$plugins[] = "ftp";

3. SETTING MAIL SERVICES
^^^^^^^^^^^^^^^^^^^^^^^^^^
There are a couple of excellent general examples of how to setup
postfix and courier below these should assist with a more detailed
discription of what you find below.

http://www.postfix.org/addon.html
http://www.faqs.org/docs/Linux-HOWTO/LDAP-Implementation-HOWTO.html#AEN747
http://alinux.washcoll.edu/docs/plc/postfix-courier-howto.html


   3.1 config postfix
	
	install postfix as a full internet email server, and then add the snips
	that are in the samples directory to the relevent parts of the postfix
	configuration files, remember to reload postfix after making the changes
	(most postfix configuration files are found in /etc/postfix)
	ensure the user vmail and the group vmail have been added. if not add them and
	remember the gid and uid as you need it here and in courier config
	
	don't forget to update your transport file and the transport.db file this is required.
	postmap /etc/postfix/transport

	test this by logging into smtp and sending a mail to yourself (then when you set up
	courier you should have the mail awaiting you) log with 
	/etc/init.d/postfix start; tail -f /var/log/mail.log


   3.2 config courier

	check that authdaemonrc is using ldap as a method to authenicate ie (authmodulelist=ldap), 
	add the snips from the samples folder to the relevent file (normally found in /etc/courier)
	these files are authldap (configuration of ldap server)
	
	test by logging into your pop or imap server and collecting the mail that you sent to your
	self in setting up postfix.
   
	/etc/init.d/courier-authdaemonrc start; tail -f /var/log/mail.log

   3.3 config amavis
	
	add the amavis sample data to your amavis.conf file. restart the services and check the 
	logs for dependancies)

   3.4 config gnarwl

	add the sample gnarwl.cfg snip to you gnarwl.cfg. (this normally lives in /etc/gnarwl.cfg)
	set debug to 3 and test. don't forget to set debug back again when working.
   
   3.5 cleaner.sh script

	Edit the cleaner.sh script to reflect the your ldap layout.
	
   Phamm does not really delete accounts. Phamm mark them as "Deleting".
   You can use tools/cleaner.sh to do this with crond.