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

<!-- $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.24_official.tar.gz    
jerome@nordine:~$ cd pykota-1.24_official
jerome@nordine:~/pykota-1.24_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. Of course you already
    know this because that's what you are currently reading !
  </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. Allowing <acronym>TCP/IP</acronym> connections
        is not necessary though if your Quota Storage Server and your Print Server are
        the very same host.
      </para>  
      
      <para>
        Here's an excerpt from a <filename>pg_hba.conf</filename> file. This one rejects all
        connections to PyKota's database excepted when made from the same host by <application>PostgreSQL</application> users
        <literal>pykotauser</literal> or <literal>pykotaadmin</literal> with the correct password.
<screen>        
        local all    postgres                              ident sameuser
        local all    all                                   reject
        host  pykota pykotauser  127.0.0.1 255.255.255.255 crypt
        host  pykota pykotaadmin 127.0.0.1 255.255.255.255 crypt
        host  pykota all         127.0.0.1 255.255.255.255 reject
</screen>
     </para>
     
     <para>
        Of course if your print server and your database servers have different <acronym>IP</acronym>
        addresses, you have to replace the <literal>127.0.0.1</literal> address above with your print
        server's <acronym>IP</acronym> address. As an alternative, you could still keep these
        lines and add similar lines with other <acronym>IP</acronym> addresses if you have several
        print servers for which you want a single centralized database.
        <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-1.24/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 name
        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 an user who is not a <application>PyKota</application> administrator 
        <footnote><para>a <application>PyKota</application> administrator is an user who can read the <filename>~pykota/pykotadmin.conf</filename> file.</para></footnote>
        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 files.
          </para>
        </note>  
      </para>
      
      <para>
        To run this script, you can use the <command>psql</command> frontend to
        <application>PostgreSQL</application>, but your priviledges must be sufficient
        to be allowed to create users and databases. You can launch <command>psql</command>
        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.24_official/initscripts/postgresql
jerome@nordine:~/pykota-1.24_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>
        <note>
          <title>Note</title>
          <para>
            If you use RPM or DEB packages, usually the
            <filename>pykota-postgresql.sql</filename> file gets installed into the
            <filename>/usr/share/pykota/postgresql</filename> directory, along 
            with a README file.
          </para>
        </note>  
      </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 <command>psql</command>
        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.24_official/initscripts/postgresql$
        </screen>
      </para>
      
      <para>
        The <literal>\q</literal> command above will quit the <command>psql</command>
        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. 
        <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 contact us via email so that we
            can try to fix the problem. Thanks in advance.
          </para>
        </tip>  
      </para>
      
    </sect2>  
    
    <sect2>
      <title>LDAP</title>
      
      <para>
        Any <acronym>LDAP</acronym> server, and particularly <application>OpenLDAP</application>, can be used 
        as a Quota Storage Backend.
        Some other LDAP servers can be used, but this is currently untested in production.
      </para>
      
      <para>
        <application>OpenLDAP</application> is a Lightweight Directory Access Protocol server
        implementation published as Free Software.
        You can download it from <ulink url="http://www.openldap.org">http://www.openldap.org</ulink>.
      </para>
      
      <para>
        To use <application>OpenLDAP</application> as your Quota Storage Backend, you have to copy the
        <filename>pykota/initscripts/ldap/pykota.schema</filename> into <application>OpenLDAP</application>'s 
        schemas directory.
        Under Debian GNU/Linux, this is something like :
        <screen>        
$ cp pykota.schema /etc/ldap/schema
        </screen>
        <note>
          <title>Note</title>
          <para>
            If you use RPM or DEB packages, the
            <filename>pykota.schema</filename> file is usually installed into the
            <filename>/usr/share/pykota/ldap</filename> directory, along
            with a README file, and may also be installed automatically in
            your <acronym>LDAP</acronym> server's schemas directory.
          </para>
        </note>  
     </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>
        While this is not mandatory, it is recommended that you setup
        some indexes for some often accessed PyKota attributes.
        Here are the minimal indexes
        lines you may want to put in <filename>slapd.conf</filename> :
        <screen>
