1   Obtaining 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/

Or, better yet, use a mirror that is closer to you. The mirror list can be found at:

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

The FTP directory contains the Horde PHP files which can be unpacked using tar and gunzip (see Installing Horde, below).

Bleeding-edge development versions of Horde and its applications are available via CVS; see the file docs/HACKING, or visit the website http://www.horde.org/source/, for information on accessing the Horde CVS repository.

You will probably also want one or more Horde applications, since Horde doesn't do much by itself; a list of available applications, with links to descriptions and downloads, can be found at

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

While previous versions of Horde were numbered to correspond with a particular version of the IMP webmail application, that is no longer true as of Horde version 2.0. The current version of Horde will work with the current version of Horde applications. For more information about which versions are compatible see http://www.horde.org/source/versions.php.

2   Quick Install

These are very terse instructions how to install Horde and its prerequisites on a LAMP sytem. They are addressed to experienced administrators who know exactly what they are doing. For more detailed instructions, start reading below at Prerequisites.

1. Compiling PHP for Apache:

   cd php-x.x.x/
   ./configure --with-apxs=/usr/sbin/apxs \
               --with-gettext --with-dom --with-mcrypt \
               --with-iconv --enable-mbstring=all --enable-mbregex \
               --with-gd --with-png-dir=/usr --with-jpeg-dir=/usr \
               --with-mime-magic=/user/share/misc/magic.mime \
               [--with-mysql|--with-pgsql|--with-oci8|--with-ldap]
   make
   make install
   

2. Restart Apache.

3. Install PEAR packages:

   pear install -o Log Mail Mail_Mime DB Date File
   pear -d preferred_state=beta install -a Services_Weather
   

4. Extract tarball:

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

5. Configure Horde:

   cd config/
   for f in *.dist; do cp $f `basename $f .dist`; done
   

6. Create database tables:

   cd ../scripts/sql
   vi create.mysql.sql
   mysql -u root -p < create.mysql.sql
   

7. Test Horde:

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

8. Finish configuration:

   http://your-server/horde/
   

   Go to Adminstration => Setup => Horde

3   Prerequisites

The following prerequisites are REQUIRED for Horde to function properly.

1. A webserver that supports PHP.

   Horde and its applications are developed under the Apache webserver, which we recommend. Apache is available from

   http://httpd.apache.org/

   Horde has also been reportedly used successfully under Microsoft IIS, among others.

