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.

  1. Install php4, ssl, and apache if necessary.
    1. http://www.apache.org
    2. gunzip apache_xxx.tar.gz
    3. tar -xvf apache_xxx.tar
    4. http://www.php.net
    5. gunzip php-xxx.tar.gz
    6. tar -xvf php-xxx.tar
    7. cd apache_xxx
    8. ./configure --prefix=/www --enable-module=so
    9. make
    10. make install
    11. cd ../php-xxx
    12. ./configure --with-mysql --with-apxs=/www/bin/apxs
    13. make
    14. make install
    15. cp php.ini-dist /usr/local/lib/php.ini
    16. 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.)
  2. Here are the relevant sections of /etc/httpd/httpd.conf: 
       < 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>
   ....
    Sometimes this is also present, but it does not seem to be necessary: 
       < IfDefine PHP4>
      LoadModule php4_module /usr/lib/apache/libphp4.so
   </IfDefine>
   ...
    Some people report that removing the PHP3 sections also helps.
  3. Restart apache 
         cd /etc/rc.d
     ./apache restart
  4. Create a file called "test.php" containing one line 
      <? phpinfo(); ?>
    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.

Installing squirrelmail

Once PHP4 is working, installing squirrelmail itself is trivial.

  1. Unpack squirrelmail somewhere, e.g., /usr/local/httpd/htdocs and create a link. 
         ln -s squirrelmail-1.4.19 mail
  2. Make the "data" directory writable by the web server: 
         chown -R wwwrun.nogroup mail
  3. Create a directory where the mail will be stored, if it doesn't exist already: 
         cd /var
     ln -s /var/spool/mail mail
  4. Make sure the tmp directory in squirrelmail has permissions 777, otherwise users will be unable to delete messages.
  5. Activate IMAP server in /etc/inetd.conf and restart inetd with a SIGHUP (i.e., 'kill -1 pid').
  6. 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.
  7. 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
  8. Browse to http://your-site.com/squirrelmail-1.4.19/src/configtest.php and make sure there are no errors.
  9. In browser, type "localhost/mail/src/login.php". You should get a login screen.
  10. 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.
  11. Edit the file help/en_US/read_mail.hlp to remove the grammatical and spelling errors.
  12. Remove the directory "plugins/spamcop".
  13. Add an HTML page called "mail.html" in /usr/local/httpd/htdocs/mail: 
         <HTML><HEAD>
     <TITLE>
     Engram Email System
     </TITLE>
     </HEAD> 
     <BODY BGCOLOR="FFFFFF">
     <META HTTP-EQUIV="REFRESH" content="0; URL=src/login.php">
     </BODY>
     </HTML>
    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.
  14. 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
  15. Turn off allow_url_fopen in /etc/php.ini for security 
    allow_url_fopen = Off

Problems

The config file php.ini should be set to send information to syslog, so errors experienced by users can be detected.

  1. Users have to login twice (first time is error message, even with correct password).

    Solution:

    1. Upgrade to latest squirrelmail, where the bug is fixed
    2. Change /etc/php.ini to session.use_trans_sid = 0
  2. 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).

  3. Users can't send attachments

    Change /etc/php.ini to contain the lines 
      file_uploads = On
  upload_max_filesize = 200M

  4. Users can't send attachments

    If it says 
      PHP Warning:  File upload error - unable to create a 
  temporary file in Unknown on line 0
    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.

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

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

  7. Unable to login

    If it says: 
      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
    change the session.save_path in /etc/php.ini to 
      session.save_path = /usr/local/httpd/htdocs/mail/tmp
    and restart apache.

  8. imap_mailbox.php

    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.

    Solution: 
     Change max_execution_time = 30
    to 
     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.)

  9. 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.: 
      mv /usr/bin/php /usr/bin/php.bak
  ln -s /usr/local/bin/php /usr/bin/php
    to make sure the system is using the correct one.

  10. Error message 
    PHP Warning:  Unknown: open(..., O_RDWR) failed: No such file or 
    directory (2) in Unknown on line 0 
PHP Warning:  Cannot modify header information
    You need to create a tmp directory, or copy the tmp directory from an earlier version of squirrelmail. 
    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
    Upgrade squirrelmail to 1.4.9a or higher.
  11. 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. 
    cd /usr/local/lib
ln -s /etc/php.ini php.ini
    Alternatively, add this to your httpd.conf: 
    <IfModule mod_php5.c>
php_value upload_max_filesize 100M
</IfModule>
    You may also have to increase the value for post_max_size in php.ini to match.

  12. 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 
    date.timezone = "America/New_York"
    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 
    timezone=US/Eastern
    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.

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

  14. OS X users losing email

    See here.

When upgrading squirrelmail, be sure to save the "data" subdirectory which contains all the users' settings.

Back