root / pykota / trunk / README @ 1765

Revision 1744, 19.5 kB (checked in by jalet, 20 years ago)

Wrote some doc for dumpykota

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