php-src/ext/vpopmail

Minimum Survial Readme

VPOPMAIL SPECIFIC ISSUES
-------------------------------------------------------------------------------

assume
	qmail is installed in /var/qmail
	vpopmail in ~vpopmail
	qmail-send runs as qmails


different parts of vpopmail require certain user id (uid) and
group id (gid) in order to operate normally.

brief list with requirements:

adddomain
deldomain
addaliasdomain
	read/write permissions on
	/var/qmail/users/ assing, assign.lock, cdb

	read/write permissions on
	/var/qmail/control/*

	singnal qmail-send with SIGHUP (uid==qmails or root)

	read/write permissions on
	~vpopmail/domains

	optionally read/write to cdb vpopmail databases

adduser
deluser
	read/write permissions on
	~vpopmail/domains/<givendomain> (or the default domain)

	optionally read/write to cdb vpopmail databases

passwd
	optionally read/write on
	~vpopmail/domains/<givendomain>/<givenuser>
	(only when sqwebmail is configured)

setuserquota
	optionally read/write to cdb vpopmail databases

auth_user
	optionally read from cdb vpopmail databases

POSSIBLE SCENARIOS
-------------------------------------------------------------------------------

php is in cgi mode

	command line invocation

	web server cgi invocation

php is web server module


in command line mode the php interpreter may be run from vpopmail uid to
administer users, etc. or as root to add/del domains - this is the easiest case

in cgi mode proper uid may be provided eighter by suid php interpreter or
using cgi exec wrapper. the same restrictions as in command line mode apply

the web server module mode is the most powerful and works much faster that cgi.
in this mode more restrictions apply because web server's uid at least must
be able to read/write the directories of the manages domains.

first scenario only allows web scripts to manage certain domains.  security 
may be compromised if there are user webs under the same web server
with allowed script execution.

second scenario is to setup web server and vpopmail under the same uid/gid.
thus allowing only user management in all domains.

third scenario extends second with the ability to manage domains. generally
from security reasons it is not a good idea to run such a system on a server
with shell users - vpopmail's domain admin tools must be suid root to work
properly and most users will be able to add/delete domains.

it is not considered a good idea to run web servers as root. hence the need
to suid vpopmail domain management tools and exec them insted using native api.
native api for domains is only suitable for cgi/command line mode, when php is
run through suid root wrapper or suid itself.

almost all scenarios lack secutiry in different ways - eighter powerful tools
get suid root or parts of vpopmail setup become useable by any system user
or web users with cgi/php access may utilize vpopmail api for mail management.

perhapse the most secure solution is to run a separate apache server under
the vpopmail user and chmod 700 ~vpopmail/bin.

FREQUENTLY USED CONFIGURATION STEPS
-------------------------------------------------------------------------------

changing existing vpopmail uid/gid is possible but not easy - 
take these into account:

#1 - backup your setup, mail and configuration!

	stop qmail-send before doing any changes
	else your mail in process may get bounced or 
	deleted or delivered to a default destination or...

	stop pop3/imap remote/local users - while changing uids
	users cannot check their mail

	you may leave smtp - qmail-inject will take care
	no matter vpopmail setup is broken (if and only
	if you have stopped qmail-send)

	in rc.d scripts tcpserver uid/gid may need to be changed

	reconfiguring vpopmail:
		./configure ....your opts plus new uid/gid....

	remember to
		make clean all install
	in vpopmail src tree; clean is needed if vpopmail has already been
	configured with another uid/gid - vpopmail's dependencies are not
	intact after reconfigure

	after these steps change the uid/gid in
		/var/qmail/users/assign
	compile the assign file. the dummies way is to
		vadddomain mydummy.domain aaaa
		vdeldomain mydummy.domain

	suid root vadddomain, vdeldomain and vaddaliasdomain
	(this is only needed for domain management in web server module)
		cd ~vpopmail/bin
		chown 0.0 vadddomain vdeldomain vaddaliasdomain
		chmod +s vadddomain vdeldomain vaddaliasdomain

	optionally secure ~vpopmail/bin
	(beware these programs may be exploitable or at least used)
		chmod 700 ~vpopmail/bin

	run qmail-send
		/bin/csh -cf '/var/qmail/rc &'
		
	run pop3 tcpserver or what you are using

	verify your setup

#2 verify php vpopmail module and configuration

	for web server module and cgi setups create a phpinfo page:

	<?php phpinfo() ?>

	for command line mode run
		php -i

	check for vpopmail section in result

	verify that php euid/egid match vpopmail's

	in setups where only certain domain users will be administrated
	verify that php euid/egid can access their respective directories

FUNCTION PROTOTYPES
-------------------------------------------------------------------------------

bool vpopmail_add_domain(string domain, string dir, int uid, int gid)
bool vpopmail_del_domain(string domain)
bool vpopmail_add_alias_domain(string domain, string aliasdomain)
bool vpopmail_add_domain_ex(string domain, string passwd [, string quota [, string bounce [, bool apop]]])
bool vpopmail_del_domain_ex(string domain)
bool vpopmail_add_alias_domain_ex(string olddomain, string newdomain)
bool vpopmail_add_user(string user, string domain, string password[, string gecos[, bool apop]])
bool vpopmail_del_user(string user, string domain)
bool vpopmail_passwd(string user, string domain, string password)
bool vpopmail_set_user_quota(string user, string domain, string quota)
bool vpopmail_auth_user(string user, string domain, string password[, string apop])
bool vpopmail_alias_add(string user, string domain, string alias)
bool vpopmail_alias_del(string user, string domain)
bool vpopmail_alias_del_domain(string domain)
array vpopmail_alias_get(string alias, string domain)
string vpopmail_error(void)


CONTACT INFO
-------------------------------------------------------------------------------

your comments, fixes and stuff are welcome
Boian Bonev <boian@bonev.com>

$Id$