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, Horde's web mail component. This is mostly a result of IMP being the most mature and most widely-deployed component.

Please send updates, corrections and comments to faq@horde.org.

Last modified: 7:00am, October 19, 2000 PDT

Table of Contents

1. General Information
2. Obtaining and Installing Prerequisite Packages 3. Obtaining and Installing Horde and Components 4. Configuration and Operation 5. Troubleshooting and Common Problems 6. Miscellaneous

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/].

Horde alone won't do you much good, though; the real functionality is in Horde's components, introduced below.

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, address books, multiple folders, and multiple-language support.

1.1.3 What is Turba?

Turba [http://www.horde.org/turba/] is the address book and contact list component of Horde. It is still in the development stage, but will be an integral component of the next major version of IMP.

1.1.4 What is Kronolith?

Kronolith [http://www.horde.org/kronolith/] is a web-based calendar and daily organizer (think Day-Timer). It is still in the development stage, but is reportedly at the point where several people (mostly developers!) are using it day-to-day.

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 will integrate a bug-tracking system, a FAQ manager, and a browsable CVS repository, and will once functional become the project management system for the rest of the Horde project. WHUPS is still in development.

1.1.7 What is Skattek?

Skattek [http://www.horde.org/skattek/] is a PHP-based interface to Linux firewall management. It is still in the development stage.

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:support@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:support@horde.org] how things turn out!

1.5.1 Does Horde run on Windows 95 or NT?

IMP, at least, is reported to work on Windows NT with IIS and PHP3, with suboptimal performance. Further testing of Horde components on the Windows platform would be welcomed by the Horde developers; if you want to give it a try, please drop us a line [mailto:support@horde.org]. Setting up a functional IMP installation would probably be the most useful test at this point.

Cygnus [http://www.cygnus.com] has reportedly produced CAMP, a port of Apache, PHP, MySQL and IMAP to Windows, but little is known about it (among the developers and FAQ maintainer, at least).

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, are also archived and searchable [http://horde.tydc.com], and another searchable archive [http://marc.theaimsgroup.com/?l=imp] is maintained for the IMP list.

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 Freshmeat editorial on bug reporting [http://freshmeat.net/news/2000/02/26/951627540.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.3 IMP-specific prerequisites

2.3.1 What does IMP need to run?

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

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

IMP requires 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. Unfortunately, the c-client IMAP library used by PHP, and thus by IMP, does not speak IMAP-SSL.

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.

Of course, some would suggest that c-client should speak SSL. Implementing this is left as an exercise for the reader.

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 [mailto:alex@wankwood.com], a contributor to the old FAQ, and is included with minor editing exactly as he wrote it then.

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?

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;
in horde/imp/config/default.php3.

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. The most stable databases to use with Horde and IMP are MySQL [http://www.mysql.org/] 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 tends to be faster at the expense of robustness and commercial-RDBMS features, while PostgreSQL suffers slightly in performance while being more of an enterprise-class database. For what it's worth, the FAQ maintainer uses PostgreSQL because other, non-Horde applications on his machines require features not offered by MySQL.

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?

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).

2.3.8 Should I use wordview or wvHtml?

Yes! Wordview and wvWare [http://www.wvware.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". 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.

2.3.9 Is Sendmail required?

Yes and no. 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.

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/] which provides a sendmail-compatible interface, but merely takes the mail and hands it off to the SMTP server of your choice.

[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 both RPM and tar formats. The following components are currently available there: All components which have never seen a stable release are available only through CVS. Step-by-step directions [http://www.horde.org/cvs/] 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.)

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; in particular, the stable version of IMP requires Horde 1.2. Anything currently only available in CVS should require Horde 1.3.

3.2.1 What version of IMP should I be using?

The typical site will want to install IMP 2.2.

There are currently three versions of IMP available: 2.0, 2.2, and 2.3. (2.1 was a development version which is no longer available.) 2.2 is the current stable release; most installations will want this, which will maximize features, performance and stability while minimizing bugs and problems. 2.0 is also quite stable, but is old, and is missing many features present in 2.2. 2.3 is the development version, and may have parts that do not function correctly, or undiscovered or un-fixed bugs. The development version is also 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 This is really complicated. Is there an easier way?

It is possible (and possibly easier) to install Horde and any of its stable components from RPMs; there is a short README [ftp://ftp.horde.org/pub/RPMS/noarch/horde-1.2.1-1.README] in the RPMs directory on the Horde FTP site which explains the procedure.

Rich Lafferty [mailto:rich@horde.org] has been considering pre-packaged IMP installations which require only untarring and answering some questions, but hasn't yet implemented one. If you're got some time to spare before your installation is ready, and would be interested in testing out such an installation, please let him know.

[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.

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/
   DocumentRoot /usr/local/apache/htdocs/horde/imp
(substituting your own directory names for the defaults above). Then, to make sure links within Horde are correct. 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 to be at the root of the webserver. For example, in IMP's 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 '/'! 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). Configure Horde's 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/>

4.1.2 How can I change the appearance?

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.

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 component-to-component basis, in /horde/componentname/config/menu.txt, and using the component's graphics directory.

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

If you wish to alter some of the text in an existing language -- to match the terminology used locally, for instance -- 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 signup 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.

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.

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

If you want to provide an entirely new language translation for Horde or one of its components:
  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: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 1.2 already comes with a problem-reporting form. To enable it, 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.

4.2 IMP-specific 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.

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.

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

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:

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/footer.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/].

4.2.7 Can IMP show attachments inline?

IMP is capable of showing 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.

Before any attachments will appear inline, inline display must be turned on globally in horde/imp/config/defaults.php3: 

   $default->inline_in_parts_list = false;
After this, for each MIME type you wish to have displayed inline, modify the entry in horde/imp/config/mime.php3: 
   'inline' => true,
Of course, this will only work for elements that could be displayed in a regular HTML page.

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

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.

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

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

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 [ftp://ftp.sri.ucl.ac.be/pub/poppassd/] on your IMAP server for the above to work.

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.

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

There is rudimentary account-signup functionality built into Horde, 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.
[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"

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"

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 the --with-gettext option to configure. Rebuild PHP with gettext support.

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.

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.16.

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"

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 nonexistant 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 2.3 uses Horde 1.3.

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.16 instead, or upgrade to PHP4.

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 is 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, test.php3, somewhere under your web server's document root, with the following contents: 
   <?php php_info() ?>
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 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:

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 <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 deletes 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.

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.

5.3.5 Mail sent from IMP never actually gets sent.

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.

5.3.6 IMP's Compose window is annoyingly narrow.

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 nonexistant 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 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 cookie timing out because you were idle for too long. This is a feature, designed to prevent unauthorized use of an IMP session if you walks away from their computer leaving the browser running.

If it is happening too soon to be a timeout, you may have used the file php.ini-optimized from the PHP distribution to configure PHP. Using the php.ini-dist file instead of php.ini-optimized will 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.9 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.10 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.11 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].

5.3.12 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; consult your Sendmail documentation for details.

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

Incorrect configuration cause 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, either in horde/imp/config/defaults.php3, 
   $default->folders
in horde/imp/config/servers.php3, or as specified by the user. 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.14 Users are getting mail sent to "MISSING_MAILBOX_TERMINATOR@.SYNTAX-ERROR.".

Addresses in the To: header, such as the above, are the result of the unusual behavior of Outlook Express in handling messages that are sent only to Bcc: recipients. The bogus addresses can be ignored.

5.3.15 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.16 Users can't get at any folder other than INBOX.

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!).
[Return to Table of Contents]

6. Miscellaneous

6.1 Who maintains this FAQ?

The current maintainer is Rich Lafferty [mailto:faq@horde.org], 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 [mailto:faq@horde.org] 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 secure is IMP?

Imp is fairly secure. It is not completely secure; any system that claims to be completely secure is holding a rather large foot near its mouth. However, I can say that IMP is more secure than many applications that you may use daily, such as telnet. The precautions taken in IMP include:

Use of a secure web server
Reasonable use of cookies

What does this mean?

Secure Web Server

Every piece of data - including your username and password, as well as the text of all of your emails - is encrypted before being sent between your web browser and the server that IMP runs on. This is done via SSL, a widely available, commercially used system that uses public/private key cryptography from RSA Data Security.

Does this mean that no one can read it? Realistically, no. For one thing, IMP uses IMAP (Internet Mail Access Protocol) to achieve independence from the server the mail sits on. IMAP is a fundamentally insecure system, because none of its transactions are encrypted. So your username, password, and email all have to travel between your mail server and IMP.

However, this is no different from any other way you might choose to read your mail, unless you use SSH to login to your mail host (if you do, good for you!). POP3, the other major protocol for retrieving mail over the internet, suffers from the same insecurity.
[Side Note:] Intranet mail protocols (like Exchange) also don't encrypt data. Don't go off thinking there's something inherently less secure about all this!

So SSL encryption essentially makes IMP a toss up security-wise. It is no more secure than other common ways of reading mail, but its use of the World Wide Web does not make it any less secure.

Note: if your IMAP server runs on the same server that IMP does, or if the IMAP server is on a switched connection to the web server that IMP runs on, IMP will be about as secure as any unencrypted network transaction will get. This is because data only has to travel to the loopback or along a dedicated connection; thus only the (supposedly trusted) systems administrators would have the priviledges to monitor this traffic. These conditions are met for both Colrain and WSO for the IMP installation at Williams College.

Cookies

Yes, IMP uses cookies to store some of the data it needs to pass between scripts - namely usernames and passwords. However, the cookies that IMP sets are tagged such that they will never be sent over an insecure connection, so you never need to worry about your password being sent clear text over http - SSL takes care of the security of your cookies as well as the rest of the http transaction.

IMP also sets cookies to expire within 15 minutes of being set, unless they are refreshed. This can be a minor inconvenience, but means that if you forget to log yourself out, the vulnerable period when another person could walk up to your web browser and use the cache and the already set cookies to read your mail is fairly slim.

Finally, the cookies that IMP sets do not contain your actual username and password - they contain a scrambled, unrecognizable version of them. Note that they are NOT encrypted, and this scrambling should not be regarded as a serious security feature. It is solely for cases like when you have cookies set to verify before accepting, which can cause the contents to be displayed on your screen. In a case like this, if your were showing IMP to someone, you would not want your cleartext password displayed on the screen. The scrambling feature remedies this and similar situations.

Conclusions

IMP is intended as a convenience and a pretty interface. It is not intended for situations where utmost security is needed, and I, the creator of IMP, or any of the other contributing authors, will not be held liable for security breaches that occur, directly or indirectly, through its use.

Chuck Hagenbuch, chuck@horde.org

6.5 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.6 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/cvs/], and start hacking!

6.7 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]