root / pykota / trunk / README @ 737

# $Id$

PyKota - Print Quota for CUPS

(c) 2003 Jerome Alet <alet@librelogiciel.com>
You're welcome to redistribute this software under the
terms of the GNU General Public Licence version 2.0
or, at your option, any higher version.

You can read the complete GNU GPL in the file COPYING
which should come along with this software, or visit
the Free Software Foundation's WEB site http://www.fsf.org

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

PyKota is a complete Print Quota system for the Common Unix Printing
System (aka CUPS), which works by directly querying the printers
for the number of pages they have printed.

Actually only the lazy quota method is implemented. What do I call
lazy method ?

  The lazy method consists in querying the printer via SNMP for
  its total pages counter, just before the beginning of a job, and
  use this to modify the *preceding* user's quota. So you're
  always late of one print job, but this is generally ok, especially
  because a check is also done to see if the current user is allowed
  or not to print.
  
  Problem may arise however in batches on successive print jobs 
  by different users when there's no sleep time between two jobs :
  the used pages may be attributed to incorrect user. This
  depends on the printer speed and time between jobs.
  
  Other querying methods which won't suffer from this problem,
  but probably from other ones ;-) will be implemented in the 
  future.
  
PyKota is known to work fine with HP Laserjet 2100 and 2200   
networked printers.

Planned features are :

        - Easier installation.
        
        - Per printer Group quotas. Currently Group
          quotas are only at skeleton stage.
        
        - Configurable printer querying methods. Currently
          only SNMP method is supported.
          
        - More Quota Storage backends.  

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

INSTALLATION:
=============

Prerequisite : 
--------------
   
  You need to have the following tools installed on the CUPS Server :
  
    - CUPS
    - Python
    - eGenix' mxDateTime Python extension
    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
      libraries.
    - SNMP tools (specifically the snmpget command)
    
  You need to have the following tools installed on the Quota Storage  
  Server :
  
    - PostgreSQL
    
  PygreSQL and the PostgreSQL client libraries's versions on the CUPS 
  Server must match the PostgreSQL version used on the Quota Storage 
  Server.
  
  Of course the CUPS Server and the Quota Storage Server can be the  
  very same machine. 
  
  This list of prerequisite software may change in the future, when
  PyKota will support more functionnalities you will be given 
  alternatives.
  
Then :   
------
 
Download the latest PyKota version from the CVS tree on :

    http://savannah.nongnu.org/projects/pykota

Just type :

    python setup.py install

You may need to be logged in with sufficient privileges (e.g. root)

Go to the initscripts subdirectory of PyKota's sources, and choose
the appropriate storage backend for your configuration. Read
the associated README file and execute the initialization script
to create an empty PyKota Storage.

Copy the conf/pykota.conf.sample sample configuration file to
CUPS' configuration directory, usually /etc/cups, under the
name pykota.conf, and adapt this file to your own needs and 
configuration.

Modify the PPD files for each printer on which you want to manage
print quotas, for example /etc/cups/ppd/lp.ppd :

--- Add the line below exactly as-is somewhere near the top ---
*cupsFilter:  "application/vnd.cups-postscript 0 /usr/bin/pykota"
--- Add the line above exactly as-is somewhere near the top  ---

Modify the path to the pykota executable if needed, unfortunately 
you have to supply the correct absolute path here due to CUPS 
internals, or put the pykota executable into /usr/lib/cups/filter 
instead of into /usr/bin. 

Do this for each ppd file present in this directory if you want
to enable quota on every printer.
          
Add printers and users to the quota system and set their quota values : 

    $ edpykota --add -P printer -S softlimit -H hardlimit user1 ... userN
        
    launching edpykota without any argument or with the --help
    command line option will show you all the possibilities.

Restart CUPS, for example under Debian GNU/Linux systems :          

    $ /etc/init.d/cupsys restart
        
Your users now should be able to print but not exceed their 
printing quota.

WARNING : as of today, 2003-02-06, group quotas are not
implemented.

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

Please e-mail bugs to: alet@librelogiciel.com (Jerome Alet)