root / pykota / trunk / README @ 1660

Revision 1651, 19.3 kB (checked in by jalet, 20 years ago)

Added link to Sergio Gonzalez Gonzalez' document

  • 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 empty 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        - Hardware or Software accounting methods are completely
52          configurable.
53         
54        - Supports any printer which can report its internal
55          page counter. Can ask printers for their internal
56          page counter via SNMP, Netatalk, PJL, PS, or any
57          other way.
58          This is completely configurable.
59         
60        - Supports DSC compliant and binary PostScript, PDF, PCL5,
61          and PCLXL (aka PCL6) printers natively for software
62          accounting methods. More formats to come.
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. The history of payments (positive
78          or negative credits to an user account) is kept.
79         
80        - Page quotas and account balance can be set/reset
81          independantly.
82         
83        - Page quotas and account balances can be set on
84          a per user or per group basis.
85         
86        - Price per page and per job can be set differently 
87          on any printer.
88       
89        - Low level of page quota or account balance are
90          configurable.
91         
92        - Both soft and hard limit with configurable grace delay 
93          can be set for page quota.
94         
95        - Possibility to disable quota enforcement for any user
96          or group, while still keeping page accounting.
97             
98    Administration :       
99   
100        - Powerful administration tools can be used to
101          automate setting or resetting of quotas or
102          account balances at specific intervals.
103         
104        - Administration tools can modify several users, 
105          groups, or printers at once.
106         
107        - Account balances can be set, incremented, or 
108          decremented. History of payments is kept.
109         
110        - Both printers and users can be automatically added on
111          first print in a completely configurable way.
112         
113        - Quota report generator available either from the 
114          command line or in any web browser.
115          The web-based quota report generator can be
116          user/password protected.
117         
118        - Print quote generator can tell users how much 
119          a print job will cost them in advance.
120         
121        - Policy with regard to unregistered users can   
122          be configured for each printer to either deny
123          printing, allow printing, or delegate the
124          decision to any external tool.
125         
126        - Warning and error messages can be automatically 
127          sent via email to the administrator, the user,
128          both, or none.
129         
130        - Warning and error messages' content is completely
131          configurable.
132         
133        - Configuration can be changed without needing to 
134          restart the printing system.
135       
136        - Complete print job history is kept. This can be
137          disabled if needed.
138         
139        - Automated low quota or balance remainder can be
140          scheduled regularly or launched manually.
141         
142    User Interface :         
143   
144        - All the command line tools accept the -h | --help
145          command line option which prints all the available
146          options and show usage examples.
147         
148        - Completely internationalized. Actually supports the 
149          English, French, Spanish, Portuguese, Brasilian, Swedish,
150          Thai, and Italian languages. More to come.
151
152====================================================================
153       
154Planned features are described in the TODO file.
155
156Actually two (or an infinity of) page accounting methods are
157implemented :
158
159  - The 'hardware' method consists in querying the printer (via SNMP
160    or Netatalk or any other method of your choice) for its total pages
161    counter.
162   
163    This is done both at the beginning and at the end of a
164    print job. The counters difference is then immediately used to
165    decrease the user's account balance or increase his quota usage.
166   
167  - The 'software' method consists in delegating the computation of the
168    job's size in number of pages to any external command of your choice.
169    The command can read the job's data from its standard input and MUST
170    output the job's size on its standard output. Changes to the user
171    account are reported immediately.
172   
173PyKota is known to work fine with most laser printers, either with
174software accounting, or with hardware accounting if the printer
175supports this.
176
177============================================================
178
179INSTALLATION:
180=============
181
182NB :
183====
184
185  You may learn more about PyKota, if it fits your own organization,
186  its internal working, and some potential performance drawbacks and
187  how to avoid them, in a WiKi administered by Ryan Suarez at :
188 
189    http://webcrossing.macosxlabs.org/webx?14@30.QAu3a5k0c4z.7@.26bf4661
190
191  You may also find the following document interesting :
192 
193    http://es.tldp.org/Tutoriales/doc-openldap-samba-cups-python/
194   
195  This document, written in Spanish by Sergio Gonzalez Gonzalez, 
196  describes the integration of PyKota into an OpenLDAP + Samba
197  + CUPS installation. Even for people who can't read spanish
198  this document is really interesting, and contains lots of
199  screenshots.
200 
201Prerequisite :
202--------------
203   
204  You need to have the following tools installed on the CUPS Server :
205 
206    - CUPS or LPRng
207    - Python v2.1 or above
208    - eGenix' mxDateTime Python extension
209    - SNMP tools (specifically the snmpget command) if you plan to
210      request your printer's lifetime page counter via SNMP.
211    - Netatalk (specifically the pap command) if you plan to
212      request your printer's lifetime page counter via AppleTalk.
213    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
214      libraries if you plan to use PostgreSQL as the Quota Storage
215      backend.
216 or     
217    - python-ldap Python module and the OpenLDAP client libraries 
218      if you plan to use OpenLDAP as the Quota Storage backend.
219   
220  On Intel i386 architecture, and for performance reasons if you
221  print in PCL5 or PCL6 format, it is strongly suggested that you 
222  install the Python accelerator Psyco, available at :
223 
224      http://psyco.sourceforge.net
225     
226  Under Debian :   
227 
228      $ apt-get install python-psyco
229     
230  Other architectures may be supported as well in the future, check   
231  this on Psyco's website.
232 
233  Installing Psyco is not mandatory, but it will speedup PCL5 parsing
234  by almost 3 times. PostScript and PDF parsing can also benefit,
235  but in an almost unnoticeable manner since this part of the code
236  is already optimal. For PCL5 this is a completely different matter,
237  and if you install Psyco you will never regret it !
238  Same remark applies for PCL6 (aka PCLXL) : the parser is completely
239  different, but the performance gain with Psyco is impressive.
240 
241  You may also benefit from having the following tools installed to
242  deal with some printers :
243 
244    - npadmin
245    - netcat
246    - ghostscript
247   
248  You need to have the following tools installed on the Quota Storage 
249  Server :
250 
251    - PostgreSQL
252   
253  or 
254 
255    - OpenLDAP
256   
257NB :   
258
259  PygreSQL must be linked with the PostgreSQL client libraries on
260  the Print Server. The PostgreSQL client libraries' version must
261  match the PostgreSQL version used on the Quota Storage Server.
262 
263or 
264
265  python-ldap must be linked with the OpenLDAP client libraries on the
266  Print Server. The OpenLDAP client libraries' version must match the
267  OpenLDAP version used on the Quota Storage Server.
268 
269  This list of prerequisite software may change in the future, when
270  PyKota will support more functionnalities you will be given
271  alternatives.
272 
273  Of course the Print Server and the Quota Storage Server can be the
274  very same machine if you've got a tiny network, or you can have
275  multiple Print Servers all storing their quotas on the same Quota
276  Storage Server if you've got a bigger network.
277 
278Then :   
279------
280 
281Download the latest PyKota version from the CVS tree on :
282
283    http://savannah.nongnu.org/projects/pykota
284
285Just type :
286
287    python setup.py install
288
289You may need to be logged in with sufficient privileges (e.g. root)
290
291The installation script will now automatically check if some software
292is missing and ask you if you still want to proceed with the
293installation or abort it completely.
294
295Go to the initscripts subdirectory of PyKota's sources, and choose
296the appropriate storage backend for your configuration. Read carefully
297the associated README file and execute the initialization script
298to create an empty PyKota Storage. Upgrade scripts may be
299provided as well.
300
301Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
302sample configuration files to /etc/pykota/pykota.conf and
303/etc/pykota/pykotadmin.conf (the installation script tries to do
304this for you if needed and you agreed to this action). You need to
305adapt these files to your own needs. Especially you may have to create
306sections named after your own printers, and change the
307administrator's email address which by default is root@localhost.
308Read and try to understand these two very well commented files,
309so that you'll encounter less problems later.
310
311Also be sure to double check that commands that query printers
312for their internal page counter work from the command line
313before using them in PyKota's configuration.
314
315The rest of the installation depends on your printing system :
316
317  - CUPS Printing System :
318 
319    Once and for all :
320   
321        Create a symbolic link to the cupspykota backend
322        in CUPS's backend directory :
323       
324          $ cd /usr/lib/cups/backend
325          $ ln -s /usr/share/pykota/cupspykota cupspykota
326         
327        Restart CUPS so that the new backend can be detected.
328       
329          $ /etc/init.d/cupsys restart
330         
331        or :   
332     
333          $ /etc/rc.d/init.d/cupsysrestart
334         
335        or any similar command depending on your operating system. 
336         
337    For new printers :
338   
339        Go to CUPS management interface (http://localhost:631)
340        and choose the appropriate PyKota managed device depending
341        on the type of printer you use. For example, if your
342        printer is waiting on :
343       
344            socket://myprinter.example.com:9100
345           
346        Then choose :   
347       
348            cupspykota:socket://myprinter.example.com:9100
349           
350        Configure your printer as usual.   
351       
352        Now double check /etc/pykota/pykota.conf
353       
354        You should manually create a section named after the
355        printer you've just added, unless you have set
356        all options globally.
357       
358        The new pkhint command can help you with correct settings
359        for your printers, but don't rely on it because it is still
360        experimental work. To use pkhint, you have to feed it with
361        CUPS' printers.conf file this way :
362       
363          $ pkhint </etc/cups/printers.conf
364       
365        pkhint will try to tell you what is the best accounting
366        method for each printer and will print some lines you'll
367        just have to copy&paste in the appropriate sections in
368        /etc/pykota/pykota.conf
369       
370        That's all.
371   
372    For existing printers :
373   
374        If you had already installed a version of PyKota earlier
375        than 1.16alpha7, then remove the *cupsFilter lines in your
376        PPD files for each printer already managed printers. Each
377        line to remove is of the form :
378       
379          *cupsFilter: "application/vnd.cups-postscript 0 /usr/share/pykota/pykota"
380       
381        This means that each time the pstops filter will be executed, it will
382        pass the job's data through the pykota filter which is present in
383        /usr/share/pykota
384       
385        Don't touch anything else, especially any other *cupsFilter line.
386        Then save each of these files.
387       
388        Then, the easiest is to directly modify the DeviceURI lines
389        in /etc/cups/printers.conf, you just have to put
390        'cupspykota:' in front of what is already on these lines.
391        For example, replace :
392   
393            DeviceURI socket://myprinter.example.com:9100
394       
395        with :   
396   
397            DeviceURI cupspykota:socket://myprinter.example.com:9100
398           
399        or :   
400       
401            DeviceURI cupspykota://socket://myprinter.example.com:9100
402       
403        Save the file and restart CUPS.
404       
405        Here too, you may find it interesting to use the pkhint command as
406        described above to help with manual configuration of the file
407        /etc/pykota/pykota.conf
408
409  - LPRng Printing System :
410 
411    For each printer on which you want to use PyKota :
412   
413        Modify the printer's entry in /etc/printcap : you have to add
414        the three following lines :
415       
416          :achk=true:\
417          :as=/usr/share/pykota/lprngpykota:\
418          :ae=/usr/share/pykota/lprngpykota:\
419         
420        This will tell LPRng to activate accounting, and use the lprngpykota
421        accounting filter both at the start and at the end of printing.
422       
423    When all modifications are done, just save the /etc/printcap file and   
424    restart LPRng :
425   
426          $ /etc/init.d/lprng restart
427         
428        or :   
429     
430          $ /etc/rc.d/init.d/lprng restart
431         
432        or any similar command depending on your operating system. 
433       
434    NB : the pkhint command can't be used with LPRng for now, so you   
435         have to modify /etc/pykota/pykota.conf carefully. The comments
436         in this file will help you.
437     
438Now you can begin to populate the PyKota's database with printers,
439users and groups :
440 
441Add printers and users to the quota system and set their quota values :
442
443Starting from version 1.18alpha2, the preferred command to manage
444printers is named pkprinters
445
446    $ pkprinters --help
447   
448    will tell you how to create, manage or delete printers and
449    printers groups.
450   
451    $ pkprinters --add --charge 0.05 hp2100
452   
453    would add the printer named hp2100 with a price per page
454    of 0.05 unit.
455
456Now set quotas for users on this printer :     
457
458    $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN
459       
460    launching edpykota without any argument or with the --help
461    command line option will show you all the possibilities.
462   
463    by default, each user is limited by "quota", this means that on
464    each printer he can have a different soft and hard limit.
465    You may want to limit the user by his account balance value,
466    in which case, the print quota is shared between all printers
467    instead of being different. To do this, use the following :
468   
469    $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN
470   
471    This will put 10 $ (or Euros, PyKota doesn't care) on each user's account
472    balance, and tell PyKota to limit them by their account balance value.
473    Whenever they print on any printer, their account balance value is
474    decreased by an amount which depends on the particular price per page
475    and per job that you may have defined on the printer with edpykota's
476    --charge command line option.
477    Soft and Hard limits are not used if "--limitby balance" is used,
478    but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf
479    to obtain a similar result (warning message when quota is low).
480
481Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
482
483    $ /etc/init.d/cupsys restart
484   
485  or :
486 
487    $ /etc/init.d/lprng restart
488       
489Your users now should be able to print but not exceed their
490printing quota.
491
492To see printer quota usage, you can use :
493
494    $ repykota --printer lp
495   
496or :
497
498    $ repykota
499   
500    which will print quota usage for all users on all printers,
501    along with totals, if you are the root user. If you are
502    a regular user, only your own quota report will be produced.
503   
504Quota reports are also available remotely by using the CGI script
505printquota.cgi provided in the cgi-bin/ subdirectory. You can
506also use the CSS stylesheet present in the stylesheets/ subdirectory
507and put it at your web server's DocumentRoot, to benefit from a nicer
508look, especially quota violations will appear in different colors.
509
510For different security concerns, please give a look at the SECURITY
511file which is part of this software.
512           
513============================================================
514
515Mailing list :
516--------------
517
518  A mailing list is dedicated to Pykota, you can subscribe to it
519  or consult its archives at :
520 
521    http://cgi.librelogiciel.com/mailman/listinfo/pykota
522   
523  The mailing list is the preferred way to obtain support, because 
524  all members can help and can also benefit from the solutions
525  proposed by other members.
526 
527  Posts by non-members are usually rejected.
528 
529  The mailing list language is english and only english.
530   
531IRC :   
532-----
533
534  You can also chat with us :
535 
536        /server irc.freenode.net
537        /join #pykota
538       
539  Preferred language on this channel is english, but french     
540  is also accepted. Try to avoid exposing complex problems
541  in french because english speaking people on the channel
542  wouldn't benefit from the solutions.
543 
544  PyKota's main author is known as 'tamere' on IRC.
545   
546============================================================
547   
548Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
549or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.