root / pykota / trunk / README @ 3513

Revision 3506, 19.0 kB (checked in by jerome, 15 years ago)

Removed all support for pysnmp v3.x
Applied the patch from Ilya Etingof and Börje Sennung to fix #47.

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