=================
 Upgrading Horde
=================

:Contact: horde@lists.horde.org


These are instructions to upgrade from earlier Horde versions. Please backup
your existing data before running any of the steps described below. You can't
use the updated data with your old Horde version anymore.

After updating to a newer Horde version, or a newer version of **any** Horde
application, you **always** need to update configurations and database
schemes. Log in as an administrator, go to Administration => Configuration and
update anything that's highlighted as outdated.


Upgrading Horde from 3.3.x to 4.x
=================================


New configuration scheme
------------------------

With Horde 4 it is no longer necessary to create any configuration files
besides ``conf.php`` files. The default configuration files in the ``config/``
directory should work for most systems. If some changes in those files are
necessary, don't edit the files directly or your changes will be lost with the
next upgrade. Create ``*.local.php`` files instead and only add configuration
settings that you want to change from the default values there. See the header
of the configuration files for details and examples.

``conf.php`` files are still created and updated as usual through the
configuration interface.


New database migrations
-----------------------

With Horde 4 database updates are no longer done by running SQL scripts through
your database server's console or web frontend. A migration framework has been
created instead that can be used through the web interface and a command line
script.

After updating, log in to Horde as an adminstrator, make sure that all
configurations are up-to-date, then click on the ``Update all DB schemas``
button. You can also update the database schemas individually if necessary.

Alternatively there is a command line script ``bin/db_migrate`` that can be
used for upgrading the database schemas. Call it without any parameters to
upgrade schemas for all installed applications and components, or specify the
application, component, or ``migration/`` directory that you want to upgrade
individually.


PostgreSQL
----------

If using PostgreSQL, you must upgrade the value column of the preference table
from TEXT to BYTEA. The necessary SQL statement is found at::

    scripts/upgrades/2009-04-13_horde_pgsql_upgrade.sql


Configuration changes
---------------------

Many configuration names and values have changed. It is suggested that you
start with a fresh configuration instead of trying to import some existing
configuration from Horde 3.


Preferences
-----------

The following preferences are no longer used and can be removed from the
horde_prefs table if you want to save database storage:

    * confirm_maintenance
    * do_maintenance
    * editor_plugins
    * last_maintenance


Hooks
-----

The hooks format has been changed completely. ``hooks.php`` no longer contains
separate functions for each hook, but a single class with separate methods for
each hook. Please take a look at the new examples in ``hooks.php.dist`` before
porting any hooks to Horde 4. Some hook signatures have changed, some hooks
have been renamed, removed or added.

Noteably the following hooks have changed:

    * "preauthenticate" (Parameters and return value have changed)
    * "postauthenticate" (Parameters and return value have changed)
    * "username_tobackend", "username_frombackend" (Have been combined and
      renamed to "authusername")
    * There are only two methods prefs_init() and prefs_change() for all
      preferences.


Alarms
------

The alarm system is using UTC dates now. This can cause problems for a short
time after updating to Horde and before the alarms have been refreshed. To
avoid any problems you should empty the horde_alarms table after upgrading
manually. This SQL query should work::

    DELETE FROM horde_alarms


PEAR packages
-------------

The Crypt_Blowfish package is required now. If you installed Horde using the
PEAR installer, it will be installed automatically though.


Removed features
----------------

* Database abstraction has been moved to a new Horde_Db component. Any database
  support beside MySQL (native and PDO), PostgreSQL, and SQLite have been
  removed. If you need support for any other RDBMS, consider sponsoring the
  development of new drivers for that system.
* The krb5 authentication driver has been removed.
* The LDAP session handler has been removed.
* The enscript and webcpp MIME Viewers have been replaced by the
  'Syntaxhighlighter' driver.


Upgrading Horde from 3.3.x to 3.3.5
===================================

The signup_email column of the horde_signups table is no longer needed. You
can execute the provide SQL script to remove that column, e.g.::

   mysql --user=root --password=<MySQL-root-password> <db name> < scripts/upgrades/3.3_to_3.3.5.sql


Upgrading Horde from 3.2.x to 3.3.x
===================================

The sequence name for the SQL share driver has been changed from 'sequence' to
'id' You must execute the provided PHP script to update your database::

    php scripts/upgrades/2008-08-29_fix_mdb2_sequences.php

Note that this upgrade will require you to have the PEAR MDB2_Schema package
installed on your system::

    pear install MDB2_Schema


Upgrading Horde from 3.1.x to 3.2.x
===================================


SQL Backends
------------

A few new tables have been added to Horde.

