=======================
 Installing Passwd 3.0
=======================

:Last update:   $Date: 2009/06/10 08:20:39 $
:Revision:      $Revision: 1.31.2.4 $
:Contact:       sork@lists.horde.org

.. contents:: Contents
.. section-numbering::

This document contains instructions for installing the Passwd Password
Changing Application.

For information on the capabilities and features of Passwd, see the file
README_ in the top-level directory of the Passwd distribution.


Obtaining Passwd
==================

Passwd can be obtained from the Horde website and FTP server, at

   http://www.horde.org/passwd/

   ftp://ftp.horde.org/pub/passwd/

Or use the mirror closest to you:

   http://www.horde.org/mirrors.php

Bleeding-edge development versions of Passwd are available via CVS; see the
file `horde/docs/HACKING`_ in the Horde distribution, or the website
http://www.horde.org/source/, for information on accessing the Horde CVS
repository.


Prerequisites
=============

To function properly, Passwd **requires** the following:

1. A working Horde installation.

   Passwd runs within the `Horde Application Framework`_, a set of common
   tools for Web applications written in PHP.  You must install Horde before
   installing Passwd.

   .. Important:: Passwd 3.0 requires version 3.0+ of the Horde Framework -
                  earlier versions of Horde will **not** work.

   .. _`Horde Application Framework`: http://www.horde.org/horde/

   The Horde Framework can be obtained from the Horde website and FTP server,
   at

      http://www.horde.org/horde/

      ftp://ftp.horde.org/pub/horde/

   Many of Passwd's prerequisites are also Horde prerequisites.

   .. Important:: Be sure to have completed all of the steps in the
                  `horde/docs/INSTALL`_ file for the Horde Framework before
                  installing Passwd.

2. The following PHP capabilities, depending on the drivers you want use:

   a. Character Type support ``--enable-ctype``

   b. LDAP support ``--with-ldap`` [OPTIONAL]

      LDAP support is required for the kolab, ldap, and smbldap drivers.

   c. Mhash support ``--with-mhash`` [OPTIONAL]

      Mhash support is necessary for the smbldap driver.  See `LDAP
      Implementation Information`_ for details.

   d. Mcrypt support ``--with-mcrypt`` [OPTIONAL]

      Mcrypt support is necessary for the smbldap driver.  See `LDAP
      Implementation Information`_ for details.

   e. SOAP support ``--enable-soap`` [OPTIONAL]

      SOAP support is necessary for the soap driver.

3. The following PEAR modules:
   (See `horde/docs/INSTALL`_ for instructions on installing PEAR modules)

   a. Crypt_CHAP [OPTIONAL]
  
      Passwd uses this package to encrypt passwords for the smbldap driver.

The following items might be required, depending on the drivers you want to
use:

1. A poppassd server installed, running, and working on a system.

2. An LDAP server installed, running, and working for authentication.

3. A working smbpasswd program on the web server.  It can access a remote
   server, but the smbpasswd binary must be installed on the local system.

4. A working SQL authentication system.

5. Expect installed, and access to telnet or ssh to the machine where
   passwords are stored/set (could be localhost).

6. A SOAP service endpoint.


Installing Passwd
===================

Passwd is written in PHP, and must be installed in a web-accessible directory.
The precise location of this directory will differ from system to system.
Conventionally, Passwd is installed directly underneath Horde in the web
server's document tree.

Since Passwd is written in PHP, there is no compilation necessary; simply
expand the distribution where you want it to reside and rename the root
directory of the distribution to whatever you wish to appear in the URL.  For
example, with the Apache web server's default document root of
``/usr/local/apache/htdocs``, you would type::

   cd /usr/local/apache/htdocs/horde
   tar zxvf /path/to/passwd-x.y.z.tar.gz
   mv passwd-x.y.z passwd

and would then find Passwd at the URL::

   http://your-server/horde/passwd/


Configuring Passwd
====================

