# $Id$ PyKota - Print Quota for CUPS and LPRng (c) 2003 Jerome Alet This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. ==================================================================== READ SPECIAL LICENSING AND REDISTRBUTION TERMS IN THE FILE 'LICENSE' ==================================================================== PyKota is a complete Print Quota system for the Common Unix Printing System (aka CUPS) or LPR Next Generation (LPRng), which works by directly querying the printers for the number of pages they have printed. Actual working features : - Supports both CUPS and LPRng backends. - Per printer user and group quotas. - Automated email warning of users above quota to the user himself and to the print quota administrator. - Filter for quota accounting : pykota - Command line print quota editor : edpykota - Command line print quota report generator : repykota - Command line print quota automated warning sender : warnpykota - Command line tools mimic the disk quota utilities for easier mastering. - Centralized storage of quotas : you can manage quotas for different printers on different print servers and store them all on the same quota storage server. - SNMP querying of any networked SNMP-enabled printer. - Netatalk querying of any networked AppleTalk-enabled printer. - External command querying of any printer : you can use you own querying command, e.g. to query a printer via the serial port, sending it a special PJL job and reading the result. See the example scripts in the "untested" directory and try to adapt them to your configuration. - External accounting methods : you can use your own accounting method to compute each job's size. Just create a shell script which prints the job's (read from its standard input) size on its standard output, and you're done ! - Special scripts included for a seamless integration of PyKota on Debian machines. - Complete job history is saved. This will allow more complex reports in the future. - Price per page and price per job can be defined for every printer. A job's price is the sum of the price per job for this printer plus the number of pages multiplied by the price per page for this printer. - User's account balance and lifetime paid money are now stored in the Quota Storage, and account balance can be used to limit the user printing instead of a print quota. Actually you can limit either by account balance OR by print quota, but maybe both should be checked at the same time. Tell me what you prefer. All the command line tools accept the -h | --help command line option which prints all the available options and show usage examples. Planned features are described in the TODO file. Actually three (or an infinity of) page accounting methods are implemented : - The 'querying' method consists in querying the printer (via SNMP or Netatalk) for its total pages counter, just before the beginning of a job, and use this to modify the *preceding* user's quota. So you're always late of one print job, but this is generally ok, especially because a check is also done to see if the current user is allowed or not to print. You're not limited to SNMP or Netatalk, because you can also use any external command instead if you want. - The 'external' method consists in delegating the computation of the job's size in number of pages to any external command of your choice. The command can read the job's data from its standard input and MUST output the job's size on its standard output. - The 'stupid' method consists in counting the 'showpage' PostSript statements in the job. THIS IS UNRELIABLE, but can serve as an example if you plan to write your own accounting method for integration into PyKota. PyKota is known to work fine with HP Laserjet 2100 and 2200, and Apple LaserWriter 16/600 PS, both with CUPS and LPRng, under Debian GNU/Linux (Sarge and Sid) operating systems. I'm interested in receiving success or failure reports with other brands or models of printers, as well as with other operating systems. ============================================================ INSTALLATION: ============= WARNING : ========= If you run a PyKota version lower than 1.03, you definitely have to upgrade you Quota Storage Database. Please read the documentation included in the initscripts subdirectory first ! Prerequisite : -------------- You need to have the following tools installed on the CUPS Server : - CUPS or LPRng - Python v2.1 or above - eGenix' mxDateTime Python extension - PostgreSQL's PygreSQL Python extension and the PostgreSQL client libraries. - SNMP tools (specifically the snmpget command) if you plan to request your printer's lifetime page counter via SNMP. - Netatalk (specifically the pap command) if you plan to request your printer's lifetime page counter via AppleTalk. You need to have the following tools installed on the Quota Storage Server : - PostgreSQL PygreSQL and the PostgreSQL client libraries's versions on the Print Server must match the PostgreSQL version used on the Quota Storage Server. This list of prerequisite software may change in the future, when PyKota will support more functionnalities you will be given alternatives. Of course the Print Server and the Quota Storage Server can be the very same machine if you've got a tiny network, or you can have multiple Print Servers all storing their quotas on the same Quota Storage Server if you've got a bigger network. Then : ------ Download the latest PyKota version from the CVS tree on : http://savannah.nongnu.org/projects/pykota Just type : python setup.py install You may need to be logged in with sufficient privileges (e.g. root) The installation script will now automatically check if some software is missing and ask you if you still want to proceed with the installation or abort it completely. Go to the initscripts subdirectory of PyKota's sources, and choose the appropriate storage backend for your configuration. Read the associated README file and execute the initialization script to create an empty PyKota Storage. Upgrade scripts may be provided as well. Copy the conf/pykota.conf.sample sample configuration file to /etc/pykota.conf, and adapt this file to your own needs and configuration. The installation script tries to do this for you if needed and you agreed to this action. - CUPS Print Backend : Modify the PPD files for each printer on which you want to manage print quotas, for example /etc/cups/ppd/lp.ppd : --- Add the line below exactly as-is somewhere near the top --- *cupsFilter: "application/vnd.cups-postscript 0 /usr/bin/pykota" --- Add the line above exactly as-is somewhere near the top --- Modify the path to the pykota executable if needed, unfortunately you have to supply the correct absolute path here due to CUPS internals, or put the pykota executable into /usr/lib/cups/filter instead of into /usr/bin. Do this for each ppd file present in this directory if you want to enable quota on every printer. WARNING : In the case you've got a non-postscript printer, chances are that the *cupsFilter is already filled-in and points to cupsomatic or such a print filter. In this case please check if you can switch your printer to PostScript mode or if there's a way to make it accept PostScript jobs. If yes then ensure that your workstations uses a PostScript printer driver, and replace the *cupsFilter line with the one pointing to the pykota filter. This should work, but is currently untested. If your printer really needs the original *cupsFilter line then you may not be able to use PyKota easily for now. - LPRng Print Backend : Modify the /etc/printcap file to add two lines identical to these ones : :achk=true :as=|/usr/bin/pykota For each printer on which you want to use print accounting. Add printers and users to the quota system and set their quota values : $ edpykota --add -P printer -S softlimit -H hardlimit user1 ... userN launching edpykota without any argument or with the --help command line option will show you all the possibilities. Restart CUPS, for example under Debian GNU/Linux systems : $ /etc/init.d/cupsys restart Your users now should be able to print but not exceed their printing quota. To see printer command usage, you can use : $ repykota --printer lp or : $ repykota which will print quota usage for all users on all printers, along with totals. For different security concerns, please give a look at the SECURITY file which is part of this software. ============================================================ Mailing list : -------------- A mailing list is dedicated to Pykota, you can subscribe to it or consult its archives at : http://cgi.librelogiciel.com/mailman/listinfo/pykota ============================================================ Please e-mail bugs to: alet@librelogiciel.com (Jerome Alet)