Hi,

Here are some notes for you to write authentication module for openwebmail.
We assume the module you want to write is auth_XYZ

ps: A simplest way is to modify an existing one to fit your requirement.


filename
---------
The file name should be auth_XYZ.pl, XYZ could be A-Za-z and _


location
--------
This auth_XYZ.pl should be put at the same directory 
as other auth module is.


package name
------------
The package name for this module is openwebmail::auth_XYZ
The first line of auth_XYZ.pl should be

package openwebmail::auth_XYZ;


functions
----------
An auth module should have the following 4 API routines

get_userlist
get_userinfo
check_userpassword
change_userpassword

All functions follow this form

($retcode, $errmsg, retvals...)=routine($r_config, parameters);
where:
	$retcode:  0 means ok, else means error
	$errmsg:   message for sysadm, it will be logged to openwebmail.log
                   this won't be displayed to user
	$r_config: reference of the system config hash %config

#  0 : ok
# -2 : parameter format error
# -3 : authentication system/internal error
# -4 : user doesn't exist
($retcode, $errmsg, realname, uid, gid, homedir)=get_userinfo($r_config, $user);

#  0 : ok
# -1 : function not supported
# -3 : authentication system/internal error
($retcode, $errmsg,$userlist)=get_userlist($r_config);

#  0 : ok
# -2 : parameter format error
# -3 : authentication system/internal error
# -4 : password incorrect
($retcode, $errmsg)=check_userpassword($r_config, $user, $password)

#  0 : ok
# -1 : function not supported
# -2 : parameter format error
# -3 : authentication system/internal error
# -4 : password incorrect
($retcode, $errmsg)=change_userpassword($r_config, $user, $oldpassword, $newpassword)


globals
---------
Openwebmail can run in persistent mode, 
so you have to be very careful about the global variables.

1. initialize all globals explicitly

2. it would be even better to use global as constent only

3. don't write code outside routines, 
   or they will be executed once in persistent mode

4. if you auth module has to chat with remote server,
   please do all the following thing in each of the 4 API routines

   open the connection, 
   chat with server, 
   close connection

   This is the simplest way, and it can avoid the problem of lost connection
   or server rebooting.
   Openwebmail will cache the userinfo for each session. In most case, each user
   session will need send only one request to auth server.

5. if you really need global variables, please remember
   value of global variables will be kept forever when running in persistent mode

6. if you hope to save some connections to your auth server:

   a. you can use global variable to store connection handle
      but please don't do thing outside routines.

   b. all of the 4 API routines should have the capability

      1. if the connection has not been initialized
         => initialize the connection handle
      2. if the connection is lost or dead
         => free old/stale connection handle
            reinitialize the connection handle

7. The signal handler for child process $SIG{CHLD} may have been set 
   before calling the API routines, if your routine will fork new process, 
   you may need to disable the handler temporarily by putting the following
   line in the routine

   local $SIG{CHLD}; undef $SIG{CHLD}


More about persistent CGI
-------------------------
1. a persistent CGI process serves one request at a time,
   if more than one request come, more processes are forked

2. a persistent CGI process won't end after a request is completed,
   it waits for a new request and the global variable will be kept 
   across requests.

3. Normally, a persistent perl CGI runs under main:: package
   Just the same as pure CGI

4. But SpeedyCGI has a group mode which puts servers CGIs into one process,
   each CGI is running under a package other than main::, 

   And here are the differences in group mode:

   a. one resident perl process can be used to wait requests for different CGIs

   b. you can not access variable with prefix like  $main:: or $::.

   c. Different CGI may share one copy of packages during differnt time
      So if package use global vraible to store state, 
      the global may be changed or used by different CGIs