1. Configuring Horde for Passwd

   a. Register the application

      In ``horde/config/registry.php``, find the ``applications['passwd']``
      stanza.  The default settings here should be okay, but you can change
      them if desired.  If you have changed the location of Passwd relative to
      Horde, either in the URL, in the filesystem or both, you must update the
      ``fileroot`` and ``webroot`` settings to their correct values.

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

   Or on Windows::

      copy *.dist *.

   Documentation on the format and purpose of those files can be found in each
   file.  You may edit these files if you wish to customize Passwd's
   appearance and behavior.  With one exception (``backends.php``) the
   defaults will be correct for most sites.

   You must login to Horde as a Horde Administrator to finish the
   configuration of Passwd.  Use the Horde ``Administration`` menu item to get
   to the administration page, and then click on the ``Configuration`` icon to
   get the configuration page.  Select ``Password`` from the selection list of
   applications.  Fill in or change any configuration values as needed.  When
   done click on ``Generate Password Configuration`` to generate the
   ``conf.php`` file.  If your web server doesn't have write permissions to
   the Passwd configuration directory or file, it will not be able to write
   the file.  In this case, go back to ``Configuration`` and choose one of the
   other methods to create the configuration file ``passwd/config/conf.php``.

   Note for international users: Passwd uses GNU gettext to provide local
   translations of text displayed by applications; the translations are found
   in the ``po/`` directory.  If a translation is not yet available for your
   locale (and you wish to create one), see the ``horde/po/README`` file, or
   if you're having trouble using a provided translation, please see the
   `horde/docs/TRANSLATIONS`_ file for instructions.

3. Testing Passwd

   Once you have configured Passwd, bring up the included test page in your
   Web browser to ensure that all necessary prerequisites have been met.  See
   the `horde/docs/INSTALL`_ document for further details on Horde test
   scripts.  If you installed Passwd as described above, the URL to the test
   page would be::

      http://your-server/horde/passwd/test.php


Security considerations
=======================

.. Note:: Some drivers like poppassd always use clear text password
          transmissions.  Others may also use clear text passwords (e.g. the
          expect script driver using telnet rather than ssh).  This can be
          considered somewhat safe if the server is on the same machine, there
          are no user interactive logins allowed on that machine, and the
          connection uses the loopback (localhost) interface.  It is up to the
          administrator to evaluate the security implications of using this
          module, and to understand the security implications of how their
          server and this module is configured.

.. Note:: 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 administrator to evaluate the security implications of using
          this module with guest access if they choose to do so.


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 includes 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 smbldap extension require the php mhash and mcrypt extensions.  To
enable these you must compile php with the ``--with-mhash[=DIR]`` and
``--with-mcrypt[=DIR]`` parameters. ``DIR`` is the mhash or mcrypt
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.

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 includes 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 Implementation Information
====================================

To use this module, you must pass the address of your Samba 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:: 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, 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.  The
module 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`` or ``success_string`` (as only two examples).

For security reasons, it is generally suggested to use ssh rather than telnet
for the transport, if possible.


Expect PECL Information
=======================

This code allows users to change their passwords via the PHP PECL expect
extension. It requires the PECL expect extension and a ssh program.

You can find the extension on http://pecl.php.net/package/expect


Obtaining Support
=================

If you encounter problems with Passwd, help is available!

The Horde Frequently Asked Questions List (FAQ), available on the Web at

  http://www.horde.org/faq/

The Horde Project runs a number of mailing lists, for individual applications
and for issues relating to the project as a whole.  Information, archives, and
subscription information can be found at

  http://www.horde.org/mail/

Lastly, Horde developers, contributors and users may also be found on IRC,
on the channel #horde on the Freenode Network (irc.freenode.net).

Please keep in mind that Passwd is free software written by volunteers.  For
information on reasonable support expectations, please read

  http://www.horde.org/support.php

Thanks for using Passwd!

The Passwd team


.. _README: ?f=README.html
.. _`horde/docs/HACKING`: ../../horde/docs/?f=HACKING.html
.. _`horde/docs/INSTALL`: ../../horde/docs/?f=INSTALL.html
.. _`horde/docs/TRANSLATIONS`: ../../horde/docs/?f=TRANSLATIONS.html