One Hat Cyber Team

Edit File: mod_exec.html

<!DOCTYPE html>
<html>
<head>
<title>ProFTPD module mod_exec</title>
</head>

<hr> 
<center>
<h2>ProFTPD module <code>mod_exec</code></h2>
</center>
<hr>

This module is contained in the <code>mod_exec.c</code> file for
ProFTPD 1.3.x, found
<a href="http://www.castaglia.org/proftpd/">here</a>, and is not compiled by
default. Installation instructions are discussed
<a href="#Installation">here</a>.

The <code>mod_exec</code> module can be used to execute external programs
or scripts at various points in the process of handling FTP commands. By
conscious design, the core ProFTPD engine does not and will not execute
external programs. This is a security decision, as it was decided not to allow
ProFTPD to serve as a means of compromising a system or disclosing information
via bugs in external programs or scripts. Use of this module allows for such
external programs to be executed, and also opens up the server to the
mentioned possibilities of compromise or disclosure via those programs.

<center>
 YOU HAVE BEEN WARNED 
 USE AT YOUR OWN RISK 
</center>

Please read the <a href="#Usage">usage</a> section to know the other caveats
with this module.

The most current version of <code>mod_exec</code> is distributed with the
ProFTPD source code.

<h2>Author</h2>

Please contact TJ Saunders &lt;tj at castaglia.org&gt; with any
questions, concerns, or suggestions regarding this module.

<h2>Directives</h2>
<ul>
 <li><a href="#ExecBeforeCommand">ExecBeforeCommand</a>
 <li><a href="#ExecEnable">ExecEnable</a>
 <li><a href="#ExecEngine">ExecEngine</a>
 <li><a href="#ExecEnviron">ExecEnviron</a>
 <li><a href="#ExecLog">ExecLog</a>
 <li><a href="#ExecOnCommand">ExecOnCommand</a>
 <li><a href="#ExecOnConnect">ExecOnConnect</a>
 <li><a href="#ExecOnError">ExecOnError</a>
 <li><a href="#ExecOnEvent">ExecOnEvent</a>
 <li><a href="#ExecOnExit">ExecOnExit</a>
 <li><a href="#ExecOnRestart">ExecOnRestart</a>
 <li><a href="#ExecOptions">ExecOptions</a>
 <li><a href="#ExecTimeout">ExecTimeout</a>
</ul>

<hr>
<h3><a name="ExecBeforeCommand">ExecBeforeCommand</a></h3>
Syntax: ExecBeforeCommand cmds path [arg1 arg2 ...] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.8 and later

The <code>ExecBeforeCommand</code> directive is used to execute the program or
script at path before the handling of any FTP command listed
in cmds, where cmds is a comma-delimited list of FTP commands.
The command groups of the <code>&lt;Limit&gt;</code> directive, such as
READ, WRITE, and ALL, may also be used. The program will be executed with
the privileges of the logged-in user.

Any number of arbitrary arguments may be configured to pass to the script.
In addition, the variables supported by the <code>ExecEnviron</code> directive
may also be used in the script argument list.

Important: use of <code>DefaultRoot</code> will cause complications
(to be elaborated upon soon).

Example:
<pre>
 ExecBeforeCommand RETR /path/to/ftp-prep --file %f
</pre>

See Also:
 <a href="#ExecEnviron">ExecEnviron</a>,
 <a href="#ExecOnCommand">ExecOnCommand</a>,
 <a href="#ExecOnConnect">ExecOnConnect</a>,
 <a href="#ExecOnError">ExecOnError</a>,
 <a href="#ExecOnExit">ExecOnExit</a>,
 <a href="#ExecOnRestart">ExecOnRestart</a>,
 <a href="http://www.proftpd.org/docs/modules/mod_core.html#Limit">&lt;Limit&gt;</a>

<hr>
<h3><a name="ExecEnable">ExecEnable</a></h3>
Syntax: ExecEnable on|off 
Default: None 
Context: <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code>, <code>.ftpaccess</code> 
Module: mod_exec 
Compatibility: 1.3.6rc1 and later