# Indexes for PyKota
index pykotaUserName pres,eq,sub
index pykotaGroupName pres,eq,sub
index pykotaPrinterName pres,eq,sub
index pykotaBillingCode pres,eq,sub
index pykotaLastJobIdent eq
        </screen>
      </para>
      
      <para>
        Now you must ensure that the DNs you'll use to bind to    
        your OpenLDAP server don't have search queries size limits,
        which gives for example (OpenLDAP 2.1.x or above) :
        
<screen>        
# No Limits for PyKota's administrator and read-only user
limits dn="cn=pykotaadmin,dc=example,dc=com" size.soft=-1 size.hard=soft
limits dn="cn=pykotauser,dc=example,dc=com" size.soft=-1 size.hard=soft
</screen>        

        Where pykotaadmin and pykotauser are the usernames used to bind to your
        OpenLDAP server within PyKota, respectively in ReadWrite mode 
        (as set in pykotadmin.conf) and in ReadOnly mode (as set in pykota.conf).
      </para>
      
      <para>
        Finally, stop the <application>OpenLDAP</application> server, generate
        the index files, and restart <application>OpenLDAP</application>
        <screen>    
$ /etc/init.d/slapd stop
$ slapindex
$ /etc/init.d/slapd start
        </screen>
      </para>
      
      <para>
        With an <acronym>LDAP</acronym> backend, PyKota will need some branches
        in your <acronym>LDAP</acronym> directory to put its own datas.
        You can configure PyKota to either attach its datas to your existing
        users and groups, or to put them in their own <literal>ou</literal>.
        But some <literal>ou</literal>s dedicated to PyKota are needed in any case,
        so the best bet may be to put all PyKota's datas below an <literal>ou=PyKota</literal>
        branch. While this will separate these datas from your existing users and groups
        entries, this may ease the maintainance.
      </para>
      
      <para>
        PyKota needs at least an <literal>ou</literal> for printers, for users quotas, for
        groups quotas, for print jobs, for billing codes, and for pointers to the last job of each printer.
        In the future, this last <literal>ou</literal> may disappear as its content
        will probably be attached to each printer.
      </para>
      
      <para>
        Actually PyKota doesn't create these <literal>ou</literal>s for you, because it's
        difficult to guess what is the best configuration for you. So you have to
        create them by yourself, either directly with a text editor and the
        <command>ldapadd</command> command, or with some specialized tool
        like <command>gq</command>. You can look at the <filename>initscripts/ldap/pykota-sample.ldif</filename>
        file to see which minimal branches are necessary.
        <note>
          <title>Note</title>
          <para>
            If you use RPM or DEB packages, usually the
            <filename>pykota-sample.ldif</filename> file is installed into the
            <filename>/usr/share/pykota/ldap</filename> directory, along 
            with a README file.
          </para>
        </note>  
      </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 OpenLDAP version is too old, or
            an unexpected problem (like a bug) happened. Please contact us via email so that we
            can try to fix the problem. Thanks in advance.
          </para>
        </tip>  
      </para>
    </sect2>  
    
    <sect2>
      <title>MySQL</title>
      
      <para>
        <application>MySQL</application> is supported but not documented for now.
      </para>
    </sect2>  
    
    <sect2>
      <title>SQLite</title>
      
      <para>
        <application>SQLite</application> is supported but not documented for now.
      </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 
      <ulink url="http://www.cups.org"><application>CUPS</application></ulink>
      but older releases also supported <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>.
      <application>LPRng</application> support might be re-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.14 or above.
            You can download it from <ulink url="http://www.cups.org">http://www.cups.org</ulink>
          </para>
        </listitem>  
        <listitem>
          <para>
            <application>Python</application> version 2.2 or above.
            You can download it from <ulink url="http://www.python.org">http://www.python.org</ulink>.
            While <application>PyKota</application> itself will try to preserve compatibility
            with <application>Python</application> version 2.2 for the near future, some <application>Python</application>
            modules which are needed by <application>PyKota</application> may require a more recent version
            of this language.
          </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 have been compiled against the same
                        <application>PostgreSQL</application> client libraries.
                        <application>PygreSQL</application> is normally included in
                        <application>PostgreSQL</application>, but you may want to
                        download it from <ulink url="http://www.pygresql.org">http://www.pygresql.org</ulink>
                      </para>
                    </listitem>  
                  </itemizedlist>  
                </para>
              </listitem>  
              <listitem>
                <para>
                  OpenLDAP backend : 
                  <itemizedlist>
                    <listitem>
                      <para>
                        <application>OpenLDAP</application> client libraries. They must match
                        the <application>OpenLDAP</application> version used on your Quota Storage Server.
                      </para>
                    </listitem>  
                    <listitem>
                      <para>
                        The <application>Python-LDAP</application> python module.
                        It must have been compiled against the same
                        <application>OpenLDAP</application> client libraries.
                        You may download this module from <ulink url="http://python-ldap.sourceforge.net">http://python-ldap.sourceforge.net</ulink>
                      </para>
                    </listitem>  
                  </itemizedlist>
                </para>
              </listitem>
              <listitem>
                <para>
                  MySQL backend : Supported but not documented yet.
                </para>
              </listitem>
              <listitem>
                <para>
                  SQLite backend : Supported but not documented yet.
                </para>
              </listitem>
              <listitem>
                <para>
                  Berkeley DB backend : Not supported yet.
                </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 <command>snmpget</command> command.
            You can download this software 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 <command>pap</command> command.
            You can download this software 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>  
        <listitem>
          <para>
            The Python acccelerator <application>Psyco</application>. It must match your default Python version.
            You can download it from <ulink url="http://psyco.sourceforge.net">http://psyco.sourceforge.net</ulink>.
            You only need this if you run on the <literal>x86</literal> architecture because 
            <application>Psyco</application> doesn't yet exist on other architectures.
          </para>
        </listitem>  
        <listitem>
          <para>
            The <application>pysnmp</application> Python module version 3.4.2, 3.4.3 or 3.4.4 exclusively. 
            You can download it from <ulink url="http://pysnmp.sourceforge.net">http://pysnmp.sourceforge.net</ulink>.
          </para>
        </listitem>  
        <listitem>
          <para>
            The <application>JAXML</application> Python module. 
            You can download it from <ulink url="http://www.librelogiciel.com/software/">http://www.librelogiciel.com/software/</ulink>.
          </para>
        </listitem>  
        <listitem>
          <para>
            The <application>ReportLab</application> Toolkit Python module. 
            You can download it from <ulink url="http://www.reportlab.org">http://www.reportlab.org</ulink>.
          </para>
        </listitem>  
        <listitem>
          <para>
            The <application>Python Imaging Library - PIL</application> module. 
            You can download it from <ulink url="http://www.pythonware.com">http://www.pythonware.com</ulink>.
          </para>
        </listitem>  
        <listitem>
          <para>
            The <application>PyOSD</application> Python module. 
            You can download it from <ulink url="http://repose.cx/pyosd/">http://repose.cx/pyosd/</ulink>.
          </para>
        </listitem>  
        <listitem>
          <para>
            The <application>pkpgcounter</application> Generic Page Description Language parser. 
            You can download it from <ulink url="http://www.librelogiciel.com/software/">http://www.librelogiciel.com/software/</ulink>.
          </para>
        </listitem>  
        <listitem>
          <para>
            The <application>PyPAM</application> Python interface to <acronym>PAM</acronym>.
            You'll need this if you plan to ask users to authenticate when printing through <command>pknotify</command>
            and <command>pykoticon</command>. You don't need this module otherwise.
            If needed, you can download it from <ulink url="http://www.pangalactic.org/PyPAM/">http://www.pangalactic.org/PyPAM/</ulink>.
          </para>
        </listitem>  
      </itemizedlist>  
    </para>
    
    <para>
      Instead of downloading all these programs' sources and compiling them, which really
      is a boring task considering that many software are needed, you may prefer to look
      into the packages included with your GNU/Linux distribution of choice (if you use
      this operating system of course). Most, if not all, GNU/Linux distributions include
      all the software mentionned above, in the form of packages which are easier to
      install than sources tarballs. This is probably the same for the many *BSD
      distributions.
    </para>
    
    <para>
       You can check that all needed software is installed by launching the <command>checkdeps.py</command>
       command :
      <screen>      
