root / pykota / trunk / README @ 1183

Revision 1181, 14.2 kB (checked in by jalet, 21 years ago)

Note about the new IRC channel

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