The <code>ExecEnable</code> directive can be used to disable the execution
of commands by <code>mod_exec</code> for particular directories or anonymous
logins.

<hr>
<h3><a name="ExecEngine">ExecEngine</a></h3>
Syntax: ExecEngine on|off 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.5rc2 and later

The <code>ExecEngine</code> directive enables or disables the module's
runtime exec engine. If it is set to off this module will not
manipulate environment variables or execute external scripts. Use this
directive to disable the module instead of commenting out all
<code>mod_exec</code> directives.

<hr>
<h3><a name="ExecEnviron">ExecEnviron</a></h3>
Syntax: ExecEnviron key value 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.5rc2 and later

The <code>ExecEnviron</code> directive is used to set the environment variables
in the environment created for the script to be executed. The current
environment is not passed directly to the script; this is to prevent unwanted
information leakage. The given key parameter will be uppercased,
to follow the convention for environment variable keys.

The value parameter may be any arbitrary string which may contain any
of the normal <a href="../modules/mod_log.html#LogFormat"><code>LogFormat</code></a> variables.

The value parameter may be also be &quot;-&quot;, which indicates that
the current value of the environment variable of name key should be
used (e.g. PATH). If there is no environment of name key when
&quot;-&quot; is used, it will be created with a blank string as the value.

<hr>
<h3><a name="ExecLog">ExecLog</a></h3>
Syntax: ExecLog file|&quot;none&quot; 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.5rc2 and later

The <code>ExecLog</code> directive is used to specify a log file for
<code>mod_exec</code> reporting and debugging, and can be done a per-server
basis. The file parameter must be the full path to the file to use for
logging. Note that this path must not be to a world-writeable
directory and, unless <code>AllowLogSymlinks</code> is explicitly set to
on (generally a bad idea), the path must not be a symbolic
link.

If file is &quot;none&quot;, no logging will be done at all; this
setting can be used to override an <code>ExecLog</code> setting inherited from
a <code>&lt;Global&gt;</code> context.

<hr>
<h3><a name="ExecOnCommand">ExecOnCommand</a></h3>
Syntax: ExecOnCommand cmds path [arg1 arg2 ...] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.5rc2 and later

The <code>ExecOnCommand</code> directive is used to execute the program or
script at path after the successful completion of any FTP command
listed in cmds, where cmds is a comma-delimited list of FTP
commands. The command groups of the <code>&lt;Limit&gt;</code> directive,
such as READ, WRITE, and ALL, may also be used. The program will be executed
with the privileges of the logged-in user.

Important: use of <code>DefaultRoot</code> will cause complications
(to be elaborated upon soon).

Example:
<pre>
 ExecOnCommand APPE,STOR /path/to/ftp-email-script --user %u --file %f
</pre>

See Also:
 <a href="#ExecBeforeCommand">ExecBeforeCommand</a>,
 <a href="#ExecEnviron">ExecEnviron</a>,
 <a href="#ExecOnConnect">ExecOnConnect</a>,
 <a href="#ExecOnError">ExecOnError</a>,
 <a href="#ExecOnExit">ExecOnExit</a>,
 <A href="#ExecOnRestart">ExecOnRestart</a>,
 <a href="http://www.proftpd.org/docs/modules/mod_core.html#Limit">&lt;Limit&gt;</a>

<hr>
<h3><a name="ExecOnConnect">ExecOnConnect</a></h3>
Syntax: ExecOnConnect path [arg1 arg2 ...] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.5rc2 and later

The <code>ExecOnConnect</code> directive is used to execute the program or
script at path whenever a client connects to the server. The program
will be executed with the privileges of the contacted server, which are
set via the <code>User</code>/<code>Group</code> directives.

Example:
<pre>
 ExecOnConnect /path/to/ftp-logger --ip %a --dns %h
</pre>

See Also:
 <a href="#ExecBeforeCommand">ExecBeforeCommand</a>,
 <a href="#ExecEnviron">ExecEnviron</a>,
 <a href="#ExecOnCommand">ExecOnCommand</a>,
 <a href="#ExecOnError">ExecOnError</a>,
 <a href="#ExecOnExit">ExecOnExit</a>,
 <a href="#ExecOnRestart">ExecOnRestart</a>