2. PHP 4.3.0 or above.

   PHP is the interpreted language in which Horde is written. You can obtain PHP at

   http://www.php.net/

   Follow the instructions in the PHP package to build PHP for your system. If you use Apache, be sure to build PHP as a library with one of the following options:

   --with-apache
   --with-apxs
   --with-apxs2
   

   options to ./configure, and not as a standalone executable.

   The following PHP options are REQUIRED by Horde (listed with their own prerequisites and configure options). In many cases, the required libraries and tools can be obtained as packages from your operating system vendor.

   1. Gettext support. --with-gettext

      Gettext is the GNU Translation Project's localization library. Horde uses gettext to provide local translations of text displayed by applications. Information on obtaining the gettext package is available at

      http://www.gnu.org/software/gettext/gettext.html

      See also note below on configuring Translations.

   2. XML and DOMXML support. --with-dom

      Horde's help engine and component setup require XML support. While some webservers (including recent Apache versions) have XML libraries built-in, others will require the expat XML parser libraries, available from

      http://expat.sourceforge.net/

      Important

      You must have both XML libraries installed for Horde to work properly!

      Older versions of PHP also require --with-xml to enable the SAX XML functions. With recent versions of PHP, this is enabled by default.

   The following PHP options are RECOMMENDED to enable advanced features in Horde:

   1. A preferences container.

      Horde applications can store user preferences in an SQL database, an LDAP directory, an IMSP server, a Kolab server, or in PHP sessions.

      For SQL database preferences storage, Horde is thoroughly tested on MySQL (--with-mysql) and PostgreSQL (--with-pgsql) and has been reported to work with Oracle (--with-oci8) and SQL Server (--with-mssql). It may also work with any other database supported by PEAR, but they are untested.

      Preferences can also be stored via LDAP (--with-ldap), Kolab (--with-ldap), and IMSP.

      Alternatively, preferences can be stored in PHP sessions, which requires no external programs or configure options, but which will not maintain preferences between sessions.

      While the LDAP, database, Kolab, or IMSP server need not be running on the machine onto which you are installing Horde, the appropriate client libraries to access the server must be available locally.

      If a preference container is not configured, no preference options will be configurable via Horde's web interface - the default values stored in each applications config/prefs.php file will be used.

   2. Mcrypt support --with-mcrypt

      Mcrypt is a general-purpose cryptography library which is broader and significantly more efficient (FASTER!) than PHP's own cryptographic code. You can obtain mcrypt from

      http://mcrypt.sourceforge.net/

      Building PHP without mcrypt support will not stop Horde from working, but will force it to use weaker (and much slower) encryption.

   3. UTF-8 support --with-iconv --enable-mbstring=all --enable-mbregex

      If these extensions are enabled, Horde can support multibyte character sets like UTF-8 (meaning that content with any charset can be viewed with any translation).

      For iconv support you should use the GNU libiconv library, which is more stable and supports more charsets, compared to other iconv implementations, like Solaris', for example.

   4. GD support --with-gd

      Horde will use the GD extension to perform manipulations on image data through the Horde_Image library.

      If you want GD to be able to work with PNG images, you should use the --with-png-dir option to make sure PHP can find the PNG libraries it needs to compile.

      If you want GD to be able to work with JPEG images, you should use the --with-jpeg-dir option to make sure PHP can find the JPEG libraries it needs to compile.

      You can also use the ImageMagick package to do these manipulations instead. See the Image Manipulation tab of the Horde setup for more details.

   5. MIME Magic support --with-mime-magic

      Horde will use the MIME Magic extension to guess the MIME type of files by analyzing their contents.

      Note

      This extension is reported to be deprecated in favor of the fileinfo PECL extension (see below). However, some users have reported that the fileinfo extension will not build correctly on their system. If so, then the MIME Magic extension should be used instead. Pick one or the other - there is no need to compile both.

      If using PHP 4.3.0 -> 4.3.1, you should use --enable-mime-magic instead of --with-mime-magic.

   Important

   Additionally, individual Horde applications may REQUIRE or RECOMMEND other options to be built into PHP also. Please check docs/INSTALL for all applications you wish to use to see if other PHP options are needed.

