Index: pykoticon/trunk/README
===================================================================
--- pykoticon/trunk/README (revision 68)
+++  (revision )
@@ -1,647 +1,0 @@
-# $Id: README,v 1.109 2005/01/06 19:42:53 jalet Exp $
-
-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.
-
-====================================================================
-
-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.
-        
-    Databases :
-    
-        - Supports PostgreSQL as the Quota Storage backend.
-          Complete database creation script in SQL is included.
-        
-        - Supports any LDAP server 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 and binary PostScript, PDF, PCL5 (up to), 
-          PCLXL (aka PCL6) and ESC/P2 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 quotas and account balance can be set/reset
-          independantly.
-          
-        - Page quotas and account balances 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.
-          
-        - Starting and Ending personalized dynamic banners can be
-          generated on the fly, and accounted for or not, depending 
-          on some configuration settings.
-          NB : Banners are a CUPS only feature for now.
-              
-    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.
-          
-        - Powerful data dumper to export datas to other
-          software (spreadsheets for example). Actually
-          supported formats are :
-          
-            - Comma separated values ;
-            
-            - Semicolon separated values ;
-            
-            - Tab separated values ;
-            
-            - XML.
-          
-    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,
-          Thai, Greek, German, Italian, Norwegian (Bokm� and 
-          Turkish 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.
-    
-    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.
-    
-  - 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.
-    
-PyKota is known to work fine with most laser printers, either with
-software accounting, or with hardware accounting if the printer
-supports this.
-
-============================================================
-
-SUPPORT CONTRACTS:
-==================
-
-  You can now purchase 8x5x365@NextBusinessDay Technical
-Support Contracts from us. The yearly fee is computed with  
-the following formula :
-
-  (100.0 * NbPrintServers) + (2.5 * NbPrinters) + (0.04 * NbUsers) EUROS.
-  
-  This fee includes the VAT, and a free subscription to official  
-PyKota packages.  
-
-  Please send an email to alet@librelogiciel.com if you're
-interested in purchasing such a contract.   
-
-============================================================
-
-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://archive.macosxlabs.org/forum/webcrossing_archive/documentation/Pykota_and_CUPS/Pykota_and_CUPS.html
-
-  You may also find the following document interesting :
-  
-    http://es.tldp.org/Tutoriales/doc-openldap-samba-cups-python/
-    
-  This document, written in Spanish by Sergio Gonzalez Gonzalez,  
-  describes the integration of PyKota into an OpenLDAP + Samba
-  + CUPS installation. Even for people who can't read spanish 
-  this document is really interesting, and contains lots of
-  screenshots.
-  
-  Finally, SuSe users may find the following document to best describe
-  how to install PyKota on their favorite distribution. It's a Spanish
-  document written by Dennis Romero :
-  
-    http://www.cvr.espol.edu.ec/people/dennis/Pykota1.19-SuSE9.1.pdf
-  
-  
-Prerequisite : 
---------------
-   
-  You need to have the following tools installed on the CUPS Server :
-  
-    - CUPS (http://www.cups.org) or LPRng (http://www.lprng.com)
-    - Python v2.1 or above (http://www.python.org)
-    - eGenix' mxDateTime Python extension (http://www.egenix.com)
-    - The JAXML Python module to be able to dump datas in the XML format.
-      (http://www.librelogiciel.com/software/)
-    - The Python-SNMP module to query printers for their page counter.
-      (http://pysnmp.sourceforge.net). 
-      IMPORTANT : version 3.4.3 (or 3.4.2) is REQUIRED. Versions 2.x or
-      4.x won't work for now.
-    - The Python-OSD module to use the graphical print quota reminder.
-    - SNMP tools (specifically the snmpget command) if you prefer to
-      use your own script to request query printers.
-    - Netatalk (specifically the pap command) if you plan to
-      request your printer's lifetime page counter via AppleTalk.
-      (http://netatalk.sourceforge.net)
-    - The ReportLab Python module (http://www.reportlab.org) if you want  
-      to have PyKota generate nice banners for you.
-    - The Python Imaging Library (aka PIL) module 
-      (http://www.pythonware.com/downloads) if you want to have PyKota 
-      generate nice banners for you.
-    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
-      libraries if you plan to use PostgreSQL as the Quota Storage
-      backend.
-      (http://www.postgresql.org and http://www.pygreql.org)
- or     
-    - python-ldap Python module and the OpenLDAP client libraries  
-      if you plan to use an LDAP server as the Quota Storage backend.
-      (http://www.openldap.org and http://python-ldap.sourceforge.net)
-    
-  On Intel i386 architecture, and for performance reasons, 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    
-  this 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) : the parser is completely
-  different, but the performance gain with Psyco is impressive.
-  
-  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 (http://www.postgresql.org)
-    
-  or  
-  
-    - OpenLDAP, or any other LDAP server (http://www.openldap.org)
-    
-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 should match the 
-  OpenLDAP version used on the Quota Storage Server, if applicable.
-  
-  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. 
-  
-Hint :  
-------
-
-  - The Debian GNU/Linux distribution is to our knowledge the 
-    easiest distribution to install PyKota on, because all
-    of PyKota dependencies are already included, excepted
-    for the PySNMP (http://pysnmp.sourceforge.net) module
-    which for now has to be downloaded separately.
-
-Then :   
-------
- 
-Download the latest PyKota version from the CVS tree on :
-
-    http://savannah.nongnu.org/projects/pykota
-
-You can now check if the dependencies are correct by typing :
-
-    python checkdeps.py
-    
-To install the software, just type :
-
-    python setup.py install
-
-You may need to be logged in with sufficient privileges (e.g. root)
-
-Create a system user for PyKota :
-
-    adduser --system --group --home /etc/pykota --gecos PyKota pykota
-    
-Put the user your printing system is run as in the pykota system group :
-
-    adduser lp pykota
-    
-    NB : on our system, the CUPS printing system runs as system user 'lp'.
-    Please adapt this to your own system.
-
-Go to the initscripts subdirectory of PyKota's sources, and choose
-the appropriate storage backend for your configuration. Read carefully
-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 usually copies these files into /usr/share/pykota
-
-NB : You can move PyKota's configuration files elsewhere, they will
-be searched first in user pykota's home directory.
-
-You need to adapt these files to your own needs. Especially you may 
-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
-          
-        or :    
-      
-          $ /etc/rc.d/init.d/cupsys restart
-          
-        or any similar command depending on your operating system.  
-          
-    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 
-        
-        You should manually create 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
-        experimental work. To use pkhint, you have to feed it with
-        CUPS' printers.conf file this way :
-        
-          $ pkhint </etc/cups/printers.conf
-        
-        pkhint will try to tell you what is the best accounting
-        method for each printer and will print some lines you'll
-        just have to copy&paste in the appropriate sections in
-        /etc/pykota/pykota.conf
-        
-        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 already managed printer. 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.
-        
-        Here too, you may find it interesting to use the pkhint command as
-        described above to help with manual configuration of the file
-        /etc/pykota/pykota.conf
-
-  - LPRng Printing System :
-  
-    For each printer on which you want to use PyKota :
-    
-        Modify the printer's entry in /etc/printcap : you have to add
-        the three following lines :
-        
-          :achk=true:\
-          :as=/usr/share/pykota/lprngpykota:\
-          :ae=/usr/share/pykota/lprngpykota:\
-          
-        This will tell LPRng to activate accounting, and use the lprngpykota 
-        accounting filter both at the start and at the end of printing. 
-        
-    When all modifications are done, just save the /etc/printcap file and    
-    restart LPRng :
-    
-          $ /etc/init.d/lprng restart
-          
-        or :    
-      
-          $ /etc/rc.d/init.d/lprng restart
-          
-        or any similar command depending on your operating system.  
-        
-    NB : the pkhint command can't be used with LPRng for now, so you    
-         have to modify /etc/pykota/pykota.conf carefully. The comments
-         in this file will help you.
-      
-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.
-           
-============================================================
-
-Additionnal tools :
--------------------
-
-Some people have developped tools around PyKota, and make
-them available under the GNU General Public License :
-
-  - Kanakorn Horsiritham developped phpPykotaAdmin which is 
-    a web based administrative GUI :
-  
-      http://opensource.psu.ac.th/~kanakorn/mambo/
-  
-Additionnal software will be listed here when they will be  
-ready.
-
-============================================================
-
-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
-    
-  The mailing list is the preferred way to obtain support, because  
-  all members can help and can also benefit from the solutions
-  proposed by other members. 
-  
-  Posts by non-members are usually rejected.
-  
-  The mailing list language is english and only english.
-    
-IRC :    
------
-
-  You can also chat with us :
-  
-        /server irc.freenode.net
-        /join #pykota
-        
-  Preferred language on this channel is english, but french      
-  is also accepted. Try to avoid exposing complex problems
-  in french because english speaking people on the channel
-  wouldn't benefit from the solutions.
-  
-  PyKota's main author is known as 'tamere' on IRC.
-    
-============================================================
-    
-Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
-or to the main author at : alet@librelogiciel.com (Jerome Alet)
