The Horde Administrator's FAQ

About the FAQ

The Horde Administrator's FAQ contains questions and answers regarding obtaining, installing, configuring, and running Horde and its components. If you are not the system administrator for your Horde installation, then you probably want the User's FAQ.

Much of what follows involves IMP 2.2, Horde's webmail component. This is mostly a result of IMP being the most mature and most widely-deployed component.

Please send updates, corrections and comments to the FAQ coordinator.

Last modified: 1:38pm, July 14, 2004 PDT

Table of Contents

1. General Information
1.1 What is...
1.1.1 Horde?
1.1.2 IMP?
1.1.3 Turba?
1.1.4 Kronolith?
1.1.5 Jonah?
1.1.6 WHUPS?
1.1.7 Skattek?
1.1.8 Chora?
1.1.9 Gollem?
1.1.10 Nag?
1.1.11 Mnemo?
1.2 What other Horde components are rumored to exist?
1.3 I just want web mail. Why do I need Horde?
1.4 How much does Horde cost?
1.5 On what platforms does Horde run?
1.5.1 Does Horde run on Windows 95 or NT/2K/XP?
1.6 How can I get help with setting up Horde?
1.7 Is there a mailing list for Horde and its components?
1.8 I found a bug in Horde. Who should I tell?
2. Obtaining and Installing Prerequisite Packages
2.1 About this FAQ section
2.2 General prerequisites
2.2.1 What does Horde need to run?
2.2.2 How do I build Apache with PHP?
2.2.3 Can I install Horde's prerequisites from RPMs?
2.2.4 Do I really need gettext support?
2.3 IMP prerequisites
2.3.1 What does IMP need to run?
2.3.2 I don't use UW-IMAP. How can I build IMAP support into PHP?
2.3.3 How can I use secure/encrypted IMAP-SSL connections?
2.3.4 How can I use Microsoft Exchange as my IMAP server?
2.3.5 Can I use POP3 instead of IMAP?
2.3.6 Which database should I use?
2.3.7 Can I run Horde without a database?
2.3.8 Should I use wordview or wvHtml?
2.3.9 Do I have to install Sendmail?
2.4 Turba prerequisites
2.4.1 What does Turba need to run?
3. Obtaining and Installing Horde and Components
3.1 Where can I obtain Horde and its components?
3.2 What version of Horde should I be using?
3.2.1 What version of IMP should I be using?
3.3 Can I install Horde and its components as precompiled packages?
3.3.1 How can I make Debian's PHP package use IMAP-SSL?
3.4 How do I install from CVS?
3.5 How do I upgrade via patch files?
4. Configuration and Operation
4.1 General configuration
4.1.1 How can I have Horde in a directory other than /horde/?
4.1.2 How can I change the appearance?
4.1.3 How can I change the phrases used for various features?
4.1.4 How can I provide another translation for Horde/IMP's messages?
4.1.5 How do I let users report problems directly from Horde?
4.1.6 Can I use PHP's safe_mode with Horde?
4.1.7 How can I add a graphic or banner to every page?
4.1.8 Why do old preference values overrule newly locked preference values?
4.1.9 How can I disable the username/password saving feature at the login screen?
4.1.10 I've just installed Horde, how do I log in or create users?
4.2 IMP configuration
4.2.1 Can a single IMP installation serve different virtual hosts?
4.2.2 How can I restrict what my users can do with IMP?
4.2.3 How can I configure IMP's maximum attachment size?
4.2.4 Can I add a custom header to mail sent from IMP?
4.2.5 Where can I find foreign-language dictionaries for spellcheck?
4.2.6 How do I access shared mail folders? Maildir folders? MH folders?
4.2.7 Can IMP show attachments or html inline?
4.2.8 How can I use LDAP for IMP's contact list?
4.2.9 How can I let users change their password through IMP?
4.2.10 How can I let users open new accounts through IMP?
4.2.11 How can I remove maintenance functions in IMP?
4.2.12 Why doesn't the Options button show up in IMP?
4.2.13 Can IMP be used with SMTP authentication?
4.2.14 How can I remove or change the text appended to each email sent through IMP?
4.3 Turba Configuration
4.3.1 How do I migrate my IMP 2.x contacts to Turba?
4.3.2 How do I use LDAP for IMP's Contact List?
5. Troubleshooting and Common Problems
5.1 Common error messages
5.1.1 "Document contains no data"
5.1.2 "Database error (HordeDB): Session: freeze() failed"
5.1.3 "Cannot instantiate non-existent class: hordect"
5.1.4 "top.opener.parent is not an object"
5.1.5 "undefined function: mysql_pconnect()"
5.1.6 "undefined function: bindtextdomain()"
5.1.7 "undefined function: imap_utf7_encode()"
5.1.8 "imap_utf7_decode: Unexpected end of string"
5.1.9 "undefined function: imap_open"
5.1.10 "Wrong parameter count for imap_delete()"
5.1.11 "PostgreSQL Error: attribute 'val' not found"
5.1.12 "Call to unsupported function page_open"
5.1.13 "Cannot extend nonexistent class HordeDefaults"
5.1.14 "Warning: errflg=2, text=Can't get status of mailbox"
5.1.15 "Warning: Undefined index: Send Message"
5.1.16 "Warning: Undefined variable: sid in .../session.inc"
5.1.17 "Warning: Unable to open '/tmp/...'" when attaching
5.1.18 "Call to undefined function: _()" [Horde 2.0]
5.1.19 "Failed opening test.php3 for inclusion"
5.1.20 "Fatal error: Call to undefined function: quote()"
5.1.21 "Fatal error: Undefined class name 'log' in ..."
5.1.22 "Fatal error: Call to undefined function: iswarning() in..."
5.1.23 "output handler 'ob_gzhandler' cannot be used twice in..."
5.1.24 "Warning: Undefined property: _iv in..."
5.1.25 "Fatal error: Allowed memory size of ### bytes exhausted..."
5.2 Verifying Components
5.2.1 How can I tell if my Web server works?
5.2.2 How can I tell if PHP works?
5.2.3 How can I tell if Horde and PHPlib work?
5.2.4 How can I tell if my IMAP server works?
5.2.5 How can I tell if my database works?
5.3 Troubleshooting IMP
5.3.1 Attachments aren't showing up in IMP.
5.3.2 IMP says that every message has an attachment.
5.3.3 Part of the message header is ending up in the body of mail sent from IMP.
5.3.4 In IMP, users can't use any folders besides INBOX.
5.3.5 Mail sent from IMP never actually gets sent.
5.3.6 IMP's Compose window is annoyingly narrow.
5.3.7 Over SSL, Netscape takes forever to load pages.
5.3.8 Internet Explorer users can't access IMP over SSL.
5.3.9 IMP logs me out for no apparent reason at all.
5.3.10 Email sent from IMP is full of backslashes.
5.3.11 After I read a message in IMP, it still shows as unread.
5.3.12 Apache segfaults while I'm using Horde or its components.
5.3.13 Messages sent from IMP have an Authentication-Warning: header added to them.
5.3.14 After logging in successfully, everything just hangs until the IMAP server times out.
5.3.15 #t36
5.3.16 When using IMP plus a POP3 client, users get FOLDER INTERNAL DATA messages.
5.3.17 Users can't get at any folder other than INBOX with Cyrus or Courier imapd.
5.3.18 IMP fails to add new attachments in the Compose window.
5.3.19 IMP displays "There are no parts that can be displayed inline" for all my messages.
5.4 Troubleshooting Turba
5.4.1 When adding a new address from IMP I get an error that it is already in the address book.
5.4.2 Why does Turba give the error "Undefined index: socket ..."
5.4.3 Added attribute names not working with ldap
5.4.4 LDAP queries empty after upgrading to Turba 1.2
5.4.5 Notice: Undefined index: businesscategory
5.5 Troubleshooting Trean
5.5.1 Can't save bookmarks or categories.
5.6 Troubleshooting Chora
5.6.1 Why do I get a 404, Object not found error when clicking on any cvsroot subdirectories?
6. Miscellaneous
6.1 Who maintains this FAQ?
6.2 Can I maintain a local copy of this FAQ?
6.3 Where can I find this FAQ?
6.4 How can I scale IMP to thousands of users?
6.5 I want to contribute to Horde.
6.6 Where did the names of the components come from?

1. General Information

1.1 What is..

1.1.1 What is Horde?