$ python checkdeps.py      
      </screen>
    </para>
    
    <para>
      Once all these software are installed, installing PyKota itself is a breeze.
      PyKota being written entirely in the Python language, which is interpreted, 
      there's no need to compile anything. You just have to execute the installation
      script :
      <screen>      
$ python setup.py install      
      </screen>
    </para>
    
    <para>
      The setup script will automatically create the 
      <filename>/usr/share/pykota/conf</filename> directory and put the sample 
      configuration files <filename>conf/pykota.conf.sample</filename> and
      <filename>conf/pykotadmin.conf.sample</filename> there, along with
      a <filename>README</filename> file explaining their purpose.
    </para>
    
    <para>
      Now you have to create a <literal>pykota</literal> system user and group. The <application>PyKota</application>
      software will automatically search its configuration files in user <literal>pykota</literal>'s
      home directory. For example we could create the user and group, and set <filename>/etc/pykota</filename>
      as the home directory, but any other home directory will do :
<screen>      
    adduser --system --group --home /etc/pykota --gecos PyKota pykota
</screen>
    </para>
    
    <para>
      You now have to copy the sample configuration files into the <filename>~pykota</filename>
      directory, under the respective names <filename>pykota.conf</filename> and 
      <filename>pykotadmin.conf</filename>. Once copied there, you just
      have to modify these files to adapt them to your own setup.
      These files are heavily commented, so you should have no problem.
      Also their format is quite common, because it's the one used by
      <application>Samba</application> for example, or by <literal>.ini</literal>
      files under <application>MS-Windows</application>, so you may already
      be familiar with this syntax.
      In a future release, this documentation will include the complete
      reference for all configuration fields available. Keep in mind that
      <application>PyKota</application> can be really heavily customized, and can delegate some work
      to any external command of your choice.
    </para>
    
    <para>
      Please create a backup copy of the <filename>~pykota</filename>
      directory before modifying a working installation.
    </para>
    
    <para>
      PyKota features some interesting possibilities which allow you to
      define options either globally so that they apply to all printers,
      or on a per printer basis. Please see the sample configuration files
      to see what I mean. In the simplest form, only a <literal>[global]</literal> section is
      needed. In more complex configurations, you will have to create 
      one section per printer. Each section in the configuration files
      begins with a name between square brackets <literal>[]</literal>.
      The name to use to define a particular printer section is the name
      of the print queue you want to manage with PyKota.
    </para>
    
    <para>
      After you have modified <application>PyKota</application>'s configuration files, you have to
      double check their permissions, otherwise your installation may be
      insecure or may not work at all.
      The main configuration file <filename>~pykota/pykota.conf</filename>
      doesn't contain much sensitive information, so it can be made
      readable by anyone. If normal users read this file, at best they
      will learn the username and optional password of the read-only
      database user. This means that beside being allowed to read all the contents of
      the quota database, they won't be allowed to modify or delete it.
      On the other hand, the <filename>~pykota/pykotadmin.conf</filename>
      file contains the read-write user's identity and password. You must then
      ensure that no normal user can read this file. It should only be readable
      by the <literal>root</literal> user, which is always the case, and by 
      <application>PyKota</application> administrators. In addition,
      users for which <application>CUPS</application> doesn't run as user <literal>root</literal> will 
      have to ensure that the user their printing system is run as
      can read both of these files. An easy way to do so is to put the <literal>lp</literal> user
      (for example) into the <literal>pykota</literal> system group, then
      to give the correct permissions to <application>PyKota</application>'s configuration files :
      <screen>
