root / pykota / trunk / README @ 1107

# $Id$

PyKota - Print Quota for CUPS and LPRng

(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 REDISTRIBUTION TERMS IN THE FILE 'LICENSE'

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

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

Actual working features :

        - Supports both CUPS and LPRng backends.
        
        - Can store quota information either with PostgreSQL or with 
          OpenLDAP.
        
        - Per printer user and group quotas.
        
        - Automated email warning of users above quota to the
          user himself and to the print quota administrator.
        
        - 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 print quote maker, to learn how much a print job 
          will cost in advance : pykotme
        
        - 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. 
                    
        - 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.
          
        - External accounting methods : you can use your own accounting
          method to compute each job's size. Just create a shell script
          which reads the job's data from its standard input and prints 
          the job's size on its standard output, and you're done !
        
        - 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. Account balance is shared between printers
          for an user, while quotas are define separately for
          each printer the user prints on.
          
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 three (or an infinity of) page accounting methods are
implemented :

  - The 'querying' method consists in querying the printer (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. You're not limited to SNMP or Netatalk,
    because you can also use any external command instead if you want.
    
  - The 'external' method consists in delegating the computation of the
    job's size in number of pages to any external command of your choice.
    The command can read the job's data from its standard input and MUST
    output the job's size on its standard output.
    
  - The 'stupid' method consists in counting the 'showpage' PostSript  
    statements in the job. THIS IS UNRELIABLE, but can serve as an
    example if you plan to write your own accounting method for
    integration into PyKota.
  
PyKota is known to work fine with HP Laserjet 2100 and 2200, and 
Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under 
Debian GNU/Linux (Sarge and Sid) operating systems.

I'm interested in receiving success or failure reports with other
brands or models of printers, as well as with other operating 
systems.

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

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

WARNING :
=========

  If you run a PyKota version lower than 1.03, you definitely have to 
  upgrade you Quota Storage Database. Please read the documentation 
  included in the initscripts subdirectory first ! 
  
  Users of MacOS-X may find the following tutorial useful :

      http://ell-tech.com/pages/pykota.php

Prerequisite : 
--------------
   
  You need to have the following tools installed on the CUPS Server :
  
    - CUPS or LPRng
    - Python v2.1 or above
    - eGenix' mxDateTime Python extension
    - 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.
    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
      libraries if you plan to use PostgreSQL as the Quota Storage
      backend.
 or     
    - python-ldap Python module and the OpenLDAP client libraries  
      if you plan to use OpenLDAP as the Quota Storage backend.
    
  You need to have the following tools installed on the Quota Storage  
  Server :
  
    - PostgreSQL
    
  or  
  
    - OpenLDAP
    
NB :    

  PygreSQL must be linked with the PostgreSQL client libraries on 
  the Print Server. The PostgreSQL client libraries' version must 
  match the PostgreSQL version used on the Quota Storage Server. 
  
or  

  python-ldap must be linked with the OpenLDAP client libraries on the 
  Print Server. The OpenLDAP client libraries' version must match the 
  OpenLDAP 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 Print Server and the Quota Storage Server can be the 
  very same machine if you've got a tiny network, or you can have 
  multiple Print 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 and  conf/pykotadmin.conf.sample
sample configuration files to /etc/pykota/pykota.conf and 
/etc/pykota/pykotadmin.conf. The installation script tries to do this 
for you if needed and you agreed to this action.
You need to adapt these files to your own needs.
Especially you have to create sections named after your own
printers, and change the administrator's email address.

  - CUPS Print Backend :
  
    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.

  - LPRng Print Backend :
  
    Modify the /etc/printcap file to add two lines identical to these ones :
    
    :achk=true
    :as=|/usr/bin/pykota
    
    For each printer on which you want to use print accounting.
  
Add printers and users to the quota system and set their quota values : 

    $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN
        
    launching edpykota without any argument or with the --help
    command line option will show you all the possibilities.
    
    by default, each user is limited by "quota", this means that on
    each printer he can have a different soft and hard limit.
    You may want to limit the user by his account balance value, 
    in which case, the print quota is shared between all printers
    instead of being different. To do this, use the following :
    
    $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN
    
    This will put 10 $ (or Euros, PyKota doesn't care) on each user's account
    balance, and tell PyKota to limit them by their account balance value.
    Whenever they print on any printer, their account balance value is
    decreased by an amount which depends on the particular price per page
    and per job that you may have defined on the printer with edpykota's
    --charge command line option.
    Soft and Hard limits are not used if "--limitby balance" is used,
    but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf
    to obtain a similar result (warning message when quota is low).

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

    $ /etc/init.d/cupsys restart
    
  or :
  
    $ /etc/init.d/lprng 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, if you are the root user. If you are
    a regular user, only your own quota report will be produced.
    
Quota reports are also available remotely by using the CGI script
printquota.cgi provided in the cgi-bin/ subdirectory.

For different security concerns, please give a look at the SECURITY
file which is part of this software.
           
============================================================

Mailing list :
--------------

  A mailing list is dedicated to Pykota, you can subscribe to it
  or consult its archives at :
  
    http://cgi.librelogiciel.com/mailman/listinfo/pykota
    
============================================================
    
Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
or to the main author at : alet@librelogiciel.com (Jerome Alet)