root / pykota / trunk / README @ 1152

Revision 1149, 12.9 kB (checked in by jalet, 21 years ago)

Job history can be disabled.
Some typos in README.
More messages in setup script.

  • 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. This can be disabled
81          if preserving the history is of no interest or
82          makes the database grow out of control.
83         
84        - Price per page and price per job can be defined for 
85          every printer. A job's price is the sum of the
86          price per job for this printer plus the number of
87          pages multiplied by the price per page for this
88          printer.
89         
90        - User's account balance and lifetime paid money are now
91          stored in the Quota Storage, and account balance can be
92          used to limit the user printing instead of a print quota.
93          Actually you can limit either by account balance OR by
94          print quota. Account balance is shared between printers
95          for an user, while quotas are define separately for
96          each printer the user prints on.
97         
98All the command line tools accept the -h | --help command line option
99which prints all the available options and show usage examples.
100       
101Planned features are described in the TODO file.
102
103Actually three (or an infinity of) page accounting methods are
104implemented :
105
106  - The 'querying' method consists in querying the printer (via SNMP
107    or Netatalk) for its total pages counter, just before the beginning
108    of a job, and use this to modify the *preceding* user's quota. So
109    you're always late of one print job, but this is generally ok,
110    especially because a check is also done to see if the current user
111    is allowed or not to print. You're not limited to SNMP or Netatalk,
112    because you can also use any external command instead if you want.
113   
114  - The 'external' method consists in delegating the computation of the
115    job's size in number of pages to any external command of your choice.
116    The command can read the job's data from its standard input and MUST
117    output the job's size on its standard output.
118   
119  - The 'stupid' method consists in counting the 'showpage' PostSript 
120    statements in the job. THIS IS UNRELIABLE, but can serve as an
121    example if you plan to write your own accounting method for
122    integration into PyKota.
123 
124PyKota is known to work fine with HP Laserjet 2100 and 2200, and
125Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under
126Debian GNU/Linux (Sarge and Sid) operating systems.
127
128I'm interested in receiving success or failure reports with other
129brands or models of printers, as well as with other operating
130systems.
131
132============================================================
133
134INSTALLATION:
135=============
136
137WARNING :
138=========
139
140  If you run a PyKota version lower than 1.03, you definitely have to
141  upgrade you Quota Storage Database. Please read the documentation
142  included in the initscripts subdirectory first !
143 
144  Users of MacOS-X may find the following tutorial useful :
145
146      http://ell-tech.com/pages/pykota.php
147
148Prerequisite :
149--------------
150   
151  You need to have the following tools installed on the CUPS Server :
152 
153    - CUPS or LPRng
154    - Python v2.1 or above
155    - eGenix' mxDateTime Python extension
156    - SNMP tools (specifically the snmpget command) if you plan to
157      request your printer's lifetime page counter via SNMP.
158    - Netatalk (specifically the pap command) if you plan to
159      request your printer's lifetime page counter via AppleTalk.
160    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
161      libraries if you plan to use PostgreSQL as the Quota Storage
162      backend.
163 or     
164    - python-ldap Python module and the OpenLDAP client libraries 
165      if you plan to use OpenLDAP as the Quota Storage backend.
166   
167  You need to have the following tools installed on the Quota Storage 
168  Server :
169 
170    - PostgreSQL
171   
172  or 
173 
174    - OpenLDAP
175   
176NB :   
177
178  PygreSQL must be linked with the PostgreSQL client libraries on
179  the Print Server. The PostgreSQL client libraries' version must
180  match the PostgreSQL version used on the Quota Storage Server.
181 
182or 
183
184  python-ldap must be linked with the OpenLDAP client libraries on the
185  Print Server. The OpenLDAP client libraries' version must match the
186  OpenLDAP version used on the Quota Storage Server.
187 
188  This list of prerequisite software may change in the future, when
189  PyKota will support more functionnalities you will be given
190  alternatives.
191 
192  Of course the Print Server and the Quota Storage Server can be the
193  very same machine if you've got a tiny network, or you can have
194  multiple Print Servers all storing their quotas on the same Quota
195  Storage Server if you've got a bigger network.
196 
197Then :   
198------
199 
200Download the latest PyKota version from the CVS tree on :
201
202    http://savannah.nongnu.org/projects/pykota
203
204Just type :
205
206    python setup.py install
207
208You may need to be logged in with sufficient privileges (e.g. root)
209
210The installation script will now automatically check if some software
211is missing and ask you if you still want to proceed with the
212installation or abort it completely.
213
214Go to the initscripts subdirectory of PyKota's sources, and choose
215the appropriate storage backend for your configuration. Read
216the associated README file and execute the initialization script
217to create an empty PyKota Storage. Upgrade scripts may be
218provided as well.
219
220Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
221sample configuration files to /etc/pykota/pykota.conf and
222/etc/pykota/pykotadmin.conf. The installation script tries to do this
223for you if needed and you agreed to this action.
224You need to adapt these files to your own needs.
225Especially you have to create sections named after your own
226printers, and change the administrator's email address.
227
228  - CUPS Print Backend :
229 
230    Modify the PPD files for each printer on which you want to manage
231    print quotas, for example /etc/cups/ppd/lp.ppd :
232   
233    --- Add the line below exactly as-is somewhere near the top ---
234    *cupsFilter:  "application/vnd.cups-postscript 0 /usr/bin/pykota"
235    --- Add the line above exactly as-is somewhere near the top  ---
236   
237    Modify the path to the pykota executable if needed, unfortunately
238    you have to supply the correct absolute path here due to CUPS
239    internals, or put the pykota executable into /usr/lib/cups/filter
240    instead of into /usr/bin.
241   
242    Do this for each ppd file present in this directory if you want
243    to enable quota on every printer.
244             
245    WARNING : In the case you've got a non-postscript printer, chances
246              are that the *cupsFilter is already filled-in and points
247              to cupsomatic or such a print filter. In this case please
248              check if you can switch your printer to PostScript mode
249              or if there's a way to make it accept PostScript jobs.
250              If yes then ensure that your workstations uses a PostScript
251              printer driver, and replace the *cupsFilter line with the
252              one pointing to the pykota filter. This should work, but
253              is currently untested.
254              If your printer really needs the original *cupsFilter line
255              then you may not be able to use PyKota easily for now.
256
257  - LPRng Print Backend :
258 
259    Modify the /etc/printcap file to add two lines identical to these ones :
260   
261    :achk=true
262    :as=|/usr/bin/pykota
263   
264    For each printer on which you want to use print accounting.
265 
266Add printers and users to the quota system and set their quota values :
267
268    $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN
269       
270    launching edpykota without any argument or with the --help
271    command line option will show you all the possibilities.
272   
273    by default, each user is limited by "quota", this means that on
274    each printer he can have a different soft and hard limit.
275    You may want to limit the user by his account balance value,
276    in which case, the print quota is shared between all printers
277    instead of being different. To do this, use the following :
278   
279    $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN
280   
281    This will put 10 $ (or Euros, PyKota doesn't care) on each user's account
282    balance, and tell PyKota to limit them by their account balance value.
283    Whenever they print on any printer, their account balance value is
284    decreased by an amount which depends on the particular price per page
285    and per job that you may have defined on the printer with edpykota's
286    --charge command line option.
287    Soft and Hard limits are not used if "--limitby balance" is used,
288    but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf
289    to obtain a similar result (warning message when quota is low).
290
291Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
292
293    $ /etc/init.d/cupsys restart
294   
295  or :
296 
297    $ /etc/init.d/lprng restart
298       
299Your users now should be able to print but not exceed their
300printing quota.
301
302To see printer quota usage, you can use :
303
304    $ repykota --printer lp
305   
306or :
307
308    $ repykota
309   
310    which will print quota usage for all users on all printers,
311    along with totals, if you are the root user. If you are
312    a regular user, only your own quota report will be produced.
313   
314Quota reports are also available remotely by using the CGI script
315printquota.cgi provided in the cgi-bin/ subdirectory.
316
317For different security concerns, please give a look at the SECURITY
318file which is part of this software.
319           
320============================================================
321
322Mailing list :
323--------------
324
325  A mailing list is dedicated to Pykota, you can subscribe to it
326  or consult its archives at :
327 
328    http://cgi.librelogiciel.com/mailman/listinfo/pykota
329   
330============================================================
331   
332Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
333or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.