3. Additional PEAR Modules

   PEAR is short for "PHP Extension and Application Repository". The goal of PEAR is to provide a means of distributing reusable code.

   For more information, see http://pear.php.net/

   Important

   Make sure you are running a supported (i.e. new enough) version of PEAR: use the test script described below under "Configuring Horde". Do not use the PEAR version from ftp.horde.org.

   Check that the path where the PEAR packages are installed are part of the include_path parameter that PHP uses to find PEAR packages.

   Run the command:

   pear config-show
   

   You will see something like:

   PEAR directory                 php_dir         /usr/share/php
   

   Now open the php.ini file of your system, for example /etc/php.ini, find the include_path and make sure that /usr/share/php is part of the list. If you had to change that value, restart the web server after saving php.ini.

   These PEAR modules are REQUIRED to be installed for complete Horde functionality:

   1. Log

   2. Mail

   3. Mail_Mime

      To install, enter the following at the command prompt:

      pear install Log Mail Mail_Mime
      

   These PEAR modules are RECOMMENDED to be installed:

   1. DB (>= 1.7.8)

      REQUIRED as soon as you want or need to store anything in a database. To install, enter the following at the command prompt:

      pear install DB
      

      To upgrade, enter the following at the command prompt:

      pear upgrade DB
      

   2. File

      REQUIRED only if you wish to import CSV files. To install, enter the following at the command prompt:

      pear install File
      

   3. Date

      REQUIRED only if you are dealing with calendar data. To install, enter the following at the command prompt:

      pear install Date
      

   4. Services_Weather (>= 1.3.1)

      REQUIRED only if you wish to use the weather.com block on the portal page. To install, enter the following at the command prompt:

      pear install -a Services_Weather
      

      Additional steps are required if you want use the METAR weather block on the portal page. See the file data/Services_Weather/buildMetarDB.php in your PEAR directory for details.

   5. HTTP_WebDAV_Server

      REQUIRED only if you want to use Horde's WebDAV interface, for example to access calendars, tasklists or files with an external client. To install, enter the following at the command prompt:

      pear install HTTP_WebDAV_Server-beta
      

   6. Net_DNS

      If installed, it will be used instead of the built-in PHP function gethostbyaddr() for host name lookups. This has the advantage that Net_DNS has configurable timeouts and retries. Net_DNS requires the mhash PHP extension. To install, enter the following at the command prompt:

      pear install Net_DNS
      

   7. File_Fstab

   Required only if you use the localhost driver for the Accounts block. To install, enter the following at the command prompt:

   pear install File_Fstab
   

   This method of installing PEAR modules requires that you have a PHP version that has been compiled as a static binary. All versions of PHP 4.3.0+ build both a SAPI module (Apache, CGI, etc.) and a command-line (CLI) binary at the same time. Check if you have a php binary in /usr/local/bin (/usr/bin if if you installed from an operating system package) before recompiling.

   If you receive the error Could not read cmd args you should run the pear script this way:

   php -d register_argc_argv=1 _PEAR_ install _MODULE_
   

   _PEAR_ is the complete path of the pear script installed by PHP during installation (e.g. /usr/local/bin/pear). Make sure the pear script appears in your path. The default installation path for pear is /usr/local/bin/pear.

   _MODULE_ is the PEAR module, listed above, which you wish to install.

   For more detailed directions on installing PEAR modules, see the PEAR documentation at http://pear.php.net/manual/

4. Additional PECL Modules

   PECL is short for "PHP Extension Community Library". The goal of PECL is to provide a means of easily distributing PHP extensions.

   For more information, see http://pecl.php.net/

   PECL is the "sister" of PEAR and uses the same packaging and distribution system as PEAR, so the configuration/setup is essentially identical to the PEAR instructions above.

   When you install a PECL extension, you have to add it to your php.ini so it gets loaded. Add the following line to your php.ini file to load the extension (the extension should be installed in the directory specified by the extension_dir option in php.ini):

   extension=fileinfo.so
   

   Or on Windows:

   extension=fileinfo.dll
   

   After that, restart your webserver.

   These PECL modules are RECOMMENDED to be installed:

   1. fileinfo

      Allows Horde modules to guess the MIME type of files by analyzing their contents.

      If not enabled, Horde will use its own PHP code to perform MIME magic lookups. However, this lookup is slower, less accurate, and detects fewer MIME types than the PECL extension will.

      To install, enter the following at the command prompt:

      pecl install fileinfo
      

   2. json

      The json extension will be used for JSON serialization if available. json's author claims this module is 86 - 270 times faster than a pure PHP solution.

      THE JSON MODULE IS ONLY REQUIRED FOR VERSIONS OF PHP < 5.2. JSON SUPPORT IS AUTOMATICALLY INCLUDED IN PHP 5.2+.

      To install, enter the following at the command prompt:

      pecl install json
      

   These PECL modules are RECOMMENDED to be installed if you need advanced functionality:

   1. memcache

      If using the memcached SessionHandler, the memcache PECL extension must be installed.

      To install, enter the following at the command prompt:

      pecl install memcache
      

   2. lzf

      If the lzf module is available, Horde can compress some cached data in the current session, thus reducing the size of the current session.

      To install, enter the following at the command prompt:

      pecl install lzf
      

   For additional help on using the pear command-line program to install PECL extensions, see the PEAR installation section above.