<hr>
<h3><a name="ExecOnError">ExecOnError</a></h3>
Syntax: ExecOnError cmds path [arg1 arg2 ...] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.5rc2 and later

The <code>ExecOnError</code> directive is used to execute the program or
script at path if an error occurs while processing any FTP command listed
in cmds, where cmds is a comma-delimited list of FTP commands.
The command groups of the <code>&lt;Limit&gt;</code> directive, such as
READ, WRITE, and ALL, may also be used. The program will be executed with
the privileges of the logged-in user.

Important: use of <code>DefaultRoot</code> will cause complications
(to be elaborated upon soon).

Example:
<pre>
 ExecOnError APPE,STOR /path/to/ftp-cleanup-script --user %u --file %f
</pre>

See Also:
 <a href="#ExecBeforeCommand">ExecBeforeCommand</a>,
 <a href="#ExecEnviron">ExecEnviron</a>,
 <a href="#ExecOnCommand">ExecOnCommand</a>,
 <a href="#ExecOnConnect">ExecOnConnect</a>,
 <a href="#ExecOnExit">ExecOnExit</a>,
 <a href="#ExecOnRestart">ExecOnRestart</a>,
 <a href="http://www.proftpd.org/docs/modules/mod_core.html#Limit">&lt;Limit&gt;</a>

<hr>
<h3><a name="ExecOnEvent">ExecOnEvent</a></h3>
Syntax: ExecOnEvent event[*|~] path [arg1 arg2 ...] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.10rc1 and later

The <code>ExecOnEvent</code> directive is used to execute the program or
script at path when the given event occurs. The program will
be executed with the privileges of the server (set via the <code>User</code>
and <code>Group</code> directives in the <code>proftpd.conf</code>file),
unless the event name is followed either by a &quot;*&quot; or
a &quot;~&quot; character.

If the event name is followed by a &quot;*&quot;, the program will be
executed with root privileges. Note: this feature should be used
very carefully. It allows scripts to modify things like firewall
rules, but should be used only for such sensitive tasks.

If, on the other hand, the eevent name is followed by a &quot;~&quot;,
the program will be executed with the privileges of the logged-in user.
Note: support for this feature first appeared in
<code>proftpd-1.3.5rc4</code>.

Presently only two specific events are supported: <code>MaxConnectionRate</code>
and <code>MaxInstances</code>. These events happen when ever the limit
configured by these configuration directives is reached.

This directive may be used several times to configure multiple programs
to be invoked when event occurs.

Important: use of <code>DefaultRoot</code> will cause complications
(to be elaborated upon soon).

Example:
<pre>
 ExecOnEvent MaxConnectionRate* /path/to/ftp-firewall-script --ip %a
</pre>

<hr>
<h3><a name="ExecOnExit">ExecOnExit</a></h3>
Syntax: ExecOnExit path [arg1 arg2 ...] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.8 and later

The <code>ExecOnExit</code> directive is used to execute the program or
script at path whenever a client disconnects to the server. The program
will be executed with the privileges of the contacted server, which are
set via the <code>User</code>/<code>Group</code> directives.

Example:
<pre>
 ExecOnExit /path/to/ftp-logger --ip %a --dns %h
</pre>

See Also:
 <a href="#ExecBeforeCommand">ExecBeforeCommand</a>,
 <a href="#ExecEnviron">ExecEnviron</a>,
 <a href="#ExecOnCommand">ExecOnCommand</a>,
 <a href="#ExecOnConnect">ExecOnConnect</a>,
 <a href="#ExecOnError">ExecOnError</a>,
 <a href="#ExecOnRestart">ExecOnRestart</a>

<hr>
<h3><a name="ExecOnRestart">ExecOnRestart</a></h3>
Syntax: ExecOnRestart path [arg1 arg2 ...] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.5rc2 and later

The <code>ExecOnRestart</code> directive is used to execute the program or
script at path whenever the server receives a <code>SIGHUP</code>
signal. The program will be executed with the privileges of the contacted
server, which are set via the <code>User</code>/<code>Group</code> directives.