Execute one of the provided SQL scripts to update your data to the new Horde
version, e.g.::

   mysql --user=root --password=<MySQL-root-password> <db name> < scripts/upgrades/3.1_to_3.2.mysql.sql


Beta SQL Drivers
----------------

There are now beta-level SQL drivers for Groups, Shares, and
Permissions. There is a script
``horde/scripts/upgrades/convert_datatree_perms_to_sql.php`` that will migrate
all of your DataTree-based permissions to the SQL backend, and
``horde/scripts/upgrades/convert_datatree_groups_to_sql.php`` that will
migrate groups. For shares, you will need to upgrade each application
individually. Applications that use shares have entries in ``docs/UPGRADING``
and upgrade scripts ``scripts/upgrades/convert_datatree_shares_to_sql.php``
for creating the SQL share tables and migrating data.

The SQL drivers should perform much better than the DataTree versions,
but they have not received the same level of testing, thus the beta
designation.


Memcache Configuration
----------------------

All memcache configuration has been moved to the $conf['memcache'] parameter.


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

All hooks that are specific to a single application have been moved to that
application's ``config/hooks.php`` file. Split up your existing Hooks from
``horde/config/hooks.php`` and move them to the correct application.


Group Hooks
-----------

The format for group hook functions has changed from
_group_hook_groupName($username) to _group_hook($groupName,
$userName).  So you will need to modify any existing group hook
functions in config/hooks.php for the new interface.

Alternatively, an example _group_hook() function is provided in
config/hooks.php that will call the old style hook functions for you.


Custom Themes
-------------

Themes only have a single ``info.php`` file with the theme name in Horde's
``themes`` directory now. If you have any custom themes that provide their own
images, you must add a ``themed_graphics`` file to the theme's directory (for
all applications the theme provides images for) in order for Horde to know to
use the custom images. The file can be empty or contain whatever you wish; it
simply needs to exist.


Static Log out Links
--------------------

If you have hardcoded a log out link in any custom templates or menu
items, you must update it to use Horde::getServiceLink(). This is
because logging out is now protected by a token to avoid CSRF
exploits.


Upgrading Horde from 3.1.1 to 3.1.2
===================================


Session Configuration
---------------------

A new configuration setting has been added to disable GET-based
sessions.  If this setting is enabled, session IDs will only be stored
in session cookies, requiring the users to enable cookies in their
browser and the cookie settings in Horde's configuration to be correct.

Using session cookies is much safer since no session information can
be stored in any web server or proxy log files, referrer headers,
browser caches, or browser bookmarks.

.. Warning:: This setting in enabled by default.


Additional Indexes for the Preference Table
-------------------------------------------

Optionally execute the provided SQL script 2006-06-29_horde_prefs_indexes.sql
to create two additional indexes in the preference table, e.g.::

   mysql --user=root --password=<MySQL-root-password> <db name> < scripts/upgrades/2006-06-29_horde_prefs_indexes.sql

This increases database performance for some database systems, e.g. PostgreSQL
if you have large preference tables.


Upgrading Horde from 3.1 to 3.1.1
=================================


MySQL Session Handler
---------------------

The mysql session handler has been improved to correctly lock concurrent
accesses to the same session. You need to set in the Horde configuration if
you want to use row-level locking and transactions or table-level
locking. Row-level locking and transactions are only supported by some table
engines like InnoDB, and is recommended for session tables. The default table
type for MySQL is MyISAM though, that only supports table-level locking. If
you used the SQL scripts from Horde 3.1 or earlier to create the session
table, this is probably the current engine of you session table. If you want
to change the table type to InnoDB, execute the following SQL statement::

   ALTER TABLE horde_sessionhandler ENGINE = InnoDB


Upgrading Horde from 3.0.x to 3.1.x
===================================


SQL Backends
------------

A few new tables have been added to Horde.

Execute one of the provided SQL scripts to update your data to the new Horde
version, e.g.::

   mysql --user=root --password=<MySQL-root-password> <db name> < scripts/upgrades/3.0_to_3.1.mysql.sql


Groups
------

The Horde_Group API uses group IDs instead of group names to avoid ambiguity.
Be sure to update any custom code that uses Horde_Group.


History
-------

The Horde_History storage has been moved out to a separate database table to
drastically improve performance.

.. Warning:: Migration of the Horde_History data may take a very long time,
             possibly days, depending on the number of entries.  Be sure to
             execute this script from a location where it will not be timed
             out by firewall or terminal timeouts.

Execute the provided PHP script to migrate your histories to the new table::

   php scripts/upgrades/move_history_out_of_datatree.php