The following non-PHP prerequisites are RECOMMENDED, or are REQUIRED if you use a specific Horde application (as noted in [brackets]):

1. Sendmail or equivalent.

   Horde uses sendmail, or a program that implements the sendmail(8) API (as included with postfix, qmail, and exim, among others). If your system does not already have a full mail transport with a sendmail interface, you can configure Horde to speak directly with a remote SMTP server, but this may incur a performance penalty.

4   Installing Horde

Horde 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. If you have no idea where you should be installing Horde, install it directly under the root of your webserver's document tree.

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

http://your-server/horde/

cd horde
cvs co framework
cd framework
pear channel-discover pear.horde.org
php -q install-packages.php

5   Configuring Horde

1. Configuring the web server

   Horde requires the following webserver settings. Examples shown are for Apache; other webservers' configurations will differ.

   1. PHP interpretation for files matching *.php:

      AddType application/x-httpd-php .php
      

      Note

      The above instructions may not work if you have specified PHP as an output filter with SetOutputFilter directive in Apache 2.x versions. In particular, Red Hat 8.0 and above Apache 2.x RPMS have the output filter set, and MUST NOT have the above AddType directive added.

   2. index.php as an index file (brought up when a user requests a URL for a directory):

      DirectoryIndex index.php
      

2. Creating databases

   The specific steps to create a preferences storage container depend on which database you've chosen to use.

   First, look in scripts/sql/ to see if a create. script already exists for your database. If so, you should be able to simply execute that script as superuser in your database. Consult the scripts/sql/README file for more information.

   Be sure to change the default password, horde, to something else before creating the tables! (Remember to use this password when you configure Horde in the next step.)

   If such a script does not exist, you'll need to build your own, using the files horde_users.sql, horde_prefs.sql, and horde_datatree.sql as a starting point. If you need assistance in creating databases for a database for which no create. script exists, you may wish to let us know on the Horde mailing list.

   If you make any changes to the user that will access the database, you MUST ensure that that user can still create tables. Otherwise Horde will be unable to create sequence tables for tracking primary keys.

   If you are going to use database based sessions, create a table using the files scripts/sql/horde_sessionhandler*.sql as a starting point.

3. Configuring Horde

   To configure Horde, 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 f in *.dist; do cp $f `basename $f .dist`; done
   

   Or if you are installing Horde an a Windows system:

   cd config
   copy *.dist *.
   

   Documentation on the format of those files can be found in each file.

   Warning

   All configuration files in Horde are PHP scripts that are executed by the web server. If you make an error in one of these files, Horde might stop working. Thus it is always a good idea to test the configuration files after you edited them. If you want to test mime_drivers.php for example run:

   php -l mime_drivers.php
   

4. Setting up alarm emails

   If you want your users to be able to receive emails from the Horde_Alarm system, you must set up a cron entry for horde/scripts/alarms.php, you must have at least one administrator specified in the Horde configuration, and you must have the PHP CLI installed (a CGI binary is not supported - php -v will report what kind of PHP binary you have).

   Running the job every 5 minutes is recommended:

   # Horde Alarms
   */5 * * * * /usr/bin/php /var/www/horde/scripts/alarms.php
   

   (replace /usr/bin/php with the path to your PHP CLI and /var/www/horde/ with the path to your Horde installation)

5. Testing Horde

   Once you have configured your webserver, PHP, and Horde, bring up the included test page in your Web browser to ensure that all necessary prerequisites have been met. If you installed Horde as described above, the URL to the test page would be:

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

   Check that your PHP and PEAR versions are acceptably recent, that all required module capabilities are present, and that magic_quotes_runtime is set to Off. Then note the Session counter: 1 line under PHP Sessions, and reload the page. The session counter should increment.

   If you get a warning like Failed opening '/path/to/test.php' for inclusion, make sure that the web server has the permission to read the test.php file.

