root / pykota / trunk / README @ 1823

Revision 1823, 19.9 kB (checked in by jalet, 20 years ago)

Replaced 'OpenLDAP' with 'any LDAP server'

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