X-Git-Url: https://vcs.fsf.org/?p=squirrelmail.git;a=blobdiff_plain;f=INSTALL;h=d618837651a0bf749f78b6e1f2da307d2bbe8494;hp=f242ce9ce1aabf3f963df9f50fce4fc510b7e5b1;hb=2229a3ae504ba005fca71bef2c3111e28050e1b6;hpb=3b3d853fc0fe4d408956a7bd9358ca6dde0b1a13 diff --git a/INSTALL b/INSTALL index f242ce9c..d6188376 100644 --- a/INSTALL +++ b/INSTALL @@ -1,93 +1,100 @@ +Installing SquirrelMail +======================= + Table of Contents: - 1. (PHP4) Configure your webserver to work with PHP4 + 0. (QUICK!) Quick install guide + 1. (PHP) Configure your webserver to work with PHP 2. (IMAP) Setting up IMAP (not covered) 3. (INSTALL) Obtaining and installing SquirrelMail 4. (RUN) Running SquirrelMail 5. (CHARSETS) Russian Charsets + 6. (LOCALES) Translations of SquirrelMail + 7. (PLUGINS) Installation of included plugins +0. QUICK INSTALL GUIDE +---------------------- +Each of these steps is covered in detail below. -1. CONFIGURE YOUR WEBSERVER TO WORK WITH PHP4 ---------------------------------------------- - - If your webserver does not already have PHP4 you must configure it - to work with PHP4. SquirrelMail uses the standard suffix .php for - all PHP4 files. This is a quick and dirty guide to installing PHP4 - to run as CGI under Apache. How you end up doing this is up to you - (your mileage may vary). - -a. Obtaining and compiling PHP4 - - Point your favorite webserver at http://www.php.net/version4/ and - download the source. Untar (tar xvfz filename-you-downloaded.tgz) - the source, cd into the directory and run configure. To make PHP4 - work with SquirrelMail a commandline like this should do: - - ./configure --enable-track-vars --enable-force-cgi-redirect --with-gettext - - If you have a database like MySQL you might want to add something - like --with-mysql to get database functionality. +- Install webserver and PHP (at least 4.1.0). +- Install IMAP server (see docs of that server). +- Unpack the SquirrelMail package in a web-accessible location. +- Select a data-dir and attachment dir, outside the webtree (e.g. in /var). + The data-dir (for user prefs) should be owned by the user the webserver + runs as (e.g. www-data). The attachment dir (for uploading files as + attachments) should be file mode 0730 and in the same group as the + webserver. +- Run config/conf.pl from the command line. Use the D option to load + predefined options for specific IMAP servers, and edit at least the + Server Settings and General Options (datadir). +- Browse to http://example.com/yourwebmaillocation/src/configtest.php + to test your configuration for common errors. +- Browse to http://example.com/yourwebmaillocation/ to log in. - If you're going to use LDAP in the addressbook, you must compile PHP4 - with --with-ldap (see the PHP4 docs for more information). - Run make to build the binary file. This will generate a binary file - called "php". Move this file into a CGI-directory. +1. CONFIGURE YOUR WEBSERVER TO WORK WITH PHP +-------------------------------------------- - You might also want to read the INSTALL file in the PHP-distribution - :-) + If your webserver does not already have PHP you must configure it + to work with PHP. You need at least PHP v4.1.0. SquirrelMail uses + the standard suffix .php for all PHP files. -b. Changing php.ini + You can find PHP at http://php.net. See the documentation that + comes with PHP for instructions how to set it up. - PHP defaults to look for php.ini (PHP's configuration file) in - /usr/local/lib. However, for security reasons, it is suggested - that the location of this file is changed to someplace else. This - can be done at configure time with the configuration directive - --with-config-file-path=PATH. + The PHP IMAP extension is NOT necessary at all (but won't harm)! + Below is a list of optional PHP extensions: - Edit the php.ini file and make sure session.use_cookies is 1. Also - be sure to change the session.save_path to someplace that can only - be read and written to by the webserver. session.save_path is the - location that PHP's session data will be written to. + --with-ldap + Required for LDAP addressbooks - SECURITY WARNING - If a user has access to write PHP scripts on your - system and knows the location where PHP stores session data, he - could get a listing of the sessions being used and then read a given - session's data with his own PHP script. Caution should be used when - setting up permissions and locations of php.ini and the session data. + --with-pear and --with-mysql + For MySQL storage of preferences or addressbooks. You will need PHP + compiled with --with-pgsql option, if you want to use PostgreSQL instead + of MySQL. You will need PHP with appropriate database extension, if you + want to use any other database. -c. Setting up .php files to use PHP4 + --with-openssl + Required for encrypted IMAP or SMTP connections (TLS) - You need to create a .htaccess file in you SquirrelMail directory - that looks something like this: + --with-mcrypt + Can be used by SquirrelSpell plugin for encryption of personal + dictionaries - AddType application/php4script .php - Action application/php4script /cgi-bin/php + --with-iconv or --with-recode + Can be used by Eastern charset decoding functions - You could also add these lines to your Apache configuration file. + --enable-mbstring + Required for Japanese translation. Optional for translations that + use non-ISO-8859-1 charset -d. Running into trouble + It is highly advised to NOT turn on register_globals, as this can lead + to security holes. If you must use register_globals for some applications, + turn it on locally for only those directories, or turn it off for the + SquirrelMail folder. + If you want your users to attach files to their mails, make sure + File Uploads in php.ini is set to On. - Setting up Apache with PHP4 can be a non-trivial task. Read the PHP4 - and Apache documentation carefully if you run into trouble. If you - have an experienced system administrator around ask her/him to help - you. 2. SETTING UP IMAP ------------------ - This is not covered here :-/ + This depends a lot on the server your choose. See the documentation + that comes with your server. + + If you're concerned about people accessing it directly, you can + limit access to only the IP of the webserver. + 3. OBTAINING AND INSTALLING SQUIRRELMAIL ---------------------------------------- - SquirrelMail is still under development. Therefore you should always - get the newest version around. Look at - http://squirrelmail.sourceforge.net/index.php3?page=5 to see what it - is. If you want to be bleeding edge you might want to consider using - the latest CVS version (with the latest and most fashionable of - bugs). + SquirrelMail is constantly being improved. Therefore you should always + get the newest version around. Look at http://squirrelmail.org + to see what it is. If you want to be bleeding edge you might want to + consider using the latest SVN version (with the latest and most + fashionable bugs). a. Download SquirrelMail @@ -103,55 +110,140 @@ b. Setting up directories directories outside of your web tree. The data directory is used for storing user preferences, like - signature, name and theme. When unpacking the sources this directory - is created as data/ in you SquirrelMail directory. This directory - must be writable by the webserver. If your webserver is running as - the user nobody you can fix this by running: - - chown -R nobody data - chgrp -R nobody data - + signature, name and theme. You need to create this directory yourself. + Recommended location is under /var, for example: + /var/local/squirrelmail/data + This directory must be writable by the webserver. If your webserver is + running as the user "nobody" and group "nobody" you can fix this by + running: + + $ chown -R nobody:nobody /var/local/squirrelmail/data + + Keep in mind that with different installations, the web server could + typically run as userid/groupid of nobody/nobody, nobody/nogroup, + apache/apache or www-data/www-data. The best way to find out is to read + the web server's configuration file. + There also needs to be a directory where attachments are stored before they are sent. Since personal mail is stored in this directory you might want to be a bit careful about how you set it up. It should be owned by another user than the webserver is running - as (root might be a good choice) and the webserver should have write - and execute permissions on the directory, but should not have read + as (root might be a good choice) and the webserver should have directory + write and execute permissions, but should not have read permissions. You could do this by running these commands (still - granted that the webserver is running as nobody/nobody) + granted that the webserver is running as nobody/nobody): + + $ cd /var/local/squirrelmail/ + $ mkdir attach + $ chgrp -R nobody attach + $ chmod 730 attach + + If you trust all the users at your system not to read mail they are + not supposed to read, you can simply use /tmp as you attachments + directory. + + If a user is aborting a mail but has uploaded some attachments to it + the files will be lying around in this directory forever if you do not + remove them. To fix this, it is recommended to create a cron job that + deletes everything in the attachment directory. Something similar + to the following will be good enough: + + $ cd /var/local/squirrelmail/attach + $ rm -f * + + However, this will delete attachments that are currently in use by people + sending email when the cron job runs. You can either (1) make sure that + the cron job runs at an obscure hour and hope that nobody gets upset, or + (2) you can run a modified version of the commands above. Check out the + man pages for other commands such as 'find' or 'tmpreaper'. - cd /var/some/place - mkdir SomeDirectory - chgrp -R nobody SomeDirectory - chmod 730 SomeDirectory + One sample script you could set up that would erase all attachments, but + wouldn't erase preferences, address books, or the like (just in case your + attachment directory is the same as your data directory) might look like + this: - If you trust all the users on you system not to read mail they are - not supposed to read change the last line to chmod 777 SomeDirectory - or simply use /tmp as you attachments directory. If a user is - aborting a mail but has uploaded som attachments to it the files - will be lying around in this directory forever if you do not remove - them. + $ rm `find /var/local/squirrelmail/attach -atime +2 | grep -v "\." | grep -v _` + + Remember to be careful with whatever method you do use, and to test out + the command before it potentially wipes out everyone's preferences. c. Setting up SquirrelMail - There are two ways to configure Squirrelmail. In the config/ directory, + There are three ways to configure SquirrelMail. In the config/ directory, there is a perl script called conf.pl that will aid you in the - configuration process. This is the most recommended way of handling + configuration process. This is the recommended way of handling the config. - You can also copy the config/config_default.php file to config.php + There's also a plugin called 'administrator' for the webinterface but you'll + have to be able to at least log in to SquirrelMail first. + + You can also copy the config/config_default.php file to config/config.php and edit that manually. + After you've created a configuration, you can use your webbrowser to + browse to http://your-squirrelmail-location/src/configtest.php. + This will perform some basic checks on your configuration to make sure + everything works like it should. + + 4. RUNNING SQUIRRELMAIL ----------------------- - Point your browser at the URL at which SquirrelMail is installed. It - should be pretty stright forward to use. Some more documentation - might show up onbe day or another. + Point your browser at the URL at which SquirrelMail is installed. A + possible example of this is: + http://example.com/squirrelmail + + It should be pretty straight forward to use. Some more documentation + might show up one day or another. 5. RUSSIAN CHARSETS ------------------- For information on how to make SquirrelMail work with Russian - Apache, see the README.russian_apache in the doc/ subdirectory. + Apache, see the russian_apache.txt in the doc/ subdirectory. + + +6. TRANSLATIONS +--------------- + + In order to use translated versions of SquirrelMail, you need + to download and install locale packages that contain translations + that you want to use with SquirrelMail. + + Locale packages can be downloaded from SquirrelMail SourceForge + project page. + + http://sourceforge.net/project/showfiles.php?group_id=311&package_id=110388 + + Each translation contains an install script that copies the required files + into their appropriate locations. If you can't run that script, you can + extract the contents of a translation package into your SquirrelMail + directory. + + NOTE No.1: *-src.tar.gz, *-src.tar.bz2 and *-src.zip archives do not contain + compiled translation files. You will need to run the "compilelocales" script + in order to get all gettext binary translations. + + NOTE No.2: You might need to restart your webserver before using translations. + If you can't do that, install your translations _before_ you use SquirrelMail. + + +7. PLUGINS +---------- + + The SquirrelMail package includes some standard plugins. These plugins can be + enabled in the SquirrelMail configuration script. + + Included plugins can use additional configuration files: + * change_password + configuration file is required. Without it plugin defaults to invalid + backend. See plugins/change_password/README + * filters, fortune, mail_fetch, newmail, translate + configuration files are optional. See README files in plugin directories. + * squirrelspell + configuration is stored in plugins/squirrelspell/sqspell_config.php + The default configuration might not work at your server. + * administrator + plugin must be setup correctly in order to detect administrative user. + See plugins/administrator/INSTALL