# $Id$ PyKota - Print Quotas for CUPS and LPRng (c) 2003, 2004, 2005, 2006 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ==================================================================== READ SPECIAL LICENSING AND REDISTRIBUTION TERMS IN THE FILE 'LICENSE' ==================================================================== PyKota features : ----------------- Free Software : - Licensed under the terms of the GNU General Public License. Commercially Supported : - Support Contracts are available from http://www.pykota.com/technical-support/ Operating systems : - Any Unix-like system as print server. - Any operating system as client. Printing systems : - Supports both CUPS and LPRng as the printing system. NB : LPRng is only supported with versions of PyKota <= v1.22HotFix1, but support for LPRng may be reintroduced at a later date. This version DOES NOT support LPRng ! Databases : - Supports PostgreSQL as the database backend. An SQL script to create the database is included. - Supports any LDAP server as the database backend. Complete LDAP schema and sample empty tree are included. Plugging PyKota into your existing LDAP infrastructure is really easy thanks to PyKota's great configurability. - Supports SQLite as the database backend. An SQL script to create the database is included. - Supports MySQL as the database backend. An SQL script to create the database is included. - The print jobs history can be stored in any database of your choice (or in plain text files) if needed. - Master and slave databases are supported : master in read+write mode, slave in readonly mode. Master and slave databases can be of different types ! Printers : - Hardware or Software accounting methods are completely configurable. - Supports any printer which can report its internal page counter. Can ask printers for their internal page counter via SNMP, Netatalk, PJL, PS, or any other way. This is completely configurable. - Supports DSC compliant and binary PostScript, PDF, PCL5 (up to), PCLXL (aka PCL6), ESC/P2, DVI, TIFF, OpenDocument (OpenOffice.org) and Zenographics ZjStream natively (through the direct use of pkpgcounter's code) for software accounting methods. More formats to come. - Supports any other Page Description Language for which you have a parser which can be scripted. Quota systems : - Supports printers and printers groups quotas. - Supports users and users 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. The history of payments (positive or negative credits to an user account) is kept. - Supports high granularity periodic print quotas : down to one minute intervals if needed. - Page quotas and account balance can be set/reset independantly. - Page quotas can be set on a per user or per group basis for a particular printer. - 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. - Both soft and hard limits can be increased or decreased at will. - Possibility to disable quota enforcement for any user or group, while still keeping page accounting. - Each user can have an overcharging (or undercharging) factor, which is applied whenever PyKota computes the cost of a print job. - Specific pages and credits counters can be defined per billing code, and can be reset independantly of the printing history. - Supports a passthrough mode for printers, which doesn't modify users quota when they print. - Supports a maximum number of pages per job, configurable for each printer. - Each user can be completely forbidden to print, independantly from other users. - A transparent printing mode is supported for users, in which their quota is not modified when they print. Administration : - Almost turn-key solution, with the help of the pkturnkey command line tool for database initialization and initial configuration. - Powerful delegation of administrative priviledges. - 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 with the use of powerful wildcard characters. - Account balances can be set, incremented, or decremented. History of payments is kept. - Number of pages used can be set, incremented, or decremented. - Both printers and 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. - PDF invoice generator to charge back users. - 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 or via any other mean 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. - Starting and Ending personalized dynamic banners can be generated on the fly, and accounted for or not, depending on some configuration settings. Banners can still be enabled even if the print job is denied. NB : Banners are a CUPS only feature for now. - Duplicate print jobs can be forbidden automatically. The decision can be left to any script to decide this on a per job basis. - Username and billing code can be overwritten at printing time, to allow people to login as guest users and print as authenticated users, for example. - The pknotify command can now interact with remote users who run the PyKotIcon application which is distributed separately. - Powerful data dumper to export datas to other software (spreadsheets for example). Actually supported formats are : - Comma separated values ; - Semicolon separated values ; - Tab separated values ; - XML. - CUPS' page_log format, to easily interface in real time with third party apps like phpPrintAnalyzer and similar tools. 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 at least partially English, French, Polish, Spanish, Portuguese, Brazilian, Swedish, Thai, Greek, German, Italian, Norwegian (Bokmål), Turkish and traditional Chinese languages. More to come. - Web enabled print quota monitor, data dumper, and quote generator. - An On Screen Display X-Window print quota monitor is included. - An email gateway to allow users to retrieve their print quota information by sending an email message to a dedicated address is included. - Third party web based management tools are available. ==================================================================== Planned features are described in the TODO file. Actually two (or an infinity of) page accounting methods are implemented : - The 'hardware' method consists in querying the printer (via SNMP or Netatalk or any other method of your choice) for its total pages counter. 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. - The 'software' 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. PyKota featured an internal software accounting method which handles several Page Description Languages : DSC compliant and binary PostScript, PDF, PCLXL (aka PCL6), PCL3/4/5, ESC/P2, DVI, TIFF, OpenOffice.org Writer and OpenOffice.org Impress. This software is now distributed separately as 'pkpgcounter', and not included anymore in PyKota, so you must now download and install it before running PyKota. PyKota is known to work fine with most laser printers, either with software accounting, or with hardware accounting if the printer supports this. ============================================================ SUPPORT CONTRACTS: ================== You can now purchase 8x5x365@NextBusinessDay Technical Support Contracts from us. The yearly fee is computed with the following formula : (100.0 * NbPrintServers) + (2.5 * NbPrinters) + (0.04 * NbUsers) EUROS. This fee includes the VAT, and a free subscription to Official PyKota packages. Please send an email to alet@librelogiciel.com if you're interested in purchasing such a contract. Remember that purchasing a support contract for Free Software like PyKota is a great way to show your appreciation for the work already being done on this project, and will help to improve this software in the future. ============================================================ INSTALLATION: ============= NB : ==== PyKota's documentation is available as DocBook SGML sources files in the pykota/docs directory. If you obtained an Official package, in the same directory you'll also find the documentation in HTML and PDF formats. PyKota's collaborative documentation is available from : http://www.pykota.com/wiki/ You may learn more about PyKota, if it fits your own organization, its internal working, and some potential performance drawbacks and how to avoid them, in a document created by Ryan Suarez at : http://archive.macosxlabs.org/forum/webcrossing_archive/documentation/Pykota_and_CUPS/Pykota_and_CUPS.html You may also find the following document interesting : http://es.tldp.org/Tutoriales/doc-openldap-samba-cups-python/ This document, written in Spanish by Sergio Gonzalez Gonzalez, describes the integration of PyKota into an OpenLDAP + Samba + CUPS installation. Even for people who can't read spanish this document is really interesting, and contains lots of screenshots. Finally, SuSe users may find the following document to best describe how to install PyKota on their favorite distribution. It's a Spanish document written by Dennis Romero, and is mostly outdated now : http://www.cvr.espol.edu.ec/people/dennis/Pykota1.19-SuSE9.1.pdf Prerequisite : -------------- See : http://www.pykota.com/wiki/Dependencies for an up-to-date list, or see below (maybe not up-to-date) : You need to have the following tools installed on the CUPS Server : - CUPS (http://www.cups.org) - Python v2.2 or higher (http://www.python.org) - eGenix' mxDateTime Python extension (http://www.egenix.com) - The pkpgcounter command line tool, version 1.56 or higher. This tool is now mandatory for PyKota to work. (http://www.pykota.com/software/pkpgcounter) - The pkipplib Python library (http://www.pykota.com/software/pkipplib) - The JAXML Python module to be able to dump datas in the XML format. (http://www.librelogiciel.com/software/) - The Python-PAM module if you need the pknotify command to be able to check usernames and passwords. - The Python-SNMP module to query printers for their page counter. (http://pysnmp.sourceforge.net). IMPORTANT : version 3.4.2 or higher is REQUIRED. Versions 2.x won't work. Versions 4.x now work (tested with v4.1.5a). - The Python-OSD module to use the graphical print quota reminder. (http://repose.cx/pyosd/) - SNMP tools (specifically the snmpget command) if you prefer to use your own script to request query printers. (http://www.net-snmp.org) - Netatalk (specifically the pap command) if you plan to request your printer's lifetime page counter via AppleTalk. (http://netatalk.sourceforge.net) - The ReportLab Python module (http://www.reportlab.org) if you want to have PyKota generate nice banners for you. - The Python Imaging Library (aka PIL) module (http://www.pythonware.com/downloads) if you want to have PyKota generate nice banners for you. - PostgreSQL's PygreSQL Python extension and the PostgreSQL client libraries if you plan to use PostgreSQL as the database backend. (http://www.postgresql.org and http://www.pygreql.org) or - python-ldap Python module and the OpenLDAP client libraries if you plan to use an LDAP server as the database backend. (http://www.openldap.org and http://python-ldap.sourceforge.net) or - SQLite v3.2.7 and the SQLite libraries if you plan to use SQLite as the database backend (http://www.sqlite.org). You also need the PySQLite module v2.0.5 or higher (http://www.pysqlite.org) or - The MySQL-python bindings. IMPORTANT: If you are using MySQL 4.1, then MySQL-python must be version 1.2 or greater. Version 1.0 does not work correctly with 4.1. On Intel i386 architecture, and for performance reasons, it is strongly suggested that you install the Python accelerator Psyco, available at : http://psyco.sourceforge.net Under Debian : $ apt-get install python-psyco Other architectures may be supported as well in the future, check this on Psyco's website. Installing Psyco is not mandatory, but it will speedup PCL5 parsing by almost 3 times. PostScript and PDF parsing can also benefit, but in an almost unnoticeable manner since this part of the code is already optimal. For PCL5 this is a completely different matter, and if you install Psyco you will never regret it ! Same remark applies for PCL6 (aka PCLXL) : the parser is completely different, but the performance gain with Psyco is impressive. 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 database server : - PostgreSQL (http://www.postgresql.org) or - OpenLDAP, or any other LDAP server (http://www.openldap.org) or - SQLite, v3.2.7 or higher (http://www.sqlite.org). Beware : with SQLite the database server and the print servers MUST be the very same machine. or - MySQL 4.1 or higher. 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 database 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 database server if you've got a bigger network. (NB : with SQLite, the database can't be shared between several print servers) Hint : ------ - The Debian GNU/Linux distribution is to our knowledge the easiest distribution to install PyKota on, because all of PyKota dependencies are already included, excepted for the PySNMP (http://pysnmp.sourceforge.net) module and the pkpgcounter utility which for now have to be downloaded and installed separately. Then : ------ Download the latest PyKota version from the Subversion tree : $ svn co svn://svn.librelogiciel.com/pykota/trunk pykota You can now check if the dependencies are correct by typing : $ python checkdeps.py An availability report for all the software needed by PyKota will be displayed : you'll have to install the missing software if you want PyKota to work correctly. To install the software, just type : $ python setup.py install You may need to be logged in with sufficient privileges (e.g. root) Create a system user for PyKota : $ adduser --system --group --home /etc/pykota --gecos PyKota pykota Put the user your printing system is run as in the pykota system group : $ adduser lp pykota NB : on our system, the CUPS printing system runs as system user 'lp'. Please adapt this to your own system. Go to the initscripts subdirectory of PyKota's sources, and choose the appropriate storage backend for your configuration. Read carefully the associated README file and execute the initialization script to create an empty PyKota database. Upgrade scripts may be provided as well. NB : if you use PostgreSQL, a good way to make PyKota work first time is to modify PostgreSQL's pg_hba.conf to allow the 'trust' database connection mode. However once PyKota works it is HIGHLY RECOMMENDED TO CHANGE THIS TO A MORE SECURE VALUE. 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 usually copies these files into /usr/share/pykota NB : You can move PyKota's configuration files elsewhere, they will be searched first in user pykota's home directory. You need to adapt these files to your own needs. Especially you may 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/share/pykota/cupspykota cupspykota If you use CUPS v1.2 or higher, please do this as well : $ chmod 700 /usr/share/pykota/cupspykota This allows the cupspykota backend to support other backends which must be run as user root, like the lpd backend for example. Restart CUPS so that the new backend can be detected. $ /etc/init.d/cupsys restart or : $ /etc/rc.d/init.d/cupsys restart or any similar command depending on your operating system. 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.example.com:9100 Then choose : cupspykota:socket://myprinter.example.com:9100 Configure your printer as usual. Now double check /etc/pykota/pykota.conf You should manually create a section named after the printer you've just added, unless you have set all options globally. The new pkturnkey command can help you with correct settings for your printers, but don't rely on it because it is still experimental work. To have pkturnkey give you some hints about what to put into pykota.conf, just use its --doconf command line switch : $ pkturnkey --doconf pkturnkey will try to tell you what is the best accounting method for each printer and will print some lines you'll just have to copy&paste in the appropriate sections in /etc/pykota/pykota.conf For more informations about what pkturnkey can do for you, see pkturnkey's manual page or use the --help command line switch : $ pkturnkey --help | less That's all. For existing printers : 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.example.com:9100 with : DeviceURI cupspykota:socket://myprinter.example.com:9100 or : DeviceURI cupspykota://socket://myprinter.example.com:9100 Save the file and restart CUPS. Here too, you may find it interesting to use the pkturnkey command as described above to help with manual configuration of the file /etc/pykota/pykota.conf - LPRng Printing System : IMPORTANT : This release of PyKota DOES NOT support LPRng. If you want to use PyKota with LPRng, you have to download an earlier release of PyKota, for example v1.22HotFix1. 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 : You can either use pkturnkey, or do the same things manually by using the pkprinters, pkusers and edpykota command line tools : Create printers : $ pkprinters --help will tell you how to create, manage or delete printers and printers groups. $ pkprinters --add --charge 0.05 hp2100 would add the printer named hp2100 with a price per page of 0.05 unit. Create users : $ pkusers --add --limitby balance --balane 10.0 jerome would create user jerome and give him ten credits to spend on any printer. Finally create print quota entries : $ edpykota --add -P hp2100 jerome This will create a print quota entry for user jerome on printer hp2100. The print quota entry holds the number of pages printed on a particular printer for a particular user, as well as optional page limits to be used instead of balance limits. See pkusers and edpykota's manual pages for details. 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 quota usage on printer hp2100, you can use : $ repykota --printer hp2100 or : $ repykota which will print quota usage for all users on all printers, along with totals, if you are a PyKota Administator. 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. You can also use the CSS stylesheet present in the stylesheets/ subdirectory and put it at your web server's DocumentRoot, to benefit from a nicer look, especially quota violations will appear in different colors. For additionnal security concerns, please give a look at the SECURITY file which is part of this software. To diagnose a problem when something doesn't work as expected, please read the very first entry in the FAQ document. ============================================================ Additionnal tools : ------------------- Some people have developped tools around PyKota, and make them available under the GNU General Public License : - Kanakorn Horsiritham developped phpPykotaAdmin which is a web based database independant administrative GUI, written in PHP. http://opensource.psu.ac.th/~kanakorn/mambo/ He was also kind enough to write an installation guide in english for CUPS and PyKota with phpPykotaAdmin on Fedora Core 3. You'll find this document on the same website. This great software currently at version 0.3 is a wonderful basis for an administrative GUI since it only depends on PyKota commands to be present to successfully manage PyKota's database. Additionnal software will be listed here when they will be ready. ============================================================ 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 The mailing list is the preferred way to obtain support, because all members can help and can also benefit from the solutions proposed by other members. Posts by non-members are usually rejected. The mailing list language is english and only english. IRC : ----- You can also chat with us : /server irc.freenode.net /join #pykota Preferred language on this channel is english, but french is also accepted. Try to avoid exposing complex problems in french because english speaking people on the channel wouldn't benefit from the solutions. PyKota's main author is known as 'tamere' on IRC. ============================================================ Please e-mail bugs to the mailing list at : pykota@librelogiciel.com or to the main author at : alet@librelogiciel.com (Jerome Alet)