Example:
<pre>
 ExecOnRestart /path/to/ftp-counter-reset
</pre>

See Also:
 <a href="#ExecBeforeCommand">ExecBeforeCommand</a>,
 <a href="#ExecEnviron">ExecEnviron</a>,
 <a href="#ExecOnCommand">ExecOnCommand</a>,
 <a href="#ExecOnConnect">ExecOnConnect</a>,
 <a href="#ExecOnError">ExecOnError</a>,
 <a href="#ExecOnExit">ExecOnExit</a>

<hr>
<h3><a name="ExecOptions">ExecOptions</a></h3>
Syntax: ExecOptions opt1 ... 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.9rc2 and later

The <code>ExecOptions</code> directive is used to configure various optional
behavior of <code>mod_exec</code>.

Example:
<pre>
 ExecOptions logStderr sendStdout
</pre>

The currently implemented options are:
<ul>
 <li><code>logStderr</code> 
 When executing commands, <code>mod_exec</code> usually ignore any
 <code>stderr</code> output of the command. If this option is enabled,
 <code>mod_exec</code> will monitor for and log any <code>stderr</code>
 from the executed command to the <code>ExecLog</code>.

<li><code>logStdout</code> 
 When executing commands, <code>mod_exec</code> usually ignore any
 <code>stdout</code> output of the command. If this option is enabled,
 <code>mod_exec</code> will monitor for and log any <code>stdout</code>
 from the executed command to the <code>ExecLog</code>.

<li><code>sendStdout</code> 
 If this option is enabled, <code>mod_exec</code> will attempt to
 send any <code>stdout</code> output from the executed command to the
 connected client. Note that this only works for commands that are
 executed via <code>ExecOnCommand</code> or <code>ExecOnConnect</code>.
 
 Note this this option should not be used for SSH2/SFTP/SCP
 sessions, as it will only cause connection problems for SSH2/SFTP/SCP
 clients.

<li><code>useStdin</code> 
 If this option is enabled, <code>mod_exec</code> will not
 send arguments to the command being executed using the command line;
 instead, those arguments will written to the <code>stdin</code> stream.
 Each command-line argument will be written as a newline-terminated
 string to <code>stdin</code>; the end of arguments is indicated by
 writing the period ('.') character on a line by itself (again, terminated
 with a newline).

For example, a Perl script reading its arguments from <code>stdin</code>
 would use something like:
<pre>
 while (my $line = &lt;STDIN&gt;) {
 chomp($line);

if ($line eq ".") {
        last;
      }

# Handle $line appropriately here
 }
</pre>
 The advantange of using this <code>useStdin</code> option is that some
 systems have tools (e.g. <code>ps</code>) which will show the
 command-line arguments to commands being executed. For the security
 conscious, using <code>stdin</code> to pass arguments is less visible
 to other users of the system.
</ul>

<hr>
<h3><a name="ExecTimeout">ExecTimeout</a></h3>
Syntax: ExecTimeout seconds 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_exec 
Compatibility: 1.2.9rc2 and later

The <code>ExecTimeout</code> directive is used to set a limit on how long
the executed commands can run. Processes that exceed the configured timeout
will first be sent SIGTERM, to allow them to cleanly shutdown. If the process
is still around, it will then be sent SIGKILL, which cannot be ignored. A
value of zero configures an infinite timeout (not recommended).

<hr>
<h2><a name="Usage">Usage</a></h2>
Example configuration:
<pre>
 &lt;IfModule mod_exec.c&gt;
 ExecEngine on
 ExecLog /var/log/ftpd/exec.log
 ExecOnConnect /path/to/script
 &lt;/IfModule&gt;
</pre>

