root / pykota / trunk / README @ 1907

Revision 1906, 20.6 kB (checked in by jalet, 20 years ago)

Changes to the installation documentation

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