INSTALL

   1 Installing SquirrelMail
   2 =======================
   3
   4 Table of Contents:
   5   0.  (QUICK!)   Quick install guide
   6   1.  (PHP4)     Configure your webserver to work with PHP4
   7   2.  (IMAP)     Setting up IMAP (not covered)
   8   3.  (INSTALL)  Obtaining and installing SquirrelMail
   9   4.  (RUN)      Running SquirrelMail
  10   5.  (CHARSETS) Russian Charsets
  11   6.  (LOCALES)  Translations of SquirrelMail
  12
  13
  14 0. QUICK INSTALL GUIDE
  15 ----------------------
  16
  17 Each of these steps is covered in detail below.
  18
  19 - Install webserver and PHP4 (at least 4.1.0).
  20 - Install IMAP server (see docs of that server).
  21 - Unpack the SquirrelMail package in a web-accessible location.
  22 - Select a data-dir and attachment dir, outside the webtree (e.g. in /var).
  23   The data-dir (for user prefs) should be owned by the user the webserver
  24   runs as (eg www-data). The attachment dir (for uploading files as
  25   attachments) should be file mode 0730 and in the same group as the
  26   webserver.
  27 - Run config/conf.pl from the command line. Use the D option to load
  28   predefined options for specific IMAP servers, and edit at least the
  29   Server Settings and General Options (datadir).
  30 - Browse to http://www.example.com/yourwebmaillocation/src/configtest.php
  31   to test your configuration for common errors.
  32 - Browse to http://www.example.com/yourwebmaillocation/ to log in.
  33
  34
  35 1. CONFIGURE YOUR WEBSERVER TO WORK WITH PHP4
  36 ---------------------------------------------
  37
  38   If your webserver does not already have PHP you must configure it
  39   to work with PHP. You need at least PHP v4.1.0. SquirrelMail uses
  40   the standard suffix .php for all PHP4 files.
  41
  42   You can find PHP at http://www.php.net. See the documentation that
  43   comes with PHP for instructions how to set it up.
  44
  45   The PHP IMAP extension is NOT neccessary at all (but won't harm)!
  46   Below is a list of optional PHP extensions:
  47
  48   --with-ldap     Required for LDAP addressbooks
  49   --with-mhash    Will improve charset decoding if present
  50   --with-mysql    For MySQL storage of preferences or addressbooks
  51   --with-openssl  When you want to use encrypted IMAP connections (TLS)
  52
  53   If you're going to use LDAP in the addressbook, you must compile PHP
  54   with the LDAP extension. Include the MHASH extension to improve
  55   performance in character set decoding.
  56
  57   If you want your users to attach files to their mails, make sure
  58   File Uploads in php.ini is set to On.
  59
  60
  61 2. SETTING UP IMAP
  62 ------------------
  63
  64   This depends a lot on the server your choose. See the documentation
  65   that comes with your server.
  66
  67   If you're concerned about people accessing it directly, you can
  68   limit access to only the IP of the webserver.
  69
  70
  71 3. OBTAINING AND INSTALLING SQUIRRELMAIL
  72 ----------------------------------------
  73
  74   SquirrelMail is constantly being improved. Therefore you should always
  75   get the newest version around. Look at http://www.squirrelmail.org
  76   to see what it is. If you want to be bleeding edge you might want to
  77   consider using the latest CVS version (with the latest and most
  78   fashionable bugs).
  79
  80 a. Download SquirrelMail
  81
  82   Get SquirrelMail from the address above if you do not have it or are
  83   uncertain if you have the newest version. Untar (again tar xvfz
  84   filename.tgz) SquirrelMail in a directory that is readable for your
  85   webserver.
  86
  87 b. Setting up directories
  88
  89   SquirrelMail uses two directories to store user configuration and
  90   attachments that are about to be sent. You might want to have these
  91   directories outside of your web tree.
  92
  93   The data directory is used for storing user preferences, like
  94   signature, name and theme. When unpacking the sources this directory
  95   is created as data/ in your SquirrelMail directory. This directory
  96   must be writable by the webserver. If your webserver is running as
  97   the user "nobody" you can fix this by running:
  98
  99     $ chown -R nobody data
 100     $ chgrp -R nobody data
 101
 102   Keep in mind that with different installations, the web server could
 103   typically run as userid/groupid of nobody/nobody, nobody/nogroup,
 104   apache/apache or www-data/www-data.  The best way to find out is to read
 105   the web server's configuration file.
 106
 107   There also needs to be a directory where attachments are stored
 108   before they are sent. Since personal mail is stored in this
 109   directory you might want to be a bit careful about how you set it
 110   up. It should be owned by another user than the webserver is running
 111   as (root might be a good choice) and the webserver should have write
 112   and execute permissions on the directory, but should not have read
 113   permissions. You could do this by running these commands (still
 114   granted that the webserver is running as nobody/nobody)
 115
 116     $ cd /var/some/place
 117     $ mkdir SomeDirectory
 118     $ chgrp -R nobody SomeDirectory
 119     $ chmod 730 SomeDirectory
 120
 121   If you trust all the users on you system not to read mail they are
 122   not supposed to read change the last line to chmod 777 SomeDirectory
 123   or simply use /tmp as you attachments directory.
 124
 125   If a user is aborting a mail but has uploaded some attachments to it
 126   the files will be lying around in this directory forever if you do not
 127   remove them.  To fix this, it is recommended to create a cron job that
 128   deletes everything in the attachment directory.  Something similar
 129   to the following will be good enough:
 130
 131     $ cd /var/attach/directory
 132     $ rm -f *
 133
 134   However, this will delete attachments that are currently in use by people
 135   sending email when the cron job runs.  You can either (1) make sure that
 136   the cron job runs at an obscure hour and hope that nobody gets upset, or
 137   (2) you can run a modified version of the commands above.  Check out the
 138   man pages for other commands such as 'find' or 'tmpreaper'.
 139
 140   One sample script you could set up that would erase all attachments, but
 141   wouldn't erase preferences, address books, or the like (just in case your
 142   attachment directory is the same as your data directory) might look like
 143   this:
 144
 145     $ rm `find /var/attach/directory -atime +2 | grep -v "\." | grep -v _`
 146
 147   Remember to be careful with whatever method you do use, and to test out
 148   the command before it potentially wipes out everyone's preferences.
 149
 150 c. Setting up SquirrelMail
 151
 152   There are two ways to configure SquirrelMail.  In the config/ directory,
 153   there is a perl script called conf.pl that will aid you in the
 154   configuration process.  This is the recommended way of handling
 155   the config.
 156
 157   You can also copy the config/config_default.php file to config/config.php
 158   and edit that manually.
 159
 160   After you've created a configuration, you can use your webbrowser to
 161   browse to http://your-squirrelmail-location/src/configtest.php.
 162   This will perform some basic checks on your config to make sure
 163   everything works like it should.
 164
 165
 166 4. RUNNING SQUIRRELMAIL
 167 -----------------------
 168
 169   Point your browser at the URL at which SquirrelMail is installed.  A
 170   possible example of this is:
 171      http://www.yourdomain.com/squirrelmail
 172
 173   It should be pretty straight forward to use. Some more documentation
 174   might show up one day or another.
 175
 176
 177 5. RUSSIAN CHARSETS
 178 -------------------
 179
 180   For information on how to make SquirrelMail work with Russian
 181   Apache, see the README.russian_apache in the doc/ subdirectory.
 182
 183
 184 6. TRANSLATIONS
 185 ---------------
 186
 187   In order to use translated versions of SquirrelMail, you need
 188   to download and install locale packages that contain translations
 189   that you want to use with squirrelmail.
 190
 191   Locale packages can be downloaded from SquirrelMail SourceForge
 192   project page.
 193
 194   http://sourceforge.net/project/showfiles.php?group_id=311&package_id=110388
 195
 196   Each translation contains install script that copies required files
 197   into appropriate locations. If you can't run that script, you can extract
 198   contents of translation packages into your squirrelmail directory.
 199
 200   NOTE No.1: *-src.tar.gz, *-src.tar.bz2 and *-src.zip archives does not contain
 201   compiled translation files. You will need to run compilelocales script
 202   in order to get all gettext binary translations.
 203
 204   NOTE No.2: You might need to restart your webserver before using translations.
 205   If you can't do that, install your translations _before_ you use SquirrelMail.