InstallationLast 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 PyKotaStorage 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.22_official.tar.gz
jerome@nordine:~$ cd pykota-1.22_official
jerome@nordine:~/pykota-1.22_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.
Note
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.
Storage Server Installation
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.
PostgreSQLPostgreSQL 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 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.
Here's an excerpt from a pg_hba.conf file. This one rejects all
connections to PyKota's database excepted when made from the same host by PostgreSQL users
pykotauser or pykotaadmin with the correct password.
local all postgres ident sameuser
local all all reject
host pykota pykotauser 127.0.0.1 255.255.255.255 crypt
host pykota pykotaadmin 127.0.0.1 255.255.255.255 crypt
host pykota all 127.0.0.1 255.255.255.255 reject
Of course if your print server and your database servers have different IP
addresses, you have to replace the 127.0.0.1 address above with your print
server's IP address. As an alternative, you could still keep these
lines and add similar lines with other IP addresses if you have several
print servers for which you want a single centralized database.
Tip
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.
Note
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-1.22/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 an user who is not a PyKota administrator
a PyKota administrator is an user who can read the ~pykota/pykotadmin.conf file.
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.
Note
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 files.
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.22_official/initscripts/postgresql
jerome@nordine:~/pykota-1.22_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=#
Note
If you use RPM or DEB packages, usually the
pykota-postgresql.sql file gets installed into the
/usr/share/pykota/postgresql directory, along
with a README file.
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.22_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.
Warning
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.
Tip
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 fix the problem. Thanks in advance.
LDAP
Any LDAP server, and particularly OpenLDAP, can be used
as a Quota Storage Backend.
Some other LDAP servers can be used, but this is currently untested in production.
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 into OpenLDAP's
schemas directory.
Under Debian GNU/Linux, this is something like :
$ cp pykota.schema /etc/ldap/schema
Note
If you use RPM or DEB packages, the
pykota.schema file is usually installed into the
/usr/share/pykota/ldap directory, along
with a README file, and may also be installed automatically in
your LDAP server's schemas directory.
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.
Here are the minimal indexes
lines you may want to put in slapd.conf :
# Indexes for PyKota
index pykotaUserName pres,eq,sub
index pykotaGroupName pres,eq,sub
index pykotaPrinterName pres,eq,sub
index pykotaLastJobIdent eq
Now you must ensure that the DNs you'll use to bind to
your OpenLDAP server don't have search queries size limits,
which gives for example (OpenLDAP 2.1.x or above) :
# No Limits for PyKota's administrator and read-only user
limits dn="cn=RWadmin,dc=example,dc=com" size.soft=-1 size.hard=soft
limits dn="cn=ROadmin,dc=example,dc=com" size.soft=-1 size.hard=soft
Where RWadmin and ROadmin are the usernames used to bind to your
OpenLDAP server within PyKota, respectively in ReadWrite mode
(as set in pykotadmin.conf) and in ReadOnly mode (as set in pykota.conf).
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. You can look at the initscripts/ldap/pykota-sample.ldif
file to see which minimal branches are necessary.
Note
If you use RPM or DEB packages, usually the
pykota-sample.ldif file is installed into the
/usr/share/pykota/ldap directory, along
with a README file.
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.
Tip
If an error occured, maybe your OpenLDAP version is too old, or
an unexpected problem (like a bug) happened. Please contact us via email so that we
can try to fix the problem. Thanks in advance.
MySQL
A MySQL Storage Backend is planned, but it actually
doesn't exist.
Berkeley DB
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.
Print Server Installation
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.14 or above, or LPRng
version 3.8.27 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.netPython version 2.1 or above.
You can download it from http://www.python.org.
While PyKota itself will try to preserve compatibility
with Python version 2.1 for the near future, some Python
modules which are needed by PyKota may mandate the use of a more recent version
of this language.
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.
The Python acccelerator Psyco. It must match your default Python version.
You can download it from http://psyco.sourceforge.net.
You only need this if you run on the x86 architecture because
Psyco doesn't yet exist on other architectures.
The pysnmp Python module version 3.4.2 or 3.4.3 exclusively.
You can download it from http://pysnmp.sourceforge.net.
The JAXML Python module.
You can download it from http://www.librelogiciel.com/software/.
The ReportLab Toolkit Python module.
You can download it from http://www.reportlab.org.
The Python Imaging Library - PIL module.
You can download it from http://www.pythonware.com.
The PyOSD Python module.
You can download it from http://repose.cx/pyosd/.
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.
You can check that all needed software is installed by launching the checkdeps.py
command :
$ python checkdeps.py
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 setup script will automatically create the
/usr/share/pykota/conf directory and put the sample
configuration files conf/pykota.conf.sample and
conf/pykotadmin.conf.sample there, along with
a README file explaining their purpose.
Now you have to create a pykota system user and group. The PyKota
software will automatically search its configuration files in user pykota's
home directory. For example we could create the user and group, and set /etc/pykota
as the home directory, but any other home directory will do :
adduser --system --group --home /etc/pykota --gecos PyKota pykota
You now have to copy the sample configuration files into the ~pykota
directory, under the respective names 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.
Please create a backup copy of the ~pykota
directory before modifying a working installation.
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 ~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. This means that beside being allowed to read all the contents of
the quota database, they won't be allowed to modify or delete it.
On the other hand, the ~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, and by
PyKota administrators. In addition, LPRng
users, or users for which CUPS doesn't run as user root will
have to ensure that the user their printing system is run as
can read both of these files. An easy way to do so is to put the lp user
(for example) into the pykota system group, then
to give the correct permissions to PyKota's configuration files :
$ chown pykota.pykota ~pykota/pykota.conf
$ chmod 644 ~pykota/pykota.conf
$ chown pykota.pykota ~pykota/pykotadmin.conf
$ chmod 640 ~pykota/pykotadmin.conf
Warning
All the users allowed to read the ~pykota/pykotadmin.conf
are considered to be PyKota administrators. So be
careful with these files permissions.
On some systems, you may be able to strenghten permissions like this :
$ chown pykota.pykota ~pykota/pykota.conf
$ chmod 640 ~pykota/pykota.conf
$ chown pykota.pykota ~pykota/pykotadmin.conf
$ chmod 600 ~pykota/pykotadmin.conf
And on other ones, you may need to relax them, and change the files' owner :
$ chown lp.pykota ~pykota/pykota.conf
$ chmod 640 ~pykota/pykota.conf
$ chown lp.pykota ~pykota/pykotadmin.conf
$ chmod 640 ~pykota/pykotadmin.conf
This all depends on the printing system you are using, and the user the
printing system is usually running as. You need to remember two things :
The user your printing system runs as MUST be allowed to read
both PyKota's configuration files.
Any user who can read pykotadmin.conf
is a PyKota administrator, and
can do whatever he wants to the print quota database.
Don't forget to restart your print server sofware if you changed group membership for the user it runs
as, otherwise your change wouldn't be taken into account.
Now depending on your printing system, the configuration to do is particular.
We will now see how to plug PyKota into your printing system.
With CUPS
From version 1.16alpha7 on, configuring PyKota to integrate
within CUPS is more than easy.
You just have to create a symbolic link to the cupspykota
command in CUPS' backend directory :
$ cd /usr/lib/cups/backend
$ ln -s /usr/share/pykota/cupspykota cupspykota
You have to restart CUPS for this modification to
take effect :
$ /etc/init.d/cupsys restart
Now point your web browser to CUPS configuration page, usually at
http://localhost:631 on
your print server.
Then when creating new printers or reconfiguring existing ones, just
choose devices which are PyKota managed
Debian 3.0 Woody is known to have problems : CUPS 1.1.14 doesn't automatically
detect PyKota managed devices. So you have to manually
modify CUPS' printers.conf file as explained in
PyKota's toplevel README file.
instead of
normal devices. You've got one PyKota managed device
for each regular device available from CUPS, so just choose the appropriate
one.
Repeat the above procedure for each print queue on which you want to use
PyKota. That's all !
Troubleshooting
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.
You can now also ask us questions on IRC :
/server irc.freenode.net
/join #pykota
With LPRng
For each printer on which you want to use PyKota, just modify the printer's
entry in /etc/printcap : you have to add
the three following lines :
:achk=true:\
:as=/usr/share/pykota/lprngpykota:\
:ae=/usr/share/pykota/lprngpykota:\
This will tell LPRng to activate accounting, and use the lprngpykota
accounting filter both at the start and at the end of printing.
Repeat the above procedure for each print queue on which you want to use
PyKota. That's all !
When all modifications are done, just save the /etc/printcap file
and restart LPRng for the changes to take effect :
$ /etc/init.d/lprng restart
Troubleshooting
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.
You can now also ask us questions on IRC :
/server irc.freenode.net
/join #pykota