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

Revision 2943, 50.0 kB (checked in by jerome, 18 years ago)

Improved setup documentation wrt CUPS 1.2 or higher because
of the change in how CUPS runs backends in restricted mode.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
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    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>
18 
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>
23 
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>
29 
30  <para>
31    Finally you have to download <application>PyKota</application>'s latest version
32    or buy an official package, from
33    <ulink url="http://www.pykota.com/software/pykota">http://www.pykota.com/software/pykota</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
39jerome@nordine:~/pykota-1.24_official$
40    </screen>
41  </para>
42 
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="http://www.docbook.org">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>
56 
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 database server.
64        This is especially the case if you've got only one server.
65      </para>
66    </note> 
67  </para>
68 
69  <sect1>
70    <title>Database server installation</title>
71   
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>
77   
78    <sect2>
79      <title>PostgreSQL</title>
80     
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="http://www.postgresql.org">http://www.postgresql.org</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>
89     
90      <para>
91        To configure your database, 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="http://www.postgresql.org">http://www.postgresql.org</ulink> for
95        details.
96      </para>
97     
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> 
113     
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.
118<screen>        
119        local all    postgres                              ident sameuser
120        local all    all                                   reject
121        host  pykota pykotauser  127.0.0.1 255.255.255.255 crypt
122        host  pykota pykotaadmin 127.0.0.1 255.255.255.255 crypt
123        host  pykota all         127.0.0.1 255.255.255.255 reject
124</screen>
125     </para>
126     
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>127.0.0.1</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>
141     
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>
157     
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_official/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        The <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users by
178        default respectively have <literal>readwritepw</literal> and <literal>readonlypw</literal>
179        as their passwords.
180        <note>
181          <title>Note</title>
182          <para>
183            You can choose other names and passwords if you want by modifying the
184            <filename>initscripts/postgresql/pykota-postgresql.sql</filename> file
185            accordingly, and report your changes into <application>PyKota</application>'s
186            configuration files.
187          </para>
188        </note> 
189      </para>
190     
191      <para>
192        To run this script, you can use the <command>psql</command> frontend to
193        <application>PostgreSQL</application>, but your priviledges must be sufficient
194        to be allowed to create users and databases. You can launch <command>psql</command>
195        as the <literal>postgres</literal> user which is <application>PostgreSQL</application>'s
196        default administrator, and connect to the default database named <literal>template1</literal>.
197        From a command line interpreter (i.e. shell), type the following commands :
198        <screen>
199jerome@nordine:~$ cd pykota-1.24_official/initscripts/postgresql
200jerome@nordine:~/pykota-1.24_official/initscripts$ psql -h localhost -U postgres template1
201Welcome to psql, the PostgreSQL interactive terminal.
202
203Type:  \copyright for distribution terms
204       \h for help with SQL commands
205       \? for help on internal slash commands
206       \g or terminate with semicolon to execute query
207       \q to quit
208
209template1=# \i pykota-postgresql.sql
210            ... a lot of output lines
211pykota=#       
212        </screen>
213        <note>
214          <title>Note</title>
215          <para>
216            If you use RPM or DEB packages, usually the
217            <filename>pykota-postgresql.sql</filename> file gets installed into the
218            <filename>/usr/share/pykota/postgresql</filename> directory, along
219            with a README file.
220          </para>
221        </note> 
222      </para>
223     
224      <para>
225        If you want to you can change passwords later in
226        <application>PostgreSQL</application> for the
227        <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users.
228        To do so, just type the following lines while still being at the <command>psql</command>
229        prompt (replace the password values by your own :
230        <screen>
231pykota=# ALTER USER pykotaadmin PASSWORD 'somepassword';
232ALTER USER
233pykota=# ALTER USER pykotauser PASSWORD 'anotherpassword';
234pykota=# \q
235jerome@nordine:~/pykota-1.24_official/initscripts/postgresql$
236        </screen>
237      </para>
238     
239      <para>
240        The <literal>\q</literal> command above will quit the <command>psql</command>
241        program and return you to the shell's command line prompt.
242      </para>
243     
244      <para>
245        To improve security further, you could encrypt your database connections, or
246        take any other step as needed. Please refer to <application>PostgreSQL</application>'s
247        documentation for details.
248        <warning>
249          <title>Warning</title>
250          <para>
251            Defining passwords may not be sufficient if your database access rule is
252            set to <literal>trust</literal> in the <filename>/etc/postgresql/pg_hba.conf</filename>.
253            Again, please refer to <application>PostgreSQL</application>'s documentation
254            for details. Also, passwords will fly unencrypted over the network by default,
255            so be sure to take any necessary step to secure your database server from
256            unauthorized use. This has nothing to do with <application>PyKota</application>
257            though, it is just a general rule to keep in mind.
258          </para>
259        </warning> 
260      </para>
261     
262      <para>
263        For more details, please see <filename>initscripts/mysql/README.mysql</filename>.
264      </para>
265     
266      <para>
267        If no error occured, then your print quota database is ready to be used.
268        Now you can let the print quota database server alone, the remaining work
269        will have to be done on each one of the print servers which will
270        use this particular print quota database server.
271        <tip>
272          <title>Tip</title>
273          <para>
274            If an error occured, maybe your PostgreSQL version is too old, or
275            an unexpected problem (like a bug) happened. Please contact us via email so that we
276            can try to fix the problem. Thanks in advance.
277          </para>
278        </tip> 
279      </para>
280     
281    </sect2> 
282   
283    <sect2>
284      <title>LDAP</title>
285     
286      <para>
287        Any <acronym>LDAP</acronym> server, and particularly <application>OpenLDAP</application>, can be used
288        as a print quota database backend.
289        Some other LDAP servers can be used, but this is currently untested in production.
290      </para>
291     
292      <para>
293        <application>OpenLDAP</application> is a Lightweight Directory Access Protocol server
294        implementation published as Free Software.
295        You can download it from <ulink url="http://www.openldap.org">http://www.openldap.org</ulink>.
296      </para>
297     
298      <para>
299        To use <application>OpenLDAP</application> as your print quota database backend, you have to copy the
300        <filename>pykota/initscripts/ldap/pykota.schema</filename> into <application>OpenLDAP</application>'s
301        schemas directory.
302        Under Debian GNU/Linux, this is something like :
303        <screen>       
304$ cp pykota.schema /etc/ldap/schema
305        </screen>
306        <note>
307          <title>Note</title>
308          <para>
309            If you use RPM or DEB packages, the
310            <filename>pykota.schema</filename> file is usually installed into the
311            <filename>/usr/share/pykota/ldap</filename> directory, along
312            with a README file, and may also be installed automatically in
313            your <acronym>LDAP</acronym> server's schemas directory.
314          </para>
315        </note> 
316     </para>
317     <para>   
318       Then edit <filename>/etc/ldap/slapd.conf</filename> and add a line to   
319       include the PyKota schema. You should have something
320       like :
321       <screen>   
322# Schema and objectClass definitions
323include         /etc/ldap/schema/core.schema
324include         /etc/ldap/schema/cosine.schema
325include         /etc/ldap/schema/nis.schema
326include         /etc/ldap/schema/inetorgperson.schema
327include         /etc/ldap/schema/pykota.schema
328        </screen>       
329      </para>
330     
331      <para>
332        While this is not mandatory, it is recommended that you setup
333        some indexes for some often accessed PyKota attributes.
334        Here are the minimal indexes
335        lines you may want to put in <filename>slapd.conf</filename> :
336        <screen>
337# Indexes for PyKota
338index pykotaUserName pres,eq,sub
339index pykotaGroupName pres,eq,sub
340index pykotaPrinterName pres,eq,sub
341index pykotaBillingCode pres,eq,sub
342index pykotaLastJobIdent eq
343        </screen>
344      </para>
345     
346      <para>
347        Now you must ensure that the DNs you'll use to bind to   
348        your OpenLDAP server don't have search queries size limits,
349        which gives for example (OpenLDAP 2.1.x or above) :
350       
351<screen>        
352# No Limits for PyKota's administrator and read-only user
353limits dn="cn=pykotaadmin,dc=example,dc=com" size.soft=-1 size.hard=soft
354limits dn="cn=pykotauser,dc=example,dc=com" size.soft=-1 size.hard=soft
355</screen>       
356
357        Where pykotaadmin and pykotauser are the usernames used to bind to your
358        OpenLDAP server within PyKota, respectively in ReadWrite mode
359        (as set in pykotadmin.conf) and in ReadOnly mode (as set in pykota.conf).
360      </para>
361     
362      <para>
363        Finally, stop the <application>OpenLDAP</application> server, generate
364        the index files, and restart <application>OpenLDAP</application>
365        <screen>   
366$ /etc/init.d/slapd stop
367$ slapindex
368$ /etc/init.d/slapd start
369        </screen>
370      </para>
371     
372      <para>
373        With an <acronym>LDAP</acronym> backend, PyKota will need some branches
374        in your <acronym>LDAP</acronym> directory to put its own datas.
375        You can configure PyKota to either attach its datas to your existing
376        users and groups, or to put them in their own <literal>ou</literal>.
377        But some <literal>ou</literal>s dedicated to PyKota are needed in any case,
378        so the best bet may be to put all PyKota's datas below an <literal>ou=PyKota</literal>
379        branch. While this will separate these datas from your existing users and groups
380        entries, this may ease the maintainance.
381      </para>
382     
383      <para>
384        PyKota needs at least an <literal>ou</literal> for printers, for users quotas, for
385        groups quotas, for print jobs, for billing codes, and for pointers to the last job of each printer.
386        In the future, this last <literal>ou</literal> may disappear as its content
387        will probably be attached to each printer.
388      </para>
389     
390      <para>
391        Actually PyKota doesn't create these <literal>ou</literal>s for you, because it's
392        difficult to guess what is the best configuration for you. So you have to
393        create them by yourself, either directly with a text editor and the
394        <command>ldapadd</command> command, or with some specialized tool
395        like <command>gq</command>. You can look at the <filename>initscripts/ldap/pykota-sample.ldif</filename>
396        file to see which minimal branches are necessary.
397        <note>
398          <title>Note</title>
399          <para>
400            If you use RPM or DEB packages, usually the
401            <filename>pykota-sample.ldif</filename> file is installed into the
402            <filename>/usr/share/pykota/ldap</filename> directory, along
403            with a README file.
404          </para>
405        </note> 
406      </para>
407     
408      <para>
409        If no error occured, then your print quota database is ready to be used.
410        Now you can let the print quota database server alone, the remaining work
411        will have to be done on each one of the print servers which will
412        use this particular print quota database server.
413        <tip>
414          <title>Tip</title>
415          <para>
416            If an error occured, maybe your OpenLDAP version is too old, or
417            an unexpected problem (like a bug) happened. Please contact us via email so that we
418            can try to fix the problem. Thanks in advance.
419          </para>
420        </tip> 
421      </para>
422    </sect2> 
423   
424    <sect2>
425      <title>MySQL</title>
426     
427      <para>
428        <application>MySQL</application> is a simple Relationnal DataBase
429        Management System distributed under a <firstterm>Free Software</firstterm>
430        license from the
431        <ulink url="http://www.mysql.org">http://www.mysql.org</ulink>
432        web site.
433      </para>
434     
435      <para>
436        To configure your database, you must have MySQL version 4.1 or higher already working.
437        We recommend that you use MySQL 5.0 or higher though.
438        The complete installation of <application>MySQL</application> is not covered by
439        the present manual, please refer to your system's documentation or to
440        <ulink url="http://www.mysql.org">http://www.mysql.org</ulink> for
441        details.
442      </para>
443     
444      <para>
445        One thing you have to check, though, is that every Print Server on which you
446        want to install the print quota mechanism, must be able to connect to the
447        <application>MySQL</application> server. In the default installation of
448        <application>MySQL</application> this may not be the case for security reasons, except if both
449        servers are in fact the same machine. In any case, it is recommended that you
450        check the <filename>/etc/mysql/my.cnf</filename> file and modify it if
451        needed.
452        <tip>
453          <title>Tip</title>
454          <para>
455            Don't forget to restart <application>MySQL</application> if you modify
456            any of its configuration files, in order for the changes to take effect.
457          </para>
458        </tip> 
459      </para>
460     
461      <para>
462        Be careful, you may be unable to connect from a Print Server to the <application>MySQL</application>
463        server even if the configuration is correct. Sometimes your connections may be blocked by
464        one or more network firewalls along the route from one machine to the other. If this
465        is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm>
466        to not filter the IP port used by <application>MySQL</application>, which is
467        usually port <literal>3306/tcp</literal>.
468        <note>
469          <title>Note</title>
470          <para>
471            The TCP/IP network port used by MySQL may be different. When in doubt, ask your
472            <firstterm>System Administrator</firstterm> for the correct value.
473          </para>
474        </note> 
475      </para>
476     
477      <para>
478        Now that your <application>MySQL</application> server is up and running, and
479        is waiting for your connections, you have to create the print quota database.
480        To do so, you'll have to feed <application>MySQL</application> with the
481        <filename>pykota-1.24_official/initscripts/mysql/pykota-mysql.sql</filename> file.
482        This file will create an empty
483        print quota database and set some permissions on it.
484        The database which will be created will be named <literal>pykota</literal> by default.
485        Two database users will be defined to have access in readonly and read+write modes under
486        the respective names <literal>pykotauser</literal> and <literal>pykotaadmin</literal>.
487        The <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users by
488        default respectively have <literal>readwritepw</literal> and <literal>readonlypw</literal>
489        as their passwords.
490        <note>
491          <title>Note</title>
492          <para>
493            You can choose other names and passwords if you want by modifying the
494            <filename>initscripts/mysql/pykota-mysql.sql</filename> file
495            accordingly, and report your changes into <application>PyKota</application>'s
496            configuration files.
497          </para>
498        </note> 
499      </para>
500     
501      <para>
502        To run this script, you can use the <command>mysql</command> frontend to
503        <application>MySQL</application>, but your priviledges must be sufficient
504        to be allowed to create databases. You can launch <command>mysql</command>
505        as the <literal>root</literal> user for example.
506        From a command line interpreter (i.e. shell), type the following commands :
507        <screen>
508jerome@nordine:~$ cd pykota-1.24_official/initscripts/mysql
509jerome@nordine:~/pykota-1.24_official/initscripts$ mysql &lt;pykota-mysql.sql
510        </screen>
511        <note>
512          <title>Note</title>
513          <para>
514            If you use RPM or DEB packages, usually the
515            <filename>pykota-mysql.sql</filename> file gets installed into the
516            <filename>/usr/share/pykota/mysql</filename> directory, along
517            with a README file.
518          </para>
519        </note> 
520      </para>
521     
522      <para>
523        To improve security further, you could encrypt your database connections, or
524        take any other step as needed. Please refer to <application>MySQL</application>'s
525        documentation for details.
526      </para>
527     
528      <para>
529        For more details, please see <filename>initscripts/mysql/README.mysql</filename>.
530      </para>
531     
532      <para>
533        If no error occured, then your print quota database is ready to be used.
534        Now you can let the print quota database server alone, the remaining work
535        will have to be done on each one of the print servers which will
536        use this particular print quota database server.
537        <tip>
538          <title>Tip</title>
539          <para>
540            If an error occured, maybe your MySQL version is too old, or
541            an unexpected problem (like a bug) happened. Please contact us via email so that we
542            can try to fix the problem. Thanks in advance.
543          </para>
544        </tip> 
545      </para>
546     
547    </sect2> 
548   
549    <sect2>
550      <title>SQLite</title>
551     
552      <para>
553        <application>SQLite</application> is an embeddable Relationnal DataBase
554        distributed under a Free Software
555        license from the
556        <ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink>
557        web site.
558        If is very easy to configure and use, offers a very small memory footprint,
559        is very fast, but can only be used on the print server because it doesn't include
560        a server daemon : the database is directly embedded in the application.
561      </para>
562     
563      <para>
564        To configure your database, you must have SQLite already working.
565        The complete installation of <application>SQLite</application> is not covered by
566        the present manual, please refer to your system's documentation or to
567        <ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink> for
568        details.
569      </para>
570     
571      <para>
572        Once <application>SQLite</application> is installed, you have to decide where
573        you'll put your database. A good idea is to store it into the <literal>pykota</literal>
574        user's home directory. Then to create the database, just type :
575<screen>        
576# sqlite3 ~pykota/pykota.db &lt;pykota/initscripts/sqlite/pykota.sqlite
577# chown pykota.pykota ~pykota/pykota.db
578# chmod 660 ~pykota/pykota.db
579# chown pykota.pykota ~pykota
580</screen>
581      </para>
582      <para>
583        If user <literal>pykota</literal> doesn't exist yet, then please
584        follow the instructions a bit below which explain how to install PyKota on the print server.
585      </para>
586     
587      <para>
588        Once this is done, you'll want to set in <filename>~pykota/pykota.conf</filename> the
589        following lines in the <literal>[global]</literal> section :
590<screen>        
591storagebackend : sqlitestorage
592storagename : /etc/pykota/pykota.db
593</screen>
594      </para>
595      <para>
596        Of course you'll want to replace the path on the <literal>storagename</literal> line
597        with the full path to the newly created <application>SQLite</application> database.
598      </para>
599      <para>
600        If no error occured, then your print quota database is ready to be used.
601        In case you need them, additional instructions are available in <filename>pykota/initscripts/sqlite/README.sqlite</filename>
602        <tip>
603          <title>Tip</title>
604          <para>
605            If an error occured, maybe your SQLite version is too old, or
606            an unexpected problem (like a bug) happened. Please contact us via email so that we
607            can try to fix the problem. Thanks in advance.
608          </para>
609        </tip> 
610      </para>
611    </sect2> 
612   
613    <sect2>
614      <title>Berkeley DB</title>
615     
616      <para>
617        A <application>Berkeley DB</application> backend is planned, but it actually
618        doesn't exist. It seems that remote storage won't be possible with such a backend,
619        so in other terms this means that you will have a different quota database on
620        each print server. This may still prove to be useful for small configurations.
621      </para>
622    </sect2> 
623  </sect1> 
624 
625  <sect1>
626    <title>Print Server Installation</title>
627   
628    <para>
629      For each Print Server on which you plan to implement the print quota
630      mechanism, you have, of course, to have an already working printing environment.
631      Currently <application>PyKota</application> works with
632      <ulink url="http://www.cups.org"><application>CUPS</application></ulink>
633      but older releases also supported <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>.
634      <application>LPRng</application> support might be re-added in the future.
635    </para>
636   
637    <para>
638      Here's the list of software you have to install on each Print Server, version numbers
639      are given as an indication of which was successfully tested, but older versions may
640      work too.
641      <itemizedlist>
642        <listitem>
643          <para>
644            <application>CUPS</application> version 1.1.14 or above.
645            You can download it from <ulink url="http://www.cups.org">http://www.cups.org</ulink>
646          </para>
647        </listitem> 
648        <listitem>
649          <para>
650            <application>Python</application> version 2.2 or above.
651            You can download it from <ulink url="http://www.python.org">http://www.python.org</ulink>.
652            While <application>PyKota</application> itself will try to preserve compatibility
653            with <application>Python</application> version 2.2 for the near future, some <application>Python</application>
654            modules which are needed by <application>PyKota</application> may require a more recent version
655            of this language.
656          </para>
657        </listitem> 
658        <listitem>
659          <para>
660            print quota database client libraries, depending on your print quota database backend :
661            <itemizedlist>
662              <listitem>
663                <para>
664                  PostgreSQL backend :
665                  <itemizedlist>
666                    <listitem>
667                      <para>
668                        <application>PostgreSQL</application> client libraries. They must match the <application>PostgreSQL</application>
669                        version used on your print quota database server.
670                      </para>
671                    </listitem> 
672                    <listitem>
673                      <para>
674                        The <application>PygreSQL</application> python module.
675                        <application>PygreSQL</application> is normally included in
676                        <application>PostgreSQL</application>, but you may want to
677                        download it from <ulink url="http://www.pygresql.org">http://www.pygresql.org</ulink>
678                      </para>
679                    </listitem> 
680                  </itemizedlist> 
681                </para>
682              </listitem> 
683              <listitem>
684                <para>
685                  OpenLDAP backend :
686                  <itemizedlist>
687                    <listitem>
688                      <para>
689                        <application>OpenLDAP</application> client libraries. They must match
690                        the <application>OpenLDAP</application> version used on your print quota database server.
691                      </para>
692                    </listitem> 
693                    <listitem>
694                      <para>
695                        The <application>Python-LDAP</application> python module.
696                        You may download this module from <ulink url="http://python-ldap.sourceforge.net">http://python-ldap.sourceforge.net</ulink>
697                      </para>
698                    </listitem> 
699                  </itemizedlist>
700                </para>
701              </listitem>
702              <listitem>
703                <para>
704                  MySQL backend :
705                  <itemizedlist>
706                    <listitem>
707                      <para>
708                        <application>MySQL</application> client libraries. They must match the <application>MySQL</application>
709                        version used on your database server.
710                      </para>
711                    </listitem> 
712                    <listitem>
713                      <para>
714                        The <application>Python-MySQL</application> python module, version 1.2.x or higher.
715                        You can download it from <ulink url="http://sourceforge.net/projects/mysql-python">http://sourceforge.net/projects/mysql-python</ulink>
716                      </para>
717                    </listitem> 
718                  </itemizedlist> 
719                </para>
720              </listitem>
721              <listitem>
722                <para>
723                  SQLite backend : SQLite is not a database server, but an embeddable database, so
724                  if you want to use it you MUST install SQLite on your print server. With
725                  <application>PostgreSQL</application>, <application>MySQL</application> or
726                  <application>OpenLDAP</application> you can store your datas on a different
727                  machine than the print server, but this is not possible with <application>SQLite</application>.
728                  <itemizedlist>
729                    <listitem>
730                      <para>
731                        <application>SQLite</application> version 3.2.1 or higher and its library.
732                        You can download it from
733                        <ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink>
734                      </para>
735                    </listitem> 
736                    <listitem>
737                      <para>
738                        The <application>Python-SQLite</application> python module version 2.0.5 or higher.
739                        You can download it from
740                        <ulink url="http://www.pysqlite.org">http://www.pysqlite.org</ulink>
741                      </para>
742                    </listitem> 
743                  </itemizedlist>
744                </para>
745              </listitem>
746              <listitem>
747                <para>
748                  Berkeley DB backend : Not supported yet.
749                </para>
750              </listitem>
751            </itemizedlist> 
752          </para>
753        </listitem> 
754        <listitem>
755          <para>
756            <application>ucd-snmp</application> or <application>net-snmp</application> tools, version 4.2.5 or above. You only need
757            the <command>snmpget</command> command.
758            You can download this software from <ulink url="http://www.sourceforge.net/projects/net-snmp/">http://www.sourceforge.net/projects/net-snmp/</ulink>.
759            You only need this if you plan to query your printers for their internal page counter via SNMP.
760          </para>
761        </listitem> 
762        <listitem>
763          <para>
764            <application>netatalk</application> version 1.6.1 or above. You only need
765            the <command>pap</command> command.
766            You can download this software from <ulink url="http://netatalk.sourceforge.net/">http://netatalk.sourceforge.net/</ulink>.
767            You only need this if you plan to query your printers for their internal page counter via AppleTalk.
768          </para>
769        </listitem> 
770        <listitem>
771          <para>
772            eGenix' mxDateTime Python module version 2.0.3 or above. It must match your default Python version.
773            You can download it from <ulink url="http://www.egenix.com">http://www.egenix.com</ulink>.
774          </para>
775        </listitem> 
776        <listitem>
777          <para>
778            The Python acccelerator <application>Psyco</application>. It must match your default Python version.
779            You can download it from <ulink url="http://psyco.sourceforge.net">http://psyco.sourceforge.net</ulink>.
780            You only need this if you run on the <literal>x86</literal> architecture because
781            <application>Psyco</application> doesn't yet exist on other architectures.
782          </para>
783        </listitem> 
784        <listitem>
785          <para>
786            The <application>pysnmp</application> Python module version 3.4.2, or higher.
787            You can download it from <ulink url="http://pysnmp.sourceforge.net">http://pysnmp.sourceforge.net</ulink>.
788          </para>
789        </listitem> 
790        <listitem>
791          <para>
792            The <application>JAXML</application> Python module.
793            You can download it from <ulink url="http://www.librelogiciel.com/software/">http://www.librelogiciel.com/software/</ulink>.
794          </para>
795        </listitem> 
796        <listitem>
797          <para>
798            The <application>ReportLab</application> Toolkit Python module.
799            You can download it from <ulink url="http://www.reportlab.org">http://www.reportlab.org</ulink>.
800          </para>
801        </listitem> 
802        <listitem>
803          <para>
804            The <application>Python Imaging Library - PIL</application> module.
805            You can download it from <ulink url="http://www.pythonware.com">http://www.pythonware.com</ulink>.
806          </para>
807        </listitem> 
808        <listitem>
809          <para>
810            The <application>PyOSD</application> Python module.
811            You can download it from <ulink url="http://repose.cx/pyosd/">http://repose.cx/pyosd/</ulink>.
812          </para>
813        </listitem> 
814        <listitem>
815          <para>
816            The <application>pkpgcounter</application> Generic Page Description Language parser.
817            You can download it from <ulink url="http://www.pykota.com.com/software/pkpgcounter">http://www.pykota.com.com/software/pkpgcounter</ulink>.
818          </para>
819        </listitem> 
820        <listitem>
821          <para>
822            The <application>PyPAM</application> Python interface to <acronym>PAM</acronym>.
823            You'll need this if you plan to ask users to authenticate when printing through <command>pknotify</command>
824            and <command>pykoticon</command>. You don't need this module otherwise.
825            If needed, you can download it from <ulink url="http://www.pangalactic.org/PyPAM/">http://www.pangalactic.org/PyPAM/</ulink>.
826          </para>
827        </listitem> 
828        <listitem>
829          <para>
830            The <application>PkIPPLib</application> Python <acronym>IPP</acronym> library.
831            You can download it from <ulink url="http://www.pykota.com/software/pkipplib">http://www.pykota.com/software/pkipplib</ulink>.
832          </para>
833        </listitem> 
834      </itemizedlist> 
835    </para>
836   
837    <para>
838      Instead of downloading all these programs' sources and compiling them, which really
839      is a boring task considering that many software are needed, you may prefer to look
840      into the packages included with your GNU/Linux distribution of choice (if you use
841      this operating system of course). Most, if not all, GNU/Linux distributions include
842      all the software mentionned above, in the form of packages which are easier to
843      install than sources tarballs. This is probably the same for the many *BSD
844      distributions.
845    </para>
846   
847    <para>
848       You can check that all needed software is installed by launching the <command>checkdeps.py</command>
849       command :
850      <screen>     
851$ python checkdeps.py     
852      </screen>
853    </para>
854   
855    <para>
856      Once all these software are installed, installing PyKota itself is a breeze.
857      PyKota being written entirely in the Python language, which is interpreted,
858      there's no need to compile anything. You just have to execute the installation
859      script :
860      <screen>     
861$ python setup.py install     
862      </screen>
863    </para>
864   
865    <para>
866      The setup script will automatically create the
867      <filename>/usr/share/pykota/conf</filename> directory and put the sample
868      configuration files <filename>conf/pykota.conf.sample</filename> and
869      <filename>conf/pykotadmin.conf.sample</filename> there, along with
870      a <filename>README</filename> file explaining their purpose.
871    </para>
872   
873    <para>
874      Now you have to create a <literal>pykota</literal> system user and group. The <application>PyKota</application>
875      software will automatically search its configuration files in user <literal>pykota</literal>'s
876      home directory. For example we could create the user and group, and set <filename>/etc/pykota</filename>
877      as the home directory, but any other home directory will do :
878<screen>      
879    adduser --system --group --home /etc/pykota --gecos PyKota pykota
880</screen>
881    </para>
882   
883    <para>
884      You now have to copy the sample configuration files into the <filename>~pykota</filename>
885      directory, under the respective names <filename>pykota.conf</filename> and
886      <filename>pykotadmin.conf</filename>. Once copied there, you just
887      have to modify these files to adapt them to your own setup.
888      These files are heavily commented, so you should have no problem.
889      Also their format is quite common, because it's the one used by
890      <application>Samba</application> for example, or by <literal>.ini</literal>
891      files under <application>MS-Windows</application>, so you may already
892      be familiar with this syntax.
893      In a future release, this documentation will include the complete
894      reference for all configuration fields available. Keep in mind that
895      <application>PyKota</application> can be really heavily customized, and can delegate some work
896      to any external command of your choice.
897    </para>
898   
899    <para>
900      Please create a backup copy of the <filename>~pykota</filename>
901      directory before modifying a working installation.
902    </para>
903   
904    <para>
905      PyKota features some interesting possibilities which allow you to
906      define options either globally so that they apply to all printers,
907      or on a per printer basis. Please see the sample configuration files
908      to see what I mean. In the simplest form, only a <literal>[global]</literal> section is
909      needed. In more complex configurations, you will have to create
910      one section per printer. Each section in the configuration files
911      begins with a name between square brackets <literal>[]</literal>.
912      The name to use to define a particular printer section is the name
913      of the print queue you want to manage with PyKota.
914    </para>
915   
916    <para>
917      After you have modified <application>PyKota</application>'s configuration files, you have to
918      double check their permissions, otherwise your installation may be
919      insecure or may not work at all.
920      The main configuration file <filename>~pykota/pykota.conf</filename>
921      doesn't contain much sensitive information, so it can be made
922      readable by anyone. If normal users read this file, at best they
923      will learn the username and optional password of the read-only
924      database user. This means that beside being allowed to read all the contents of
925      the quota database, they won't be allowed to modify or delete it.
926      On the other hand, the <filename>~pykota/pykotadmin.conf</filename>
927      file contains the read-write user's identity and password. You must then
928      ensure that no normal user can read this file. It should only be readable
929      by the <literal>root</literal> user, which is always the case, and by
930      <application>PyKota</application> administrators. In addition,
931      users for which <application>CUPS</application> doesn't run as user <literal>root</literal> will
932      have to ensure that the user their printing system is run as
933      can read both of these files. An easy way to do so is to put the <literal>lp</literal> user
934      (for example) into the <literal>pykota</literal> system group, then
935      to give the correct permissions to <application>PyKota</application>'s configuration files :
936      <screen>
937$ chown pykota.pykota ~pykota/pykota.conf     
938$ chmod 644 ~pykota/pykota.conf     
939$ chown pykota.pykota ~pykota/pykotadmin.conf     
940$ chmod 640 ~pykota/pykotadmin.conf     
941      </screen>
942     
943      <warning>
944        <title>Warning</title>
945        <para>
946          All the users allowed to read the <filename>~pykota/pykotadmin.conf</filename>
947          are considered to be <application>PyKota</application> administrators. So be
948          careful with these files permissions.
949        </para>
950      </warning>
951    </para>
952   
953    <para>
954      On some systems, you may be able to strenghten permissions like this :
955      <screen>
956$ chown pykota.pykota ~pykota/pykota.conf     
957$ chmod 640 ~pykota/pykota.conf     
958$ chown pykota.pykota ~pykota/pykotadmin.conf     
959$ chmod 600 ~pykota/pykotadmin.conf     
960      </screen>
961    </para>
962   
963    <para>
964      And on other ones, you may need to relax them, and change the files' owner :
965      <screen>
966$ chown lp.pykota ~pykota/pykota.conf     
967$ chmod 640 ~pykota/pykota.conf     
968$ chown lp.pykota ~pykota/pykotadmin.conf     
969$ chmod 640 ~pykota/pykotadmin.conf     
970      </screen>
971    </para>
972   
973    <para>
974      This all depends on the printing system you are using, and the user the
975      printing system is usually running as. You need to remember three things :
976     
977      <itemizedlist>
978        <listitem>
979          <para>
980            The user your printing system runs as MUST be allowed to read
981            both <application>PyKota</application>'s configuration files.
982          </para> 
983        </listitem> 
984        <listitem>       
985          <para>
986            Any user who can read <filename>pykotadmin.conf</filename>
987            is a <application>PyKota</application> administrator, and
988            can do whatever he wants to the print quota database.
989          </para>
990        </listitem>
991        <listitem>       
992          <para>
993            If <filename>cupsd.conf</filename> contains <literal>RunAsUser</literal>, then
994            you won't be able to authenticate users with <command>pknotify</command> and <command>pykoticon</command>.
995            Also in this case you may have to make <application>PyKota</application>'s configuration files
996            owned by the user <application>CUPS</application> runs as.
997          </para>
998        </listitem>
999      </itemizedlist> 
1000    </para>
1001   
1002    <para>
1003      Don't forget to restart your print server sofware if you changed group membership for the user it runs
1004      as, otherwise your change wouldn't be taken into account.
1005    </para>
1006   
1007    <para>
1008      Now depending on your printing system, the configuration to do is particular.
1009      We will now see how to plug PyKota into <application>CUPS</application> since <application>LPRng</application>
1010      is not supported anymore.
1011    </para>
1012   
1013    <sect2>
1014      <title>With CUPS</title>
1015     
1016      <para>
1017        From version 1.16alpha7 on, configuring <application>PyKota</application> to integrate
1018        within <application>CUPS</application> is more than easy.
1019      </para>
1020     
1021      <para>
1022        You just have to create a symbolic link to the <command>cupspykota</command>
1023        command in <application>CUPS</application>' backend directory :
1024        <screen>       
1025$ cd /usr/lib/cups/backend       
1026$ ln -s /usr/share/pykota/cupspykota cupspykota
1027        </screen>
1028      </para>
1029     
1030      <para>
1031        If you use CUPS v1.2 or higher, it is recommended that you
1032        also type the following command to allow the <command>cupspykota</command>
1033        backend to correctly support other backends which must be run
1034        as the root user (e.g. the <command>lpd</command> backend) :
1035        <screen>       
1036$ chmod 700 /usr/share/pykota/cupspykota
1037        </screen>
1038      </para>
1039     
1040      <para>
1041        You have to restart <application>CUPS</application> for this modification to
1042        take effect :
1043        <screen>
1044$ /etc/init.d/cupsys restart       
1045        </screen>
1046      </para>
1047     
1048      <para>
1049        Now point your web browser to CUPS configuration page, usually at
1050        <ulink url="http://localhost:631">http://localhost:631</ulink> on
1051        your print server.
1052      </para>
1053     
1054      <para>
1055        Then when creating new printers or reconfiguring existing ones, just
1056        choose devices which are <literal>PyKota managed</literal>
1057        <footnote>
1058          <para>
1059            Debian 3.0 Woody is known to have problems : CUPS 1.1.14 doesn't automatically
1060            detect <literal>PyKota managed</literal> devices. So you have to manually
1061            modify CUPS' <filename>printers.conf</filename> file as explained in
1062            PyKota's toplevel <filename>README</filename> file.
1063          </para>
1064        </footnote>
1065        instead of
1066        normal devices. You've got one <literal>PyKota managed</literal> device
1067        for each regular device available from CUPS, so just choose the appropriate
1068        one.
1069      </para>
1070     
1071      <para>
1072        Repeat the above procedure for each print queue on which you want to use
1073        PyKota. That's all !
1074      </para>
1075     
1076      <sect3>
1077        <title>Troubleshooting</title>
1078        <para>
1079          In case of problem, the simplest way to solve it is currently
1080          to ask on PyKota's mailing list, describing the symptoms, as
1081          well as the hardware and software you use.
1082        </para>
1083       
1084        <para>
1085          A searchable FAQ is now available at
1086          <ulink url="http://otrs.librelogiciel.com/otrs/public.pl">http://otrs.librelogiciel.com/public.pl</ulink>.
1087          A FAQ entry explaining in great details how to diagnose a problem correctly is
1088          available at
1089          <ulink url="http://otrs.librelogiciel.com/otrs/public.pl?ID=2">http://otrs.librelogiciel.com/public.pl?ID=2</ulink>.
1090        </para>
1091       
1092        <para>
1093          You can also ask questions on IRC :
1094          <screen>
1095/server irc.freenode.net         
1096/join #pykota
1097          </screen>
1098        </para> 
1099      </sect3> 
1100     
1101    </sect2>
1102   
1103  </sect1> 
1104</chapter>
1105
Note: See TracBrowser for help on using the browser.