Installation of Squirrelmail Web Email Interface
Squirrelmail is a way for users to access their email using a browser. Some users dislike using dedicated software like Outlook or pine to read their email. A Webmail server allows them to access it using a convenient browser interface. An article by Brent Bice in the July 2002 issue of Sys Admin Magazine gives more information on Squirrelmail, including a description on integrating it with MySQL.
Squirrelmail requires PHP4, SSL, IMAP4, Apache, and of course a functioning mail transport agent such as 'sendmail'. Installing php from scratch and getting it to work with Apache can be a major ordeal, so it is preferable to install php4 from the OS installation media if at all possible. If you install php from source, it may also be necessary to recompile Apache httpd. Below is a procedure from the php manual. I did not test this, because php was already installed on my system.
- Install php4, ssl, and apache if necessary.
- gunzip apache_xxx.tar.gz
- tar -xvf apache_xxx.tar
- gunzip php-xxx.tar.gz
- tar -xvf php-xxx.tar
- cd apache_xxx
- ./configure --prefix=/www --enable-module=so
- make install
- cd ../php-xxx
- ./configure --with-mysql --with-apxs=/www/bin/apxs
- make install
- cp php.ini-dist /usr/local/lib/php.ini
- Edit /etc/httpd/httpd.conf as described below and use your normal procedure for starting the Apache server. (You must stop and restart the server, not just cause the server to reload by use a HUP or USR1 signal.)
Here are the relevant sections of /etc/httpd/httpd.conf:
Sometimes this is also present, but it does not seem to be necessary:
< IfDefine PHP4> AddModule mod_php4.c </IfDefine> ... < IfDefine PHP4> AddType application/x-httpd-php .php AddType application/x-httpd-php .php4 AddType application/x-httpd-php-source .phps </IfDefine> ....
Some people report that removing the PHP3 sections also helps.
< IfDefine PHP4> LoadModule php4_module /usr/lib/apache/libphp4.so </IfDefine> ...
- Restart apache
cd /etc/rc.d ./apache restart
- Create a file called "test.php" containing one line
and put it in the htdocs directory. Note: The spacing must be exactly as shown. In particular, there must be no spaces between the '<', and the '>' and the '?'. Otherwise, the phpinfo() command will only be displayed instead of executed. If you go to your server's Web page in a browser and type "test.php", php4 should generate several pages of diagnostic information to indicate that it's working. This command can also be included in a Web page.
<? phpinfo(); ?>
Once PHP4 is working, installing squirrelmail itself is trivial.
- Unpack squirrelmail somewhere, e.g., /usr/local/httpd/htdocs
and create a link.
ln -s squirrelmail-1.4.19 mail
- Make the "data" directory writable by the web server:
chown -R wwwrun.nogroup mail
- Create a directory where the mail will be stored, if it doesn't
cd /var ln -s /var/spool/mail mail
- Make sure the tmp directory in squirrelmail has permissions 777, otherwise users will be unable to delete messages.
- Activate IMAP server in /etc/inetd.conf and restart inetd with a SIGHUP (i.e., 'kill -1 pid').
- Type "conf.pl" or "configure" to start the installation perl script, which creates the file config/config.php. Squirrel mail consists entirely of scripts. There is nothing to build.
- If upgrading from a previous version, copy the squirrelmail
directories (themes, images, etc) to the new directory.
Make sure permissions are correct so the browser can read it. The browser should be able to read all the squirrelmail files and write to the data files. If it's a link outside of the Web server's directory, don't forget to enable symlinks in /etc/httpd/httpd.conf.
-rw------- 1 wwwrun nogroup 77 Jun 13 22:25 tjnelson.pref
- Browse to http://your-site.com/squirrelmail-1.4.19/src/configtest.php and make sure there are no errors.
- In browser, type "localhost/mail/src/login.php". You should get a login screen.
- Get rid of "Dark Gray" and "Darkness" themes by deleting their php files in the "themes" directory. These themes set the foreground and background colors to black, which prevents users from changing them back.
- Edit the file help/en_US/read_mail.hlp to remove the grammatical and spelling errors.
- Remove the directory "plugins/spamcop".
- Add an HTML page called "mail.html" in /usr/local/httpd/htdocs/mail:
This will allow them to type "http://www.diarrhea.com/mail.html" to get their mail instead of "http://www.diarrhea.com/mail/src/login.php". Alternatively, put a link to "src/login.php" on your main Web page.
<HTML><HEAD> <TITLE> Engram Email System </TITLE> </HEAD> <BODY BGCOLOR="FFFFFF"> <META HTTP-EQUIV="REFRESH" content="0; URL=src/login.php"> </BODY> </HTML>
- Modify /etc/php.ini and /usr/local/lib/php.ini to allow HTTP uploads
and specify their maximum size:
file_uploads = On ;upload_tmp_dir = upload_max_filesize = 20M
- Turn off allow_url_fopen in /etc/php.ini for security
allow_url_fopen = Off
The config file php.ini should be set to send information to syslog, so errors experienced by users can be detected.
- Users have to login twice (first time is error message, even with correct
- Upgrade to latest squirrelmail, where the bug is fixed
- Change /etc/php.ini to session.use_trans_sid = 0
- Users can't log in
Check configuration by browsing to http://your-site.com/squirrelmail-1.4.19/src/configtest.php and change your /etc/php.ini file as necessary to get rid of any errors. In particular, session.auto_start must be 0 and all magic_quotes should be Off. Also, check ownership and permissions of squirrelmail files and directories. They should all be readable by the owner of your httpd (usually nobody.nogroup).
- Users can't send attachments
Change /etc/php.ini to contain the lines
file_uploads = On upload_max_filesize = 200M
- Users can't send attachments
If it says
Check phpinfo as described above and change the setting of upload_tmp_dir. Restart sendmail. In most cases, however, this will have no effect, so it's easier to just create the directory that php expects.
PHP Warning: File upload error - unable to create a temporary file in Unknown on line 0
- Users can't delete mail messages
Make sure permission in /tmp (or /usr/local/httpd/htdocs/mail/tmp, or wherever squirrelmail is configured to save temporary files) is set to 777. This is session.save_path in /etc/php.ini.
- Other problems
Most other problems are caused by incorrect permissions or file ownerships. In the main squirrelmail directory, the 'attachments' and 'data' directories (and the files therein) are owned by wwwrun.nogroup, and everything else is owned by root.root.
- Unable to login
If it says:
change the session.save_path in /etc/php.ini to
session_write_close(): open(/tmp/sess_46, O_RDWR) failed: Invalid argument (22) in redirect.php on line 152 session_write_close(): Failed to write session data (files). Please verify that the current setting of session.save_path is correct (/tmp) in redirect.php on line 152 Cannot modify header information - headers already sent by (output started at redirect.php:152) in redirect.php on line 153
and restart apache.
session.save_path = /usr/local/httpd/htdocs/mail/tmp
When users click on "Folders", it says
Fatal error: Maximum execution time of 30 seconds exceeded in imap_mailbox.php line 651.
This is caused by the user having a large number of files in their home directory. Imap reads the user's entire directory tree and squirrelmail creates a list of mail files the user can "subscribe" to. This can take a long time.
Change max_execution_time = 30
Change max_execution_time = 120
in /usr/local/lib/php.ini and restart apache. (This only partially solved the problem. Now the command doesn't time out, but Mozilla becomes unusably slow, taking several minutes to redraw its window.)
- Blank screen
Users see a blank screen when viewing any php page, including test.php.
Solution: Check the apache logs (error_log). One possibility is that php is crashing. The first line in the log below shows that PHP is configured correctly. The second line shows that it's crashing.
Apache/2.0.48 (Unix) mod_ssl/2.0.48 OpenSSL/0.9.7c PHP/4.3.1 PHP/5.0.3 configured -- resuming normal operations [notice] child pid 2257 exit signal Segmentation fault (11)
One solution is to recompile and reinstall php. This is not easy, because (at least on my SuSE system) the installation script hangs at installation of PEAR. If you don't need pear, this problem can be solved by editing the makefile and removing "install-pear" from the line that starts with "install-targets".
Another reason php may crash is that your httpd.conf file contains references to both php4 and php5. If you try to load both versions, it will crash.
It's also important to remove any pre-existing versions of php that may be on your system, e.g.:
to make sure the system is using the correct one.
mv /usr/bin/php /usr/bin/php.bak ln -s /usr/local/bin/php /usr/bin/php
- Error message
You need to create a tmp directory, or copy the tmp directory from an earlier version of squirrelmail.
PHP Warning: Unknown: open(..., O_RDWR) failed: No such file or directory (2) in Unknown on line 0 PHP Warning: Cannot modify header information
Upgrade squirrelmail to 1.4.9a or higher.
PHP Warning: preg_split() expects parameter 4 to be long, string given in imap_messages.php on line 806 PHP Warning: Invalid argument supplied for foreach() in mime.php on line 53
- Unable to set upload_max_filesize in php.ini
Check the phpinfo() page to find the directory where php is looking for php.ini. If no file exists there, php will use default values. Create a link to point to the correct file and restart Apache.
Alternatively, add this to your httpd.conf:
cd /usr/local/lib ln -s /etc/php.ini php.ini
You may also have to increase the value for post_max_size in php.ini to match.
<IfModule mod_php5.c> php_value upload_max_filesize 100M </IfModule>
- Unable to set time zone
Users see a long error message in the left panel warning about how dangerous it is not to set their time zone.
Solution: Supposedly, this can be fixed systemwide by adding the line
in /etc/php.ini and restarting httpd. (Note that there are now three php.ini files: one in /etc and two more in /etc/php5.) However, this did not work for us, and we finally ended up adding the line
date.timezone = "America/New_York"
to each user's preference file (e.g., chuck.pref for user Chuck) in Squrrelmail's data directory. The users can also fix this themselves by clicking on Options, but the error message is confusing enough that most of them don't realize this.
- Multiple PHP errors
If you upgrade to PHP 5.4, you may get a slew of PHP errors when the user logs in. The Squirrelmail website attributes this to changes in PHP.
Solution: PHP version 5.2 no longer compiles on many Linux systems, giving the message "Error dereferencing pionter to incomplete type." PHP 5.4 doesn't work with Squirrelmail versions as recent as 1.4.22. We switched to PHP 5.3.25, which worked.
- OS X users losing email
When upgrading squirrelmail, be sure to save the "data" subdirectory which contains all the users' settings.