INSTALLATION INSTRUCTIONS:

Disk Quota Plugin
version 2.5

=================================================================

WHAT DO I NEED TO USE THIS PLUGIN?

- SquirrelMail configured and running on any Unix/Linux system
- Diskquota installed on your IMAP server
- A PHP enabled webserver installed on the machine that holds
  the IMAP server if SquirrelMail and IMAP server are not on
  the same machine.

=================================================================

ON WHICH CASES CAN I USE THIS PLUGIN?

This plugin may be used on both these cases:

1. SquirrelMail and IMAP server are on the same machine.
2. SquirrelMail and IMAP server are on seperate machines.

=================================================================

HOW CAN I INSTALL THE PLUGIN?

For the two cases mentioned above, you will have two different
installation procedures.

1. If SquirrelMail and IMAP server are on the same machine,

Ungzip and untar the plugin into the plugins directory of
SquirrelMail. After that go to the section:
"HOW CAN I CONFIGURE THE PLUGIN" of this file.

2. If SquirrelMail and IMAP server are on different machines,

Ungzip and untar the plugin into the plugins directory of
SquirrelMail.

To have the plugin work correctly, you must have a PHP enabled
webserver on your IMAP server. For Apache webserver, you should
follow these instructions.

  a. If not installed, install an Apache webserver with PHP on
     the machine that is your IMAP server.
  b. Open the httpd.conf file of Apache and create a Virtual Host
     that will hold the needed files for the plugin. You must
     create something like:

     <VirtualHost 192.168.1.2>
     ServerAdmin webmaster@yourdomain.com
     DocumentRoot /usr/local/apache/htdocs/quota_plugin
     ServerName quota.yourdomain.com
     ErrorLog        logs/quota-error.log
     CustomLog       logs/quota-access.log common
     </VirtualHost>

  c. Copy the check_quota_sv.php and left_quota_sv.php to the
     document root of your newly created virtual host.
  d. Restart the webserver with apachectl program.
  e. Don't forget to add quota.yourdomain.com to your DNS list.
  f. (optional) Add an .htaccess file to the document root of
     your Virtual host and add these lines to that file:

     Deny from All
     Allow from 192.168.1.100

     192.168.1.100 would be replaced by the IP of the machine
     on which SquirrelMail is running. By doing this, you only
     give the SquirrelMail machine to access the check_quota.php
     and left_quota.php, which will give you improved security.

After completing all these steps successfully, nslookup to
quota.yourdomain.com. If it can be resolved correctly, you can
go to the next section.

=================================================================

HOW CAN I CONFIGURE THE PLUGIN?

The plugin has been completely rewritten for simplicity and
functionality. It has an options.php on which all options for
the plugin need to be configured for once.

For the two cases above, you need to do several necessary steps
in order to have the plugin work correctly.

Open the options.php with a text editor after this:

1. If SquirrelMail and IMAP server are on the same machine,

You must set three variables which are:
$dq_check_quota_on_remote, $dq_quota_binary and
$dq_strange_binary.

Obviously, you can see by the name, $dq_check_quota_on_remote
should be set to 0 as you will check quota on local :-)

For the version of SM you use, you must set the $dq_sm_is_13_or_newer
correctly. See options.php for details.

For the $dq_quota_binary, you have several choices. Read the
"WHICH WAY SHOULD I CHOOSE TO USE THE QUOTA BINARY?" section and
choose one of the three ways from that section. After choosing,
you must state the path to your quota binary with this variable.
Because of the execution mechanism of the plugin, you should not
use spaces on this variable. Use "_" instead of spaces. So for
example if you will be using the third way, you must write
something like:

$dq_quota_binary = "sudo_/usr/bin/quota";

on the options.php page.

After setting $dq_quota_binary read the instructions for
setting the $dq_strange_binary on options.php. This variable
MUST be set correctly or the plugin will behave abnormally, or
give errors.

2. If SquirrelMail and IMAP server are on different machines,

You must set five variables which are:
$dq_check_quota_on_remote, $dq_imap_server, $dq_quota_binary,
$dq_strange_binary and $dq_sm_is_13_or_newer.

For this case, you must set $dq_check_quota_on_remote to 1,
as IMAP server is on another machine.

After setting this variable, you must tell the plugin, the http
address of the Virtual host that you created on your IMAP server.
To do this, you will set the $dq_imap_server variable as your
Virtual host's http address. This will be something like:

$dq_imap_server = "http://quota.yourdomain.com";

DON'T forget the http:// and DON'T put a trailing slash after the
domain name as http://quota.yourdomain.com/. If you do these
mistakes, your plugin won't work.

For the version of SM you use, you must set the $dq_sm_is_13_or_newer
correctly. See options.php for details.

For $dq_quota_binary, and $dq_strange_binary,the same conditions
as the 1st (local) case apply.
Read the "WHICH WAY SHOULD I CHOOSE TO USE THE QUOTA BINARY?"
section and choose the way you want. You must not use spaces.

After that you will be able to check quota on your IMAP server.

=================================================================

CAN I LOCALISE THE PLUGIN?