$ chown pykota.pykota ~pykota/pykota.conf      
$ chmod 644 ~pykota/pykota.conf      
$ chown pykota.pykota ~pykota/pykotadmin.conf      
$ chmod 640 ~pykota/pykotadmin.conf      
      </screen>
      
      <warning>
        <title>Warning</title>
        <para>
          All the users allowed to read the <filename>~pykota/pykotadmin.conf</filename> 
          are considered to be <application>PyKota</application> administrators. So be
          careful with these files permissions.
        </para>
      </warning>
    </para>
    
    <para>
      On some systems, you may be able to strenghten permissions like this :
      <screen>
$ chown pykota.pykota ~pykota/pykota.conf      
$ chmod 640 ~pykota/pykota.conf      
$ chown pykota.pykota ~pykota/pykotadmin.conf      
$ chmod 600 ~pykota/pykotadmin.conf      
      </screen>
    </para>
    
    <para>
      And on other ones, you may need to relax them, and change the files' owner :
      <screen>
$ chown lp.pykota ~pykota/pykota.conf      
$ chmod 640 ~pykota/pykota.conf      
$ chown lp.pykota ~pykota/pykotadmin.conf      
$ chmod 640 ~pykota/pykotadmin.conf      
      </screen>
    </para>
    
    <para>
      This all depends on the printing system you are using, and the user the
      printing system is usually running as. You need to remember three things :
      
      <itemizedlist>
        <listitem>
          <para>
            The user your printing system runs as MUST be allowed to read
            both <application>PyKota</application>'s configuration files.
          </para>  
        </listitem>  
        <listitem>        
          <para>
            Any user who can read <filename>pykotadmin.conf</filename>
            is a <application>PyKota</application> administrator, and
            can do whatever he wants to the print quota database.
          </para>
        </listitem>
        <listitem>        
          <para>
            If <filename>cupsd.conf</filename> contains <literal>RunAsUser</literal>, then
            you won't be able to authenticate users with <command>pknotify</command> and <command>pykoticon</command>.
            Also in this case you may have to make <application>PyKota</application>'s configuration files
            owned by the user <application>CUPS</application> runs as.
          </para>
        </listitem>
      </itemizedlist>  
    </para>
    
    <para>
      Don't forget to restart your print server sofware if you changed group membership for the user it runs
      as, otherwise your change wouldn't be taken into account.
    </para>
    
    <para>
      Now depending on your printing system, the configuration to do is particular.
      We will now see how to plug PyKota into <application>CUPS</application> since <application>LPRng</application>
      is not supported anymore.
    </para>
    
    <sect2>
      <title>With CUPS</title>
      
      <para>
        From version 1.16alpha7 on, configuring <application>PyKota</application> to integrate
        within <application>CUPS</application> is more than easy.
      </para>
      
      <para>
        You just have to create a symbolic link to the <command>cupspykota</command>
        command in <application>CUPS</application>' backend directory :
        <screen>        
