root / pykota / trunk / README @ 3373

Revision 3373, 21.2 kB (checked in by anonymous, 14 years ago)

just a test.

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