root / pykota / trunk / README @ 2421

Revision 2394, 27.3 kB (checked in by jerome, 19 years ago)

New feature added to list

  • 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19
20====================================================================
21
22READ SPECIAL LICENSING AND REDISTRIBUTION TERMS IN THE FILE 'LICENSE'
23
24====================================================================
25
26PyKota features :
27-----------------
28
29    Free Software :
30   
31        - Licensed under the terms of the GNU General Public License.
32       
33    Commercially Supported :   
34   
35        - Support Contracts are available from http://www.librelogiciel.com/techsupport/
36       
37    Operating systems :
38   
39        - Any Unix-like system as print server.
40           
41        - Any operating system as client.
42           
43    Printing systems :
44   
45        - Supports both CUPS and LPRng as the printing system.
46       
47    Databases :
48   
49        - Supports PostgreSQL as the Quota Storage backend.
50          Complete database creation script in SQL is included.
51       
52        - Supports any LDAP server as the Quota Storage backend.
53          Complete LDAP schema and sample empty tree are included.
54          Plugging PyKota into your existing LDAP infrastructure
55          is really easy thanks to PyKota's great configurability.
56         
57        - The print jobs history can be stored in any database 
58          of your choice (or in plain text files) if needed.
59           
60    Printers :       
61   
62        - Hardware or Software accounting methods are completely
63          configurable.
64         
65        - Supports any printer which can report its internal
66          page counter. Can ask printers for their internal
67          page counter via SNMP, Netatalk, PJL, PS, or any
68          other way.
69          This is completely configurable.
70         
71        - Supports DSC compliant and binary PostScript, PDF, PCL5 (up to),
72          PCLXL (aka PCL6), ESC/P2, DVI, TIFF, OpenOffice.org Writer and
73          OpenOffice.org Impress printers (or virtual printers) natively
74          (through the direct use of pkpgcounter's code) for software
75          accounting methods. More formats to come.
76         
77        - Supports any other Page Description Language for which you 
78          have a parser which can be scripted.
79           
80    Quota systems :       
81   
82        - Supports printers and printers groups quotas.
83       
84        - Supports users and users groups quotas.
85       
86        - Supports page quotas.
87          Page quotas can be set differently on a per printer
88          and per user/group basis.
89       
90        - Supports account balance quotas in any currency.
91          Account balance quotas can be set on a per user
92          basis. The account balance is shared amongst
93          all printers. The history of payments (positive
94          or negative credits to an user account) is kept.
95         
96        - Supports high granularity periodic print quotas : down
97          to one minute intervals if needed.
98       
99        - Page quotas and account balance can be set/reset
100          independantly.
101         
102        - Page quotas can be set on a per user or per group basis
103          for a particular printer.
104         
105        - Price per page and per job can be set differently 
106          on any printer.
107       
108        - Low level of page quota or account balance are
109          configurable.
110         
111        - Both soft and hard limit with configurable grace delay 
112          can be set for page quota.
113         
114        - Possibility to disable quota enforcement for any user
115          or group, while still keeping page accounting.
116         
117        - Each user can have an overcharging (or undercharging) factor, 
118          which is applied whenever PyKota computes the cost of a
119          print job.
120         
121        - Specific pages and credits counters can be defined per billing code,
122          and can be reset independantly of the printing history.
123       
124    Administration :       
125   
126        - Powerful delegation of administrative priviledges.
127       
128        - Powerful administration tools can be used to
129          automate setting or resetting of quotas or
130          account balances at specific intervals.
131         
132        - Administration tools can modify several users, 
133          groups, or printers at once with the use of
134          powerful wildcard characters.
135         
136        - Account balances can be set, incremented, or 
137          decremented. History of payments is kept.
138         
139        - Number of pages used can be set, incremented, or 
140          decremented.
141         
142        - Both printers and users can be automatically added on
143          first print in a completely configurable way.
144         
145        - Quota report generator available either from the 
146          command line or in any web browser.
147          The web-based quota report generator can be
148          user/password protected.
149         
150        - Print quote generator can tell users how much 
151          a print job will cost them in advance.
152         
153        - Policy with regard to unregistered users can   
154          be configured for each printer to either deny
155          printing, allow printing, or delegate the
156          decision to any external tool.
157         
158        - Warning and error messages can be automatically 
159          sent via email or via any other mean to the administrator,
160          the user, both, or none.
161         
162        - Warning and error messages' content is completely
163          configurable.
164         
165        - Configuration can be changed without needing to 
166          restart the printing system.
167       
168        - Complete print job history is kept. This can be
169          disabled if needed.
170         
171        - Automated low quota or balance remainder can be
172          scheduled regularly or launched manually.
173         
174        - Starting and Ending personalized dynamic banners can be
175          generated on the fly, and accounted for or not, depending
176          on some configuration settings.
177          Banners can still be enabled even if the print job is denied.
178          NB : Banners are a CUPS only feature for now.
179         
180        - Duplicate print jobs can be forbidden automatically. The decision
181          can be left to any script to decide this on a per job basis.
182         
183        - Username and billing code can be overwritten at printing time,
184          to allow people to login as guest users and print as authenticated
185          users, for example.
186         
187        - Powerful data dumper to export datas to other
188          software (spreadsheets for example). Actually
189          supported formats are :
190         
191            - Comma separated values ;
192           
193            - Semicolon separated values ;
194           
195            - Tab separated values ;
196           
197            - XML.
198           
199            - CUPS' page_log format, to easily interface in
200              real time with third party apps like phpPrintAnalyzer
201              and similar tools.
202         
203    User Interface :         
204   
205        - All the command line tools accept the -h | --help
206          command line option which prints all the available
207          options and show usage examples.
208         
209        - Completely internationalized. Actually supports the 
210          English, French, Spanish, Portuguese, Brazilian, Swedish,
211          Thai, Greek, German, Italian, Norwegian (Bokm�, Turkish
212          and traditional Chinese languages.
213          More to come.
214         
215        - Web enabled print quota monitor, data dumper, and quote
216          generator.
217       
218        - An On Screen Display X-Window print quota monitor is included.
219       
220        - An email gateway to allow users to retrieve their print quota
221          information by sending an email message to a dedicated address
222          is included.
223       
224        - A cross-platform print quota monitor will soon be available
225          as an purchaseable add-on.
226         
227        - Third party web based management tools are available.
228
229====================================================================
230       
231Planned features are described in the TODO file.
232
233Actually two (or an infinity of) page accounting methods are
234implemented :
235
236  - The 'hardware' method consists in querying the printer (via SNMP
237    or Netatalk or any other method of your choice) for its total pages
238    counter.
239    This is done both at the beginning and at the end of a
240    print job. The counters difference is then immediately used to
241    decrease the user's account balance or increase his quota usage.
242   
243  - The 'software' method consists in delegating the computation of the
244    job's size in number of pages to any external command of your choice.
245    The command can read the job's data from its standard input and MUST
246    output the job's size on its standard output. Changes to the user
247    account are reported immediately.
248   
249    PyKota featured an internal software accounting method which handles
250    several Page Description Languages : DSC compliant and binary PostScript,
251    PDF, PCLXL (aka PCL6), PCL3/4/5, ESC/P2, DVI, TIFF, OpenOffice.org Writer
252    and OpenOffice.org Impress. This software is now distributed separately
253    as 'pkpgcounter', and not included anymore in PyKota, so you must now
254    download and install it before running PyKota.
255   
256PyKota is known to work fine with most laser printers, either with
257software accounting, or with hardware accounting if the printer
258supports this.
259
260============================================================
261
262SUPPORT CONTRACTS:
263==================
264
265  You can now purchase 8x5x365@NextBusinessDay Technical
266  Support Contracts from us. The yearly fee is computed with 
267  the following formula :
268
269  (100.0 * NbPrintServers) + (2.5 * NbPrinters) + (0.04 * NbUsers) EUROS.
270 
271  This fee includes the VAT, a free subscription to official 
272  PyKota packages, and the latest documentation on paper.
273
274  Please send an email to alet@librelogiciel.com if you're
275  interested in purchasing such a contract.   
276
277  Remember that purchasing a support contract for Free Software like PyKota
278  is a great way to show your appreciation for the work already being done
279  on this project, and will help to improve this software in the future.
280
281============================================================
282
283INSTALLATION:
284=============
285
286NB :
287====
288
289  You may learn more about PyKota, if it fits your own organization,
290  its internal working, and some potential performance drawbacks and
291  how to avoid them, in a document created by Ryan Suarez at :
292 
293    http://archive.macosxlabs.org/forum/webcrossing_archive/documentation/Pykota_and_CUPS/Pykota_and_CUPS.html
294
295  You may also find the following document interesting :
296 
297    http://es.tldp.org/Tutoriales/doc-openldap-samba-cups-python/
298   
299  This document, written in Spanish by Sergio Gonzalez Gonzalez, 
300  describes the integration of PyKota into an OpenLDAP + Samba
301  + CUPS installation. Even for people who can't read spanish
302  this document is really interesting, and contains lots of
303  screenshots.
304 
305  Finally, SuSe users may find the following document to best describe
306  how to install PyKota on their favorite distribution. It's a Spanish
307  document written by Dennis Romero :
308 
309    http://www.cvr.espol.edu.ec/people/dennis/Pykota1.19-SuSE9.1.pdf
310 
311 
312Prerequisite :
313--------------
314   
315  You need to have the following tools installed on the CUPS Server :
316 
317    - CUPS (http://www.cups.org) or LPRng (http://www.lprng.com)
318    - Python v2.1 or above (http://www.python.org)
319    - eGenix' mxDateTime Python extension (http://www.egenix.com)
320    - The pkpgcounter command line tool, version 1.56 or higher. This
321      tool is now mandatory for PyKota to work.
322      (http://www.librelogiciel.com/software/)
323    - The JAXML Python module to be able to dump datas in the XML format.
324      (http://www.librelogiciel.com/software/)
325    - The Python-SNMP module to query printers for their page counter.
326      (http://pysnmp.sourceforge.net).
327      IMPORTANT : version 3.4.3 (or 3.4.2) is REQUIRED. Versions 2.x or
328      4.x won't work for now.
329    - The Python-OSD module to use the graphical print quota reminder.
330      (http://repose.cx/pyosd/)
331    - SNMP tools (specifically the snmpget command) if you prefer to
332      use your own script to request query printers.
333      (http://www.net-snmp.org)
334    - Netatalk (specifically the pap command) if you plan to
335      request your printer's lifetime page counter via AppleTalk.
336      (http://netatalk.sourceforge.net)
337    - The ReportLab Python module (http://www.reportlab.org) if you want 
338      to have PyKota generate nice banners for you.
339    - The Python Imaging Library (aka PIL) module
340      (http://www.pythonware.com/downloads) if you want to have PyKota
341      generate nice banners for you.
342    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
343      libraries if you plan to use PostgreSQL as the Quota Storage
344      backend.
345      (http://www.postgresql.org and http://www.pygreql.org)
346 or     
347    - python-ldap Python module and the OpenLDAP client libraries 
348      if you plan to use an LDAP server as the Quota Storage backend.
349      (http://www.openldap.org and http://python-ldap.sourceforge.net)
350   
351  On Intel i386 architecture, and for performance reasons, it is
352  strongly suggested that you install the Python accelerator Psyco,
353  available at :
354 
355      http://psyco.sourceforge.net
356     
357  Under Debian :   
358 
359      $ apt-get install python-psyco
360     
361  Other architectures may be supported as well in the future, check   
362  this on Psyco's website.
363 
364  Installing Psyco is not mandatory, but it will speedup PCL5 parsing
365  by almost 3 times. PostScript and PDF parsing can also benefit,
366  but in an almost unnoticeable manner since this part of the code
367  is already optimal. For PCL5 this is a completely different matter,
368  and if you install Psyco you will never regret it !
369  Same remark applies for PCL6 (aka PCLXL) : the parser is completely
370  different, but the performance gain with Psyco is impressive.
371 
372  You may also benefit from having the following tools installed to
373  deal with some printers :
374 
375    - npadmin
376    - netcat
377    - ghostscript
378   
379  You need to have the following tools installed on the Quota Storage 
380  Server :
381 
382    - PostgreSQL (http://www.postgresql.org)
383   
384  or 
385 
386    - OpenLDAP, or any other LDAP server (http://www.openldap.org)
387   
388NB :   
389
390  PygreSQL must be linked with the PostgreSQL client libraries on
391  the Print Server. The PostgreSQL client libraries' version must
392  match the PostgreSQL version used on the Quota Storage Server.
393 
394or 
395
396  python-ldap must be linked with the OpenLDAP client libraries on the
397  Print Server. The OpenLDAP client libraries' version should match the
398  OpenLDAP version used on the Quota Storage Server, if applicable.
399 
400  This list of prerequisite software may change in the future, when
401  PyKota will support more functionnalities you will be given
402  alternatives.
403 
404  Of course the Print Server and the Quota Storage Server can be the
405  very same machine if you've got a tiny network, or you can have
406  multiple Print Servers all storing their quotas on the same Quota
407  Storage Server if you've got a bigger network.
408 
409Hint : 
410------
411
412  - The Debian GNU/Linux distribution is to our knowledge the
413    easiest distribution to install PyKota on, because all
414    of PyKota dependencies are already included, excepted
415    for the PySNMP (http://pysnmp.sourceforge.net) module
416    and the pkpgcounter utility which for now have to be downloaded
417    and installed separately.
418
419Then :   
420------
421 
422Download the latest PyKota version from the Subversion tree :
423
424    $ svn co svn://svn.librelogiciel.com/pykota/trunk pykota
425
426You can now check if the dependencies are correct by typing :
427
428    $ python checkdeps.py
429   
430    An availability report for all the software needed by PyKota
431    will be displayed : you'll have to install the missing
432    software if you want PyKota to work correctly.
433   
434To install the software, just type :
435
436    $ python setup.py install
437
438You may need to be logged in with sufficient privileges (e.g. root)
439
440Create a system user for PyKota :
441
442    $ adduser --system --group --home /etc/pykota --gecos PyKota pykota
443   
444Put the user your printing system is run as in the pykota system group :
445
446    $ adduser lp pykota
447   
448    NB : on our system, the CUPS printing system runs as system user 'lp'.
449    Please adapt this to your own system.
450
451Go to the initscripts subdirectory of PyKota's sources, and choose
452the appropriate storage backend for your configuration. Read carefully
453the associated README file and execute the initialization script
454to create an empty PyKota Storage. Upgrade scripts may be
455provided as well. NB : if you use PostgreSQL, a good way to
456make PyKota work first time is to modify PostgreSQL's pg_hba.conf
457to allow the 'trust' database connection mode. However once PyKota
458works it is HIGHLY RECOMMENDED TO CHANGE THIS TO A MORE SECURE
459VALUE.
460
461Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
462sample configuration files to /etc/pykota/pykota.conf and
463/etc/pykota/pykotadmin.conf 
464The installation script usually copies these files into /usr/share/pykota
465
466NB : You can move PyKota's configuration files elsewhere, they will
467be searched first in user pykota's home directory.
468
469You need to adapt these files to your own needs. Especially you may
470have to create sections named after your own printers, and change
471the administrator's email address which by default is
472root@localhost. Read and try to understand these two very well
473commented files, so that you'll encounter less problems later.
474
475Also be sure to double check that commands that query printers
476for their internal page counter work from the command line
477before using them in PyKota's configuration.
478
479The rest of the installation depends on your printing system :
480
481  - CUPS Printing System :
482 
483    Once and for all :
484   
485        Create a symbolic link to the cupspykota backend
486        in CUPS's backend directory :
487       
488          $ cd /usr/lib/cups/backend
489          $ ln -s /usr/share/pykota/cupspykota cupspykota
490         
491        Restart CUPS so that the new backend can be detected.
492       
493          $ /etc/init.d/cupsys restart
494         
495        or :   
496     
497          $ /etc/rc.d/init.d/cupsys restart
498         
499        or any similar command depending on your operating system. 
500         
501    For new printers :
502   
503        Go to CUPS management interface (http://localhost:631)
504        and choose the appropriate PyKota managed device depending
505        on the type of printer you use. For example, if your
506        printer is waiting on :
507       
508            socket://myprinter.example.com:9100
509           
510        Then choose :   
511       
512            cupspykota:socket://myprinter.example.com:9100
513           
514        Configure your printer as usual.   
515       
516        Now double check /etc/pykota/pykota.conf
517       
518        You should manually create a section named after the
519        printer you've just added, unless you have set
520        all options globally.
521       
522        The new pkhint command can help you with correct settings
523        for your printers, but don't rely on it because it is still
524        experimental work. To use pkhint, you have to feed it with
525        CUPS' printers.conf file this way :
526       
527          $ pkhint </etc/cups/printers.conf
528       
529        pkhint will try to tell you what is the best accounting
530        method for each printer and will print some lines you'll
531        just have to copy&paste in the appropriate sections in
532        /etc/pykota/pykota.conf
533       
534        That's all.
535   
536    For existing printers :
537   
538        If you had already installed a version of PyKota earlier
539        than 1.16alpha7, then remove the *cupsFilter lines in your
540        PPD files for each already managed printer. Each
541        line to remove is of the form :
542       
543          *cupsFilter: "application/vnd.cups-postscript 0 /usr/share/pykota/pykota"
544       
545        This means that each time the pstops filter will be executed, it will
546        pass the job's data through the pykota filter which is present in
547        /usr/share/pykota
548       
549        Don't touch anything else, especially any other *cupsFilter line.
550        Then save each of these files.
551       
552        Then, the easiest is to directly modify the DeviceURI lines
553        in /etc/cups/printers.conf, you just have to put
554        'cupspykota:' in front of what is already on these lines.
555        For example, replace :
556   
557            DeviceURI socket://myprinter.example.com:9100
558       
559        with :   
560   
561            DeviceURI cupspykota:socket://myprinter.example.com:9100
562           
563        or :   
564       
565            DeviceURI cupspykota://socket://myprinter.example.com:9100
566       
567        Save the file and restart CUPS.
568       
569        Here too, you may find it interesting to use the pkhint command as
570        described above to help with manual configuration of the file
571        /etc/pykota/pykota.conf
572
573  - LPRng Printing System :
574 
575    For each printer on which you want to use PyKota :
576   
577        Modify the printer's entry in /etc/printcap : you have to add
578        the three following lines :
579       
580          :achk=true:\
581          :as=/usr/share/pykota/lprngpykota:\
582          :ae=/usr/share/pykota/lprngpykota:\
583         
584        This will tell LPRng to activate accounting, and use the lprngpykota
585        accounting filter both at the start and at the end of printing.
586       
587    When all modifications are done, just save the /etc/printcap file and   
588    restart LPRng :
589   
590          $ /etc/init.d/lprng restart
591         
592        or :   
593     
594          $ /etc/rc.d/init.d/lprng restart
595         
596        or any similar command depending on your operating system. 
597       
598    NB : the pkhint command can't be used with LPRng for now, so you   
599         have to modify /etc/pykota/pykota.conf carefully. The comments
600         in this file will help you.
601     
602Now you can begin to populate the PyKota's database with printers,
603users and groups :
604 
605Add printers and users to the quota system and set their quota values :
606
607Starting from version 1.18alpha2, the preferred command to manage
608printers is named pkprinters
609
610    $ pkprinters --help
611   
612    will tell you how to create, manage or delete printers and
613    printers groups.
614   
615    $ pkprinters --add --charge 0.05 hp2100
616   
617    would add the printer named hp2100 with a price per page
618    of 0.05 unit.
619
620Now set quotas for users on this printer :     
621
622    $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN
623       
624    launching edpykota without any argument or with the --help
625    command line option will show you all the possibilities.
626   
627    by default, each user is limited by "quota", this means that on
628    each printer he can have a different soft and hard limit.
629    You may want to limit the user by his account balance value,
630    in which case, the print quota is shared between all printers
631    instead of being different. To do this, use the following :
632   
633    $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN
634   
635    This will put 10 $ (or Euros, PyKota doesn't care) on each user's account
636    balance, and tell PyKota to limit them by their account balance value.
637    Whenever they print on any printer, their account balance value is
638    decreased by an amount which depends on the particular price per page
639    and per job that you may have defined on the printer with edpykota's
640    --charge command line option.
641    Soft and Hard limits are not used if "--limitby balance" is used,
642    but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf
643    to obtain a similar result (warning message when quota is low).
644
645Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
646
647    $ /etc/init.d/cupsys restart
648   
649  or :
650 
651    $ /etc/init.d/lprng restart
652       
653Your users now should be able to print but not exceed their
654printing quota.
655
656To see printer quota usage on printer hp2100, you can use :
657
658    $ repykota --printer hp2100
659   
660or :
661
662    $ repykota
663   
664    which will print quota usage for all users on all printers,
665    along with totals, if you are a PyKota Administator. If you are
666    a regular user, only your own quota report will be produced.
667   
668Quota reports are also available remotely by using the CGI script
669printquota.cgi provided in the cgi-bin/ subdirectory. You can
670also use the CSS stylesheet present in the stylesheets/ subdirectory
671and put it at your web server's DocumentRoot, to benefit from a nicer
672look, especially quota violations will appear in different colors.
673
674For additionnal security concerns, please give a look at the SECURITY
675file which is part of this software.
676
677To diagnose a problem when something doesn't work as expected,
678please read the very first entry in the FAQ document.
679           
680============================================================
681
682Additionnal tools :
683-------------------
684
685Some people have developped tools around PyKota, and make
686them available under the GNU General Public License :
687
688  - Kanakorn Horsiritham developped phpPykotaAdmin which is
689    a web based database independant administrative GUI,
690    written in PHP.
691 
692      http://opensource.psu.ac.th/~kanakorn/mambo/
693     
694    He was also kind enough to write an installation guide 
695    in english for CUPS and PyKota with phpPykotaAdmin on Fedora
696    Core 3. You'll find this document on the same website.
697   
698    This great software currently at version 0.3 is a wonderful
699    basis for an administrative GUI since it only depends on
700    PyKota commands to be present to successfully manage
701    PyKota's database.
702 
703Additionnal software will be listed here when they will be 
704ready.
705
706============================================================
707
708Mailing list :
709--------------
710
711  A mailing list is dedicated to Pykota, you can subscribe to it
712  or consult its archives at :
713 
714    http://cgi.librelogiciel.com/mailman/listinfo/pykota
715   
716  The mailing list is the preferred way to obtain support, because 
717  all members can help and can also benefit from the solutions
718  proposed by other members.
719 
720  Posts by non-members are usually rejected.
721 
722  The mailing list language is english and only english.
723   
724IRC :   
725-----
726
727  You can also chat with us :
728 
729        /server irc.freenode.net
730        /join #pykota
731       
732  Preferred language on this channel is english, but french     
733  is also accepted. Try to avoid exposing complex problems
734  in french because english speaking people on the channel
735  wouldn't benefit from the solutions.
736 
737  PyKota's main author is known as 'tamere' on IRC.
738   
739============================================================
740   
741Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
742or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.