root / pykota / trunk / docs / installation.sgml @ 2844

Revision 2844, 43.7 kB (checked in by jerome, 18 years ago)

Added some stuff about MySQL.
Removed confusing vocabulary.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
1<!-- $Id$ -->
4  <title id="installation">Installation</title>
6  <para>Last modified on $Date$</para>
8  <para>
9    Before being able to use <application>PyKota</application>, you have of course to
10    install it first. But before installing, you must carefully plan your installation.
11  </para>
13  <para>
14    First you have to determine which machine will be the <application>PyKota</application>
15    database server. The database server is the host responsible
16    for keeping a centralized database of print usage for all your printers, users and groups.
17  </para>
19  <para>
20    Then you have to list all the <firstterm>Print Servers</firstterm> for which
21    you plan to use print quota facilities.
22  </para>
24  <para>
25    With most database backends, several print servers can share a single database, however
26    as we'll see later this is not possible if you choose to use <application>SQLite</application>
27    as your print quota database backend.
28  </para>
30  <para>
31    Finally you have to download <application>PyKota</application>'s latest version
32    or buy an official package, from
33    <ulink url=""></ulink>.
34    If you've just bought an official package, then as soon as you've receive it you
35    have to decompress and visit its archive, to do so just type the following commands :
36    <screen>
37jerome@nordine:~$ tar -zxf pykota-1.24_official.tar.gz   
38jerome@nordine:~$ cd pykota-1.24_official
40    </screen>
41  </para>
43  <para>
44    You can see many files in this directory, the first ones to read are <filename>README</filename>,
45    then <filename>COPYING</filename> and <filename>LICENSE</filename>. They will give you
46    basic installation instructions and explain the licensing terms under which
47    <application>PyKota</application> is distributed. Of course they are also mostly
48    boring to read ! Detailed installation and operating instructions are defined
49    in the <filename>./docs</filename> directory, in the form of <acronym>SGML</acronym>
50    documentation in the <ulink url="">DocBook</ulink> format.
51    You have to compile these files into readable documentation like the <acronym>HTML</acronym>
52    or <acronym>PDF</acronym> formats, or buy an official <application>PyKota</application> package
53    which already contains these compiled forms of the documentation. Of course you already
54    know this because that's what you are currently reading !
55  </para>
57  <para>
58    Now we will see what has to be done on each of the servers we are planning to use.
59    <note>
60      <title>Note</title>
61      <para>
62        Of course, depending on the size of your network, you may very well
63        use the same machine as both a Print Server and a Storage Server.
64        This is especially the case if you've got only one server.
65      </para>
66    </note> 
67  </para>
69  <sect1>
70    <title>Storage Server Installation</title>
72    <para>
73      Depending on <application>PyKota</application>'s version number, different
74      types of storage backends may be supported, so we will see for each one of
75      them how to configure it.
76    </para>
78    <sect2>
79      <title>PostgreSQL</title>
81      <para>
82        <application>PostgreSQL</application> is an <firstterm>Object Relationnal DataBase
83        Management System</firstterm> distributed under a <firstterm>Free Software</firstterm>
84        license from the
85        <ulink url=""></ulink>
86        web site. It certainely is the free <acronym>RDBMS</acronym> which has the most advanced
87        features, and is widely used all over the world.
88      </para>
90      <para>
91        To configure your Storage Server, you must have PostgreSQL already working.
92        The complete installation of <application>PostgreSQL</application> is not covered by
93        the present manual, please refer to your system's documentation or to
94        <ulink url=""></ulink> for
95        details.
96      </para>
98      <para>
99        One thing you have to check, though, is that every Print Server on which you
100        want to install the print quota mechanism, must be able to connect to the
101        <application>PostgreSQL</application> server. In the default installation of
102        <application>PostgreSQL</application> this may not be the case for security reasons, except if both
103        servers are in fact the same machine. In any case, it is recommended that you
104        check the <filename>/etc/postgresql/pg_hba.conf</filename> file and modify it if
105        needed. This file is self documented and its modification is straightforward.
106        You also have to make sure that <application>PostgreSQL</application> accepts <acronym>TCP/IP</acronym> connections.
107        To do so you either have to launch it with the <option>-i</option> option or
108        modify the <filename>/etc/postgresql/postgresql.conf</filename> file, which is
109        self documented and easy to modify too. Allowing <acronym>TCP/IP</acronym> connections
110        is not necessary though if your print quota database server and your Print Server are
111        the very same host.
112      </para> 
114      <para>
115        Here's an excerpt from a <filename>pg_hba.conf</filename> file. This one rejects all
116        connections to PyKota's database excepted when made from the same host by <application>PostgreSQL</application> users
117        <literal>pykotauser</literal> or <literal>pykotaadmin</literal> with the correct password.
119        local all    postgres                              ident sameuser
120        local all    all                                   reject
121        host  pykota pykotauser crypt
122        host  pykota pykotaadmin crypt
123        host  pykota all reject
125     </para>
127     <para>
128        Of course if your print server and your database servers have different <acronym>IP</acronym>
129        addresses, you have to replace the <literal></literal> address above with your print
130        server's <acronym>IP</acronym> address. As an alternative, you could still keep these
131        lines and add similar lines with other <acronym>IP</acronym> addresses if you have several
132        print servers for which you want a single centralized database.
133        <tip>
134          <title>Tip</title>
135          <para>
136            Don't forget to restart <application>PostgreSQL</application> if you modify
137            any of its configuration files, in order for the changes to take effect.
138          </para>
139        </tip> 
140      </para>
142      <para>
143        Be careful, you may be unable to connect from a Print Server to the <application>PostgreSQL</application>
144        server even if the configuration is correct. Sometimes your connections may be blocked by
145        one or more network firewalls along the route from one machine to the other. If this
146        is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm>
147        to not filter the IP port used by <application>PostgreSQL</application>, which is
148        usually port <literal>5432/tcp</literal>.
149        <note>
150          <title>Note</title>
151          <para>
152            The TCP/IP network port used by PostgreSQL may be different. When in doubt, ask your
153            <firstterm>System Administrator</firstterm> for the correct value.
154          </para>
155        </note> 
156      </para>
158      <para>
159        Now that your <application>PostgreSQL</application> server is up and running, and
160        is waiting for your connections, you have to create the print quota database.
161        To do so, you'll have to feed <application>PostgreSQL</application> with the
162        <filename>pykota-1.24/initscripts/postgresql/pykota-postgresql.sql</filename> file.
163        This file will create a print quota database administrator in the <application>PostgreSQL</application> system, then create an empty
164        print quota database and set some permissions on it. The print quota database administrator
165        is the <application>PostgreSQL</application>'s user used to manage the quota database.
166        The print quota database Administrator is not present in the quota database
167        itself, he is only defined in <application>PostgreSQL</application> and don't
168        have to exist on any system, nor in the print quota database. His default name
169        is <literal>pykotaadmin</literal>.
170        A print quota database read-only user is also created under the name of <literal>pykotauser</literal>.
171        This read-only user is used by <application>PyKota</application> to connect to the
172        print quota database when an user who is not a <application>PyKota</application> administrator
173        <footnote><para>a <application>PyKota</application> administrator is an user who can read the <filename>~pykota/pykotadmin.conf</filename> file.</para></footnote>
174        launches a pykota command. This prevents normal
175        users from being able to modify their own, or other users', quota information.
176        The database which will be created will be named <literal>pykota</literal> by default.
177        <note>
178          <title>Note</title>
179          <para>
180            You can choose other names if you want, just modify the
181            <filename>initscripts/postgresql/pykota-postgresql.sql</filename> file
182            accordingly, and report your changes into <application>PyKota</application>'s
183            configuration files.
184          </para>
185        </note> 
186      </para>
188      <para>
189        To run this script, you can use the <command>psql</command> frontend to
190        <application>PostgreSQL</application>, but your priviledges must be sufficient
191        to be allowed to create users and databases. You can launch <command>psql</command>
192        as the <literal>postgres</literal> user which is <application>PostgreSQL</application>'s
193        default administrator, and connect to the default database named <literal>template1</literal>.
194        From a command line interpreter (i.e. shell), type the following commands :
195        <screen>
196jerome@nordine:~$ cd pykota-1.24_official/initscripts/postgresql
197jerome@nordine:~/pykota-1.24_official/initscripts$ psql -h localhost -U postgres template1
198Welcome to psql, the PostgreSQL interactive terminal.
200Type:  \copyright for distribution terms
201       \h for help with SQL commands
202       \? for help on internal slash commands
203       \g or terminate with semicolon to execute query
204       \q to quit
206template1=# \i pykota-postgresql.sql
207            ... a lot of output lines
209        </screen>
210        <note>
211          <title>Note</title>
212          <para>
213            If you use RPM or DEB packages, usually the
214            <filename>pykota-postgresql.sql</filename> file gets installed into the
215            <filename>/usr/share/pykota/postgresql</filename> directory, along
216            with a README file.
217          </para>
218        </note> 
219      </para>
221      <para>
222        For security reasons, you may want to set passwords in
223        <application>PostgreSQL</application> for the
224        <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users.
225        Otherwise any user able to connect to
226        <application>PostgreSQL</application> on your print quota database server
227        could connect to the quota database, and either see it, or even modify it without problem.
228      </para>
230      <para>
231        To do so, just type the following lines while still being at the <command>psql</command>
232        prompt (replace the password values by your own, and do the same for the <literal>pykotauser</literal> user) :
233        <screen>
234pykota=# ALTER USER pykotaadmin PASSWORD 'somepassword';
236pykota=# \q
238        </screen>
239      </para>
241      <para>
242        The <literal>\q</literal> command above will quit the <command>psql</command>
243        program and return you to the shell's command line prompt.
244      </para>
246      <para>
247        To improve security further, you could encrypt your database connections, or
248        take any other step as needed. Please refer to <application>PostgreSQL</application>'s
249        documentation for details.
250        <warning>
251          <title>Warning</title>
252          <para>
253            Defining passwords may not be sufficient if your database access rule is
254            set to <literal>trust</literal> in the <filename>/etc/postgresql/pg_hba.conf</filename>.
255            Again, please refer to <application>PostgreSQL</application>'s documentation
256            for details. Also, passwords will fly unencrypted over the network by default,
257            so be sure to take any necessary step to secure your database server from
258            unauthorized use. This has nothing to do with <application>PyKota</application>
259            though, it is just a general rule to keep in mind.
260          </para>
261        </warning> 
262      </para>
264      <para>
265        If no error occured, then your print quota database is ready to be used.
266        Now you can let the print quota database server alone, the remaining work
267        will have to be done on each one of the print servers which will
268        use this particular print quota database server.
269        <tip>
270          <title>Tip</title>
271          <para>
272            If an error occured, maybe your PostgreSQL version is too old, or
273            an unexpected problem (like a bug) happened. Please contact us via email so that we
274            can try to fix the problem. Thanks in advance.
275          </para>
276        </tip> 
277      </para>
279    </sect2> 
281    <sect2>
282      <title>LDAP</title>
284      <para>
285        Any <acronym>LDAP</acronym> server, and particularly <application>OpenLDAP</application>, can be used
286        as a print quota database backend.
287        Some other LDAP servers can be used, but this is currently untested in production.
288      </para>
290      <para>
291        <application>OpenLDAP</application> is a Lightweight Directory Access Protocol server
292        implementation published as Free Software.
293        You can download it from <ulink url=""></ulink>.
294      </para>
296      <para>
297        To use <application>OpenLDAP</application> as your print quota database backend, you have to copy the
298        <filename>pykota/initscripts/ldap/pykota.schema</filename> into <application>OpenLDAP</application>'s
299        schemas directory.
300        Under Debian GNU/Linux, this is something like :
301        <screen>       
302$ cp pykota.schema /etc/ldap/schema
303        </screen>
304        <note>
305          <title>Note</title>
306          <para>
307            If you use RPM or DEB packages, the
308            <filename>pykota.schema</filename> file is usually installed into the
309            <filename>/usr/share/pykota/ldap</filename> directory, along
310            with a README file, and may also be installed automatically in
311            your <acronym>LDAP</acronym> server's schemas directory.
312          </para>
313        </note> 
314     </para>
315     <para>   
316       Then edit <filename>/etc/ldap/slapd.conf</filename> and add a line to   
317       include the PyKota schema. You should have something
318       like :
319       <screen>   
320# Schema and objectClass definitions
321include         /etc/ldap/schema/core.schema
322include         /etc/ldap/schema/cosine.schema
323include         /etc/ldap/schema/nis.schema
324include         /etc/ldap/schema/inetorgperson.schema
325include         /etc/ldap/schema/pykota.schema
326        </screen>       
327      </para>
329      <para>
330        While this is not mandatory, it is recommended that you setup
331        some indexes for some often accessed PyKota attributes.
332        Here are the minimal indexes
333        lines you may want to put in <filename>slapd.conf</filename> :
334        <screen>
335# Indexes for PyKota
336index pykotaUserName pres,eq,sub
337index pykotaGroupName pres,eq,sub
338index pykotaPrinterName pres,eq,sub
339index pykotaBillingCode pres,eq,sub
340index pykotaLastJobIdent eq
341        </screen>
342      </para>
344      <para>
345        Now you must ensure that the DNs you'll use to bind to   
346        your OpenLDAP server don't have search queries size limits,
347        which gives for example (OpenLDAP 2.1.x or above) :
350# No Limits for PyKota's administrator and read-only user
351limits dn="cn=pykotaadmin,dc=example,dc=com" size.soft=-1 size.hard=soft
352limits dn="cn=pykotauser,dc=example,dc=com" size.soft=-1 size.hard=soft
355        Where pykotaadmin and pykotauser are the usernames used to bind to your
356        OpenLDAP server within PyKota, respectively in ReadWrite mode
357        (as set in pykotadmin.conf) and in ReadOnly mode (as set in pykota.conf).
358      </para>
360      <para>
361        Finally, stop the <application>OpenLDAP</application> server, generate
362        the index files, and restart <application>OpenLDAP</application>
363        <screen>   
364$ /etc/init.d/slapd stop
365$ slapindex
366$ /etc/init.d/slapd start
367        </screen>
368      </para>
370      <para>
371        With an <acronym>LDAP</acronym> backend, PyKota will need some branches
372        in your <acronym>LDAP</acronym> directory to put its own datas.
373        You can configure PyKota to either attach its datas to your existing
374        users and groups, or to put them in their own <literal>ou</literal>.
375        But some <literal>ou</literal>s dedicated to PyKota are needed in any case,
376        so the best bet may be to put all PyKota's datas below an <literal>ou=PyKota</literal>
377        branch. While this will separate these datas from your existing users and groups
378        entries, this may ease the maintainance.
379      </para>
381      <para>
382        PyKota needs at least an <literal>ou</literal> for printers, for users quotas, for
383        groups quotas, for print jobs, for billing codes, and for pointers to the last job of each printer.
384        In the future, this last <literal>ou</literal> may disappear as its content
385        will probably be attached to each printer.
386      </para>
388      <para>
389        Actually PyKota doesn't create these <literal>ou</literal>s for you, because it's
390        difficult to guess what is the best configuration for you. So you have to
391        create them by yourself, either directly with a text editor and the
392        <command>ldapadd</command> command, or with some specialized tool
393        like <command>gq</command>. You can look at the <filename>initscripts/ldap/pykota-sample.ldif</filename>
394        file to see which minimal branches are necessary.
395        <note>
396          <title>Note</title>
397          <para>
398            If you use RPM or DEB packages, usually the
399            <filename>pykota-sample.ldif</filename> file is installed into the
400            <filename>/usr/share/pykota/ldap</filename> directory, along
401            with a README file.
402          </para>
403        </note> 
404      </para>
406      <para>
407        If no error occured, then your print quota database is ready to be used.
408        Now you can let the print quota database server alone, the remaining work
409        will have to be done on each one of the print servers which will
410        use this particular print quota database server.
411        <tip>
412          <title>Tip</title>
413          <para>
414            If an error occured, maybe your OpenLDAP version is too old, or
415            an unexpected problem (like a bug) happened. Please contact us via email so that we
416            can try to fix the problem. Thanks in advance.
417          </para>
418        </tip> 
419      </para>
420    </sect2> 
422    <sect2>
423      <title>MySQL</title>
425      <para>
426        <application>MySQL</application> is supported but not documented for now.
427      </para>
428    </sect2> 
430    <sect2>
431      <title>SQLite</title>
433      <para>
434        <application>SQLite</application> is an embeddable Relationnal DataBase
435        distributed under a Free Software
436        license from the
437        <ulink url=""></ulink>
438        web site.
439        If is very easy to configure and use, offers a very small memory footprint,
440        is very fast, but can only be used on the print server because it doesn't include
441        a server daemon : the database is directly embedded in the application.
442      </para>
444      <para>
445        To configure your database, you must have SQLite already working.
446        The complete installation of <application>SQLite</application> is not covered by
447        the present manual, please refer to your system's documentation or to
448        <ulink url=""></ulink> for
449        details.
450      </para>
452      <para>
453        Once <application>SQLite</application> is installed, you have to decide where
454        you'll put your database. A good idea is to store it into the <literal>pykota</literal>
455        user's home directory. Then to create the database, just type :
457# sqlite3 ~pykota/pykota.db &lt;pykota/initscripts/sqlite/pykota.sqlite
458# chown pykota.pykota ~pykota/pykota.db
459# chmod 660 ~pykota/pykota.db
460# chown pykota.pykota ~pykota
462      </para>
463      <para>
464        If user <literal>pykota</literal> doesn't exist yet, then please
465        follow the instructions a bit below which explain how to install PyKota on the print server.
466      </para>
468      <para>
469        Once this is done, you'll want to set in <filename>~pykota/pykota.conf</filename> the
470        following lines in the <literal>[global]</literal> section :
472storagebackend : sqlitestorage
473storagename : /etc/pykota/pykota.db
475      </para>
476      <para>
477        Of course you'll want to replace the path on the <literal>storagename</literal> line
478        with the full path to the newly created <application>SQLite</application> database.
479      </para>
480      <para>
481        If no error occured, then your print quota database is ready to be used.
482        In case you need them, additional instructions are available in <filename>pykota/initscripts/sqlite/README.sqlite</filename>
483        <tip>
484          <title>Tip</title>
485          <para>
486            If an error occured, maybe your SQLite version is too old, or
487            an unexpected problem (like a bug) happened. Please contact us via email so that we
488            can try to fix the problem. Thanks in advance.
489          </para>
490        </tip> 
491      </para>
492    </sect2> 
494    <sect2>
495      <title>Berkeley DB</title>
497      <para>
498        A <application>Berkeley DB</application> backend is planned, but it actually
499        doesn't exist. It seems that remote storage won't be possible with such a backend,
500        so in other terms this means that you will have a different quota database on
501        each print server. This may still prove to be useful for small configurations.
502      </para>
503    </sect2> 
504  </sect1> 
506  <sect1>
507    <title>Print Server Installation</title>
509    <para>
510      For each Print Server on which you plan to implement the print quota
511      mechanism, you have, of course, to have an already working printing environment.
512      Currently <application>PyKota</application> works with
513      <ulink url=""><application>CUPS</application></ulink>
514      but older releases also supported <ulink url=""><application>LPRng</application></ulink>.
515      <application>LPRng</application> support might be re-added in the future.
516    </para>
518    <para>
519      Here's the list of software you have to install on each Print Server, version numbers
520      are given as an indication of which was successfully tested, but older versions may
521      work too.
522      <itemizedlist>
523        <listitem>
524          <para>
525            <application>CUPS</application> version 1.1.14 or above.
526            You can download it from <ulink url=""></ulink>
527          </para>
528        </listitem> 
529        <listitem>
530          <para>
531            <application>Python</application> version 2.2 or above.
532            You can download it from <ulink url=""></ulink>.
533            While <application>PyKota</application> itself will try to preserve compatibility
534            with <application>Python</application> version 2.2 for the near future, some <application>Python</application>
535            modules which are needed by <application>PyKota</application> may require a more recent version
536            of this language.
537          </para>
538        </listitem> 
539        <listitem>
540          <para>
541            print quota database client libraries, depending on your print quota database backend :
542            <itemizedlist>
543              <listitem>
544                <para>
545                  PostgreSQL backend :
546                  <itemizedlist>
547                    <listitem>
548                      <para>
549                        <application>PostgreSQL</application> client libraries. They must match the <application>PostgreSQL</application>
550                        version used on your print quota database server.
551                      </para>
552                    </listitem> 
553                    <listitem>
554                      <para>
555                        The <application>PygreSQL</application> python module.
556                        <application>PygreSQL</application> is normally included in
557                        <application>PostgreSQL</application>, but you may want to
558                        download it from <ulink url=""></ulink>
559                      </para>
560                    </listitem> 
561                  </itemizedlist> 
562                </para>
563              </listitem> 
564              <listitem>
565                <para>
566                  OpenLDAP backend :
567                  <itemizedlist>
568                    <listitem>
569                      <para>
570                        <application>OpenLDAP</application> client libraries. They must match
571                        the <application>OpenLDAP</application> version used on your print quota database server.
572                      </para>
573                    </listitem> 
574                    <listitem>
575                      <para>
576                        The <application>Python-LDAP</application> python module.
577                        You may download this module from <ulink url=""></ulink>
578                      </para>
579                    </listitem> 
580                  </itemizedlist>
581                </para>
582              </listitem>
583              <listitem>
584                <para>
585                  MySQL backend :
586                  <itemizedlist>
587                    <listitem>
588                      <para>
589                        <application>MySQL</application> client libraries. They must match the <application>MySQL</application>
590                        version used on your database server.
591                      </para>
592                    </listitem> 
593                    <listitem>
594                      <para>
595                        The <application>Python-MySQL</application> python module, version 1.2.x or higher.
596                        You can download it from <ulink url=""></ulink>
597                      </para>
598                    </listitem> 
599                  </itemizedlist> 
600                </para>
601              </listitem>
602              <listitem>
603                <para>
604                  SQLite backend : SQLite is not a database server, but an embeddable database, so
605                  if you want to use it you MUST install SQLite on your print server. With
606                  <application>PostgreSQL</application>, <application>MySQL</application> or
607                  <application>OpenLDAP</application> you can store your datas on a different
608                  machine than the print server, but this is not possible with <application>SQLite</application>.
609                  <itemizedlist>
610                    <listitem>
611                      <para>
612                        <application>SQLite</application> version 3.2.1 or higher and its library.
613                        You can download it from
614                        <ulink url=""></ulink>
615                      </para>
616                    </listitem> 
617                    <listitem>
618                      <para>
619                        The <application>Python-SQLite</application> python module version 2.0.5 or higher.
620                        You can download it from
621                        <ulink url=""></ulink>
622                      </para>
623                    </listitem> 
624                  </itemizedlist>
625                </para>
626              </listitem>
627              <listitem>
628                <para>
629                  Berkeley DB backend : Not supported yet.
630                </para>
631              </listitem>
632            </itemizedlist> 
633          </para>
634        </listitem> 
635        <listitem>
636          <para>
637            <application>ucd-snmp</application> or <application>net-snmp</application> tools, version 4.2.5 or above. You only need
638            the <command>snmpget</command> command.
639            You can download this software from <ulink url=""></ulink>.
640            You only need this if you plan to query your printers for their internal page counter via SNMP.
641          </para>
642        </listitem> 
643        <listitem>
644          <para>
645            <application>netatalk</application> version 1.6.1 or above. You only need
646            the <command>pap</command> command.
647            You can download this software from <ulink url=""></ulink>.
648            You only need this if you plan to query your printers for their internal page counter via AppleTalk.
649          </para>
650        </listitem> 
651        <listitem>
652          <para>
653            eGenix' mxDateTime Python module version 2.0.3 or above. It must match your default Python version.
654            You can download it from <ulink url=""></ulink>.
655          </para>
656        </listitem> 
657        <listitem>
658          <para>
659            The Python acccelerator <application>Psyco</application>. It must match your default Python version.
660            You can download it from <ulink url=""></ulink>.
661            You only need this if you run on the <literal>x86</literal> architecture because
662            <application>Psyco</application> doesn't yet exist on other architectures.
663          </para>
664        </listitem> 
665        <listitem>
666          <para>
667            The <application>pysnmp</application> Python module version 3.4.2, 3.4.3 or 3.4.4 exclusively.
668            You can download it from <ulink url=""></ulink>.
669          </para>
670        </listitem> 
671        <listitem>
672          <para>
673            The <application>JAXML</application> Python module.
674            You can download it from <ulink url=""></ulink>.
675          </para>
676        </listitem> 
677        <listitem>
678          <para>
679            The <application>ReportLab</application> Toolkit Python module.
680            You can download it from <ulink url=""></ulink>.
681          </para>
682        </listitem> 
683        <listitem>
684          <para>
685            The <application>Python Imaging Library - PIL</application> module.
686            You can download it from <ulink url=""></ulink>.
687          </para>
688        </listitem> 
689        <listitem>
690          <para>
691            The <application>PyOSD</application> Python module.
692            You can download it from <ulink url=""></ulink>.
693          </para>
694        </listitem> 
695        <listitem>
696          <para>
697            The <application>pkpgcounter</application> Generic Page Description Language parser.
698            You can download it from <ulink url=""></ulink>.
699          </para>
700        </listitem> 
701        <listitem>
702          <para>
703            The <application>PyPAM</application> Python interface to <acronym>PAM</acronym>.
704            You'll need this if you plan to ask users to authenticate when printing through <command>pknotify</command>
705            and <command>pykoticon</command>. You don't need this module otherwise.
706            If needed, you can download it from <ulink url=""></ulink>.
707          </para>
708        </listitem> 
709      </itemizedlist> 
710    </para>
712    <para>
713      Instead of downloading all these programs' sources and compiling them, which really
714      is a boring task considering that many software are needed, you may prefer to look
715      into the packages included with your GNU/Linux distribution of choice (if you use
716      this operating system of course). Most, if not all, GNU/Linux distributions include
717      all the software mentionned above, in the form of packages which are easier to
718      install than sources tarballs. This is probably the same for the many *BSD
719      distributions.
720    </para>
722    <para>
723       You can check that all needed software is installed by launching the <command></command>
724       command :
725      <screen>     
726$ python     
727      </screen>
728    </para>
730    <para>
731      Once all these software are installed, installing PyKota itself is a breeze.
732      PyKota being written entirely in the Python language, which is interpreted,
733      there's no need to compile anything. You just have to execute the installation
734      script :
735      <screen>     
736$ python install     
737      </screen>
738    </para>
740    <para>
741      The setup script will automatically create the
742      <filename>/usr/share/pykota/conf</filename> directory and put the sample
743      configuration files <filename>conf/pykota.conf.sample</filename> and
744      <filename>conf/pykotadmin.conf.sample</filename> there, along with
745      a <filename>README</filename> file explaining their purpose.
746    </para>
748    <para>
749      Now you have to create a <literal>pykota</literal> system user and group. The <application>PyKota</application>
750      software will automatically search its configuration files in user <literal>pykota</literal>'s
751      home directory. For example we could create the user and group, and set <filename>/etc/pykota</filename>
752      as the home directory, but any other home directory will do :
754    adduser --system --group --home /etc/pykota --gecos PyKota pykota
756    </para>
758    <para>
759      You now have to copy the sample configuration files into the <filename>~pykota</filename>
760      directory, under the respective names <filename>pykota.conf</filename> and
761      <filename>pykotadmin.conf</filename>. Once copied there, you just
762      have to modify these files to adapt them to your own setup.
763      These files are heavily commented, so you should have no problem.
764      Also their format is quite common, because it's the one used by
765      <application>Samba</application> for example, or by <literal>.ini</literal>
766      files under <application>MS-Windows</application>, so you may already
767      be familiar with this syntax.
768      In a future release, this documentation will include the complete
769      reference for all configuration fields available. Keep in mind that
770      <application>PyKota</application> can be really heavily customized, and can delegate some work
771      to any external command of your choice.
772    </para>
774    <para>
775      Please create a backup copy of the <filename>~pykota</filename>
776      directory before modifying a working installation.
777    </para>
779    <para>
780      PyKota features some interesting possibilities which allow you to
781      define options either globally so that they apply to all printers,
782      or on a per printer basis. Please see the sample configuration files
783      to see what I mean. In the simplest form, only a <literal>[global]</literal> section is
784      needed. In more complex configurations, you will have to create
785      one section per printer. Each section in the configuration files
786      begins with a name between square brackets <literal>[]</literal>.
787      The name to use to define a particular printer section is the name
788      of the print queue you want to manage with PyKota.
789    </para>
791    <para>
792      After you have modified <application>PyKota</application>'s configuration files, you have to
793      double check their permissions, otherwise your installation may be
794      insecure or may not work at all.
795      The main configuration file <filename>~pykota/pykota.conf</filename>
796      doesn't contain much sensitive information, so it can be made
797      readable by anyone. If normal users read this file, at best they
798      will learn the username and optional password of the read-only
799      database user. This means that beside being allowed to read all the contents of
800      the quota database, they won't be allowed to modify or delete it.
801      On the other hand, the <filename>~pykota/pykotadmin.conf</filename>
802      file contains the read-write user's identity and password. You must then
803      ensure that no normal user can read this file. It should only be readable
804      by the <literal>root</literal> user, which is always the case, and by
805      <application>PyKota</application> administrators. In addition,
806      users for which <application>CUPS</application> doesn't run as user <literal>root</literal> will
807      have to ensure that the user their printing system is run as
808      can read both of these files. An easy way to do so is to put the <literal>lp</literal> user
809      (for example) into the <literal>pykota</literal> system group, then
810      to give the correct permissions to <application>PyKota</application>'s configuration files :
811      <screen>
812$ chown pykota.pykota ~pykota/pykota.conf     
813$ chmod 644 ~pykota/pykota.conf     
814$ chown pykota.pykota ~pykota/pykotadmin.conf     
815$ chmod 640 ~pykota/pykotadmin.conf     
816      </screen>
818      <warning>
819        <title>Warning</title>
820        <para>
821          All the users allowed to read the <filename>~pykota/pykotadmin.conf</filename>
822          are considered to be <application>PyKota</application> administrators. So be
823          careful with these files permissions.
824        </para>
825      </warning>
826    </para>
828    <para>
829      On some systems, you may be able to strenghten permissions like this :
830      <screen>
831$ chown pykota.pykota ~pykota/pykota.conf     
832$ chmod 640 ~pykota/pykota.conf     
833$ chown pykota.pykota ~pykota/pykotadmin.conf     
834$ chmod 600 ~pykota/pykotadmin.conf     
835      </screen>
836    </para>
838    <para>
839      And on other ones, you may need to relax them, and change the files' owner :
840      <screen>
841$ chown lp.pykota ~pykota/pykota.conf     
842$ chmod 640 ~pykota/pykota.conf     
843$ chown lp.pykota ~pykota/pykotadmin.conf     
844$ chmod 640 ~pykota/pykotadmin.conf     
845      </screen>
846    </para>
848    <para>
849      This all depends on the printing system you are using, and the user the
850      printing system is usually running as. You need to remember three things :
852      <itemizedlist>
853        <listitem>
854          <para>
855            The user your printing system runs as MUST be allowed to read
856            both <application>PyKota</application>'s configuration files.
857          </para> 
858        </listitem> 
859        <listitem>       
860          <para>
861            Any user who can read <filename>pykotadmin.conf</filename>
862            is a <application>PyKota</application> administrator, and
863            can do whatever he wants to the print quota database.
864          </para>
865        </listitem>
866        <listitem>       
867          <para>
868            If <filename>cupsd.conf</filename> contains <literal>RunAsUser</literal>, then
869            you won't be able to authenticate users with <command>pknotify</command> and <command>pykoticon</command>.
870            Also in this case you may have to make <application>PyKota</application>'s configuration files
871            owned by the user <application>CUPS</application> runs as.
872          </para>
873        </listitem>
874      </itemizedlist> 
875    </para>
877    <para>
878      Don't forget to restart your print server sofware if you changed group membership for the user it runs
879      as, otherwise your change wouldn't be taken into account.
880    </para>
882    <para>
883      Now depending on your printing system, the configuration to do is particular.
884      We will now see how to plug PyKota into <application>CUPS</application> since <application>LPRng</application>
885      is not supported anymore.
886    </para>
888    <sect2>
889      <title>With CUPS</title>
891      <para>
892        From version 1.16alpha7 on, configuring <application>PyKota</application> to integrate
893        within <application>CUPS</application> is more than easy.
894      </para>
896      <para>
897        You just have to create a symbolic link to the <command>cupspykota</command>
898        command in <application>CUPS</application>' backend directory :
899        <screen>       
900$ cd /usr/lib/cups/backend       
901$ ln -s /usr/share/pykota/cupspykota cupspykota
902        </screen>
903      </para>
905      <para>
906        You have to restart <application>CUPS</application> for this modification to
907        take effect :
908        <screen>
909$ /etc/init.d/cupsys restart       
910        </screen>
911      </para>
913      <para>
914        Now point your web browser to CUPS configuration page, usually at
915        <ulink url="http://localhost:631">http://localhost:631</ulink> on
916        your print server.
917      </para>
919      <para>
920        Then when creating new printers or reconfiguring existing ones, just
921        choose devices which are <literal>PyKota managed</literal>
922        <footnote>
923          <para>
924            Debian 3.0 Woody is known to have problems : CUPS 1.1.14 doesn't automatically
925            detect <literal>PyKota managed</literal> devices. So you have to manually
926            modify CUPS' <filename>printers.conf</filename> file as explained in
927            PyKota's toplevel <filename>README</filename> file.
928          </para>
929        </footnote>
930        instead of
931        normal devices. You've got one <literal>PyKota managed</literal> device
932        for each regular device available from CUPS, so just choose the appropriate
933        one.
934      </para>
936      <para>
937        Repeat the above procedure for each print queue on which you want to use
938        PyKota. That's all !
939      </para>
941      <sect3>
942        <title>Troubleshooting</title>
943        <para>
944          In case of problem, the simplest way to solve it is currently
945          to ask on PyKota's mailing list, describing the symptoms, as
946          well as the hardware and software you use.
947        </para>
949        <para>
950          A searchable FAQ is now available at
951          <ulink url=""></ulink>.
952          A FAQ entry explaining in great details how to diagnose a problem correctly is
953          available at
954          <ulink url=""></ulink>.
955        </para>
957        <para>
958          You can also ask questions on IRC :
959          <screen>
961/join #pykota
962          </screen>
963        </para> 
964      </sect3> 
966    </sect2>
968  </sect1> 
Note: See TracBrowser for help on using the browser.