root / pykota / trunk / README @ 1156

Revision 1155, 13.9 kB (checked in by jalet, 21 years ago)

Forgotten message

  • 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 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 CUPS as the printing system.
38       
39        - Supports LPRng as the printing system.
40           
41    Databases :
42   
43        - Supports PostgreSQL as the Quota Storage backend.
44          Complete database creation SQL script is included.
45       
46        - Supports OpenLDAP as the Quota Storage backend.
47          Complete LDAP schema and sample tree are included.
48           
49    Printers :       
50   
51        - Supports any printer which can report its internal
52          page counter.
53         
54        - Supports any other printer via GhostScript.
55       
56        - Can ask printers for their internal page counter
57          via SNMP, Netatalk, or any other mean of your
58          choice. This is completely configurable.
59         
60        - External accounting methods are configurable 
61           
62    Quota systems :       
63   
64        - Supports user and groups quotas.
65       
66        - Supports page quotas.
67          Page quotas can be set differently on a per printer
68          and per user/group basis.
69       
70        - Supports account balance quotas in any currency.
71          Account balance quotas can be set on a per user
72          basis. The account balance is shared amongst
73          all printers.
74         
75        - Experimental support for printer groups, so that
76          you can share quota between printers of the same
77          type but in different locations.
78         
79        - Page quota and account balance can be set/reset
80          independantly.
81         
82        - Limiting factor, page quota or account balance, 
83          can be set on a per user or per group basis.
84         
85        - Price per page and per job can be set differently 
86          on any printer.
87       
88        - Low level of page quota or account balance are
89          configurable.
90         
91        - Both soft and hard limit with configurable grace delay 
92          can be set for page quota.
93         
94        - Possibility to disable quota enforcement for any user
95          or group, while still keeping page accounting.
96             
97    Administration :       
98   
99        - Powerful administration tools can be used to
100          automate setting or resetting of quotas or
101          account balances at specific intervals.
102         
103        - Administration tools can modify several users, 
104          groups, or printers at once.
105         
106        - Account balances can be set, incremented, or 
107          decremented.
108         
109        - Users can be automatically added on first print 
110          in a completely configurable way.
111         
112        - Quota report generator available either from the 
113          command line or in any web browser.
114          The web-based quota report generator can be
115          user/password protected.
116         
117        - Print quote generator can tell users how much 
118          a print job will cost them in advance.
119         
120        - Policy with regard to unregistered users can   
121          be configured for each printer to either deny
122          printing, allow printing, or delegate the
123          decision to any external tool.
124         
125        - Warning and error messages can be automatically 
126          sent via email to the administrator, the user,
127          both, or none.
128         
129        - Warning and error messages' content is completely
130          configurable.
131         
132        - Configuration can be changed without needing to 
133          restart the printing system.
134       
135        - Complete print job history is kept. This can be
136          disabled if needed.
137         
138        - Automated low quota or balance remainder can be
139          scheduled regularly or launched manually.
140         
141    User Interface :         
142   
143        - All the command line tools accept the -h | --help
144          command line option which prints all the available
145          options and show usage examples.
146         
147        - Completely internationalized. Actually supports the 
148          English and French languages. More to come.
149
150====================================================================
151       
152Planned features are described in the TODO file.
153
154Actually three (or an infinity of) page accounting methods are
155implemented :
156
157  - The 'querying' method consists in querying the printer (via SNMP
158    or Netatalk) for its total pages counter, just before the beginning
159    of a job, and use this to modify the *preceding* user's quota. So
160    you're always late of one print job, but this is generally ok,
161    especially because a check is also done to see if the current user
162    is allowed or not to print. You're not limited to SNMP or Netatalk,
163    because you can also use any external command instead if you want.
164   
165  - The 'external' method consists in delegating the computation of the
166    job's size in number of pages to any external command of your choice.
167    The command can read the job's data from its standard input and MUST
168    output the job's size on its standard output.
169   
170  - The 'stupid' method consists in counting the 'showpage' PostSript 
171    statements in the job. THIS IS UNRELIABLE, but can serve as an
172    example if you plan to write your own accounting method for
173    integration into PyKota.
174 
175PyKota is known to work fine with HP Laserjet 2100 and 2200, and
176Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under
177Debian GNU/Linux (Sarge and Sid) operating systems.
178
179I'm interested in receiving success or failure reports with other
180brands or models of printers, as well as with other operating
181systems.
182
183============================================================
184
185INSTALLATION:
186=============
187
188WARNING :
189=========
190
191  If you run a PyKota version lower than 1.03, you definitely have to
192  upgrade you Quota Storage Database. Please read the documentation
193  included in the initscripts subdirectory first !
194 
195  Users of MacOS-X may find the following tutorial useful :
196
197      http://ell-tech.com/pages/pykota.php
198
199Prerequisite :
200--------------
201   
202  You need to have the following tools installed on the CUPS Server :
203 
204    - CUPS or LPRng
205    - Python v2.1 or above
206    - eGenix' mxDateTime Python extension
207    - SNMP tools (specifically the snmpget command) if you plan to
208      request your printer's lifetime page counter via SNMP.
209    - Netatalk (specifically the pap command) if you plan to
210      request your printer's lifetime page counter via AppleTalk.
211    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
212      libraries if you plan to use PostgreSQL as the Quota Storage
213      backend.
214 or     
215    - python-ldap Python module and the OpenLDAP client libraries 
216      if you plan to use OpenLDAP as the Quota Storage backend.
217   
218  You need to have the following tools installed on the Quota Storage 
219  Server :
220 
221    - PostgreSQL
222   
223  or 
224 
225    - OpenLDAP
226   
227NB :   
228
229  PygreSQL must be linked with the PostgreSQL client libraries on
230  the Print Server. The PostgreSQL client libraries' version must
231  match the PostgreSQL version used on the Quota Storage Server.
232 
233or 
234
235  python-ldap must be linked with the OpenLDAP client libraries on the
236  Print Server. The OpenLDAP client libraries' version must match the
237  OpenLDAP version used on the Quota Storage Server.
238 
239  This list of prerequisite software may change in the future, when
240  PyKota will support more functionnalities you will be given
241  alternatives.
242 
243  Of course the Print Server and the Quota Storage Server can be the
244  very same machine if you've got a tiny network, or you can have
245  multiple Print Servers all storing their quotas on the same Quota
246  Storage Server if you've got a bigger network.
247 
248Then :   
249------
250 
251Download the latest PyKota version from the CVS tree on :
252
253    http://savannah.nongnu.org/projects/pykota
254
255Just type :
256
257    python setup.py install
258
259You may need to be logged in with sufficient privileges (e.g. root)
260
261The installation script will now automatically check if some software
262is missing and ask you if you still want to proceed with the
263installation or abort it completely.
264
265Go to the initscripts subdirectory of PyKota's sources, and choose
266the appropriate storage backend for your configuration. Read
267the associated README file and execute the initialization script
268to create an empty PyKota Storage. Upgrade scripts may be
269provided as well.
270
271Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
272sample configuration files to /etc/pykota/pykota.conf and
273/etc/pykota/pykotadmin.conf. The installation script tries to do this
274for you if needed and you agreed to this action.
275You need to adapt these files to your own needs.
276Especially you have to create sections named after your own
277printers, and change the administrator's email address.
278
279  - CUPS Print Backend :
280 
281    Modify the PPD files for each printer on which you want to manage
282    print quotas, for example /etc/cups/ppd/lp.ppd :
283   
284    --- Add the line below exactly as-is somewhere near the top ---
285    *cupsFilter:  "application/vnd.cups-postscript 0 /usr/bin/pykota"
286    --- Add the line above exactly as-is somewhere near the top  ---
287   
288    Modify the path to the pykota executable if needed, unfortunately
289    you have to supply the correct absolute path here due to CUPS
290    internals, or put the pykota executable into /usr/lib/cups/filter
291    instead of into /usr/bin.
292   
293    Do this for each ppd file present in this directory if you want
294    to enable quota on every printer.
295             
296    WARNING : In the case you've got a non-postscript printer, chances
297              are that the *cupsFilter is already filled-in and points
298              to cupsomatic or such a print filter. In this case please
299              check if you can switch your printer to PostScript mode
300              or if there's a way to make it accept PostScript jobs.
301              If yes then ensure that your workstations uses a PostScript
302              printer driver, and replace the *cupsFilter line with the
303              one pointing to the pykota filter. This should work, but
304              is currently untested.
305              If your printer really needs the original *cupsFilter line
306              then you may not be able to use PyKota easily for now.
307
308  - LPRng Print Backend :
309 
310    Modify the /etc/printcap file to add two lines identical to these ones :
311   
312    :achk=true
313    :as=|/usr/bin/pykota
314   
315    For each printer on which you want to use print accounting.
316 
317Add printers and users to the quota system and set their quota values :
318
319    $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN
320       
321    launching edpykota without any argument or with the --help
322    command line option will show you all the possibilities.
323   
324    by default, each user is limited by "quota", this means that on
325    each printer he can have a different soft and hard limit.
326    You may want to limit the user by his account balance value,
327    in which case, the print quota is shared between all printers
328    instead of being different. To do this, use the following :
329   
330    $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN
331   
332    This will put 10 $ (or Euros, PyKota doesn't care) on each user's account
333    balance, and tell PyKota to limit them by their account balance value.
334    Whenever they print on any printer, their account balance value is
335    decreased by an amount which depends on the particular price per page
336    and per job that you may have defined on the printer with edpykota's
337    --charge command line option.
338    Soft and Hard limits are not used if "--limitby balance" is used,
339    but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf
340    to obtain a similar result (warning message when quota is low).
341
342Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
343
344    $ /etc/init.d/cupsys restart
345   
346  or :
347 
348    $ /etc/init.d/lprng restart
349       
350Your users now should be able to print but not exceed their
351printing quota.
352
353To see printer quota usage, you can use :
354
355    $ repykota --printer lp
356   
357or :
358
359    $ repykota
360   
361    which will print quota usage for all users on all printers,
362    along with totals, if you are the root user. If you are
363    a regular user, only your own quota report will be produced.
364   
365Quota reports are also available remotely by using the CGI script
366printquota.cgi provided in the cgi-bin/ subdirectory.
367
368For different security concerns, please give a look at the SECURITY
369file which is part of this software.
370           
371============================================================
372
373Mailing list :
374--------------
375
376  A mailing list is dedicated to Pykota, you can subscribe to it
377  or consult its archives at :
378 
379    http://cgi.librelogiciel.com/mailman/listinfo/pykota
380   
381============================================================
382   
383Please e-mail bugs to the mailing list at : pykota@librelogiciel.com
384or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.