root / pykota / trunk / README @ 927

# $Id$

PyKota - Print Quota for CUPS

(c) 2003 Jerome Alet <alet@librelogiciel.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

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

READ SPECIAL LICENSING AND REDISTRBUTION TERMS IN THE FILE 'LICENSE'

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

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.

Actual working features :

        - Per printer user and group quotas.
        
        - Automated email warning of users above quota to the
          user himself and to the print quota administrator.
        
        - CUPS filter for quota accounting : pykota
        
        - Command line print quota editor : edpykota
        
        - Command line print quota report generator : repykota
        
        - Command line print quota automated warning sender : warnpykota
        
        - Command line tools mimic the disk quota utilities for
          easier mastering.
        
        - Centralized storage of quotas : you can manage quotas for
          different printers on different print servers and store them all
          on the same quota storage server. 
          WARNING : actually all your printers must have an unique name,
                    but this may change in a future version.
                    
        - SNMP querying of any networked SNMP-enabled printer. 
        
        - Netatalk querying of any networked AppleTalk-enabled printer. 
        
        - External command querying of any printer : you can use
          you own querying command, e.g. to query a printer via
          the serial port, sending it a special PJL job and 
          reading the result. See the example scripts in the
          "untested" directory and try to adapt them to your
          configuration.
        
        - Special scripts included for a seamless integration of
          PyKota on Debian machines.
          
        - Complete job history is saved. This will allow more
          complex reports in the future.
          
        - Price per page and price per job can be defined for  
          every printer. A job's price is the sum of the
          price per job for this printer plus the number of
          pages multiplied by the price per page for this
          printer.
          
        - User's account balance and lifetime paid money are now
          stored in the Quota Storage, and account balance can be
          used to limit the user printing instead of a print quota.
          Actually you can limit either by account balance OR by
          print quota, but maybe both should be checked at the 
          same time. Tell me what you prefer.
          
All the command line tools accept the -h | --help command line option
which prints all the available options and show usage examples.
        
Planned features are described in the TODO file.

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

  The lazy method consists in querying the printer (actually via SNMP 
  or Netatalk) 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 theorically arise in batches of successive print jobs by 
  different users when there's no sleep time between two jobs : the 
  used pages may theorically be attributed to an incorrect user in the 
  case that the printer is asked for its page counter at the beginning 
  of a new job and before the end of the previous job. This depends on 
  the printer speed and time between jobs, but so far I've not seen 
  any problem with moderately used printers. This also depends on CUPS 
  internal behavior : if CUPS doesn't begin to send a job to a printer 
  before the previous one is completely printed, then there's no 
  problem. 
  
  Other querying methods which won't suffer from this possible 
  problem, but probably from other ones ;-) will be implemented in the 
  future. 
  
PyKota is known to work fine with HP Laserjet 2100 and 2200, and 
Apple LaserWriter 16/600 PS. 

It should also work fine with any printer capable of outputing 
its lifetime printed pages counter via either SNMP or AppleTalk. 

If your printers don't support SNMP or AppleTalk, then making them 
work with PyKota is up to you. Some sample scripts which can query 
non-SNMP printers for their lifetime page counter are included in 
the ./untested directory. You'll have to test and adapt them though, 
and define them as external requesters in the PyKota configuration 
file. See the sample configuration file to learn how to do that.

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

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

WARNING :
=========

  If you run a PyKota version lower than 1.01, you definitely have to 
  upgrade you Quota Storage Database. Please read the documentation 
  included in the initscripts subdirectory first ! 
  
Prerequisite : 
--------------
   
  You need to have the following tools installed on the CUPS Server :
  
    - CUPS
    - Python v2.1 or above
    - eGenix' mxDateTime Python extension
    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
      libraries.
    - SNMP tools (specifically the snmpget command) if you plan to
      request your printer's lifetime page counter via SNMP.
    - Netatalk (specifically the pap command) if you plan to
      request your printer's lifetime page counter via AppleTalk.
    
  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.
  
  This list of prerequisite software may change in the future, when
  PyKota will support more functionnalities you will be given 
  alternatives.
  
  Of course the CUPS Server and the Quota Storage Server can be the 
  very same machine if you've got a tiny network, or you can have 
  multiple CUPS Servers all storing their quotas on the same Quota 
  Storage Server if you've got a bigger network. 
  
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)

The installation script will now automatically check if some software
is missing and ask you if you still want to proceed with the 
installation or abort it completely.

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. Upgrade scripts may be 
provided as well.

Copy the conf/pykota.conf.sample sample configuration file to
/etc/pykota.conf, and adapt this file to your own needs and 
configuration. The installation script tries to do this for
you if needed and you agreed to this action.

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.
          
WARNING : In the case you've got a non-postscript printer, chances
          are that the *cupsFilter is already filled-in and points
          to cupsomatic or such a print filter. In this case please
          check if you can switch your printer to PostScript mode
          or if there's a way to make it accept PostScript jobs.
          If yes then ensure that your workstations uses a PostScript
          printer driver, and replace the *cupsFilter line with the
          one pointing to the pykota filter. This should work, but
          is currently untested.
          If your printer really needs the original *cupsFilter line
          then you may not be able to use PyKota easily for now.

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.

To see printer command usage, you can use :

    $ repykota --printer lp
    
or :

    $ repykota
    
    which will print quota usage for all users on all printers,
    along with totals.
    
SECURITY : You should ensure that only the print quota administrator
           can run the warnpykota command, but this is actually not
           enforced in the program. Any user able to launch warnpykota
           could flood over-quota users' email boxes.
           
           You should ensure that only the print quota administrator
           can run the edpykota command, but this is actually not
           enforced in the program. Otherwise, any user could modify 
           his/her or other people's print quota.
          
           launching : chmod 750 /usr/bin/warnpykota /usr/bin/edpykota
           should make you reasonably safe.
           
============================================================

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