root / pykota / branches / specialauth / docs / installation.sgml

Revision 3116, 53.8 kB (checked in by jerome, 18 years ago)

Improved the documentation.

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