root / pykota / trunk / README @ 1935

Revision 1928, 21.1 kB (checked in by jalet, 20 years ago)

Added a note about banners

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1# $Id$
2
3PyKota - Print Quota for CUPS and LPRng
4
5(c) 2003-2004 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
19
20====================================================================
21
22READ SPECIAL LICENSING AND REDISTRIBUTION TERMS IN THE FILE 'LICENSE'
23
24====================================================================
25
26PyKota features :
27-----------------
28
29    Operating systems :
30   
31        - Any Unix-like system as print server.
32           
33        - Any operating system as client.
34           
35    Printing systems :
36   
37        - Supports both CUPS and LPRng as the printing system.
38       
39    Databases :
40   
41        - Supports PostgreSQL as the Quota Storage backend.
42          Complete database creation script in SQL is included.
43       
44        - Supports any LDAP server as the Quota Storage backend.
45          Complete LDAP schema and sample empty tree are included.
46          Plugging PyKota into your existing LDAP infrastructure
47          is really easy thanks to PyKota's great configurability.
48           
49    Printers :       
50   
51        - Hardware or Software accounting methods are completely
52          configurable.
53         
54        - Supports any printer which can report its internal
55          page counter. Can ask printers for their internal
56          page counter via SNMP, Netatalk, PJL, PS, or any
57          other way.
58          This is completely configurable.
59         
60        - Supports DSC compliant and binary PostScript, PDF, PCL5 (up to),
61          PCLXL (aka PCL6) and ESC/P2 printers natively for software
62          accounting methods. More formats to come.
63           
64    Quota systems :       
65   
66        - Supports printers and printers groups quotas.
67       
68        - Supports users and users groups quotas.
69       
70        - Supports page quotas.
71          Page quotas can be set differently on a per printer
72          and per user/group basis.
73       
74        - Supports account balance quotas in any currency.
75          Account balance quotas can be set on a per user
76          basis. The account balance is shared amongst
77          all printers. The history of payments (positive
78          or negative credits to an user account) is kept.
79         
80        - Page quotas and account balance can be set/reset
81          independantly.
82         
83        - Page quotas and account balances can be set on
84          a per user or per group basis.
85         
86        - Price per page and per job can be set differently 
87          on any printer.
88       
89        - Low level of page quota or account balance are
90          configurable.
91         
92        - Both soft and hard limit with configurable grace delay 
93          can be set for page quota.
94         
95        - Possibility to disable quota enforcement for any user
96          or group, while still keeping page accounting.
97         
98        - Starting and Ending personalized dynamic banners can be
99          generated on the fly, and accounted for or not, depending
100          on some configuration settings.
101          NB : Banners are a CUPS only feature for now.
102             
103    Administration :       
104   
105        - Powerful administration tools can be used to
106          automate setting or resetting of quotas or
107          account balances at specific intervals.
108         
109        - Administration tools can modify several users, 
110          groups, or printers at once.
111         
112        - Account balances can be set, incremented, or 
113          decremented. History of payments is kept.
114         
115        - Both printers and users can be automatically added on
116          first print in a completely configurable way.
117         
118        - Quota report generator available either from the 
119          command line or in any web browser.
120          The web-based quota report generator can be
121          user/password protected.
122         
123        - Print quote generator can tell users how much 
124          a print job will cost them in advance.
125         
126        - Policy with regard to unregistered users can   
127          be configured for each printer to either deny
128          printing, allow printing, or delegate the
129          decision to any external tool.
130         
131        - Warning and error messages can be automatically 
132          sent via email to the administrator, the user,
133          both, or none.
134         
135        - Warning and error messages' content is completely
136          configurable.
137         
138        - Configuration can be changed without needing to 
139          restart the printing system.
140       
141        - Complete print job history is kept. This can be
142          disabled if needed.
143         
144        - Automated low quota or balance remainder can be
145          scheduled regularly or launched manually.
146         
147        - Powerful data dumper to export datas to other
148          software (spreadsheets for example). Actually
149          supported formats are :
150         
151            - Comma separated values ;
152           
153            - Semicolon separated values ;
154           
155            - Tab separated values ;
156           
157            - XML.
158         
159    User Interface :         
160   
161        - All the command line tools accept the -h | --help
162          command line option which prints all the available
163          options and show usage examples.
164         
165        - Completely internationalized. Actually supports the 
166          English, French, Spanish, Portuguese, Brasilian, Swedish,
167          Thai, Greek, German, Italian and Norwegian (Bokm� languages.
168          More to come.
169
170====================================================================
171       
172Planned features are described in the TODO file.
173
174Actually two (or an infinity of) page accounting methods are
175implemented :
176
177  - The 'hardware' method consists in querying the printer (via SNMP
178    or Netatalk or any other method of your choice) for its total pages
179    counter.
180   
181    This is done both at the beginning and at the end of a
182    print job. The counters difference is then immediately used to
183    decrease the user's account balance or increase his quota usage.
184   
185  - The 'software' method consists in delegating the computation of the
186    job's size in number of pages to any external command of your choice.
187    The command can read the job's data from its standard input and MUST
188    output the job's size on its standard output. Changes to the user
189    account are reported immediately.
190   
191PyKota is known to work fine with most laser printers, either with
192software accounting, or with hardware accounting if the printer
193supports this.
194
195============================================================
196
197INSTALLATION:
198=============
199
200NB :
201====
202
203  You may learn more about PyKota, if it fits your own organization,
204  its internal working, and some potential performance drawbacks and
205  how to avoid them, in a WiKi administered by Ryan Suarez at :
206 
207    http://webcrossing.macosxlabs.org/webx?14@30.QAu3a5k0c4z.7@.26bf4661
208
209  You may also find the following document interesting :
210 
211    http://es.tldp.org/Tutoriales/doc-openldap-samba-cups-python/
212   
213  This document, written in Spanish by Sergio Gonzalez Gonzalez, 
214  describes the integration of PyKota into an OpenLDAP + Samba
215  + CUPS installation. Even for people who can't read spanish
216  this document is really interesting, and contains lots of
217  screenshots.
218 
219Prerequisite :
220--------------
221   
222  You need to have the following tools installed on the CUPS Server :
223 
224    - CUPS (http://www.cups.org) or LPRng (http://www.lprng.com)
225    - Python v2.1 or above (http://www.python.org)
226    - eGenix' mxDateTime Python extension (http://www.egenix.com)
227    - The JAXML Python module to be able to dump datas in the XML format.
228      (http://www.librelogiciel.com/software/)
229    - The Python-SNMP module to query printers for their page counter.
230      (http://pysnmp.sourceforge.net)
231    - The Python-OSD module to use the graphical print quota reminder.
232    - SNMP tools (specifically the snmpget command) if you prefer to
233      use your own script to request query printers.
234    - Netatalk (specifically the pap command) if you plan to
235      request your printer's lifetime page counter via AppleTalk.
236      (http://netatalk.sourceforge.net)
237    - The ReportLab Python module (http://www.reportlab.org) if you want 
238      to have PyKota generate nice banners for you.
239    - The Python Imaging Library (aka PIL) module
240      (http://www.pythonware.com/downloads) if you want to have PyKota
241      generate nice banners for you.
242    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
243      libraries if you plan to use PostgreSQL as the Quota Storage
244      backend.
245      (http://www.postgresql.org and http://www.pygreql.org)
246 or     
247    - python-ldap Python module and the OpenLDAP client libraries 
248      if you plan to use an LDAP server as the Quota Storage backend.
249      (http://www.openldap.org and http://python-ldap.sourceforge.net)
250   
251  On Intel i386 architecture, and for performance reasons, it is
252  strongly suggested that you install the Python accelerator Psyco,
253  available at :
254 
255      http://psyco.sourceforge.net
256     
257  Under Debian :   
258 
259      $ apt-get install python-psyco
260     
261  Other architectures may be supported as well in the future, check   
262  this on Psyco's website.
263 
264  Installing Psyco is not mandatory, but it will speedup PCL5 parsing
265  by almost 3 times. PostScript and PDF parsing can also benefit,
266  but in an almost unnoticeable manner since this part of the code
267  is already optimal. For PCL5 this is a completely different matter,
268  and if you install Psyco you will never regret it !
269  Same remark applies for PCL6 (aka PCLXL) : the parser is completely
270  different, but the performance gain with Psyco is impressive.
271 
272  You may also benefit from having the following tools installed to
273  deal with some printers :
274 
275    - npadmin
276    - netcat
277    - ghostscript
278   
279  You need to have the following tools installed on the Quota Storage 
280  Server :
281 
282    - PostgreSQL (http://www.postgresql.org)
283   
284  or 
285 
286    - OpenLDAP, or any other LDAP server (http://www.openldap.org)
287   
288NB :   
289
290  PygreSQL must be linked with the PostgreSQL client libraries on
291  the Print Server. The PostgreSQL client libraries' version must
292  match the PostgreSQL version used on the Quota Storage Server.
293 
294or 
295
296  python-ldap must be linked with the OpenLDAP client libraries on the
297  Print Server. The OpenLDAP client libraries' version should match the
298  OpenLDAP version used on the Quota Storage Server, if applicable.
299 
300  This list of prerequisite software may change in the future, when
301  PyKota will support more functionnalities you will be given
302  alternatives.
303 
304  Of course the Print Server and the Quota Storage Server can be the
305  very same machine if you've got a tiny network, or you can have
306  multiple Print Servers all storing their quotas on the same Quota
307  Storage Server if you've got a bigger network.
308 
309Hint : 
310------
311
312  - The Debian GNU/Linux distribution is to our knowledge the
313    easiest distribution to install PyKota on, because all
314    of PyKota dependencies are already included, excepted
315    for the PySNMP (http://pysnmp.sourceforge.net) module
316    which for now has to be downloaded separately.
317
318Then :   
319------
320 
321Download the latest PyKota version from the CVS tree on :
322
323    http://savannah.nongnu.org/projects/pykota
324
325You can now check if the dependencies are correct by typing :
326
327    python checkdeps.py
328   
329To install the software, just type :
330
331    python setup.py install
332
333You may need to be logged in with sufficient privileges (e.g. root)
334
335Go to the initscripts subdirectory of PyKota's sources, and choose
336the appropriate storage backend for your configuration. Read carefully
337the associated README file and execute the initialization script
338to create an empty PyKota Storage. Upgrade scripts may be
339provided as well.
340
341Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
342sample configuration files to /etc/pykota/pykota.conf and
343/etc/pykota/pykotadmin.conf 
344The installation script usually copies these files into /usr/share/pykota
345
346You need to adapt these files to your own needs. Especially you may
347have to create sections named after your own printers, and change
348the administrator's email address which by default is
349root@localhost. Read and try to understand these two very well
350commented files, so that you'll encounter less problems later.
351
352Also be sure to double check that commands that query printers
353for their internal page counter work from the command line
354before using them in PyKota's configuration.
355
356The rest of the installation depends on your printing system :
357
358  - CUPS Printing System :
359 
360    Once and for all :
361   
362        Create a symbolic link to the cupspykota backend
363        in CUPS's backend directory :
364       
365          $ cd /usr/lib/cups/backend
366          $ ln -s /usr/share/pykota/cupspykota cupspykota
367         
368        Restart CUPS so that the new backend can be detected.
369       
370          $ /etc/init.d/cupsys restart
371         
372        or :   
373     
374          $ /etc/rc.d/init.d/cupsysrestart
375         
376        or any similar command depending on your operating system. 
377         
378    For new printers :
379   
380        Go to CUPS management interface (http://localhost:631)
381        and choose the appropriate PyKota managed device depending
382        on the type of printer you use. For example, if your
383        printer is waiting on :
384       
385            socket://myprinter.example.com:9100
386           
387        Then choose :   
388       
389            cupspykota:socket://myprinter.example.com:9100
390           
391        Configure your printer as usual.   
392       
393        Now double check /etc/pykota/pykota.conf
394       
395        You should manually create a section named after the
396        printer you've just added, unless you have set
397        all options globally.
398       
399        The new pkhint command can help you with correct settings
400        for your printers, but don't rely on it because it is still
401        experimental work. To use pkhint, you have to feed it with
402        CUPS' printers.conf file this way :
403       
404          $ pkhint </etc/cups/printers.conf
405       
406        pkhint will try to tell you what is the best accounting
407        method for each printer and will print some lines you'll
408        just have to copy&paste in the appropriate sections in
409        /etc/pykota/pykota.conf
410       
411        That's all.
412   
413    For existing printers :
414   
415        If you had already installed a version of PyKota earlier
416        than 1.16alpha7, then remove the *cupsFilter lines in your
417        PPD files for each printer already managed printers. Each
418        line to remove is of the form :
419       
420          *cupsFilter: "application/vnd.cups-postscript 0 /usr/share/pykota/pykota"
421       
422        This means that each time the pstops filter will be executed, it will
423        pass the job's data through the pykota filter which is present in
424        /usr/share/pykota
425       
426        Don't touch anything else, especially any other *cupsFilter line.
427        Then save each of these files.
428       
429        Then, the easiest is to directly modify the DeviceURI lines
430        in /etc/cups/printers.conf, you just have to put
431        'cupspykota:' in front of what is already on these lines.
432        For example, replace :
433   
434            DeviceURI socket://myprinter.example.com:9100
435       
436        with :   
437   
438            DeviceURI cupspykota:socket://myprinter.example.com:9100
439           
440        or :   
441       
442            DeviceURI cupspykota://socket://myprinter.example.com:9100
443       
444        Save the file and restart CUPS.
445       
446        Here too, you may find it interesting to use the pkhint command as
447        described above to help with manual configuration of the file
448        /etc/pykota/pykota.conf
449
450  - LPRng Printing System :
451 
452    For each printer on which you want to use PyKota :
453   
454        Modify the printer's entry in /etc/printcap : you have to add
455        the three following lines :
456       
457          :achk=true:\
458          :as=/usr/share/pykota/lprngpykota:\
459          :ae=/usr/share/pykota/lprngpykota:\
460         
461        This will tell LPRng to activate accounting, and use the lprngpykota
462        accounting filter both at the start and at the end of printing.
463       
464    When all modifications are done, just save the /etc/printcap file and   
465    restart LPRng :
466   
467          $ /etc/init.d/lprng restart
468         
469        or :   
470     
471          $ /etc/rc.d/init.d/lprng restart
472         
473        or any similar command depending on your operating system. 
474       
475    NB : the pkhint command can't be used with LPRng for now, so you   
476         have to modify /etc/pykota/pykota.conf carefully. The comments
477         in this file will help you.
478     
479Now you can begin to populate the PyKota's database with printers,
480users and groups :
481 
482Add printers and users to the quota system and set their quota values :
483
484Starting from version 1.18alpha2, the preferred command to manage
485printers is named pkprinters
486
487    $ pkprinters --help
488   
489    will tell you how to create, manage or delete printers and
490    printers groups.
491   
492    $ pkprinters --add --charge 0.05 hp2100
493   
494    would add the printer named hp2100 with a price per page
495    of 0.05 unit.
496
497Now set quotas for users on this printer :     
498
499    $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN
500       
501    launching edpykota without any argument or with the --help
502    command line option will show you all the possibilities.
503   
504    by default, each user is limited by "quota", this means that on
505    each printer he can have a different soft and hard limit.
506    You may want to limit the user by his account balance value,
507    in which case, the print quota is shared between all printers
508    instead of being different. To do this, use the following :
509   
510    $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN
511   
512    This will put 10 $ (or Euros, PyKota doesn't care) on each user's account
513    balance, and tell PyKota to limit them by their account balance value.
514    Whenever they print on any printer, their account balance value is
515    decreased by an amount which depends on the particular price per page
516    and per job that you may have defined on the printer with edpykota's
517    --charge command line option.
518    Soft and Hard limits are not used if "--limitby balance" is used,
519    but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf
520    to obtain a similar result (warning message when quota is low).
521
522Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
523
524    $ /etc/init.d/cupsys restart
525   
526  or :
527 
528    $ /etc/init.d/lprng restart
529       
530Your users now should be able to print but not exceed their
531printing quota.
532
533To see printer quota usage, you can use :
534
535    $ repykota --printer lp
536   
537or :
538
539    $ repykota
540   
541    which will print quota usage for all users on all printers,
542    along with totals, if you are the root user. If you are
543    a regular user, only your own quota report will be produced.
544   
545Quota reports are also available remotely by using the CGI script
546printquota.cgi provided in the cgi-bin/ subdirectory. You can
547also use the CSS stylesheet present in the stylesheets/ subdirectory
548and put it at your web server's DocumentRoot, to benefit from a nicer
549look, especially quota violations will appear in different colors.
550
551For different security concerns, please give a look at the SECURITY
552file which is part of this software.
553           
554============================================================
555
556Mailing list :
557--------------
558
559  A mailing list is dedicated to Pykota, you can subscribe to it
560  or consult its archives at :
561 
562    http://cgi.librelogiciel.com/mailman/listinfo/pykota
563   
564  The mailing list is the preferred way to obtain support, because 
565  all members can help and can also benefit from the solutions
566  proposed by other members.
567 
568  Posts by non-members are usually rejected.
569 
570  The mailing list language is english and only english.
571   
572IRC :   
573-----
574
575  You can also chat with us :
576 
577        /server irc.freenode.net
578        /join #pykota
579       
580  Preferred language on this channel is english, but french     
581  is also accepted. Try to avoid exposing complex problems
582  in french because english speaking people on the channel
583  wouldn't benefit from the solutions.
584 
585  PyKota's main author is known as 'tamere' on IRC.
586   
587============================================================
588   
589Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
590or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.