unneeded undercore in example

[squirrelmail.git] / plugins / change_password / README

Master Change Password plugin
-----------------------------

WHAT'S THIS?
This plugin is a general framework for enabling the user to
change his/her password. It allows for different backend
to perform this task on different systems.

STATUS
Development

REQUIREMENTS:
- SquirrelMail 1.4.3 or later. (plugin is included in squirrelmail 
  1.5.0 and later versions).
- ldap backend needs php ldap extension. It might need php
  mhash extension and system crypt libraries that support crypto
  used on ldap server. It might need php ldap extension with ssl
  support, if ldap server requires it.
- mysql backend needs php mysql extension.
- merak backend needs php curl extension.
- poppass backend needs poppassd server that supports authentication
  used by imap server.
- vmailmgrd backend needs vmailmgr php library (vmail.inc) and
  vmailmgrd service running on tcp port or unix socket. It also 
  requires SquirrelMail 1.4.4 or 1.5.1.

CONFIGURATION
Edit the file config.php to set the backend you want to use.

Backends can use special arrays that override default values set
in backend/<yourbackend>.php. Check description of backend that
you use.

BACKENDS
- ldap

  Default settings are supplied in backends/ldap.php.

  You don't have to change any configuration vars in
  backend/ldap.php - instead, create an $cpw_ldap array in 
  config.php containing the variable you want to override.

  See more information in "About ldap backend" chapter.

- mysql

  Default settings are supplied in backends/mysql.php.

  You do not have to change any configuration vars in 
  backend/mysql.php - instead, create an $cpw_mysql array in 
  config.php containing the variable you want to override, 
  for example:

  To override the server name ($mysql_server), you would add
    $cpw_mysql['server'] = 'remote_servername';
  to config.php.

  See more information in "About mysql backend" chapter.

- merak

  Default settings are supplied in backends/merak.php.

  Site configuration is controlled in config.php $cpw_merak
  array. You can use 'url','selfpage' and 'action' array
  keys to override default values.

  * 'url'
    override sets address of merak interface. URL is used 
    by webserver's libraries. If it points at localhost, 
    plugin tries to connect to administrative interface on
    same machine that hosts squirrelmail scripts.
    Defaults to 'http://localhost:32000/'.

  * 'selfpage'
    override sets page that is used to change password.
    Defaults to 'self.html'.

  * 'action'
    override sets action that is used during password change.
    Defaults to 'self_edit'.

  For example:
  $cpw_merak['url']='http://example.com:32000';


- poppassd

  Default settings are supplied in backends/poppassd.php.

  Site configuration is controlled in config.php $cpw_poppassd 
  array. You can use 'server' array key to override address
  of poppassd server. Backend uses address of imap server, if
  variable is set to empty string. It uses address of imap 
  server by default.

  For example:
  $cpw_poppassd['server'] = 'remote_servername';

- vmailmgrd

  Default settings are supplied in backends/vmailmgrd.php.
  
  Site configuration is controlled in config.php $cpw_vmailmgrd 
  array. Backend uses 'vmail_inc_path', 'vm_tcphost', 
  'vm_tcphost_port' and '8bitpw' array keys.
  
  'vmail_inc_path' sets path to vmail.inc. 'vm_tcphost' sets
  vmailmgrd tcp service ip address or dns name. Plugin uses 
  vmailmgrd socket, if it is not set. 'vm_tcphost_port' sets 
  port of vmailmrgd service. Plugin uses port 322, if it is 
  not set. '8bitpw' controls use of 8bit passwords. If it 
  is not set, interface does not allow new passwords with 
  8bit symbols.

  $cpw_vmailmgrd['vmail_inc_path'] setting is required.

  Tested configurations:
  - Linux Debian Woody, vmailmgr 0.96.9, stock Woody's courier-imap 
    with vmailmgr authentication module.


AUTHORS:
ldap backend      - Tomas Kuliavas <tokul@users.sourceforge.net>
                    used code from phpldapadmin and squirrelmail
                    ldapquery plugin.
merak backend     - Edwin van Elk <Edwin@eve-software.com>
mysql backend     - Thijs Kinkhorst <kink@squirrelmail.org>
poppassd backend  - Seth Randall <sethr@missoulafcu.org>
vmailmgrd backend - Tomas Kuliavas <tokul@users.sourceforge.net>