$ cd /usr/lib/cups/backend        
$ ln -s /usr/share/pykota/cupspykota cupspykota
        </screen>
      </para>
      
      <para>
        You have to restart <application>CUPS</application> for this modification to
        take effect : 
        <screen>
$ /etc/init.d/cupsys restart        
        </screen>
      </para>
      
      <para>
        Now point your web browser to CUPS configuration page, usually at 
        <ulink url="http://localhost:631">http://localhost:631</ulink> on
        your print server.
      </para>
      
      <para>
        Then when creating new printers or reconfiguring existing ones, just
        choose devices which are <literal>PyKota managed</literal>
        <footnote>
          <para>
            Debian 3.0 Woody is known to have problems : CUPS 1.1.14 doesn't automatically
            detect <literal>PyKota managed</literal> devices. So you have to manually
            modify CUPS' <filename>printers.conf</filename> file as explained in 
            PyKota's toplevel <filename>README</filename> file.
          </para>
        </footnote>
        instead of
        normal devices. You've got one <literal>PyKota managed</literal> device
        for each regular device available from CUPS, so just choose the appropriate
        one.
      </para>
      
      <para>
        Repeat the above procedure for each print queue on which you want to use
        PyKota. That's all !
      </para>
      
      <sect3>
        <title>Troubleshooting</title>
        <para>
          In case of problem, the simplest way to solve it is currently
          to ask on PyKota's mailing list, describing the symptoms, as
          well as the hardware and software you use.
        </para>
        
        <para>
          A searchable FAQ is now available at 
          <ulink url="http://otrs.librelogiciel.com/otrs/public.pl">http://otrs.librelogiciel.com/public.pl</ulink>.
          A FAQ entry explaining in great details how to diagnose a problem correctly is
          available at 
          <ulink url="http://otrs.librelogiciel.com/otrs/public.pl?ID=2">http://otrs.librelogiciel.com/public.pl?ID=2</ulink>.
        </para>
        
        <para>
          You can now ask questions on IRC :
          <screen>
/server irc.freenode.net          
/join #pykota
          </screen>
        </para>  
      </sect3>  
      
    </sect2>
    
  </sect1>  
</chapter>