This module will not work properly for <code>&lt;Anonymous&gt;</code> logins,
or for logins that are affected by <code>DefaultRoot</code>. These directives
use the <code>chroot(2)</code> system call, which wreaks havoc when it
comes to scripts. The path to script/shell interpreters often assume a certain
location that is no longer valid within a chroot. In addition, most modern
operating systems use dynamically loaded libraries (<code>.so</code>
libraries) for many binaries, including script/shell interpreters. The
location of these libraries, when they come to be loaded, are also assumed;
those assumptions break within a chroot. Perl, in particular, is so
wrought with filesystem location assumptions that it's almost impossible
to get a Perl script to work within a chroot, short of installing Perl
itself into the chroot environment.

In short, this module is probably not what you want. And, try as I might,
I cannot convince users that this module is not what they want. Therefore,
I'll let you try to use this module yourself, and you can prove to yourself
that it probably won't do what you want.

As an alternative to <code>mod_exec</code> for executing arbitrary
scripts/commands based on FTP command issued, file uploaded/downloaded,
etc, I recommend using a logging FIFO-based approach, similar to
what is illustrated <a href="../howto/Logging.html">here</a>. This approach
allows for any script you wish, and is not subject to the restrictions of a
chroot, meaning that you can use <code>DefaultRoot</code> and still have
arbitrary scripts executed. If requested, I can provide help in writing a
FIFO reader to execute the necessary scripts.

<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_exec</code> module is distributed with ProFTPD. Follow the
usual steps for using third-party modules in ProFTPD:
<pre>
 $ ./configure --with-modules=mod_exec
</pre>
To build <code>mod_exec</code> as a DSO module:
<pre>
 $ ./configure --enable-dso --with-shared=mod_exec
</pre>
Then follow the usual steps:
<pre>
 $ make
 $ make install
</pre>

Alternatively, if your <code>proftpd</code> was compiled with DSO support, you
can use the <code>prxs</code> tool to build <code>mod_exec</code> as a shared
module:
<pre>
 $ prxs -c -i -d mod_exec.c
</pre>

<a name="FAQ"></a>
Frequently Asked Questions 
Question: Why do <code>%U/%u</code> not work properly with <code>ExecOnConnect</code>? 
Answer: Both <code>%U</code> and <code>%u</code> will
be empty on <code>ExecOnConnect</code> because, at that point, the client has
done a TCP connect to the server, but has not sent any sort of information
(including user name). Which means that <code>mod_exec</code> does not have
a user name to use at connect time.

One way to work around this limitation is to use a different trigger,
e.g.:
<pre>
 ExecOnCommand PASS ...
</pre>
By the time the client sends the <code>USER</code> and <code>PASS</code>
commands, the server will have the necessary user information to populate
the <code>%U/%u</code> variables.

Question: When I use <code>DefaultRoot</code> to chroot
my sessions, my exec scripts no longer work; the <code>ExecLog</code> shows
errors like this:
<pre>
preparing to execute '/tmp/ftp-logger.py' with uid 1000 (euid 1000), gid 1000 (egid 1000)
 + '/tmp/ftp-logger.py': argv[1] = --user
 + '/tmp/ftp-logger.py': argv[2] = ftp
 + '/tmp/ftp-logger.py': argv[3] = --file
 + '/tmp/ftp-logger.py': argv[4] = /home/ftp/test-ftp-demo.py
 + '/tmp/ftp-logger.py': argv[5] = 172.17.0.1
error: unable to open /dev/null for stdin: No such file or directory
'/tmp/ftp-logger.py' terminated normally, with exit status 2
STOR ExecOnCommand '/tmp/ftp-logger.py' failed: No such file or directory
</pre>
Is this a bug? 
Answer: No, this is not a bug. It is a consequence
of how the <code>DefaultRoot</code> directive works.

The <code>DefaultRoot</code> directive uses the <code>chroot(2)</code> system
call, to effectively "jail" your sessions, by changing the root of the
filesystem for that process. This affects everything. Many scripts
are executed by interpreters; you can see these in the very first line of the
script, e.g.:
<pre>
#!/bin/bash
</pre>
or:
<pre>
#!/usr/bin/env python
</pre>
Within a chrooted environment, though, those interpreter paths are no longer
valid. Hence the "No such file or directory" error. This also explains why
<code>/dev/null</code> cannot be found; it does not exist in the chroot.

</body>
</html>