[753] | 1 | <!-- $Id$ --> |
---|
| 2 | |
---|
| 3 | <chapter> |
---|
[865] | 4 | <title id="installation">Installation</title> |
---|
[860] | 5 | |
---|
| 6 | <para>Last modified on $Date$</para> |
---|
| 7 | |
---|
[753] | 8 | <para> |
---|
[856] | 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. |
---|
[753] | 11 | </para> |
---|
[856] | 12 | |
---|
| 13 | <para> |
---|
| 14 | First you have to determine which machine will be the <application>PyKota</application> |
---|
[860] | 15 | <firstterm>Storage Server</firstterm>. The Storage Server is the host responsible |
---|
[856] | 16 | for keeping a centralized database of print usage for all your printers, users and groups. |
---|
| 17 | </para> |
---|
| 18 | |
---|
| 19 | <para> |
---|
[860] | 20 | Then you have to list all the <firstterm>Print Servers</firstterm> for which |
---|
| 21 | you plan to use <firstterm>print quota</firstterm> facilities. |
---|
[856] | 22 | </para> |
---|
| 23 | |
---|
| 24 | <para> |
---|
[861] | 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> |
---|
[1015] | 31 | jerome@nordine:~$ tar -zxf pykota-1.08-official.tar.gz |
---|
| 32 | jerome@nordine:~$ cd pykota-1.08-official |
---|
| 33 | jerome@nordine:~/pykota-1.08-official$ |
---|
[861] | 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. |
---|
[856] | 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> |
---|
[860] | 75 | <application>PostgreSQL</application> is an <firstterm>Object Relationnal DataBase |
---|
| 76 | Management System</firstterm> distributed under a <firstterm>Free Software</firstterm> |
---|
[856] | 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 |
---|
[863] | 93 | want to install the print quota mechanism, must be able to connect to the |
---|
[856] | 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 |
---|
[862] | 97 | check the <filename>/etc/postgresql/pg_hba.conf</filename> file and modify it if |
---|
[856] | 98 | needed. This file is self documented and its modification is straightforward. |
---|
[858] | 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 |
---|
[862] | 101 | modify the <filename>/etc/postgresql/postgresql.conf</filename> file, which is |
---|
[858] | 102 | self documented and easy to modify too. |
---|
[856] | 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 |
---|
[860] | 116 | is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm> |
---|
[856] | 117 | to not filter the IP port used by <application>PostgreSQL</application>, which is |
---|
| 118 | usually port 5432/tcp. |
---|
[860] | 119 | <note> |
---|
| 120 | <title>Note</title> |
---|
[856] | 121 | <para> |
---|
| 122 | The TCP/IP network port used by PostgreSQL may be different. When in doubt, ask your |
---|
[860] | 123 | <firstterm>System Administrator</firstterm> for the correct value. |
---|
[856] | 124 | </para> |
---|
[860] | 125 | </note> |
---|
[856] | 126 | </para> |
---|
| 127 | |
---|
| 128 | <para> |
---|
[860] | 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 |
---|
[1015] | 132 | <filename>pykota-x.xx/initscripts/postgresql/pykota-postgresql.sql</filename> file. |
---|
[1021] | 133 | This file will create a Quota DataBase administrator in the <application>PostgreSQL</application> system, then create an empty |
---|
[862] | 134 | Quota DataBase and set some permissions on it. The Quota DataBase administrator |
---|
[1021] | 135 | is the <application>PostgreSQL</application>'s user used to manage the Quota database. |
---|
| 136 | The Quota DataBase Administrator is not present in the Quota Database |
---|
| 137 | itself, he is only defined in <application>PostgreSQL</application> and don't |
---|
| 138 | have to exist on any system, nor in the Quota DataBase. His default names |
---|
| 139 | is <literal>pykotaadmin</literal>. |
---|
| 140 | The database which will be created will be named <literal>pykota</literal> by default. |
---|
[862] | 141 | <note> |
---|
| 142 | <title>Note</title> |
---|
| 143 | <para> |
---|
| 144 | You can choose other names if you want, just modify the |
---|
[1015] | 145 | <filename>initscripts/postgresql/pykota-postgresql.sql</filename> file |
---|
[864] | 146 | accordingly, and report your changes into <application>PyKota</application>'s |
---|
| 147 | configuration file. |
---|
[862] | 148 | </para> |
---|
| 149 | </note> |
---|
[856] | 150 | </para> |
---|
[860] | 151 | |
---|
| 152 | <para> |
---|
| 153 | To run this script, you can use the <application>psql</application> frontend to |
---|
| 154 | <application>PostgreSQL</application>, but your priviledges must be sufficient |
---|
| 155 | to be allowed to create users and databases. You can launch <application>psql</application> |
---|
| 156 | as the <literal>postgres</literal> user which is <application>PostgreSQL</application>'s |
---|
| 157 | default administrator, and connect to the default database named <literal>template1</literal>. |
---|
| 158 | From a command line interpreter (i.e. shell), type the following commands : |
---|
| 159 | <screen> |
---|
[1015] | 160 | jerome@nordine:~$ cd pykota-1.08-official/initscripts/postgresql |
---|
| 161 | jerome@nordine:~/pykota-1.08-official/initscripts$ psql -h localhost -U postgres template1 |
---|
[860] | 162 | Welcome to psql, the PostgreSQL interactive terminal. |
---|
| 163 | |
---|
| 164 | Type: \copyright for distribution terms |
---|
| 165 | \h for help with SQL commands |
---|
| 166 | \? for help on internal slash commands |
---|
| 167 | \g or terminate with semicolon to execute query |
---|
| 168 | \q to quit |
---|
| 169 | |
---|
| 170 | template1=# \i pykota-postgresql.sql |
---|
| 171 | ... a lot of output lines |
---|
[862] | 172 | pykota=# |
---|
[860] | 173 | </screen> |
---|
| 174 | </para> |
---|
| 175 | |
---|
| 176 | <para> |
---|
[862] | 177 | For security reasons, you may want to set passwords in |
---|
| 178 | <application>PostgreSQL</application> for the |
---|
[1021] | 179 | <literal>pykotaadmin</literal> user. |
---|
| 180 | Otherwise any user able to connect to |
---|
[862] | 181 | <application>PostgreSQL</application> on your Quota Storage Server |
---|
[1021] | 182 | could connect to the quota database as this user, and modify it without problem. |
---|
[862] | 183 | </para> |
---|
| 184 | |
---|
| 185 | <para> |
---|
| 186 | To do so, just type the following lines while still being at the <application>psql</application> |
---|
[1021] | 187 | prompt (replace the password values by your own) : |
---|
[862] | 188 | <screen> |
---|
| 189 | pykota=# ALTER USER pykotaadmin PASSWORD 'somepassword'; |
---|
| 190 | ALTER USER |
---|
| 191 | pykota=# \q |
---|
[1015] | 192 | jerome@nordine:~/pykota-1.08-official/initscripts/postgresql$ |
---|
[862] | 193 | </screen> |
---|
| 194 | </para> |
---|
| 195 | |
---|
| 196 | <para> |
---|
| 197 | The <literal>\q</literal> command above will quit the <application>psql</application> |
---|
| 198 | program and return you to the shell's command line prompt. |
---|
| 199 | </para> |
---|
| 200 | |
---|
| 201 | <para> |
---|
| 202 | To improve security further, you could encrypt your database connections, or |
---|
| 203 | take any other step as needed. Please refer to <application>PostgreSQL</application>'s |
---|
[959] | 204 | documentation for details. Also if <application>PyKota</application>'s configuration |
---|
| 205 | file is readable by anyone with access on your file system, a local user could |
---|
| 206 | create some script to modify his own print quota. |
---|
[862] | 207 | <warning> |
---|
| 208 | <title>Warning</title> |
---|
| 209 | <para> |
---|
| 210 | Defining passwords may not be sufficient if your database access rule is |
---|
| 211 | set to <literal>trust</literal> in the <filename>/etc/postgresql/pg_hba.conf</filename>. |
---|
| 212 | Again, please refer to <application>PostgreSQL</application>'s documentation |
---|
| 213 | for details. Also, passwords will fly unencrypted over the network by default, |
---|
| 214 | so be sure to take any necessary step to secure your database server from |
---|
| 215 | unauthorized use. This has nothing to do with <application>PyKota</application> |
---|
| 216 | though, it is just a general rule to keep in mind. |
---|
| 217 | </para> |
---|
| 218 | </warning> |
---|
| 219 | </para> |
---|
| 220 | |
---|
| 221 | <para> |
---|
[860] | 222 | If no error occured, then your Quota DataBase is ready to be used. |
---|
| 223 | Now you can let the Quota Storage Server alone, the remaining work |
---|
| 224 | will have to be done on each one of the print servers which will |
---|
| 225 | use this particular Quota Storage Server. |
---|
| 226 | <tip> |
---|
| 227 | <title>Tip</title> |
---|
| 228 | <para> |
---|
| 229 | If an error occured, maybe your PostgreSQL version is too old, or |
---|
| 230 | an unexpected problem (like a bug) happened. Please send me an email so that I |
---|
| 231 | can try to solve the problem. Thanks in advance. |
---|
| 232 | </para> |
---|
| 233 | </tip> |
---|
| 234 | </para> |
---|
[862] | 235 | |
---|
[856] | 236 | </sect2> |
---|
| 237 | |
---|
| 238 | <sect2> |
---|
| 239 | <title>MySQL</title> |
---|
| 240 | |
---|
| 241 | <para> |
---|
[857] | 242 | A <application>MySQL</application> Storage Backend is planned, but it actually |
---|
| 243 | doesn't exist. |
---|
[856] | 244 | </para> |
---|
| 245 | </sect2> |
---|
| 246 | |
---|
| 247 | <sect2> |
---|
| 248 | <title>LDAP</title> |
---|
| 249 | |
---|
| 250 | <para> |
---|
[1021] | 251 | An <application>LDAP</application> Storage Backend is currently under heavy work. |
---|
| 252 | You can already give a look at the LDAP schema which was defined for PyKota. |
---|
| 253 | Full support for LDAP in PyKota should be OK by the end of July 2003, if all |
---|
| 254 | continues to go well. |
---|
[856] | 255 | </para> |
---|
| 256 | </sect2> |
---|
| 257 | |
---|
| 258 | <sect2> |
---|
| 259 | <title>Berkeley DB</title> |
---|
| 260 | |
---|
| 261 | <para> |
---|
[857] | 262 | A <application>Berkeley DB</application> Storage Backend is planned, but it actually |
---|
| 263 | doesn't exist. It seems that remote storage won't be possible with such a backend, |
---|
| 264 | so in other terms this means that you will have a different quota database on |
---|
| 265 | each print server. This may still prove to be useful for small configurations. |
---|
[856] | 266 | </para> |
---|
| 267 | </sect2> |
---|
| 268 | </sect1> |
---|
| 269 | |
---|
| 270 | <sect1> |
---|
| 271 | <title>Print Server Installation</title> |
---|
| 272 | |
---|
| 273 | <para> |
---|
| 274 | For each Print Server on which you plan to implement the print quota |
---|
| 275 | mechanism, you have, of course, to have an already working printing environment. |
---|
[959] | 276 | Currently <application>PyKota</application> works with either the |
---|
| 277 | <ulink url="http://www.cups.org"><application>CUPS</application></ulink> |
---|
| 278 | or the <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>, |
---|
[856] | 279 | but more may be added in the future. |
---|
| 280 | </para> |
---|
| 281 | |
---|
| 282 | <para> |
---|
[959] | 283 | Here's the list of software you have to install on each Print Server, version numbers |
---|
| 284 | are given as an indication of which was successfully tested, but older versions may |
---|
| 285 | work too. |
---|
[862] | 286 | <itemizedlist> |
---|
| 287 | <listitem> |
---|
| 288 | <para> |
---|
[959] | 289 | <application>CUPS</application> version 1.1 or above, or <application>LPRng</application> |
---|
| 290 | version 3.8.20 or above (it probably works with older versions but this is untested). |
---|
| 291 | You can download them from <ulink url="http://www.cups.org">http://www.cups.org</ulink> |
---|
| 292 | or <ulink url="http://lprng.sourceforge.net">http://lprng.sourceforge.net</ulink> |
---|
[862] | 293 | </para> |
---|
| 294 | </listitem> |
---|
| 295 | <listitem> |
---|
| 296 | <para> |
---|
| 297 | Python version 2.1 or above. |
---|
| 298 | You can download it from <ulink url="http://www.python.org">http://www.python.org</ulink>. |
---|
| 299 | </para> |
---|
| 300 | </listitem> |
---|
| 301 | <listitem> |
---|
| 302 | <para> |
---|
| 303 | Quota Storage client libraries, depending on your Quota Storage Backend : |
---|
| 304 | <itemizedlist> |
---|
| 305 | <listitem> |
---|
| 306 | <para> |
---|
| 307 | PostgreSQL backend : |
---|
| 308 | <itemizedlist> |
---|
| 309 | <listitem> |
---|
| 310 | <para> |
---|
| 311 | <application>PostgreSQL</application> client libraries. They must match the <application>PostgreSQL</application> |
---|
| 312 | version used on your Quota Storage Server. |
---|
| 313 | </para> |
---|
| 314 | </listitem> |
---|
| 315 | <listitem> |
---|
| 316 | <para> |
---|
| 317 | The <application>PygreSQL</application> python module. |
---|
| 318 | It must match the |
---|
| 319 | <application>PostgreSQL</application> client libraries' |
---|
| 320 | version, as well as Python's version. |
---|
| 321 | </para> |
---|
| 322 | </listitem> |
---|
| 323 | </itemizedlist> |
---|
| 324 | </para> |
---|
| 325 | </listitem> |
---|
| 326 | <listitem> |
---|
| 327 | <para> |
---|
| 328 | MySQL backend : TODO |
---|
| 329 | </para> |
---|
| 330 | </listitem> |
---|
| 331 | <listitem> |
---|
| 332 | <para> |
---|
| 333 | LDAP backend : TODO |
---|
| 334 | </para> |
---|
| 335 | </listitem> |
---|
| 336 | <listitem> |
---|
| 337 | <para> |
---|
| 338 | Berkeley DB backend : TODO |
---|
| 339 | </para> |
---|
| 340 | </listitem> |
---|
| 341 | </itemizedlist> |
---|
| 342 | </para> |
---|
| 343 | </listitem> |
---|
| 344 | <listitem> |
---|
| 345 | <para> |
---|
| 346 | <application>ucd-snmp</application> or <application>net-snmp</application> tools, version 4.2.5 or above. You only need |
---|
| 347 | the <application>snmpget</application> command. |
---|
[959] | 348 | You can download them from <ulink url="http://www.sourceforge.net/projects/net-snmp/">http://www.sourceforge.net/projects/net-snmp/</ulink>. |
---|
| 349 | You only need this if you plan to query your printers for their internal page counter via SNMP. |
---|
[862] | 350 | </para> |
---|
| 351 | </listitem> |
---|
| 352 | <listitem> |
---|
| 353 | <para> |
---|
[959] | 354 | <application>netatalk</application> version 1.6.1 or above. You only need |
---|
| 355 | the <application>pap</application> command. |
---|
| 356 | You can download them from <ulink url="http://netatalk.sourceforge.net/">http://netatalk.sourceforge.net/</ulink>. |
---|
| 357 | You only need this if you plan to query your printers for their internal page counter via AppleTalk. |
---|
| 358 | </para> |
---|
| 359 | </listitem> |
---|
| 360 | <listitem> |
---|
| 361 | <para> |
---|
| 362 | eGenix' mxDateTime Python module version 2.0.3 or above. It must match your default Python version. |
---|
[862] | 363 | You can download it from <ulink url="http://www.egenix.com">http://www.egenix.com</ulink>. |
---|
| 364 | </para> |
---|
| 365 | </listitem> |
---|
| 366 | </itemizedlist> |
---|
[856] | 367 | </para> |
---|
| 368 | </sect1> |
---|
[753] | 369 | </chapter> |
---|
| 370 | |
---|
| 371 | <!-- |
---|
| 372 | |
---|
| 373 | $Log$ |
---|
[1021] | 374 | Revision 1.15 2003/06/10 16:37:54 jalet |
---|
| 375 | Deletion of the second user which is not needed anymore. |
---|
| 376 | Added a debug configuration field in /etc/pykota.conf |
---|
| 377 | All queries can now be sent to the logger in debug mode, this will |
---|
| 378 | greatly help improve performance when time for this will come. |
---|
| 379 | |
---|
[1015] | 380 | Revision 1.14 2003/06/05 07:12:29 jalet |
---|
| 381 | Reorganization of directories |
---|
| 382 | |
---|
[959] | 383 | Revision 1.13 2003/04/24 21:09:47 jalet |
---|
| 384 | Documentation slightly improved. |
---|
| 385 | |
---|
[942] | 386 | Revision 1.12 2003/04/17 21:33:16 jalet |
---|
| 387 | Version 1.03 is out. |
---|
| 388 | |
---|
[865] | 389 | Revision 1.11 2003/03/25 09:32:06 jalet |
---|
| 390 | Improved documentation. |
---|
| 391 | |
---|
[864] | 392 | Revision 1.10 2003/03/23 17:59:56 jalet |
---|
| 393 | Clarify a point. |
---|
| 394 | |
---|
[863] | 395 | Revision 1.9 2003/03/23 17:57:20 jalet |
---|
| 396 | Deleted a repetition. |
---|
| 397 | |
---|
[862] | 398 | Revision 1.8 2003/03/22 15:34:50 jalet |
---|
| 399 | More complete installation documentation. |
---|
| 400 | |
---|
[861] | 401 | Revision 1.7 2003/03/22 14:26:45 jalet |
---|
| 402 | Download instructions added. |
---|
| 403 | |
---|
[860] | 404 | Revision 1.6 2003/03/22 14:06:02 jalet |
---|
| 405 | Quota Storage Server installation is OK for PostgreSQL. |
---|
| 406 | |
---|
[859] | 407 | Revision 1.5 2003/03/22 13:11:33 jalet |
---|
| 408 | The port on which the Quota Storage Sever is listening can now |
---|
| 409 | be set in the configuration file (see sample). |
---|
| 410 | Better error handling if PygreSQL is not installed. |
---|
| 411 | Improved documentation. |
---|
| 412 | Version number changed to 1.02alpha |
---|
| 413 | |
---|
[858] | 414 | Revision 1.4 2003/03/22 07:20:38 jalet |
---|
| 415 | More information wrt PostgreSQL tcp/ip configuration. |
---|
| 416 | |
---|
[857] | 417 | Revision 1.3 2003/03/18 22:18:25 jalet |
---|
| 418 | The documentation will only be a sequence of chapters in a single part, not |
---|
| 419 | multiple parts each including chapters. |
---|
| 420 | |
---|
[856] | 421 | Revision 1.2 2003/03/18 22:10:54 jalet |
---|
| 422 | Documentation improvements. |
---|
| 423 | |
---|
[753] | 424 | Revision 1.1 2003/02/08 00:03:35 jalet |
---|
| 425 | Documentation skeleton added |
---|
| 426 | |
---|
| 427 | |
---|
| 428 | --> |
---|