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

<!-- $Id$ -->

<chapter>
  <title id="installation">Installation</title>
  
  <para>Last modified on $Date$</para>
  
  <para>
    Before being able to use <application>PyKota</application>, you have of course to
    install it first. But before installing, you must carefully plan your installation.
  </para>
  
  <para>
    First you have to determine which machine will be the <application>PyKota</application>
    <firstterm>Storage Server</firstterm>. The Storage Server is the host responsible
    for keeping a centralized database of print usage for all your printers, users and groups.
  </para>
  
  <para>
    Then you have to list all the <firstterm>Print Servers</firstterm> for which
    you plan to use <firstterm>print quota</firstterm> facilities.
  </para>
  
  <para>
    Finally you have to download <application>PyKota</application>'s latest version
    or buy an official package, from 
    <ulink url="http://www.librelogiciel.com/software/">http://www.librelogiciel.com/software/</ulink>.
    If you've just bought an official package, then as soon as you've receive it you
    have to decompress and visit its archive, to do so just type the following commands :
    <screen>
jerome@nordine:~$ tar -zxf pykota-1.14_official.tar.gz    
jerome@nordine:~$ cd pykota-1.14_official
jerome@nordine:~/pykota-1.14_official$
    </screen>
  </para>
  
  <para>
    You can see many files in this directory, the first ones to read are <filename>README</filename>,
    then <filename>COPYING</filename> and <filename>LICENSE</filename>. They will give you
    basic installation instructions and explain the licensing terms under which 
    <application>PyKota</application> is distributed. Of course they are also mostly
    boring to read ! Detailed installation and operating instructions are defined
    in the <filename>./docs</filename> directory, in the form of <acronym>SGML</acronym>
    documentation in the <ulink url="http://www.docbook.org">DocBook</ulink> format.
    You have to compile these files into readable documentation like the <acronym>HTML</acronym>
    or <acronym>PDF</acronym> formats, or buy an official <application>PyKota</application> package
    which already contains these compiled forms of the documentation.
  </para>
  
  <para>
    Now we will see what has to be done on each of the servers we are planning to use.
    <note>
      <title>Note</title>
      <para>
        Of course, depending on the size of your network, you may very well
        use the same machine as both a Print Server and a Storage Server.
        This is especially the case if you've got only one server.
      </para>
    </note>  
  </para>
  
  <sect1>
    <title>Storage Server Installation</title>
    
    <para>
      Depending on <application>PyKota</application>'s version number, different
      types of storage backends may be supported, so we will see for each one of
      them how to configure it.
    </para>
    
    <sect2>
      <title>PostgreSQL</title>
      
      <para>
        <application>PostgreSQL</application> is an <firstterm>Object Relationnal DataBase
        Management System</firstterm> distributed under a <firstterm>Free Software</firstterm>
        license from the 
        <ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink>
        web site. It certainely is the free <acronym>RDBMS</acronym> which has the most advanced
        features, and is widely used all over the world.
      </para>
      
      <para>
        To configure your Storage Server, you must have PostgreSQL already working.
        The complete installation of <application>PostgreSQL</application> is not covered by
        the present manual, please refer to your system's documentation or to 
        <ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink> for
        details.
      </para>
      
      <para>
        One thing you have to check, though, is that every Print Server on which you
        want to install the print quota mechanism, must be able to connect to the
        <application>PostgreSQL</application> server. In the default installation of
        <application>PostgreSQL</application> this may not be the case for security reasons, except if both
        servers are in fact the same machine. In any case, it is recommended that you
        check the <filename>/etc/postgresql/pg_hba.conf</filename> file and modify it if
        needed. This file is self documented and its modification is straightforward.
        You also have to make sure that <application>PostgreSQL</application> accepts <acronym>TCP/IP</acronym> connections.
        To do so you either have to launch it with the <option>-i</option> option or
        modify the <filename>/etc/postgresql/postgresql.conf</filename> file, which is
        self documented and easy to modify too.
        <tip>
          <title>Tip</title>
          <para>
            Don't forget to restart <application>PostgreSQL</application> if you modify
            any of its configuration files, in order for the changes to take effect.
          </para>
        </tip>  
      </para>
      
      <para>
        Be careful, you may be unable to connect from a Print Server to the <application>PostgreSQL</application>
        server even if the configuration is correct. Sometimes your connections may be blocked by
        one or more network firewalls along the route from one machine to the other. If this
        is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm>
        to not filter the IP port used by <application>PostgreSQL</application>, which is
        usually port <literal>5432/tcp</literal>.
        <note>
          <title>Note</title>
          <para>
            The TCP/IP network port used by PostgreSQL may be different. When in doubt, ask your 
            <firstterm>System Administrator</firstterm> for the correct value. 
          </para>
        </note>  
      </para>
      
      <para>
        Now that your <application>PostgreSQL</application> server is up and running, and
        is waiting for your connections, you have to create the Quota Storage DataBase.
        To do so, you'll have to feed <application>PostgreSQL</application> with the
        <filename>pykota-x.xx/initscripts/postgresql/pykota-postgresql.sql</filename> file.
        This file will create a Quota DataBase administrator in the <application>PostgreSQL</application> system, then create an empty
        Quota DataBase and set some permissions on it. The Quota DataBase administrator
        is the <application>PostgreSQL</application>'s user used to manage the Quota database.
        The Quota DataBase Administrator is not present in the Quota Database
        itself, he is only defined in <application>PostgreSQL</application> and don't
        have to exist on any system, nor in the Quota DataBase. His default names
        is <literal>pykotaadmin</literal>. 
        A Quota Storage read-only user is also created under the name of <literal>pykotauser</literal>.
        This read-only user is used by <application>PyKota</application> to connect to the 
        Quota Storage when a non-root user launches a pykota command. This prevents normal
        users from being able to modify their own, or other users', quota information.
        The database which will be created will be named <literal>pykota</literal> by default.
        <note>
          <title>Note</title>
          <para>
            You can choose other names if you want, just modify the 
            <filename>initscripts/postgresql/pykota-postgresql.sql</filename> file
            accordingly, and report your changes into <application>PyKota</application>'s
            configuration file.
          </para>
        </note>  
      </para>
      
      <para>
        To run this script, you can use the <application>psql</application> frontend to
        <application>PostgreSQL</application>, but your priviledges must be sufficient
        to be allowed to create users and databases. You can launch <application>psql</application>
        as the <literal>postgres</literal> user which is <application>PostgreSQL</application>'s
        default administrator, and connect to the default database named <literal>template1</literal>.
        From a command line interpreter (i.e. shell), type the following commands :
        <screen>
