# $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 REDISTRIBUTION TERMS IN THE FILE 'LICENSE' ==================================================================== PyKota features : ----------------- Operating systems : - Any Unix-like system as print server. - Any operating system as client. Printing systems : - Supports CUPS as the printing system. - Supports LPRng as the printing system. Databases : - Supports PostgreSQL as the Quota Storage backend. Complete database creation SQL script is included. - Supports OpenLDAP as the Quota Storage backend. Complete LDAP schema and sample tree are included. Plugging PyKota into your existing LDAP infrastructure is really easy thanks to PyKota's great configurability. Printers : - Supports any printer which can report its internal page counter. - Supports any other printer via GhostScript. Depending on the printer some configuration may be needed. - Can ask printers for their internal page counter via SNMP, Netatalk, or any other mean of your choice. This is completely configurable. - External accounting methods are configurable. Quota systems : - Supports user and groups quotas. - Supports page quotas. Page quotas can be set differently on a per printer and per user/group basis. - Supports account balance quotas in any currency. Account balance quotas can be set on a per user basis. The account balance is shared amongst all printers. - Experimental support for printer groups, so that you can share quota between printers of the same type but in different locations. - Page quota and account balance can be set/reset independantly. - Limiting factor, page quota or account balance, can be set on a per user or per group basis. - Price per page and per job can be set differently on any printer. - Low level of page quota or account balance are configurable. - Both soft and hard limit with configurable grace delay can be set for page quota. - Possibility to disable quota enforcement for any user or group, while still keeping page accounting. Administration : - Powerful administration tools can be used to automate setting or resetting of quotas or account balances at specific intervals. - Administration tools can modify several users, groups, or printers at once. - Account balances can be set, incremented, or decremented. - Users can be automatically added on first print in a completely configurable way. - Quota report generator available either from the command line or in any web browser. The web-based quota report generator can be user/password protected. - Print quote generator can tell users how much a print job will cost them in advance. - Policy with regard to unregistered users can be configured for each printer to either deny printing, allow printing, or delegate the decision to any external tool. - Warning and error messages can be automatically sent via email to the administrator, the user, both, or none. - Warning and error messages' content is completely configurable. - Configuration can be changed without needing to restart the printing system. - Complete print job history is kept. This can be disabled if needed. - Automated low quota or balance remainder can be scheduled regularly or launched manually. User Interface : - All the command line tools accept the -h | --help command line option which prints all the available options and show usage examples. - Completely internationalized. Actually supports the English and French languages. More to come. ==================================================================== 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 or any other method of your choice) for its total pages counter. With CUPS, this is done both at the beginning and at the end of a print job. The counters difference is then immediately used to decrease the user's account balance or increase his quota usage. With LPRng, this is done just before the beginning of a job, and used 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. - 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. Changes to the user account are reported immediately, both with CUPS and LPRng. - 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. It basically works like the 'external' method, but does the computation internally. 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: ============= NB : ==== Users of MacOS-X may find the following tutorial useful : http://ell-tech.com/pages/pykota.php 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 - 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. - PostgreSQL's PygreSQL Python extension and the PostgreSQL client libraries if you plan to use PostgreSQL as the Quota Storage backend. or - python-ldap Python module and the OpenLDAP client libraries if you plan to use OpenLDAP as the Quota Storage backend. You may also benefit from having the following tools installed to deal with some printers : - npadmin - netcat - ghostscript You need to have the following tools installed on the Quota Storage Server : - PostgreSQL or - OpenLDAP NB : PygreSQL must be linked with the PostgreSQL client libraries on the Print Server. The PostgreSQL client libraries' version must match the PostgreSQL version used on the Quota Storage Server. or python-ldap must be linked with the OpenLDAP client libraries on the Print Server. The OpenLDAP client libraries' version must match the OpenLDAP 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 and conf/pykotadmin.conf.sample sample configuration files to /etc/pykota/pykota.conf and /etc/pykota/pykotadmin.conf. The installation script tries to do this for you if needed and you agreed to this action. You need to adapt these files to your own needs. Especially you have to create sections named after your own printers, and change the administrator's email address which by default is root@localhost. Read and try to understand these two very well commented files, so that you'll encounter less problems later. Also be sure to double check that commands that query printers for their internal page counter work from the command line before using them in PyKota's configuration. The rest of the installation depends on your printing system : - CUPS Printing System : Once and for all : Create a symbolic link to the cupspykota backend in CUPS's backend directory : $ cd /usr/lib/cups/backend $ ln -s /usr/bin/cupspykota cupspykota Restart CUPS so that the new backend can be detected. $ /etc/init.d/cupsys restart For new printers : Go to CUPS management interface (http://localhost:631) and choose the appropriate PyKota managed device depending on the type of printer you use. For example, if your printer is waiting on : socket://myprinter.domain.com:9100 Then choose : cupspykota:socket://myprinter.domain.com:9100 Configure your printer as usual. Now double check /etc/pykota/pykota.conf This file should contain a section named after the printer you've just added. That's all. For existing printers : If you had already installed a version of PyKota earlier than 1.16alpha7, then remove the *cupsFilter lines in your PPD files for each printer already managed printers. Each line to remove is of the form : *cupsFilter: "application/vnd.cups-postscript 0 /usr/bin/pykota" Don't touch anything else, especially any other *cupsFilter line. Then save each of these files. Then, the easiest is to directly modify the DeviceURI lines in /etc/cups/printers.conf, you just have to put 'cupspykota:' in front of what is already on these lines. For example, replace : DeviceURI socket://myprinter.domain.com:9100 with : DeviceURI cupspykota:socket://myprinter.domain.com:9100 Save the file and restart CUPS. - LPRng Printing System : 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. And then save the file and restart LPRng : $ /etc/init.d/lprng restart Now you can begin to populate the PyKota's database with printers, users and groups : Add printers and users to the quota system and set their quota values : $ edpykota --add -P hp2100 -S 40 -H 50 user1 ... userN launching edpykota without any argument or with the --help command line option will show you all the possibilities. by default, each user is limited by "quota", this means that on each printer he can have a different soft and hard limit. You may want to limit the user by his account balance value, in which case, the print quota is shared between all printers instead of being different. To do this, use the following : $ edpykota --add -P hp2100 --limitby balance --balance 10 user1 ... userN This will put 10 $ (or Euros, PyKota doesn't care) on each user's account balance, and tell PyKota to limit them by their account balance value. Whenever they print on any printer, their account balance value is decreased by an amount which depends on the particular price per page and per job that you may have defined on the printer with edpykota's --charge command line option. Soft and Hard limits are not used if "--limitby balance" is used, but you can define a "poorman"'s threshold in /etc/pykota/pykota.conf to obtain a similar result (warning message when quota is low). Restart CUPS or LPRng, for example under Debian GNU/Linux systems : $ /etc/init.d/cupsys restart or : $ /etc/init.d/lprng restart Your users now should be able to print but not exceed their printing quota. To see printer quota usage, you can use : $ repykota --printer lp or : $ repykota which will print quota usage for all users on all printers, along with totals, if you are the root user. If you are a regular user, only your own quota report will be produced. Quota reports are also available remotely by using the CGI script printquota.cgi provided in the cgi-bin/ subdirectory. 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 IRC : ----- You can also chat with us : /server irc.freenode.net /join #pykota ============================================================ Please e-mail bugs to the mailing list at : pykota@librelogiciel.com or to the main author at : alet@librelogiciel.com (Jerome Alet)