root / pykota / trunk / README @ 2236

Revision 2234, 25.9 kB (checked in by jerome, 19 years ago)

Improved installation instructions

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