Changeset 2527

Show
Ignore:
Timestamp:
09/29/05 20:20:17 (19 years ago)
Author:
jerome
Message:

Added the content of the introduction chapter

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • pykota/trunk/docs/introduction.sgml

    r2526 r2527  
    1313   
    1414  <sect1> 
    15     <title>What is PyKota ?</title> 
    16      
    17     <para> 
     15    <title>What is <application>PyKota</application> ?</title> 
     16     
     17    <para> 
     18      <application>PyKota</application> is a print quota and print accounting software solution 
     19      for GNU/Linux and compatible print servers. 
     20    </para> 
     21     
     22    <para> 
     23      PyKota currently supports the 
     24      <ulink url="http://www.cups.org"><application>CUPS</application></ulink> 
     25      <footnote><para>Common UNIX Printing System</para></footnote> 
     26      printing subsystem, although older releases also supported  
     27      <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>. 
     28    </para> 
     29     
     30    <para> 
     31      PyKota is distributed under the terms of the GNU General Public License of the 
     32      <ulink url="http://www.fsf.org">Free Software Foundation</ulink>. This means that 
     33      you are allowed to use, modify or redistribute its code provided that you respect 
     34      the terms of this license. 
     35    </para> 
     36     
     37    <para> 
     38      We believe that despite being a bit rough around the edges sometimes, <application>PyKota</application> 
     39      offers an unmatched flexibility and probably all you want to do with a print quota software is 
     40      either already included, easily scriptable with a few lines of shell scripting, or planned 
     41      for the next release. 
     42    </para> 
     43     
     44    <para> 
     45      <application>PyKota</application> is however a somewhat complex piece of software, and installing 
     46      it will mandate that you also install several dependencies beforehand, as you'll see in the 
     47      next chapter. 
     48    </para> 
     49     
     50    <para> 
     51      <application>PyKota</application> is made of the following components : 
     52      <itemizedlist> 
     53        <listitem> 
     54          <para> 
     55            Configuration files, which must be placed into the system user 
     56            <literal>pykota</literal>'s home directory : 
     57            <itemizedlist> 
     58              <listitem> 
     59                <para> 
     60                  <filename>pykotadmin.conf</filename> : this file contains sensitive database settings 
     61                  allowing the <application>PyKota</application> software to modify the 
     62                  print quota database. This file should be protected and should only be 
     63                  made readable by the administrators of <application>PyKota</application> 
     64                  and the system user the printing subsystem is running as. 
     65                  The possibility for a particular user to read this file determines if 
     66                  this user is a <application>PyKota</application> Administrator or not, 
     67                  so please give particular attention to this file's permissions. 
     68                </para> 
     69              </listitem>   
     70              <listitem> 
     71                <para> 
     72                  <filename>pykota.conf</filename> : this is the main configuration file for  
     73                  <application>PyKota</application>. It contains database settings which 
     74                  allow the <application>PyKota</application> software to access to the print 
     75                  quota database in readonly mode, as well as global and print queue specific 
     76                  configuration directives. With a properly configured <application>PyKota</application>,  
     77                  letting normal users read this file is safe 
     78                  excepted where you want to forbid users to read other users' print quota 
     79                  information. However if you're not confident about your database settings, 
     80                  it's better to not let normal users read this file. This way they can't even 
     81                  use any of the <application>PyKota</application> command line tools. 
     82                </para> 
     83              </listitem>   
     84            </itemizedlist> 
     85          </para> 
     86        </listitem>   
     87        <listitem> 
     88          <para> 
     89            Either a <application>PostgreSQL</application> database, or an <acronym>LDAP</acronym> 
     90            <footnote><para>Lightweight Directory Access Protocol</para></footnote> 
     91            <acronym>DIT</acronym> 
     92            <footnote><para>Directory Information Tree</para></footnote> : 
     93            <application>PyKota</application> can store its datas into any of these. Support 
     94            for other database backends  might be added in a future release. 
     95          </para> 
     96        </listitem>   
     97        <listitem> 
     98          <para> 
     99            A generic <acronym>CUPS</acronym> backend wrapper, named <filename>cupspykota</filename> : 
     100            this software captures all print jobs passing through the print queues it manages, 
     101            and does the accounting and quota checking. It can reject print jobs in a number 
     102            of circumstances like the user being over quota, and interact with the end user through the use of external 
     103            commands or shell scripts. This software is written in such a manner than system 
     104            administrators can plug their own scripts at the most strategic points of the  
     105            printing process, through specific directives that you put in <application>PyKota</application>'s 
     106            configuration files. 
     107          </para> 
     108        </listitem>   
     109        <listitem> 
     110          <para> 
     111            Several command line tools to manage print quotas and accounting. All of these 
     112            commands accept the <literal>--version</literal> and <literal>--help</literal> 
     113            command line switches, and all have a manual page. Many manual pages are available 
     114            in several native languages and contain usage examples. Some commands have many 
     115            options and switches, so please read their help carefully. 
     116            <itemizedlist> 
     117              <listitem> 
     118                <para> 
     119                  <filename>pkturnkey</filename> : to help you do the initial 
     120                  configuration and database initialization. This command almost transforms <application>PyKota</application> 
     121                  into a turn-key solution, hence the name. 
     122                </para> 
     123              </listitem>   
     124              <listitem> 
     125                <para> 
     126                  <filename>pkprinters</filename> : to manage printers and printers groups. 
     127                </para> 
     128              </listitem>   
     129              <listitem> 
     130                <para> 
     131                  <filename>edpykota</filename> : to manage users, users groups and quotas. 
     132                </para> 
     133              </listitem>   
     134              <listitem> 
     135                <para> 
     136                  <filename>pkbcodes</filename> : to manage billing codes. 
     137                </para> 
     138              </listitem>   
     139              <listitem> 
     140                <para> 
     141                  <filename>repykota</filename> : to do some basic print quota reporting. 
     142                </para> 
     143              </listitem>   
     144              <listitem> 
     145                <para> 
     146                   <filename>dumpykota</filename> : to dump the database's contents in a portable 
     147                   way. This command can be used to export <application>PyKota</application>'s 
     148                   datas to third party software, like print log analyzers or spreadsheets, and 
     149                   numerous output formats are supported. 
     150                </para> 
     151              </listitem>   
     152              <listitem> 
     153                <para> 
     154                   <filename>autopykota</filename> : to automate the creation of user accounts on 
     155                   first print. This command is not meant to be used from the command line, but 
     156                   instead from <filename>pykota.conf</filename>'s <literal>policy</literal> directive. 
     157                </para> 
     158              </listitem>   
     159              <listitem> 
     160                <para> 
     161                  <filename>pykosd</filename> : an X Window application to display their remaining credits or 
     162                  pages to end users. 
     163                </para> 
     164              </listitem>   
     165              <listitem> 
     166                <para> 
     167                  <filename>pykotme</filename> : to help end user obtain quotes before printing, this way 
     168                  they know in advance how much a print job will cost to them and can decide to route it to 
     169                  a less costly printer. 
     170                </para> 
     171              </listitem>   
     172              <listitem> 
     173                <para> 
     174                   <filename>pkbanner</filename> : to generate dynamic banner pages when printing. 
     175                   This command is 
     176                   not meant to be used from the command line, but 
     177                   instead from <filename>pykota.conf</filename>'s <literal>startingbanner</literal>  
     178                   and <literal>endingbanner</literal> directives. If you prefer you can use 
     179                   your own generator of dynamic banner pages or even static banner pages. 
     180                </para> 
     181              </listitem>   
     182              <listitem> 
     183                <para> 
     184                  <filename>warnpykota</filename> : to warn users over quota from time to time, for example 
     185                  from <filename>crontab</filename>. Users are warned while printing in any case, so 
     186                  this command is meant to be used as a periodic reminder. 
     187                </para> 
     188              </listitem>   
     189              <listitem> 
     190                <para> 
     191                  <filename>pkmail</filename> : to let users obtain their print quota situation by email. 
     192                  In the future other functionnalities will be added. 
     193                  This command is not meant to be used from the command line, but 
     194                  instead as a pipe from your mail server's <filename>/etc/aliases</filename> file. 
     195                </para> 
     196              </listitem>   
     197            </itemizedlist> 
     198          </para> 
     199        </listitem>   
     200        <listitem> 
     201          <para> 
     202            Several <acronym>CGI</acronym> scripts which constitute <application>PyKota</application>'s web interface. 
     203            All these scripts behave differently when they are protected with an username and password 
     204            compared to when they are not. See <filename>pykota/cgi-bin/README</filename> for 
     205            details. 
     206            <itemizedlist> 
     207              <listitem> 
     208                <para> 
     209                  <filename>printquota.cgi</filename> : to do basic print quota reports like repykota,  
     210                  and also to examine the printing history, which is not possible with repykota for now. 
     211                </para> 
     212              </listitem>   
     213              <listitem> 
     214                <para> 
     215                  <filename>dumpykota.cgi</filename> : identical to the <filename>dumpykota</filename> 
     216                  command line tool, but works over the web. 
     217                </para> 
     218              </listitem>   
     219              <listitem> 
     220                <para> 
     221                  <filename>pykotme.cgi</filename> : identical to the <filename>pykotme</filename> 
     222                  command line tool, but works over the web. 
     223                </para> 
     224              </listitem>   
     225            </itemizedlist> 
     226          </para> 
     227        </listitem>   
     228        <listitem> 
     229          <para> 
     230            Several helper scripts and contributed stuff to help manage particular configurations. 
     231            Please visit the subdirectories of the <filename>pykota/</filename> directory, and 
     232            you may find interesting things... 
     233          </para> 
     234        </listitem>   
     235      </itemizedlist> 
    18236    </para> 
    19237     
    20238  </sect1>   
    21    
    22239   
    23240</chapter>