root / pykota / trunk / README @ 1407

Revision 1402, 16.9 kB (checked in by jalet, 21 years ago)

Documentation

  • 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-2004 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 features :
27-----------------
28
29    Operating systems :
30   
31        - Any Unix-like system as print server.
32           
33        - Any operating system as client.
34           
35    Printing systems :
36   
37        - Supports both CUPS and LPRng as the printing system.
38           
39    Databases :
40   
41        - Supports PostgreSQL as the Quota Storage backend.
42          Complete database creation script in SQL is included.
43       
44        - Supports OpenLDAP as the Quota Storage backend.
45          Complete LDAP schema and sample tree are included.
46          Plugging PyKota into your existing LDAP infrastructure
47          is really easy thanks to PyKota's great configurability.
48           
49    Printers :       
50   
51        - Supports any printer which can report its internal
52          page counter.
53         
54        - Supports any other printer via GhostScript.
55          Depending on the printer some configuration may
56          be needed.
57       
58        - Can ask printers for their internal page counter
59          via SNMP, Netatalk, or any other mean of your
60          choice. This is completely configurable.
61         
62        - External accounting methods are configurable.
63           
64    Quota systems :       
65   
66        - Supports printers and printers groups quotas.
67       
68        - Supports users and users groups quotas.
69       
70        - Supports page quotas.
71          Page quotas can be set differently on a per printer
72          and per user/group basis.
73       
74        - Supports account balance quotas in any currency.
75          Account balance quotas can be set on a per user
76          basis. The account balance is shared amongst
77          all printers.
78         
79        - Page quota and account balance can be set/reset
80          independantly.
81         
82        - Limiting factor, page quota or account balance, 
83          can be set on a per user or per group basis.
84         
85        - Price per page and per job can be set differently 
86          on any printer.
87       
88        - Low level of page quota or account balance are
89          configurable.
90         
91        - Both soft and hard limit with configurable grace delay 
92          can be set for page quota.
93         
94        - Possibility to disable quota enforcement for any user
95          or group, while still keeping page accounting.
96             
97    Administration :       
98   
99        - Powerful administration tools can be used to
100          automate setting or resetting of quotas or
101          account balances at specific intervals.
102         
103        - Administration tools can modify several users, 
104          groups, or printers at once.
105         
106        - Account balances can be set, incremented, or 
107          decremented.
108         
109        - Both printers and users can be automatically added on
110          first print in a completely configurable way.
111         
112        - Quota report generator available either from the 
113          command line or in any web browser.
114          The web-based quota report generator can be
115          user/password protected.
116         
117        - Print quote generator can tell users how much 
118          a print job will cost them in advance.
119         
120        - Policy with regard to unregistered users can   
121          be configured for each printer to either deny
122          printing, allow printing, or delegate the
123          decision to any external tool.
124         
125        - Warning and error messages can be automatically 
126          sent via email to the administrator, the user,
127          both, or none.
128         
129        - Warning and error messages' content is completely
130          configurable.
131         
132        - Configuration can be changed without needing to 
133          restart the printing system.
134       
135        - Complete print job history is kept. This can be
136          disabled if needed.
137         
138        - Automated low quota or balance remainder can be
139          scheduled regularly or launched manually.
140         
141    User Interface :         
142   
143        - All the command line tools accept the -h | --help
144          command line option which prints all the available
145          options and show usage examples.
146         
147        - Completely internationalized. Actually supports the 
148          English, French, Spanish, Portuguese, Brasilian, Swedish
149          and Italian languages. More to come.
150
151====================================================================
152       
153Planned features are described in the TODO file.
154
155Actually three (or an infinity of) page accounting methods are
156implemented :
157
158  - The 'querying' method consists in querying the printer (via SNMP
159    or Netatalk or any other method of your choice) for its total pages
160    counter.
161   
162    With CUPS, this is done both at the beginning and at the end of a
163    print job. The counters difference is then immediately used to
164    decrease the user's account balance or increase his quota usage.
165   
166    With LPRng, this is done just before the beginning of a job, and used
167    this to modify the *preceding* user's quota. So you're always late
168    of one print job, but this is generally ok.
169   
170  - The 'external' method consists in delegating the computation of the
171    job's size in number of pages to any external command of your choice.
172    The command can read the job's data from its standard input and MUST
173    output the job's size on its standard output. Changes to the user
174    account are reported immediately, both with CUPS and LPRng.
175   
176  - The 'stupid' method consists in counting the 'showpage' PostSript 
177    statements in the job. THIS IS UNRELIABLE, SO DON'T USE IT, but
178    can serve as an example if you plan to write your own accounting
179    method for integration into PyKota. It basically works like the
180    'external' method, but does the computation internally and in
181    a non-reliable way.
182 
183PyKota is known to work fine with HP Laserjet 2100 and 2200, and
184Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under
185Debian GNU/Linux (Sarge and Sid) operating systems. It should work
186fine with most network printers.
187
188============================================================
189
190INSTALLATION:
191=============
192
193NB :
194====
195
196  You may learn more about PyKota, if it fits your own organization,
197  its internal working, and some potential performance drawbacks and
198  how to avoid them, in a WiKi administered by Ryan Suarez at :
199 
200    http://webcrossing.macosxlabs.org/webx?14@30.QAu3a5k0c4z.7@.26bf4661
201
202Prerequisite :
203--------------
204   
205  You need to have the following tools installed on the CUPS Server :
206 
207    - CUPS or LPRng
208    - Python v2.1 or above
209    - eGenix' mxDateTime Python extension
210    - SNMP tools (specifically the snmpget command) if you plan to
211      request your printer's lifetime page counter via SNMP.
212    - Netatalk (specifically the pap command) if you plan to
213      request your printer's lifetime page counter via AppleTalk.
214    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
215      libraries if you plan to use PostgreSQL as the Quota Storage
216      backend.
217 or     
218    - python-ldap Python module and the OpenLDAP client libraries 
219      if you plan to use OpenLDAP as the Quota Storage backend.
220   
221  You may also benefit from having the following tools installed to
222  deal with some printers :
223 
224    - npadmin
225    - netcat
226    - ghostscript
227   
228  You need to have the following tools installed on the Quota Storage 
229  Server :
230 
231    - PostgreSQL
232   
233  or 
234 
235    - OpenLDAP
236   
237NB :   
238
239  PygreSQL must be linked with the PostgreSQL client libraries on
240  the Print Server. The PostgreSQL client libraries' version must
241  match the PostgreSQL version used on the Quota Storage Server.
242  BEWARE : under Debian Sarge, as of March 15th 2004, there's a
243  problem with python2.2-pygresql and python-2.3-pygresql, so please
244  install python2.1-pygresql and use Python 2.1 to install and run
245  PyKota. This is not a bug in PyKota, and this should be fixed
246  by Debian in a few days I hope.
247 
248or 
249
250  python-ldap must be linked with the OpenLDAP client libraries on the
251  Print Server. The OpenLDAP client libraries' version must match the
252  OpenLDAP version used on the Quota Storage Server.
253 
254  This list of prerequisite software may change in the future, when
255  PyKota will support more functionnalities you will be given
256  alternatives.
257 
258  Of course the Print Server and the Quota Storage Server can be the
259  very same machine if you've got a tiny network, or you can have
260  multiple Print Servers all storing their quotas on the same Quota
261  Storage Server if you've got a bigger network.
262 
263Then :   
264------
265 
266Download the latest PyKota version from the CVS tree on :
267
268    http://savannah.nongnu.org/projects/pykota
269
270Just type :
271
272    python setup.py install
273
274You may need to be logged in with sufficient privileges (e.g. root)
275
276The installation script will now automatically check if some software
277is missing and ask you if you still want to proceed with the
278installation or abort it completely.
279
280Go to the initscripts subdirectory of PyKota's sources, and choose
281the appropriate storage backend for your configuration. Read
282the associated README file and execute the initialization script
283to create an empty PyKota Storage. Upgrade scripts may be
284provided as well.
285
286Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
287sample configuration files to /etc/pykota/pykota.conf and
288/etc/pykota/pykotadmin.conf. The installation script tries to do
289this for you if needed and you agreed to this action. You need to
290adapt these files to your own needs. Especially you have to create
291sections named after your own printers, and change the
292administrator's email address which by default is root@localhost.
293Read and try to understand these two very well commented files,
294so that you'll encounter less problems later.
295
296Also be sure to double check that commands that query printers
297for their internal page counter work from the command line
298before using them in PyKota's configuration.
299
300The rest of the installation depends on your printing system :
301
302  - CUPS Printing System :
303 
304    Once and for all :
305   
306        Create a symbolic link to the cupspykota backend
307        in CUPS's backend directory :
308       
309          $ cd /usr/lib/cups/backend
310          $ ln -s /usr/share/pykota/cupspykota cupspykota
311         
312        Restart CUPS so that the new backend can be detected.
313       
314          $ /etc/init.d/cupsys restart
315         
316    For dumb printers :
317   
318        The FAQ contains both the PyKota's definition of a 'dumb'
319        printer, and how to deal with them.
320   
321    For new printers :
322   
323        Go to CUPS management interface (http://localhost:631)
324        and choose the appropriate PyKota managed device depending
325        on the type of printer you use. For example, if your
326        printer is waiting on :
327       
328            socket://myprinter.example.com:9100
329           
330        Then choose :   
331       
332            cupspykota:socket://myprinter.example.com:9100
333           
334        Configure your printer as usual.   
335       
336        Now double check /etc/pykota/pykota.conf
337        This file should contain a section named after the
338        printer you've just added, unless you have set
339        all options globally.
340       
341        That's all.
342   
343    For existing printers :
344   
345        If you had already installed a version of PyKota earlier
346        than 1.16alpha7, then remove the *cupsFilter lines in your
347        PPD files for each printer already managed printers. Each
348        line to remove is of the form :
349       
350          *cupsFilter: "application/vnd.cups-postscript 0 /usr/share/pykota/pykota"
351       
352        This means that each time the pstops filter will be executed, it will
353        pass the job's data through the pykota filter which is present in
354        /usr/share/pykota
355       
356        Don't touch anything else, especially any other *cupsFilter line.
357        Then save each of these files.
358       
359        Then, the easiest is to directly modify the DeviceURI lines
360        in /etc/cups/printers.conf, you just have to put
361        'cupspykota:' in front of what is already on these lines.
362        For example, replace :
363   
364            DeviceURI socket://myprinter.example.com:9100
365       
366        with :   
367   
368            DeviceURI cupspykota:socket://myprinter.example.com:9100
369           
370        or :   
371       
372            DeviceURI cupspykota://socket://myprinter.example.com:9100
373       
374        Save the file and restart CUPS.
375
376  - LPRng Printing System :
377 
378    Modify the /etc/printcap file to add two lines identical to these ones :
379   
380    :achk=true
381    :as=|/usr/share/pykota/pykota
382   
383    For each printer on which you want to use print accounting.
384   
385    And then save the file and restart LPRng :
386   
387        $ /etc/init.d/lprng restart
388       
389Now you can begin to populate the PyKota's database with printers,
390users and groups :
391 
392Add printers and users to the quota system and set their quota values :
393
394Starting from version 1.18alpha2, the preferred command to manage
395printers is named pkprinters
396
397    $ pkprinters --help
398   
399    will tell you how to create, manage or delete printers and
400    printers groups.
401   
402    $ pkprinters --add --charge 0.05 hp2100
403   
404    would add the printer named hp2100 with a price per page
405    of 0.05 unit.
406
407Now set quotas for users on this printer :     
408
409    $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN
410       
411    launching edpykota without any argument or with the --help
412    command line option will show you all the possibilities.
413   
414    by default, each user is limited by "quota", this means that on
415    each printer he can have a different soft and hard limit.
416    You may want to limit the user by his account balance value,
417    in which case, the print quota is shared between all printers
418    instead of being different. To do this, use the following :
419   
420    $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN
421   
422    This will put 10 $ (or Euros, PyKota doesn't care) on each user's account
423    balance, and tell PyKota to limit them by their account balance value.
424    Whenever they print on any printer, their account balance value is
425    decreased by an amount which depends on the particular price per page
426    and per job that you may have defined on the printer with edpykota's
427    --charge command line option.
428    Soft and Hard limits are not used if "--limitby balance" is used,
429    but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf
430    to obtain a similar result (warning message when quota is low).
431
432Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
433
434    $ /etc/init.d/cupsys restart
435   
436  or :
437 
438    $ /etc/init.d/lprng restart
439       
440Your users now should be able to print but not exceed their
441printing quota.
442
443To see printer quota usage, you can use :
444
445    $ repykota --printer lp
446   
447or :
448
449    $ repykota
450   
451    which will print quota usage for all users on all printers,
452    along with totals, if you are the root user. If you are
453    a regular user, only your own quota report will be produced.
454   
455Quota reports are also available remotely by using the CGI script
456printquota.cgi provided in the cgi-bin/ subdirectory. You can
457also use the CSS stylesheet present in the stylesheets/ subdirectory
458and put it at your web server's DocumentRoot, to benefit from a nicer
459look, especially quota violations will appear in different colors.
460
461For different security concerns, please give a look at the SECURITY
462file which is part of this software.
463           
464============================================================
465
466Mailing list :
467--------------
468
469  A mailing list is dedicated to Pykota, you can subscribe to it
470  or consult its archives at :
471 
472    http://cgi.librelogiciel.com/mailman/listinfo/pykota
473   
474IRC :   
475-----
476
477  You can also chat with us :
478 
479        /server irc.freenode.net
480        /join #pykota
481   
482============================================================
483   
484Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
485or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.