root / pykota / branches / specialauth / README @ 3241

Revision 3152, 21.1 kB (checked in by jerome, 18 years ago)

Last test.

  • 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, 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 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 three (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 internal
40    pages counter.
41    This is done both at the beginning and at the end of a
42    print job. The counters difference is then 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. PyKota by default internally
50    uses the code from pkpgcounter which can handle
51    several Page Description Languages : DSC compliant and binary PostScript,
52    PDF, PCLXL (aka PCL6), PCL3/4/5, ESC/P2, DVI, TIFF, OpenDocument,
53    Zenographics ZjStream, Samsung QPDL,Samsung SPL1, 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.2 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
280   
281and follow the instructions to install PyKota in interactive mode, then
282skip the remaining of the section below.
283
284Otherwise, you have to setup manually :
285
286Create a system user for PyKota :
287
288    $ adduser --system --group --home /etc/pykota --gecos PyKota pykota
289   
290Put the user your printing system is run as in the pykota system group :
291
292    $ adduser lp pykota
293   
294    NB : on our system, the CUPS printing system runs as system user 'lp'.
295    Please adapt this to your own system.
296
297Go to the initscripts/ subdirectory of PyKota's sources, and choose
298the appropriate storage backend for your configuration. Read carefully
299the associated README file, modify the initialization script to
300change the passwords, or, in the case of the LDAP backend, adapt it
301to your own LDAP DIT, and execute the initialization script
302to create an empty PyKota database. Upgrade scripts may be
303provided as well. NB : if you use PostgreSQL, a good way to
304make PyKota work first time is to modify PostgreSQL's pg_hba.conf
305to allow the 'trust' database connection mode. However once PyKota
306works it is HIGHLY RECOMMENDED TO CHANGE THIS TO A MORE SECURE
307VALUE. Look at the SECURITY document, PyKota's Official documentation
308and PostgreSQL's documentation for details on this subject.
309
310Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
311sample configuration files to ~pykota/pykota.conf and
312~pykota/pykotadmin.conf 
313The installation script usually copies these files into /usr/share/pykota
314
315NB : You can move PyKota's configuration files elsewhere, they will
316be searched first in user pykota's home directory, then in /etc/pykota.
317
318You need to adapt these files to your own needs. Especially you may
319have to create sections named after your own printers, and change
320the administrator's email address which by default is
321root@localhost. Read and try to understand these two very well
322commented files, so that you'll encounter less problems later.
323
324The rest of the installation depends on your printing system :
325
326  - CUPS Printing System :
327 
328    Once and for all :
329   
330        Create a symbolic link to the cupspykota backend
331        in CUPS's backend directory :
332       
333          $ cd /usr/lib/cups/backend
334          $ ln -s /usr/share/pykota/cupspykota cupspykota
335         
336        If you use CUPS v1.2 or higher, please do this as well : 
337       
338          $ chmod 700 /usr/share/pykota/cupspykota
339         
340          This allows the cupspykota backend to support other
341          backends which must be run as user root, like the
342          lpd backend for example.
343         
344        Restart CUPS so that the new backend can be detected.
345       
346          $ /etc/init.d/cupsys restart
347         
348          for example under Debian, or any similar command depending
349          on your operating system of choice.
350         
351    For new printers :
352   
353        Go to CUPS management interface (http://localhost:631)
354        and choose the appropriate PyKota managed device depending
355        on the type of printer you use. For example, if your
356        printer is waiting on :
357       
358            socket://myprinter.example.com:9100
359           
360        Then choose :   
361       
362            cupspykota:socket://myprinter.example.com:9100
363           
364        Configure your printer as usual.   
365       
366        Now double check /etc/pykota/pykota.conf
367       
368        You should manually create a section named after the
369        printer you've just added, unless you have set
370        all options globally.
371       
372        The new pkturnkey command can help you with correct settings
373        for your printers. To have pkturnkey give you some hints
374        about what to put into pykota.conf for a particular
375        print queue, just use its --doconf command line switch :
376       
377          $ pkturnkey --doconf TheNameOfThePrintQueue
378       
379        pkturnkey will try to tell you what is the best accounting
380        method for each printer and will print some lines you'll
381        just have to copy&paste in the appropriate sections in
382        /etc/pykota/pykota.conf
383       
384        For more informations about what pkturnkey can do for you,
385        see pkturnkey's manual page or use the --help command
386        line switch :
387       
388          $ pkturnkey --help | less
389       
390        That's all.
391   
392    For existing print queues :
393   
394        You want to route the print queue through PyKota,
395        and you can do this in several manners.
396       
397          $ pkprinters --add --cups TheNameOfThePrintQueue
398         
399        or   
400       
401          if your printer's DeviceURI is something like :
402         
403              socket://myprinter.example.com:9100
404             
405          then you can do this :   
406         
407          $ pkprinters --add TheNameOfThePrintQueue
408          $ lpadmin -p TheNameOfThePrintQueue \
409                    -v cupspykota://socket://myprinter.example.com:9100
410         
411        Finally, you could do it manually by modifying the
412        the DeviceURI lines in /etc/cups/printers.conf :
413        You would have to preprend 'cupspykota://' in front
414        of what is already on these lines. For example, replace :
415   
416            DeviceURI socket://myprinter.example.com:9100
417       
418        with :   
419   
420            DeviceURI cupspykota://socket://myprinter.example.com:9100
421           
422        or :   
423       
424            DeviceURI cupspykota://socket://myprinter.example.com:9100
425       
426        Save the file and restart CUPS for the changes to take effect.
427       
428        Here too, you may find it interesting to use the pkturnkey command as
429        described above to help with manual configuration of the file
430        /etc/pykota/pykota.conf
431
432  - LPRng Printing System :
433 
434    IMPORTANT : This release of PyKota DOES NOT support LPRng.
435   
436    If you want to use PyKota with LPRng, you have to download
437    an earlier release of PyKota, for example v1.22HotFix1.
438       
439Now you can begin to populate the PyKota's database with printers,
440users and groups :
441 
442Add printers and users to the quota system and set their quota values :
443
444You can either use pkturnkey, or do the same things manually by
445using the pkprinters, pkusers and edpykota command line tools :
446
447Create printers :
448
449    $ pkprinters --help
450   
451    will tell you how to create, manage or delete printers and
452    printers groups.
453   
454    $ pkprinters --add --charge 0.05 hp2100
455   
456    would add the printer named hp2100 with a price per page
457    of 0.05 unit.
458
459Create users :
460
461    $ pkusers --add --limitby balance --balance 10.0 jerome
462   
463    would create user jerome and give him ten credits to spend
464    on any printer.
465   
466Finally create print quota entries :
467
468    $ edpykota --add --printer hp2100 john paul george ringo
469       
470    This will create print quota entries for The Beatles on   
471    printer hp2100. The print quota entry holds the number of
472    pages printed on a particular printer for a particular
473    user, as well as optional page limits to be used instead
474    of balance limits. See pkusers and edpykota's manual
475    pages for details.
476   
477Your users now should be able to print but not exceed their
478printing quota.
479
480To see printer quota usage on printer hp2100, you can use :
481
482    $ repykota --printer hp2100
483   
484or :
485
486    $ repykota
487   
488    which will print quota usage for all users on all printers,
489    along with totals, if you are a PyKota Administator. If you are
490    a regular user, only your own quota report will be produced.
491   
492You can also use these commands :   
493
494    $ pkusers --list
495    $ edpykota --list
496   
497    $ pkusers --list john paul george ringo
498    $ edpykota --list --printer hp2100 john paul george ringo
499   
500Quota reports are also available remotely by using the CGI script
501printquota.cgi provided in the cgi-bin/ subdirectory. You can
502also use the CSS stylesheet present in the stylesheets/ subdirectory
503and put it at your web server's DocumentRoot, to benefit from a nicer
504look, especially quota violations will appear in different colors.
505
506For additionnal security concerns, please give a look at the SECURITY
507file which is part of this software.
508
509To diagnose a problem when something doesn't work as expected,
510please read this FAQ entry :
511
512  http://otrs.librelogiciel.com/otrs/public.pl?ID=2
513           
514============================================================
515
516Additionnal tools :
517-------------------
518
519Some people have developped tools around PyKota, and make
520them available under the GNU General Public License :
521
522  - Kanakorn Horsiritham developped phpPykotaAdmin which is
523    a web based database independant administrative GUI,
524    written in PHP.
525 
526      http://opensource.psu.ac.th/~kanakorn/mambo/
527     
528    He was also kind enough to write an installation guide 
529    in english for CUPS and PyKota with phpPykotaAdmin on Fedora
530    Core 3. You'll find this document on the same website.
531   
532    This great software currently at version 0.3 is a wonderful
533    basis for an administrative GUI since it only depends on
534    PyKota commands to be present to successfully manage
535    PyKota's database.
536   
537    However this tool is very old now and doesn't work
538    with more recent versions of PyKota. It could be
539    a good starting point if you planned to develop such
540    a web user interface though.
541 
542Additionnal software will be listed here when they will be 
543ready.
544
545============================================================
546
547Mailing list :
548--------------
549
550  A mailing list is dedicated to Pykota, you can subscribe to it
551  or consult its archives at :
552 
553    http://cgi.librelogiciel.com/mailman/listinfo/pykota
554   
555  The mailing list is the preferred way to obtain support, because 
556  all members can help and can also benefit from the solutions
557  proposed by other members.
558 
559  Posts by non-members are usually rejected.
560 
561  The mailing list language is english and only english.
562   
563IRC :   
564-----
565
566  You can also chat with us :
567 
568        /server irc.freenode.net
569        /join #pykota
570       
571  Preferred language on this channel is english, but french     
572  is also accepted. Try to avoid exposing complex problems
573  in french because english speaking people on the channel
574  wouldn't benefit from the solutions.
575 
576  PyKota's main author is known as 'tamere' on IRC.
577   
578============================================================
579   
580Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
581or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.