moving functions to separate file, adding configuration files
[squirrelmail.git] / INSTALL
CommitLineData
d68a3926 1Installing SquirrelMail
2=======================
3
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
13
46f33521 140. QUICK INSTALL GUIDE
15----------------------
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/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.
2a32fc83 33
1067414d 34
46f33521 351. CONFIGURE YOUR WEBSERVER TO WORK WITH PHP4
36---------------------------------------------
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.
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.
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)
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.
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
612. SETTING UP IMAP
62------------------
63
46f33521 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
17cec454 70
713. OBTAINING AND INSTALLING SQUIRRELMAIL
72----------------------------------------
73
ef1932a4 74 SquirrelMail is constantly being improved. Therefore you should always
46f33521 75 get the newest version around. Look at http://www.squirrelmail.org
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
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
87b. 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
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
ff65039a 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.
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)
115
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
390372b4 123 or simply use /tmp as you attachments directory.
124
4bc627ae 125 If a user is aborting a mail but has uploaded some attachments to it
390372b4 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
4bc627ae 129 to the following will be good enough:
390372b4 130
131 $ cd /var/attach/directory
132 $ rm -f *
4bc627ae 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.
17cec454 149
150c. Setting up SquirrelMail
151
cbd6543c 152 There are two ways to configure SquirrelMail. In the config/ directory,
be8e07f8 153 there is a perl script called conf.pl that will aid you in the
390372b4 154 configuration process. This is the recommended way of handling
be8e07f8 155 the config.
156
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.
164
165
17cec454 1664. RUNNING SQUIRRELMAIL
167-----------------------
65b14f90 168
429f8906 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
3d8fe250 173 It should be pretty straight forward to use. Some more documentation
429f8906 174 might show up one day or another.
8c086db6 175
176
1775. 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.
2481e3c1 182
46f33521 183
2481e3c1 1846. 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.