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

Revision 2139, 40.9 kB (checked in by jerome, 19 years ago)

Added the Log keyword property

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