root / pykota / trunk / README @ 2547

Revision 2545, 27.7 kB (checked in by jerome, 19 years ago)

Added polish translation.
Updated manual pages.

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