617 lines
20 KiB
Plaintext
617 lines
20 KiB
Plaintext
=================
|
|
Upgrading Horde
|
|
=================
|
|
|
|
:Contact: horde@lists.horde.org
|
|
|
|
.. contents:: Contents
|
|
.. section-numbering::
|
|
|
|
|
|
General instructions
|
|
====================
|
|
|
|
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.
|
|
|
|
Upgrading Horde (and all installed Horde libraries and applications)
|
|
is as easy as running::
|
|
|
|
pear upgrade -a -B -c horde
|
|
|
|
If you want to upgrade Horde 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 -c horde
|
|
|
|
If you want to upgrade to an alpha or beta version of Horde, 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 -c horde
|
|
|
|
If you want to upgrade from a Horde version prior to 4.0, please follow the
|
|
instructions in INSTALL_ to install the most recent Horde version using the
|
|
PEAR installer.
|
|
|
|
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 5.1.x to 5.2
|
|
=================================
|
|
|
|
Configuration Options (conf.php)
|
|
--------------------------------
|
|
|
|
New logging options for ActiveSync logging have been added. It is now possible
|
|
to log all devices to a single log file or to device specific files.
|
|
Additionally, it is also possible to select between including the raw wbxml
|
|
stream in the output, or prune tag content greater than 50 bytes. The
|
|
ActiveSync configuration section should be revisited.
|
|
|
|
It is now possible to use X509 certificates either in addition to, or in place
|
|
of traditional HTTP Basic authentication for ActiveSync. Refer to the
|
|
ActiveSync configuration section for more details.
|
|
|
|
An additional option is now available for the SMTP Mailer driver: 'lmtp'.
|
|
|
|
A new NoSQL driver is now available for storing ActiveSync device state. Refer
|
|
to the ActiveSync configuration section for more details.
|
|
|
|
The History driver can now be explicitly defined in the configuration (and a
|
|
new NoSQL driver has been added).
|
|
|
|
Additional options are now available for the Predis HashTable driver:
|
|
'password', 'persistent', and 'protocol'. Additionally, the 'hostspec' and
|
|
'port' options now accept multiple values (separated by commas).
|
|
|
|
The following options were added::
|
|
|
|
$conf['activesync']['logging']['level']
|
|
$conf['activesync']['auth']['type']
|
|
$conf['activesync']['auth']['params']
|
|
$conf['activesync']['storage']
|
|
$conf['activesync']['params']['driverconfig']
|
|
$conf['cachecssparams']['filemtime']
|
|
$conf['history']['driver']
|
|
$conf['history']['params']['driverconfig']
|
|
$conf['mailer']['params']['password_auth']
|
|
$conf['mailer']['params']['username_auth']
|
|
|
|
The available options for the following options were changed::
|
|
|
|
$conf['activesync']['logging']['type']
|
|
$conf['mailer']['params']['password'] (for SMTP)
|
|
$conf['mailer']['params']['username'] (for SMTP)
|
|
|
|
The default value for the following options were changed::
|
|
|
|
$conf['prefs']['maxsize']
|
|
|
|
The following options were removed::
|
|
|
|
$conf['mailformat']['brokenrfc2231']
|
|
|
|
|
|
Hooks (hooks.php)
|
|
-----------------
|
|
|
|
New ActiveSync related hooks have been added::
|
|
|
|
activesync_create_device
|
|
activesync_device_check
|
|
activesync_device_modify
|
|
|
|
Read the comments at the top of the hooks.php file for descriptions of each
|
|
hook.
|
|
|
|
|
|
Registry Options (registry.php)
|
|
-------------------------------
|
|
|
|
The 'staticfs' and 'staticuri' configuration options were added to the 'horde'
|
|
configuration.
|
|
|
|
|
|
|
|
Upgrading Horde from 5.0.x to 5.1
|
|
=================================
|
|
|
|
Configuration Options (conf.php)
|
|
--------------------------------
|
|
|
|
It is now possible to configure Horde-wide settings for a NoSQL database
|
|
backend. Addtionally, several Horde packages now allow a NoSQL backend driver
|
|
to be used.
|
|
|
|
The Memcache configuration options have been deprecated and have been replaced
|
|
by the generic Horde_HashTable package (which supports both Memcache and Redis
|
|
servers). Although the previous memcache configuration will continue to work
|
|
in Horde 5.x, it is recommended to upgrade to the new 'hashtable'
|
|
configuration setup.
|
|
|
|
The following options were added::
|
|
|
|
$conf['auth']['resetpassword_from']
|
|
|
|
The following options were removed::
|
|
|
|
$conf['cache']['compress']
|
|
$conf['cachecssparams']['compress']
|
|
|
|
|
|
Hooks (hooks.php)
|
|
-----------------
|
|
|
|
The 'ajaxaction' hook has been deprecated and replaced with the
|
|
'ajaxaction_handle' hook (new hook needed in order to allow, e.g., adding
|
|
tasks to the outgoing response).
|
|
|
|
The following hooks were added::
|
|
|
|
ajaxaction_data
|
|
|
|
|
|
Upgrading Horde from 5.0 to 5.0.1
|
|
=================================
|
|
|
|
Weather portal block
|
|
--------------------
|
|
|
|
Google no longer provides a weather API. Support for this has therefore been
|
|
removed from Horde. If you were using Google as a source for weather, you will
|
|
need to pick a new provider and update the Horde configuration.
|
|
|
|
|
|
Upgrading Horde from 4.x to 5.x
|
|
===============================
|
|
|
|
Configuration Options (conf.php)
|
|
--------------------------------
|
|
|
|
The $conf['session']['max_time'] option was added. The default is no maximum
|
|
session time, the same behavior as in Horde 4.
|
|
|
|
The $conf['cachecssparams']['url_version_param'] option was added. This option
|
|
is only used if no CSScaching is selected (a configuration that is NOT
|
|
recommended for production servers). The new default is to add version
|
|
information to CSS server URLs, which is altered behavior from Horde 4.
|
|
|
|
The $conf['cachejsparams']['url_version_param'] option was added. This option
|
|
is only used if no javascript caching is selected (a configuration that is NOT
|
|
recommended for production servers). The new default is to add version
|
|
information to javascript server URLs, which is altered behavior from Horde 4.
|
|
|
|
|
|
Hooks (hooks.php)
|
|
-----------------
|
|
|
|
The 'appauthenticated' hook has been added.
|
|
|
|
The behavior of the 'pushapp' hook has changed - it is now called a maximum of
|
|
one time per page access for an application.
|
|
|
|
The 'appinitialized' hook was removed (replaced by the 'appauthenticated'
|
|
hook).
|
|
|
|
The 'pushapp_post' hook was removed.
|
|
|
|
See ``config/hooks.php.dist`` for further details.
|
|
|
|
|
|
Preferences (prefs.php)
|
|
-----------------------
|
|
|
|
The 'sending_charset' preference now defaults to 'UTF-8'. Any previous saved
|
|
value will be deleted when upgrading to 5.0 - if you want to send in a
|
|
charset other than UTF-8 (NOT RECOMMENDED), you will need to explicitly set
|
|
this value again (in either ``config/prefs.local.php`` or you preferences
|
|
storage backend).
|
|
|
|
The 'menu_view' and 'show_sidebar' preferences have been removed.
|
|
|
|
|
|
ActiveSync (EAS) Integration
|
|
----------------------------
|
|
|
|
Email support has been added, along with support for the EAS 12.0 and 12.1
|
|
protocol versions. New configuration options have been added to support this.
|
|
You MUST update Horde's ActiveSync configuration.
|
|
|
|
The Custom logging option has been changed to ALWAYS be a path to a directory,
|
|
and not a specific filename.
|
|
|
|
The security policy settings have been moved out of the global configuration and
|
|
into the permissions system for greater per user control over policies.
|
|
|
|
New database migrations have been added, you MUST run these migrations for
|
|
ActiveSync to work.
|
|
|
|
|
|
Upgrading Horde from 4.0.x to 4.0.12
|
|
====================================
|
|
|
|
|
|
Weather portal block
|
|
--------------------
|
|
|
|
The weather.com website has dropped their API to retrieve weather forecasts
|
|
with a very short notice. The weather.com portal block has been removed and
|
|
will be automatically removed from the users' portal configurations too.
|
|
|
|
A new portal block for weather forecasts is available, powered by the new
|
|
Horde_Service_Weather library that supports a number of free weather
|
|
services. To provide this block to the end users, install the
|
|
Horde_Service_Weather library from Horde's PEAR server, and configure a weather
|
|
service in Horde's configuration::
|
|
|
|
pear install horde/horde_service_weather-alpha
|
|
|
|
|
|
Upgrading Horde from 4.0.x to 4.0.10
|
|
====================================
|
|
|
|
Configuration changes
|
|
---------------------
|
|
|
|
The 'nobase64_img' option was added.
|
|
|
|
|
|
Upgrading Horde from 4.0 to 4.0.1
|
|
=================================
|
|
|
|
Configuration Values
|
|
--------------------
|
|
|
|
Cyrsql driver: The 'unixhier' parameter has been replaced by the
|
|
'userhierarchy' parameter.
|
|
|
|
|
|
Hooks
|
|
-----
|
|
|
|
The appinitialized hook was added. See ``config/hooks.php.dist`` for more
|
|
details on this hook.
|
|
|
|
|
|
Upgrading Horde from 3.3.x to 4.x
|
|
=================================
|
|
|
|
New installation method
|
|
-----------------------
|
|
|
|
Since Horde 4 the supported installation method has been changed to
|
|
install Horde and all dependencies through the PEAR installer. See
|
|
INSTALL_ for instructions how to install Horde through PEAR.
|
|
|
|
Existing **data** from the latest Horde can be migrated from the
|
|
configuration screen in the administration section. It is recommended
|
|
to re-create the **configuration** from scratch though.
|
|
|
|
|
|
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 administrator, 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 ``horde-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 **before** running any other upgrade tasks. 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
|
|
|
|
The script to generate alarm notifications through a cron job
|
|
(``scripts/alarms.php``) has been renamed and is installed to a different
|
|
location when using the PEAR installation method. The new name is
|
|
``bin/horde-alarms`` and it will be installed to ``/usr/bin/horde-alarms`` by
|
|
default. Update your cron jobs accordingly.
|
|
|
|
|
|
Groups
|
|
------
|
|
|
|
The groups system has been rewritten. Group hierarchies, i.e. parent and child
|
|
groups are no longer supported. Support for nested groups will be added at a
|
|
later point.
|
|
|
|
|
|
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.
|
|
* DataTree support has been removed. Several systems used DataTree as a
|
|
possible backend for historical reasons. If you still used DataTree backends
|
|
in Horde 3 and didn't migrate to SQL drivers yet, now you have to. See
|
|
further below for instructions how to migrate away from DataTree backends.
|
|
* 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-convert-datatree-perms-to-sql`` that will migrate all of
|
|
your DataTree-based permissions to the SQL backend, and
|
|
``horde-convert-datatree-groups-to-sql`` 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
|
|
``app-convert-datatree-shares-to-sql`` 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::
|
|
|
|
horde-move-history-out-of-datatree
|
|
|
|
|
|
.. _INSTALL: INSTALL
|