root / pykota / trunk / README @ 1580

# $Id$

PyKota - Print Quota for CUPS and LPRng

(c) 2003-2004 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.

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

   NOTE FOR LPRNG USERS :
   
     FROM MAY 21ST 2004 ON, AND UNTIL THIS NOTE IS REMOVED
     FROM THIS FILE, PYKOTA CAN'T BE USED ANYMORE WITH LPRNG.
     
     SUPPORT FOR LPRNG SHOULD BE RE-ADDED SOON WHEN A HUGE REWRITE
     OF SOME PARTS OF PYKOTA WILL HAVE TAKEN PLACE

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

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

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

PyKota features :
-----------------

    Operating systems :
    
        - Any Unix-like system as print server.
            
        - Any operating system as client.
            
    Printing systems :
    
        - Supports both CUPS and LPRng as the printing system.
        
          NB : LPRng support is currently being rewritten, so
          LPRng is actually not supported in latest CVS versions.
            
    Databases :
    
        - Supports PostgreSQL as the Quota Storage backend.
          Complete database creation script in SQL is included.
        
        - Supports OpenLDAP as the Quota Storage backend.
          Complete LDAP schema and sample empty tree are included.
          Plugging PyKota into your existing LDAP infrastructure
          is really easy thanks to PyKota's great configurability.
            
    Printers :        
    
        - Hardware or Software accounting methods are completely
          configurable.
          
        - Supports any printer which can report its internal
          page counter. Can ask printers for their internal 
          page counter via SNMP, Netatalk, PJL, PS, or any 
          other way.
          This is completely configurable.
          
        - Supports DSC compliant PostScript, PDF, PCL5, and
          PCLXL (aka PCL6) printers natively for software 
          accounting methods. More formats to come.
            
    Quota systems :        
    
        - Supports printers and printers groups quotas.
        
        - Supports users and users groups quotas.
        
        - Supports page quotas.
          Page quotas can be set differently on a per printer
          and per user/group basis.
        
        - Supports account balance quotas in any currency.
          Account balance quotas can be set on a per user 
          basis. The account balance is shared amongst
          all printers. The history of payments (positive
          or negative credits to an user account) is kept.
          
        - Page quota and account balance can be set/reset
          independantly.
          
        - Limiting factor, page quota or account balance,  
          can be set on a per user or per group basis.
          
        - Price per page and per job can be set differently  
          on any printer.
        
        - Low level of page quota or account balance are
          configurable.
          
        - Both soft and hard limit with configurable grace delay  
          can be set for page quota.
          
        - Possibility to disable quota enforcement for any user
          or group, while still keeping page accounting.
              
    Administration :        
    
        - Powerful administration tools can be used to
          automate setting or resetting of quotas or
          account balances at specific intervals.
          
        - Administration tools can modify several users,  
          groups, or printers at once.
          
        - Account balances can be set, incremented, or  
          decremented. History of payments is kept.
          
        - Both printers and users can be automatically added on 
          first print in a completely configurable way.
          
        - Quota report generator available either from the  
          command line or in any web browser.
          The web-based quota report generator can be 
          user/password protected.
          
        - Print quote generator can tell users how much  
          a print job will cost them in advance.
          
        - Policy with regard to unregistered users can   
          be configured for each printer to either deny
          printing, allow printing, or delegate the
          decision to any external tool.
          
        - Warning and error messages can be automatically  
          sent via email to the administrator, the user,
          both, or none.
          
        - Warning and error messages' content is completely 
          configurable.
          
        - Configuration can be changed without needing to  
          restart the printing system.
        
        - Complete print job history is kept. This can be
          disabled if needed.
          
        - Automated low quota or balance remainder can be 
          scheduled regularly or launched manually.
          
    User Interface :          
    
        - All the command line tools accept the -h | --help 
          command line option which prints all the available 
          options and show usage examples.
          
        - Completely internationalized. Actually supports the  
          English, French, Spanish, Portuguese, Brasilian, Swedish 
          and Italian languages. More to come.

====================================================================
        
Planned features are described in the TODO file.

Actually two (or an infinity of) page accounting methods are
implemented :

  - The 'hardware' method consists in querying the printer (via SNMP
    or Netatalk or any other method of your choice) for its total pages 
    counter.
    
    With CUPS, this is done both at the beginning and at the end of a
    print job. The counters difference is then immediately used to 
    decrease the user's account balance or increase his quota usage.
    
    With LPRng, this is done just before the beginning of a job, and used 
    this to modify the *preceding* user's quota. So you're always late 
    of one print job, but this is generally ok.
    
  - The 'software' 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. Changes to the user
    account are reported immediately, both with CUPS and LPRng.
    
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. It should work
fine with most network printers.

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

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

