root / pykota / branches / 1.26_fixes / README

Revision 3572, 19.6 kB (checked in by jerome, 11 years ago)

Removed a remaining reference to psyco

  • 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.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  You may also benefit from having the following tools installed to
185  deal with some printers :
186
187    - npadmin
188    - netcat
189    - ghostscript
190
191  You need to have the following tools installed on the database
192  server :
193
194    - PostgreSQL (http://www.postgresql.org)
195
196  or
197
198    - OpenLDAP, or any other LDAP server (http://www.openldap.org)
199
200  or
201
202    - SQLite, v3.2.7 or higher (http://www.sqlite.org).
203      Beware : with SQLite the database server and the print
204      servers MUST be the very same machine.
205
206  or
207
208    - MySQL 4.1 or higher. 5.x is recommended.
209
210  This list of prerequisite software may change in the future, when
211  PyKota will support more functionnalities you will be given
212  alternatives.
213
214  Of course the Print Server and the database server can be the
215  very same machine if you've got a tiny network, or you can have
216  multiple Print Servers all storing their quotas on the same database
217  server if you've got a bigger network. (NB : with SQLite, the database
218  can't be shared between several print servers)
219
220Hint :
221------
222
223  - The Debian GNU/Linux distribution is to our knowledge the
224    easiest distribution to install PyKota on, because almost all
225    of PyKota dependencies are already included, excepted
226    the pkpgcounter utility which for now have to be downloaded
227    and installed separately, and maybe one or two other dependencies,
228    depending on the version of Debian you are using.
229    We recommend you to use Debian's Etch distribution or
230    more recent. PyKota works fine on Sarge, but some additional
231    dependencies are missing in Sarge and have to be installed
232    manually.
233
234Then :
235------
236
237Download the latest PyKota version from the Subversion tree :
238
239    $ svn co svn://svn.librelogiciel.com/pykota/trunk pykota
240
241You can now check if the dependencies are correct by typing :
242
243    $ python checkdeps.py
244
245    An availability report for all the software needed by PyKota
246    will be displayed : you'll have to install the missing
247    software if you want PyKota to work correctly.
248
249To install the software, just type :
250
251    $ python setup.py install
252
253You may need to be logged in with sufficient privileges (e.g. root)
254
255If you use Debian or Ubuntu, and want to use PostgreSQL as the
256database backend, just type :
257
258    $ pksetup debian
259
260or :
261
262    $ pksetup ubuntu
263
264and follow the instructions to install PyKota in interactive mode, then
265skip the remaining of the section below.
266
267Otherwise, you have to setup manually :
268
269Create a system user for PyKota :
270
271    $ adduser --system --group --home /etc/pykota --gecos PyKota pykota
272
273Put the user your printing system is run as in the pykota system group :
274
275    $ adduser lp pykota
276
277    NB : on our system, the CUPS printing system runs as system user 'lp'.
278    Please adapt this to your own system.
279
280Go to the initscripts/ subdirectory of PyKota's sources, and choose
281the appropriate storage backend for your configuration. Read carefully
282the associated README file, modify the initialization script to
283change the passwords, or, in the case of the LDAP backend, adapt it
284to your own LDAP DIT, and execute the initialization script
285to create an empty PyKota database. Upgrade scripts may be
286provided as well. NB : if you use PostgreSQL, a good way to
287make PyKota work first time is to modify PostgreSQL's pg_hba.conf
288to allow the 'trust' database connection mode. However once PyKota
289works it is HIGHLY RECOMMENDED TO CHANGE THIS TO A MORE SECURE
290VALUE. Look at the SECURITY document, PyKota's Official documentation
291and PostgreSQL's documentation for details on this subject.
292
293Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
294sample configuration files to ~pykota/pykota.conf and
295~pykota/pykotadmin.conf
296The installation script usually copies these files into /usr/share/pykota
297
298NB : You can move PyKota's configuration files elsewhere, they will
299be searched first in user pykota's home directory, then in /etc/pykota.
300
301You need to adapt these files to your own needs. Especially you may
302have to create sections named after your own printers, and change
303the administrator's email address which by default is
304root@localhost. Read and try to understand these two very well
305commented files, so that you'll encounter less problems later.
306
307The rest of the installation depends on your printing system :
308
309  - CUPS Printing System :
310
311    Once and for all :
312
313        Create a symbolic link to the cupspykota backend
314        in CUPS's backend directory :
315
316          $ cd /usr/lib/cups/backend
317          $ ln -s /usr/share/pykota/cupspykota cupspykota
318
319        If you use CUPS v1.2 or higher, please do this as well :
320
321          $ chmod 700 /usr/share/pykota/cupspykota
322
323          This allows the cupspykota backend to support other
324          backends which must be run as user root, like the
325          lpd backend for example.
326
327        Restart CUPS so that the new backend can be detected.
328
329          $ /etc/init.d/cupsys restart
330
331          for example under Debian, or any similar command depending
332          on your operating system of choice.
333
334    For new printers :
335
336        Go to CUPS management interface (http://localhost:631)
337        and choose the appropriate PyKota managed device depending
338        on the type of printer you use. For example, if your
339        printer is waiting on :
340
341            socket://myprinter.example.com:9100
342
343        Then choose :
344
345            cupspykota:socket://myprinter.example.com:9100
346
347        Configure your printer as usual.
348
349        Now double check /etc/pykota/pykota.conf
350
351        You should manually create a section named after the
352        printer you've just added, unless you have set
353        all options globally.
354
355        The new pkturnkey command can help you with correct settings
356        for your printers. To have pkturnkey give you some hints
357        about what to put into pykota.conf for a particular
358        print queue, just use its --doconf command line switch :
359
360          $ pkturnkey --doconf TheNameOfThePrintQueue
361
362        pkturnkey will try to tell you what is the best accounting
363        method for each printer and will print some lines you'll
364        just have to copy&paste in the appropriate sections in
365        /etc/pykota/pykota.conf
366
367        For more informations about what pkturnkey can do for you,
368        see pkturnkey's manual page or use the --help command
369        line switch :
370
371          $ pkturnkey --help | less
372
373        That's all.
374
375    For existing print queues :
376
377        You want to route the print queue through PyKota,
378        and you can do this in several manners.
379
380          $ pkprinters --add --cups TheNameOfThePrintQueue
381
382        or
383
384          if your printer's DeviceURI is something like :
385
386              socket://myprinter.example.com:9100
387
388          then you can do this :
389
390          $ pkprinters --add TheNameOfThePrintQueue
391          $ lpadmin -p TheNameOfThePrintQueue \
392                    -v cupspykota://socket://myprinter.example.com:9100
393
394        Finally, you could do it manually by modifying the
395        the DeviceURI lines in /etc/cups/printers.conf :
396        You would have to preprend 'cupspykota://' in front
397        of what is already on these lines. For example, replace :
398
399            DeviceURI socket://myprinter.example.com:9100
400
401        with :
402
403            DeviceURI cupspykota://socket://myprinter.example.com:9100
404
405        or :
406
407            DeviceURI cupspykota://socket://myprinter.example.com:9100
408
409        Save the file and restart CUPS for the changes to take effect.
410
411        Here too, you may find it interesting to use the pkturnkey command as
412        described above to help with manual configuration of the file
413        /etc/pykota/pykota.conf
414
415  - LPRng Printing System :
416
417    IMPORTANT : This release of PyKota DOES NOT support LPRng.
418
419    If you want to use PyKota with LPRng, you have to download
420    an earlier release of PyKota, for example v1.22HotFix1.
421
422Now you can begin to populate the PyKota's database with printers,
423users and groups :
424
425Add printers and users to the quota system and set their quota values :
426
427You can either use pkturnkey, or do the same things manually by
428using the pkprinters, pkusers and edpykota command line tools :
429
430Create printers :
431
432    $ pkprinters --help
433
434    will tell you how to create, manage or delete printers and
435    printers groups.
436
437    $ pkprinters --add --charge 0.05 hp2100
438
439    would add the printer named hp2100 with a price per page
440    of 0.05 unit.
441
442Create users :
443
444    $ pkusers --add --limitby balance --balance 10.0 jerome
445
446    would create user jerome and give him ten credits to spend
447    on any printer.
448
449Finally create print quota entries :
450
451    $ edpykota --add --printer hp2100 john paul george ringo
452
453    This will create print quota entries for The Beatles on
454    printer hp2100. The print quota entry holds the number of
455    pages printed on a particular printer for a particular
456    user, as well as optional page limits to be used instead
457    of balance limits. See pkusers and edpykota's manual
458    pages for details.
459
460Your users now should be able to print but not exceed their
461printing quota.
462
463To see printer quota usage on printer hp2100, you can use :
464
465    $ repykota --printer hp2100
466
467or :
468
469    $ repykota
470
471    which will print quota usage for all users on all printers,
472    along with totals, if you are a PyKota Administator. If you are
473    a regular user, only your own quota report will be produced.
474
475You can also use these commands :
476
477    $ pkusers --list
478    $ edpykota --list
479
480    $ pkusers --list john paul george ringo
481    $ edpykota --list --printer hp2100 john paul george ringo
482
483Quota reports are also available remotely by using the CGI script
484printquota.cgi provided in the cgi-bin/ subdirectory. You can
485also use the CSS stylesheet present in the stylesheets/ subdirectory
486and put it at your web server's DocumentRoot, to benefit from a nicer
487look, especially quota violations will appear in different colors.
488
489For additionnal security concerns, please give a look at the SECURITY
490file which is part of this software.
491
492To diagnose a problem when something doesn't work as expected,
493please read this FAQ entry :
494
495  http://otrs.librelogiciel.com/otrs/public.pl?ID=2
496
497============================================================
498
499Additionnal tools :
500-------------------
501
502Some people have developped tools around PyKota, and make
503them available under the GNU General Public License :
504
505  - Kanakorn Horsiritham developped phpPykotaAdmin which is
506    a web based database independant administrative GUI,
507    written in PHP.
508
509      http://opensource.psu.ac.th/~kanakorn/mambo/
510
511    He was also kind enough to write an installation guide
512    in english for CUPS and PyKota with phpPykotaAdmin on Fedora
513    Core 3. You'll find this document on the same website.
514
515    This great software currently at version 0.3 is a wonderful
516    basis for an administrative GUI since it only depends on
517    PyKota commands to be present to successfully manage
518    PyKota's database.
519
520    However this tool is very old now and doesn't work
521    with more recent versions of PyKota. It could be
522    a good starting point if you planned to develop such
523    a web user interface though.
524
525Additionnal software will be listed here when they will be
526ready.
527
528============================================================
529
530Mailing list :
531--------------
532
533  A mailing list is dedicated to Pykota, you can subscribe to it
534  or consult its archives at :
535
536    http://cgi.librelogiciel.com/mailman/listinfo/pykota
537
538  The mailing list is the preferred way to obtain support, because
539  all members can help and can also benefit from the solutions
540  proposed by other members.
541
542  Posts by non-members are usually rejected.
543
544  The mailing list language is english and only english.
545
546IRC :
547-----
548
549  You can also chat with us :
550
551        /server irc.freenode.net
552        /join #pykota
553
554  Preferred language on this channel is english, but french
555  is also accepted. Try to avoid exposing complex problems
556  in french because english speaking people on the channel
557  wouldn't benefit from the solutions.
558
559  PyKota's main author is known as 'tamere' on IRC.
560
561============================================================
562
563Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
564or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.