jerome@nordine:~$ cd pykota-1.14_official/initscripts/postgresql
jerome@nordine:~/pykota-1.14_official/initscripts$ psql -h localhost -U postgres template1
Welcome to psql, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help on internal slash commands
       \g or terminate with semicolon to execute query
       \q to quit

template1=# \i pykota-postgresql.sql 
            ... a lot of output lines
pykota=#       
        </screen>
      </para>
      
      <para>
        For security reasons, you may want to set passwords in 
        <application>PostgreSQL</application> for the 
        <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users.
        Otherwise any user able to connect to 
        <application>PostgreSQL</application> on your Quota Storage Server 
        could connect to the quota database, and either see it, or even modify it without problem. 
      </para>
      
      <para>
        To do so, just type the following lines while still being at the <application>psql</application>
        prompt (replace the password values by your own, and do the same for the <literal>pykotauser</literal> user) :
        <screen>
pykota=# ALTER USER pykotaadmin PASSWORD 'somepassword';
ALTER USER
pykota=# \q
jerome@nordine:~/pykota-1.14_official/initscripts/postgresql$
        </screen>
      </para>
      
      <para>
        The <literal>\q</literal> command above will quit the <application>psql</application>
        program and return you to the shell's command line prompt.
      </para>
      
      <para>
        To improve security further, you could encrypt your database connections, or
        take any other step as needed. Please refer to <application>PostgreSQL</application>'s
        documentation for details. Also if <application>PyKota</application>'s configuration
        file <filename>/etc/pykota/pykotadmin.conf</filename> is readable by anyone with access on your file system, a local user could 
        create some script to modify his own print quota.
        <warning>
          <title>Warning</title>
          <para>
            Defining passwords may not be sufficient if your database access rule is
            set to <literal>trust</literal> in the <filename>/etc/postgresql/pg_hba.conf</filename>.
            Again, please refer to <application>PostgreSQL</application>'s documentation
            for details. Also, passwords will fly unencrypted over the network by default,
            so be sure to take any necessary step to secure your database server from
            unauthorized use. This has nothing to do with <application>PyKota</application>
            though, it is just a general rule to keep in mind.
          </para>
        </warning>  
      </para>
      
      <para>
        If no error occured, then your Quota DataBase is ready to be used.
        Now you can let the Quota Storage Server alone, the remaining work
        will have to be done on each one of the print servers which will
        use this particular Quota Storage Server.
        <tip>
          <title>Tip</title>
          <para>
            If an error occured, maybe your PostgreSQL version is too old, or
            an unexpected problem (like a bug) happened. Please send me an email so that I
            can try to solve the problem. Thanks in advance.
          </para>
        </tip>  
      </para>
      
    </sect2>  
    
    <sect2>
      <title>LDAP</title>
      
      <para>
        From version 1.09 on, <application>OpenLDAP</application> can be used as a Quota Storage Backend.
        It is possible that other LDAP servers can be used, but this is currently untested.
      </para>
      
      <para>
        To use <application>OpenLDAP</application> as your Quota Storage Backend, you have to copy the
        <filename>pykota/initscripts/ldap/pykota.schema</filename> in <application>OpenLDAP</application>'s 
        schemas directory.
        Under Debian GNU/Linux, this is something like :
        <screen>        
