root / pykota / trunk / README @ 1233

Revision 1206, 15.7 kB (checked in by jalet, 21 years ago)

Link to the FAQ

  • 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 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 CUPS as the printing system.
38       
39        - Supports LPRng as the printing system.
40           
41    Databases :
42   
43        - Supports PostgreSQL as the Quota Storage backend.
44          Complete database creation SQL script is included.
45       
46        - Supports OpenLDAP as the Quota Storage backend.
47          Complete LDAP schema and sample tree are included.
48          Plugging PyKota into your existing LDAP infrastructure
49          is really easy thanks to PyKota's great configurability.
50           
51    Printers :       
52   
53        - Supports any printer which can report its internal
54          page counter.
55         
56        - Supports any other printer via GhostScript.
57          Depending on the printer some configuration may
58          be needed.
59       
60        - Can ask printers for their internal page counter
61          via SNMP, Netatalk, or any other mean of your
62          choice. This is completely configurable.
63         
64        - External accounting methods are configurable.
65           
66    Quota systems :       
67   
68        - Supports user and 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        - Experimental support for printer groups, so that
80          you can share quota between printers of the same
81          type but in different locations.
82         
83        - Page quota and account balance can be set/reset
84          independantly.
85         
86        - Limiting factor, page quota or account balance, 
87          can be set on a per user or per group basis.
88         
89        - Price per page and per job can be set differently 
90          on any printer.
91       
92        - Low level of page quota or account balance are
93          configurable.
94         
95        - Both soft and hard limit with configurable grace delay 
96          can be set for page quota.
97         
98        - Possibility to disable quota enforcement for any user
99          or group, while still keeping page accounting.
100             
101    Administration :       
102   
103        - Powerful administration tools can be used to
104          automate setting or resetting of quotas or
105          account balances at specific intervals.
106         
107        - Administration tools can modify several users, 
108          groups, or printers at once.
109         
110        - Account balances can be set, incremented, or 
111          decremented.
112         
113        - Users can be automatically added on first print 
114          in a completely configurable way.
115         
116        - Quota report generator available either from the 
117          command line or in any web browser.
118          The web-based quota report generator can be
119          user/password protected.
120         
121        - Print quote generator can tell users how much 
122          a print job will cost them in advance.
123         
124        - Policy with regard to unregistered users can   
125          be configured for each printer to either deny
126          printing, allow printing, or delegate the
127          decision to any external tool.
128         
129        - Warning and error messages can be automatically 
130          sent via email to the administrator, the user,
131          both, or none.
132         
133        - Warning and error messages' content is completely
134          configurable.
135         
136        - Configuration can be changed without needing to 
137          restart the printing system.
138       
139        - Complete print job history is kept. This can be
140          disabled if needed.
141         
142        - Automated low quota or balance remainder can be
143          scheduled regularly or launched manually.
144         
145    User Interface :         
146   
147        - All the command line tools accept the -h | --help
148          command line option which prints all the available
149          options and show usage examples.
150         
151        - Completely internationalized. Actually supports the 
152          English and French languages. More to come.
153
154====================================================================
155       
156Planned features are described in the TODO file.
157
158Actually three (or an infinity of) page accounting methods are
159implemented :
160
161  - The 'querying' method consists in querying the printer (via SNMP
162    or Netatalk or any other method of your choice) for its total pages
163    counter.
164   
165    With CUPS, this is done both at the beginning and at the end of a
166    print job. The counters difference is then immediately used to
167    decrease the user's account balance or increase his quota usage.
168   
169    With LPRng, this is done just before the beginning of a job, and used
170    this to modify the *preceding* user's quota. So you're always late
171    of one print job, but this is generally ok, especially because a
172    check is also done to see if the current user is allowed or not to
173    print.
174   
175  - The 'external' method consists in delegating the computation of the
176    job's size in number of pages to any external command of your choice.
177    The command can read the job's data from its standard input and MUST
178    output the job's size on its standard output. Changes to the user
179    account are reported immediately, both with CUPS and LPRng.
180   
181  - The 'stupid' method consists in counting the 'showpage' PostSript 
182    statements in the job. THIS IS UNRELIABLE, but can serve as an
183    example if you plan to write your own accounting method for
184    integration into PyKota. It basically works like the 'external'
185    method, but does the computation internally.
186 
187PyKota is known to work fine with HP Laserjet 2100 and 2200, and
188Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under
189Debian GNU/Linux (Sarge and Sid) operating systems.
190
191I'm interested in receiving success or failure reports with other
192brands or models of printers, as well as with other operating
193systems.
194
195============================================================
196
197INSTALLATION:
198=============
199
200NB :
201====
202
203  Users of MacOS-X may find the following tutorial useful :
204
205      http://ell-tech.com/pages/pykota.php
206
207Prerequisite :
208--------------
209   
210  You need to have the following tools installed on the CUPS Server :
211 
212    - CUPS or LPRng
213    - Python v2.1 or above
214    - eGenix' mxDateTime Python extension
215    - SNMP tools (specifically the snmpget command) if you plan to
216      request your printer's lifetime page counter via SNMP.
217    - Netatalk (specifically the pap command) if you plan to
218      request your printer's lifetime page counter via AppleTalk.
219    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
220      libraries if you plan to use PostgreSQL as the Quota Storage
221      backend.
222 or     
223    - python-ldap Python module and the OpenLDAP client libraries 
224      if you plan to use OpenLDAP as the Quota Storage backend.
225   
226  You may also benefit from having the following tools installed to
227  deal with some printers :
228 
229    - npadmin
230    - netcat
231    - ghostscript
232   
233  You need to have the following tools installed on the Quota Storage 
234  Server :
235 
236    - PostgreSQL
237   
238  or 
239 
240    - OpenLDAP
241   
242NB :   
243
244  PygreSQL must be linked with the PostgreSQL client libraries on
245  the Print Server. The PostgreSQL client libraries' version must
246  match the PostgreSQL version used on the Quota Storage Server.
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/bin/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.domain.com:9100
329           
330        Then choose :   
331       
332            cupspykota:socket://myprinter.domain.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.
339       
340        That's all.
341   
342    For existing printers :
343   
344        If you had already installed a version of PyKota earlier
345        than 1.16alpha7, then remove the *cupsFilter lines in your
346        PPD files for each printer already managed printers. Each
347        line to remove is of the form :
348       
349          *cupsFilter: "application/vnd.cups-postscript 0 /usr/bin/pykota"
350       
351        Don't touch anything else, especially any other *cupsFilter line.
352        Then save each of these files.
353       
354        Then, the easiest is to directly modify the DeviceURI lines
355        in /etc/cups/printers.conf, you just have to put
356        'cupspykota:' in front of what is already on these lines.
357        For example, replace :
358   
359            DeviceURI socket://myprinter.domain.com:9100
360       
361        with :   
362   
363            DeviceURI cupspykota:socket://myprinter.domain.com:9100
364       
365        Save the file and restart CUPS.
366
367  - LPRng Printing System :
368 
369    Modify the /etc/printcap file to add two lines identical to these ones :
370   
371    :achk=true
372    :as=|/usr/bin/pykota
373   
374    For each printer on which you want to use print accounting.
375   
376    And then save the file and restart LPRng :
377   
378        $ /etc/init.d/lprng restart
379       
380Now you can begin to populate the PyKota's database with printers,
381users and groups :
382 
383Add printers and users to the quota system and set their quota values :
384
385    $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN
386       
387    launching edpykota without any argument or with the --help
388    command line option will show you all the possibilities.
389   
390    by default, each user is limited by "quota", this means that on
391    each printer he can have a different soft and hard limit.
392    You may want to limit the user by his account balance value,
393    in which case, the print quota is shared between all printers
394    instead of being different. To do this, use the following :
395   
396    $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN
397   
398    This will put 10 $ (or Euros, PyKota doesn't care) on each user's account
399    balance, and tell PyKota to limit them by their account balance value.
400    Whenever they print on any printer, their account balance value is
401    decreased by an amount which depends on the particular price per page
402    and per job that you may have defined on the printer with edpykota's
403    --charge command line option.
404    Soft and Hard limits are not used if "--limitby balance" is used,
405    but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf
406    to obtain a similar result (warning message when quota is low).
407
408Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
409
410    $ /etc/init.d/cupsys restart
411   
412  or :
413 
414    $ /etc/init.d/lprng restart
415       
416Your users now should be able to print but not exceed their
417printing quota.
418
419To see printer quota usage, you can use :
420
421    $ repykota --printer lp
422   
423or :
424
425    $ repykota
426   
427    which will print quota usage for all users on all printers,
428    along with totals, if you are the root user. If you are
429    a regular user, only your own quota report will be produced.
430   
431Quota reports are also available remotely by using the CGI script
432printquota.cgi provided in the cgi-bin/ subdirectory.
433
434For different security concerns, please give a look at the SECURITY
435file which is part of this software.
436           
437============================================================
438
439Mailing list :
440--------------
441
442  A mailing list is dedicated to Pykota, you can subscribe to it
443  or consult its archives at :
444 
445    http://cgi.librelogiciel.com/mailman/listinfo/pykota
446   
447IRC :   
448-----
449
450  You can also chat with us :
451 
452        /server irc.freenode.net
453        /join #pykota
454   
455============================================================
456   
457Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
458or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.