==================
 Upgrading Passwd
==================

:Contact: dev@lists.horde.org

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


General instructions
====================

These are instructions to upgrade from earlier Passwd versions.

Upgrading Passwd is as easy as running::

   pear upgrade -a -B horde/passwd

If you want to upgrade Passwd with all binary dependencies, you need to remove
the ``-B`` flag. Please note that this might also try to install PHP extensions
through PECL that might need further configuration or activation in your PHP
configuration::

   pear upgrade -a horde/passwd

If you want to upgrade to an alpha or beta version of Passwd, you need to tell
the PEAR installer to prefer non-stable package versions. Please note that this
might also install pre-release 3rd-party PEAR packages::

   pear -d preferred_state=alpha upgrade -a horde/passwd

If you want to upgrade from a Passwd version prior to 4.0, please follow the
instructions in INSTALL_ to install the most recent Passwd version using the
PEAR installer.

After updating to a newer Passwd version, you **always** need to update
configurations. Log in as an administrator, go to Administration =>
Configuration and update anything that's highlighted as outdated.


Upgrading to Passwd 5.0.2
=========================

Hooks Configuration (hooks.php)
-------------------------------

The 'userdn' hook has been re-added.



Upgrading to Passwd 5.0
=======================

NOTE: If changing a password that is currently being used to authenticate to
Horde, you CANNOT continue to use Horde after changing the authentication
password. Instead, you MUST configure backends.local.php to logout of Horde
after a successful password change (see the logout parameter in
``config/backends.php``). The old authentication credentials may be cached in
various Horde applications, and there is no way to clear this cache unless the
session is destroyed.

Backend Configuration (backends.php)
------------------------------------

The following options have been added::

   logout

The following options have been removed::

   no_reset

Hooks Configuration (hooks.php)
-------------------------------

The 'default_username' hook no longer receives a $user parameter.

The 'userdn' hook has been removed. It can now be configured using the
'userdn' parameter in the LDAP driver configuration.


Upgrading to Passwd 4.0
=======================

Backend Configuration (backends.php)
------------------------------------

The 'password policy' setting in backends.php has been renamed to 'policy'.


Upgrading to Passwd 3.1
=======================

Application Hooks
-----------------

All hooks that are specific to Passwd have been moved from the
``horde/config/hooks.php`` file. Move your existing Passwd Hooks from there to
``passwd/config/hooks.php``.


New Hook Parameters
-------------------

The _passwd_hook_username hook is now passed an additional parameter, the
Passwd_Driver_* object for the backend that you are changing the password on.
This allows Passwd to support users being able to change passwords on multiple
backends even when the different backends may have different requirements for
the username (such as one requiring'user@example.com' while another only
requiring 'user'). Additionally, the Passwd_Driver_composite driver also
supports this functionality by checking for the existence of a parameter
called 'be_username' in each of it's sub-drivers. If this parameter is
present, its value overrides any other value of $userid it is passed. If you
wish to use this functionality of the composite driver, look at the example
_passwd_hook_username function in horde/config/hooks.php.dist.


.. _INSTALL: INSTALL