$ cp pykota.schema /etc/ldap/schema
        </screen>
     </para>
     <para>   
       Then edit <filename>/etc/ldap/slapd.conf</filename> and add a line to    
       include the PyKota schema. You should have something
       like :
       <screen>    
# Schema and objectClass definitions
include         /etc/ldap/schema/core.schema
include         /etc/ldap/schema/cosine.schema
include         /etc/ldap/schema/nis.schema
include         /etc/ldap/schema/inetorgperson.schema
include         /etc/ldap/schema/pykota.schema
        </screen>        
      </para>
      <para>
        Finally, restart the <application>OpenLDAP</application> server :    
        <screen>    
$ /etc/init.d/slapd restart
        </screen>
      </para>
      
      <para>
        Then you have to modify PyKota's configuration files <filename>/etc/pykota/pykota.conf</filename>
        and <filename>/etc/pykota/pykotadmin.conf</filename>
        to include LDAP specific options. You may want to give a look at 
        <filename>pykota/conf/pykota.conf.sample</filename> to see all the options that are
        needed. Adapt the values to your own configuration, and finally initialize your 
        Quota Storage with the help of the <application>edpykota</application> command.
      </para>
    </sect2>  
    
    <sect2>
      <title>MySQL</title>
      
      <para>
        A <application>MySQL</application> Storage Backend is planned, but it actually
        doesn't exist.
      </para>
    </sect2>  
    
    <sect2>
      <title>Berkeley DB</title>
      
      <para>
        A <application>Berkeley DB</application> Storage Backend is planned, but it actually
        doesn't exist. It seems that remote storage won't be possible with such a backend,
        so in other terms this means that you will have a different quota database on
        each print server. This may still prove to be useful for small configurations.
      </para>
    </sect2>  
  </sect1>  
  
  <sect1>
    <title>Print Server Installation</title>
    
    <para>
      For each Print Server on which you plan to implement the print quota
      mechanism, you have, of course, to have an already working printing environment. 
      Currently <application>PyKota</application> works with either the
      <ulink url="http://www.cups.org"><application>CUPS</application></ulink>
      or the <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>,
      but more may be added in the future.
    </para>
    
    <para>
      Here's the list of software you have to install on each Print Server, version numbers
      are given as an indication of which was successfully tested, but older versions may 
      work too.
      <itemizedlist>
        <listitem>
          <para>
            <application>CUPS</application> version 1.1 or above, or <application>LPRng</application>
            version 3.8.20 or above (it probably works with older versions but this is untested).
            You can download them from <ulink url="http://www.cups.org">http://www.cups.org</ulink>
            or <ulink url="http://lprng.sourceforge.net">http://lprng.sourceforge.net</ulink>
          </para>
        </listitem>  
        <listitem>
          <para>
            Python version 2.1 or above.
            You can download it from <ulink url="http://www.python.org">http://www.python.org</ulink>.
          </para>
        </listitem>  
        <listitem>
          <para>
            Quota Storage client libraries, depending on your Quota Storage Backend :
            <itemizedlist>
              <listitem>
                <para>
                  PostgreSQL backend :
                  <itemizedlist>
                    <listitem>
                      <para>
                        <application>PostgreSQL</application> client libraries. They must match the <application>PostgreSQL</application>
                        version used on your Quota Storage Server.
                      </para>
                    </listitem>  
                    <listitem>
                      <para>
                        The <application>PygreSQL</application> python module. 
                        It must match the 
                        <application>PostgreSQL</application> client libraries'
                        version, as well as Python's version.
                      </para>
                    </listitem>  
                  </itemizedlist>  
                </para>
              </listitem>  
              <listitem>
                <para>
                  LDAP backend : TODO
                </para>
              </listitem>
              <listitem>
                <para>
                  MySQL backend : TODO
                </para>
              </listitem>
              <listitem>
                <para>
                  Berkeley DB backend : TODO
                </para>
              </listitem>
            </itemizedlist>  
          </para>
        </listitem>  
        <listitem>
          <para>
            <application>ucd-snmp</application> or <application>net-snmp</application> tools, version 4.2.5 or above. You only need
            the <application>snmpget</application> command.
            You can download them from <ulink url="http://www.sourceforge.net/projects/net-snmp/">http://www.sourceforge.net/projects/net-snmp/</ulink>.
            You only need this if you plan to query your printers for their internal page counter via SNMP.
          </para>
        </listitem>  
        <listitem>
          <para>
            <application>netatalk</application> version 1.6.1 or above. You only need
            the <application>pap</application> command.
            You can download them from <ulink url="http://netatalk.sourceforge.net/">http://netatalk.sourceforge.net/</ulink>.
            You only need this if you plan to query your printers for their internal page counter via AppleTalk.
          </para>
        </listitem>  
        <listitem>
          <para>
            eGenix' mxDateTime Python module version 2.0.3 or above. It must match your default Python version.
            You can download it from <ulink url="http://www.egenix.com">http://www.egenix.com</ulink>.
          </para>
        </listitem>  
      </itemizedlist>  
    </para>
  </sect1>  
