root / pykota / trunk / README @ 3259

Revision 3259, 21.1 kB (checked in by jerome, 17 years ago)

Began work on moving from GNU GPL v2 or later to GNU GPL v3 or later.
TODO : Also move command line tools and library.
TODO : Change documentation from SGML DocBook? to XML DocBook? to
TODO : accomodate the GNU GPL v3 text available in DocBook? XML
TODO : from www.gnu.org

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