root / pykota / trunk / docs / pkmail.sgml @ 2949

Revision 2551, 3.6 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
Line 
1<!-- $Id$ -->
2
3<chapter>
4  <title>Control PyKota by email with pkmail</title>
5  <para>Last modified on $Date$</para>
6 
7  <para>
8    <command>pkmail</command> is an email gateway which allows you to control
9    <application>PyKota</application> using email messages.
10  </para> 
11 
12  <para>
13    For now, this command can't do more than print quota reports, but more
14    powerful functionnalities are planned for a future release.
15  </para>
16 
17  <sect1>
18    <title>Installation</title>
19    <para>
20      Contrary to other commands included with <application>PyKota</application>,
21      <command>pkmail</command> is not meant to be used from the command line,
22      but instead launched from your mail server when particular messages are
23      received.
24    </para>
25   
26    <para>
27      In order to achieve this, the easiest way is to define a special
28      email alias. Every message received on this address will cause your webserver to automatically
29      launch <command>pkmail</command>, passing the message's content on <command>pkmail</command>'s standard input.
30    </para>
31   
32    <para>
33      The name of the email alias is completely free, let's call it <literal>pykotacmd</literal> for example.
34      Now edit <filename>/etc/aliases</filename> with your favorite text editor and enter the following :
35<screen>      
36pykotacmd :     "|/usr/bin/pkmail"
37</screen>
38    </para>
39   
40    <para>
41      Finally, tell your mail server that new aliases are available. To do so, at the command prompt just
42      type :
43<screen>      
44$ newaliases
45</screen>     
46    </para>
47   
48    <para>
49      But to be useful, <command>pkmail</command> must be able to read <application>PyKota</application>'s
50      <filename>pykotadmin.conf</filename> configuration file. A simple way to do so is to put the system
51      user your mail server runs aliases commands as into the <literal>pykota</literal> system group, then
52      restart your mail server software.
53      <tip>
54        <title>Tip</title>
55        <para>
56          Depending on the software you use as the mail server, additional work may be needed. For example
57          <application>Exim</application> doesn't by default initialize all the groups when launching a
58          command from the <filename>/etc/aliases</filename> database. Please refer to your mail server's
59          documentation for details.
60        </para>
61      </tip> 
62    </para>
63  </sect1> 
64 
65  <sect1>
66    <title>Usage</title>
67    <para>
68      Now that <command>pkmail</command> is installed, we can use it by sending email messages to the address
69      <literal>pykotacmd@yourmailserver.example.com</literal>. This command will then process your request,
70      and send the result back to you by email.
71    </para>
72   
73    <para>
74      For now, <command>pkmail</command> only accepts commands in the <literal>Subject:</literal> field
75      of the email message you send to it.
76    </para>
77   
78    <para>
79      <command>pkmail</command> is still in a pretty experimental state, and only recognizes a single command :
80      <command>report</command>
81    </para>
82   
83    <para>
84      The <command>report</command> takes an username as its only optional argument. So for example to
85      receive a print quota report for user <literal>jerome</literal>, you'll just have to send
86      an email message with <literal>report jerome</literal> in the subject.
87    </para>
88  </sect1> 
89 
90  <sect1>
91    <title>Reference</title>
92    <para>
93      <cmdsynopsis>
94        <command>pkmail</command>
95        <group choice="opt"><arg>-v</arg><arg>--version</arg></group>
96        <group choice="opt"><arg>-h</arg><arg>--help</arg></group>
97      </cmdsynopsis>
98    </para>
99  </sect1>
100</chapter>
101
Note: See TracBrowser for help on using the browser.