6. Completing Configuration

   You can now access Horde without a password, and you will be logged in as an administrator.

   Important

   You should first configure a real authentication backend and designate which accounts in your real backend will be administrator accounts. Horde does NOT have a default administrator account - all users, including administrators, must exist in the actual authentication backend. Click on Setup in the Administration menu and configure Horde. Start in the Authentication tab.

   Here is an example for configuring authentication against a remote IMAP server. Similar steps apply for authenticating against a database, an LDAP server, etc.

   1. In the Which users should be treated as administrators field enter a comma separated list of user names of your choosing. This will control who is allowed to make configuration changes, see passwords, potentially add users, etc.
   2. In the What backend should we use for authenticating users to Horde pulldown menu select IMAP authentication. The page will reload and you will have specific options for IMAP authentication.
   3. In the Configuration type pulldown menu select Separate values. The page will reload with additional options. Fill in the remaining three fields appropriately:
      • IP name/number of the IMAP server
      • For a secure connection, select port 993.
      • Select the protocol; for a secure connection either imap/ssl or imap/ssl/novalidate-cert (for self-signed certificates).

   Continue to configure Horde through all the tabs of the setup interface and click on Generate Horde Configuration. Important items that you probably want to configure are the Preference System that lets users save their personal options, and the DataTree System that is required for some applications to work at all.

   Configuration of applications in registry.php is documented in the INSTALL file of each application. Most applications require you to configure them with a "Horde administrator" account. A Horde administrator account is any normal Horde account that has been added to the administrator list in the Authentication tab of the Horde setup.

   The other files in that directory need only be modified if you wish to customize Horde's appearance or behaviour -- the defaults will work at most sites.

7. Securing Horde

   1. Passwords

      Some of Horde's configuration files contain passwords which local users could use to access your database. It is recommended to ensure that at least the Horde configuration files (in config/) are not readable to system users. There are .htaccess files restricting access to directories that do not need to be accessed directly; before relying on those, ensure that your webserver supports .htaccess and is configured to use them, and that the files in those directories are in fact inaccessible via the browser.

      An additional approach is to make Horde's configuration files owned by the user root and by a group which only the webserver user belongs to, and then making them readable only to owner and group. For example, if your webserver runs as www.www, do as follows:

      chown root.www config/*
      chmod 0440 config/*
      

   2. Sessions

      Session data -- including hashed versions of your users' passwords, in some applications -- may not be stored as securely as necessary.

      If you are using file-based PHP sessions (which are the default), be sure that session files are not being written into /tmp with permissions that allow other users to read them. Ideally, change the session.save_path setting in php.ini to a directory only readable and writeable by your webserver.

      Additionally, you can change the session handler of PHP to use any storage backend requested (e.g. SQL database) via the Custom Session Handler tab in the Horde setup.

   For more information about securing your webserver, PHP and Horde, see the docs/SECURITY file.

8. Entering the survey

   If you like, go to http://www.horde.org/survey/ and enter the details of your system.

6   Configuring Applications

A list of available Horde applications can be found at

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

Instructions on configuring Horde applications can be found in the INSTALL file in the application's docs/ directory.

7   Temporary Files

Various Horde applications will generate temporary files in PHP's temporary directory (see the General tab in the Horde setup). For various reasons, some of these files may not be removed when the user's session ends. To reclaim this disk space, it may be necessary to periodically delete these old temporary files.

An example cron-based solution can be found at scripts/temp-cleanup.cron. Another possible solution is to use Red Hat's tmpwatch utility or anything similar to remove old files (see http://www.redhat.com/).

8   Translations

Note for international users: Horde 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.

9   Obtaining Support

If you encounter problems with Horde, 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 Horde is free software written by volunteers. For information on reasonable support expectations, please read

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

Thanks for using Horde!

The Horde Team