root / pykota / trunk / README @ 2049

Revision 2049, 23.4 kB (checked in by jalet, 19 years ago)

Typos andnote about third party apps

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