root / pykota / trunk / README @ 986

Revision 985, 10.4 kB (checked in by jalet, 22 years ago)

Misleading 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 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, but maybe both should be checked at the
87          same time. Tell me what you prefer.
88         
89All the command line tools accept the -h | --help command line option
90which prints all the available options and show usage examples.
91       
92Planned features are described in the TODO file.
93
94Actually three (or an infinity of) page accounting methods are
95implemented :
96
97  - The 'querying' method consists in querying the printer (via SNMP
98    or Netatalk) for its total pages counter, just before the beginning
99    of a job, and use this to modify the *preceding* user's quota. So
100    you're always late of one print job, but this is generally ok,
101    especially because a check is also done to see if the current user
102    is allowed or not to print. You're not limited to SNMP or Netatalk,
103    because you can also use any external command instead if you want.
104   
105  - The 'external' method consists in delegating the computation of the
106    job's size in number of pages to any external command of your choice.
107    The command can read the job's data from its standard input and MUST
108    output the job's size on its standard output.
109   
110  - The 'stupid' method consists in counting the 'showpage' PostSript 
111    statements in the job. THIS IS UNRELIABLE, but can serve as an
112    example if you plan to write your own accounting method for
113    integration into PyKota.
114 
115PyKota is known to work fine with HP Laserjet 2100 and 2200, and
116Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under
117Debian GNU/Linux (Sarge and Sid) operating systems.
118
119I'm interested in receiving success or failure reports with other
120brands or models of printers, as well as with other operating
121systems.
122
123============================================================
124
125INSTALLATION:
126=============
127
128WARNING :
129=========
130
131  If you run a PyKota version lower than 1.03, you definitely have to
132  upgrade you Quota Storage Database. Please read the documentation
133  included in the initscripts subdirectory first !
134 
135Prerequisite :
136--------------
137   
138  You need to have the following tools installed on the CUPS Server :
139 
140    - CUPS or LPRng
141    - Python v2.1 or above
142    - eGenix' mxDateTime Python extension
143    - PostgreSQL's PygreSQL Python extension and the PostgreSQL client
144      libraries.
145    - SNMP tools (specifically the snmpget command) if you plan to
146      request your printer's lifetime page counter via SNMP.
147    - Netatalk (specifically the pap command) if you plan to
148      request your printer's lifetime page counter via AppleTalk.
149   
150  You need to have the following tools installed on the Quota Storage 
151  Server :
152 
153    - PostgreSQL
154   
155  PygreSQL and the PostgreSQL client libraries's versions on the Print
156  Server must match the PostgreSQL version used on the Quota Storage
157  Server.
158 
159  This list of prerequisite software may change in the future, when
160  PyKota will support more functionnalities you will be given
161  alternatives.
162 
163  Of course the Print Server and the Quota Storage Server can be the
164  very same machine if you've got a tiny network, or you can have
165  multiple Print Servers all storing their quotas on the same Quota
166  Storage Server if you've got a bigger network.
167 
168Then :   
169------
170 
171Download the latest PyKota version from the CVS tree on :
172
173    http://savannah.nongnu.org/projects/pykota
174
175Just type :
176
177    python setup.py install
178
179You may need to be logged in with sufficient privileges (e.g. root)
180
181The installation script will now automatically check if some software
182is missing and ask you if you still want to proceed with the
183installation or abort it completely.
184
185Go to the initscripts subdirectory of PyKota's sources, and choose
186the appropriate storage backend for your configuration. Read
187the associated README file and execute the initialization script
188to create an empty PyKota Storage. Upgrade scripts may be
189provided as well.
190
191Copy the conf/pykota.conf.sample sample configuration file to
192/etc/pykota.conf, and adapt this file to your own needs and
193configuration. The installation script tries to do this for
194you if needed and you agreed to this action.
195
196  - CUPS Print Backend :
197 
198    Modify the PPD files for each printer on which you want to manage
199    print quotas, for example /etc/cups/ppd/lp.ppd :
200   
201    --- Add the line below exactly as-is somewhere near the top ---
202    *cupsFilter:  "application/vnd.cups-postscript 0 /usr/bin/pykota"
203    --- Add the line above exactly as-is somewhere near the top  ---
204   
205    Modify the path to the pykota executable if needed, unfortunately
206    you have to supply the correct absolute path here due to CUPS
207    internals, or put the pykota executable into /usr/lib/cups/filter
208    instead of into /usr/bin.
209   
210    Do this for each ppd file present in this directory if you want
211    to enable quota on every printer.
212             
213    WARNING : In the case you've got a non-postscript printer, chances
214              are that the *cupsFilter is already filled-in and points
215              to cupsomatic or such a print filter. In this case please
216              check if you can switch your printer to PostScript mode
217              or if there's a way to make it accept PostScript jobs.
218              If yes then ensure that your workstations uses a PostScript
219              printer driver, and replace the *cupsFilter line with the
220              one pointing to the pykota filter. This should work, but
221              is currently untested.
222              If your printer really needs the original *cupsFilter line
223              then you may not be able to use PyKota easily for now.
224
225  - LPRng Print Backend :
226 
227    Modify the /etc/printcap file to add two lines identical to these ones :
228   
229    :achk=true
230    :as=|/usr/bin/pykota
231   
232    For each printer on which you want to use print accounting.
233 
234Add printers and users to the quota system and set their quota values :
235
236    $ edpykota --add -P printer -S softlimit -H hardlimit user1 ... userN
237       
238    launching edpykota without any argument or with the --help
239    command line option will show you all the possibilities.
240
241Restart CUPS, for example under Debian GNU/Linux systems :         
242
243    $ /etc/init.d/cupsys restart
244       
245Your users now should be able to print but not exceed their
246printing quota.
247
248To see printer command usage, you can use :
249
250    $ repykota --printer lp
251   
252or :
253
254    $ repykota
255   
256    which will print quota usage for all users on all printers,
257    along with totals.
258   
259For different security concerns, please give a look at the SECURITY
260file which is part of this software.
261           
262============================================================
263
264Mailing list :
265--------------
266
267  A mailing list is dedicated to Pykota, you can subscribe to it
268  or consult its archives at :
269 
270    http://cgi.librelogiciel.com/mailman/listinfo/pykota
271   
272============================================================
273   
274Please e-mail bugs to: alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.