root / pykota / trunk / README @ 3086

Revision 3081, 19.5 kB (checked in by jerome, 18 years ago)

Improved documentation.

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