Diff for FAQ/Admin/Config between 15 and 16


+ Horde Administrator's FAQ

++ General configuration

+++ How can I have Horde in a different directory than /horde/ or configure an application to run in a virtual host?

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 Kronolith -- one often wants to have http://horde.example.com/mail/ and http://horde.example.com/calendar/ instead of the longer versions with the {{/horde/}} component.

++++ Virtual Host

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, 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/
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 5]:**

Create or edit {{horde/config/registry.local.php}} (make sure the file starts with a PHP tag {{<?php}}) and change the value of the webroot as follows:

<code type="php">
$this->applications['horde']['webroot'] = '/horde';
$this->applications['imp']['webroot'] = '';

**[Horde 4]:**

Create or edit {{horde/config/registry.local.php}} (make sure the file starts with a PHP tag {{<?php}}) and change the value of the webroot as follows:

<code type="php">
$this->applications['imp']['webroot'] = '';

**[Horde 3]:**

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

<code type="php">
$this->applications['imp'] = array(
    'fileroot' => dirname(__FILE__) . '/../imp',
    'webroot' => '',
    'icon' => '/graphics/imp.gif',
    'name' => _("Mail"),

With the above settings, going to {{http://yourserver.example.com/}} will take the user right to the IMP login screen.

++++ Shorter/nicer URLs

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. In Apache:

DocumentRoot /usr/local/apache/htdocs/horde

(substituting directory names as appropriate). Then, if the automatic webroot detection doesn't work, make sure links within Horde are correct as follows:

**[Horde 4]:**

Create or edit {{horde/config/registry.local.php}} (make sure the file starts with a PHP tag {{<?php}}) and change the value of the webroot as follows:

<code type="php">
$app_webroot = '';

**[Horde 3]:**

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

<code type="php">
$this->applications['horde'] = array(
    'fileroot' => dirname(__FILE__) . '/..',
    'webroot' => '',
    'initial_page' => 'login.php',
    'name' => _("Horde"),

If you want to change the name "Horde" on the login screen ("Welcome to Horde"), the above file is the place to do it.

**[Horde 4]:**

Create or edit {{horde/config/registry.local.php}} (make sure the file starts with a PHP tag {{<?php}}) and change the value to:

<code type="php">
$this->applications['horde']['name'] = _("Whatever");

**[Horde 3]:**

Change the value from:

<code type="php">
    'name' => _("Horde"),


<code type="php">
    'name' => _("Whatever"),

+++ How can I change the appearance?

See ((Doc/Dev/Layout)) and Doc/Dev/Themes.

You can add Horde modules to the left navigation bar by creating/editing {{/horde/config/registry.local.php}} (Horde 4 or later) or modifying {{/horde/config/registry.php}} (Horde 3).

You can modify the components' navigation bars (at the top of screen) by adding menu entries through the Setup Interface, or modifying the {{/horde/componentname/config/menu.php}} files. 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.

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

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/locale/}} ({{/horde/po/}} in Horde 3), named by the locale name. Edit the translation(s) in this file to suite your needs. Then compile the locale files as described in your version's {{/horde/docs/TRANSLATIONS}} ({{/horde/po/README}} in Horde 3) file. For other components, follow the same steps using the {{/horde/componentname/locale/}} 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:

grep -rli 'Your Phrase' horde/

where {{horde/}} is the root directory of your Horde installation. To make your search case sensitive remove the {{-i}}. To see the match rather than just the file name remove the {{-l}}.

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

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

Horde uses GNU gettext for internationalization (i18n) and localization (l10n). See {{[http://www.horde.org/apps/horde/docs/TRANSLATIONS horde/docs/TRANSLATIONS]}} for more information.

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

Horde comes with a problem-reporting form. You can control who sees it, and what is done with problem reports, by going to the //Problem Reporting// tab of the Horde setup interface.

+++ Can I use PHP's safe_mode with Horde?

PHP's safe_mode is not officially supported by Horde, although we work around its restrictions wherever we can. 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 PHP 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_php5.c>
       php_admin_value safe_mode Off

It has been reported that Horde, IMP, and Turba, with safe_mode enabled, are working fine with this apache configuration:

	<Directory /path/to/horde>
		php_admin_value open_basedir "/path/to/horde:/path/to/pear/lib/:/path/to/logfile/dir"
		php_admin_flag file_uploads On
		php_admin_value upload_tmp_dir /path/to/horde/tmp
		<FilesMatch "smime\.php">
			php_admin_value safe_mode_exec_dir "/path/to/openssl/bin"
			php_admin_value open_basedir "/path/to/horde:/path/to/pear/lib/:/path/to/logfile/dir:/var/tmp"

With this configuration, it is possible to import private keys, to sign and encrypt mails, to add attachment files, and to set languages. The {{$conf['tmpdir']}} setting must be set to {{/path/to/horde/tmp}} in the Horde setup. It is used for uploads (IMP attachments) and to generate temporary files when you are signing and/or encrypting mails. A special configuration is set for the {{smime.php}} file so it can run the openssl command to encrypt and decrypt the private key when it is imported in the database. To enable the private key import, {{/var/tmp}} must be added to the the {{open_basedir}} list (why?).

This configuration has been tested with a direct access to the SMTP server (no local sendmail).

There is no warranty that everything works fine but the most important features (like sending, receiving, attaching files, signing, encrypting) are working fine.

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

**[Horde 3]:**
You can add content to the top of every page in Horde by adding appropriate code to the file {{horde/templates/common-header.inc}}. You can add content to the bottom of every page in all Horde components by adding appropriate code to the file {{horde/templates/common-footer.inc}}.

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

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. This is because the administrator may want to lock a preference, but create a different value for some users. The administrator controls the preferences container, so we trust the preferences container.

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. Horde 3 includes a script in {{horde/scripts/remove_prefs.php}} to aid in doing this. In Horde 3.2 and above, this script is in the administrator tools package (http://pear.horde.org/index.php?package=admintools) (This package and the script still have to be updated for Horde 4. In the meantime, you can run the following SQL query in the database administration tool of your choice, if you use a SQL preference backend: {{DELETE FROM horde_prefs WHERE pref_scope = 'applicationname' AND pref_name = "preferencename"}}.

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

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

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 //Authentication// tab of the setup interface. 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/backends.local.php}} appropriately also.

Some special notes for some of the authentication methods are:

* {{horde/scripts/sql/script.initial_horde_user.sql}} is an SQL script which will create an initial administration user for SQL authentication. This can be used to login and configure the system. If you use this, be sure to change it as soon as possible so it does not become a security risk. If using the SQL backend with the {{horde_users}} table and using this script to add an initial user, the password must be in MD5 format (for Horde <= 3.1.x) or SSHA (for Horde >= 3.2.x) (and not the !MySQL password() format, for example). You can add an initial user manually though and choose a different password hashing method.
* If using IMAP authentication, see the comments in {{horde/imp/config/backends.php}} for options you may need to specify.
* See the [HowTo authentication howtos] for some example authentication setups and especially SQLAuthHowTo for an authentication setup example that allows for user management.

+++ What are the default user name and password for the administrator?

There are none. Since Horde supports a broad variety of different authentication backends and you are free to choose any of them for your Horde installation, the selected backend decides which are valid login credentials. And we didn't add an authentication independent backdoor to Horde, for obvious reasons.
Instead, you can turn any valid and authenticated user into an administrator by adding his user name to the administrator list in Horde's configuration. Make sure to use user names exactly like they are used inside Horde, i.e. with or without a domain name, and considering any user name hooks that you enabled.

+++ How can I get back to the setup screen?

You probably locked yourself out as an administrator because you properly configured an authentication backend for Horde, but forgot to add yourself as an administrator in the Horde configuration - see the paragraph above. If you don't want to start from scratch by copying {{conf.php.dist}} to {{conf.php}} again, you need to change the configuration file {{horde/config/conf.php}} manually. Edit the {{$conf['auth']['admins']}} setting and add your username, e.g. {{$conf['auth']['admins'] = array('joe');}} or {{$conf['auth']['admins'] = array('joe@example.com');}}. You can add several administrators using a comma separated list.

+++ How can I pre-configure a portal view for the users?

You may have noticed within the Horde configuration an option to fix certain portal blocks on the Portal screen.  The next question is often "how are those blocks to be configured?"  The answer lies within the Horde Preferences system.  The Horde preference that controls the layout of the portal blocks and their settings is the 'portal_layout' preference.  This preference is stored as a serialized array of data containing all the information required to display the Portal.  However this format can be tricky to come up with manually.  The easiest way to generate the value is to set up your own portal view as you would like your users to experience it.  Once you have done so, and saved the setting, the preference will be saved to your configured Horde_Prefs backend.  At this point you can either consult the Horde_Prefs backend directly (ie. pull the value directly from SQL or the Base64 encoded value from LDAP) or you can use Horde's built-in PHP Shell, accessible from the "Administration" menu.  To get your current preference value, type the following into the PHP Shell text box:

<code type="php">
echo $GLOBALS['prefs']->getValue('portal_layout');

This value can then be put into the file {{horde/config/prefs.local.php}} as the default value of the 'portal_layout' preference:

<code type="php">
$_prefs['portal_layout']['value'] = 'paste_value_here';

Please note that some portal block settings might be user dependent (e.g. only showing a certain calendar etc.). These settings won't work as a default for all users. You better create a preference hook in These cases. Hooks are capable of creating dynamic default values for preferences.

++ IMP configuration

+++ Can a single IMP installation serve different virtual hosts?

If you have your web server 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//.

You can check the IMP mailing list archives for information.

+++ 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 setup interface and in the file {{/horde/imp/config/prefs.local.php}}. See the comments in the interface and in {{/horde/imp/config/prefs.php}} for more information.

When changing settings in {{/horde/imp/config/prefs.local.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}}:

<code type="php">
$_prefs['somepref']['value'] = 'different_default_value';
$_prefs['somepref']['locked'] = true;

There are also a number of permissions that can be set for all users, individual users, or certain user groups. These permissions include the maximum number of message recipients or IMAP folders, or a rate limit that sets how many messages can be sent in a certain time period. Permissions can be added in the permissions section of the administration interface.

[[# attachment-size]]
+++ How can I configure IMP's maximum attachment size?

You may need to make changes to any or all of the following settings:  PHP, Apache, database, and Mail Transfer Agent.  Settings in each of these parts may affect overall attachment size and you will likely want any value that deals with size to be set to the same value of whatever maximum size you want to support.

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}}:

upload_max_filesize = number of bytes
post_max_size = number of bytes + size of form data, e.g. message text

Other limits that might affect the maximum size of attachments that PHP is able to handle:

max_execution_time = 30 ;may need to be higher
memory_limit = -1 ;removes the memory limit for php

You will need to restart your web server after this change and logout/login back into horde to see your new configured values in effect.

A few of these settings can also be changed through Horde's setup interface and override the default PHP settings.

It is also possible that web server settings may limit the size of attachments.  For example, the Apache setting {{!LimitRequestBody}} will limit the size also.  In some Linux distributions (e.g. Red Hat Enterprise Linux 3), this is set very low in a distribution-created {{/etc/httpd/conf.d/php.conf}} file.  Again, you will need to restart your web server after changing web server configuration settings.

Your database server may impose limits on the maximum size of files that can be uploaded.  Check your database server documentation to see what this limit may be.  For !MySQL, this limit is controlled by the {{max_allowed_packet}} configuration directive.

Finally, your MTA may impose size limits for the overall size of messages that it will handle.  Check your MTA configuration to see if there are settings to limit overall message size.

See ((FAQ/Admin/FileUploads)) too.

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

**[IMP 5]:**

Messages can be altered with the {{pre_sent}} hook. The {{horde/imp/config/hook.php.dist}} file contains an example how to add custom headers to all outgoing messages.

**[IMP 4]:**

To add custom headers to mail sent from IMP, place the headers in {{/horde/imp/config/header.txt}} ({{/horde/imp/config/header.php}} in IMP 4.1 or higher). Make sure that your header is the last line in the file!

**[IMP 4.0]:** 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.

**[IMP 4.1+]**: You can enter any valid PHP expressions.

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

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

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.

+++ 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 might be executed by the browser. We try to filter out any active content, but just like with any filter, it might not be perfect and let some code through. //Enabling inline HTML attachments is discouraged//.

Of course, this will only work for elements that could be part of a regular HTML page or that have a MIME viewer (attachment renderer) in Horde that converts the original attachment into HTML output.

Create the files {{horde/config/mime_drivers.local.php}} and {{horde/imp/config/mime_drivers.local.php}} (IMP 4: edit the files {{horde/config/mime_drivers.php}} and {{horde/imp/config/mime_drivers.php}}) to enable inline support for the mime types you wish to have displayed inline. Simply add an {{'inline'}} setting (IMP 4: 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 in {{mime_drivers.php}} than that type can not be viewed inline.

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

<code type="php">
$mime_drivers['imp']['html']['inline']$mime_drivers['html']['inline'] = true; // for horde/config/mime_drivers.local.php
$mime_drivers['html']['inline'] = true;        //// for horde/imp/config/mime_drivers.local.php

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

IMP has no built-in address book, but instead uses the Horde module [http://www.horde.org/apps/turba Turba] for an address book. See the Turba FAQ section below 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.

**[IMP 5]:**

To configure IMP to use one or more Turba directories by default, you create a preference hook. See the file {{horde/imp/config/hook.php.dist}} for examples.

**[IMP 4]:**

To configure IMP to use one or more Turba directories by default, 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.

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

IMP does not include support for changing passwords. You can download a separate Horde module called [http://www.horde.org/apps/passwd/ Passwd] to add this functionality.

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

There is some signup functionality in Horde that requires an authentication backend that can be managed through Horde. Signups have to be enabled in the Horde setup interface.

+++ How can I remove maintenance functions in IMP?

**[IMP 4.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}}.

**[IMP 4.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}}.

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

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 {{[http://www.horde.org/apps/horde/docs/INSTALL horde/docs/INSTALL]}}. You will also have to configure Horde to use the preferences container.

+++ Can IMP be used with SMTP authentication?

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) or the same set of credentials for ever user. Simply edit the Horde configuration as per the comments in the //Mailer// tab of the setup interface.

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

**[IMP 5]:**

Trailers can be added with the {{trailer}} hook. The {{horde/imp/config/hook.php.dist}} file contains examples how to add custom trailers to all outgoing messages.

**[IMP 4]:**

IMP automatically appends the content of the file {{horde/imp/config/trailer.txt}} to each email it sends. You can disable this by disabling the according configuration option (Setup -> Mail (Imp)... -> Compose -> Should we append the contents...) in IMP's setup interface. 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.

++ Turba Configuration

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

See the file {{horde/turba/config/backends.php}}. The documentation in the file is pretty complete, and there are some examples using public LDAP directories.

+++ How do I enable shared address books?

**[Turba 3]:** Shared address books are already enabled by default.

**[Turba 2.1+]:** You can enable shared address book support for a source that supports this by adding {{'use_shares' => true}} to the source's stanza in {{horde/turba/config/sources.php}}. This allows users to create and delete new address books as well as manage permissions on the address books that they own. Permissions for shared address books should be set through the //My Address Books// interface in Turba and **not** through the administration interface. Choose the menu item //My Address Books// and then select the address book you want to share from the drop down menu in the //Edit Address Book// section then click //Edit Permissions//.