10. Solving problems

10.1 Configtest

When attempting to diagnose any issues with SquirrelMail, the first thing to do is load up http://example.org/squirrelmail/src/configtest.php and ensure that SquirrelMail can't already tell you what the problem is.

Note that as of SquirrelMail version 1.5.0, you cannot view this page from any computer other than the one where SquirrelMail is installed unless you have enabled remote computers to view it by using the SquirrelMail configuration tool (config/conf.pl, which is usually aliased to configure in the main SquirrelMail directory) and going to "11. Tweaks" and then chossing "7. Allow remote configtest". You can also edit the $allow_remote_configtest setting directly in config/config.php if you prefer. Before leaving this enabled, consider that exposing the kind of information it displays can be a security concern, so you are advised to turn it off except when specifically needed.

Aside from diagnosing certain problems directly, this tool will also display many pieces of information that may be very helpful when asking others to help you with problems you cannot fix yourself. Therefore, this should always be your first stop when any problems come up.

10.2 Common PHP error messages

unknown function session_id() call

missing session support

Safe mode

TODO: Clean the Safe mode section up.

Running SquirrelMail with PHP safe_mode restrictions.

Settings that are used in safe mode

• safe_mode
• safe_mode_gid
• safe_mode_include_dir
• safe_mode_exec_dir
• safe_mode_allowed_env_vars
• safe_mode_protected_env_vars
• disable_functions
• disable_classes

(open_basedir is related but functions independently of safe_mode.)

It is possible to run SquirrelMail with safe_mode limitations, if you solve some problems.

1. safe_mode controls list of allowed executables.

SquirrelMail has to use SMTP in order to send email or provider has to provide wrapper for /usr/sbin/sendmail.

Fortune and SquirrelSpell plugins don't work, if provider does not add path to fortune, ispell/aspell and cat programs into safe_mode_exec_dir variable.

Since safe_mode_exec_dir only allows only directory to be added, it is necessary to create symbolic links from that directory to any other executables required (for example, add a link to /usr/sbin/sendmail and /bin/cat from /usr/bin).

Also, since under safe_mode exec() will only allow an executable to be called with a single argument, the line:

exec("cat $floc | $sqspell_command 2>&1", $sqspell_output, $sqspell_exitcode);

in check_me.mod will fail. It is necessary to create a shell script (in safe_mode_exec_dir) which takes as an argument the file to check, and then call this instead. For example, the line could be changed to:

exec("squirrelmail_hack $floc", $sqspell_output, $sqspell_exitcode);

and then /usr/bin/squirrelmail_hack could be created as follows:

#!/bin/sh
# allow sqspell plugin to work with safe_mode
cat "$1" | /usr/bin/aspell pipe 2>&1

and spellchecking will work. Note that language options will be ignored with this script. It would also be possible to write something cleverer that splits its argument by whitespace and calls the required dictionary. However, custom user dictionaries will continue to work.

2. safe_mode controls list of allowed environment variables.

time zone settings are not available if use of TZ variable is not allowed.

gettext extension on some operating systems depends on environment variables. SquirrelMail does not set them in safe mode.

3. directory hashing does not work

4. path to data directory should be relative.

SquirrelMail configuration tools allow relative paths only with one upper level. Longer relative paths are converted to full path.

5. mail_fetch plugin can't control PHP script execution time limits.

Your email fetching time must be within PHP max_execution_time limits.

6. File ownership restrictions

The default preference file (frequently named default_pref) AND the default data directory (frequently /var/lib/squirrelmail/data/) must be owned by same user that owns other SquirrelMail scripts. The default preference file and the default data directory must be readable and writable by the user that the web server runs as. The user that the web server runs as and the owner of the SquirrelMail scripts may be different (e.g. in Debian, SquirrelMail is owned by root, but the web server runs as www-data).

10.3 UW IMAP

Login Disabled

uw-imapd server disables plain text logins by default in 2002 and newer versions. This was done in order to follow security recommendations by IETF (The Internet Engineering Task Force) and strict RFC 3501 security recommendations.

You can see this by telneting to your IMAP server and checking for LOGIN=DISABLED string in CAPABILITY description.

SquirrelMail uses plain text logins. In order to enable plain text logins, you will have to recompile UW IMAP or use the semi-official /etc/c-client.cf configuration file.

See doc/imaprc.txt for further information. In order to enable plain text logins, you must add

set disable-plaintext nil

Please remember that you need to use specific phrase in first line of /etc/c-client.cf. This phrase does not look like normal option, but uw imap will refuse to parse other options, if this phrase is not present. Correct sentence can be found in uw imap source or imaprc.txt document.

WARNING: uw imap developers discourage usage of /etc/c-client.cf options

OS specific notes

Debian Sarge 3.1 and newer versions

Plain text logins are not enabled. See bugs 227709, 239537, 273687.

Create c-client.cf file manually or dpkg-reconfigure uw-imapd, enable IMAPS and set SquirrelMail to use IMAP over SSL or use different IMAP server.

OpenBSD

there are two different packaging flavors. [default package] and [package with plaintext support]. Use plaintext package or enable plain text login in /etc/c-client.cf

FreeBSD

You need to recompile package from ports and set WITHOUT_SSL or WITH_SSL_AND_PLAINTEXT variables. You must remove prepackaged versions of imap-uw and cclient before doing this. If you don't want to recompile - enable plain text login in /etc/c-client.cf.

  cd /usr/ports/mail/imap-uw
  env WITH_SSL_AND_PLAINTEXT=YES make
  

If you don't want to enable plain text login, you must use IMAP-SSL server on different port. Other programs support STARTTLS on default IMAP port, but SquirrelMail can't do that due to specific limitations of PHP SSL module and restrictions of SquirrelMail IMAP implementation. You may be able to use the IMAPS port of 993.

Please note, that if your IMAP server is on the same machine as the web server that hosts SquirrelMail, SSL adds security features that are useless. During connection to localhost password information is not transmitted over unsafe network. If you want to secure your IMAP server, bind it to localhost address only or use tcpwrappers or firewall to disable external connections.

Long listing

Configure SquirrelMail with UW preset and don't remove mail/ prefix in Folder Options.

10.4 Common interface error messages

TODO: Clean the "Common interface error messages" section up.

Special folders (Sent/Drafts/Trash) are not translated

See http://squirrelmail.org/docs/translator/translator-3.html#ss3.6

Unknown username or password

password is not ********. you need cookies.

Session timeout

session.gc_maxlifetime

Can't delete emails. Quota exceeded.

SquirrelMail's default behavior is to move messages to the trash folder when they are deleted. If mail account has a quota and user is close to exceeding it, user might experience problems. IMAP protocol does not support move command. This is what happens when message is deleted:

1. The message is copied to the trashcan.
2. The original message is marked for deletion.
3. The original message is expunged, i.e. removed from the original folder.

If user tries to delete message that exceeds left quota, operation is aborted with quota error message.

Issue can be solved by deleting messages from trash or disabling use of Trash in SquirrelMail.

1. Click "Options".
2. Click "Folder Preferences".
3. Set "Trash Folder" to "Do not use Trash".
4. Click "Submit".

When trash is disabled, user can delete unneeded messages and reduce total amount of data stored in his/her account.

Starting with SquirrelMail 1.5.0 version, there is a "Bypass Trash" check box when viewing the message list or a message's content, that can be used to delete mails without changing the trash folder setting per above.

Some quota setups can ignore files placed in Trash folder.