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

Revision 3413, 53.4 kB (checked in by jerome, 14 years ago)

Removed unnecessary spaces at EOL.

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