root / pykota / trunk / README @ 1107

Revision 1107, 12.8 kB (checked in by jalet, 21 years ago)

More complete README file

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1# $Id$
2
3PyKota - Print Quota for CUPS and LPRng
4
5(c) 2003 Jerome Alet <alet@librelogiciel.com>
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.
10
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.
15
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
20====================================================================
21
22READ SPECIAL LICENSING AND REDISTRIBUTION TERMS IN THE FILE 'LICENSE'
23
24====================================================================
25
26PyKota is a complete Print Quota system for the Common Unix Printing
27System (aka CUPS) or LPR Next Generation (LPRng), which works by directly
28querying the printers for the number of pages they have printed.
29
30Actual working features :
31
32        - Supports both CUPS and LPRng backends.
33       
34        - Can store quota information either with PostgreSQL or with
35          OpenLDAP.
36       
37        - Per printer user and group quotas.
38       
39        - Automated email warning of users above quota to the
40          user himself and to the print quota administrator.
41       
42        - Filter for quota accounting : pykota
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       
50        - Command line print quote maker, to learn how much a print job
51          will cost in advance : pykotme
52       
53        - Command line tools mimic the disk quota utilities for
54          easier mastering.
55       
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                   
60        - SNMP querying of any networked SNMP-enabled printer.
61       
62        - Netatalk querying of any networked AppleTalk-enabled printer.
63       
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
67          reading the result. See the example scripts in the
68          "untested" directory and try to adapt them to your
69          configuration.
70         
71        - External accounting methods : you can use your own accounting
72          method to compute each job's size. Just create a shell script
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 !
75       
76        - Special scripts included for a seamless integration of
77          PyKota on Debian machines.
78         
79        - Complete job history is saved. This will allow more
80          complex reports in the future.
81         
82        - Price per page and price per job can be defined for 
83          every printer. A job's price is the sum of the
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
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.
95         
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
101Actually three (or an infinity of) page accounting methods are
102implemented :
103
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.
121 
122PyKota is known to work fine with HP Laserjet 2100 and 2200, and
123Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under
124Debian GNU/Linux (Sarge and Sid) operating systems.
125
126I'm interested in receiving success or failure reports with other
127brands or models of printers, as well as with other operating
128systems.
129
130============================================================
131
132INSTALLATION:
133=============
134
135WARNING :
136=========
137
138  If you run a PyKota version lower than 1.03, you definitely have to
139  upgrade you Quota Storage Database. Please read the documentation
140  included in the initscripts subdirectory first !
141 
142  Users of MacOS-X may find the following tutorial useful :
143
144      http://ell-tech.com/pages/pykota.php
145
146Prerequisite :
147--------------
148   
149  You need to have the following tools installed on the CUPS Server :
150 
151    - CUPS or LPRng
152    - Python v2.1 or above
153    - eGenix' mxDateTime Python extension
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.
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.
164   
165  You need to have the following tools installed on the Quota Storage 
166  Server :
167 
168    - PostgreSQL
169   
170  or 
171 
172    - OpenLDAP
173   
174NB :   
175
176  PygreSQL must be linked with the PostgreSQL client libraries on
177  the Print Server. The PostgreSQL client libraries' version must
178  match the PostgreSQL version used on the Quota Storage Server.
179 
180or 
181
182  python-ldap must be linked with the OpenLDAP client libraries on the
183  Print Server. The OpenLDAP client libraries' version must match the
184  OpenLDAP version used on the Quota Storage Server.
185 
186  This list of prerequisite software may change in the future, when
187  PyKota will support more functionnalities you will be given
188  alternatives.
189 
190  Of course the Print Server and the Quota Storage Server can be the
191  very same machine if you've got a tiny network, or you can have
192  multiple Print Servers all storing their quotas on the same Quota
193  Storage Server if you've got a bigger network.
194 
195Then :   
196------
197 
198Download the latest PyKota version from the CVS tree on :
199
200    http://savannah.nongnu.org/projects/pykota
201
202Just type :
203
204    python setup.py install
205
206You may need to be logged in with sufficient privileges (e.g. root)
207
208The installation script will now automatically check if some software
209is missing and ask you if you still want to proceed with the
210installation or abort it completely.
211
212Go to the initscripts subdirectory of PyKota's sources, and choose
213the appropriate storage backend for your configuration. Read
214the associated README file and execute the initialization script
215to create an empty PyKota Storage. Upgrade scripts may be
216provided as well.
217
218Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
219sample configuration files to /etc/pykota/pykota.conf and
220/etc/pykota/pykotadmin.conf. The installation script tries to do this
221for you if needed and you agreed to this action.
222You need to adapt these files to your own needs.
223Especially you have to create sections named after your own
224printers, and change the administrator's email address.
225
226  - CUPS Print Backend :
227 
228    Modify the PPD files for each printer on which you want to manage
229    print quotas, for example /etc/cups/ppd/lp.ppd :
230   
231    --- Add the line below exactly as-is somewhere near the top ---
232    *cupsFilter:  "application/vnd.cups-postscript 0 /usr/bin/pykota"
233    --- Add the line above exactly as-is somewhere near the top  ---
234   
235    Modify the path to the pykota executable if needed, unfortunately
236    you have to supply the correct absolute path here due to CUPS
237    internals, or put the pykota executable into /usr/lib/cups/filter
238    instead of into /usr/bin.
239   
240    Do this for each ppd file present in this directory if you want
241    to enable quota on every printer.
242             
243    WARNING : In the case you've got a non-postscript printer, chances
244              are that the *cupsFilter is already filled-in and points
245              to cupsomatic or such a print filter. In this case please
246              check if you can switch your printer to PostScript mode
247              or if there's a way to make it accept PostScript jobs.
248              If yes then ensure that your workstations uses a PostScript
249              printer driver, and replace the *cupsFilter line with the
250              one pointing to the pykota filter. This should work, but
251              is currently untested.
252              If your printer really needs the original *cupsFilter line
253              then you may not be able to use PyKota easily for now.
254
255  - LPRng Print Backend :
256 
257    Modify the /etc/printcap file to add two lines identical to these ones :
258   
259    :achk=true
260    :as=|/usr/bin/pykota
261   
262    For each printer on which you want to use print accounting.
263 
264Add printers and users to the quota system and set their quota values :
265
266    $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN
267       
268    launching edpykota without any argument or with the --help
269    command line option will show you all the possibilities.
270   
271    by default, each user is limited by "quota", this means that on
272    each printer he can have a different soft and hard limit.
273    You may want to limit the user by his account balance value,
274    in which case, the print quota is shared between all printers
275    instead of being different. To do this, use the following :
276   
277    $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN
278   
279    This will put 10 $ (or Euros, PyKota doesn't care) on each user's account
280    balance, and tell PyKota to limit them by their account balance value.
281    Whenever they print on any printer, their account balance value is
282    decreased by an amount which depends on the particular price per page
283    and per job that you may have defined on the printer with edpykota's
284    --charge command line option.
285    Soft and Hard limits are not used if "--limitby balance" is used,
286    but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf
287    to obtain a similar result (warning message when quota is low).
288
289Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
290
291    $ /etc/init.d/cupsys restart
292   
293  or :
294 
295    $ /etc/init.d/lprng restart
296       
297Your users now should be able to print but not exceed their
298printing quota.
299
300To see printer command usage, you can use :
301
302    $ repykota --printer lp
303   
304or :
305
306    $ repykota
307   
308    which will print quota usage for all users on all printers,
309    along with totals, if you are the root user. If you are
310    a regular user, only your own quota report will be produced.
311   
312Quota reports are also available remotely by using the CGI script
313printquota.cgi provided in the cgi-bin/ subdirectory.
314
315For different security concerns, please give a look at the SECURITY
316file which is part of this software.
317           
318============================================================
319
320Mailing list :
321--------------
322
323  A mailing list is dedicated to Pykota, you can subscribe to it
324  or consult its archives at :
325 
326    http://cgi.librelogiciel.com/mailman/listinfo/pykota
327   
328============================================================
329   
330Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
331or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.