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

The Passwd module is a module that allows the user to change their own
password via a poppassd server, smbpasswd program, or 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.

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
       for Horde and courier.
     * a working smbpasswd program on the localhost.  It can access a
       remote server, but the smbpasswd binary must be on the 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 need to add an entry to the HORDE
   horde/config/registry.php file. 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
);


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. Crypt encrypted passwords

The Sha encryption will require the php mcrypt() extension!

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

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.

MDAEMON IMPLEMENTAION INFORMATION:
----------------------------------

This code should allow users to change their passwords for the windows mail
server program MDaemon.  The code uses semaphore files so it needs
read/write access to the mdaemon/app folder. It has only been tested with
local file access but network or any other location which fopen supports
should work. It was tested with mdaemon 5.0.4