NB :
====

  You may learn more about PyKota, if it fits your own organization,
  its internal working, and some potential performance drawbacks and
  how to avoid them, in a WiKi administered by Ryan Suarez at :
  
    http://webcrossing.macosxlabs.org/webx?14@30.QAu3a5k0c4z.7@.26bf4661

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.
    
  On Intel i386 architecture, and for performance reasons if you 
  print in PCL5 or PCL6 format, it is strongly suggested that you  
  install the Python accelerator Psyco, available at :
  
      http://psyco.sourceforge.net
      
  Under Debian :    
  
      $ apt-get install python-psyco
      
  Other architectures may be supported as well in the future, check    
  on Psyco's website.
  
  Installing Psyco is not mandatory, but it will speedup PCL5 parsing
  by almost 3 times. PostScript and PDF parsing can also benefit,
  but in an almost unnoticeable manner since this part of the code
  is already optimal. For PCL5 this is a completely different matter,
  and if you install Psyco you will never regret it !
  Same remark applies for PCL6 (aka PCLXL) but performance improvement
  is yet to be fully tested (it is very high anyway).
  
  You may also benefit from having the following tools installed to
  deal with some printers :
  
    - npadmin
    - netcat
    - ghostscript
    
  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. 
  BEWARE : under Debian Sarge, as of March 15th 2004, there's a
  problem with python2.2-pygresql and python-2.3-pygresql, so please
  install python2.1-pygresql and use Python 2.1 to install and run
  PyKota. This is not a bug in PyKota, and this should be fixed
  by Debian in a few days I hope.
  
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 which by default is root@localhost.
Read and try to understand these two very well commented files,
so that you'll encounter less problems later.

Also be sure to double check that commands that query printers
for their internal page counter work from the command line
before using them in PyKota's configuration.

The rest of the installation depends on your printing system :

  - CUPS Printing System :
  
    Once and for all :
    
        Create a symbolic link to the cupspykota backend 
        in CUPS's backend directory :
        
          $ cd /usr/lib/cups/backend
          $ ln -s /usr/share/pykota/cupspykota cupspykota
          
        Restart CUPS so that the new backend can be detected.
        
          $ /etc/init.d/cupsys restart
          
    For new printers :
    
        Go to CUPS management interface (http://localhost:631) 
        and choose the appropriate PyKota managed device depending
        on the type of printer you use. For example, if your
        printer is waiting on :
        
            socket://myprinter.example.com:9100
            
        Then choose :    
        
            cupspykota:socket://myprinter.example.com:9100
            
        Configure your printer as usual.    
        
        Now double check /etc/pykota/pykota.conf 
        This file should contain a section named after the
        printer you've just added, unless you have set
        all options globally.
        The new pkhint command can help you with correct settings 
        for your printers, but don't rely on it because it is still
        incomplete.
        
        That's all.
    
    For existing printers :
    
        If you had already installed a version of PyKota earlier 
        than 1.16alpha7, then remove the *cupsFilter lines in your 
        PPD files for each printer already managed printers. Each 
        line to remove is of the form :
        
          *cupsFilter: "application/vnd.cups-postscript 0 /usr/share/pykota/pykota"
        
        This means that each time the pstops filter will be executed, it will
        pass the job's data through the pykota filter which is present in 
        /usr/share/pykota
        
        Don't touch anything else, especially any other *cupsFilter line.
        Then save each of these files.
        
        Then, the easiest is to directly modify the DeviceURI lines 
        in /etc/cups/printers.conf, you just have to put 
        'cupspykota:' in front of what is already on these lines. 
        For example, replace :
    
            DeviceURI socket://myprinter.example.com:9100
        
        with :    
    
            DeviceURI cupspykota:socket://myprinter.example.com:9100
            
        or :    
        
            DeviceURI cupspykota://socket://myprinter.example.com:9100
        
        Save the file and restart CUPS.

  - LPRng Printing System :
  
      For now LPRng support in PyKota is deactivated. Please be patient.
      
Now you can begin to populate the PyKota's database with printers,
users and groups :
  
Add printers and users to the quota system and set their quota values : 

Starting from version 1.18alpha2, the preferred command to manage
printers is named pkprinters

    $ pkprinters --help
    
    will tell you how to create, manage or delete printers and
    printers groups.
    
    $ pkprinters --add --charge 0.05 hp2100
    
    would add the printer named hp2100 with a price per page
    of 0.05 unit.

Now set quotas for users on this printer :     

    $ 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 quota 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. You can 
also use the CSS stylesheet present in the stylesheets/ subdirectory
and put it at your web server's DocumentRoot, to benefit from a nicer 
look, especially quota violations will appear in different colors.

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
    
IRC :    
-----

  You can also chat with us :
  
        /server irc.freenode.net
        /join #pykota
    
============================================================
    
Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
or to the main author at : alet@librelogiciel.com (Jerome Alet)