Definitely. Just create an appropriate directory for your locale
in the locale directory (ex. For German de_DE) and copy the
disk_quota.po to LC_MESSAGES directory in this directory. After
that you can localise the strings in disk_quota.po. When you
finish localising, use this command:

#: msgfmt -o disk_quota.mo disk_quota.po
and restart your webserver. Your new strings will appear
immediately :-)

=================================================================

The next section was taken from the original plugin written by
Claudio Panichi. As the original plugin and this plugin execute
the quota binary the same way, the rules below apply to this
plugin also.

=================================================================

WHICH WAY SHOULD I CHOOSE TO USE THE QUOTA BINARY?

Well, first of all you have to identify the user running the
web-server on you system. You could procede like that:

[root@monster root]# ps aux |grep http
root      1135  0.0  0.8 45320 4612 ?        S    17:34   0:00 httpd -DHAVE_PHP4
apache    1143  0.0  1.4 47672 7376 ?        S    17:34   0:00 httpd -DHAVE_PHP4
apache    1144  0.0  1.4 47748 7440 ?        S    17:34   0:00 httpd -DHAVE_PHP4
apache    1145  0.0  1.4 47764 7460 ?        S    17:34   0:01 httpd -DHAVE_PHP4
apache    1146  0.0  1.3 47492 7152 ?        S    17:34   0:01 httpd -DHAVE_PHP4
apache    1848  0.0  1.4 47604 7224 ?        S    17:48   0:00 httpd -DHAVE_PHP4
apache    1852  0.0  1.1 46560 6148 ?        S    17:48   0:00 httpd -DHAVE_PHP4
[root@monster root]#

which means that "apache" is the user running the httpd server.
It usually happens (on unix systems) that quota command is executable
by any user, but each user can ONLY query his own disk-quota usage,
while user root can obviously look at anyone's quota!
In order to let the plugin work, the user running httpd (let's suppose
it's the user Apache) must have the same power of root: he must be
able to ask quota for any user.

Please notice that you cannot "chown apache:apache /usr/bin/quota" for
example. It will NOT work because the quota binary simply retrive some
data from a special database which permissions are:

-rw-------    1 root     root         7168 gen 19 15:15 aquota.group
-rw-------    1 root     root         7168 gen 19 15:15 aquota.user

so even if quota-binary is owned by apache, the access to the databases
is still denied. The only way to procede if... having a kind of setuided
quota binary.
Indeed, you have three ways to go on:

FIRST WAY: (simplest, but not very secure for the privacy)
You could simply "chmod +s /usr/bin/quota", so that any user will run
quota binary as root. There is "just" a privacy issue with it: anyone
could check quotas for any other one! It's not very nice, because the
user you hate could discover that he got 30 MB of disk-quota, while
your girlfriend got 1 GB on raid-1! =;-p
Anyway you can surely use this simple solution (chmoding +s the quota
binary) if user have only got IMAP(s)/HTTP(s) access to the server. It
can happen if any user does not have a shell (let's say he have some-
thing like /bin/false) and the server is just IMAP and WWW...

SECOND WAY: (definitely better if users have a real shell)
I have to thank Jakub Grygiel (kubas@kul.lublin.pl) for this nice
suggestion. I simply report his mail: I test it and it works very
well on my system. So here you are:

/*
 *	We have to copy quota binary to wwwquota (for example)
 *	Then:
 *
 *	chown root:apache wwwquota
 *	chmod 4750 wwwquota
 *
 *	In options.php we have to change line with $quota_binary:
 *	
 *	$dq_quota_binary="/usr/bin/wwwquota"
 *
 *	So only wwwquota will be suided and none of the users can
 *	use it except apache users.
*/

the last problem is that users having www account (I mean: a user who
can upload their www pages) can still use a php script with a call
to the quota-binary (just like the one in options.php) to run quota
as apache, and then he can know all of the quota.
Sorry, but I do not have a "global" solution at the moment: please
consider to email me (claudio.panichi @roma2.infn.it) any eventual
hint about it.

THIRD WAY: (Thanks to Harry Yu, Andrzej Wojkowski, Jorge Paramo)
It seems that FIRST and SECOND way won't work on some systems like
Solaris, BSD and some Linux distribuion (RedHat afaik). So this is
the last resource to make this plugin work on those systems: you can
simply try using "sudo". For example, on Solaris you must add

     nobody  ALL=NOPASSWD: /usr/lib/fs/ufs/quota -v *
or
     apache  ALL= NOPASSWD: /usr/bin/wwwquota -v [A-z]*

into /etc/sudoers. This seems to fix the problem!

After selecting your way, add the path to quota binary to
$dq_quota_binary in options.php

=================================================================

REPORTED SUCCESS

We have been notified about a fine working of this plugin on...

- Linux Mandrake 8.1
- Solaris
- RedHat
- BSD
- Debian Linux
- Gentoo Linux

=================================================================

If the plugin fails after installation, please let me know
by mailing <kerem.erkan@hacettepe.edu.tr>
Also if you have no problems, I would like to hear about your
operating system.
