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

Revision 1783, 35.1 kB (checked in by jalet, 20 years ago)

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