</chapter>

<!--

$Log$
Revision 1.20  2003/07/25 13:20:32  jalet
Typo which wasn't

Revision 1.19  2003/07/25 13:18:44  jalet
Typos

Revision 1.18  2003/07/25 10:41:29  jalet
Better documentation.
pykotme now displays the current user's account balance.
Some test changed in ldap module.

Revision 1.17  2003/06/30 21:44:18  jalet
1.09 is out !

Revision 1.16  2003/06/24 21:37:05  jalet
Minor changes

Revision 1.15  2003/06/10 16:37:54  jalet
Deletion of the second user which is not needed anymore.
Added a debug configuration field in /etc/pykota.conf
All queries can now be sent to the logger in debug mode, this will
greatly help improve performance when time for this will come.

Revision 1.14  2003/06/05 07:12:29  jalet
Reorganization of directories

Revision 1.13  2003/04/24 21:09:47  jalet
Documentation slightly improved.

Revision 1.12  2003/04/17 21:33:16  jalet
Version 1.03 is out.

Revision 1.11  2003/03/25 09:32:06  jalet
Improved documentation.

Revision 1.10  2003/03/23 17:59:56  jalet
Clarify a point.

Revision 1.9  2003/03/23 17:57:20  jalet
Deleted a repetition.

Revision 1.8  2003/03/22 15:34:50  jalet
More complete installation documentation.

Revision 1.7  2003/03/22 14:26:45  jalet
Download instructions added.

Revision 1.6  2003/03/22 14:06:02  jalet
Quota Storage Server installation is OK for PostgreSQL.

Revision 1.5  2003/03/22 13:11:33  jalet
The port on which the Quota Storage Sever is listening can now
be set in the configuration file (see sample).
Better error handling if PygreSQL is not installed.
Improved documentation.
Version number changed to 1.02alpha

Revision 1.4  2003/03/22 07:20:38  jalet
More information wrt PostgreSQL tcp/ip configuration.

Revision 1.3  2003/03/18 22:18:25  jalet
The documentation will only be a sequence of chapters in a single part, not
multiple parts each including chapters.

Revision 1.2  2003/03/18 22:10:54  jalet
Documentation improvements.

Revision 1.1  2003/02/08 00:03:35  jalet
Documentation skeleton added


-->