root / pykota / trunk / README @ 1015

Revision 1015, 10.7 kB (checked in by jalet, 21 years ago)

Reorganization of directories

  • 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. The installation script tries to do this for
193you if needed and you agreed to this action.
194You need to adapt the /etc/pykota.conf file to your own needs.
195Especially you have to create sections named after your own
196printers, and change the administrator's email address.
197
198  - CUPS Print Backend :
199 
200    Modify the PPD files for each printer on which you want to manage
201    print quotas, for example /etc/cups/ppd/lp.ppd :
202   
203    --- Add the line below exactly as-is somewhere near the top ---
204    *cupsFilter:  "application/vnd.cups-postscript 0 /usr/bin/pykota"
205    --- Add the line above exactly as-is somewhere near the top  ---
206   
207    Modify the path to the pykota executable if needed, unfortunately
208    you have to supply the correct absolute path here due to CUPS
209    internals, or put the pykota executable into /usr/lib/cups/filter
210    instead of into /usr/bin.
211   
212    Do this for each ppd file present in this directory if you want
213    to enable quota on every printer.
214             
215    WARNING : In the case you've got a non-postscript printer, chances
216              are that the *cupsFilter is already filled-in and points
217              to cupsomatic or such a print filter. In this case please
218              check if you can switch your printer to PostScript mode
219              or if there's a way to make it accept PostScript jobs.
220              If yes then ensure that your workstations uses a PostScript
221              printer driver, and replace the *cupsFilter line with the
222              one pointing to the pykota filter. This should work, but
223              is currently untested.
224              If your printer really needs the original *cupsFilter line
225              then you may not be able to use PyKota easily for now.
226
227  - LPRng Print Backend :
228 
229    Modify the /etc/printcap file to add two lines identical to these ones :
230   
231    :achk=true
232    :as=|/usr/bin/pykota
233   
234    For each printer on which you want to use print accounting.
235 
236Add printers and users to the quota system and set their quota values :
237
238    $ edpykota --add -P printer -S softlimit -H hardlimit user1 ... userN
239       
240    launching edpykota without any argument or with the --help
241    command line option will show you all the possibilities.
242
243Restart CUPS or LPRng, for example under Debian GNU/Linux systems :         
244
245    $ /etc/init.d/cupsys restart
246   
247  or :
248 
249    $ /etc/init.d/lprng restart
250       
251Your users now should be able to print but not exceed their
252printing quota.
253
254To see printer command usage, you can use :
255
256    $ repykota --printer lp
257   
258or :
259
260    $ repykota
261   
262    which will print quota usage for all users on all printers,
263    along with totals.
264   
265Quota reports are also available remotely by using the CGI scripts
266provided in the cgi-bin/ subdirectory.
267
268For different security concerns, please give a look at the SECURITY
269file which is part of this software.
270           
271============================================================
272
273Mailing list :
274--------------
275
276  A mailing list is dedicated to Pykota, you can subscribe to it
277  or consult its archives at :
278 
279    http://cgi.librelogiciel.com/mailman/listinfo/pykota
280   
281============================================================
282   
283Please e-mail bugs to: alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.