root / pykota / trunk / README @ 1066

Revision 1066, 11.4 kB (checked in by jalet, 21 years ago)

Forgotten a comment.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
RevLine 
[695]1# $Id$
2
[952]3PyKota - Print Quota for CUPS and LPRng
[695]4
5(c) 2003 Jerome Alet <alet@librelogiciel.com>
[873]6This program is free software; you can redistribute it and/or modify
7it under the terms of the GNU General Public License as published by
8the Free Software Foundation; either version 2 of the License, or
9(at your option) any later version.
[695]10
[873]11This program is distributed in the hope that it will be useful,
12but WITHOUT ANY WARRANTY; without even the implied warranty of
13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14GNU General Public License for more details.
[695]15
[873]16You should have received a copy of the GNU General Public License
17along with this program; if not, write to the Free Software
18Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
19
[761]20====================================================================
[695]21
[1052]22READ SPECIAL LICENSING AND REDISTRIBUTION TERMS IN THE FILE 'LICENSE'
[761]23
24====================================================================
25
[695]26PyKota is a complete Print Quota system for the Common Unix Printing
[952]27System (aka CUPS) or LPR Next Generation (LPRng), which works by directly
28querying the printers for the number of pages they have printed.
[695]29
[739]30Actual working features :
31
[952]32        - Supports both CUPS and LPRng backends.
33       
[1043]34        - Can store quota information either with PostgreSQL or with
35          OpenLDAP.
36       
[927]37        - Per printer user and group quotas.
[739]38       
39        - Automated email warning of users above quota to the
40          user himself and to the print quota administrator.
41       
[952]42        - Filter for quota accounting : pykota
[739]43       
44        - Command line print quota editor : edpykota
45       
46        - Command line print quota report generator : repykota
47       
48        - Command line print quota automated warning sender : warnpykota
49       
[1066]50        - Command line print quote maker, to learn how much a print job
51          will cost in advance : pykotme
52       
[760]53        - Command line tools mimic the disk quota utilities for
54          easier mastering.
55       
[739]56        - Centralized storage of quotas : you can manage quotas for
57          different printers on different print servers and store them all
58          on the same quota storage server.
59                   
[794]60        - SNMP querying of any networked SNMP-enabled printer.
[739]61       
[920]62        - Netatalk querying of any networked AppleTalk-enabled printer.
63       
[794]64        - External command querying of any printer : you can use
65          you own querying command, e.g. to query a printer via
66          the serial port, sending it a special PJL job and
[840]67          reading the result. See the example scripts in the
68          "untested" directory and try to adapt them to your
69          configuration.
[980]70         
71        - External accounting methods : you can use your own accounting
72          method to compute each job's size. Just create a shell script
[985]73          which reads the job's data from its standard input and prints
74          the job's size on its standard output, and you're done !
[794]75       
[739]76        - Special scripts included for a seamless integration of
77          PyKota on Debian machines.
78         
[900]79        - Complete job history is saved. This will allow more
80          complex reports in the future.
81         
[925]82        - Price per page and price per job can be defined for 
[926]83          every printer. A job's price is the sum of the
[925]84          price per job for this printer plus the number of
85          pages multiplied by the price per page for this
86          printer.
87         
88        - User's account balance and lifetime paid money are now
89          stored in the Quota Storage, and account balance can be
90          used to limit the user printing instead of a print quota.
91          Actually you can limit either by account balance OR by
[1027]92          print quota. Account balance is shared between printers
93          for an user, while quotas are define separately for
94          each printer the user prints on.
[925]95         
[739]96All the command line tools accept the -h | --help command line option
97which prints all the available options and show usage examples.
98       
99Planned features are described in the TODO file.
100
[980]101Actually three (or an infinity of) page accounting methods are
102implemented :
[695]103
[980]104  - The 'querying' method consists in querying the printer (via SNMP
105    or Netatalk) for its total pages counter, just before the beginning
106    of a job, and use this to modify the *preceding* user's quota. So
107    you're always late of one print job, but this is generally ok,
108    especially because a check is also done to see if the current user
109    is allowed or not to print. You're not limited to SNMP or Netatalk,
110    because you can also use any external command instead if you want.
111   
112  - The 'external' method consists in delegating the computation of the
113    job's size in number of pages to any external command of your choice.
114    The command can read the job's data from its standard input and MUST
115    output the job's size on its standard output.
116   
117  - The 'stupid' method consists in counting the 'showpage' PostSript 
118    statements in the job. THIS IS UNRELIABLE, but can serve as an
119    example if you plan to write your own accounting method for
120    integration into PyKota.
[724]121 
[919]122PyKota is known to work fine with HP Laserjet 2100 and 2200, and
[980]123Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under
124Debian GNU/Linux (Sarge and Sid) operating systems.
[724]125
[980]126I'm interested in receiving success or failure reports with other
127brands or models of printers, as well as with other operating
128systems.
[859]129
[695]130============================================================
131
132INSTALLATION:
133=============
134
[887]135WARNING :
136=========
137
[942]138  If you run a PyKota version lower than 1.03, you definitely have to
[887]139  upgrade you Quota Storage Database. Please read the documentation
140  included in the initscripts subdirectory first !
141 
[1034]142  Users of MacOS-X may find the following tutorial useful :
143
144      http://ell-tech.com/pages/pykota.php
145
[714]146Prerequisite :
147--------------
148   
149  You need to have the following tools installed on the CUPS Server :
150 
[952]151    - CUPS or LPRng
[809]152    - Python v2.1 or above
[714]153    - eGenix' mxDateTime Python extension
[919]154    - SNMP tools (specifically the snmpget command) if you plan to
155      request your printer's lifetime page counter via SNMP.
156    - Netatalk (specifically the pap command) if you plan to
157      request your printer's lifetime page counter via AppleTalk.
[1043]158    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
159      libraries if you plan to use PostgreSQL as the Quota Storage
160      backend.
161 or     
162    - python-ldap Python module and the OpenLDAP client libraries 
163      if you plan to use OpenLDAP as the Quota Storage backend.
[714]164   
165  You need to have the following tools installed on the Quota Storage 
166  Server :
167 
168    - PostgreSQL
169   
[1043]170  or 
171 
172    - OpenLDAP
173   
174  PygreSQL and the PostgreSQL client libraries' versions on the Print
[714]175  Server must match the PostgreSQL version used on the Quota Storage
176  Server.
177 
[1043]178or 
179
180  python-ldap and the OpenLDAP client libraries' versions on the Print
181  Server must match the OpenLDAP version used on the Quota Storage
182  Server.
183 
[714]184  This list of prerequisite software may change in the future, when
185  PyKota will support more functionnalities you will be given
186  alternatives.
187 
[952]188  Of course the Print Server and the Quota Storage Server can be the
[851]189  very same machine if you've got a tiny network, or you can have
[952]190  multiple Print Servers all storing their quotas on the same Quota
[851]191  Storage Server if you've got a bigger network.
192 
[714]193Then :   
194------
195 
[724]196Download the latest PyKota version from the CVS tree on :
[695]197
[725]198    http://savannah.nongnu.org/projects/pykota
[695]199
[714]200Just type :
[695]201
[725]202    python setup.py install
[695]203
204You may need to be logged in with sufficient privileges (e.g. root)
205
[878]206The installation script will now automatically check if some software
207is missing and ask you if you still want to proceed with the
208installation or abort it completely.
209
[695]210Go to the initscripts subdirectory of PyKota's sources, and choose
211the appropriate storage backend for your configuration. Read
212the associated README file and execute the initialization script
[878]213to create an empty PyKota Storage. Upgrade scripts may be
214provided as well.
[695]215
216Copy the conf/pykota.conf.sample sample configuration file to
[1015]217/etc/pykota.conf. The installation script tries to do this for
[927]218you if needed and you agreed to this action.
[1015]219You need to adapt the /etc/pykota.conf file to your own needs.
220Especially you have to create sections named after your own
221printers, and change the administrator's email address.
[695]222
[952]223  - CUPS Print Backend :
224 
225    Modify the PPD files for each printer on which you want to manage
226    print quotas, for example /etc/cups/ppd/lp.ppd :
227   
228    --- Add the line below exactly as-is somewhere near the top ---
229    *cupsFilter:  "application/vnd.cups-postscript 0 /usr/bin/pykota"
230    --- Add the line above exactly as-is somewhere near the top  ---
231   
232    Modify the path to the pykota executable if needed, unfortunately
233    you have to supply the correct absolute path here due to CUPS
234    internals, or put the pykota executable into /usr/lib/cups/filter
235    instead of into /usr/bin.
236   
237    Do this for each ppd file present in this directory if you want
238    to enable quota on every printer.
239             
240    WARNING : In the case you've got a non-postscript printer, chances
241              are that the *cupsFilter is already filled-in and points
242              to cupsomatic or such a print filter. In this case please
243              check if you can switch your printer to PostScript mode
244              or if there's a way to make it accept PostScript jobs.
245              If yes then ensure that your workstations uses a PostScript
246              printer driver, and replace the *cupsFilter line with the
247              one pointing to the pykota filter. This should work, but
248              is currently untested.
249              If your printer really needs the original *cupsFilter line
250              then you may not be able to use PyKota easily for now.
[695]251
[952]252  - LPRng Print Backend :
253 
254    Modify the /etc/printcap file to add two lines identical to these ones :
255   
256    :achk=true
257    :as=|/usr/bin/pykota
258   
259    For each printer on which you want to use print accounting.
260 
[716]261Add printers and users to the quota system and set their quota values :
[695]262
[725]263    $ edpykota --add -P printer -S softlimit -H hardlimit user1 ... userN
[724]264       
[725]265    launching edpykota without any argument or with the --help
266    command line option will show you all the possibilities.
[695]267
[990]268Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
[695]269
[725]270    $ /etc/init.d/cupsys restart
[990]271   
272  or :
273 
274    $ /etc/init.d/lprng restart
[695]275       
276Your users now should be able to print but not exceed their
277printing quota.
278
[794]279To see printer command usage, you can use :
280
281    $ repykota --printer lp
282   
283or :
284
285    $ repykota
286   
287    which will print quota usage for all users on all printers,
288    along with totals.
289   
[990]290Quota reports are also available remotely by using the CGI scripts
291provided in the cgi-bin/ subdirectory.
292
[980]293For different security concerns, please give a look at the SECURITY
294file which is part of this software.
[741]295           
[695]296============================================================
297
[958]298Mailing list :
299--------------
300
301  A mailing list is dedicated to Pykota, you can subscribe to it
302  or consult its archives at :
303 
304    http://cgi.librelogiciel.com/mailman/listinfo/pykota
305   
306============================================================
307   
[695]308Please e-mail bugs to: alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.