Last modified on $Date$ Before being able to use PyKota, you have of course to install it first. But before installing, you must carefully plan your installation. First you have to determine which machine will be the PyKota Storage Server. The Storage Server is the host responsible for keeping a centralized database of print usage for all your printers, users and groups. Then you have to list all the Print Servers for which you plan to use print quota facilities. Finally you have to download PyKota's latest version or buy an official package, from http://www.librelogiciel.com/software/. If you've just bought an official package, then as soon as you've receive it you have to decompress and visit its archive, to do so just type the following commands : jerome@nordine:~$ tar -zxf pykota-1.15_official.tar.gz jerome@nordine:~$ cd pykota-1.15_official jerome@nordine:~/pykota-1.15_official$ You can see many files in this directory, the first ones to read are README, then COPYING and LICENSE. They will give you basic installation instructions and explain the licensing terms under which PyKota is distributed. Of course they are also mostly boring to read ! Detailed installation and operating instructions are defined in the ./docs directory, in the form of SGML documentation in the DocBook format. You have to compile these files into readable documentation like the HTML or PDF formats, or buy an official PyKota package which already contains these compiled forms of the documentation. Of course you already know this because that's what you are currently reading ! Now we will see what has to be done on each of the servers we are planning to use. Of course, depending on the size of your network, you may very well use the same machine as both a Print Server and a Storage Server. This is especially the case if you've got only one server. Depending on PyKota's version number, different types of storage backends may be supported, so we will see for each one of them how to configure it. PostgreSQL is an Object Relationnal DataBase Management System distributed under a Free Software license from the http://www.postgresql.org web site. It certainely is the free RDBMS which has the most advanced features, and is widely used all over the world. To configure your Storage Server, you must have PostgreSQL already working. The complete installation of PostgreSQL is not covered by the present manual, please refer to your system's documentation or to http://www.postgresql.org for details. One thing you have to check, though, is that every Print Server on which you want to install the print quota mechanism, must be able to connect to the PostgreSQL server. In the default installation of PostgreSQL this may not be the case for security reasons, except if both servers are in fact the same machine. In any case, it is recommended that you check the /etc/postgresql/pg_hba.conf file and modify it if needed. This file is self documented and its modification is straightforward. You also have to make sure that PostgreSQL accepts TCP/IP connections. To do so you either have to launch it with the -i option or modify the /etc/postgresql/postgresql.conf file, which is self documented and easy to modify too. Allowing TCP/IP connections is not necessary though if your Quota Storage Server and your Print Server are the very same host. Don't forget to restart PostgreSQL if you modify any of its configuration files, in order for the changes to take effect. Be careful, you may be unable to connect from a Print Server to the PostgreSQL server even if the configuration is correct. Sometimes your connections may be blocked by one or more network firewalls along the route from one machine to the other. If this is the case, then the best thing you can do is to ask your Network Administrator to not filter the IP port used by PostgreSQL, which is usually port 5432/tcp. The TCP/IP network port used by PostgreSQL may be different. When in doubt, ask your System Administrator for the correct value. Now that your PostgreSQL server is up and running, and is waiting for your connections, you have to create the Quota Storage DataBase. To do so, you'll have to feed PostgreSQL with the pykota-x.xx/initscripts/postgresql/pykota-postgresql.sql file. This file will create a Quota DataBase administrator in the PostgreSQL system, then create an empty Quota DataBase and set some permissions on it. The Quota DataBase administrator is the PostgreSQL's user used to manage the Quota database. The Quota DataBase Administrator is not present in the Quota Database itself, he is only defined in PostgreSQL and don't have to exist on any system, nor in the Quota DataBase. His default name is pykotaadmin. A Quota Storage read-only user is also created under the name of pykotauser. This read-only user is used by PyKota to connect to the Quota Storage when a non-root user launches a pykota command. This prevents normal users from being able to modify their own, or other users', quota information. The database which will be created will be named pykota by default. You can choose other names if you want, just modify the initscripts/postgresql/pykota-postgresql.sql file accordingly, and report your changes into PyKota's configuration file. To run this script, you can use the psql frontend to PostgreSQL, but your priviledges must be sufficient to be allowed to create users and databases. You can launch psql as the postgres user which is PostgreSQL's default administrator, and connect to the default database named template1. From a command line interpreter (i.e. shell), type the following commands : jerome@nordine:~$ cd pykota-1.15_official/initscripts/postgresql jerome@nordine:~/pykota-1.15_official/initscripts$ psql -h localhost -U postgres template1 Welcome to psql, the PostgreSQL interactive terminal. Type: \copyright for distribution terms \h for help with SQL commands \? for help on internal slash commands \g or terminate with semicolon to execute query \q to quit template1=# \i pykota-postgresql.sql ... a lot of output lines pykota=# For security reasons, you may want to set passwords in PostgreSQL for the pykotaadmin and pykotauser users. Otherwise any user able to connect to PostgreSQL on your Quota Storage Server could connect to the quota database, and either see it, or even modify it without problem. To do so, just type the following lines while still being at the psql prompt (replace the password values by your own, and do the same for the pykotauser user) : pykota=# ALTER USER pykotaadmin PASSWORD 'somepassword'; ALTER USER pykota=# \q jerome@nordine:~/pykota-1.15_official/initscripts/postgresql$ The \q command above will quit the psql program and return you to the shell's command line prompt. To improve security further, you could encrypt your database connections, or take any other step as needed. Please refer to PostgreSQL's documentation for details. Also if PyKota's configuration file /etc/pykota/pykotadmin.conf is readable by anyone with access on your file system, a local user could create some script to modify his own print quota. Defining passwords may not be sufficient if your database access rule is set to trust in the /etc/postgresql/pg_hba.conf. Again, please refer to PostgreSQL's documentation for details. Also, passwords will fly unencrypted over the network by default, so be sure to take any necessary step to secure your database server from unauthorized use. This has nothing to do with PyKota though, it is just a general rule to keep in mind. If no error occured, then your Quota DataBase is ready to be used. Now you can let the Quota Storage Server alone, the remaining work will have to be done on each one of the print servers which will use this particular Quota Storage Server. If an error occured, maybe your PostgreSQL version is too old, or an unexpected problem (like a bug) happened. Please contact us via email so that we can try to solve the problem. Thanks in advance. From version 1.09 on, OpenLDAP can be used as a Quota Storage Backend. It is possible that other LDAP servers can be used, but this is currently untested. OpenLDAP is a Lightweight Directory Access Protocol server implementation published as Free Software. You can download it from http://www.openldap.org. To use OpenLDAP as your Quota Storage Backend, you have to copy the pykota/initscripts/ldap/pykota.schema in OpenLDAP's schemas directory. Under Debian GNU/Linux, this is something like : $ cp pykota.schema /etc/ldap/schema Then edit /etc/ldap/slapd.conf and add a line to include the PyKota schema. You should have something like : # Schema and objectClass definitions include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema include /etc/ldap/schema/pykota.schema While this is not mandatory, it is recommended that you setup some indexes for some often accessed PyKota attributes. Actually, the LDAP schema included with PyKota doesn't allow indexes of another type than eq, but this will change in a next release. Here are the minimal indexes lines you may want to put in slapd.conf : # Indexes for PyKota index pykotaUserName eq index pykotaGroupName eq index pykotaPrinterName eq index pykotaLastJobIdent eq Finally, restart the OpenLDAP server : $ /etc/init.d/slapd restart With an LDAP backend, PyKota will need some branches in your LDAP directory to put its own datas. You can configure PyKota to either attach its datas to your existing users and groups, or to put them in their own ou. But some ous dedicated to PyKota are needed in any case, so the best bet may be to put all PyKota's datas below an ou=PyKota branch. While this will separate these datas from your existing users and groups entries, this may ease the maintainance. PyKota needs at least an ou for printers, for users quotas, for groups quotas, for print jobs, and for pointers to the last job of each printer. In the future, this last ou may disappear as its content will probably be attached to each printer. Actually PyKota doesn't create these ous for you, because it's difficult to guess what is the best configuration for you. So you have to create them by yourself, either directly with a text editor and the ldapadd command, or with some specialized tool like gq. Once you have chosen and created your directory structure, you have to modify PyKota's configuration files /etc/pykota/pykota.conf and /etc/pykota/pykotadmin.conf to set some LDAP specific options and binding dns. The easiest is probably to give a look at pykota/conf/pykota.conf.sample to see all the options that are needed. Adapt the values to your own configuration, and finally initialize your Quota Storage with the help of the edpykota command. A MySQL Storage Backend is planned, but it actually doesn't exist. A Berkeley DB Storage Backend is planned, but it actually doesn't exist. It seems that remote storage won't be possible with such a backend, so in other terms this means that you will have a different quota database on each print server. This may still prove to be useful for small configurations. For each Print Server on which you plan to implement the print quota mechanism, you have, of course, to have an already working printing environment. Currently PyKota works with either CUPS or LPRng, but more printing systems may be added in the future. Here's the list of software you have to install on each Print Server, version numbers are given as an indication of which was successfully tested, but older versions may work too. CUPS version 1.1 or above, or LPRng version 3.8.20 or above (it probably works with older versions but this is untested). You can download them from http://www.cups.org or http://lprng.sourceforge.net Python version 2.1 or above. You can download it from http://www.python.org. Quota Storage client libraries, depending on your Quota Storage Backend : PostgreSQL backend : PostgreSQL client libraries. They must match the PostgreSQL version used on your Quota Storage Server. The PygreSQL python module. It must have been compiled against the same PostgreSQL client libraries. PygreSQL is normally included in PostgreSQL, but you may want to download it from http://www.pygresql.org OpenLDAP backend : OpenLDAP client libraries. They must match the OpenLDAP version used on your Quota Storage Server. The Python-LDAP python module. It must have been compiled against the same OpenLDAP client libraries. You may download this module from http://python-ldap.sourceforge.net MySQL backend : TODO Berkeley DB backend : TODO ucd-snmp or net-snmp tools, version 4.2.5 or above. You only need the snmpget command. You can download this software from http://www.sourceforge.net/projects/net-snmp/. You only need this if you plan to query your printers for their internal page counter via SNMP. netatalk version 1.6.1 or above. You only need the pap command. You can download this software from http://netatalk.sourceforge.net/. You only need this if you plan to query your printers for their internal page counter via AppleTalk. eGenix' mxDateTime Python module version 2.0.3 or above. It must match your default Python version. You can download it from http://www.egenix.com. Instead of downloading all these programs' sources and compiling them, which really is a boring task considering that many software are needed, you may prefer to look into the packages included with your GNU/Linux distribution of choice (if you use this operating system of course). Most, if not all, GNU/Linux distributions include all the software mentionned above, in the form of packages which are easier to install than sources tarballs. This is probably the same for the many *BSD distributions. Once all these software are installed, installing PyKota itself is a breeze. PyKota being written entirely in the Python language, which is interpreted, there's no need to compile anything. You just have to execute the installation script : $ python setup.py install The installation script will try to do a safe upgrade if needed. Also it will check if some needed software is missing or unavailable and will tell you so. This may be the case for example if you installed several versions of the Python language, and some Python modules are only available for one of them which is not the one you are actually running. On your first installation, the setup script will automatically create the /etc/pykota directory and put the sample configuration files conf/pykota.conf.sample and conf/pykotadmin.conf.sample there, after having renamed them respectively pykota.conf and pykotadmin.conf. Once copied there, you just have to modify these files to adapt them to your own setup. These files are heavily commented, so you should have no problem. Also their format is quite common, because it's the one used by Samba for example, or by .ini files under MS-Windows, so you may already be familiar with this syntax. In a future release, this documentation will include the complete reference for all configuration fields available. Keep in mind that PyKota can be really heavily customized, and can delegate some work to any external command of your choice. On later installations, the setup script won't modify any of your configuration files. However it will try to explain what have changed and encourages you to manually do the modifications which are needed. Please create a backup of the /etc/pykota directory before modifying anything. Under some circumstances, the setup PyKota may refuse to install PyKota until you have modified your configuration. Just do it and restart the installation script as described above. PyKota features some interesting possibilities which allow you to define options either globally so that they apply to all printers, or on a per printer basis. Please see the sample configuration files to see what I mean. In the simplest form, only a global section is needed. In more complex configurations, you will have to create one section per printer. Each section in the configuration files begins with a name between square brackets []. The name to use to define a particular printer section is the name of the print queue on which you want to set quotas. After you have modified PyKota's configuration files, you have to double check their permissions, otherwise your installation may be insecure or may not work at all. The main configuration file /etc/pykota/pykota.conf doesn't contain much sensitive information, so it can be made readable by anyone. If normal users read this file, at best they will learn the username and optional password of the read-only database user, so they won't be allowed to do any harm. On the other hand, the /etc/pykota/pykotadmin.conf file contains the read-write user's identity and password. You must then ensure that no normal user can read this file. It should only be readable by the root user, which is always the case, by the user your printing system is running as, and optionally by the print administrators, who are usually members of the lpadmin group. Under my Debian GNU/Linux system, with CUPS, here's how to do to give the correct permissions : $ chown root.root /etc/pykota/pykota.conf $ chmod 644 /etc/pykota/pykota.conf $ chown lp.lpadmin /etc/pykota/pykotadmin.conf $ chmod 640 /etc/pykota/pykotadmin.conf Now depending on your printing system, the configuration to do is particular. We will now see how to plug PyKota into your printing system. The easiest way to configure PyKota to be used for a particular CUPS print queue, is to modify the PPD file associated with this print queue. Say you want to set quotas on the HPLaser print queue. You then just have to modify the file /etc/cups/ppd/HPLaser.ppd. You will have to add the following lines somewhere near the beginning of this file : *% Print Quota System *cupsFilter: "application/vnd.cups-postscript 0 /usr/bin/pykota" The first line is a comment. The second one tells CUPS to launch PyKota's accounting filter just before sending the print job to the printer's hardware. You have to restart CUPS for this modification to take effect : $ /etc/init.d/cupsys restart Repeat the above procedure for each print queue on which you want to use PyKota. That's all ! NB : the above procedure only works with PPD files which don't already contain an *cupsFilter line. PostScript printers usually don't need this line, but other types of printers may need it. A different procedure exists for such printers, but it is not actually documented. Search the mailing list archives at http://cgi.librelogiciel.com/mailman/listinfo/pykota to learn how to do. In case of problem, the simplest way to solve it is currently to ask on PyKota's mailing list, describing the symptoms, as well as the hardware and software you use. In a future release of this document, a section dedicated to Frequently Asked Questions will be included. To plug PyKota into your LPRng setup, you have to modify the /etc/printcap. You just have to add the following lines to each queue on which you want to use PyKota : :achk=true :as=|/usr/bin/pykota You have to restart LPRng for this modification to take effect : $ /etc/init.d/lprng restart Repeat the above procedure for each print queue on which you want to use PyKota. That's all ! In case of problem, the simplest way to solve it is currently to ask on PyKota's mailing list, describing the symptoms, as well as the hardware and software you use. In a future release of this document, a section dedicated to Frequently Asked Questions will be included.