translating some internal vmailmgr library messages
[squirrelmail.git] / plugins / change_password / README
CommitLineData
27663afe 1Master Change Password plugin
2-----------------------------
3
4WHAT'S THIS?
5This plugin is a general framework for enabling the user to
6change his/her password. It allows for different backend
7to perform this task on different systems.
8
9STATUS
10Development
11
fe90e5e4 12REQUIREMENTS:
13- SquirrelMail 1.4.3 or later. (plugin is included in squirrelmail
14 1.5.0 and later versions).
15- ldap backend needs php ldap extension. It might need php
16 mhash extension and system crypt libraries that support crypto
ffa25c5c 17 used on ldap server. It might need php ldap extension with ssl
18 support, if ldap server requires it.
fe90e5e4 19- mysql backend needs php mysql extension.
20- merak backend needs php curl extension.
21- poppass backend needs poppassd server that supports authentication
22 used by imap server.
23- vmailmgrd backend needs vmailmgr php library (vmail.inc) and
24 vmailmgrd service running on tcp port or unix socket.
25
27663afe 26CONFIGURATION
27Edit the file config.php to set the backend you want to use.
28Probably, you need to set some config vars in the backend too
29(backend/<yourbackend>.php).
30
31BACKENDS
02c81de4 32- ldap
33
34 Default settings are supplied in backends/ldap.php.
35
36 You don't have to change any configuration vars in
37 backend/ldap.php - instead, create an $cpw_ldap array in
38 config.php containing the variable you want to override.
39
40 See more information in "About ldap backend" chapter.
41
4165198d 42- mysql
43
44 Default settings are supplied in backends/mysql.php.
45
46 You do not have to change any configuration vars in
47 backend/mysql.php - instead, create an array in config.php
48 containing the variable you want to override, for example:
49
50 To override the server name ($mysql_server), you would add
51 $mysql['server'] = 'remote_servername';
52 to config.php.
53
27663afe 54
a391f3af 55- merak
27663afe 56
a391f3af 57 Default settings are supplied in backends/merak.php.
27663afe 58
59
a391f3af 60- poppassd
61
62 Default settings are supplied in backends/poppassd.php.
63
64
65- vmailmgrd
66
67 Default settings are supplied in backends/vmailmgrd.php.
68
69 Site configuration is controlled in config.php $vmailmgrd
70 array. Backend uses 'vmail_inc_path', 'vm_tcphost',
71 'vm_tcphost_port' and 'cpw_vmailmgrd_8bitpw' array keys.
72
73 'vmail_inc_path' sets path to vmail.inc. 'vm_tcphost' sets
74 vmailmgrd tcp service ip address or dns name. Plugin uses
75 vmailmgrd socket, if it is not set. 'vm_tcphost_port' sets
76 port of vmailmrgd service. Plugin uses port 322, if it is
77 not set. 'cpw_vmailmgrd_8bitpw' controls use of 8bit
78 passwords. If it is not set, interface does not allow new
79 passwords with 8bit symbols.
80
81 $vmailmgrd['vmail_inc_path'] setting is required.
82
02c81de4 83
a391f3af 84AUTHORS:
02c81de4 85ldap backend - Tomas Kuliavas <tokul@users.sourceforge.net>
86 used code from phpldapadmin and squirrelmail
87 ldapquery plugin.
a391f3af 88merak backend - Edwin van Elk <Edwin@eve-software.com>
89mysql backend - Thijs Kinkhorst <kink@squirrelmail.org>
90poppassd backend - Seth Randall <sethr@missoulafcu.org>
91vmailmgrd backend - Tomas Kuliavas <tokul@users.sourceforge.net>
27663afe 92
02c81de4 93------------------
94ABOUT LDAP BACKEND
95------------------
96 List of supported overrides
97 * 'server'
98 overrides address of ldap server. use any syntax that is supported
99 by your php ldap extension. Defaults to address of imap server.
100
101 * 'port'
102 overrides port of ldap server. Defaults to 389.
103
104 * 'basedn'
105 (required) ldap basedn used for binding to ldap server. Empty
106 string blocks use of backend. Defaults to empty string.
107
108 * 'connect_opts'
ffa25c5c 109 controls LDAP_OPT_* settings that are set with ldap_set_option()
110 function. See available options at http://www.php.net/ldap-set-option.
111 LDAP_OPT_ prefix must be omitted in $cpw_ldap['connect_opts']
112 overrides. No connection options are enabled by default.
113
114 You can use this option only when your ldap extension supports
115 ldap_set_option() function.
02c81de4 116
117 * 'use_tls'
118 enables or disables use of tls in ldap connection. Requires php
119 4.2+, php ldap extension with ssl support and PROTOCOL_VERSION => 3
120 setting in $cpw_ldap_connect_opts. Does not enable tls by default.
121
122 * 'binddn'
123 unprivileged binddn. should be able to search ldap directory and
124 find DN used by user. Uses anonymous bind, if set to empty string.
125 You should not use DN with write access to ldap directory here.
126 Defaults to anonymous bind.
127
128 * 'bindpw'
129 password used for unprivileged bind
130
131 * 'admindn'
132 bind DN that should be able to change password.
133 WARNING: usually user has enough privileges to change own password.
134 If you leave default value, plugin will try to connect with dn that
135 is detected in $cpw_ldap_username_attr=$username search and current
136 user password will be used for authentication.
137
138 * 'adminpw'
139 password for binding with 'admindn'
140
141 * 'userid_attr'
142 ldap attribute that stores username. Defaults to 'uid'
143
144 * 'default_crypto'
145 crypto that is used to encode new password. If set to empty string,
146 system tries to keep same encoding/hashing algorithm. Currently
147 backend supports:
148 - md5 - used name 'md5'. Implemented in standard php functions.
149 - smd5 - used name 'smd5'. Implemented in php mhash extension functions.
150 Minimal php version 4.0.4.
151 - sha - used name 'sha'. Implemented in php mhash extension functions.
152 - ssha - used name 'ssha'. Implemeted in php mhash extension functions.
153 Minimal php version 4.0.4.
154 - md5 crypt - used name 'md5crypt'. Uses php crypt function. Depends on
155 md5 support in system crypt libraries. Should work on linux glibc2 systems
ffa25c5c 156 and bsd systems.
02c81de4 157 - blowfish crypt - used name 'blowfish' Uses php crypt function. Depends on
ffa25c5c 158 blowfish support in system crypt libraries. Should work on bsd systems.
159 Is not supported by glibc 2.3.2.
02c81de4 160 - extended des crypt - used name 'extcrypt'. Uses php crypt function. Depends on
ffa25c5c 161 extended des support in system crypt libraries. Should work on bsd systems.
fe90e5e4 162 Is not supported by glibc 2.3.2.
02c81de4 163 - standard des crypt - used name 'crypt'. Uses php crypt function. Depends on
164 standard des support in system crypt libraries. Should work on libc systems
ffa25c5c 165 and bsd systems.
02c81de4 166 - plain text passwords - used name 'plaintext'
167
168 If you use admindn, plugin should support all encryption/hashing
169 algorithms used in your ldap server.
170
171 WARNINGS:
172 * don't enforce any crypto that is not supported by ldap server.
173 * don't enforce extcrypt, md5crypt or blowfish, if they are not supported
174 by ldap server and web server crypt libraries.
175
176 Safest setting options:
177 * If web server and ldap server is on same OS, make sure that mhash
178 extension is present in php.
179 * If web server and ldap server is on same OS and mhash extension is
180 not present, enforce md5 passwords or any crypt password algorithm
181 supported by your os. Remember that standard des crypt is limited
182 to eight symbols. Don't use admindn override, if ldap server
183 supports sha, ssha or smd5.
184 * If crypt libraries differ on web server and ldap server -
185 enforce md5 passwords or any crypt password algorithm supported by
186 web server and ldap server. Don't use admindn override, if ldap
187 server supports sha, ssha or smd5 and mhash extension is not
188 present.
189
190 Example:
191 $cpw_ldap['base_dn']='ou=users,dc=example,dc=com'; // sets base dn
192 $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3; // forces v3 bind protocol
193
194
27663afe 195$Id$