root / pykota / trunk / docs / repykota.sgml @ 2551

Revision 2551, 7.2 kB (checked in by jerome, 19 years ago)

Replaced some 'filename' tags with 'command' tags.
Improved pkbcodes' documentation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
1<!-- $Id$ -->
4  <title id="repykota">Create print quota usage reports with repykota</title>
5  <para>Last modified on $Date$</para>
7  <para>
8    To account for print usage is good, however there must be a way to easily
9    query the <emphasis>Quota Storage Server</emphasis> and generate
10    reports describing current usage for every user on every printer.
11  </para>
13  <sect1>
14    <title>Command line based Print Quota reports</title>
16    <para>
17      PyKota features a quota report generator, named <command>repykota</command>,
18      with which you can print the current state of the quota database.
19    </para>
21    <para>
22      <command>repykota</command> behaves differently when it is launched by a
23      <application>PyKota</application> administrator, compared to when it is launched by a normal user.
24    </para> 
26    <para>
27      In the first case, the print quota report will contain current account balance,
28      soft and hard limits, number of pages printed since last reset, total number
29      of pages printed, total paid, for possibly all users or all groups, depending
30      on command line options.
31    </para>
33    <para>
34      In the second case, i.e. when <command>repykota</command> is launched by
35      a normal user, the user will only be allowed to see informations about himself or
36      the groups he his a member of.
37    </para>
39    <para>
40      Any user can limit the report to only one or more printers, by specifying the
41      <literal>-P</literal> or <literal>--printer</literal> command line option,
42      followed by one or more printer name or wildcard. If more than one printer name
43      or wildcard is used, they must be separated by commas.
44    </para>
46    <para>
47      Launching <command>repykota</command> with no arguments will generate
48      a complete print quota report, depending on what you are allowed to see.
49    </para>
51    <para>
52      Use the <literal>--help</literal> command line argument to learn what are
53      the different command line options available.
54    </para>
56    <sect2>
57      <title>Reference</title>
58      <para>
59        <cmdsynopsis>
60          <command>repykota</command>
61          <group choice="opt"><arg>-v</arg><arg>--version</arg></group>
62          <group choice="opt"><arg>-h</arg><arg>--help</arg></group>
63          <group choice="opt"><arg>-u</arg><arg>--users</arg></group>
64          <group choice="opt"><arg>-g</arg><arg>--groups</arg></group>
65          <group choice="opt">
66            <arg>-P <replaceable>printername</replaceable></arg>
67            <arg>--printer <replaceable>printername</replaceable></arg>
68          </group> 
69          <group choice="opt">
70            <arg><replaceable>name1</replaceable></arg>
71            <arg><replaceable>name2</replaceable></arg>
72            <arg><replaceable>...</replaceable></arg>
73            <arg><replaceable>nameN</replaceable></arg>
74          </group> 
75        </cmdsynopsis>
76      </para>
77    </sect2>
78  </sect1>
80  <sect1>
81    <title>Web based Print Quota reports</title>
83    <para>
84      <application>PyKota</application> also features a CGI script to remotely access
85      to print quota reports with a web browser, it is called <command>printquota.cgi</command>
86      and you can put it in your web server's <filename>cgi-bin</filename> directory if a web server is installed on
87      any machine on which <application>PyKota</application> is also installed and configured
88      correctly.
89    </para>
91    <para>
92      You may also want to copy the <acronym>CSS</acronym> stylesheets which are present in the
93      <filename>stylesheets/</filename> directory to your web server's <literal>DocumentRoot</literal>
94      (e.g. <filename>/var/lib/www</filename>) so that the CGI script can find them to present
95      a nicer web interface.
96    </para>
98    <para>
99      You can find <command>printquota.cgi</command> in the <filename>pykota/cgi-bin</filename>
100      directory. Here's how to install it, provided that your web server's <filename>cgi-bin</filename>
101      directory is <filename>/usr/lib/cgi-bin</filename> :
103port50-2:/home/jerome/pykota$ cp cgi-bin/printquota.cgi /usr/lib/cgi-bin
104port50-2:/home/jerome/pykota$ chmod 755 /usr/lib/cgi-bin/printquota.cgi
107      <note>
108        <title>Note</title>
109        <para>
110          Please ensure that the user your web server is run as, for example <literal>www-data</literal> under
111          Debian, is allowed to read <filename>~pykota/pykota.conf</filename> but for security reasons you
112          must ensure that this user <emphasis>is not</emphasis> allowed to read <filename>~pykota/pykotadmin.conf</filename>
113        </para>
114      </note> 
115    </para>
117    <para>
118      If you install the CGI script as described above, any user will be allowed to view the complete print
119      quota report, for all users, groups and printers. This is then a different behavior compared to when
120      a normal user wants a print quota report from the command line through <command>repykota</command>.
121      If you find this disturbing, then the best is to ask for user authentication whenever the <command>printquota.cgi</command>
122      CGI script is accessed. This CGI script will then automatically behave as expected, showing in the print quota
123      report only what the authenticated user is allowed to see, just like when he launches <command>repykota</command>
124      from the command line. As a special case, if the user authenticates using the <literal>root</literal> username,
125      then there's no restriction on what may appear on the print quota report.
126    </para>
128    <para>
129      To automatically ask for an authentication dialog whenever the CGI script is accessed, you have to configure
130      your web server to do so. If your webserver is <ulink url=""><application>Apache</application></ulink>, then it's relatively easy. First you have to put
131      <command>printquota.cgi</command> in its own subdirectory below your web server's <filename>cgi-bin</filename>
132      directory, for example in <filename>cgi-bin/PyKota/</filename>. Then use the <command>htpasswd</command>
133      command line tool to create a file which contains usernames and passwords for all your users allowed to see
134      the print quota report from a web browser, and put this file outside of the directories served by <application>Apache</application>
135      so that nobody could retrieve it. Finally create a file named <filename>.htaccess</filename> in
136      <filename>cgi-bin/PyKota/</filename> with appropriate content in it. This file should tell <application>Apache</application> to automatically ask
137      for an authentication whenever something from this directory is accessed, and to use the password file previously
138      created to match usernames and passwords.
139      You may also have to tweak <application>Apache</application>'s default configuration to allow the
140      authentication mechanism.
141    </para>
143    <para>
144      The detailed procedure to do all this is out of the scope of the present document, please refer to
145      <application>Apache</application>'s <ulink url="">documentation</ulink>
146      for all the gory details.
147    </para>
148  </sect1>
Note: See TracBrowser for help on using the browser.