Horde [http://www.horde.org] is both a piece of software and a project. The Horde Project comprises a set of Web-based productivity, messaging, and project-management applications, each of which is described below. The Horde Framework is a common code-base used by Horde applications, including libraries and a common user interface. Horde and its components are written in PHP [http://www.php.net/].

1.1.2 What is IMP?

IMP [http://www.horde.org/imp/] is the Internet Messaging Program (formerly, among other things, the IMAP webMail Program), a PHP-based webmail system and a component of the Horde project. IMP is the most mature of the Horde components, and is the most widely deployed (thus far!). IMP, once installed, accesses mail over IMAP, thus requiring little to no special preparations on the server on which mail is stored.

IMP offers most of the features users have come to expect from their conventional mail programs, including attachments, spell-check, multiple folders, and multiple-language support.

1.1.3 What is Turba?

Turba [http://www.horde.org/turba/] is the address book and contact management component of Horde. It replaces the simple contacts manager that was part of earlier IMP versions.

1.1.4 What is Kronolith?

Kronolith [http://www.horde.org/kronolith/] is a web-based calendar and daily organizer (think Day-Timer). It currently provides a robust web-based calendar for individual users with repeating events, and a smart algorithm to display a whole day of events even if many of them overlap with each other. Future plans include support for shared calendars, merging multiple calendars into a single view, and Palm syncing.

1.1.5 What is Jonah?

Jonah [http://www.horde.org/jonah/] is a PHP-based content and display manager designed to manage a portal-like site using RDF, RSS and Syndicated XML backend content. It is still in the development stage.

1.1.6 What is WHUPS?

WHUPS [http://www.horde.org/whups/] is the Web-based Horde Unified Project System, a PHP-based project management system and a component of the Horde Project. WHUPS implements a very flexible ticket-tracking system, and in the future will be integrated with Chora and other Horde development and project management appliations.

1.1.7 What is Skattek?

Skattek was a Horde interface to Linux firewall management. It is dormant and not developed anymore.

1.1.8 What is Chora?

Chora [http://www.horde.org/chora/] is our tool for viewing code repositories that are managed using the CVS source control system. It provides a web-based view of any CVS repository. It now includes annotation support, visual branch viewing, and human-readable diffs.

1.1.9 What is Gollem?

Gollem [http://www.horde.org/gollem/] is the Horde file manager, providing a common interface to accessing FTP sites, local file system storage, and virtual SQL filesystem storage. Still in development are enhanced file viewing and editing capabilities and CMS-like capabilities.

1.1.10 What is Nag?

Nag [http://www.horde.org/nag/] is a simple, multiuser task list manager.

1.1.11 What is Mnemo?

Mnemo [http://www.horde.org/mnemo/] is a simple note manager (memo pad application).

1.2 What other Horde components are rumored to exist?

Aside from those listed above, the following Horde components have are in various states of completion, from being thought about to being proposed to being worked on to being abandoned:

1.3 I just want web mail. Why do I need Horde?

If you only need the functionality of one component, you can just install that component; however, all of the components rely on common code in the Horde package itself. Whether you install one component or all of them, you need to install Horde. So, if you just want to offer Web-based email (by far, the most common use of Horde applications thus far) you'd need to install Horde and IMP.

1.4 How much does Horde cost?

Horde, and all of Horde's components, are free, having been released under the GNU Public License [http://www.gnu.org/copyleft/gpl.html]. Those of you familiar with open-source software can stop reading now. For those of you who are used to paying for software, no, we're not kidding, it's really free. And not only is it no-cost, but it's yours to modify and redistribute, too; the only restriction is that you can't turn around and make it not free. So, you can download Horde and components and install them on as many computers as you want, and let as many users as you want use it, without having to pay a penny to anyone, and you can make changes to the way it looks or operates, either for local use or for redistribution.

The Horde framework itself is even free-er, being released under the Lesser GNU Public License [http://www.gnu.org/copyleft/lgpl.html]. This basically means that you can use the Horde framework in proprietary programs; if you are considering doing this, please read the license [http://www.gnu.org/copyleft/lgpl.html], and, ideally, let us know [mailto:dev@lists.horde.org].

1.5 On what platforms does Horde run?

Horde is developed on Unix, with the Apache web server, so it should certainly work on any Unix that you can build Apache and PHP on. Being written in PHP means that it should work anywhere that PHP works, though, so if you're not on Unix, please give it a try and let us know [mailto:dev@lists.horde.org] how things turn out!

1.5.1 Does Horde run on Windows 95 or NT/2K/XP?

Horde and all the Horde Components are known to work under Windows NT/2K/XP with Apache and PHP4 with acceptable performance. IMP and Turba, at least, are also believed to work on Windows NT/2K with IIS and PHP4.

1.6 How can I get help with setting up Horde?

The best place to turn after reading the documentation is to the appropriate mailing list [http://www.horde.org/mail/] for the component you're trying to install. Make sure you describe the problem clearly, including all error messages you might have received. Include the version of all the software you're using, including PHP, your web server, your database, any mail or LDAP servers you might be using, and, if the errors are occurring in use, what browser and OS are being used to access it.

Please don't contact the developers or the FAQ maintainer directly. They usually don't have time to deal with individual installations of Horde and its components, being too busy developing and FAQ-maintaining. (Besides, they're probably on the mailing list anyhow.)

1.7 Is there a mailing list for Horde and its components?

Not just a mailing list, but many. The Horde mailing lists [http://www.horde.org/mail/], one for each component and then some, and the most active ones are also archived and searchable [http://marc.theaimsgroup.com/].

Horde users are encouraged to join the announce list and the list specific to their module; those interested in getting their hands a little dirty might also wish to join the horde and dev lists. Those interested in knowing everything that's going on with Horde development might wish to join the machine-generated cvs and bugs list, which report changes in the CVS repository and in the bugs database.

1.8 I found a bug in Horde. Who should I tell?

Before you do anything, take a moment to read this article on bug reporting [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html], and keep its comments in mind when reporting Horde bugs.

Having read that, there are two places where a bug can be reported. If you're on the mailing list [http://www.horde.org/mail/] for the component you think you've found a bug in, send a message to the mailing list, and be sure to keep an eye out for replies. You can also enter the bug into the Horde bug database [http://bugs.horde.org].

Be sure to describe exactly how to reproduce the bug (if you know!), and include all error messages that appeared. Also, specify the versions of Horde, the Horde component exhibiting the bug, and all supporting applications (web server, PHP, database, mail server, etc.). Of course, developers love when bugs come with patches attached; but if you can't write PHP, or can't track down the bug, make sure you let us know about it!

[Return to Table of Contents]

2. Obtaining and Installing Prerequisite Packages

2.1 About this FAQ section

This section of the FAQ addresses issues that routinely come up while installing programs and packages upon which Horde and its components depend. This is not a step-by-step guide to installing any of the components. In other words, you'll still need to read the installation instructions (usually in README and INSTALL) of the prerequisite packages you need to install.

2.2 General prerequisites

2.2.1 What does Horde need to run?

Horde itself requires the following: Horde can use the following, although they are not required:

It should be noted that while a database is not technically required, it is strongly recommended. While Horde can track its sessions in shared memory, development takes place on a system with a database, and the majority of Horde users do the same.

2.2.2 How do I build Apache with PHP?

The following is not meant to spare you from having to read the installation instructions that come with PHP and Apache, but since some of the steps aren't exactly intuitive, the general procedure is as follows:
  1. If your Horde components require PHP support for specific packages (such as IMAP or database support), obtain and install those packages.
  2. Obtain and untar Apache [http://www.apache.org/] and PHP [http://www.php.net].
  3. Move into the apache directory and run ./configure once. Don't worry about arguments for now; this run is just to put things that PHP requires in place.
  4. Move to the php directory and run ./configure --help. Make sure that you note all of the options that your components need.
  5. Run ./configure. A basic configuration with MySQL and IMAP support would be
       ./configure --with-apache=../apache-1.3.12 \
                   --with-mysql=/usr/local/mysql \
                   --with-imap=../imap-4.7c 
      
    where ../apache-1.3.12 is your Apache source directory, and ../imap-4.7c is your UW-IMAP source directory, and /usr/local/mysql is your MySQL installation directory.
  6. Run make install. If all is successful, PHP is installed and ready to go.
  7. Change back to the Apache directory and run ./configure --help. Make sure that you note all of the options your local configuration needs.
  8. Run ./configure. A basic configuration with PHP version 4 would be
       ./configure --activate-module=src/modules/php4/libphp4.a
           
    Note that the file src/modules/php4/libphp4.a does not exist yet. While that seems wrong, that's how it's supposed to work, and it will be built when Apache builds.
  9. Run make and make install. You now have a PHP-enabled Apache installed.

2.2.3 Can I install Horde's prerequisites from RPMs?

In order to provide a seamless RPM-based installation of Horde, the Horde developers have put together customized PHP RPMs with the appropriate --with configure options and with any necessary patches already applied. Those RPMs are available on the Horde FTP site [ftp://ftp.horde.org]. A thorough explanation [ftp://ftp.horde.org/pub/RPMS/i386/php-3.0.16-5horde7.README] of an RPM-based Horde prerequisite installation is available in the README file in the RPMs directory on ftp.horde.org. RPMs for PHP version 4 should be appearing soon.

2.2.4 Do I really need gettext support?

[IMP 2.x]: Horde 1.x and IMP 2.x do not require gettext support.

[IMP 3.x]: At a minimum, Horde 2.x and its applications require gettext support in PHP. Horde will not run without gettext support in php. In addition, if you wish to have the messages translated, then you will require working gettext support in the operating system and the desired locales installed for the languages you want to support. Some operating system specific notes follow.

Debian Linux: You can configure the locale support with the command dpkg-reconfigure locales

(In the rare case that the above command returns an error about locales not being installed, you should use the command apt-get install locales to install and configure the locales).

RedHat Linux: You will need the following RPMS gettext and php-gettext installed.

With RedHat 8.0 and above, if your only getting English no matter what language you select, try re-installing glibc-common. You can do this with a command such as: rpm -Uhv --force glibc-common-2.2.93-5.i386.rpm

Slackware Linux: Make sure you have the glibc-i18n package installed. Make sure in /etc/apache/php.ini you set register_argc_argv = On (it's Off by default) and that you enable the gettext extension by setting adding or uncommenting extension=gettext.so also (also not enabled by default).

SuSe Linux: Make sure you have the glibc-locale package installed. You can install it via the yast configuration tool.

Solaris: On Solaris 7, you must have installed the Partial Locales (SUNWploc) and Supplementary Partial Locales (SUNWploc1) packages. On Solaris 8, you must install the local packages required for the locales you desire (for example, you may need to install SUNWweuos for Western European locales or SUNWmeaos for Middle Eastern locales). Horde assumes that the Sun Solaris gettext implementation is in place. If you have installed the GNU gettext instead or in addition, you may have problems. In particular you must make sure that your web server software and php software are linked to the same version of gettext (e.g. libintl.so). See the file /horde/po/README for more information. (Since Horde 2.2 this information is instead located in /horde/docs/TRANSLATIONS)

On some systems, in particular on Solaris, you will need to rebuild the Horde locale files. You may need to restart the web server after rebuilding the locale files in order for the web server to see the new files.

For more information, see the file /horde/docs/TRANSLATIONS.

2.3 IMP prerequisites

2.3.1 What does IMP need to run?

Aside from the general Horde requirements, IMP 2.2 requires: IMP 2.2 can use the following, although they are not required:

IMP 3.x requirements are the same as above with the following exceptions and additions.

2.3.2 I don't use UW-IMAP. How can I build IMAP support into PHP?

IMP 2.2 and 3.x require that PHP be built with IMAP support; PHP requires that the UW-IMAP "c-client" library be available during compilation. This library is the reference IMAP implementation and is only an IMAP client.

It has nothing to do with the IMAP server that you use; even if you use the Courier or Cyrus IMAP server, you must download the UW-IMAP package and build c-client on the same machine as the webserver. The steps to build only the c-client libraries are as follows:

  1. Move to the top directory of the UW-IMAP distribution.
  2. Run make with the correct argument for your operating system.
  3. ln -s c-client include
  4. mkdir lib
  5. cd lib
  6. ln -s ../c-client/c-client.a libc-client.a
and then point PHP configure's --with-imap option at the top directory of the UW-IMAP distribution. (There is no need to make install in the IMAP distribution.)

2.3.3 How can I use secure/encrypted IMAP-SSL connections?

Some IMAP servers also support IMAP-SSL, which encrypts the connection between the client and the server so as to protect passwords (and, I suppose, message content) which would otherwise be passed in plaintext.

[IMP 2.2]: While IMP 2.2 doesn't support IMAP-SSL directly, by using the stunnel [http://www.stunnel.org/] SSL-tunneling program, you can make IMP use SSL connections; you can even use stunnel on both ends of the connection to make IMP use an SSL connection to an IMAP server which doesn't support SSL connections.

The stunnel FAQ [http://www.stunnel.org/faq/examples.html#ToC6] explains the latter case; if your IMAP server already speaks SSL, you only need to complete the client-side steps.

[IMP 3.x]: If PHP is built against a recent version of c-client, IMP supports IMAP-SSL and POP-SSL natively. Use "imap/ssl" or "pop/ssl" as the protocol type in horde/imp/config/servers.php.

2.3.4 How can I use Microsoft Exchange as my IMAP server?

Note: The FAQ maintainer does not use Exchange, or even NT. The following comes from Alex Howansky, a contributor to the old FAQ, and is included with minor editing exactly as he wrote it then.

[IMP 2.2]: First, you must enable IMAP access in the Exchange Administrator. Expand your main container, and click Protocols. Double-click IMAP4. Check the Enable Protocol check box. Jason Haar also suggests unchecking the Enable Fast Message Retrieval check box if you experience problems with missing attachments. If you only want certain users to have IMP access, you can use the Exchange Administrator to disable IMAP for individual mailboxes.

In horde/imp/config/defaults.php3, edit these settings:

   $default->folders   = "";
   $default->sent_mail = "Sent Items";
   $default->postponed = "Drafts";

For the IMP username, use nt_domain\nt_login_id\exchange_alias. If your Exchange alias is the same as your NT login id, you may be able to use just the Exchange alias for the IMP username. Use your NT domain password for the IMP password.

Once logged in, you will have access to all your Exchange data, including calendar, tasks, contacts, etc. You can use the Imp folder management interface to subscribe and unsubscribe from these folders. Exchange serves up everything via IMAP, and IMP will happily display the contents of the non-email folders as if they were email messages. As a result, they aren't terribly useful and not at all editable, but at least you can see some detail.

2.3.5 Can I use POP3 instead of IMAP?

[IMP 2.2]: Certainly! IMP supports IMAP, POP3, and even NNTP; just specify the appropriate protocol in horde/imp/config/servers.php3 or set

   $default->user_change_servtype = true;          
   $default->user_change_port = true;
or
   $default->servtype = 'pop3';
   $default->port = '110';

in horde/imp/config/default.php3.

[IMP 3.x]: Certainly! IMP supports IMAP and POP3; just specify the appropriate protocol for each server in horde/imp/config/servers.php as described in the comments at the top of that file.

Keep in mind that PHP will always have to be compiled with the --with-imap option to configure, and built against the IMAP c-client libraries, even if you're not going to use it with an IMAP server.

2.3.6 Which database should I use?

The one you already have, of course!

Well, no, that's not exactly true. Horde supports a wide variety of database backends. The most stable databases to use with Horde and IMP are MySQL [http://www.mysql.com/] and PostgreSQL [http://www.postgresql.org/]. Since they are free (and Oracle, Informix and Sybase are not), they're the ones that get the most use by developers and by those installing IMP who don't already have a commercial RDBMS lying around. Choosing between MySQL and PostgreSQL is as much a religious issue as a technical one; MySQL was traditionally considered to be faster but at the expense of robustness and providing commercial-RDBMS features, while PostgreSQL was traditionally considered to suffer slightly in performance and ease of management while being more of an enterprise-class database. Recent versions of PostgreSQL and MySQL are probably of about the same performance. MySql is probably more popular however due to these historical circumstances and considerations.

Those of you with existing Oracle, Informix or Sybase installations will be happy to know that you can use them with IMP as well. The only disadvantage to that is that it might require a little more work to configure, simply because it hasn't been tested to the extent that the free databases have.

2.3.7 Can I run IMP without a database?

[IMP 2.2]: You can, by configuring PHPlib to use shared memory for sessions, but other database functionality such as preferences and non-LDAP contact lists will not be available. We strongly recommend using a database with IMP (and include everything you need for configuring the horde database once your database software is installed).

[IMP 3.x]: You can, by configuring php to use shared memory for sessions, but other database functionality such as persistent preferences will not be available. We strongly recommend using a database with IMP (and include everything you need for configuring the horde database once your database software is installed -- see the files in horde/scripts/db/).

2.3.8 Should I use wordview or wvHtml?

Yes!

Wordview and wvWare [http://wvware.sourceforge.com/] are the old name and the new name of the same program; the name was changed after it was realized that there was the potential for confusion between it and Microsoft's own "wordview".

[IMP 2.2]: The option syntax changed between the last "wordview" version and the first "wvHtml" version, though; if you're using a "wordview" version, make sure you have something similar to

   $default->path_to_mswordview = '/usr/bin/mswordview -o -'

in your horde/imp/config/defaults.php3. If you're using wvHtml, the above variable need only be set to the path to the program, without the trailing arguments.

[IMP 3.x]:

IMP 3.x ships ready for wvHtml support, but with the support disabled by default. Simply edit the file horde/config/mime_drivers.php and uncomment the needed lines.

You will need to uncomment the reference to msword in the $mime_drivers_map['horde']['registered'] array, and then uncomment the stanza later in the file dealing with wvHtml. Last, you will need to make sure that the path specified in the $mime_drivers['horde']['msword']['location'] variable is correct for your system.

Support for excel files is also available via the xlhtml, and is configured the same was as wvHtml (substituting xlhtml for wvHtml, and msexcel for msword were applicable).

2.3.9 Is Sendmail required?

Yes and no.

[IMP 2.2]: There's absolutely nothing at all forcing you to use Sendmail [http://www.sendmail.org] proper, but IMP does require a command-line program on the webserver from which it can send mail, using the same arguments that Sendmail takes. In other words, IMP cannot send mail over SMTP all by itself.

[IMP 3.x]: IMP 3.x can use either a local sendmail program, or connect to a remote SMTP gateway. So if you have access to a remote SMTP gateway, then there is no need to install sendmail (or equivalent) on the webserver.

If you don't need an entire mail server on the machine on which IMP runs, you might like ssmtp [ftp://metalab.unc.edu/pub/Linux/system/mail/mta/]or nullmailer [http://em.ca/~bruceg/nullmailer/]which provides a sendmail-compatible interface, but merely takes the mail and hands it off to the SMTP server of your choice.

Some mailers (like Postfix and qmail) have wrapper scripts that accept the sendmail syntax. These programs should work with IMP as long as the wrapper script accurately implements the sendmail syntax and semantics.

2.4 Turba prerequisites

2.4.1 What does Turba need to run?

Aside from the general Horde requirements, Turba 1.1 does not have any real requirements. However, the following are strongly recommended and will be needed in most cases:

[Return to Table of Contents]

3. Obtaining and Installing Horde and Components

3.1 Where can I obtain Horde and its components?

Horde, as well as any components which have seen a stable release, are available from the Horde FTP site [ftp://ftp.horde.org/] in tar formats. Many are also available in RPM format. The following components are currently available there: All components which have never seen a stable release are available hrough CVS. Step-by-step directions [http://www.horde.org/source/] for obtaining them with CVS are available on the Horde website.

(Please keep in mind that anything that hasn't seen a stable release hasn't seen it for a reason; while some of the components are functional at this point and may be capable of being used in production, they're still not quite ready in the eyes of the developers, and might be buggy in interesting and well-hidden ways.)

Nightly snapshots of all CVS modules are also available at Snapshot site [http://snaps.horde.org/] in tar formats. Since these are unattended, automatted snapshots they may not always be stable or even work at all. They are mostly intended for those who need the CVS code but do not have access to CVS.

3.2 What version of Horde should I be using?

The version of Horde that you use depends on what components you are going to be using with it. In general, any stable components will require Horde 1.2 or Horde 2.x. Anything currently only available in CVS should require Horde 1.3 or Horde 3.0. You can find out which components require which Horde versions by visiting the Horde Version Compatibility [http://www.horde.org/source/versions.php] web page.

3.2.1 What version of IMP should I be using?

The typical site will want to install IMP 3.2.

There are currently four versions of IMP available: 2.2, 3.0, and 3.1, and 3.2. (2.3 was a development version which is no longer available.) There is also a development version, not recommended for production use.

3.2 is the current stable release; most installations will want this, which will maximize features, performance and stability while minimizing bugs and problems. 3.1, 3.0 and 2.2 are also quite stable and secure. The development version is a moving target, with regular updates to CVS which users are expected to keep up with in order to ensure that any potentially harmful bugs, when found, are fixed.

3.3 Can I install Horde and its components as precompiled packages?

On some Linux distributions, it is possible (and possibly easier) to install Horde and any of its stable components from precompiled packages.

We make our own RPMs available; there is a README for Red Hat 6.x [ftp://ftp.horde.org/pub/RPMS/noarch/rh6/horde-latest.README] and a README for Red Hat 7.x [ftp://ftp.horde.org/pub/RPMS/noarch/rh7/horde-latest.README] in the RPMs directory on the Horde FTP site which explain the procedure.

Debian users can install IMP through their package manager as well; the IMP packages are available in the stable distribution [http://packages.debian.org/stable/web/imp.html].

3.3.1 How can I make Debian's PHP package use IMAP-SSL?

Jason Healy [mailto:jhealy@logn.net] contributed these instructions for building PHP with IMAP-SSL support. He tested them on a Debian testing system (Woody) with PHP 4.0.5-2.

Find a nice quiet directory (replace /usr/local/src or your favorite source tree location:):

   mkdir /usr/local/src
   cd /usr/local/src

Get the source to the PHP IMAP package (you must have deb-src: lines in your /etc/apt/sources.list for this to work)

   apt-get source php4-imap
This will download and unpack the source to the php4 package.

Make sure that you have all the development tools necessary to build the php4 package. A list of them can be found in /usr/local/src/php4_VERSION.dscM. Install all of those packages with apt-get. Make sure to use libc-client-ssl2000 and libc-client-ssl2000-dev (in non-us) instead of plain libc-client.

Move into the source tree unpacked by Debian:

  cd /usr/local/src/php4-VERSION/debian
Make these two changes: in the file rules, add the line
   --with-imap-ssl \
directly under the line
   --with-imap=shared \
and in the file libc-client.la, change the line
   dependency_libs=' -lpam -ldl -lcrypt'
to read
   dependency_libs=' -lpam -ldl -lcrypt -lc-client -lssl -lcrypto'
(and in case you're wondering, the added flags are given in /usr/share/doc/libc-client-ssl2000-dev/README.Debian).

Then move into the root of the unpacked source directory:

   cd /usr/local/src/php4-VERSION
and build the package (the -us -uc options prevent you from trying to cryptographically sign the binaries):
   dpkg-buildpackage -us -uc -rsudo
You can also use -rfakeroot, or whatever your favorite root enabler is.

Wait for the compile to finish. If it doesn't work, make sure you've installed all the devel packages you need, and then start making burnt offerings.

When the compile succeeds, move up to the root level of the source:

   cd /usr/local/src
and then install all of the new debs that you've created. Note that you must install the new php4-VERSION.deb that is built, as all the modules are compiled against it. You cannot mix your newly-compiled php4 with any existing modules from the debian package system. So if you already have php4, php4-gd, and php4-imap on your system from Debian, you have to install php4, php4-gd, and php4-imap from your new source directory for everything to continue working. In the example above, you'd say (as root):
   dpkg -i php4_VERSION.deb php4-imap_VERSION.deb php4-gd_VERSION.deb

Once that's all done, restart the webserver, and see if SSL works!

NOTES:

If the compile breaks, check the package dependencies in the .dsc file and make sure you have them installed correctly. Also, make sure that the flags you add to the libc-client.la file match those specified in the libc-client-ssl README.

If your webserver refuses to restart, it's probably because you're mixing old and new PHP modules. You cannot just replace the IMAP module with your new compiled version; you must use your newly compiled php4 base, plus ALL the modules you compiled that match those already on your system. dpkg -i should replace the modules on your system with the newly compiled ones without causing any dependency problems.

3.4 How do I install from CVS?

Step-by-step directions [http://www.horde.org/source/] for obtaining the software with CVS are available on the Horde website. In addition, please note the following issues which often come up:

3.5 How do I upgrade via patch files?

Upgrading from the patch files is an easy way to upgrade the code base. Note however that it is preferable to upgrade from the tar files or from CVS/rsync, as the patch files will only update the code and text files and not the binary files such as images, compiled translations, and so on.

How to upgrade via the provided patch files is operating system dependent. The following directions will work for most unix based systems. Consult your operating system software documentation for additional information or for information on using patch sets for other operating systems.

First, make sure you meet all the pre-requesites for the new version. See the appropriate section of this FAQ for more information.

Next, download the patch file into the directory where the software resides. For Horde use your Horde directory, for IMP use your IMP directory, and so on. The following examples will use IMP as an example, and assume you have already downloaded the patch file to the imp directory.

It is advisable, for various reasons, to stop your Horde web services before you do an upgrade, and restart them afterwards. While not always required, doing so may help provide a more successful upgrade.

  • cd imp
  • gunzip patch-imp-3.1-3.2
  • patch -p1 < patch-imp-3.1-3.2
  • cd po
  • make

    As the upgrade process does not change your configuration files, but rather only operates on the *.php.dist files in the configuration directories. So you will need to manually compare your configuration files to their respective *.dist version, and merge in any changes or additions needed.

    Be sure to check for a file called docs/UPGRADING or docs/UPDATE for additional information such as updates to database layouts or other changes which may be needed. This file will not always exist (if no additional steps are needed when upgrading) so don't panic if it isn't there!

    If you shut down your web services, then restart them at this point. Even if you did not shut down your services before the upgrade, in some cases you may need to restart your web server at this point anyway.

  • [Return to Table of Contents]

    4. Configuration and Operation

    4.1 General configuration

    4.1.1 How can I have Horde in a different directory than /horde/?

    There are usually two changes that people want to make as to how the URL to a Horde component appears in the browser. If only offering one component -- say, IMP -- then one often wants to have a url of
       <http://webmail.example.com/>
    instead of
       <http://webmail.example.com/horde/imp/>
    If offering multiple Horde components -- say, IMP and Troll -- one often wants to have
       <http://horde.example.com/mail/>
    and
       <http://horde.example.com/usenet/>
    instead of the longer versions with the /horde/ component.

    To make a single Horde component appear at the root directory of the webserver, add aliases to your webserver's configuration file for the /horde/ directory, and make the /horde/componentname/ the server's document root, and restart your web server.

    For example, to make IMP appear at the root directory with Apache, add the following to the httpd.conf:

       Alias /horde/ /usr/local/apache/htdocs/horde/
       Alias /imp/   /usr/local/apache/htdocs/horde/imp/
       DocumentRoot  /usr/local/apache/htdocs/horde/imp
    

    (substituting your own directory names for the defaults above). Then, make sure links within Horde are correct as follows:

    [Horde 1.2]: Modify the following variables in /horde/config/horde.php3:

       $default->horde_root_url      = '/horde';
       $default->horde_graphics_url  = $default->horde_root_url . '/graphics';
       $default->horde_include_dir   = './templates';
    
    

    Note that the above are relative to the URL, not to the filesystem; the alias we added to the webserver will ensure that /horde works for anything not included in the component (such as problem reporting).

    Lastly, configure the Horde component (e.g. IMP) to be at the root of the webserver.

    [IMP 2.x]: Modify the following values in the file /horde/imp/config/defaults.php3 :

       $default->root_url      = '';
       $default->graphics_url  = $default->root_url . '/graphics';
       $default->include_dir   = './templates';
    

    Note that the root_url is the empty string '', and is NOT '/'!

    [IMP 3.x]: Modify the $this->applications['imp'] array in horde/config/registry.php and change the value of the webroot as follows:

       'webroot' => '/imp',
    

    With the above settings, going to

       <http://yourserver.example.com/>

    will take the user right to the IMP login screen.

    In the case where one wants to run more than one Horde component but omit the /horde/ part of the URL, configure the webserver to treat the /horde/ directory as the root document directory, and add an alias to make sure links into it still succeed. In Apache:

       Alias /horde/ /usr/local/apache/htdocs/horde/
       DocumentRoot /usr/local/apache/htdocs/horde
    

    (substituting directory names as appropriate).

    [Horde 1.x]: Configure the file /horde/config/horde.php3 as above, and configure the root URL of the component (/horde/component/config/defaults.php3) as follows:

       $default->root_url      = '/componentdir';
       $default->graphics_url  = $default->root_url . '/graphics';
       $default->include_dir   = './templates';
    

    replacing componentdir with the name of the directory containing the component. Users will then be able to access components at URLs like

       <http://yourhost.example.com/imp/>
       <http://yourhost.example.com/troll/>
    

    [Horde 2.x]: For Horde 2.x and it's components, modify the file /horde/config/registry.php in a similar way. At a minimum, you will need to change the horde application stanza, changing the webroot entry from 'horde' to '' (the empty string, not '/').

    Finally, modify the file horde/config/conf.php to change the cookie path from "/horde" to "/" as in:

       $conf['cookie']['path'] = '/';
    

    4.1.2 How can I change the appearance?

    [Horde 1.2]: To change the basic look and feel of components based on Horde 1.2, change the settings in /horde/config/html.php3 and in /horde/componentname/config/html.php3. The settings for various colours, fonts, logos, and screen elements sizes are found within, with explanatory variable names.

    [Horde 2.0]: For Horde 2.x and its components, configure the settings in /horde/config/html.php and in /horde/componentname/config/html.php. The settings for various colours, fonts, and styles are found within, with explanatory comments and variable names.

    [Horde 1.2]: In Horde 1.2, you can also add items to the bottom of the left-hand menu by adding them to /horde/config/menu.txt. This entry:

       http://www.example.com/<Our Website>logo.gif
    

    would make a menu item entitled "Our Website", place /horde/graphics/logo.gif beside it, and link it to http://www.example.com/.

    Similar functionality is available on a Horde 1.2 component-to-component basis to add items to the top of the left-hand menu. Add your entries in /horde/componentname/config/menu.txt, and using the component's graphics directory.

    [Horde 2.0]: In Horde 2.x, you can add Horde modules to the bottom Horde navigation bar by modifying /horde/config/registry.php. This is not as easy or flexible as the Horde 1.x method above.

    You can modify most Horde 2.x components' navigation bars (at the top of screen) by similarly modifying the /horde/componentname/config/menu.php file. Follow the instructions in the comments found in the file. This provides a very easy way to add links to the various Horde component navigation menus.

    4.1.3 How can I change the phrases used for various features?

    You may wish to alter some of the text in an existing language -- to match the terminology used locally, for instance.

    [Horde 1.2]: In Horde 1.2, you need only find the text in question in the locale directory for the language in question and alter it there. For instance, if you want the Horde sign up form to read "Welcome to Foo" instead of "Welcome to Horde", you would change the $lang->welcome_to_horde variable in /horde/locale/en/signup.lang to your phrase. Similar functionality can be found in the locale/ directory of Horde components.

    [Horde 2.x]: In Horde 2.x, you change strings by changing them in the locale files for the desired language(s). To change the US English translation, you will need to create a new US English (en_US) locale, as one normally does not exist, and modify the translations in that file. See the following FAQ entry for information on creating a new locale file.

    To change the translation for a locale, you must first change the locale files and then recompile them. Find the appropriate files in /horde/po/, named by the locale name. Edit the translation(s) in this file to suite your needs. Then compile the locale files using the provided Makefile. For Horde 2.x components, follow the same steps using the /horde/componentname/po files.

    If you are having difficulty finding the file which contains the phrase you want to change, the following Unix command may be of assistance:

       find horde/ -type f -exec grep -li 'Your Phrase' {} \;
    

    where horde/ is the root directory of your Horde installation.

    Note: The following question may also be of help to you if you are changing the locale files.

    4.1.4 How can I provide another translation for Horde/IMP's messages?

    [Horde 1.2]: If you want to provide an entirely new language translation for Horde or one of its components, in Horde 1.x:

    1. Find the two-letter ISO country code [http://www.w3.org/WAI/ER/IG/ert/iso639.htm] for your language.
    2. Copy the contents of locale/en/ for your component to locale/yourcountrycode/. (Or, if you are more familiar with a language already provided other than English, copy that instead, since you will be using that translation to base yours upon.)
    3. In each file within the directory you just created, replace the English (etc.) text with the equivalent text in your language.
    4. Add your language to config/lang.php3 for Horde or the component you changed.
    5. Mail your new translation to the developers [mailto:i18n@lists.horde.org] so that we can include it in the distribution!

    [Horde 2.x]: Horde 2.x uses GNU gettext for internationalization (i18n) and localization (l10n). See horde/po/README for more information. (Since Horde 2.2 this information is instead located at horde/docs/TRANSLATIONS)

    To create a new translation:

    1. Go to the horde/po directory (for other components go to horde/componentname/po)
    2. run xgettext.sh to generate a messages.po file
    3. rename the messages.po file base on the language you are using. For example, for Dutch (nl_NL) you would rename the file to nl_NL.po
    4. Adjust the header lines (dates, authors, etc) of the file, and remove the first #, fuzzy line
    5. Translate the text in the msgid lines into the appropriate msgstr lines.
    6. Compile the new file using the included makefile (make install)
    7. If the language does not already exist in horde/config/lang.php add any required entries for it in that file. You may want to add a two-letter alias for the language, and if it uses a non-ascii character set you should define that also in the $nls['charsets'] array.
    8. Mail your new translation to the developers [mailto:dev@lists.horde.org] so that we can include it in the distribution!

    4.1.5 How do I let users report problems directly from Horde?

    Horde comes with a problem-reporting form.

    [Horde 1.2]: To enable it in Horde 1.2, make the following configuration changes to Horde in /horde/config/horde.php3:

       $default->problem_email     = 'your problem-report email address';
       $default->problem_reporting = true;
    

    and users will be presented with a 'Problem?' menu item which leads to a problem-report form.

    [Horde 2.0]: In Horde 2.0, configure it in /horde/config/horde.php by modifying the following lines:

       // Should we display a problem reporting link in Horde application
       // menus?
       $conf['problems']['enabled'] = false;
    
       // If so, where should problem report emails be sent?
       $conf['problems']['email'] = 'postmaster@example.com';
    

    Set the first flag to true and then modify the email address to be the address where you want the problem report sent.

    4.1.6 Can I use PHP's safe_mode with Horde?

    [Horde 2.0]: PHP's safe_mode is not officially supported for Horde 2.x. Many have tried to use it, and have reported various levels of success. To run in safe_mode you will need to modify the PHP safe_mode settings. You may also have to change some code in Horde or other Horde components in order to make things work properly. Some of the known issues are not being able to set php maximum execution time, problems with spell checking, not being able to use Sendmail (without modifying the php safe_mode configuration), and problems with any sort of file uploads (adding attachments in IMP, file uploads in gollem, etc).

    If you run the Apache web server with virtual hosts and with PHP's safe_mode enabled by default, you can use the Apache PHP4 module configuration command php_admin_value in your main Apache configuration file to remove safe_mode for the Horde virtual host. For example:

    <VirtualHost ...>
    ...
      <Directory ...>
        ....
        <IfModule mod_php4.c>
           php_admin_value safe_mode Off
           ...
        </IfModule>
        ...
      </Directory>
      ...
    </VirtualHost>
    

    4.1.7 How can I add a graphic or banner to every page?

    [Horde 2.0]: You can add content to the top of every page in a horde component by adding appropriate code to the file templates/common-header.inc for that component. You can add content to the bottom of every page in a horde component by adding appropriate code to the file templates/common-footer.inc for that component.

    4.1.8 Why do old preference values overrule newly locked preference values?

    [Horde 2.0]: Any user preferences already set and stored in the preference storage container will overrule any newly locked preferences that may be set by the administrator.

    Thus if users select and save their own values for an unlocked preference, and then the administrator decides to lock that preference value, any previously set user values would overrule the new locked value set by the administrator.

    Therefore, if when locking a preference for which users have already set values you wish that all users conform to the new locked setting, you must empty out the stored preference values in the preference storage container for all users.

    4.1.9 How do I deactivate the username/password saving feature at the login screen?

    This is a function of some web browsers called AutoComplete. It can be disabled in the browser or via the html code on the server. Horde does not currently disable this via html code as the method for doing so is not XHTML 1.0 compliant.

    This is best done by disabling the feature in your web browser. How to do this depends on your browser. See the documentation for your browser for information on how to accomplish this.

    Some browsers let you selectively erase your AutoComplete data. How to do this would vary depending on your browser. For example, in Microsoft's Internet Explorer you can use the following sequence to erase all your stored autocomplete data: From the menu bar at the top of your browser, choose: Tools -> Internet Options -> Content Tab -> AutoComplete Button -> Clear Forms.

    You can also selectively delete individual items. For example, in Internet Explorer, while the cursor is in a form element, put in at least one letter so that the AutoComplete responses are made visible. Using your arrow keys, scroll down to highlight the response you want to erase. Push the Delete key on your keyboard.

    If you wish to disable this for your site, you can do so by modifying the html code. This may make upgrading your installation more difficult, so think twice about this before doing it.

    You can edit the source code for the login form and add autocomplete="off" to the form to disable autocomplete for all fields in the form. For example:

       <form method="post" action="/path" autocomplete="off">
    
    

    You can also use the attribute in individual form fields to disable autocomplete only for that field. For example:

       Password: <input type="password" name="pass" autocomplete="off" />
    
    

    You can also disable it in a form, and then enable it for certain fields in a form, or vice versa, by using the above techniques and setting the autocomplete attribute to "on" or "off" where desired.

    4.1.10 I've just installed Horde, how do I log in or create users?

    [Horde 2.0]: Horde is very flexible in how it can authenticate users, allowing for many different types of authentication. Because of this, there is no single answer for how you authenticate users; the answer will depend on your particular setup and needs.

    In most cases, you will want to use an existing user database. If not, you will need to create a new user database of some sort on your own.

    Once you know what type of user database you want to use, you must configure Horde and possibly some other Horde applications (like IMP, gollem, etc) to use that authentication source. For Horde, you do this in the files horde/config/horde.php and horde/config/registry.php. If you choose to use IMP to authenticate users (e.g. by having IMP log into the IMAP or POP3 server) you must configure horde/imp/config/servers.php appropriately also.

    Note: the admin user which is sometimes referred to in the mailing lists ONLY applies to the latest development version (CVS HEAD version) and IS NOT available in the release versions.

    Some special notes for some of the authentication methods are:

    4.2 IMP configuration

    4.2.1 Can a single IMP installation serve different virtual hosts?

    If you have your webserver set up to answer requests from multiple domains, you can use those virtual hosts to ensure that mail is sent with the appropriate From: header. In other words, when someone goes to
       <http://example.com/webmail/>
    mail will be sent from username@example.com, and when they go to
       <http://example.net/webmail/>
    mail will be sent from username@example.net.

    [IMP 2.2]: To do this, set the following values in /horde/imp/config/defaults.php3:

       $default->server      = $SERVER_NAME;
       $default->from_server = $SERVER_NAME;
    

    Note that the above will allow someone to go to a different virtual host than the one they are intended to use, after which their mail will come from the unintended virtual host.

    [IMP 3.x]: It is possible in Horde 2.x and IMP 3.x to use virtual hosts, but at this time we have no instructions for doing so. You can check the IMP mailing list archives for information.

    4.2.2 How can I restrict what my users can do with IMP?

    [IMP 2.2]: There are a number of IMP features and functions which can be disabled in imp's configuration file, /horde/imp/config/defaults.php3.

    They are:

    [IMP 3.x]: IMP 3.x contains similar functionality in the files horde/imp/config/conf.php and /horde/imp/config/prefs.php. See the comments in those files for more information.

    When changing settings in /horde/imp/config/prefs.php you can set the "value" field for a preference to set the default value of that preference. If you want to force users to use that value, and not allow them to change it, you must also set the "locked" field to true.

    4.2.3 How can I configure IMP's maximum attachment size?

    By default, PHP limits uploaded files to 2 MB, and this limit applies to attachments on messages sent from IMP. To change this value, edit the following value in your php.ini (or, in PHP3, php3.ini):
       upload_max_filesize = number of bytes
    
    You will need to restart your web server after this change.

    4.2.4 Can I add a custom header to mail sent from IMP?

    To add custom SMTP headers to mail sent from IMP, place the headers in /horde/imp/config/header.txt. Make sure that your header is the last line in the file! You can include PHP variables by enclosing them in percent signs ("%"). One useful header is
       X-Originating-IP: %REMOTE_ADDR%
    
    which follows a de-facto standard adhered to by Hotmail, Yahoo Mail, and Dejanews (to name but a few) of listing the address of the computer at which the mail message was composed.

    Note that these are email headers, not body text. If you want to add an advertisement for your webmail service, or a similar announcement, to outgoing mail, put it at the bottom of the message (which is the standard location) by placing the text in /horde/imp/config/tailer.txt.

    4.2.5 Where can I find foreign-language dictionaries for spellcheck?

    Oxford University's archive provides wordlists [ftp://sable.ox.ac.uk/pub/wordlists]  for the languages in IMP's spellcheck (and many more!), as does the International ispell Home Page [http://ficus-www.cs.ucla.edu/ficus-members/geoff/ispell-dictionaries.html].

    4.2.6 How do I access shared mail folders? Maildir folders? MH folders?

    All of the above are transparent to the IMAP protocol itself, and are thus transparent to IMP. If you can tell your IMAP server to serve the type of folders that you want to serve, then IMP can read them.

    Both Maildir and shared folders are supported by Courier-IMAP [http://www.inter7.com/courierimap/], although it does not support standard mbox format mailboxes. MH folders are supported by UW-IMAP [http://www.washington.edu/imap/].

    Note that you can not use folders with POP3 as the POP3 protocol does not contain any support for folders. If you want to use folders then you must configure IMP to use IMAP rather than POP3 access.

    4.2.7 Can IMP show attachments or html inline?

    IMP is capable of showing certain attachments inline (i.e., in the message body, rather than appearing in a new window on request), but in some cases it risks exposing the user to a security problem in the browser: by enabling inline HTML, any javascript (ActiveX, Java, etc.) in the attachment will be executed by the browser. Enabling inline HTML attachments is strongly discouraged.

    Of course, this will only work for elements that could be part of a regular HTML page. In particular, images cannot be part of in a regular HTML page (they have to be a separate file with an >IMG< tag to include them in an HTML page), and can thus not be inlined.

    [IMP 2.2]: Before any attachments will appear inline, inline display must be turned on globally in /horde/imp/config/defaults.php3 by setting one or both of the following variables (depending on IMP version) as shown:

       $default->inline_in_parts_list = false;
       $default->text_parts_inline = true;
    
    After this, for each MIME type you wish to have displayed inline, modify the entry in /horde/imp/config/mime.php3:
       'inline' => true,
    

    Note that some mime types (like text/html) may have multiple entries in the mime.php3 file. Pick the one(s) that meet your needs.

    [IMP 3.x]: Edit the file horde/imp/config/mime_drivers.php to enable inline support for the mime types you wish to have displayed inline. Simply set the 'inline' array element for that mime type to 'true' to enable a type. As noted above, not all mime types can be shown inline; if there is no 'inline' array element for a mime type than that type can not be viewed inline.

    For example, to enable inline html support you would set:

    $mime_drivers['imp']['html']['inline'] = true;
    

    4.2.8 How can I use LDAP for IMP's contact list?

    For LDAP searches to work in IMP, LDAP support must have been compiled into PHP.

    [IMP 2.2]: To configure IMP to allow LDAP searches in the contact list, first enable LDAP in /horde/imp/config/defaults.php3:

       $default->use_ldap_search = true;
    

    Then, in /horde/imp/config/ldap.php3, specify your LDAP servers. An example LDAP server configuration is available in /horde/imp/config/ldap.php3.dist.

    [IMP 3.x]: IMP 3.x no longer has a built-in address book, but instead uses the Horde module Turba for an address book. See the Turba faq section for information on configuring Turba for LDAP support. You must have Turba installed and working before you configure IMP to use it for address books.

    To configure IMP to use one or more Turba directories, you modify the file horde/imp/config/prefs.php to set the value of the $_prefs['search_sources'] array. The 'value' field of this array needs to be set to a tab delimited set of Turba directory sources. IMP will then use these sources for directory lookups.

    4.2.9 How can I let users change their password through IMP?

    [IMP 2.2]: To enable password changes through IMP, set the following in /horde/imp/config/defaults.php3:

       $default->change_password = 'poppassd.php3';
       $default->poppassd_server = $SERVER_NAME;
       $default->poppassd_port   = '0';
    

    You will have to install a poppassd server [http://www.netwinsite.com/poppassd/] on your IMAP server for the above to work. Note that that poppassd won't work out of the box unless you're using SunOS from 1993; you'll have to tell it what to expect from your passwd command at the top of poppassd.c.

    If you're using a recent version of Linux that authenticates via PAM, Jacob Coreil observes that a modified and PAM-ready version of poppassd [ftp://ftp.ceti.com.pl/pub/linux/poppassd-1.8-ceti.tar.gz] is also available.

    You can also set

       $default->change_password
    
    to the URL of a dedicated password-changing program at your site, or you can change
       $default->poppassd_server
    
    to point to a central password server at your site which runs poppassd.

    [IMP 3.x]: IMP 3.x does not include support for changing passwords. You can download a seperate Horde module called passwd to add this functionality.

    4.2.10 How can I let users open new accounts through IMP?

    [IMP 2.2]: There is rudimentary account-signup functionality built into Horde 1.2 (IMP 2.2), which will allow users to fill out a form to request an account, and then send the collected data to a specified email address. To enable it, set the following in /horde/config/horde.php3:
       $default->signup       = true;
       $default->signup_email = 'address which receives account requests';
    
    There is currently no automated account creation facility in IMP. If you feel you are capable of writing this (meaning that you know how to write secure setuid programs!), look at /horde/signup.php3. Keep in mind that allowing users to create accounts without any sort of admin authorization might not be a good thing.

    [IMP 3.x]:This functionality is not available in Horde 2.x or IMP 3.x at this time.

    4.2.11 How can I remove maintenance functions in IMP?

    [IMP 3.0]: You need to disable each maintenance function individually. You can do so by editing the file horde/imp/config/prefs.php. You need to locate the stanzas for rename_sentmail_monthly, delete_sentmail_monthly, delete_sentmail_monthly_keep, purge_trash, purge_trash_interval, and purge_trash_keep.

    For each stanza, set the 'value' field to 0 (zero) and the 'locked' field to true.

    [IMP 3.1]: To disable the maintenance functions by default for all users (but still allow individual users to choose to turn it back on) edit horde/imp/config/prefs.php, locate the stanza for $_prefs['do_maintenance'], and set the 'value' field to 0 (zero).

    To prevent maintenance functions completely (so even individual users can not enable it for themselves), simply edit horde/imp/config/prefs.php, locate the stanza for $_prefs['do_maintenance'], and set the 'value' field to 0 (zero) and the 'locked' field to true.

    4.2.12 Why doesn't the Options button show up in IMP?

    [IMP 3.x]: In order for the Options button to show up, you need to make sure you have created a preferences storage container. This means you must have either a database or LDAP backend in place and configured. For more information see the file horde/docs/INSTALL.

    You will also have to configure Horde to use the preferences container. This is done in the Preference System Settings section of the file horde/config/horde.php.

    4.2.13 Can IMP be used with SMTP authentication?

    [IMP 3.x]: Horde and IMP can support SMTP authentication, but only if the SMTP server take the same authentication credentials as the POP/IMAP server (which would generally be the case). Simply edit /horde/config/horde.php as per the comments in that file, e.g.
    $conf['mailer']['params']['auth'] = true;
    

    4.2.14 How can I remove or change the text appended to each email sent through IMP?

    [IMP 3.x]: IMP automatically appends the content of the file /horde/imp/config/trailer.txt to each email it sends. You can disable this by setting the configuration option $conf['msg']['append_trailer'] to false in your /horde/imp/config/conf.php file. If enabled, you can change the message by simply editing the contents of /horde/imp/config/trailer.txt to suit your needs. Please note that this is a text file, and should not contain html or php code but only normal text.

    4.3 Turba Configuration

    4.3.1 How do I migrate my IMP 2.x contacts to Turba?

    Use the script imp/scripts/imp2turba.pl from IMP 3.x (requires perl with appropriate sql support).

    4.3.2 How can I use LDAP for IMP's contact list?

    You need to modify horde/turba/config/sources.php to specify your ldap server and its attributes. The documentation in the file is pretty complete, and there are some examples using public ldap directories.
    [Return to Table of Contents]

    5. Troubleshooting and Common Problems

    5.1 Common error messages

    5.1.1 "Document contains no data"

    The Netscape error message, "Document contains no data", only tells you that nothing was sent from the web server to the browser. In other words, something went quite wrong, yet you've no idea what.

    In order to get an idea of what really happened, take a look in the web server's error log, in which more verbose errors should be found. There is a good chance that the error is caused by omitting IMAP support from PHP; you can check whether that is the case by examining your server configuration with a PHP script such as the following:

       <?php phpinfo(); ?>
    

    Don't confuse PHP's IMAP support with Apache's mod_imap, which refers to image maps.

    5.1.2 "Database error (HordeDB): Session: freeze() failed"

    [IMP 2.2]: Occasionally, the following message will be produced upon login or logout:

       Database error (HordeDB): Invalid SQL: INSERT INTO active_sessions 
       VALUES ('562493df1fa64bc81db7b0deb86fc019','HordeSession',
       '70ee728055533b7ad9fc0bacfb8ecde01718b97968eb65bc79b418d12c0dc0e9')
       Database error (HordeDB): Session: freeze() failed.
    

    This is produced by a race condition in PHPlib. When two pages try to update the session table at once, the update can sporadically fail. This is more likely to happen at logout from IMP (due to the multiple framesets) than in other use. Charles Wright came up with a patch against PHPlib [http://www.horde.org/faq/contrib/mysql_phplib_freeze.patch] which should fix this for MySQL users.

    Kari Asikainen reports that using PostgreSQL in place of MySQL, or downgrading from PHP 4.0.2 to 4.0.1pl2, eliminates the condition as well.

    5.1.3 "Cannot instantiate non-existent class: hordect"

    [IMP 2.2]: This error is caused by an incorrect PHPlib configuration. Make sure that the appropriate section for your chosen storage class is fully uncommented in the local.inc file in your PHPlib directory. Frequently, during configuration, the HordeCT part of the PHPlib configuration (located below the HordeDB section for your storage class) is accidentally left commented out.

    5.1.4 "top.opener.parent is not an object"

    This error is the result of a bug in Internet Explorer. Stuart [mailto:stuart@eclipse.net.uk] suggests that the following commands (executed on the Windows system on which Internet Explorer is installed) will solve the problem:

       regsvr32 c:\windows\system32\actxprxy.dll
       regsvr32 c:\windows\system32\shdocvw.dll
    

    The FAQ maintainer has not tested the above! Make sure you have a backup of your system before playing with deep Windows magic.

    5.1.5 "undefined function: mysql_pconnect()"

    This error occurs when IMP is configured to use MySQL, but PHP was not built with support for MySQL. Rebuild PHP, ensuring that MySQL support is compiled in, and that the line

       extension = mysql.so
    

    appears in your php.ini (or php3.ini in PHP version 3).

    5.1.6 "undefined function: bindtextdomain()"

    This error occurs when PHP is not compiled with gettext support. As of Horde 2.0, PHP needs to be compiled with gettext support. Rebuild PHP with the --with-gettext option to configure, or if using RPM's install the php-gettext RPM.

    5.1.7 "undefined function: imap_utf7_encode()"

    This error most often occurs when IMP tries to use a folder name with an ampersand (&) in it. The easiest solution is to rename the folder to something without an ampersand in it (on the server, or with a different IMAP client).

    The error can also occur if IMAP support has not been compiled into PHP. Ensure that your PHP installation supports IMAP.

    5.1.8 "imap_utf7_decode: Unexpected end of string"

    This error is another symptom of the ampersand question described in Section 5.1.7.

    5.1.9 "undefined function: imap_open"

    This error is the result of using IMP without compiling IMAP support into PHP. Be sure that your PHP installation supports IMAP, and rebuild it with the --with-imap flag to configure if it does not (or install the php-imap RPM in an RPM installation).

    5.1.10 "Wrong parameter count for imap_delete"

    This error is caused by a bug in older versions of PHP. Upgrade to the current version of PHP, or if you must stay with PHP3, use version 3.0.18.

    5.1.11 "PostgreSQL Error: attribute 'val' not found"

    If IMP produces an error similar to

       Warning: PostgresSQL query failed: ERROR: attribute 'val' not found in
       db_pgsql.inc on line 52
       Database error: Invalid SQL: SELECT val FROM active_sessions WHERE sid
       = '2009f5dd0a3579a38eb0dfb7b9bd2c6f' AND name = 'HordeSession'
       PostgreSQL Error: 1 (ERROR: attribute 'val' not found )
       Session halted.
    

    the usual cause is not a missing attribute nor invalid SQL, but a failure to successfully authenticate with the database. Check your PostgreSQL logs for authentication errors, and make sure you can log in to the database manually using psql with the Horde username and password.

    5.1.12 "Call to unsupported function page_open"

    [Horde 1.2]: This error occurs when PHPlib is missing from the PHP include path. Make sure you have followed the instructions in the README file in your PHPlib directory.

    5.1.13 "Cannot extend nonexistent class HordeDefaults"

    This error is often the result of using incompatible versions of Horde and IMP. The appropriate Horde version to use with a given version of IMP is that with a version number one less than IMP's; for instance, IMP 2.2-pre13 used Horde 1.2-pre13, and IMP 3.0 uses Horde 2.0.

    Information on choosing the appropriate IMP version for your site can be found in Section 3.2.1.

    5.1.14 "Warning: errflg=2, text=Can't get status of mailbox"

    This error usually results from a bug in PHP version 3.0.17. Use version 3.0.18 instead, or upgrade to PHP4.

    5.1.15 "Warning: Undefined index: Send Message"

    This error occurs on Red Hat 7 systems, and results from a bug in Red Hat's php-4.0.4pl1-3 RPM. Update your PHP to the latest available from Red Hat.

    5.1.16 "Warning: Undefined variable: sid in .../session.inc"

    [Horde 1.2]: Horde ships with its own customized (read: fixed) version of PHPLIB (the horde/phplib directory). You must use that version of PHPLIB; it is the only version that is supported, and most of the other versions of PHPLIB will not work.

    This particular error is a sign that Horde is finding a version of PHPLIB other than the one that ships with it. Make sure that session.inc has version 1.1.2.x in the Id tag at the top. Also make sure that your PHP include_path and auto_prepend_file are set properly so that Horde is finding the correct instance of PHPLIB.

    5.1.17 "Warning: Unable to open '/tmp/...'" when attaching

    On some systems (commonly Solaris and FreeBSD), the upload_tmp_dir setting in php.ini (PHP 4.x) or php3.ini (PHP 3.x) must be set to "/var/tmp".

    5.1.18 "Call to undefined function: _( )" [Horde 2.0]

    [Horde 2.0]: This error occurs when PHP is not compiled with gettext support. As of version Horde 2.0, PHP needs to be compiled with gettext support. Rebuild PHP with the --with-gettext option to configure, or if using RPM's install the php-gettext RPM. (_() is a synonym for gettext() in PHP.)

    5.1.19 "Failed opening test.php3 for inclusion"

    [Horde 1.2]: The IMP setup script changes the permissions on the test.php3 script so that it can't be run. This increases the security of your web server by not revealing to intruders information about how PHP is compiled/configured. To use the script while setting up Horde, PHPLIB, or IMP, add read permission for all users to the script:

       chmod a+r horde/test.php3
    

    Remember to remove read permission (chmod a-r) from the file when you have finished testing.

    5.1.20 "Fatal error: Call to undefined function: quote()"

    [Horde 2.x]: You are using too old a version of PHP which doesn't support some needed functions such as the quote() function. Upgrade to a supported version of PHP.

    5.1.21 "Fatal error: Undefined class name 'log' in ..."

    [Horde 2.x]: Your PHP PEAR implementation is missing the PEAR Log package. This is a common problem with the PHP 4.2.1 PEAR for example. You can install it via the network if you have a standalone php/pear command. See the file horde/docs/INSTALL for more information on how to install the required PEAR packages this way. Otherwise you can download the Log package (e.g. from http://pear.php.net/get/Log) and manually install them inside your PEAR directory. You may also need to install the modules Mail_Mime and Net_Socket as well.

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

    5.1.22 "Fatal error: Call to undefined function: iswarning() in ..."

    [Horde 2.x]: After the release of Horde 2.1, the isWarning() function was removed from PEAR, resulting in this error when using a PHP/PEAR released after Horde 2.1 was released. Possible solutions are:

    The same problem exists in some other Horde applications also (e.g. in Kronolith 1.0). The solution is the same (e.g. upgrade to a newer Kronolith version, remove the isWarning() calls, downgrade PEAR).

    5.1.23 "output handler 'ob_gzhandler' cannot be used twice in..."

    [Horde 2.x]: You enabled output compression in both your php.ini configuration file and in your horde configuration file (either horde/config/horde.php or horde/config/conf.php). Disable it in one of these two locations.

    5.1.24 "Warning: Undefined property: _iv in..."

    [Horde 2.2]: This is a bug in Horde 2.2 when used without php mcrypt support. Either upgrade to Horde 2.2.1, or install the mcrypt php extension.

    5.1.25 "Fatal error: Allowed memory size of ### bytes exhausted..."

    Either recompile PHP without the --enable-memory-limit option, or increase the value of memory_limit in your php.ini file.

    5.2 Verifying Components

    5.2.1 How can I tell if my Web server works?

    Testing your webserver is straightforward: place a file containing some HTML (or even just some text) in the directory in which it expects to find its data (in Apache, DocumentRoot), and make the file world-readable. Start up the webserver if it is not already running, and in your browser, load

       <http://hostname.example.com/filename>
    

    (substituting the name of the server and the filename as appropriate). If you see the contents of the file, your web server is running. If you receive an error, check your web server's error log to see what went wrong.

    5.2.2 How can I tell if PHP works?

    The simplest way to test PHP is to create a file, phpinfo.php3, somewhere under your web server's document root, with the following contents:

       <?php phpinfo() ?>
    

    Upon accessing it with a browser, you should be presented with a summary of your PHP configuration. If you see the program text itself, your web server does not know to interpret the file with PHP.

    5.2.3 How can I tell if Horde and PHPlib work?

    [Horde 1.2]: Horde includes a PHP program which will test both your Horde and PHPlib installations. If you have horde installed in the usual location, point your browser at

       <http://hostname.example.com/horde/test.php3>
    

    Verify the following from the information test.php3 offers:

    [Horde 2.0]: Horde includes a PHP program which will test both your Horde and PHP installations. If you have horde installed in the usual location, point your browser at

       <http://hostname.example.com/horde/test.php>
    

    Verify the following from the information test.php offers:

    This page also may have links to test pages for other installed modules, and/or links to other PHP information pages available.

    5.2.4 How can I tell if my IMAP server works?

    The simplest way to test an IMAP server is to send mail to an account on the IMAP server, and then use a standard IMAP client like Netscape Mail, Outlook Express, PINE, mutt, or Eudora Pro to read the mail.

    If you don't have a standard IMAP client handy, or if a standard client fails, you can telnet to port 143 of your IMAP server and try the following exchange (where "normal" server responses are emphasized):

       * OK imap.example.com IMAP4rev1 v12.264 server ready
       0 login yourusername yourpassword
       0 OK LOGIN completed
       0 logout
    

    If you don't get OK LOGIN, then your server is probably misconfigured (unless you are using a specific authentication module such as Kerberos, in which case you will probably have to test it with a real IMAP client or the mtest program included with the UW-IMAP c-client distribution).

    5.2.5 How can I tell if my database works?

    The most straightforward way of testing your database is to create the Horde databases themselves; if the creation proceeds without error, then the database is probably functioning normally.

    You can also use the following code, contributed by mailto:chowes@ics.bc.ca [mailto:chowes@ics.bc.ca]:

       <HTML>
       <BODY>
    
       This is a test:
       <?php
    
          function test() {
             if (!($db = mysql_pconnect(localhost,root,yourpassword))){ return 1; }
    	 if (!($imp = mysql_create_db(testdb, $db))) { return 2; }
    	 if (!($imp = mysql_select_db(testdb, $db))) { return 3; }
    	 if (!($result = mysql_db_query(testdb, "create table testtest ( test char(60))", $db))) 
                 { return 4; }
    	 if (!($result = mysql_db_query(testdb, "insert into testtest values ('hello world!')", $db))) 
                 { return 5; }
    	 if (!($result = mysql_db_query(testdb, "select * from testtest", $db)))
                { echo "$result";return 6; }
    	 if (mysql_num_rows($result)>0)
                echo (mysql_result($result, 0, 0));
    	 if (!($result = mysql_db_query(testdb, "delete from testtest", $db))) { return 7; }
    	 if (!($imp = mysql_drop_db(testdb, $db))) { return 8; }
    	 return 9;
          }
    
          $r = test();
          echo "<BR>result code = $r";
       ?>
       </BODY>
       </HTML>
    

    Then, load the file with your browser. It will create a database, a table, and a row; put data into the row; then delete the row, the table, and the database. If successful, the output will read

       This is a test: hello world!
       result code=9
    

    If it does not, at least you can see where it breaks, by matching the result code with the return statement in the program; the line on which the matching return statement lies is the one which failed. For instance, if result code=1, then mysql isn't running, or a bad host/username/password has been entered.

    5.3 Troubleshooting IMP

    5.3.1 Attachments aren't showing up in IMP.

    Jason Haar reports that if you are using Microsoft Exchange as your IMAP server, enabling the server's "fast download" feature causes Exchange to guess at the size of attachments, leading to incomplete or missing attachment information. Disabling "fast download" in Exchange solves the problem (as does switching to a more robust IMAP server).

    5.3.2 IMP says that every message has an attachment.

    David Fuchs reports that PHP 3.0.14 can cause every message in a mailbox to claim to have attachments that do not exist. Upgrading to a more recent PHP will solve this problem.

    5.3.3 Part of the message header is ending up in the body of mail sent from IMP.

    If, in messages sent from IMP, part of the headers of messages are appearing in the message body, check the file horde/imp/config/header.txt, which contains user-specified headers. If that file contains a blank line, then anything following that blank line will become body text (since the delimiter between headers and body in an email message is a blank line).

    5.3.4 In IMP, users can't use any folders besides INBOX.

    [IMP 2.2]: The most common problem that results in users being unable to access their mail folders is a misconfigured

       $default->folders
    

    in horde/imp/config/defaults.php3. That variable should be set to the location of a user's personal folders, often "mail/" or "Mail/". It must have the trailing slash.

    [IMP 3.x]: There are several settings which can influence this:

    5.3.5 Mail sent from IMP never actually gets sent.

    [IMP 2.2]: If IMP is unable to send mail, first check to make sure that Sendmail (or your Sendmail replacement) is located in the same place that the variable

       $default->path_to_sendmail
    

    in horde/imp/config/defaults.php3 is telling IMP to look. If it is there, make sure you can send mail with it with the following Unix command:

       echo testing | /usr/bin/sendmail your@email.address
    

    replacing /usr/bin/sendmail with your Sendmail path and your@email.address with your email address. You should receive a (mostly empty) email address, or an error message, almost immediately.

    If Sendmail works from the command-line but IMP still refuses to send mail, you may need to turn off PHP's Safe mode, with the following setting in your php.ini (or php3.ini in PHP version 3):

       safe_mode off
    

    Before doing that, be sure to read the Security chapter [http://www.php.net/manual/security.php] of the PHP Manual.

    [IMP 3.x]: If when you press the Send button in the compose window it simply returns the same compose window's contents and no mail is sent, then check that you have PHP file uploads enabled. This is done by setting

    file_uploads=On
    

    in your system's php.ini (PHP 4.x) or php3.ini (PHP 3.x) file.

    If you are using SMTP rather than a local Sendmail (or equivalent) binary, check that you have set the variable

    $conf['mailer']['type'] = 'smtp';
    

    in horde/config/horde.php, and that you have set the smtphost value in horde/imp/config/servers.php for your server entry to the correct smtp host value. Note that this smtphost value will override any existing value for $conf['mailer']['params']['host'] set in horde/config/horde.php.

    If you are using a local Sendmail binary, first check to make sure that Sendmail (or your Sendmail replacement) is located in the same place that the variable

       $conf['mailer']['params'] = array('sendmail_path' => '/usr/lib/sendmail');
    

    in horde/config/horde.php is telling IMP to look. If it is there, make sure you can send mail with it with the following Unix command:

       echo testing | /usr/bin/sendmail your@email.address
    

    replacing /usr/bin/sendmail with your Sendmail path and your@email.address with your email address. You should receive a (mostly empty) email message, or an error message, almost immediately.

    If Sendmail works from the command-line but IMP still refuses to send mail, you may need to turn off PHP's Safe mode, with the following setting in your php.ini file:

       safe_mode off
    

    Before doing that, be sure to read the Security chapter [http://www.php.net/manual/security.php] of the PHP Manual.

    5.3.6 IMP's Compose window is annoyingly narrow.

    [IMP 2.2]: If the Compose window seems too small, first try this setting in your horde/imp/config/defaults.php3:

       $default->screen_size = "large";
    

    Keep in mind that "large" may be too large for users with low-resolution displays. Some suggest changing the value of

       $default->compose_body_cols
    

    to something larger than the default of 80, but since 80-column text is the standard for Internet mail messages (even though you can make your Windows or MacOS mail windows larger!), it is strongly discouraged.

    The file horde/imp/locale/languagecode/openwin.lang also contains some window-size parameters, but is meant more for developer fine-tuning than for site-by-site configuration.

    5.3.7 Over SSL, Netscape takes forever to load pages.

    Certain versions of Netscape have a bug which makes IMP screens take a very long time to load over an SSL connection while not being particularly slow over an unencrypted connection. The bug is with Netscape's handling of keep-alive connections. In order to prevent the browser from having to make one connection to the web server for every file it needs, the HTTP protocol provides "keep-alive", which allows the browser to use one connection to transfer multiple files. Unfortunately, over an SSL connection, Netscape does not notice if the server closes the keep-alive connection (as servers do after a certain period of time), and continues to try to make requests over the now nonexistent connection. Since this happens towards the end of rendering the page in the browser, missing image files is a common symptom.

    It is not clear which versions of Netscape on which platforms suffer from this bug; extensive testing on MacOS showed that any release of Netscape 4 was capable of slowing down as described above, but not all installations would suffer. The bug also has been known to trigger under Windows NT.

    Unfortunately, the only solution to this problem (other than not using Netscape, or not using SSL) is to disable keep-alive on the webserver. In apache, the following entry in /usr/local/apache/conf/httpd.conf will turn keep-alive off:

       KeepAlive Off
    

    This will cause a performance degradation, as browsers will now have to make multiple connections where previously a single connection sufficed. Be sure to monitor performance after making this change to determine if the performance degradation is too severe to maintain. (On a Digital AlphaServer DS20 with two 500MHz processors and 1GB of RAM, the performance change was unnoticeable.)

    5.3.8 Internet Explorer users can't access IMP over SSL.

    Some versions of Microsoft Internet Explorer only understand 40- and 128-bit encryption, but not 56-bit. If a user has a weak-encryption version of Internet Explorer, 128-bit encryption will also be unavailable, but Apache will try to offer 56-bit, and the transaction will fail.

    To tell Apache to only offer 40- or 128-bit encryption, replace the SSLCipherSuite directive in your httpd.conf file with:

       SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
    

    When you restart your webserver, it will only offer 40- and 128-bit encryption, solving the problem. Note that this means that browsers which only support 40- and 56-bit encryption (such as weak-encryption versions of Netscape) will fall back to 40-bit as well.

    Individual users can solve this problem without having to alter the Apache configuration by obtaining a version of Internet Explorer with 128-bit encryption enabled from Microsoft [http://www.microsoft.org/ie/].

    5.3.9 IMP logs me out for no apparent reason at all.

    When IMP returns to the login screen despite not being told to log out, it is usually the result of your session timing out because you were idle for too long. This is a feature, designed to prevent unauthorized use of an IMP session if you walk away from their computer leaving the browser running.

    You may be able to adjust the timeout if you determine it is too short. In PHP4, timeout length is controlled by the following variables in your php.ini file:

    session.cookie_lifetime
    session.gc_maxlifetime
    session.gc_probability
    

    If it is happening too soon to be a timeout, you may have used the file php.ini-optimized or php.ini-recommended from the PHP distribution to configure PHP. Using the php.ini-dist file instead may prevent the erratic logouts.

    If this happens for all users -- or if IMP logins have never succeeded -- check the syslog and the IMAP server log on the mail server, and verify that there are no access controls (such as hosts.allow rules) blocking IMAP connections from the IMP web server (which might be localhost).

    5.3.10 Email sent from IMP is full of backslashes.

    If characters such as ', ", and \ are producing extra backslashes ("\") in IMP, you probably have one of the following settings in your php.ini (or php3.ini in PHP version 3):

       magic_quotes_gpc     = on
       magic_quotes_runtime = on
       magic_quotes_sybase  = on
    

    All magic_quotes options must be disabled for IMP. Remember to restart your web server after changing php.ini settings.

    5.3.11 After I read a message in IMP, it still shows as unread.

    If IMP refuses to mark a message as read after you have read it, you probably have a buggy version of the UW-IMAP c-client library. Upgrading to the current version (and rebuilding PHP against it) should resolve the problem.

    5.3.12 Apache segfaults while I'm using Horde or its components.

    No matter how broken Horde or IMP might be, there are precisely zero conditions in which it should be able to induce a segmentation fault ("core dump" or "segmentation violation" or possibly even "bus error") in Apache or PHP. If such a condition occurs, please inform the developers of PHP by making an entry in their bug database [http://bugs.php.net].

    There is a great explanation of how to debug where the segmentation fault occurs at http://bugs.php.net/bugs-generating-backtrace.php which may be of help.

    5.3.13 Messages sent from IMP have an Authentication-Warning: header added to them.

    While headers in outgoing messages such as

       X-Authentication-Warning: nobody set sender to username with -f option
    

    may sound ominous, they're only pedantically noting what took place when the message was sent. IMP, running as the user "nobody", set the envelope sender (not the From: header!) of the message to "username", using Sendmail's -f option. This makes the message appear to have originated with "username", not "nobody", so that bounces will end up in the right place.

    This can be disabled with Sendmail by removing the authwarnings option from the sendmail.cf file or by adding the web server account to the list of trusted users in the sendmail.cf or submit.cf file; consult your Sendmail documentation for details.

    5.3.14 After logging in successfully, everything just hangs until the IMAP server times out.

    Incorrect configuration causes IMP to hang upon login until the IMAP server times out, producing an error. Occasionally this will only happen for certain users on a particular server. It is usually caused by mis-specifying the name of the directory in which mail folders are found. In IMP 2.2, check the variable $default->folders in horde/imp/config/servers.php3, or the value as specified by the user if the user can specify folder information at login. In IMP 3.x check the folders and namespace values in horde/imp/config/servers.php or the value as specified by the user if the user can specify folder information at login.

    Since everything under this directory is traversed by the IMAP server in order to generate the folder list, accidentally setting this to the user's home directory -- or something higher in the filesystem -- can cause the process to take too long to generate the entire list, leading to IMAP timeouts.

    5.3.15 Users are getting mail sent to "INVALID_ADDRESS@.SYNTAX.ERROR" or "MISSING_MAILBOX_TERMINATOR@.SYNTAX-ERROR.".

    Addresses in the headers such as the above are produced by PHP, not IMP (via the IMAP c-client library), and are most often the result of a user using semicolons instead of commas to separate addresses, such as is done in MS Outlook Express. Discussions on the mailing list tend to conclude that the solution to this is "well, don't do that, then", since both commas and semicolons have their own meanings in the Internet message format standard, RFC 822.

    5.3.16 When using IMP plus a POP3 client, users get FOLDER INTERNAL DATA messages.

    The UW-IMAP server stores the state of a mailbox as a specially-formatted mail message in the mailbox, with the header

       Subject: DON'T DELETE THIS MESSAGE -- FOLDER INTERNAL DATA
    

    The messages do not appear when the mailbox is accessed over IMAP, and appear only once when the mailbox is accessed directly. When accessing the mailbox over POP3, however, that message is downloaded repeatedly, since each time the mailbox is accessed with IMAP, the message is marked as unread.

    The qpopper [http://www.eudora.com/qpopper/] POP3 server for Unix features a compile time option, --enable-uw-kludge, which will cause the server to refrain from offering the IMAP state message to a POP3 client. The current beta version of the UW-IMAP server is reported to no longer use the state message, nor do any other IMAP servers.

    5.3.17 Users can't get at any folder other than INBOX.

    [IMP 2.2]: For the Cyrus and Courier-IMAP imap servers, this is often caused by an incorrect setting in horde/imp/config/defaults.php3. Make sure you have the following:

       $default->personal_folders = 'INBOX.';
    

    The trailing dot is required (and its omission is usually the culprit!).

    See also question 5.3.4 (for any version of IMP).

    5.3.18 IMP fails to add new attachments in the Compose window.

    IMP uses the value of the upload_tmp_dir configuration variable to ensure that attachments are safely uploaded to the web server. If this variable is undefined, IMP is unable to locate the uploaded attachment. To define your upload directory, add something like the following to your php.ini file:

       upload_tmp_dir = /var/tmp
    

    Remember to restart your web server in order for this change to take effect.

    Special note for some Apache 2.0 users:

    If you are running Red Hat or Fedora Core Apache 2.x RPMS, or a Red Hat/Fedora based distribution, you should have a separate /etc/httpd/conf.d/php.conf file. Look inside it for a set of text like this:

    
        SetOutputFilter PHP
        SetInputFilter PHP
        LimitRequestBody 524288  <---- This was the problem on mine
    
    

    Change the LimitRequestBody 524288 line to something larger. It is the maximum allowed size of a httpd request in bytes. You may need to set this about twice as large as the desired size to account for encoding of submitted data.

    From http://lists.horde.org/archives/imp/Week-of-Mon-20030203/029747.html.

    5.3.19 IMP displays "There are no parts that can be displayed inline" for all my messages.

    This is a known problem with PHP 4.2.2/4.2.3 and certain versions of the UW IMAP c-client. If using these PHP versions, either downgrade to UW IMAP c-client 2001a or upgrade to PHP 4.3.0.

    5.4 Troubleshooting Turba

    5.4.1 When adding a new address from IMP I get an error that it is already in the address book.

    This is a bug in the code that has since been fixed. The error is in turba/lib/api.php at about line 93. The incorrect and correct lines are:

    INCORRECT:
        if (PEAR::isError($res) || count($res) > 0) {
    
    CORRECT:
        if (PEAR::isError($res) || $res->count() > 0) {
    
    

    5.4.2 Why does Turba give the error "Undefined index: socket ..."

    This means you have a missing or misconfigured socket and/or protocol parameter value in the params block(s) in /horde/turba/config/sources.php.

    Unless you are trying to use unix sockets rather than tcp/ip connections, set the socket value to '' (meaning no value), and/or set the protocol value to 'tcp'.

    5.4.3 Added attribute names not working with ldap

    When adding new attribute names in the sources.php map section for ldap servers, make sure all the attribute names are completely lowercase. Also make sure that all attributes you add to sources.php are also added to attributes.php. Finally, make sure your ldap ACL's are set correctly to allow them to be viewed.

    5.4.4 LDAP queries empty after upgrading to Turba 1.2

    The 'objectclass' entry for LDAP address book definitions in turba/config/sources.php is respected in Turba 1.2 but wasn't in earlier versions. Set it to use a correct value for your LDAP structure.

    5.4.5 Notice: Undefined index: businesscategory

    Turba has a system of defining what is in a directory or address book which is necessarily complicated by reason that it is flexible enough to map to pretty much anything with no code changes, only configuration file tweaks.

    In turba/config/sources.php, for every backend that you use in Turba, you configure a map. The map defines a mapping between whatever fields exist in the backend directory and what Turba calls those fields and also what kind of data Turba treats them as containing. So if the contact_email field in a database table is an email address, you could tell Turba to map 'email' => 'contact_email'.

    However, Turba needs to then know what 'email' or 'name' are. They're defined in turba/config/attributes.php, which is the set of attributes that any given Turba installation understands. The attributes.php file defines the label for a field and also what kind of data it is - a string, an email address, an enumeration of several options, etc.

    So, back to the problem: you have some attributes in your map that Turba doesn't know about. In sources.php, there's probably a line something like:

        'businesscategory' => 'backend_field_bus_cat',
    

    But there is no 'businesscategory' attribute in your attributes.php. You need to either add an attribute entry, or remove that field, or map it to something else that Turba already knows about.

    In some versions of Turba, the default sources.php file included an example that used attributes that weren't in the default attributes.php file and hence could cause this error. This has since been fixed for newer releases.

    5.5 Troubleshooting Trean

    5.5.1 Can't save bookmarks or categories.

    This usually means one of the following:

    5.6 Troubleshooting Chora

    5.6.1 Why do I get a 404, Object not found error when clicking on any cvsroot subdirectories?

    Some web servers do not support PATH_INFO, or have it disabled by default, in which case this problem will arise. Try to disable PATH_INFO usage by setting $conf['options']['use_path_info'] to false in horde/chora/config/conf.php.

    [Return to Table of Contents]

    6. Miscellaneous

    6.1 Who maintains this FAQ?

    The current maintainer is Eric Rostetter, assisted by the rest of the Horde developers and users.

    6.2 Can I maintain a local copy of this FAQ?

    Well, there's nothing stopping you from doing so. We'd much prefer that you'd link to the master copy [http://www.horde.org/faq/] instead; that way, you're always sure to have the most recent version.

    If you do want to mirror it, give the FAQ maintainer a shout so you can get the PHP source, rather than just the resulting HTML.

    6.3 Where can I find this FAQ?

    The canonical location for the FAQ is
       <http://www.horde.org/faq/>

    6.4 How can I scale IMP to thousands of users?

    Jason Belich has written the Scalable Webmail HOWTO [http://www.horde.org/papers/Scalable_webmail_HOWTO.php] on setting up a large-scale webmail architecture using LDAP, IMAP and IMP.

    6.5 I want to contribute to Horde.

    A wise choice! Of course, we're always happy to have another set of hands, eyes, and brain lobes working on this project-cum-timesink of ours. The first place to start is to make sure you're on the appropriate mailing lists [http://www.horde.org/mail/]; you should certainly be on the dev list, and probably on the bugs and cvs lists if you're working on something that's being worked on by others. Of course, you'll also want to be subscribed to the list dedicated to the component you're working on. Once you've subscribed, post a short note mentioning what you're planning on doing, to make sure that you're not duplicating someone else's work, or reimplementing a feature that was just recently removed! After that, check out your components from the Horde CVS repository [http://www.horde.org/source/], and start hacking!

    6.6 Where did the names of the components come from?

    We're not sure. Those that know aren't telling.

    Seriously, many of the components have somewhat awkward acronyms as their names, such as the Internet Messaging Program, or the Web-based Horde Unified Project System. The maintainer of the FAQ has a suspicion that others were pulled at random from an IKEA [http://www.ikea.com] catalogue. Besides, it's more fun to let you guess.

    [Return to Table of Contents]