root / pykota / trunk / README @ 2126

Revision 2126, 25.1 kB (checked in by jalet, 19 years ago)

Improved the installation documentation.
Now checkdeps also checks for the presence of GhostScript?, which
may be needed if PyKota's bannering facility is used or if some
printer driver produces non-DSC compliant PostScript?.

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