source: src/router/proftpd/doc/contrib/ftpmail.html @ 17876

Last change on this file since 17876 was 17876, checked in by BrainSlayer, 19 months ago

update proftp
File size: 7.7 KB
Line 
1<!-- $Id: ftpmail.html,v 1.3 2010/08/10 21:22:24 castaglia Exp $ -->
2<!-- $Source: /cvsroot/proftp/proftpd/doc/contrib/ftpmail.html,v $ -->
3
4<html>
5<head>
6<title>ftpmail: Automated Email Notifications of Uploads</title>
7</head>
8
9<body bgcolor=white>
10
11<hr>
12<center>
13<h2><b><code>ftpmail</code>: Automated Email Notifications of Uploads</b></h2>
14</center>
15<hr><br>
16
17<p>
18The <code>ftpmail</code> program is a Perl script designed to read
19ProFTPD's <code>TransferLog</code> log entries, watching for uploads, and
20to send an automatic email notification when uploads occur.  To use
21<code>ftpmail</code>, you configure your <code>proftpd</code> daemon to
22write its <code>TransferLog</code> to a <a href="http://www.proftpd.org/docs/howto/Logging.html#FIFOs">FIFO</a>; the <code>ftpmail</code> program is a FIFO
23reading program which then processes those log messages.
24
25<p>
26The most current version of <code>ftpmail</code> is distributed with the
27ProFTPD source code.
28
29<h2>Author</h2>
30<p>
31Please contact TJ Saunders &lt;tj <i>at</i> castaglia.org&gt; with any
32questions, concerns, or suggestions regarding this program.
33
34<p>
35<hr><br>
36<h2><a name="Usage">Usage</a></h2>
37First, you have the following Perl modules installed:
38<ul>
39  <li>Mail::Sendmail
40  <li>Time::HiRes
41</ul>
42You can easily determine if your Perl has these modules present, using:
43<pre>
44  # perl -MMail::Sendmail -e0
45  # perl -MTime::HiRes -e0
46</pre>
47If you see an error similar to:
48<pre>
49  Can't location Mail/Sendmail.pm in @INC (@INC contains: <i>...</i>)
50</pre>
51it means that you do not have that Perl module installed.  Go to <a href="http://search.cpan.org">search.cpan.org</a> to download the latest versions of
52these modules, and install them as per their instructions.
53
54<p>
55Next, you need to create the FIFO that <code>ftpmail</code> will read from.
56See the <code>mkfifo(1)</code> man page for instructions on how to create
57a FIFO.  Note that you <b>must</b> use <code>mkfifo</code> to create a FIFO;
58using an ordinary file that happens to have a ".fifo" extension will not work
59for this.
60
61<p>
62After that, you need to start <code>ftpmail</code> running, <i>before</i>
63starting <code>proftpd</code>.  For example, you might do:
64<pre>
65   # ./ftpmail \
66       --fifo=/var/proftpd/log/transfer.fifo \
67       --from='tj@castaglia.org' \
68       --recipient='tj@castaglia.org' \
69       --smtp-server=mail.domain.com \
70       --attach-file \
71       --log=/var/proftpd/log/transfer.log &
72</pre>
73The key is to make <code>ftpmail</code> run in the background, so that it is
74constantly running.  If the <code>ftpmail</code> process dies, then
75<code>proftpd</code> will not be able to write the <code>TransferLog</code>.
76
77<p>
78The next step is to configure your <code>proftpd</code> daemon to write to
79the FIFO you created.  Thus in your <code>proftpd.conf</code>, you would
80use the same path as given to <code>ftpmail</code>'s <code>--fifo</code>
81option, <i>e.g.</i>:
82<pre>
83  TransferLog /var/proftpd/log/transfer.fifo
84</pre>
85 
86<p>
87Then start <code>proftpd</code>, log in, upload a file, and see what happens.
88One user modified their <code>init</code> for <code>proftpd</code> such
89that the <code>ftpmail</code> program was automatically started before
90the <code>proftpd</code> daemon was started.
91
92<p>
93<b>Options</b><br>
94The following shows the full list of <code>ftpmail<code> options; this
95can also be obtained by running:
96<pre>
97  # ftpmail --help
98
99  usage: ftpmail [--help] [--fifo $path] [--from $addr] [--log $path]
100    [--recipient $addr] [--subject $string] [--smtp-server $addr]
101    [--attach-file] [--ignore-users $regex | --watch-users $regex]
102
103  The purpose of this script is to monitor the TransferLog written by proftpd
104  for uploaded files.  Whenever a file is uploaded by a user, an email
105  will be sent to the specified recipients.  In the email there will be
106  the timestamp, the name of the user who uploaded the file, the path to
107  the uploaded file, the size of the uploaded file, and the time it took
108  to upload.
109
110  Command-line options:
111
112    --attach-file         If used, this will cause a copy of the uploaded file
113                          to be included, as an attachment, in the generated
114                          email.
115
116    --auth $path          Configures the path to a file containing SMTP
117                          authentication information.
118
119                          The configured file should look like this:
120
121                              user = $user
122                              password = $password
123
124    --fifo $path          Indicates the path to the FIFO to which proftpd is
125                          writing its TransferLog.  That is, this is the path
126                          that you used for the TransferLog directive in your
127                          proftpd.conf.  This parameter is REQUIRED.
128
129    --from $addr          Specifies the email address to use in the From header.
130                          This parameter is REQUIRED.
131
132    --help                Displays this message.
133
134    --ignore-users $regex Specifies a Perl regular expression.  If the
135                          uploading user name matches this regular expression,
136                          then an email notification is NOT sent; otherwise,
137                          an email is sent.
138
139    --log $path           Since this script reads the TransferLog using FIFOs,
140                          the actual TransferLog file is not written by default.
141                          Use this option to write the normal TransferLog file,
142                          in addition to watching for uploads.
143
144    --recipient $addr     Specifies an email address to which to send an email
145                          notification of the upload.  This option can be
146                          used multiple times to specify multiple recipients.
147                          AT LEAST ONE recipient is REQUIRED.
148
149    --smtp-server $addr   Specifies the SMTP server to which to send the email.
150                          This parameter is REQUIRED.
151
152    --subject $string     Specify a custom Subject header for the email sent.
153                          The default Subject is:
154
155                            User '$user' uploaded file '$file' via FTP
156
157    --watch-users $regex  Specifies a Perl regular expression.  If the
158                          uploading user name matches this regular expression,
159                          then an email notification is sent; otherwise,
160                          no email is sent.
161</pre>
162
163<p><a name="FAQ"></a>
164<b>FAQ</b><br>
165
166<p>
167<font color=red>Question</font>: I would like to use <code>ftpmail</code>
168to send emails, but only for files uploaded to specific domains.  How do
169I do this?<br>
170<font color=blue>Answer</font>: To do this, you will need to configure
171different <code>TransferLog</code> files in your different
172<code>&lt;VirtualHost&gt;</code> sections in your <code>proftpd.conf</code>.
173
174<p>
175The TransferLog file format does not include a field indicating the IP
176address (or DNS name) of the server on which the file transfer is occurring.
177This means that <code>ftpmail</code> does not know which server is handling
178the transfer.  So, in order to have <code>ftpmail</code> send emails only
179for certain domains/servers, you will have to do something like:
180<pre>
181 &lt;VirtualHost a.b.c.d&gt;
182    ...
183    TransferLog /path/to/vhost1.xferlog
184    ..
185  &lt;/VirtualHost&gt;
186
187  &lt;VirtualHost e.f.g.h&gt;
188    ...
189    TransferLog /path/to/vhost2.xferlog
190    ...
191  &lt;/VirtualHost&gt;
192</pre>
193Then start instances of <code>ftpmail</code> running, but only for the
194<code>TransferLog</code> files of the domains/virtual servers to be monitored.
195
196<p>
197<hr><br>
198
199Author: <i>$Author: castaglia $</i><br>
200Last Updated: <i>$Date: 2010/08/10 21:22:24 $</i><br>
201
202<br><hr>
203
204<font size=2><b><i>
205&copy; Copyright 2008-2010 TJ Saunders<br>
206 All Rights Reserved<br>
207</i></b></font>
208
209<hr><br>
210
211</body>
212</html>
Note: See TracBrowser for help on using the repository browser.