
INTRODUCTION
------------

The Passwd module is a module that allows the user to change their own
password.  It supports various password changing backends including
poppassd server, smbpasswd program, expect script, exim sql, and ldap
server (for courier+ldap installations).

Note that poppassd uses clear text password transmissions.  This can be
considered somewhat safe if the server is on the same machine and the
connection uses the loopback (localhost) interace.  It is up to the
installer to evaluate the security implications of using this module
with poppassd servers.

Note that setting this module to allow guest access might also be
considered a security risk.  By default, guest access is disabled.
It is up to the installer to evaluate the security implications of
using this module with guest access if they so choose.

PREREQUISITES
-------------

The following prerequisites are REQUIRED.

  1. A successful Horde 2.x installation and all which that entails.

  2. One of:
     * a poppassd server installed, running, and working on a system
     * a ldap server installed, running, and working for authentication.
     * a working smbpasswd program on the localhost.  It can access a
       remote server, but the smbpasswd binary must be on the localhost.
     * a working sql authentication system
     * expect installed, and access to telnet or ssh to the machine 
       where passwords are stored/set (could be localhost).


INSTALLING PASSWD
-----------------

Passwd is intended to be installed inside the Horde package directory.

Since Passwd is written in PHP, there is no compilation necessary;
simply expand the distribution where you want it to reside (normally
into a directory inside the Horde directory).

For example, with the Apache webserver's default document
root of '/usr/local/apache/htdocs'  and your Horde install in a directory
under that called 'horde' you would type:

   cd /usr/local/apache/htdocs/horde
   tar zxvf /path/to/passwd.tgz

CONFIGURING PASSWD
------------------

1. We assume that you already have a working Horde installation.

2. Configuring Passwd

   To configure passwd, change to the config/ directory of the
   installed distribution, and make copies of all of the configuration
   "dist" files without the "dist" suffix:

      cd config/
      for foo in *.dist; do cp $foo `basename $foo .dist`; done

   Documentation on the format of those files can be found in each
   file; open each in an editor and make changes as suggested within.
   The default values are reasonable, but may not be appropriate for
   your site.  In particular if you use realms or virtual hosts you
   will need to change the configuration substantially.

3. Configuring Horde

   To make Passwd appear in Horde, you may need to add an entry to the Horde
   horde/config/registry.php file. If so, you want to add a section that looks
   like:

$this->applications['passwd'] = array(
    'fileroot' => dirname(__FILE__) . '/../passwd',
    'webroot' => $this->applications['horde']['webroot'] . '/passwd',
    'icon' => $this->applications['horde']['webroot'] . '/passwd/graphics/lock.gif',
    'name' => _("Password"),
    'allow_guests' => false,
    'show' => true,
    'status' => 'active'
);


4. Optional Configuration of IMP

   If you have IMP installed, and want to include Passwd in the IMP menu
   bar, you can add the application to IMP as well.  Edit the file
   horde/imp/config/conf.php and include 'passwd' in the list of menu apps,
   for example, it might look like the following:

   $conf['menu']['apps'] = array('turba','passwd');

OBTAINING SUPPORT
-----------------

There is a mailing list for support:
  sork@lists.horde.org

You can subscribe or view the archives at:
  http://lists.horde.org/mailman/listinfo/sork/


CREDITS
-------

See the seperate CREDITS file under the docs/ directory.

POPPASSD SERVER SOFTWARE
------------------------

The following are some links that users have submitted.  No warrenty
is made for the following links or any software obtained from then.  These
are all user submitted links, and have not been tested or verified.  Use
these links are your own risk!

http://www.ceti.com.pl/~kravietz/prog.html
http://www.samera.net/rpm/
http://netwinsite.com/poppassd/
http://echelon.pl/pubs/poppassd-1.8.1.tar.gz

LDAP IMPLEMENTATION INFORMATION:
--------------------------------

The module now includes experimental support for changing ldap stored
passwords.

LDAP can store passwords in multiple ways, namely:

  a. Plain text passwords
  b. SHA encrypted passwords
  c. SSHA encrypted passwords
  d. Crypt encrypted passwords
  e. MD5 encrypted passwords (using base64 encoding - md5-base64)
  f. SMD5 encrypted passwords

The SHA, SSHA, MD5, and SMD5 encryption types will require the php mhash
extension!  To enable this you must compile php with the --with-mhash[=DIR]
parameter to enable this extension. DIR is the mhash install directory.

Crypt cannot handle passwords longer than eight characters (it accepts them
but truncates them at 8 characters).  If you want to use longer passwords,
you may use SHA. Unfortunately, LDAP does not support salted SHA, so the
hash is the same for every call of the encryption function.

The user must be able to authenticate to the ldap directory and change
his own password now (we no longer do root access to ldap).
This assumes that the ldap administrator has allowed everyone to write
their own password, something like:

access to attribute=userPassword
       by self write
       by anonymous auth
       by * none

SQL IMPLEMENTATION INFORMATION:
-------------------------------

The module now includes experimental support for changing passwords stored
in a SQL database.  The SQL driver is similar to the ldap driver except that
it also supports MD5 encryption using hex encoding (md5-hex).  If you created
your passwords using the PHP md5() function then use md5-hex.

SMBPASSWD IMPLEMENTAION INFORMATION:
------------------------------------

To use this module, you must pass the address of your smb domain controller
on which to change the password.  This can be "localhost" for the server
that Horde runs on.  The remote system name may be passed as the NETBIOS
name, the DNS name,  or the IP address of the SMB/CIFS server to connect to.
The username is run through escapeshellcmd, so any usernames with strange
characters ($, &, etc) may not work.  I'm not sure if any of these are
even valid for smb/cifs authentication, but if so, they may not work in
this module...

Note  that if changing a Windows NT Domain password the remote machine
specified must  be  the  Primary Domain  Controller  for  the  domain
(Backup Domain Controllers only have a read-only copy of the  user
account  database  and  will not allow the password change).

Since  smbpasswd works in client-server mode communicating with a
local smbd for a non-root user then the smbd daemon must  be  running
for this to work. A common problem is to add a restriction to the
hosts that may access  the   smbd running  on  the local machine by
specifying a allow hosts or deny hosts entry in the smb.conf file
and neglecting to allow "localhost" access to the smbd.

In addition, the smbpasswd command is only useful if Samba has been
set up to use encrypted passwords.

EXPECT SCRIPT INFORMATION:
--------------------------
This code allows users to change their passwords via an expect script.
Requires the expect program and a telnet or ssh program.  You may need
to change some of the expect patterns in scripts/passwd_expect such
as the badpassword_string.

$Horde: passwd/docs/INSTALL,v 1.1.1.1.2.6 2003/05/02 03:22:16 ericr Exp $
