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

Revision 959, 17.8 kB (checked in by jalet, 22 years ago)

Documentation slightly improved.

  • 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.04-official.tar.gz   
32jerome@nordine:~$ cd pykota-1.04-official
33jerome@nordine:~/pykota-1.04-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.
48  </para>
49 
50  <para>
51    Now we will see what has to be done on each of the servers we are planning to use.
52    <note>
53      <title>Note</title>
54      <para>
55        Of course, depending on the size of your network, you may very well
56        use the same machine as both a Print Server and a Storage Server.
57        This is especially the case if you've got only one server.
58      </para>
59    </note> 
60  </para>
61 
62  <sect1>
63    <title>Storage Server Installation</title>
64   
65    <para>
66      Depending on <application>PyKota</application>'s version number, different
67      types of storage backends may be supported, so we will see for each one of
68      them how to configure it.
69    </para>
70   
71    <sect2>
72      <title>PostgreSQL</title>
73     
74      <para>
75        <application>PostgreSQL</application> is an <firstterm>Object Relationnal DataBase
76        Management System</firstterm> distributed under a <firstterm>Free Software</firstterm>
77        license from the
78        <ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink>
79        web site. It certainely is the free <acronym>RDBMS</acronym> which has the most advanced
80        features, and is widely used all over the world.
81      </para>
82     
83      <para>
84        To configure your Storage Server, you must have PostgreSQL already working.
85        The complete installation of <application>PostgreSQL</application> is not covered by
86        the present manual, please refer to your system's documentation or to
87        <ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink> for
88        details.
89      </para>
90     
91      <para>
92        One thing you have to check, though, is that every Print Server on which you
93        want to install the print quota mechanism, must be able to connect to the
94        <application>PostgreSQL</application> server. In the default installation of
95        <application>PostgreSQL</application> this may not be the case for security reasons, except if both
96        servers are in fact the same machine. In any case, it is recommended that you
97        check the <filename>/etc/postgresql/pg_hba.conf</filename> file and modify it if
98        needed. This file is self documented and its modification is straightforward.
99        You also have to make sure that <application>PostgreSQL</application> accepts <acronym>TCP/IP</acronym> connections.
100        To do so you either have to launch it with the <option>-i</option> option or
101        modify the <filename>/etc/postgresql/postgresql.conf</filename> file, which is
102        self documented and easy to modify too.
103        <tip>
104          <title>Tip</title>
105          <para>
106            Don't forget to restart <application>PostgreSQL</application> if you modify
107            any of its configuration files, in order for the changes to take effect.
108          </para>
109        </tip> 
110      </para>
111     
112      <para>
113        Be careful, you may be unable to connect from a Print Server to the <application>PostgreSQL</application>
114        server even if the configuration is correct. Sometimes your connections may be blocked by
115        one or more network firewalls along the route from one machine to the other. If this
116        is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm>
117        to not filter the IP port used by <application>PostgreSQL</application>, which is
118        usually port 5432/tcp.
119        <note>
120          <title>Note</title>
121          <para>
122            The TCP/IP network port used by PostgreSQL may be different. When in doubt, ask your
123            <firstterm>System Administrator</firstterm> for the correct value.
124          </para>
125        </note> 
126      </para>
127     
128      <para>
129        Now that your <application>PostgreSQL</application> server is up and running, and
130        is waiting for your connections, you have to create the Quota Storage DataBase.
131        To do so, you'll have to feed <application>PostgreSQL</application> with the
132        <filename>pykota-x.xx/initscripts/pykota-postgresql.sql</filename> file.
133        This file will create a Quota DataBase administrator and a Quota DataBase user
134        in the <application>PostgreSQL</application> system, then create an empty
135        Quota DataBase and set some permissions on it. The Quota DataBase administrator
136        will be able to add printers, users and groups to the Quota DataBase, while
137        the Quota DataBase user will be used to update the print quota usage
138        in the Quota DataBase. None of these two users is present in the Quota Database
139        itself, they are only defined in <application>PostgreSQL</application> and don't
140        have to exist on any system, nor in the Quota DataBase. Their default names
141        are <literal>pykotaadmin</literal> for the administrator and <literal>pykotauser</literal>
142        for the user. The database which will be created will be named <literal>pykota</literal>.
143        <note>
144          <title>Note</title>
145          <para>
146            You can choose other names if you want, just modify the
147            <filename>initscripts/pykota-postgresql.sql</filename> file
148            accordingly, and report your changes into <application>PyKota</application>'s
149            configuration file.
150          </para>
151        </note> 
152      </para>
153     
154      <para>
155        To run this script, you can use the <application>psql</application> frontend to
156        <application>PostgreSQL</application>, but your priviledges must be sufficient
157        to be allowed to create users and databases. You can launch <application>psql</application>
158        as the <literal>postgres</literal> user which is <application>PostgreSQL</application>'s
159        default administrator, and connect to the default database named <literal>template1</literal>.
160        From a command line interpreter (i.e. shell), type the following commands :
161        <screen>
162jerome@nordine:~$ cd pykota-1.04-official/initscripts/
163jerome@nordine:~/pykota-1.04-official/initscripts$ psql -h localhost -U postgres template1
164Welcome to psql, the PostgreSQL interactive terminal.
165
166Type:  \copyright for distribution terms
167       \h for help with SQL commands
168       \? for help on internal slash commands
169       \g or terminate with semicolon to execute query
170       \q to quit
171
172template1=# \i pykota-postgresql.sql
173            ... a lot of output lines
174pykota=#       
175        </screen>
176      </para>
177     
178      <para>
179        For security reasons, you may want to set passwords in
180        <application>PostgreSQL</application> for the
181        <literal>pykotaadmin</literal> and <literal>pykotauser</literal>
182        users. Otherwise any user able to connect to
183        <application>PostgreSQL</application> on your Quota Storage Server
184        could connect to the quota database as one of them and modify it without problem.
185      </para>
186     
187      <para>
188        To do so, just type the following lines while still being at the <application>psql</application>
189        prompt (replace the passwords values by your own) :
190        <screen>
191pykota=# ALTER USER pykotaadmin PASSWORD 'somepassword';
192ALTER USER
193pykota=# ALTER USER pykotauser PASSWORD 'anotherpassword';
194ALTER USER
195pykota=# \q
196jerome@nordine:~/pykota-1.04-official/initscripts$
197        </screen>
198      </para>
199     
200      <para>
201        The <literal>\q</literal> command above will quit the <application>psql</application>
202        program and return you to the shell's command line prompt.
203      </para>
204     
205      <para>
206        To improve security further, you could encrypt your database connections, or
207        take any other step as needed. Please refer to <application>PostgreSQL</application>'s
208        documentation for details. Also if <application>PyKota</application>'s configuration
209        file is readable by anyone with access on your file system, a local user could
210        create some script to modify his own print quota.
211        <warning>
212          <title>Warning</title>
213          <para>
214            Defining passwords may not be sufficient if your database access rule is
215            set to <literal>trust</literal> in the <filename>/etc/postgresql/pg_hba.conf</filename>.
216            Again, please refer to <application>PostgreSQL</application>'s documentation
217            for details. Also, passwords will fly unencrypted over the network by default,
218            so be sure to take any necessary step to secure your database server from
219            unauthorized use. This has nothing to do with <application>PyKota</application>
220            though, it is just a general rule to keep in mind.
221          </para>
222        </warning> 
223      </para>
224     
225      <para>
226        If no error occured, then your Quota DataBase is ready to be used.
227        Now you can let the Quota Storage Server alone, the remaining work
228        will have to be done on each one of the print servers which will
229        use this particular Quota Storage Server.
230        <tip>
231          <title>Tip</title>
232          <para>
233            If an error occured, maybe your PostgreSQL version is too old, or
234            an unexpected problem (like a bug) happened. Please send me an email so that I
235            can try to solve the problem. Thanks in advance.
236          </para>
237        </tip> 
238      </para>
239     
240    </sect2> 
241   
242    <sect2>
243      <title>MySQL</title>
244     
245      <para>
246        A <application>MySQL</application> Storage Backend is planned, but it actually
247        doesn't exist.
248      </para>
249    </sect2> 
250   
251    <sect2>
252      <title>LDAP</title>
253     
254      <para>
255        An <application>LDAP</application> Storage Backend is planned, but it actually
256        doesn't exist. Some people may already be working on this, though.
257      </para>
258    </sect2> 
259   
260    <sect2>
261      <title>Berkeley DB</title>
262     
263      <para>
264        A <application>Berkeley DB</application> Storage Backend is planned, but it actually
265        doesn't exist. It seems that remote storage won't be possible with such a backend,
266        so in other terms this means that you will have a different quota database on
267        each print server. This may still prove to be useful for small configurations.
268      </para>
269    </sect2> 
270  </sect1> 
271 
272  <sect1>
273    <title>Print Server Installation</title>
274   
275    <para>
276      For each Print Server on which you plan to implement the print quota
277      mechanism, you have, of course, to have an already working printing environment.
278      Currently <application>PyKota</application> works with either the
279      <ulink url="http://www.cups.org"><application>CUPS</application></ulink>
280      or the <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>,
281      but more may be added in the future.
282    </para>
283   
284    <para>
285      Here's the list of software you have to install on each Print Server, version numbers
286      are given as an indication of which was successfully tested, but older versions may
287      work too.
288      <itemizedlist>
289        <listitem>
290          <para>
291            <application>CUPS</application> version 1.1 or above, or <application>LPRng</application>
292            version 3.8.20 or above (it probably works with older versions but this is untested).
293            You can download them from <ulink url="http://www.cups.org">http://www.cups.org</ulink>
294            or <ulink url="http://lprng.sourceforge.net">http://lprng.sourceforge.net</ulink>
295          </para>
296        </listitem> 
297        <listitem>
298          <para>
299            Python version 2.1 or above.
300            You can download it from <ulink url="http://www.python.org">http://www.python.org</ulink>.
301          </para>
302        </listitem> 
303        <listitem>
304          <para>
305            Quota Storage client libraries, depending on your Quota Storage Backend :
306            <itemizedlist>
307              <listitem>
308                <para>
309                  PostgreSQL backend :
310                  <itemizedlist>
311                    <listitem>
312                      <para>
313                        <application>PostgreSQL</application> client libraries. They must match the <application>PostgreSQL</application>
314                        version used on your Quota Storage Server.
315                      </para>
316                    </listitem> 
317                    <listitem>
318                      <para>
319                        The <application>PygreSQL</application> python module.
320                        It must match the
321                        <application>PostgreSQL</application> client libraries'
322                        version, as well as Python's version.
323                      </para>
324                    </listitem> 
325                  </itemizedlist> 
326                </para>
327              </listitem> 
328              <listitem>
329                <para>
330                  MySQL backend : TODO
331                </para>
332              </listitem>
333              <listitem>
334                <para>
335                  LDAP backend : TODO
336                </para>
337              </listitem>
338              <listitem>
339                <para>
340                  Berkeley DB backend : TODO
341                </para>
342              </listitem>
343            </itemizedlist> 
344          </para>
345        </listitem> 
346        <listitem>
347          <para>
348            <application>ucd-snmp</application> or <application>net-snmp</application> tools, version 4.2.5 or above. You only need
349            the <application>snmpget</application> command.
350            You can download them from <ulink url="http://www.sourceforge.net/projects/net-snmp/">http://www.sourceforge.net/projects/net-snmp/</ulink>.
351            You only need this if you plan to query your printers for their internal page counter via SNMP.
352          </para>
353        </listitem> 
354        <listitem>
355          <para>
356            <application>netatalk</application> version 1.6.1 or above. You only need
357            the <application>pap</application> command.
358            You can download them from <ulink url="http://netatalk.sourceforge.net/">http://netatalk.sourceforge.net/</ulink>.
359            You only need this if you plan to query your printers for their internal page counter via AppleTalk.
360          </para>
361        </listitem> 
362        <listitem>
363          <para>
364            eGenix' mxDateTime Python module version 2.0.3 or above. It must match your default Python version.
365            You can download it from <ulink url="http://www.egenix.com">http://www.egenix.com</ulink>.
366          </para>
367        </listitem> 
368      </itemizedlist> 
369    </para>
370  </sect1> 
371</chapter>
372
373<!--
374
375$Log$
376Revision 1.13  2003/04/24 21:09:47  jalet
377Documentation slightly improved.
378
379Revision 1.12  2003/04/17 21:33:16  jalet
380Version 1.03 is out.
381
382Revision 1.11  2003/03/25 09:32:06  jalet
383Improved documentation.
384
385Revision 1.10  2003/03/23 17:59:56  jalet
386Clarify a point.
387
388Revision 1.9  2003/03/23 17:57:20  jalet
389Deleted a repetition.
390
391Revision 1.8  2003/03/22 15:34:50  jalet
392More complete installation documentation.
393
394Revision 1.7  2003/03/22 14:26:45  jalet
395Download instructions added.
396
397Revision 1.6  2003/03/22 14:06:02  jalet
398Quota Storage Server installation is OK for PostgreSQL.
399
400Revision 1.5  2003/03/22 13:11:33  jalet
401The port on which the Quota Storage Sever is listening can now
402be set in the configuration file (see sample).
403Better error handling if PygreSQL is not installed.
404Improved documentation.
405Version number changed to 1.02alpha
406
407Revision 1.4  2003/03/22 07:20:38  jalet
408More information wrt PostgreSQL tcp/ip configuration.
409
410Revision 1.3  2003/03/18 22:18:25  jalet
411The documentation will only be a sequence of chapters in a single part, not
412multiple parts each including chapters.
413
414Revision 1.2  2003/03/18 22:10:54  jalet
415Documentation improvements.
416
417Revision 1.1  2003/02/08 00:03:35  jalet
418Documentation skeleton added
419
420
421-->
Note: See TracBrowser for help on using the browser.