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

Revision 1906, 35.9 kB (checked in by jalet, 20 years ago)

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