moved functions from setup.php
[squirrelmail.git] / INSTALL
d68a3926 1Installing SquirrelMail
3b3d853f 4Table of Contents:
46f33521 5 0. (QUICK!) Quick install guide
3b3d853f 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
46f33521 11 6. (LOCALES) Translations of SquirrelMail
3b3d853f 12
17cec454 16
46f33521 17Each of these steps is covered in detail below.
17cec454 18
46f33521 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/ 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
31 to test your configuration for common errors.
32- Browse to to log in.
2a32fc83 33
1067414d 34
17cec454 37
46f33521 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.
598294a7 41
46f33521 42 You can find PHP at See the documentation that
43 comes with PHP for instructions how to set it up.
17cec454 44
46f33521 45 The PHP IMAP extension is NOT neccessary at all (but won't harm)!
46 Below is a list of optional PHP extensions:
17cec454 47
46f33521 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)
598294a7 52
46f33521 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.
17cec454 56
46f33521 57 If you want your users to attach files to their mails, make sure
58 File Uploads in php.ini is set to On.
17cec454 59
17cec454 60
46f33521 64 This depends a lot on the server your choose. See the documentation
65 that comes with your server.
598294a7 66
46f33521 67 If you're concerned about people accessing it directly, you can
68 limit access to only the IP of the webserver.
17cec454 70
ef1932a4 74 SquirrelMail is constantly being improved. Therefore you should always
46f33521 75 get the newest version around. Look at
ef1932a4 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
46f33521 78 fashionable bugs).
17cec454 79
80a. Download SquirrelMail
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.
87b. Setting up directories
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.
93 The data directory is used for storing user preferences, like
94 signature, name and theme. When unpacking the sources this directory
b731cd83 95 is created as data/ in your SquirrelMail directory. This directory
17cec454 96 must be writable by the webserver. If your webserver is running as
b731cd83 97 the user "nobody" you can fix this by running:
65b14f90 98
390372b4 99 $ chown -R nobody data
100 $ chgrp -R nobody data
4bc627ae 101
102 Keep in mind that with different installations, the web server could
598294a7 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
ff65039a 105 the web server's configuration file.
4bc627ae 106
17cec454 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)
390372b4 116 $ cd /var/some/place
117 $ mkdir SomeDirectory
118 $ chgrp -R nobody SomeDirectory
119 $ chmod 730 SomeDirectory
17cec454 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
598294a7 123 or simply use /tmp as you attachments directory.
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
390372b4 127 remove them. To fix this, it is recommended to create a cron job that
128 deletes everything in the attachment directory. Something similar
4bc627ae 129 to the following will be good enough:
390372b4 130
131 $ cd /var/attach/directory
132 $ rm -f *
598294a7 133
4bc627ae 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'.
598294a7 139
4bc627ae 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
598294a7 142 attachment directory is the same as your data directory) might look like
4bc627ae 143 this:
598294a7 144
4bc627ae 145 $ rm `find /var/attach/directory -atime +2 | grep -v "\." | grep -v _`
598294a7 146
4bc627ae 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.
17cec454 149
150c. Setting up SquirrelMail
cbd6543c 152 There are two ways to configure SquirrelMail. In the config/ directory,
be8e07f8 153 there is a perl script called that will aid you in the
390372b4 154 configuration process. This is the recommended way of handling
be8e07f8 155 the config.
390372b4 157 You can also copy the config/config_default.php file to config/config.php
be8e07f8 158 and edit that manually.
65b14f90 159
cbd6543c 160 After you've created a configuration, you can use your webbrowser to
13721b47 161 browse to http://your-squirrelmail-location/src/configtest.php.
cbd6543c 162 This will perform some basic checks on your config to make sure
163 everything works like it should.
65b14f90 168
429f8906 169 Point your browser at the URL at which SquirrelMail is installed. A
598294a7 170 possible example of this is:
429f8906 171
598294a7 172
3d8fe250 173 It should be pretty straight forward to use. Some more documentation
429f8906 174 might show up one day or another.
8c086db6 175
180 For information on how to make SquirrelMail work with Russian
181 Apache, see the README.russian_apache in the doc/ subdirectory.
2481e3c1 182
46f33521 183
2481e3c1 1846. TRANSLATIONS
598294a7 187 In order to use translated versions of SquirrelMail, you need
2481e3c1 188 to download and install locale packages that contain translations
598294a7 189 that you want to use with SquirrelMail.
2481e3c1 191 Locale packages can be downloaded from SquirrelMail SourceForge
192 project page.
598294a7 193
2481e3c1 194
598294a7 195
2481e3c1 196 Each translation contains install script that copies required files
197 into appropriate locations. If you can't run that script, you can extract
598294a7 198 contents of translation packages into your SquirrelMail directory.
2481e3c1 200 NOTE No.1: *-src.tar.gz, *-src.tar.bz2 and * archives does not contain
201 compiled translation files. You will need to run compilelocales script
202 in order to get all gettext binary translations.
598294a7 203
2481e3c1 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.