[753] | 1 | <!-- $Id$ --> |
---|
| 2 | |
---|
| 3 | <chapter> |
---|
[865] | 4 | <title id="installation">Installation</title> |
---|
[3413] | 5 | |
---|
[860] | 6 | <para>Last modified on $Date$</para> |
---|
[3413] | 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> |
---|
[3413] | 12 | |
---|
[856] | 13 | <para> |
---|
| 14 | First you have to determine which machine will be the <application>PyKota</application> |
---|
[2844] | 15 | database server. The database server is the host responsible |
---|
[856] | 16 | for keeping a centralized database of print usage for all your printers, users and groups. |
---|
| 17 | </para> |
---|
[3413] | 18 | |
---|
[856] | 19 | <para> |
---|
[860] | 20 | Then you have to list all the <firstterm>Print Servers</firstterm> for which |
---|
[2844] | 21 | you plan to use print quota facilities. |
---|
[856] | 22 | </para> |
---|
[3413] | 23 | |
---|
[856] | 24 | <para> |
---|
[2844] | 25 | With most database backends, several print servers can share a single database, however |
---|
| 26 | as we'll see later this is not possible if you choose to use <application>SQLite</application> |
---|
| 27 | as your print quota database backend. |
---|
| 28 | </para> |
---|
[3413] | 29 | |
---|
[2844] | 30 | <para> |
---|
[861] | 31 | Finally you have to download <application>PyKota</application>'s latest version |
---|
[3413] | 32 | or buy an official package, from |
---|
[2909] | 33 | <ulink url="http://www.pykota.com/software/pykota">http://www.pykota.com/software/pykota</ulink>. |
---|
[861] | 34 | If you've just bought an official package, then as soon as you've receive it you |
---|
| 35 | have to decompress and visit its archive, to do so just type the following commands : |
---|
| 36 | <screen> |
---|
[3413] | 37 | jerome@nordine:~$ tar -zxf pykota-1.26_official.tar.gz |
---|
[3202] | 38 | jerome@nordine:~$ cd pykota-1.26_official |
---|
| 39 | jerome@nordine:~/pykota-1.26_official$ |
---|
[861] | 40 | </screen> |
---|
| 41 | </para> |
---|
[3413] | 42 | |
---|
[861] | 43 | <para> |
---|
| 44 | You can see many files in this directory, the first ones to read are <filename>README</filename>, |
---|
| 45 | then <filename>COPYING</filename> and <filename>LICENSE</filename>. They will give you |
---|
[3413] | 46 | basic installation instructions and explain the licensing terms under which |
---|
[861] | 47 | <application>PyKota</application> is distributed. Of course they are also mostly |
---|
| 48 | boring to read ! Detailed installation and operating instructions are defined |
---|
| 49 | in the <filename>./docs</filename> directory, in the form of <acronym>SGML</acronym> |
---|
| 50 | documentation in the <ulink url="http://www.docbook.org">DocBook</ulink> format. |
---|
| 51 | You have to compile these files into readable documentation like the <acronym>HTML</acronym> |
---|
| 52 | or <acronym>PDF</acronym> formats, or buy an official <application>PyKota</application> package |
---|
[1168] | 53 | which already contains these compiled forms of the documentation. Of course you already |
---|
| 54 | know this because that's what you are currently reading ! |
---|
[861] | 55 | </para> |
---|
[3413] | 56 | |
---|
[856] | 57 | <sect1> |
---|
[3116] | 58 | <title>Interactive step-by-step installation of PyKota with pksetup</title> |
---|
[3413] | 59 | |
---|
[856] | 60 | <para> |
---|
[3116] | 61 | <command>pksetup</command> is a command line tool with which you'll be able |
---|
| 62 | to install <application>PyKota</application> and all its dependencies in |
---|
| 63 | a completely interactive way. At the end of the installation, a shell |
---|
| 64 | script is created which allows you to replicate the very same |
---|
| 65 | installation in an automated way. This can be useful if you've got |
---|
| 66 | several servers to install identically. |
---|
[856] | 67 | </para> |
---|
[3413] | 68 | |
---|
[3116] | 69 | <para> |
---|
| 70 | Currently, <command>pksetup</command> is experimental, and only works |
---|
[3413] | 71 | with <ulink url="http://www.debian.org">Debian</ulink> and |
---|
[3116] | 72 | <ulink url="http://www.ubuntu.com">Ubuntu</ulink> distributions. |
---|
| 73 | In addition, the database backend which will be installed with |
---|
| 74 | this command is <ulink url="http://www.postgresql.org">PostgreSQL</ulink> |
---|
| 75 | and you have no choice for another backend. If you want another |
---|
| 76 | database backend, or use a different distribution, or want to do |
---|
| 77 | the installation manually, then read and follow the instructions in the next section. |
---|
| 78 | </para> |
---|
[3413] | 79 | |
---|
[3116] | 80 | <para> |
---|
| 81 | To launch the installation procedure, just type <literal>pksetup</literal> |
---|
| 82 | followed with the name of your distribution, like : |
---|
[3413] | 83 | <screen> |
---|
[3202] | 84 | jerome@nordine:~/pykota-1.26_official$ ./bin/pksetup debian |
---|
[3413] | 85 | </screen> |
---|
[3116] | 86 | and then follow the instructions and answer to the several questions you'll |
---|
| 87 | be asked. |
---|
| 88 | </para> |
---|
| 89 | </sect1> |
---|
[3413] | 90 | |
---|
[3116] | 91 | <sect1> |
---|
| 92 | <title>Manual installation</title> |
---|
| 93 | <para> |
---|
| 94 | To do a manual installation, we will see what has to be done on each of the servers we are planning to use. |
---|
| 95 | <note> |
---|
| 96 | <title>Note</title> |
---|
| 97 | <para> |
---|
| 98 | Of course, depending on the size of your network, you may very well |
---|
| 99 | use the same machine as both a Print Server and a database server. |
---|
| 100 | This is especially the case if you've got only one server. |
---|
| 101 | </para> |
---|
[3413] | 102 | </note> |
---|
[3116] | 103 | </para> |
---|
[3413] | 104 | |
---|
[856] | 105 | <sect2> |
---|
[3116] | 106 | <title>Database server installation</title> |
---|
[3413] | 107 | |
---|
[856] | 108 | <para> |
---|
[3116] | 109 | Depending on <application>PyKota</application>'s version number, different |
---|
| 110 | types of storage backends may be supported, so we will see for each one of |
---|
| 111 | them how to configure it. |
---|
[856] | 112 | </para> |
---|
[3413] | 113 | |
---|
[3116] | 114 | <sect3> |
---|
| 115 | <title>PostgreSQL</title> |
---|
[3413] | 116 | |
---|
[3116] | 117 | <para> |
---|
| 118 | <application>PostgreSQL</application> is an <firstterm>Object Relationnal DataBase |
---|
| 119 | Management System</firstterm> distributed under a <firstterm>Free Software</firstterm> |
---|
[3413] | 120 | license from the |
---|
[3116] | 121 | <ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink> |
---|
| 122 | web site. It certainely is the free <acronym>RDBMS</acronym> which has the most advanced |
---|
| 123 | features, and is widely used all over the world. |
---|
| 124 | </para> |
---|
[3413] | 125 | |
---|
[3116] | 126 | <para> |
---|
| 127 | To configure your database, you must have PostgreSQL already working. |
---|
| 128 | The complete installation of <application>PostgreSQL</application> is not covered by |
---|
[3413] | 129 | the present manual, please refer to your system's documentation or to |
---|
[3116] | 130 | <ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink> for |
---|
| 131 | details. |
---|
| 132 | </para> |
---|
[3413] | 133 | |
---|
[3116] | 134 | <para> |
---|
| 135 | One thing you have to check, though, is that every Print Server on which you |
---|
| 136 | want to install the print quota mechanism, must be able to connect to the |
---|
| 137 | <application>PostgreSQL</application> server. In the default installation of |
---|
| 138 | <application>PostgreSQL</application> this may not be the case for security reasons, except if both |
---|
| 139 | servers are in fact the same machine. In any case, it is recommended that you |
---|
| 140 | check the <filename>/etc/postgresql/pg_hba.conf</filename> file and modify it if |
---|
| 141 | needed. This file is self documented and its modification is straightforward. |
---|
| 142 | You also have to make sure that <application>PostgreSQL</application> accepts <acronym>TCP/IP</acronym> connections. |
---|
| 143 | To do so you either have to launch it with the <option>-i</option> option or |
---|
| 144 | modify the <filename>/etc/postgresql/postgresql.conf</filename> file, which is |
---|
| 145 | self documented and easy to modify too. Allowing <acronym>TCP/IP</acronym> connections |
---|
| 146 | is not necessary though if your print quota database server and your Print Server are |
---|
| 147 | the very same host. |
---|
[3413] | 148 | </para> |
---|
| 149 | |
---|
[3116] | 150 | <para> |
---|
| 151 | Here's an excerpt from a <filename>pg_hba.conf</filename> file. This one rejects all |
---|
| 152 | connections to PyKota's database excepted when made from the same host by <application>PostgreSQL</application> users |
---|
| 153 | <literal>pykotauser</literal> or <literal>pykotaadmin</literal> with the correct password. |
---|
[3413] | 154 | <screen> |
---|
[3116] | 155 | local all postgres ident sameuser |
---|
| 156 | local all all reject |
---|
| 157 | host pykota pykotauser 127.0.0.1 255.255.255.255 crypt |
---|
| 158 | host pykota pykotaadmin 127.0.0.1 255.255.255.255 crypt |
---|
| 159 | host pykota all 127.0.0.1 255.255.255.255 reject |
---|
| 160 | </screen> |
---|
| 161 | </para> |
---|
[3413] | 162 | |
---|
[3116] | 163 | <para> |
---|
| 164 | Of course if your print server and your database servers have different <acronym>IP</acronym> |
---|
| 165 | addresses, you have to replace the <literal>127.0.0.1</literal> address above with your print |
---|
| 166 | server's <acronym>IP</acronym> address. As an alternative, you could still keep these |
---|
| 167 | lines and add similar lines with other <acronym>IP</acronym> addresses if you have several |
---|
| 168 | print servers for which you want a single centralized database. |
---|
| 169 | <tip> |
---|
| 170 | <title>Tip</title> |
---|
| 171 | <para> |
---|
| 172 | Don't forget to restart <application>PostgreSQL</application> if you modify |
---|
| 173 | any of its configuration files, in order for the changes to take effect. |
---|
| 174 | </para> |
---|
[3413] | 175 | </tip> |
---|
[3116] | 176 | </para> |
---|
[3413] | 177 | |
---|
[3116] | 178 | <para> |
---|
| 179 | Be careful, you may be unable to connect from a Print Server to the <application>PostgreSQL</application> |
---|
| 180 | server even if the configuration is correct. Sometimes your connections may be blocked by |
---|
| 181 | one or more network firewalls along the route from one machine to the other. If this |
---|
| 182 | is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm> |
---|
| 183 | to not filter the IP port used by <application>PostgreSQL</application>, which is |
---|
| 184 | usually port <literal>5432/tcp</literal>. |
---|
| 185 | <note> |
---|
| 186 | <title>Note</title> |
---|
| 187 | <para> |
---|
[3413] | 188 | The TCP/IP network port used by PostgreSQL may be different. When in doubt, ask your |
---|
| 189 | <firstterm>System Administrator</firstterm> for the correct value. |
---|
[3116] | 190 | </para> |
---|
[3413] | 191 | </note> |
---|
[3116] | 192 | </para> |
---|
[3413] | 193 | |
---|
[3116] | 194 | <para> |
---|
| 195 | Now that your <application>PostgreSQL</application> server is up and running, and |
---|
| 196 | is waiting for your connections, you have to create the print quota database. |
---|
| 197 | To do so, you'll have to feed <application>PostgreSQL</application> with the |
---|
[3202] | 198 | <filename>pykota-1.26_official/initscripts/postgresql/pykota-postgresql.sql</filename> file. |
---|
[3116] | 199 | This file will create a print quota database administrator in the <application>PostgreSQL</application> system, then create an empty |
---|
| 200 | print quota database and set some permissions on it. The print quota database administrator |
---|
| 201 | is the <application>PostgreSQL</application>'s user used to manage the quota database. |
---|
| 202 | The print quota database Administrator is not present in the quota database |
---|
| 203 | itself, he is only defined in <application>PostgreSQL</application> and don't |
---|
| 204 | have to exist on any system, nor in the print quota database. His default name |
---|
[3413] | 205 | is <literal>pykotaadmin</literal>. |
---|
[3116] | 206 | A print quota database read-only user is also created under the name of <literal>pykotauser</literal>. |
---|
[3413] | 207 | This read-only user is used by <application>PyKota</application> to connect to the |
---|
| 208 | print quota database when an user who is not a <application>PyKota</application> administrator |
---|
[3116] | 209 | <footnote><para>a <application>PyKota</application> administrator is an user who can read the <filename>~pykota/pykotadmin.conf</filename> file.</para></footnote> |
---|
| 210 | launches a pykota command. This prevents normal |
---|
| 211 | users from being able to modify their own, or other users', quota information. |
---|
| 212 | The database which will be created will be named <literal>pykota</literal> by default. |
---|
| 213 | The <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users by |
---|
| 214 | default respectively have <literal>readwritepw</literal> and <literal>readonlypw</literal> |
---|
| 215 | as their passwords. |
---|
| 216 | <note> |
---|
| 217 | <title>Note</title> |
---|
| 218 | <para> |
---|
[3413] | 219 | You can choose other names and passwords if you want by modifying the |
---|
[3116] | 220 | <filename>initscripts/postgresql/pykota-postgresql.sql</filename> file |
---|
| 221 | accordingly, and report your changes into <application>PyKota</application>'s |
---|
| 222 | configuration files. |
---|
| 223 | </para> |
---|
[3413] | 224 | </note> |
---|
[3116] | 225 | </para> |
---|
[3413] | 226 | |
---|
[3116] | 227 | <para> |
---|
| 228 | To run this script, you can use the <command>psql</command> frontend to |
---|
| 229 | <application>PostgreSQL</application>, but your priviledges must be sufficient |
---|
| 230 | to be allowed to create users and databases. You can launch <command>psql</command> |
---|
| 231 | as the <literal>postgres</literal> user which is <application>PostgreSQL</application>'s |
---|
| 232 | default administrator, and connect to the default database named <literal>template1</literal>. |
---|
| 233 | From a command line interpreter (i.e. shell), type the following commands : |
---|
| 234 | <screen> |
---|
[3202] | 235 | jerome@nordine:~$ cd pykota-1.26_official/initscripts/postgresql |
---|
| 236 | jerome@nordine:~/pykota-1.26_official/initscripts$ psql -h localhost -U postgres template1 |
---|
[3116] | 237 | Welcome to psql, the PostgreSQL interactive terminal. |
---|
[3413] | 238 | |
---|
[3116] | 239 | Type: \copyright for distribution terms |
---|
| 240 | \h for help with SQL commands |
---|
| 241 | \? for help on internal slash commands |
---|
| 242 | \g or terminate with semicolon to execute query |
---|
| 243 | \q to quit |
---|
[3413] | 244 | |
---|
| 245 | template1=# \i pykota-postgresql.sql |
---|
[3116] | 246 | ... a lot of output lines |
---|
[3413] | 247 | pykota=# |
---|
[3116] | 248 | </screen> |
---|
| 249 | <note> |
---|
| 250 | <title>Note</title> |
---|
| 251 | <para> |
---|
| 252 | If you use RPM or DEB packages, usually the |
---|
| 253 | <filename>pykota-postgresql.sql</filename> file gets installed into the |
---|
[3413] | 254 | <filename>/usr/share/pykota/postgresql</filename> directory, along |
---|
[3116] | 255 | with a README file. |
---|
| 256 | </para> |
---|
[3413] | 257 | </note> |
---|
[3116] | 258 | </para> |
---|
[3413] | 259 | |
---|
[3116] | 260 | <para> |
---|
| 261 | If you want to you can change passwords later in |
---|
[3413] | 262 | <application>PostgreSQL</application> for the |
---|
[3116] | 263 | <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users. |
---|
| 264 | To do so, just type the following lines while still being at the <command>psql</command> |
---|
| 265 | prompt (replace the password values by your own : |
---|
| 266 | <screen> |
---|
| 267 | pykota=# ALTER USER pykotaadmin PASSWORD 'somepassword'; |
---|
| 268 | ALTER USER |
---|
| 269 | pykota=# ALTER USER pykotauser PASSWORD 'anotherpassword'; |
---|
| 270 | pykota=# \q |
---|
[3202] | 271 | jerome@nordine:~/pykota-1.26_official/initscripts/postgresql$ |
---|
[3116] | 272 | </screen> |
---|
| 273 | </para> |
---|
[3413] | 274 | |
---|
[3116] | 275 | <para> |
---|
| 276 | The <literal>\q</literal> command above will quit the <command>psql</command> |
---|
| 277 | program and return you to the shell's command line prompt. |
---|
| 278 | </para> |
---|
[3413] | 279 | |
---|
[3116] | 280 | <para> |
---|
| 281 | To improve security further, you could encrypt your database connections, or |
---|
| 282 | take any other step as needed. Please refer to <application>PostgreSQL</application>'s |
---|
[3413] | 283 | documentation for details. |
---|
[3116] | 284 | <warning> |
---|
| 285 | <title>Warning</title> |
---|
| 286 | <para> |
---|
| 287 | Defining passwords may not be sufficient if your database access rule is |
---|
| 288 | set to <literal>trust</literal> in the <filename>/etc/postgresql/pg_hba.conf</filename>. |
---|
| 289 | Again, please refer to <application>PostgreSQL</application>'s documentation |
---|
| 290 | for details. Also, passwords will fly unencrypted over the network by default, |
---|
| 291 | so be sure to take any necessary step to secure your database server from |
---|
| 292 | unauthorized use. This has nothing to do with <application>PyKota</application> |
---|
| 293 | though, it is just a general rule to keep in mind. |
---|
| 294 | </para> |
---|
[3413] | 295 | </warning> |
---|
[3116] | 296 | </para> |
---|
[3413] | 297 | |
---|
[3116] | 298 | <para> |
---|
| 299 | For more details, please see <filename>initscripts/mysql/README.postgresql</filename>. |
---|
| 300 | </para> |
---|
[3413] | 301 | |
---|
[3116] | 302 | <para> |
---|
| 303 | If no error occured, then your print quota database is ready to be used. |
---|
| 304 | Now you can let the print quota database server alone, the remaining work |
---|
| 305 | will have to be done on each one of the print servers which will |
---|
| 306 | use this particular print quota database server. |
---|
| 307 | <tip> |
---|
| 308 | <title>Tip</title> |
---|
| 309 | <para> |
---|
| 310 | If an error occured, maybe your PostgreSQL version is too old, or |
---|
| 311 | an unexpected problem (like a bug) happened. Please contact us via email so that we |
---|
| 312 | can try to fix the problem. Thanks in advance. |
---|
| 313 | </para> |
---|
[3413] | 314 | </tip> |
---|
[3116] | 315 | </para> |
---|
[3413] | 316 | |
---|
| 317 | </sect3> |
---|
| 318 | |
---|
[3116] | 319 | <sect3> |
---|
| 320 | <title>LDAP</title> |
---|
[3413] | 321 | |
---|
[3116] | 322 | <para> |
---|
[3413] | 323 | Any <acronym>LDAP</acronym> server, and particularly <application>OpenLDAP</application>, can be used |
---|
[3116] | 324 | as a print quota database backend. |
---|
| 325 | Some other LDAP servers can be used, but this is currently untested in production. |
---|
| 326 | </para> |
---|
[3413] | 327 | |
---|
[3116] | 328 | <para> |
---|
| 329 | <application>OpenLDAP</application> is a Lightweight Directory Access Protocol server |
---|
| 330 | implementation published as Free Software. |
---|
| 331 | You can download it from <ulink url="http://www.openldap.org">http://www.openldap.org</ulink>. |
---|
| 332 | </para> |
---|
[3413] | 333 | |
---|
[3116] | 334 | <para> |
---|
| 335 | To use <application>OpenLDAP</application> as your print quota database backend, you have to copy the |
---|
[3413] | 336 | <filename>pykota/initscripts/ldap/pykota.schema</filename> into <application>OpenLDAP</application>'s |
---|
[3116] | 337 | schemas directory. |
---|
| 338 | Under Debian GNU/Linux, this is something like : |
---|
[3413] | 339 | <screen> |
---|
[3116] | 340 | $ cp pykota.schema /etc/ldap/schema |
---|
| 341 | </screen> |
---|
[3283] | 342 | <note> |
---|
[3277] | 343 | <title>Note</title> |
---|
| 344 | <para> |
---|
[3413] | 345 | If you are using a Red Hat-based system, substitute |
---|
| 346 | <filename>/etc/openldap</filename> for |
---|
[3277] | 347 | <filename>/etc/ldap</filename>. |
---|
| 348 | </para> |
---|
| 349 | </note> |
---|
[3116] | 350 | <note> |
---|
| 351 | <title>Note</title> |
---|
| 352 | <para> |
---|
| 353 | If you use RPM or DEB packages, the |
---|
| 354 | <filename>pykota.schema</filename> file is usually installed into the |
---|
| 355 | <filename>/usr/share/pykota/ldap</filename> directory, along |
---|
| 356 | with a README file, and may also be installed automatically in |
---|
| 357 | your <acronym>LDAP</acronym> server's schemas directory. |
---|
| 358 | </para> |
---|
[3413] | 359 | </note> |
---|
[3116] | 360 | </para> |
---|
[3413] | 361 | <para> |
---|
| 362 | Then edit <filename>/etc/ldap/slapd.conf</filename> and add a line to |
---|
[3116] | 363 | include the PyKota schema. You should have something |
---|
| 364 | like : |
---|
[3413] | 365 | <screen> |
---|
[3116] | 366 | # Schema and objectClass definitions |
---|
| 367 | include /etc/ldap/schema/core.schema |
---|
| 368 | include /etc/ldap/schema/cosine.schema |
---|
| 369 | include /etc/ldap/schema/nis.schema |
---|
| 370 | include /etc/ldap/schema/inetorgperson.schema |
---|
| 371 | include /etc/ldap/schema/pykota.schema |
---|
[3413] | 372 | </screen> |
---|
[3116] | 373 | </para> |
---|
[3413] | 374 | |
---|
[3116] | 375 | <para> |
---|
| 376 | While this is not mandatory, it is recommended that you setup |
---|
| 377 | some indexes for some often accessed PyKota attributes. |
---|
| 378 | Here are the minimal indexes |
---|
| 379 | lines you may want to put in <filename>slapd.conf</filename> : |
---|
| 380 | <screen> |
---|
| 381 | # Indexes for PyKota |
---|
| 382 | index pykotaUserName pres,eq,sub |
---|
| 383 | index pykotaGroupName pres,eq,sub |
---|
| 384 | index pykotaPrinterName pres,eq,sub |
---|
| 385 | index pykotaBillingCode pres,eq,sub |
---|
| 386 | index pykotaLastJobIdent eq |
---|
| 387 | </screen> |
---|
| 388 | </para> |
---|
[3413] | 389 | |
---|
[3116] | 390 | <para> |
---|
[3413] | 391 | Now you must ensure that the DNs you'll use to bind to |
---|
[3116] | 392 | your OpenLDAP server don't have search queries size limits, |
---|
| 393 | which gives for example (OpenLDAP 2.1.x or above) : |
---|
[3413] | 394 | |
---|
| 395 | <screen> |
---|
[3116] | 396 | # No Limits for PyKota's administrator and read-only user |
---|
| 397 | limits dn="cn=pykotaadmin,dc=example,dc=com" size.soft=-1 size.hard=soft |
---|
| 398 | limits dn="cn=pykotauser,dc=example,dc=com" size.soft=-1 size.hard=soft |
---|
[3413] | 399 | </screen> |
---|
| 400 | |
---|
[3116] | 401 | Where pykotaadmin and pykotauser are the usernames used to bind to your |
---|
[3413] | 402 | OpenLDAP server within PyKota, respectively in ReadWrite mode |
---|
[3116] | 403 | (as set in pykotadmin.conf) and in ReadOnly mode (as set in pykota.conf). |
---|
| 404 | </para> |
---|
[3413] | 405 | |
---|
[3116] | 406 | <para> |
---|
| 407 | Finally, stop the <application>OpenLDAP</application> server, generate |
---|
| 408 | the index files, and restart <application>OpenLDAP</application> |
---|
[3413] | 409 | <screen> |
---|
[3116] | 410 | $ /etc/init.d/slapd stop |
---|
| 411 | $ slapindex |
---|
| 412 | $ /etc/init.d/slapd start |
---|
| 413 | </screen> |
---|
| 414 | </para> |
---|
[3277] | 415 | <note> |
---|
| 416 | <title>Note</title> |
---|
| 417 | <para> |
---|
[3413] | 418 | On Red Hat-based distros, use '/sbin/service ldap stop' and |
---|
[3277] | 419 | '/sbin/service ldap start' instead. |
---|
| 420 | </para> |
---|
| 421 | </note> |
---|
[3116] | 422 | <para> |
---|
| 423 | With an <acronym>LDAP</acronym> backend, PyKota will need some branches |
---|
| 424 | in your <acronym>LDAP</acronym> directory to put its own datas. |
---|
| 425 | You can configure PyKota to either attach its datas to your existing |
---|
| 426 | users and groups, or to put them in their own <literal>ou</literal>. |
---|
| 427 | But some <literal>ou</literal>s dedicated to PyKota are needed in any case, |
---|
| 428 | so the best bet may be to put all PyKota's datas below an <literal>ou=PyKota</literal> |
---|
| 429 | branch. While this will separate these datas from your existing users and groups |
---|
| 430 | entries, this may ease the maintainance. |
---|
| 431 | </para> |
---|
[3413] | 432 | |
---|
[3116] | 433 | <para> |
---|
| 434 | PyKota needs at least an <literal>ou</literal> for printers, for users quotas, for |
---|
| 435 | groups quotas, for print jobs, for billing codes, and for pointers to the last job of each printer. |
---|
| 436 | In the future, this last <literal>ou</literal> may disappear as its content |
---|
| 437 | will probably be attached to each printer. |
---|
| 438 | </para> |
---|
[3413] | 439 | |
---|
[3116] | 440 | <para> |
---|
| 441 | Actually PyKota doesn't create these <literal>ou</literal>s for you, because it's |
---|
| 442 | difficult to guess what is the best configuration for you. So you have to |
---|
| 443 | create them by yourself, either directly with a text editor and the |
---|
| 444 | <command>ldapadd</command> command, or with some specialized tool |
---|
| 445 | like <command>gq</command>. You can look at the <filename>initscripts/ldap/pykota-sample.ldif</filename> |
---|
| 446 | file to see which minimal branches are necessary. |
---|
| 447 | <note> |
---|
| 448 | <title>Note</title> |
---|
| 449 | <para> |
---|
| 450 | If you use RPM or DEB packages, usually the |
---|
| 451 | <filename>pykota-sample.ldif</filename> file is installed into the |
---|
[3413] | 452 | <filename>/usr/share/pykota/ldap</filename> directory, along |
---|
[3116] | 453 | with a README file. |
---|
| 454 | </para> |
---|
[3413] | 455 | </note> |
---|
[3116] | 456 | </para> |
---|
[3413] | 457 | |
---|
[3116] | 458 | <para> |
---|
| 459 | If no error occured, then your print quota database is ready to be used. |
---|
| 460 | Now you can let the print quota database server alone, the remaining work |
---|
| 461 | will have to be done on each one of the print servers which will |
---|
| 462 | use this particular print quota database server. |
---|
| 463 | <tip> |
---|
| 464 | <title>Tip</title> |
---|
| 465 | <para> |
---|
| 466 | If an error occured, maybe your OpenLDAP version is too old, or |
---|
| 467 | an unexpected problem (like a bug) happened. Please contact us via email so that we |
---|
| 468 | can try to fix the problem. Thanks in advance. |
---|
| 469 | </para> |
---|
[3413] | 470 | </tip> |
---|
[3116] | 471 | </para> |
---|
[3413] | 472 | </sect3> |
---|
| 473 | |
---|
[3116] | 474 | <sect3> |
---|
| 475 | <title>MySQL</title> |
---|
[3413] | 476 | |
---|
[3116] | 477 | <para> |
---|
| 478 | <application>MySQL</application> is a simple Relationnal DataBase |
---|
| 479 | Management System distributed under a <firstterm>Free Software</firstterm> |
---|
[3413] | 480 | license from the |
---|
[3116] | 481 | <ulink url="http://www.mysql.org">http://www.mysql.org</ulink> |
---|
[3413] | 482 | web site. |
---|
[3116] | 483 | </para> |
---|
[3413] | 484 | |
---|
[3116] | 485 | <para> |
---|
| 486 | To configure your database, you must have MySQL version 4.1 or higher already working. |
---|
| 487 | We recommend that you use MySQL 5.0 or higher though. |
---|
| 488 | The complete installation of <application>MySQL</application> is not covered by |
---|
[3413] | 489 | the present manual, please refer to your system's documentation or to |
---|
[3116] | 490 | <ulink url="http://www.mysql.org">http://www.mysql.org</ulink> for |
---|
| 491 | details. |
---|
| 492 | </para> |
---|
[3413] | 493 | |
---|
[3116] | 494 | <para> |
---|
| 495 | One thing you have to check, though, is that every Print Server on which you |
---|
| 496 | want to install the print quota mechanism, must be able to connect to the |
---|
| 497 | <application>MySQL</application> server. In the default installation of |
---|
| 498 | <application>MySQL</application> this may not be the case for security reasons, except if both |
---|
| 499 | servers are in fact the same machine. In any case, it is recommended that you |
---|
| 500 | check the <filename>/etc/mysql/my.cnf</filename> file and modify it if |
---|
| 501 | needed. |
---|
| 502 | <tip> |
---|
| 503 | <title>Tip</title> |
---|
| 504 | <para> |
---|
| 505 | Don't forget to restart <application>MySQL</application> if you modify |
---|
| 506 | any of its configuration files, in order for the changes to take effect. |
---|
| 507 | </para> |
---|
[3413] | 508 | </tip> |
---|
[3116] | 509 | </para> |
---|
[3413] | 510 | |
---|
[3116] | 511 | <para> |
---|
| 512 | Be careful, you may be unable to connect from a Print Server to the <application>MySQL</application> |
---|
| 513 | server even if the configuration is correct. Sometimes your connections may be blocked by |
---|
| 514 | one or more network firewalls along the route from one machine to the other. If this |
---|
| 515 | is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm> |
---|
| 516 | to not filter the IP port used by <application>MySQL</application>, which is |
---|
| 517 | usually port <literal>3306/tcp</literal>. |
---|
| 518 | <note> |
---|
| 519 | <title>Note</title> |
---|
| 520 | <para> |
---|
[3413] | 521 | The TCP/IP network port used by MySQL may be different. When in doubt, ask your |
---|
| 522 | <firstterm>System Administrator</firstterm> for the correct value. |
---|
[3116] | 523 | </para> |
---|
[3413] | 524 | </note> |
---|
[3116] | 525 | </para> |
---|
[3413] | 526 | |
---|
[3116] | 527 | <para> |
---|
| 528 | Now that your <application>MySQL</application> server is up and running, and |
---|
| 529 | is waiting for your connections, you have to create the print quota database. |
---|
| 530 | To do so, you'll have to feed <application>MySQL</application> with the |
---|
[3202] | 531 | <filename>pykota-1.26_official/initscripts/mysql/pykota-mysql.sql</filename> file. |
---|
[3116] | 532 | This file will create an empty |
---|
[3413] | 533 | print quota database and set some permissions on it. |
---|
[3116] | 534 | The database which will be created will be named <literal>pykota</literal> by default. |
---|
| 535 | Two database users will be defined to have access in readonly and read+write modes under |
---|
| 536 | the respective names <literal>pykotauser</literal> and <literal>pykotaadmin</literal>. |
---|
| 537 | The <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users by |
---|
| 538 | default respectively have <literal>readwritepw</literal> and <literal>readonlypw</literal> |
---|
| 539 | as their passwords. |
---|
| 540 | <note> |
---|
| 541 | <title>Note</title> |
---|
| 542 | <para> |
---|
[3413] | 543 | You can choose other names and passwords if you want by modifying the |
---|
[3116] | 544 | <filename>initscripts/mysql/pykota-mysql.sql</filename> file |
---|
| 545 | accordingly, and report your changes into <application>PyKota</application>'s |
---|
| 546 | configuration files. |
---|
| 547 | </para> |
---|
[3413] | 548 | </note> |
---|
[3116] | 549 | </para> |
---|
[3413] | 550 | |
---|
[3116] | 551 | <para> |
---|
| 552 | To run this script, you can use the <command>mysql</command> frontend to |
---|
| 553 | <application>MySQL</application>, but your priviledges must be sufficient |
---|
| 554 | to be allowed to create databases. You can launch <command>mysql</command> |
---|
| 555 | as the <literal>root</literal> user for example. |
---|
| 556 | From a command line interpreter (i.e. shell), type the following commands : |
---|
| 557 | <screen> |
---|
[3202] | 558 | jerome@nordine:~$ cd pykota-1.26_official/initscripts/mysql |
---|
| 559 | jerome@nordine:~/pykota-1.26_official/initscripts$ mysql <pykota-mysql.sql |
---|
[3116] | 560 | </screen> |
---|
| 561 | <note> |
---|
| 562 | <title>Note</title> |
---|
| 563 | <para> |
---|
| 564 | If you use RPM or DEB packages, usually the |
---|
| 565 | <filename>pykota-mysql.sql</filename> file gets installed into the |
---|
[3413] | 566 | <filename>/usr/share/pykota/mysql</filename> directory, along |
---|
[3116] | 567 | with a README file. |
---|
| 568 | </para> |
---|
[3413] | 569 | </note> |
---|
[3116] | 570 | </para> |
---|
[3413] | 571 | |
---|
[3116] | 572 | <para> |
---|
| 573 | To improve security further, you could encrypt your database connections, or |
---|
| 574 | take any other step as needed. Please refer to <application>MySQL</application>'s |
---|
[3413] | 575 | documentation for details. |
---|
[3116] | 576 | </para> |
---|
[3413] | 577 | |
---|
[3116] | 578 | <para> |
---|
| 579 | For more details, please see <filename>initscripts/mysql/README.mysql</filename>. |
---|
| 580 | </para> |
---|
[3413] | 581 | |
---|
[3116] | 582 | <para> |
---|
| 583 | If no error occured, then your print quota database is ready to be used. |
---|
| 584 | Now you can let the print quota database server alone, the remaining work |
---|
| 585 | will have to be done on each one of the print servers which will |
---|
| 586 | use this particular print quota database server. |
---|
| 587 | <tip> |
---|
| 588 | <title>Tip</title> |
---|
| 589 | <para> |
---|
| 590 | If an error occured, maybe your MySQL version is too old, or |
---|
| 591 | an unexpected problem (like a bug) happened. Please contact us via email so that we |
---|
| 592 | can try to fix the problem. Thanks in advance. |
---|
| 593 | </para> |
---|
[3413] | 594 | </tip> |
---|
[3116] | 595 | </para> |
---|
[3413] | 596 | |
---|
| 597 | </sect3> |
---|
| 598 | |
---|
[3116] | 599 | <sect3> |
---|
| 600 | <title>SQLite</title> |
---|
[3413] | 601 | |
---|
[3116] | 602 | <para> |
---|
| 603 | <application>SQLite</application> is an embeddable Relationnal DataBase |
---|
| 604 | distributed under a Free Software |
---|
[3413] | 605 | license from the |
---|
[3116] | 606 | <ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink> |
---|
[3413] | 607 | web site. |
---|
[3116] | 608 | If is very easy to configure and use, offers a very small memory footprint, |
---|
| 609 | is very fast, but can only be used on the print server because it doesn't include |
---|
| 610 | a server daemon : the database is directly embedded in the application. |
---|
| 611 | </para> |
---|
[3413] | 612 | |
---|
[3116] | 613 | <para> |
---|
| 614 | To configure your database, you must have SQLite already working. |
---|
| 615 | The complete installation of <application>SQLite</application> is not covered by |
---|
[3413] | 616 | the present manual, please refer to your system's documentation or to |
---|
[3116] | 617 | <ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink> for |
---|
| 618 | details. |
---|
| 619 | </para> |
---|
[3413] | 620 | |
---|
[3116] | 621 | <para> |
---|
| 622 | Once <application>SQLite</application> is installed, you have to decide where |
---|
| 623 | you'll put your database. A good idea is to store it into the <literal>pykota</literal> |
---|
| 624 | user's home directory. Then to create the database, just type : |
---|
[3413] | 625 | <screen> |
---|
[3116] | 626 | # sqlite3 ~pykota/pykota.db <pykota/initscripts/sqlite/pykota.sqlite |
---|
| 627 | # chown pykota.pykota ~pykota/pykota.db |
---|
| 628 | # chmod 660 ~pykota/pykota.db |
---|
| 629 | # chown pykota.pykota ~pykota |
---|
| 630 | </screen> |
---|
| 631 | </para> |
---|
| 632 | <para> |
---|
| 633 | If user <literal>pykota</literal> doesn't exist yet, then please |
---|
| 634 | follow the instructions a bit below which explain how to install PyKota on the print server. |
---|
| 635 | </para> |
---|
[3413] | 636 | |
---|
[3116] | 637 | <para> |
---|
| 638 | Once this is done, you'll want to set in <filename>~pykota/pykota.conf</filename> the |
---|
| 639 | following lines in the <literal>[global]</literal> section : |
---|
[3413] | 640 | <screen> |
---|
[3116] | 641 | storagebackend : sqlitestorage |
---|
| 642 | storagename : /etc/pykota/pykota.db |
---|
| 643 | </screen> |
---|
| 644 | </para> |
---|
| 645 | <para> |
---|
| 646 | Of course you'll want to replace the path on the <literal>storagename</literal> line |
---|
| 647 | with the full path to the newly created <application>SQLite</application> database. |
---|
| 648 | </para> |
---|
| 649 | <para> |
---|
| 650 | If no error occured, then your print quota database is ready to be used. |
---|
| 651 | In case you need them, additional instructions are available in <filename>pykota/initscripts/sqlite/README.sqlite</filename> |
---|
| 652 | <tip> |
---|
| 653 | <title>Tip</title> |
---|
| 654 | <para> |
---|
| 655 | If an error occured, maybe your SQLite version is too old, or |
---|
| 656 | an unexpected problem (like a bug) happened. Please contact us via email so that we |
---|
| 657 | can try to fix the problem. Thanks in advance. |
---|
| 658 | </para> |
---|
[3413] | 659 | </tip> |
---|
[3116] | 660 | </para> |
---|
[3413] | 661 | </sect3> |
---|
| 662 | |
---|
[3116] | 663 | <sect3> |
---|
| 664 | <title>Berkeley DB</title> |
---|
[3413] | 665 | |
---|
[3116] | 666 | <para> |
---|
| 667 | A <application>Berkeley DB</application> backend is planned, but it actually |
---|
| 668 | doesn't exist. It seems that remote storage won't be possible with such a backend, |
---|
| 669 | so in other terms this means that you will have a different quota database on |
---|
| 670 | each print server. This may still prove to be useful for small configurations. |
---|
| 671 | </para> |
---|
[3413] | 672 | </sect3> |
---|
| 673 | </sect2> |
---|
| 674 | |
---|
[856] | 675 | <sect2> |
---|
[3116] | 676 | <title>Print Server Installation</title> |
---|
[3413] | 677 | |
---|
[856] | 678 | <para> |
---|
[3116] | 679 | For each Print Server on which you plan to implement the print quota |
---|
[3413] | 680 | mechanism, you have, of course, to have an already working printing environment. |
---|
| 681 | Currently <application>PyKota</application> works with |
---|
[3116] | 682 | <ulink url="http://www.cups.org"><application>CUPS</application></ulink> |
---|
| 683 | but older releases also supported <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>. |
---|
| 684 | <application>LPRng</application> support might be re-added in the future. |
---|
[856] | 685 | </para> |
---|
[3413] | 686 | |
---|
[1052] | 687 | <para> |
---|
[3116] | 688 | Here's the list of software you have to install on each Print Server, version numbers |
---|
[3413] | 689 | are given as an indication of which was successfully tested, but older versions may |
---|
[3116] | 690 | work too. |
---|
| 691 | <itemizedlist> |
---|
| 692 | <listitem> |
---|
| 693 | <para> |
---|
[3413] | 694 | <application>CUPS</application> version 1.3.4 or higher. NB : |
---|
[3283] | 695 | <application>PyKota</application> releases up to and including 1.26 support |
---|
[3413] | 696 | <application>CUPS</application> version 1.1.14 or higher. |
---|
[3116] | 697 | You can download it from <ulink url="http://www.cups.org">http://www.cups.org</ulink> |
---|
| 698 | </para> |
---|
[3413] | 699 | </listitem> |
---|
[3116] | 700 | <listitem> |
---|
| 701 | <para> |
---|
[3472] | 702 | <application>Python</application> version 2.4 or higher. |
---|
[3116] | 703 | You can download it from <ulink url="http://www.python.org">http://www.python.org</ulink>. |
---|
| 704 | While <application>PyKota</application> itself will try to preserve compatibility |
---|
[3472] | 705 | with <application>Python</application> version 2.4 for the near future, some <application>Python</application> |
---|
[3116] | 706 | modules which are needed by <application>PyKota</application> may require a more recent version |
---|
| 707 | of this language. |
---|
| 708 | </para> |
---|
[3413] | 709 | </listitem> |
---|
[3116] | 710 | <listitem> |
---|
| 711 | <para> |
---|
| 712 | print quota database client libraries, depending on your print quota database backend : |
---|
| 713 | <itemizedlist> |
---|
| 714 | <listitem> |
---|
| 715 | <para> |
---|
| 716 | PostgreSQL backend : |
---|
| 717 | <itemizedlist> |
---|
| 718 | <listitem> |
---|
| 719 | <para> |
---|
| 720 | <application>PostgreSQL</application> client libraries. They must match the <application>PostgreSQL</application> |
---|
| 721 | version used on your print quota database server. |
---|
| 722 | </para> |
---|
[3413] | 723 | </listitem> |
---|
[3116] | 724 | <listitem> |
---|
| 725 | <para> |
---|
[3413] | 726 | The <application>PygreSQL</application> python module. |
---|
[3116] | 727 | <application>PygreSQL</application> is normally included in |
---|
| 728 | <application>PostgreSQL</application>, but you may want to |
---|
| 729 | download it from <ulink url="http://www.pygresql.org">http://www.pygresql.org</ulink> |
---|
| 730 | </para> |
---|
[3413] | 731 | </listitem> |
---|
| 732 | </itemizedlist> |
---|
[3116] | 733 | </para> |
---|
[3413] | 734 | </listitem> |
---|
[3116] | 735 | <listitem> |
---|
| 736 | <para> |
---|
[3413] | 737 | OpenLDAP backend : |
---|
[3116] | 738 | <itemizedlist> |
---|
| 739 | <listitem> |
---|
| 740 | <para> |
---|
| 741 | <application>OpenLDAP</application> client libraries. They must match |
---|
| 742 | the <application>OpenLDAP</application> version used on your print quota database server. |
---|
| 743 | </para> |
---|
[3413] | 744 | </listitem> |
---|
[3116] | 745 | <listitem> |
---|
| 746 | <para> |
---|
| 747 | The <application>Python-LDAP</application> python module. |
---|
| 748 | You may download this module from <ulink url="http://python-ldap.sourceforge.net">http://python-ldap.sourceforge.net</ulink> |
---|
| 749 | </para> |
---|
[3413] | 750 | </listitem> |
---|
[3116] | 751 | </itemizedlist> |
---|
| 752 | </para> |
---|
| 753 | </listitem> |
---|
| 754 | <listitem> |
---|
| 755 | <para> |
---|
| 756 | MySQL backend : |
---|
| 757 | <itemizedlist> |
---|
| 758 | <listitem> |
---|
| 759 | <para> |
---|
| 760 | <application>MySQL</application> client libraries. They must match the <application>MySQL</application> |
---|
| 761 | version used on your database server. |
---|
| 762 | </para> |
---|
[3413] | 763 | </listitem> |
---|
[3116] | 764 | <listitem> |
---|
| 765 | <para> |
---|
[3413] | 766 | The <application>Python-MySQL</application> python module, version 1.2.x or higher. |
---|
[3116] | 767 | You can download it from <ulink url="http://sourceforge.net/projects/mysql-python">http://sourceforge.net/projects/mysql-python</ulink> |
---|
| 768 | </para> |
---|
[3413] | 769 | </listitem> |
---|
| 770 | </itemizedlist> |
---|
[3116] | 771 | </para> |
---|
| 772 | </listitem> |
---|
| 773 | <listitem> |
---|
| 774 | <para> |
---|
| 775 | SQLite backend : SQLite is not a database server, but an embeddable database, so |
---|
[3413] | 776 | if you want to use it you MUST install SQLite on your print server. With |
---|
[3116] | 777 | <application>PostgreSQL</application>, <application>MySQL</application> or |
---|
| 778 | <application>OpenLDAP</application> you can store your datas on a different |
---|
| 779 | machine than the print server, but this is not possible with <application>SQLite</application>. |
---|
| 780 | <itemizedlist> |
---|
| 781 | <listitem> |
---|
| 782 | <para> |
---|
| 783 | <application>SQLite</application> version 3.2.1 or higher and its library. |
---|
[3413] | 784 | You can download it from |
---|
[3116] | 785 | <ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink> |
---|
| 786 | </para> |
---|
[3413] | 787 | </listitem> |
---|
[3116] | 788 | <listitem> |
---|
| 789 | <para> |
---|
| 790 | The <application>Python-SQLite</application> python module version 2.0.5 or higher. |
---|
[3413] | 791 | You can download it from |
---|
[3116] | 792 | <ulink url="http://www.pysqlite.org">http://www.pysqlite.org</ulink> |
---|
| 793 | </para> |
---|
[3413] | 794 | </listitem> |
---|
[3116] | 795 | </itemizedlist> |
---|
| 796 | </para> |
---|
| 797 | </listitem> |
---|
| 798 | <listitem> |
---|
| 799 | <para> |
---|
| 800 | Berkeley DB backend : Not supported yet. |
---|
| 801 | </para> |
---|
| 802 | </listitem> |
---|
[3413] | 803 | </itemizedlist> |
---|
[3116] | 804 | </para> |
---|
[3413] | 805 | </listitem> |
---|
[3116] | 806 | <listitem> |
---|
| 807 | <para> |
---|
| 808 | <application>ucd-snmp</application> or <application>net-snmp</application> tools, version 4.2.5 or above. You only need |
---|
| 809 | the <command>snmpget</command> command. |
---|
| 810 | You can download this software from <ulink url="http://www.sourceforge.net/projects/net-snmp/">http://www.sourceforge.net/projects/net-snmp/</ulink>. |
---|
| 811 | You only need this if PyKota's internal SNMP accounting code doesn't work for your SNMP-aware |
---|
[3472] | 812 | printers. In 99% of the cases, you won't need to install this. |
---|
[3116] | 813 | </para> |
---|
[3413] | 814 | </listitem> |
---|
[3116] | 815 | <listitem> |
---|
| 816 | <para> |
---|
| 817 | <application>netatalk</application> version 1.6.1 or above. You only need |
---|
| 818 | the <command>pap</command> command. |
---|
| 819 | You can download this software from <ulink url="http://netatalk.sourceforge.net/">http://netatalk.sourceforge.net/</ulink>. |
---|
[3472] | 820 | You only need this if you plan to query your printers for |
---|
| 821 | their internal page counter via AppleTalk. |
---|
| 822 | In 99% of the cases, you won't need to install this. |
---|
[3116] | 823 | </para> |
---|
[3413] | 824 | </listitem> |
---|
[3116] | 825 | <listitem> |
---|
| 826 | <para> |
---|
| 827 | eGenix' mxDateTime Python module version 2.0.3 or above. It must match your default Python version. |
---|
| 828 | You can download it from <ulink url="http://www.egenix.com">http://www.egenix.com</ulink>. |
---|
| 829 | </para> |
---|
[3413] | 830 | </listitem> |
---|
[3116] | 831 | <listitem> |
---|
| 832 | <para> |
---|
| 833 | The Python acccelerator <application>Psyco</application>. It must match your default Python version. |
---|
| 834 | You can download it from <ulink url="http://psyco.sourceforge.net">http://psyco.sourceforge.net</ulink>. |
---|
[3413] | 835 | You only need this if you run on the <literal>x86</literal> architecture because |
---|
[3472] | 836 | <application>Psyco</application> doesn't yet exist on |
---|
| 837 | other architectures. |
---|
| 838 | Feel free to install this or not. It might speedup the |
---|
| 839 | parsing of some print jobs by <appname>PyKota</appname>. |
---|
[3116] | 840 | </para> |
---|
[3413] | 841 | </listitem> |
---|
[3116] | 842 | <listitem> |
---|
| 843 | <para> |
---|
| 844 | The <application>pysnmp</application> Python module version 3.4.2, or higher, version 4 is recommanded. |
---|
| 845 | You can download it from <ulink url="http://pysnmp.sourceforge.net">http://pysnmp.sourceforge.net</ulink>. |
---|
| 846 | </para> |
---|
[3413] | 847 | </listitem> |
---|
[3116] | 848 | <listitem> |
---|
| 849 | <para> |
---|
[3413] | 850 | The <application>JAXML</application> Python module. |
---|
[3116] | 851 | You can download it from <ulink url="http://www.librelogiciel.com/software/">http://www.librelogiciel.com/software/</ulink>. |
---|
| 852 | </para> |
---|
[3413] | 853 | </listitem> |
---|
[3116] | 854 | <listitem> |
---|
| 855 | <para> |
---|
[3413] | 856 | The <application>ReportLab</application> Toolkit Python module. |
---|
[3116] | 857 | You can download it from <ulink url="http://www.reportlab.org">http://www.reportlab.org</ulink>. |
---|
| 858 | </para> |
---|
[3413] | 859 | </listitem> |
---|
[3116] | 860 | <listitem> |
---|
| 861 | <para> |
---|
[3413] | 862 | The <application>Python Imaging Library - PIL</application> module. |
---|
[3116] | 863 | You can download it from <ulink url="http://www.pythonware.com">http://www.pythonware.com</ulink>. |
---|
| 864 | </para> |
---|
[3413] | 865 | </listitem> |
---|
[3116] | 866 | <listitem> |
---|
| 867 | <para> |
---|
[3413] | 868 | The <application>PyOSD</application> Python module. |
---|
[3116] | 869 | You can download it from <ulink url="http://repose.cx/pyosd/">http://repose.cx/pyosd/</ulink>. |
---|
| 870 | </para> |
---|
[3413] | 871 | </listitem> |
---|
[3116] | 872 | <listitem> |
---|
| 873 | <para> |
---|
[3413] | 874 | The <application>pkpgcounter</application> Generic Page Description Language parser. |
---|
[3116] | 875 | You can download it from <ulink url="http://www.pykota.com.com/software/pkpgcounter">http://www.pykota.com/software/pkpgcounter</ulink>. |
---|
| 876 | </para> |
---|
[3413] | 877 | </listitem> |
---|
[3116] | 878 | <listitem> |
---|
| 879 | <para> |
---|
| 880 | The <application>PyPAM</application> Python interface to <acronym>PAM</acronym>. |
---|
| 881 | You'll need this if you plan to ask users to authenticate when printing through <command>pknotify</command> |
---|
| 882 | and <command>pykoticon</command>. You don't need this module otherwise. |
---|
| 883 | If needed, you can download it from <ulink url="http://www.pangalactic.org/PyPAM/">http://www.pangalactic.org/PyPAM/</ulink>. |
---|
| 884 | </para> |
---|
[3413] | 885 | </listitem> |
---|
[3116] | 886 | <listitem> |
---|
| 887 | <para> |
---|
| 888 | The <application>PkIPPLib</application> Python <acronym>IPP</acronym> library. |
---|
| 889 | You can download it from <ulink url="http://www.pykota.com/software/pkipplib">http://www.pykota.com/software/pkipplib</ulink>. |
---|
| 890 | </para> |
---|
[3413] | 891 | </listitem> |
---|
| 892 | </itemizedlist> |
---|
[1168] | 893 | </para> |
---|
[3413] | 894 | |
---|
[1168] | 895 | <para> |
---|
[3116] | 896 | Instead of downloading all these programs' sources and compiling them, which really |
---|
| 897 | is a boring task considering that many software are needed, you may prefer to look |
---|
| 898 | into the packages included with your GNU/Linux distribution of choice (if you use |
---|
| 899 | this operating system of course). Most, if not all, GNU/Linux distributions include |
---|
| 900 | all the software mentionned above, in the form of packages which are easier to |
---|
| 901 | install than sources tarballs. This is probably the same for the many *BSD |
---|
| 902 | distributions. |
---|
[1052] | 903 | </para> |
---|
[3413] | 904 | |
---|
[1052] | 905 | <para> |
---|
[3116] | 906 | You can check that all needed software is installed by launching the <command>checkdeps.py</command> |
---|
| 907 | command : |
---|
[3413] | 908 | <screen> |
---|
| 909 | $ python checkdeps.py |
---|
[1168] | 910 | </screen> |
---|
| 911 | </para> |
---|
[3413] | 912 | |
---|
[1168] | 913 | <para> |
---|
[3116] | 914 | Once all these software are installed, installing PyKota itself is a breeze. |
---|
[3413] | 915 | PyKota being written entirely in the Python language, which is interpreted, |
---|
[3116] | 916 | there's no need to compile anything. You just have to execute the installation |
---|
| 917 | script : |
---|
[3413] | 918 | <screen> |
---|
| 919 | $ python setup.py install |
---|
[1052] | 920 | </screen> |
---|
| 921 | </para> |
---|
[3413] | 922 | |
---|
[1052] | 923 | <para> |
---|
[3413] | 924 | The setup script will automatically create the |
---|
| 925 | <filename>/usr/share/pykota/conf</filename> directory and put the sample |
---|
[3116] | 926 | configuration files <filename>conf/pykota.conf.sample</filename> and |
---|
| 927 | <filename>conf/pykotadmin.conf.sample</filename> there, along with |
---|
| 928 | a <filename>README</filename> file explaining their purpose. |
---|
[1168] | 929 | </para> |
---|
[3413] | 930 | |
---|
[1168] | 931 | <para> |
---|
[3116] | 932 | Now you have to create a <literal>pykota</literal> system user and group. The <application>PyKota</application> |
---|
| 933 | software will automatically search its configuration files in user <literal>pykota</literal>'s |
---|
| 934 | home directory. For example we could create the user and group, and set <filename>/etc/pykota</filename> |
---|
| 935 | as the home directory, but any other home directory will do : |
---|
[3413] | 936 | <screen> |
---|
[3116] | 937 | adduser --system --group --home /etc/pykota --gecos PyKota pykota |
---|
| 938 | </screen> |
---|
[1168] | 939 | </para> |
---|
[3413] | 940 | |
---|
[1168] | 941 | <para> |
---|
[3116] | 942 | You now have to copy the sample configuration files into the <filename>~pykota</filename> |
---|
[3413] | 943 | directory, under the respective names <filename>pykota.conf</filename> and |
---|
[3116] | 944 | <filename>pykotadmin.conf</filename>. Once copied there, you just |
---|
| 945 | have to modify these files to adapt them to your own setup. |
---|
| 946 | These files are heavily commented, so you should have no problem. |
---|
| 947 | Also their format is quite common, because it's the one used by |
---|
| 948 | <application>Samba</application> for example, or by <literal>.ini</literal> |
---|
| 949 | files under <application>MS-Windows</application>, so you may already |
---|
| 950 | be familiar with this syntax. |
---|
| 951 | In a future release, this documentation will include the complete |
---|
| 952 | reference for all configuration fields available. Keep in mind that |
---|
| 953 | <application>PyKota</application> can be really heavily customized, and can delegate some work |
---|
| 954 | to any external command of your choice. |
---|
[1168] | 955 | </para> |
---|
[3413] | 956 | |
---|
[1168] | 957 | <para> |
---|
[3116] | 958 | Please create a backup copy of the <filename>~pykota</filename> |
---|
| 959 | directory before modifying a working installation. |
---|
[1052] | 960 | </para> |
---|
[3413] | 961 | |
---|
[856] | 962 | <para> |
---|
[3116] | 963 | PyKota features some interesting possibilities which allow you to |
---|
| 964 | define options either globally so that they apply to all printers, |
---|
| 965 | or on a per printer basis. Please see the sample configuration files |
---|
| 966 | to see what I mean. In the simplest form, only a <literal>[global]</literal> section is |
---|
[3413] | 967 | needed. In more complex configurations, you will have to create |
---|
[3116] | 968 | one section per printer. Each section in the configuration files |
---|
| 969 | begins with a name between square brackets <literal>[]</literal>. |
---|
| 970 | The name to use to define a particular printer section is the name |
---|
| 971 | of the print queue you want to manage with PyKota. |
---|
[856] | 972 | </para> |
---|
[3413] | 973 | |
---|
[2851] | 974 | <para> |
---|
[3116] | 975 | After you have modified <application>PyKota</application>'s configuration files, you have to |
---|
| 976 | double check their permissions, otherwise your installation may be |
---|
| 977 | insecure or may not work at all. |
---|
| 978 | The main configuration file <filename>~pykota/pykota.conf</filename> |
---|
| 979 | doesn't contain much sensitive information, so it can be made |
---|
| 980 | readable by anyone. If normal users read this file, at best they |
---|
| 981 | will learn the username and optional password of the read-only |
---|
| 982 | database user. This means that beside being allowed to read all the contents of |
---|
| 983 | the quota database, they won't be allowed to modify or delete it. |
---|
| 984 | On the other hand, the <filename>~pykota/pykotadmin.conf</filename> |
---|
| 985 | file contains the read-write user's identity and password. You must then |
---|
| 986 | ensure that no normal user can read this file. It should only be readable |
---|
[3413] | 987 | by the <literal>root</literal> user, which is always the case, and by |
---|
[3116] | 988 | <application>PyKota</application> administrators. In addition, |
---|
[3413] | 989 | users for which <application>CUPS</application> doesn't run as user <literal>root</literal> will |
---|
[3116] | 990 | have to ensure that the user their printing system is run as |
---|
| 991 | can read both of these files. An easy way to do so is to put the <literal>lp</literal> user |
---|
| 992 | (for example) into the <literal>pykota</literal> system group, then |
---|
| 993 | to give the correct permissions to <application>PyKota</application>'s configuration files : |
---|
[2851] | 994 | <screen> |
---|
[3413] | 995 | $ chown -R pykota.pykota ~pykota/ |
---|
[3116] | 996 | $ chmod 750 ~pykota/ |
---|
[3413] | 997 | $ chmod 644 ~pykota/pykota.conf |
---|
| 998 | $ chmod 640 ~pykota/pykotadmin.conf |
---|
[2851] | 999 | </screen> |
---|
[3413] | 1000 | |
---|
[3116] | 1001 | <warning> |
---|
| 1002 | <title>Warning</title> |
---|
[2851] | 1003 | <para> |
---|
[3413] | 1004 | All the users allowed to read the <filename>~pykota/pykotadmin.conf</filename> |
---|
[3116] | 1005 | are considered to be <application>PyKota</application> administrators. So be |
---|
| 1006 | careful with these files permissions. |
---|
[2851] | 1007 | </para> |
---|
[3116] | 1008 | </warning> |
---|
[2851] | 1009 | </para> |
---|
[3413] | 1010 | |
---|
[2851] | 1011 | <para> |
---|
[3116] | 1012 | On some systems, you may be able to strenghten permissions like this : |
---|
| 1013 | <screen> |
---|
[3413] | 1014 | $ chown -R pykota.pykota ~pykota/ |
---|
[3116] | 1015 | $ chmod 750 ~pykota/ |
---|
[3413] | 1016 | $ chmod 640 ~pykota/pykota.conf |
---|
| 1017 | $ chmod 600 ~pykota/pykotadmin.conf |
---|
[1187] | 1018 | </screen> |
---|
[1168] | 1019 | </para> |
---|
[3413] | 1020 | |
---|
[1168] | 1021 | <para> |
---|
[3116] | 1022 | And on other ones, you may need to relax them, and change the files' owner : |
---|
[1168] | 1023 | <screen> |
---|
[3413] | 1024 | $ chown pykota.pykota ~pykota/ |
---|
[3116] | 1025 | $ chmod 755 ~pykota/ |
---|
[3413] | 1026 | $ chown lp.pykota ~pykota/pykota.conf |
---|
| 1027 | $ chmod 640 ~pykota/pykota.conf |
---|
| 1028 | $ chown lp.pykota ~pykota/pykotadmin.conf |
---|
| 1029 | $ chmod 640 ~pykota/pykotadmin.conf |
---|
[1168] | 1030 | </screen> |
---|
| 1031 | </para> |
---|
[3413] | 1032 | |
---|
[1168] | 1033 | <para> |
---|
[3116] | 1034 | This all depends on the printing system you are using, and the user the |
---|
| 1035 | printing system is usually running as. You need to remember three things : |
---|
[3413] | 1036 | |
---|
[3116] | 1037 | <itemizedlist> |
---|
| 1038 | <listitem> |
---|
| 1039 | <para> |
---|
| 1040 | The user your printing system runs as MUST be allowed to read |
---|
| 1041 | both <application>PyKota</application>'s configuration files. |
---|
[3413] | 1042 | </para> |
---|
| 1043 | </listitem> |
---|
| 1044 | <listitem> |
---|
[3116] | 1045 | <para> |
---|
| 1046 | Any user who can read <filename>pykotadmin.conf</filename> |
---|
| 1047 | is a <application>PyKota</application> administrator, and |
---|
| 1048 | can do whatever he wants to the print quota database. |
---|
| 1049 | </para> |
---|
| 1050 | </listitem> |
---|
[3413] | 1051 | <listitem> |
---|
[3116] | 1052 | <para> |
---|
| 1053 | If <filename>cupsd.conf</filename> contains <literal>RunAsUser</literal>, then |
---|
| 1054 | you won't be able to authenticate users with <command>pknotify</command> and <command>pykoticon</command>. |
---|
| 1055 | Also in this case you may have to make <application>PyKota</application>'s configuration files |
---|
| 1056 | owned by the user <application>CUPS</application> runs as. |
---|
| 1057 | </para> |
---|
| 1058 | </listitem> |
---|
[3413] | 1059 | </itemizedlist> |
---|
[1187] | 1060 | </para> |
---|
[3413] | 1061 | |
---|
[1187] | 1062 | <para> |
---|
[3116] | 1063 | Don't forget to restart your print server sofware if you changed group membership for the user it runs |
---|
| 1064 | as, otherwise your change wouldn't be taken into account. |
---|
[1187] | 1065 | </para> |
---|
[3413] | 1066 | |
---|
[1187] | 1067 | <para> |
---|
[3116] | 1068 | Now depending on your printing system, the configuration to do is particular. |
---|
| 1069 | We will now see how to plug PyKota into <application>CUPS</application> since <application>LPRng</application> |
---|
| 1070 | is not supported anymore. |
---|
[1168] | 1071 | </para> |
---|
[3413] | 1072 | |
---|
[1168] | 1073 | <sect3> |
---|
[3116] | 1074 | <title>With CUPS</title> |
---|
[3413] | 1075 | |
---|
[1168] | 1076 | <para> |
---|
[3116] | 1077 | From version 1.16alpha7 on, configuring <application>PyKota</application> to integrate |
---|
| 1078 | within <application>CUPS</application> is more than easy. |
---|
[1168] | 1079 | </para> |
---|
[3413] | 1080 | |
---|
[1187] | 1081 | <para> |
---|
[3116] | 1082 | You just have to create a symbolic link to the <command>cupspykota</command> |
---|
| 1083 | command in <application>CUPS</application>' backend directory : |
---|
[3413] | 1084 | <screen> |
---|
| 1085 | $ cd /usr/lib/cups/backend |
---|
[3116] | 1086 | $ ln -s /usr/share/pykota/cupspykota cupspykota |
---|
| 1087 | </screen> |
---|
[2835] | 1088 | </para> |
---|
[3413] | 1089 | |
---|
[2835] | 1090 | <para> |
---|
[3472] | 1091 | As an alternative you can simply copy it : |
---|
| 1092 | <screen> |
---|
| 1093 | $ cp /usr/share/pykota/cupspykota /usr/lib/cups/backend |
---|
| 1094 | </screen> |
---|
| 1095 | </para> |
---|
| 1096 | |
---|
| 1097 | <para> |
---|
[3116] | 1098 | If you use CUPS v1.2 or higher, you must |
---|
[3472] | 1099 | also type the following commands to allow the <command>cupspykota</command> |
---|
[3116] | 1100 | backend to correctly support other backends which must be run |
---|
| 1101 | as the root user (e.g. the <command>lpd</command> backend) : |
---|
[3413] | 1102 | <screen> |
---|
[3472] | 1103 | $ chown root.root /usr/share/pykota/cupspykota |
---|
[3116] | 1104 | $ chmod 700 /usr/share/pykota/cupspykota |
---|
| 1105 | </screen> |
---|
| 1106 | </para> |
---|
[3413] | 1107 | |
---|
[3116] | 1108 | <para> |
---|
[3472] | 1109 | As an alternative, if you've copied the backend instead of |
---|
| 1110 | having created a symbolic link : |
---|
| 1111 | <screen> |
---|
| 1112 | $ chown root.root /usr/lib/cups/backend/cupspykota |
---|
| 1113 | $ chmod 700 /usr/lib/cups/backend/cupspykota |
---|
| 1114 | </screen> |
---|
| 1115 | </para> |
---|
| 1116 | |
---|
| 1117 | <para> |
---|
[3116] | 1118 | You have to restart <application>CUPS</application> for this modification to |
---|
[3413] | 1119 | take effect : |
---|
[1187] | 1120 | <screen> |
---|
[3413] | 1121 | $ /etc/init.d/cupsys restart |
---|
[1187] | 1122 | </screen> |
---|
[3116] | 1123 | </para> |
---|
[3413] | 1124 | |
---|
[3116] | 1125 | <para> |
---|
[3413] | 1126 | Now point your web browser to CUPS configuration page, usually at |
---|
[3116] | 1127 | <ulink url="http://localhost:631">http://localhost:631</ulink> on |
---|
| 1128 | your print server. |
---|
| 1129 | </para> |
---|
[3413] | 1130 | |
---|
[3116] | 1131 | <para> |
---|
| 1132 | Then when creating new printers or reconfiguring existing ones, just |
---|
| 1133 | choose devices which are <literal>PyKota managed</literal> |
---|
| 1134 | <footnote> |
---|
| 1135 | <para> |
---|
| 1136 | Debian 3.0 Woody is known to have problems : CUPS 1.1.14 doesn't automatically |
---|
| 1137 | detect <literal>PyKota managed</literal> devices. So you have to manually |
---|
[3413] | 1138 | modify CUPS' <filename>printers.conf</filename> file as explained in |
---|
[3116] | 1139 | PyKota's toplevel <filename>README</filename> file. |
---|
| 1140 | </para> |
---|
| 1141 | </footnote> |
---|
| 1142 | instead of |
---|
| 1143 | normal devices. You've got one <literal>PyKota managed</literal> device |
---|
| 1144 | for each regular device available from CUPS, so just choose the appropriate |
---|
| 1145 | one. |
---|
| 1146 | </para> |
---|
[3413] | 1147 | |
---|
[3116] | 1148 | <para> |
---|
| 1149 | Repeat the above procedure for each print queue on which you want to use |
---|
| 1150 | PyKota. That's all ! |
---|
| 1151 | </para> |
---|
[3413] | 1152 | |
---|
[3116] | 1153 | <sect4> |
---|
| 1154 | <title>Troubleshooting</title> |
---|
| 1155 | <para> |
---|
| 1156 | In case of problem, the simplest way to solve it is currently |
---|
| 1157 | to ask on PyKota's mailing list, describing the symptoms, as |
---|
| 1158 | well as the hardware and software you use. |
---|
| 1159 | </para> |
---|
[3413] | 1160 | |
---|
[3116] | 1161 | <para> |
---|
[3413] | 1162 | A searchable FAQ is now available at |
---|
[3116] | 1163 | <ulink url="http://otrs.librelogiciel.com/otrs/public.pl">http://otrs.librelogiciel.com/public.pl</ulink>. |
---|
| 1164 | A FAQ entry explaining in great details how to diagnose a problem correctly is |
---|
[3413] | 1165 | available at |
---|
[3116] | 1166 | <ulink url="http://otrs.librelogiciel.com/otrs/public.pl?ID=2">http://otrs.librelogiciel.com/public.pl?ID=2</ulink>. |
---|
| 1167 | </para> |
---|
[3413] | 1168 | |
---|
[3116] | 1169 | <para> |
---|
| 1170 | You can also ask questions on IRC : |
---|
| 1171 | <screen> |
---|
[3413] | 1172 | /server irc.freenode.net |
---|
[3116] | 1173 | /join #pykota |
---|
| 1174 | </screen> |
---|
[3413] | 1175 | </para> |
---|
| 1176 | </sect4> |
---|
| 1177 | |
---|
[3116] | 1178 | </sect3> |
---|
[3413] | 1179 | |
---|
| 1180 | </sect2> |
---|
[3116] | 1181 | </sect1> |
---|
[753] | 1182 | </chapter> |
---|
| 1183 | |
---|