root / pykota / trunk / docs / introduction.sgml @ 2909

Revision 2909, 13.1 kB (checked in by jerome, 18 years ago)

Updated URLs.

  • Property svn:keywords set to Author Date Id Revision
Line 
1<!-- $Id$ -->
2
3<chapter>
4  <title id="introduction">Introduction to PyKota</title>
5 
6  <para>Last modified on $Date$</para>
7 
8  <para>
9    This chapter will briefly introduce you to PyKota, and will familiarize
10    you with this software and its components.
11  </para>
12 
13 
14  <sect1>
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      Beginning on October 10th 2005, this document won't be <application>PyKota</application>'s reference documentation anymore.
52      <application>PyKota</application>'s reference documentation is now at :
53      <ulink url="http://www.pykota.com/wiki">http://www.pykota.com/wiki</ulink>
54    </para>
55   
56    <para>
57      <application>PyKota</application> is made of the following components :
58      <itemizedlist>
59        <listitem>
60          <para>
61            Configuration files, which must be placed into the system user
62            <literal>pykota</literal>'s home directory as defined in <filename>/etc/passwd</filename>
63            <footnote>
64              <para>If your <filename>/etc/passwd</filename> contains something like
65                <literal>pykota:x:1001:1001:PyKota Admin,,,:/etc/pykota:/bin/sh</literal>
66                then the home directory is <filename>/etc/pykota</filename>
67              </para>
68            </footnote> :
69            <itemizedlist>
70              <listitem>
71                <para>
72                  <filename>pykotadmin.conf</filename> : this file contains sensitive database settings
73                  allowing the <application>PyKota</application> software to modify the
74                  print quota database. This file should be protected and should only be
75                  made readable by the administrators of <application>PyKota</application>
76                  and the system user the printing subsystem is running as.
77                  The possibility for a particular user to read this file determines if
78                  this user is a <application>PyKota</application> Administrator or not,
79                  so please give particular attention to this file's permissions.
80                </para>
81              </listitem> 
82              <listitem>
83                <para>
84                  <filename>pykota.conf</filename> : this is the main configuration file for
85                  <application>PyKota</application>. It contains database settings which
86                  allow the <application>PyKota</application> software to access to the print
87                  quota database in readonly mode, as well as global and print queue specific
88                  configuration directives. With a properly configured <application>PyKota</application>,
89                  letting normal users read this file is safe
90                  excepted where you want to forbid users to read other users' print quota
91                  information. However if you're not confident about your database settings,
92                  it's better to not let normal users read this file. This way they can't even
93                  use any of the <application>PyKota</application> command line tools.
94                </para>
95              </listitem> 
96            </itemizedlist>
97          </para>
98        </listitem> 
99        <listitem>
100          <para>
101            Either a <application>PostgreSQL</application>, <application>MySQL</application> or <application>SQLite</application> database, or an <acronym>LDAP</acronym>
102            <footnote><para>Lightweight Directory Access Protocol</para></footnote>
103            <acronym>DIT</acronym>
104            <footnote><para>Directory Information Tree</para></footnote> :
105            <application>PyKota</application> can store its datas into any of these. Support
106            for other database backends might be added in a future release.
107          </para>
108        </listitem> 
109        <listitem>
110          <para>
111            A generic <acronym>CUPS</acronym> backend wrapper, named <command>cupspykota</command> :
112            this software captures all print jobs passing through the print queues it manages,
113            and does the accounting and quota checking. It can reject print jobs in a number
114            of circumstances like the user being over quota, and interact with the end user through the use of external
115            commands or shell scripts. This software is written in such a manner than system
116            administrators can plug their own scripts at the most strategic points of the
117            printing process, through specific directives that you put in <application>PyKota</application>'s
118            configuration files.
119          </para>
120        </listitem> 
121        <listitem>
122          <para>
123            Several command line tools to manage print quotas and accounting. All of these
124            commands accept the <literal>--version</literal> and <literal>--help</literal>
125            command line switches, and all have a manual page. Many manual pages are available
126            in several native languages and contain usage examples. Some commands have many
127            options and switches, so please read their help carefully.
128            <itemizedlist>
129              <listitem>
130                <para>
131                  <command>pkturnkey</command> : to help you do the initial
132                  configuration and database initialization. This command almost transforms <application>PyKota</application>
133                  into a turn-key solution, hence the name.
134                </para>
135              </listitem> 
136              <listitem>
137                <para>
138                  <command>pkprinters</command> : to manage printers and printers groups.
139                </para>
140              </listitem> 
141              <listitem>
142                <para>
143                  <command>pkusers</command> : to manage users and users groups.
144                </para>
145              </listitem> 
146              <listitem>
147                <para>
148                  <command>edpykota</command> : to manage users' and users groups' print quota entries.
149                </para>
150              </listitem> 
151              <listitem>
152                <para>
153                  <command>pkbcodes</command> : to manage billing codes.
154                </para>
155              </listitem> 
156              <listitem>
157                <para>
158                  <command>repykota</command> : to do some basic print quota reporting.
159                </para>
160              </listitem> 
161              <listitem>
162                <para>
163                   <command>dumpykota</command> : to dump the database's contents in a portable
164                   way. This command can be used to export <application>PyKota</application>'s
165                   datas to third party software, like print log analyzers or spreadsheets, and
166                   numerous output formats are supported, like <acronym>csv</acronym> and <acronym>XML</acronym>
167                </para>
168              </listitem> 
169              <listitem>
170                <para>
171                   <command>autopykota</command> : to automate the creation of user print accounts on
172                   first print. This command is not meant to be used from the command line, but
173                   instead from <filename>pykota.conf</filename>'s <literal>policy</literal> directive.
174                </para>
175              </listitem> 
176              <listitem>
177                <para>
178                  <command>pykosd</command> : to display their remaining credits or
179                  pages to end users. This is an <acronym>OSD</acronym> <footnote><para>On Screen Display</para></footnote>
180                  application which works under the X Window system.
181                </para>
182              </listitem> 
183              <listitem>
184                <para>
185                  <command>pykotme</command> : to give detailed quotes to end users before they print, this way
186                  they know in advance how much a print job will cost to them and can decide to route it to
187                  a less costly printer.
188                </para>
189              </listitem> 
190              <listitem>
191                <para>
192                   <command>pkbanner</command> : to generate dynamic banner pages when printing.
193                   This command is
194                   not meant to be used from the command line, but
195                   instead from <filename>pykota.conf</filename>'s <literal>startingbanner</literal>
196                   and <literal>endingbanner</literal> directives. If you prefer you can use
197                   your own generator of dynamic banner pages or even static banner pages.
198                </para>
199              </listitem> 
200              <listitem>
201                <para>
202                  <command>warnpykota</command> : to warn users over quota from time to time, for example
203                  from <filename>crontab</filename>. Users are warned while printing in any case, so
204                  this command is meant to be used as a periodic reminder.
205                </para>
206              </listitem> 
207              <listitem>
208                <para>
209                  <command>pkmail</command> : to let users obtain their print quota situation by email.
210                  In the future other functionnalities will be added.
211                  This command is not meant to be used from the command line, but
212                  instead as a pipe from your mail server's <filename>/etc/aliases</filename> file.
213                </para>
214              </listitem> 
215              <listitem>
216                <para>
217                  <command>pknotify</command> : a client for the <application>PyKotIcon</application> cross-platform generic network dialog box manager. This
218                  tools allow you to interact with end users at printing time.
219                </para>
220              </listitem> 
221              <listitem>
222                <para>
223                  <command>pkinvoice</command> : an invoice generator which can create personalized PDF invoices
224                  for your users from their printing history.
225                </para>
226              </listitem> 
227            </itemizedlist>
228          </para>
229        </listitem> 
230        <listitem>
231          <para>
232            Several <acronym>CGI</acronym> scripts which constitute <application>PyKota</application>'s web interface.
233            All these scripts behave differently when they are protected with an username and password
234            compared to when they are not. See <filename>pykota/cgi-bin/README</filename> for
235            details.
236            <itemizedlist>
237              <listitem>
238                <para>
239                  <command>printquota.cgi</command> : to do basic print quota reports like repykota,
240                  and also to examine the printing history, which is not possible with repykota for now.
241                </para>
242              </listitem> 
243              <listitem>
244                <para>
245                  <command>dumpykota.cgi</command> : identical to the <command>dumpykota</command>
246                  command line tool, but works from within a web browser.
247                </para>
248              </listitem> 
249              <listitem>
250                <para>
251                  <command>pykotme.cgi</command> : identical to the <command>pykotme</command>
252                  command line tool, but works from within a web browser.
253                </para>
254              </listitem> 
255            </itemizedlist>
256          </para>
257        </listitem> 
258        <listitem>
259          <para>
260            Several helper scripts and contributed stuff to handle very specific configurations.
261            Please visit the subdirectories of the <filename>pykota/</filename> source directory, and
262            you may find interesting things...
263          </para>
264        </listitem> 
265      </itemizedlist>
266    </para>
267   
268  </sect1> 
269 
270</chapter>
271
Note: See TracBrowser for help on using the browser.