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