INSTALLATION INSTRUCTIONS:

Disk Quota Plugin
version 3.1.1

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

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 disk_quota.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 config.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.

Copy the config.php.sample to config.php.

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

You must set four variables correctly to make the plugin work:

  a. $dq_check_on_remote: Should be set to "0" if SquirrelMail and
     IMAP server are on the same machine.

     Should be set to "1" if SquirrelMail and IMAP server are on
     different machines.

  b. $dq_imap_server: If SquirrelMail and IMAP server are on
     different machines, this should be set to the virtual host you
     just created in HOW CAN I INSTALL THE PLUGIN section. If they
     are on the same machine you don't need to configure this variable.

  c. $dq_sm_server: For the both configurations stated above, you should
     set this variable to the http address of your SquirrelMail server. That will be
     something like http://www.smserver.yourdomain.com

  d. $dq_quota_binary: You have several choices for this one. 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.
     For example, if you will be using sudo, you must write something like:

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

     on the config.php page.

That is all!

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

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 config.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 config.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 config.php

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

REPORTED SUCCESS

These operating systems had no problems with the plugin.
Please let me know if your system works correctly, so I can add
it here.

- FreeBSD
- RedHat (Many versions from 7.1 to 9.0)

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

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.
