root / pykota / trunk / README @ 1603

Revision 1603, 19.3 kB (checked in by jalet, 20 years ago)

Rewording

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