===========================================
 Upgrading Horde Groupware Webmail Edition
===========================================

:Contact: horde@lists.horde.org

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


Introduction
============

These are instructions to upgrade from earlier Horde Groupware Webmail Edition
versions.  Please backup your existing data before running any of the steps
described below, you need the backups in case anything goes wrong with the
upgrade process, which cannot be reverted automatically. You can't use the
updated data with your old Horde Groupware Webmail Edition version anymore.

Please see below for changes between certain Horde Groupware versions that are
not covered by the update script.


Upgrading a Horde Groupware Webmail Edition 4 or later
======================================================

Upgrading Horde Groupware Webmail Edition is as easy as running::

   pear upgrade -a -B horde/webmail

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

After updating to a newer Horde Groupware Webmail Edition version, 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 Groupware Webmail Edition from 4.x to 5.x
=========================================================

Configuration Options (config/conf.php)
---------------------------------------

The $conf['session']['max_time'] option was added. The default is no maximum
session time, the same behavior as in Horde Groupware Webmail Edition 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 Groupware
Webmail Edition 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
Groupware Webmail Edition 4.


Hooks (config/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 (config/prefs.php)
------------------------------

The 'sending_charset' preference now defaults to 'UTF-8'.

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 Groupware Webmail Edition'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.


Mail Module
-----------

The basic view now requires javascript support on the browser. If not
available, the user will automatically be redirected to the minimal view.


Server Options (imp/config/backends.php)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The 'namespace' option now requires the namespaces to be in the UTF-8 charset,
not UTF7-IMAP.

The 'smtphost' and 'smtpport' options have been removed. They have been
replaced by the 'smtp' option, which allows ALL available SMTP configuration
options to be overriden.

The 'admin' option has been changed: optional configuration parameters should
live within the base 'admin' array rather than a 'params' array within the
base.


Configuration Options (imp/config/conf.php)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The $conf['fixed_folders'] option now requires the mailboxes to be in the
UTF-8 charset, not UTF7-IMAP.

The $conf['compose']['link_attach_size_limit'] option was added.

The $conf['print']['add_printedby'] option was removed and replaced by the
'add_printedby' preference.

The $conf['user']['select_sentmail_folder'] option was removed. To prevent
changing the sentmail mailbox, the 'sent_mail_folder' preference should be
locked instead.

The following configuration options were removed::

   $conf['dimp']['viewport']['buffer_pages']
   $conf['dimp']['viewport']['viewport_wait']


MIME Viewer Options (imp/config/mime_drivers.php)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The 'safe_addrs' option has been removed from the Images driver config.
To set the default list of e-mail addresses that should be considered "safe",
the 'image_replacement_addrs' preference can now be used.


Hooks (imp/config/hooks.php)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The 'mbox_sort' and 'mbox_special' hooks have been added.

The 'dimp_addressformatting' hook has been removed.

The $action parameter for reporting not spam message to the 'spam_email' and
'post_spam' hooks has been changed from 'ham' to 'innocent'.


Preferences (imp/config/prefs.php)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default values for these preferences have been changed::

   drafts_folder
   sent_mail_folder
   spam_folder
   trash_folder

The following preferences are no longer used and may be safely removed from
your preference backend (only after all users have logged in - these
preferences MAY be used to automatically upgrade to new preferences when
a user logs into Horde Groupware Webmail Edition 5 for the first time)::

   dimp_qsearch_field
   dimp_show_preview
   dimp_splitbar
   dimp_splitbar_vert
   dimp_toggle_headers
   dynamic_view
   image_addrbook
   move_ham_after_report
   sig_first
   stationery

The 'cursor_compose' preference removed the 'sig' option. Existing preferences
will automatically be converted to 'bottom'.

The 'save_attachments' preference removed the 'prompt_yes' and 'prompt_no'
options. Existing preferences will automatically be converted.

The 'add_printedby', 'image_replacement_addrs', 'reply_charset', and
'reply_strip_sig' preferences were added.

The 'forward_default' preference now contains the 'editasnew' option.


API Changes
~~~~~~~~~~~

  - copyMessages

    The $mailbox and $target parameters are now required to be UTF-8 strings.

  - createFolder

    This call has been removed (replaced with 'createMailbox').

  - deleteMessages

    The $mailbox parameter is now required to be a UTF-8 string.

  - flagMessages

    The $mailbox parameter is now required to be a UTF-8 string.

  - folderlist

    This call has been removed (replaced with 'mailboxList').

  - moveMessages

    The $mailbox and $target parameters are now required to be UTF-8 strings.

  - searchMailbox

    The $mailbox parameter is now required to be a UTF-8 string.


Filters Module
--------------

Backend Configuration (ingo/config/backends.php)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The 'hordeauth' parameter and the 'password' and 'username' parameters have
been removed. By default, the transport backend will use Horde Groupware
Webmail Edition authentication credentials to access. To set a different
username and/or password, you should use the 'transport_auth' hook.


Address Book Module
-------------------

Attribute Changes
~~~~~~~~~~~~~~~~~

  - The "gender" attribute sets values of (literally) "male" or "female" now,
    and no longer 0 or 1.


Preference Changes
~~~~~~~~~~~~~~~~~~

  - The "addressbooks" preference has been removed.


API Changes
~~~~~~~~~~~

  - search

    The $sources, $fields, $matchBegin, $forceSource and $returnFields
    parameters have been removed and replaced by the $opts parameter.

    Added a 'rfc822Return' option to return a Horde_Mail_Rfc822_List object
    instead of the search results array (which remains the default).


Upgrading Horde Groupware Webmail Edition from 4.0.x to 4.0.4
=============================================================


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 Groupware's configuration::

   pear install horde/horde_service_weather-alpha


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

The 'nobase64_img' option was added.


Preferences (imp/config/prefs.php)
----------------------------------

The 'delete_mark_seen' preference has been added to the Mail module.

The 'reply_lang' preference has been added to the Mail module.


Upgrading Horde Groupware Webmail Edition from 4.0.x to 4.0.3
=============================================================


Configuration Options
---------------------

The 'allow_resume_all' option has been removed from the Mail module.  Only
messages specifically marked as drafts can be resumed; however, all messages
are given the option to "Edit As New".


MIME Viewer Options (imp/config/mime_drivers.php)
-------------------------------------------------

The 'allthumbs' option has been removed from the Mail module's HTML driver.
Image thumbnail previews are now always shown if an image conversion utility is
present on the system.


Upgrading a Horde Groupware Webmail Edition 1.x
===============================================

For upgrading from a Horde Groupware Webmail Edition version 1.x to
4.0 or later, see the section `Upgrading a Horde Groupware Webmail
Edition 4 or later`_.

The update script will automatically migrate database backends and
update configuration files. It will add new and changed configurations
at the end of existing configuration files, any changes done to old
configuration files won't get lost, but might get overridden by new
settings. You might want to check the updated configuration files
after the update script has finished to make sure that any
customizations that you did to the old version still work as expected.

The ``.dist`` versions of the configuration files alway contain the most
recent reference settings and the settings documentation. If you experience
any problems with the configuration files after an update, or if you want
cleaner configuration files without all the updating code, you can create
fresh versions from the ``.dist`` files.

These instructions are supposed to be used with a complete tarball of the new
Horde Groupware Webmail Edition version. They don't work if you use a patch
file to upgrade your installation, because the patch already contains all
configuration file changes that the update script is going to add.

1. Extract the tarball of the new version **in parallel** to the old
   version. See the INSTALL_ file details how to unpack a tarball.

   If you want to replace the old version with the new version eventually, you
   should move the old version to a different place now and put the new
   version in the place of the old one. You can still do this later, if you
   want to, but you have to edit the configuration file then.

2. Start the setup script::

     ./scripts/setup.php

3. Choose the update option in the setup menu and answer the questions from
   the setup script.

4. Pray.

5. If everything went fine and without any error messages, point your browser
   to the URL of the new version and log in as an administrator. Go to the
   ``Administration -> Setup`` screen and update all configurations that are
   marked as being outdated.

6. If you want to replace the old version with the new one, and if you didn't
   do this already in step 1, you can do it now. But you have to edit the
   configuration file ``config/conf.php`` manually and change the setting
   ``$conf['cookie']['path']`` to match the new URL path. Otherwise you won't
   be able to login after you moved Horde Groupware Webmail Edition to a
   different directory.


Upgrading Horde Groupware Webmail Edition from 1.1.x to 1.1.1.1
===============================================================


Favourite Recpients Address Book
--------------------------------

An address book which lists the users' most favourite recipients had been
added in version 1.1 already but has only been activated with this
version. But for the address book to properly work, you also have to enable
sent mail tracking in the configuration.

Log in as an administrator, go to ``Administration -> Setup -> Webmail
(imp)``, then choose the ``Other Settings`` tab and set the
``$conf[sentmail][driver]`` setting to ``SQL``.


Upgrading Horde Groupware Webmail Edition from 1.0.x to 1.1.x
=============================================================


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 no longer have ``info.php`` files. 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.


Unified IMAP Quota Driver
-------------------------

Separate quota drivers for Cyrus and Courier servers are no longer
necessary. These drivers have been replaced by a generic IMAP driver that
should also be suitable for other IMAP servers that support the QUOTA
extension. Update ``config/servers.php`` and change the 'quota' => 'driver'
setting to 'imap'.


User-Defined Mailbox Icons
--------------------------

The usage of the hook ``_imp_hook_mbox_icons()`` has changed.  If you use this
hook, make sure you change your implementation so it returns the correct
value.


New Message List Format Hook
----------------------------

The new hook ``_imp_hook_msglist_format()`` has been added which allows the
formatting of a message entry in the mailbox message list to be altered
at the time the list is created.  This hook has made the following
configuration options obsolete::

   $conf['mailbox']['show_attachments']
   $conf['mailbox']['show_xpriority']

If you wish to continue using the functionality previously provided by these
options, you should activate the msglist_format hook in ``config/conf.php``.
The sample hook contained in ``config/hooks.php`` contains the code necessary
to replicate the previous behavior.


Spell Checking
--------------

The ``pspell`` driver is no longer supported since it does not work with
HTML messages.  If using pspell, you must upgrade to aspell version 0.60+.


Filters SQL Backend
-------------------

An SQL table has been added than can optionally be used as a storage backend
for the filter rules. Using this backend no longer limits the number and size
of rules.

You have to execute the provided PHP script to migrate the existing rules from
the preferences backend to the new database table::

   php ingo/scripts/upgrades/convert_prefs_to_sql.php < filename

``filename`` is a file that contains a list of users, one username per line.
The username should be the same as how the preferences are stored in the
preferences backend (e.g. usernames may have to be in the form
user@example.com). You can create such a list with the following MySQL
command::

   mysql --user=root --password=<MySQL-root-password> --skip-column-names --batch --execute='SELECT DISTINCT pref_uid FROM horde_prefs' <db name>


IMSP Driver and Share Support
-----------------------------

Share support has been added to the IMSP driver.  This support requires at
least a Horde 3.2 install.  With this change, any IMSP address books the user
has rights to will be represented internally as a Horde share.  Permissions
changed on the share will be reflected back to the IMSP server.  If you set
the configuration setting ``Name of source for creating new shares`` to
``imsp`` then any shares created by the user will result in a new IMSP address
book being created on the IMSP server.  Likewise, any IMSP address book
deleted in Turba will be removed from the IMSP server.

To enable this support, make sure you are using at least Horde 3.2, set the
``use_shares`` attribute to true, and uncomment the IMSP
``_horde_hook_share_*`` functions in ``horde/config/hooks.php``.

With this change, the ``IMSP Address Book Administration`` option page has
been removed, as the creation/deletion of address books is now handled with
shares.

.. Important:: IMSP contacts contained in contact groups that are not from an
               IMSP source may not be visible within that group when migrating
               an IMSP source to a share.


.. _INSTALL: INSTALL