------------------
ABOUT LDAP BACKEND
------------------
  List of supported overrides
  * 'server'
    overrides address of ldap server. use any syntax that is supported 
    by your php ldap extension. Defaults to address of imap server.

  * 'port'
    overrides port of ldap server. Defaults to 389.

  * 'basedn'
    (required) ldap basedn used for binding to ldap server. If set to
    empty string, blocks use of backend. Defaults to empty string.

  * 'connect_opts'
    controls LDAP_OPT_* settings that are set with ldap_set_option() 
    function. See available options at http://www.php.net/ldap-set-option.
    LDAP_OPT_ prefix must be omitted in $cpw_ldap['connect_opts'] 
    overrides. No connection options are enabled by default.
    
    You can use this option only when your ldap extension supports 
    ldap_set_option() function.

  * 'use_tls'
    enables or disables use of tls in ldap connection. Requires php 
    4.2+, php ldap extension with ssl support and PROTOCOL_VERSION => 3 
    setting in $cpw_ldap_connect_opts. Does not enable tls by default.

  * 'binddn'
    unprivileged binddn. should be able to search ldap directory and 
    find DN used by user. Uses anonymous bind, if set to empty string.
    You should not use DN with write access to ldap directory here.
    Defaults to anonymous bind.

  * 'bindpw'
    password used for unprivileged bind

  * 'admindn'
    bind DN that should be able to change password.
    WARNING: usually user has enough privileges to change own password.
    If you leave default value, plugin will try to connect with dn that 
    is detected in $cpw_ldap_username_attr=$username search and current
    user password will be used for authentication.

  * 'adminpw'
    password for binding with 'admindn'

  * 'userid_attr'
    ldap attribute that stores username. Defaults to 'uid'

  * 'default_crypto'
    crypto that is used to encode new password. If set to empty string, 
    system tries to keep same encoding/hashing algorithm. Currently 
    backend supports:
    - md4 - used name 'md4'. Implemented in php mhash extension functions.
    - md5 - used name 'md5'. Implemented in standard php functions.
    - smd5 - used name 'smd5'. Implemented in php mhash extension functions. 
      Minimal php version = 4.0.4.
    - ripe-md160 - used name 'rmd160'. Implemented in php mhash extension functions.
    - sha - used name 'sha'. Implemented in php mhash extension functions 
      and php 4.3.0+ sha1() function. mhash extension is used only when 
      sha1() function is unavailable.
    - ssha - used name 'ssha'. Implemented in php mhash extension functions.
      Minimal php version = 4.0.4.
    - md5 crypt - used name 'md5crypt'. Uses php crypt function. Depends on
      md5 support in system crypt libraries. Should work on linux glibc2 systems
      and bsd systems.
    - blowfish crypt - used name 'blowfish'. Uses php crypt function. Depends on
      blowfish support in system crypt libraries. Should work on bsd systems. 
      Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
    - extended des crypt - used name 'extcrypt'. Uses php crypt function. Depends on
      extended des support in system crypt libraries. Should work on bsd systems.
      Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
    - standard des crypt - used name 'crypt'. Uses php crypt function. Depends on
      standard des support in system crypt libraries. Should work on libc systems
      and bsd systems.
    - plain text passwords - used name 'plaintext'.

    If you use admindn, plugin should support all encryption/hashing 
    algorithms used in your ldap server.

    WARNINGS:
    * don't enforce any crypto that is not supported by ldap server, if admindn 
      override is not used in backend configuration.
    * don't enforce extcrypt, md5crypt or blowfish, if they are not supported 
      by ldap server and web server crypt libraries.

    Safest setting options:
    * If web server and ldap server is on same OS, make sure that mhash 
      extension is present in php.
    * If web server and ldap server is on same OS and mhash extension is 
      not present, enforce md5 passwords or any crypt password algorithm 
      supported by your os. Remember that standard des crypt is limited
      to eight symbols.  Don't use admindn override, if ldap server 
      supports md4, rmd160, sha, ssha or smd5.
    * If crypt libraries differ on web server and ldap server -
      enforce md5 passwords or any crypt password algorithm supported by
      web server and ldap server. Don't use admindn override, if ldap 
      server supports md4, rmd160, sha, ssha or smd5 and mhash extension 
      is not present.

  Configuration example:
  $cpw_ldap['basedn']='ou=users,dc=example,dc=com'; // sets base dn
  $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3;   // forces v3 bind protocol

  Tested configurations:
  - Linux Debian Sarge, OpenLDAP v.2.1.30, Qmail LDAP 20050401a, courier-imap 
    v.3.0.8 using qmail-ldap auth-imap authentication. ns-mta-md5 crypto is not
    implemented in backend. 

-------------------
ABOUT MYSQL BACKEND
------------_------
  List of supported overrides:
  * 'server'
    address of MySQL server. Defaults to localhost.

  * 'database'
    database that stores user information. Defaults to 'email'.

  * 'table'
    database table that stores user information. Defaults to 'users'.

  * 'userid_field'
    field that stores user's ID. Defaults to 'id'.

  * 'password_field'
    field that stores password. Defaults to 'password'.

  * 'manager_id'
    username that is used to log into MySQL with (must have rights).
    Defaults to 'email_admin'.

  * 'manager_pw'
    password that is used to log into MySQL.

  * 'saslcrypt'
    boolean value that controls use of SASL (MySQL) crypt in passwords.
    It is not enabled by default.

  * 'unixcrypt'
    boolean value that controls use of unix crypt() in passwords. 
    Setting is ignored, if saslcrypt is enabled. It is not enabled 
    by default. 

If saslcrypt and unixcrypt are not enabled, plugin defaults to plaintext 
passwords.

$Id$