root / pykota / trunk / README @ 3374

Revision 3374, 21.1 kB (checked in by jerome, 14 years ago)

Removed test line to see if new svn repository works as expected.

  • 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
4
5(c) 2003, 2004, 2005, 2006, 2007, 2008 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 3 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, see <http://www.gnu.org/licenses/>.
18
19====================================================================
20
21READ SPECIAL LICENSING AND REDISTRIBUTION TERMS IN THE FILE 'LICENSE'
22
23====================================================================
24
25PyKota features :
26-----------------
27
28        http://www.pykota.com/software/pykota/features/
29
30====================================================================
31       
32Planned features are described in the TODO file.
33
34Actually three (or an infinity of) page accounting methods are
35implemented :
36
37  - The 'hardware' method consists in querying the printer (via SNMP
38    or Netatalk or any other method of your choice) for its internal
39    pages counter.
40    This is done both at the beginning and at the end of a
41    print job. The counters difference is then used to
42    decrease the user's account balance or increase his quota usage.
43   
44  - The 'software' method consists in delegating the computation of the
45    job's size in number of pages to any external command of your choice.
46    The command can read the job's data from its standard input and MUST
47    output the job's size on its standard output. Changes to the user
48    account are reported immediately. PyKota by default internally
49    uses the code from pkpgcounter which can handle a large number
50    of Page Description Languages, and can parse documents produced
51    either by GhostScript or by a number of native printer drivers.
52    Of course this means you have to install pkpgcounter if you want to
53    use the default PDL parser.
54    An up-to-date list of supported Page Description Languages and their
55    level of support is available from :
56     
57      http://www.pykota.com/software/pkpgcounter/
58   
59  - The 'ink' method consists in using pkpgcounter's code to compute 
60    how much of each page is covered by ink in each color of a particular
61    colorspace chosen between CMYK, CMY, RGB, and BW (grayscale).
62    These values are then summed up together and multiplied by a set
63    of coefficients defined in PyKota's configuration files.
64   
65PyKota is known to work with most printers, excepted GDI ones (Windows
66only). At least one of the accounting methods above should work
67for you. If it's not the case, please report the problem : tell us
68the exact brand and model of the printer, if possible the driver used,
69and send some test files.
70
71============================================================
72
73SUPPORT CONTRACTS:
74==================
75
76  You can now purchase 8x5x365@NextBusinessDay Technical
77  Support Contracts from us. The yearly fee is computed with 
78  the following formula :
79
80  (100.0 * NbPrintServers) + (2.5 * NbPrinters) + (0.04 * NbUsers) EUROS.
81 
82  This fee includes the VAT, and a free subscription to Official
83  PyKota packages.
84
85  Please send an email to alet@librelogiciel.com if you're
86  interested in purchasing such a contract.   
87
88  Remember that purchasing a support contract for Free Software like PyKota
89  is a great way to show your appreciation for the work already being done
90  on this project, and will help to improve this software in the future.
91
92============================================================
93
94INSTALLATION:
95=============
96
97NB :
98====
99
100  PyKota's documentation is available as DocBook SGML sources
101  files in the pykota/docs directory. If you obtained an
102  Official package, in the same directory you'll also find
103  the documentation in HTML and PDF formats. Otherwise you
104  have to compile it into HTML or PDF yourself by using
105  the appropriate tools as installed on your system.
106 
107  PyKota's collaborative documentation is available from :
108 
109    http://www.pykota.com/wiki/
110   
111  You may learn more about PyKota, if it fits your own organization,
112  its internal working, and some potential performance drawbacks and
113  how to avoid them, in a document created by Ryan Suarez at :
114 
115    http://archive.macosxlabs.org/forum/webcrossing_archive/documentation/Pykota_and_CUPS/Pykota_and_CUPS.html
116
117  You may also find the following document interesting :
118 
119    http://es.tldp.org/Tutoriales/doc-openldap-samba-cups-python/
120   
121  This document, written in Spanish by Sergio Gonzalez Gonzalez, 
122  describes the integration of PyKota into an OpenLDAP + Samba
123  + CUPS installation. Even for people who can't read spanish
124  this document is really interesting, and contains lots of
125  screenshots.
126 
127 
128Prerequisite :
129--------------
130   
131  See :
132 
133    http://www.pykota.com/wiki/Dependencies
134   
135  for an up-to-date list, or see below (maybe not up-to-date) :
136 
137  You need to have the following tools installed on the CUPS Server :
138 
139    - CUPS (http://www.cups.org). PyKota v1.27 requires CUPS v1.3.4 or higher.
140    - Python v2.3 or higher (http://www.python.org)
141    - eGenix' mxDateTime Python extension (http://www.egenix.com)
142    - The pkpgcounter command line tool, version 1.56 or higher. This
143      tool is now mandatory for PyKota to work.
144      (http://www.pykota.com/software/pkpgcounter)
145    - The pkipplib Python library (http://www.pykota.com/software/pkipplib) 
146    - The JAXML Python module to be able to dump datas in the XML format.
147      (http://www.librelogiciel.com/software/)
148    - The Python-PAM module if you need the pknotify command to be able 
149      to check usernames and passwords. (http://www.pangalactic.org/PyPAM)
150    - The Python-SNMP module to query printers for their page counter.
151      (http://pysnmp.sourceforge.net)
152      IMPORTANT : version 3.4.2 or higher is REQUIRED.
153      Versions 2.x won't work. Versions 4.x now work (tested with v4.1.5a).
154    - The Python-OSD module to use the graphical print quota reminder.
155      (http://repose.cx/pyosd/)
156    - SNMP tools (specifically the snmpget command) if you prefer to
157      use your own script to request query printers instead of PyKota's
158      internal SNMP handling facilities, which is not recommanded...
159      (http://www.net-snmp.org)
160    - Netatalk (specifically the pap command) if you plan to
161      request your printer's lifetime page counter via AppleTalk.
162      (http://netatalk.sourceforge.net)
163    - The ReportLab Python module (http://www.reportlab.org) if you want 
164      to have PyKota generate nice banners for you.
165    - The Python Imaging Library (aka PIL) module
166      (http://www.pythonware.com/downloads) if you want to have PyKota
167      generate nice banners for you.
168    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
169      libraries if you plan to use PostgreSQL as the database backend.
170      (http://www.postgresql.org and http://www.pygreql.org)
171 or     
172    - python-ldap Python module and the OpenLDAP client libraries 
173      if you plan to use an LDAP server as the database backend.
174      (http://www.openldap.org and http://python-ldap.sourceforge.net)
175 or
176    - SQLite v3.2.7 and the SQLite libraries if you plan to use SQLite
177      as the database backend (http://www.sqlite.org). You also need the
178      PySQLite module v2.0.5 or higher (http://www.pysqlite.org)
179 or
180    - The MySQL-python bindings.
181      IMPORTANT: If you are using MySQL 4.1, then MySQL-python must be
182      version 1.2 or greater. Version 1.0 does not work correctly with 4.1.
183     
184   
185  On Intel i386 architecture, and for performance reasons, it is
186  strongly suggested that you install the Python accelerator Psyco,
187  available at :
188 
189      http://psyco.sourceforge.net
190     
191  Under Debian :   
192 
193      $ apt-get install python-psyco
194     
195  Other architectures may be supported as well in the future, check   
196  this on Psyco's website.
197 
198  Installing Psyco is not mandatory, but it will speedup PCL5 parsing
199  by almost 3 times. PostScript and PDF parsing can also benefit,
200  but in an almost unnoticeable manner since this part of the code
201  is already optimal. For PCL5 this is a completely different matter,
202  and if you install Psyco you will never regret it !
203  Same remark applies for PCL6 (aka PCLXL) : the parser is completely
204  different, but the performance gain with Psyco is impressive.
205 
206  You may also benefit from having the following tools installed to
207  deal with some printers :
208 
209    - npadmin
210    - netcat
211    - ghostscript
212   
213  You need to have the following tools installed on the database
214  server :
215 
216    - PostgreSQL (http://www.postgresql.org)
217   
218  or 
219 
220    - OpenLDAP, or any other LDAP server (http://www.openldap.org)
221   
222  or   
223 
224    - SQLite, v3.2.7 or higher (http://www.sqlite.org).
225      Beware : with SQLite the database server and the print
226      servers MUST be the very same machine.
227     
228  or     
229 
230    - MySQL 4.1 or higher. 5.x is recommended.
231   
232  This list of prerequisite software may change in the future, when
233  PyKota will support more functionnalities you will be given
234  alternatives.
235 
236  Of course the Print Server and the database server can be the
237  very same machine if you've got a tiny network, or you can have
238  multiple Print Servers all storing their quotas on the same database
239  server if you've got a bigger network. (NB : with SQLite, the database
240  can't be shared between several print servers)
241 
242Hint : 
243------
244
245  - The Debian GNU/Linux distribution is to our knowledge the
246    easiest distribution to install PyKota on, because almost all
247    of PyKota dependencies are already included, excepted
248    the pkpgcounter utility which for now have to be downloaded
249    and installed separately, and maybe one or two other dependencies,
250    depending on the version of Debian you are using.
251    We recommend you to use Debian's Etch distribution or
252    more recent. PyKota works fine on Sarge, but some additional
253    dependencies are missing in Sarge and have to be installed
254    manually.
255
256Then :   
257------
258 
259Download the latest PyKota version from the Subversion tree :
260
261    $ svn co svn://svn.librelogiciel.com/pykota/trunk pykota
262
263You can now check if the dependencies are correct by typing :
264
265    $ python checkdeps.py
266   
267    An availability report for all the software needed by PyKota
268    will be displayed : you'll have to install the missing
269    software if you want PyKota to work correctly.
270   
271To install the software, just type :
272
273    $ python setup.py install
274
275You may need to be logged in with sufficient privileges (e.g. root)
276
277If you use Debian or Ubuntu, and want to use PostgreSQL as the
278database backend, just type :
279
280    $ pksetup debian
281   
282or :   
283
284    $ pksetup ubuntu
285   
286and follow the instructions to install PyKota in interactive mode, then
287skip the remaining of the section below.
288
289Otherwise, you have to setup manually :
290
291Create a system user for PyKota :
292
293    $ adduser --system --group --home /etc/pykota --gecos PyKota pykota
294   
295Put the user your printing system is run as in the pykota system group :
296
297    $ adduser lp pykota
298   
299    NB : on our system, the CUPS printing system runs as system user 'lp'.
300    Please adapt this to your own system.
301
302Go to the initscripts/ subdirectory of PyKota's sources, and choose
303the appropriate storage backend for your configuration. Read carefully
304the associated README file, modify the initialization script to
305change the passwords, or, in the case of the LDAP backend, adapt it
306to your own LDAP DIT, and execute the initialization script
307to create an empty PyKota database. Upgrade scripts may be
308provided as well. NB : if you use PostgreSQL, a good way to
309make PyKota work first time is to modify PostgreSQL's pg_hba.conf
310to allow the 'trust' database connection mode. However once PyKota
311works it is HIGHLY RECOMMENDED TO CHANGE THIS TO A MORE SECURE
312VALUE. Look at the SECURITY document, PyKota's Official documentation
313and PostgreSQL's documentation for details on this subject.
314
315Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
316sample configuration files to ~pykota/pykota.conf and
317~pykota/pykotadmin.conf 
318The installation script usually copies these files into /usr/share/pykota
319
320NB : You can move PyKota's configuration files elsewhere, they will
321be searched first in user pykota's home directory, then in /etc/pykota.
322
323You need to adapt these files to your own needs. Especially you may
324have to create sections named after your own printers, and change
325the administrator's email address which by default is
326root@localhost. Read and try to understand these two very well
327commented files, so that you'll encounter less problems later.
328
329The rest of the installation depends on your printing system :
330
331  - CUPS Printing System :
332 
333    Once and for all :
334   
335        Modify CUPS' cupsd.conf to make CUPS listen to 127.0.0.1:631
336        INSTEAD OF to an unix domain socket, in addition to any
337        external network interface CUPS might already be listening to.
338       
339        Create a symbolic link to the cupspykota backend
340        in CUPS's backend directory :
341       
342          $ cd /usr/lib/cups/backend
343          $ ln -s /usr/share/pykota/cupspykota cupspykota
344         
345        If you use CUPS v1.2 or higher, please do this as well : 
346       
347          $ chmod 700 /usr/share/pykota/cupspykota
348         
349          This allows the cupspykota backend to support other
350          backends which must be run as user root, like the
351          lpd backend for example.
352         
353        Restart CUPS so that the new backend can be detected.
354       
355          $ /etc/init.d/cupsys restart
356         
357          for example under Debian, or any similar command depending
358          on your operating system of choice.
359         
360    For new printers :
361   
362        Go to CUPS management interface (http://localhost:631)
363        and choose the appropriate PyKota managed device depending
364        on the type of printer you use. For example, if your
365        printer is waiting on :
366       
367            socket://myprinter.example.com:9100
368           
369        Then choose :   
370       
371            cupspykota:socket://myprinter.example.com:9100
372           
373        Configure your printer as usual.   
374       
375        Now double check /etc/pykota/pykota.conf
376       
377        You should manually create a section named after the
378        printer you've just added, unless you have set
379        all options globally.
380       
381        The new pkturnkey command can help you with correct settings
382        for your printers. To have pkturnkey give you some hints
383        about what to put into pykota.conf for a particular
384        print queue, just use its --doconf command line switch :
385       
386          $ pkturnkey --doconf TheNameOfThePrintQueue
387       
388        pkturnkey will try to tell you what is the best accounting
389        method for each printer and will print some lines you'll
390        just have to copy&paste in the appropriate sections in
391        /etc/pykota/pykota.conf
392       
393        For more informations about what pkturnkey can do for you,
394        see pkturnkey's manual page or use the --help command
395        line switch :
396       
397          $ pkturnkey --help | less
398       
399        That's all.
400   
401    For existing print queues :
402   
403        You want to route the print queue through PyKota,
404        and you can do this in several manners.
405       
406          $ pkprinters --add --cups TheNameOfThePrintQueue
407         
408        or   
409       
410          if your printer's DeviceURI is something like :
411         
412              socket://myprinter.example.com:9100
413             
414          then you can do this :   
415         
416          $ pkprinters --add TheNameOfThePrintQueue
417          $ lpadmin -p TheNameOfThePrintQueue \
418                    -v cupspykota://socket://myprinter.example.com:9100
419         
420        Finally, you could do it manually by modifying the
421        the DeviceURI lines in /etc/cups/printers.conf :
422        You would have to preprend 'cupspykota://' in front
423        of what is already on these lines. For example, replace :
424   
425            DeviceURI socket://myprinter.example.com:9100
426       
427        with :   
428   
429            DeviceURI cupspykota://socket://myprinter.example.com:9100
430           
431        or :   
432       
433            DeviceURI cupspykota://socket://myprinter.example.com:9100
434       
435        Save the file and restart CUPS for the changes to take effect.
436       
437        Here too, you may find it interesting to use the pkturnkey command as
438        described above to help with manual configuration of the file
439        /etc/pykota/pykota.conf
440
441Now you can begin to populate the PyKota's database with printers,
442users and groups :
443 
444Add printers and users to the quota system and set their quota values :
445
446You can either use pkturnkey, or do the same things manually by
447using the pkprinters, pkusers and edpykota command line tools :
448
449Create printers :
450
451    $ pkprinters --help
452   
453    will tell you how to create, manage or delete printers and
454    printers groups.
455   
456    $ pkprinters --add --charge 0.05 hp2100
457   
458    would add the printer named hp2100 with a price per page
459    of 0.05 unit.
460
461Create users :
462
463    $ pkusers --add --limitby balance --balance 10.0 jerome
464   
465    would create user jerome and give him ten credits to spend
466    on any printer.
467   
468Finally create print quota entries :
469
470    $ edpykota --add --printer hp2100 john paul george ringo
471       
472    This will create print quota entries for The Beatles on   
473    printer hp2100. The print quota entry holds the number of
474    pages printed on a particular printer for a particular
475    user, as well as optional page limits to be used instead
476    of balance limits. See pkusers and edpykota's manual
477    pages for details.
478   
479Your users now should be able to print but not exceed their
480printing quota.
481
482To see printer quota usage on printer hp2100, you can use :
483
484    $ repykota --printer hp2100
485   
486or :
487
488    $ repykota
489   
490    which will print quota usage for all users on all printers,
491    along with totals, if you are a PyKota Administator. If you are
492    a regular user, only your own quota report will be produced.
493   
494You can also use these commands :   
495
496    $ pkusers --list
497    $ edpykota --list
498   
499    $ pkusers --list john paul george ringo
500    $ edpykota --list --printer hp2100 john paul george ringo
501   
502Quota reports are also available remotely by using the CGI script
503printquota.cgi provided in the cgi-bin/ subdirectory. You can
504also use the CSS stylesheet present in the stylesheets/ subdirectory
505and put it at your web server's DocumentRoot, to benefit from a nicer
506look, especially quota violations will appear in different colors.
507
508For additionnal security concerns, please give a look at the SECURITY
509file which is part of this software.
510
511To diagnose a problem when something doesn't work as expected,
512please read this FAQ entry :
513
514  http://otrs.librelogiciel.com/otrs/public.pl?ID=2
515           
516============================================================
517
518Additionnal tools :
519-------------------
520
521Some people have developped tools around PyKota, and make
522them available under the GNU General Public License :
523
524  - Kanakorn Horsiritham developped phpPykotaAdmin which is
525    a web based database independant administrative GUI,
526    written in PHP.
527 
528      http://opensource.psu.ac.th/~kanakorn/mambo/
529     
530    He was also kind enough to write an installation guide 
531    in english for CUPS and PyKota with phpPykotaAdmin on Fedora
532    Core 3. You'll find this document on the same website.
533   
534    This great software currently at version 0.3 is a wonderful
535    basis for an administrative GUI since it only depends on
536    PyKota commands to be present to successfully manage
537    PyKota's database.
538   
539    However this tool is very old now and doesn't work
540    with more recent versions of PyKota. It could be
541    a good starting point if you planned to develop such
542    a web user interface though.
543 
544Additionnal software will be listed here when they will be 
545ready.
546
547============================================================
548
549Mailing list :
550--------------
551
552  A mailing list is dedicated to Pykota, you can subscribe to it
553  or consult its archives at :
554 
555    http://cgi.librelogiciel.com/mailman/listinfo/pykota
556   
557  The mailing list is the preferred way to obtain support, because 
558  all members can help and can also benefit from the solutions
559  proposed by other members.
560 
561  Posts by non-members are usually rejected.
562 
563  The mailing list language is english and only english.
564   
565IRC :   
566-----
567
568  You can also chat with us :
569 
570        /server irc.freenode.net
571        /join #pykota
572       
573  Preferred language on this channel is english, but french     
574  is also accepted. Try to avoid exposing complex problems
575  in french because english speaking people on the channel
576  wouldn't benefit from the solutions.
577 
578  PyKota's main author is known as 'tamere' on IRC.
579   
580============================================================
581   
582Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
583or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.