root / pykota / trunk / README @ 1039

Revision 1034, 10.8 kB (checked in by jalet, 21 years ago)

Link to MacOS-X tutorial included

  • 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 REDISTRBUTION TERMS IN THE FILE 'LICENSE'
23
24====================================================================
25
26PyKota is a complete Print Quota system for the Common Unix Printing
27System (aka CUPS) or LPR Next Generation (LPRng), which works by directly
28querying the printers for the number of pages they have printed.
29
30Actual working features :
31
32        - Supports both CUPS and LPRng backends.
33       
34        - Per printer user and group quotas.
35       
36        - Automated email warning of users above quota to the
37          user himself and to the print quota administrator.
38       
39        - Filter for quota accounting : pykota
40       
41        - Command line print quota editor : edpykota
42       
43        - Command line print quota report generator : repykota
44       
45        - Command line print quota automated warning sender : warnpykota
46       
47        - Command line tools mimic the disk quota utilities for
48          easier mastering.
49       
50        - Centralized storage of quotas : you can manage quotas for
51          different printers on different print servers and store them all
52          on the same quota storage server.
53                   
54        - SNMP querying of any networked SNMP-enabled printer.
55       
56        - Netatalk querying of any networked AppleTalk-enabled printer.
57       
58        - External command querying of any printer : you can use
59          you own querying command, e.g. to query a printer via
60          the serial port, sending it a special PJL job and
61          reading the result. See the example scripts in the
62          "untested" directory and try to adapt them to your
63          configuration.
64         
65        - External accounting methods : you can use your own accounting
66          method to compute each job's size. Just create a shell script
67          which reads the job's data from its standard input and prints
68          the job's size on its standard output, and you're done !
69       
70        - Special scripts included for a seamless integration of
71          PyKota on Debian machines.
72         
73        - Complete job history is saved. This will allow more
74          complex reports in the future.
75         
76        - Price per page and price per job can be defined for 
77          every printer. A job's price is the sum of the
78          price per job for this printer plus the number of
79          pages multiplied by the price per page for this
80          printer.
81         
82        - User's account balance and lifetime paid money are now
83          stored in the Quota Storage, and account balance can be
84          used to limit the user printing instead of a print quota.
85          Actually you can limit either by account balance OR by
86          print quota. Account balance is shared between printers
87          for an user, while quotas are define separately for
88          each printer the user prints on.
89         
90All the command line tools accept the -h | --help command line option
91which prints all the available options and show usage examples.
92       
93Planned features are described in the TODO file.
94
95Actually three (or an infinity of) page accounting methods are
96implemented :
97
98  - The 'querying' method consists in querying the printer (via SNMP
99    or Netatalk) for its total pages counter, just before the beginning
100    of a job, and use this to modify the *preceding* user's quota. So
101    you're always late of one print job, but this is generally ok,
102    especially because a check is also done to see if the current user
103    is allowed or not to print. You're not limited to SNMP or Netatalk,
104    because you can also use any external command instead if you want.
105   
106  - The 'external' method consists in delegating the computation of the
107    job's size in number of pages to any external command of your choice.
108    The command can read the job's data from its standard input and MUST
109    output the job's size on its standard output.
110   
111  - The 'stupid' method consists in counting the 'showpage' PostSript 
112    statements in the job. THIS IS UNRELIABLE, but can serve as an
113    example if you plan to write your own accounting method for
114    integration into PyKota.
115 
116PyKota is known to work fine with HP Laserjet 2100 and 2200, and
117Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under
118Debian GNU/Linux (Sarge and Sid) operating systems.
119
120I'm interested in receiving success or failure reports with other
121brands or models of printers, as well as with other operating
122systems.
123
124============================================================
125
126INSTALLATION:
127=============
128
129WARNING :
130=========
131
132  If you run a PyKota version lower than 1.03, you definitely have to
133  upgrade you Quota Storage Database. Please read the documentation
134  included in the initscripts subdirectory first !
135 
136  Users of MacOS-X may find the following tutorial useful :
137
138      http://ell-tech.com/pages/pykota.php
139
140Prerequisite :
141--------------
142   
143  You need to have the following tools installed on the CUPS Server :
144 
145    - CUPS or LPRng
146    - Python v2.1 or above
147    - eGenix' mxDateTime Python extension
148    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
149      libraries.
150    - SNMP tools (specifically the snmpget command) if you plan to
151      request your printer's lifetime page counter via SNMP.
152    - Netatalk (specifically the pap command) if you plan to
153      request your printer's lifetime page counter via AppleTalk.
154   
155  You need to have the following tools installed on the Quota Storage 
156  Server :
157 
158    - PostgreSQL
159   
160  PygreSQL and the PostgreSQL client libraries's versions on the Print
161  Server must match the PostgreSQL version used on the Quota Storage
162  Server.
163 
164  This list of prerequisite software may change in the future, when
165  PyKota will support more functionnalities you will be given
166  alternatives.
167 
168  Of course the Print Server and the Quota Storage Server can be the
169  very same machine if you've got a tiny network, or you can have
170  multiple Print Servers all storing their quotas on the same Quota
171  Storage Server if you've got a bigger network.
172 
173Then :   
174------
175 
176Download the latest PyKota version from the CVS tree on :
177
178    http://savannah.nongnu.org/projects/pykota
179
180Just type :
181
182    python setup.py install
183
184You may need to be logged in with sufficient privileges (e.g. root)
185
186The installation script will now automatically check if some software
187is missing and ask you if you still want to proceed with the
188installation or abort it completely.
189
190Go to the initscripts subdirectory of PyKota's sources, and choose
191the appropriate storage backend for your configuration. Read
192the associated README file and execute the initialization script
193to create an empty PyKota Storage. Upgrade scripts may be
194provided as well.
195
196Copy the conf/pykota.conf.sample sample configuration file to
197/etc/pykota.conf. The installation script tries to do this for
198you if needed and you agreed to this action.
199You need to adapt the /etc/pykota.conf file to your own needs.
200Especially you have to create sections named after your own
201printers, and change the administrator's email address.
202
203  - CUPS Print Backend :
204 
205    Modify the PPD files for each printer on which you want to manage
206    print quotas, for example /etc/cups/ppd/lp.ppd :
207   
208    --- Add the line below exactly as-is somewhere near the top ---
209    *cupsFilter:  "application/vnd.cups-postscript 0 /usr/bin/pykota"
210    --- Add the line above exactly as-is somewhere near the top  ---
211   
212    Modify the path to the pykota executable if needed, unfortunately
213    you have to supply the correct absolute path here due to CUPS
214    internals, or put the pykota executable into /usr/lib/cups/filter
215    instead of into /usr/bin.
216   
217    Do this for each ppd file present in this directory if you want
218    to enable quota on every printer.
219             
220    WARNING : In the case you've got a non-postscript printer, chances
221              are that the *cupsFilter is already filled-in and points
222              to cupsomatic or such a print filter. In this case please
223              check if you can switch your printer to PostScript mode
224              or if there's a way to make it accept PostScript jobs.
225              If yes then ensure that your workstations uses a PostScript
226              printer driver, and replace the *cupsFilter line with the
227              one pointing to the pykota filter. This should work, but
228              is currently untested.
229              If your printer really needs the original *cupsFilter line
230              then you may not be able to use PyKota easily for now.
231
232  - LPRng Print Backend :
233 
234    Modify the /etc/printcap file to add two lines identical to these ones :
235   
236    :achk=true
237    :as=|/usr/bin/pykota
238   
239    For each printer on which you want to use print accounting.
240 
241Add printers and users to the quota system and set their quota values :
242
243    $ edpykota --add -P printer -S softlimit -H hardlimit user1 ... userN
244       
245    launching edpykota without any argument or with the --help
246    command line option will show you all the possibilities.
247
248Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
249
250    $ /etc/init.d/cupsys restart
251   
252  or :
253 
254    $ /etc/init.d/lprng restart
255       
256Your users now should be able to print but not exceed their
257printing quota.
258
259To see printer command usage, you can use :
260
261    $ repykota --printer lp
262   
263or :
264
265    $ repykota
266   
267    which will print quota usage for all users on all printers,
268    along with totals.
269   
270Quota reports are also available remotely by using the CGI scripts
271provided in the cgi-bin/ subdirectory.
272
273For different security concerns, please give a look at the SECURITY
274file which is part of this software.
275           
276============================================================
277
278Mailing list :
279--------------
280
281  A mailing list is dedicated to Pykota, you can subscribe to it
282  or consult its archives at :
283 
284    http://cgi.librelogiciel.com/mailman/listinfo/pykota
285   
286============================================================
287   
288Please e-mail bugs to: alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.