/usr/share/doc/proftpd-mod-tar/mod_tar.html is in proftpd-mod-tar 0.3.3-1build2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 | <!-- $Id: mod_tar.html,v 1.3 2009/08/20 17:07:14 tj Exp tj $ -->
<!-- $Source: /home/tj/proftpd/modules/doc/RCS/mod_tar.html,v $ -->
<html>
<head>
<title>ProFTPD module mod_tar</title>
</head>
<body bgcolor=white>
<hr>
<center>
<h2><b>ProFTPD module <code>mod_tar</code></b></h2>
</center>
<hr><br>
<p>
The <code>mod_tar</code> module supports on-the-fly creation of tar files.
Whenever a client attempts to download a directory as a tar file, the
<code>mod_tar</code> module will automatically create a tar file of that
directory.
<p>
To provide this feature, the <code>mod_tar</code> module uses the
<code>libtar</code> library; see:
<pre>
<a href="http://www.feep.net/libtar/">http://www.feep.net/libtar/</a>
</pre>
<p>
This module is contained in the <code>mod_tar</code> file for
ProFTPD 1.3.<i>x</i>, and is not compiled by default. Installation
instructions are discussed <a href="#Installation">here</a>. More examples
of <code>mod_tar</code> usage can be found <a href="#Usage">here</a>.
<p>
The most current version of <code>mod_tar</code> can be found at:
<pre>
<a href="http://www.castaglia.org/proftpd/">http://www.castaglia.org/proftpd/</a>
</pre>
<h2>Author</h2>
<p>
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
questions, concerns, or suggestions regarding this module.
<h2>Directives</h2>
<ul>
<li><a href="#TarEnable">TarEnable</a>
<li><a href="#TarEngine">TarEngine</a>
<li><a href="#TarLog">TarLog</a>
<li><a href="#TarOptions">TarOptions</a>
<li><a href="#TarTempPath">TarTempPath</a>
</ul>
<hr>
<h2><a name="TarEnable">TarEnable</a></h2>
<strong>Syntax:</strong> TarEnable <em>on|off</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> <code><Directory></code>, <code>.ftpaccess</code>
<strong>Module:</strong> mod_tar<br>
<strong>Compatibility:</strong> 1.3.1rc1 and later
<p>
The <code>TarEnable</code> directive can be used to block or prevent a
directory from being turned into a tar file by <code>mod_tar</code>.
<hr>
<h2><a name="TarEngine">TarEngine</a></h2>
<strong>Syntax:</strong> TarEngine <em>on|off</em><br>
<strong>Default:</strong> <em>off</em><br>
<strong>Context:</strong> "server config", <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code><br>
<strong>Module:</strong> mod_tar<br>
<strong>Compatibility:</strong> 1.3.1rc1 and later
<p>
The <code>TarEngine</code> directive enables or disables the module's
support for on-the-fly tar file creation.
<hr>
<h2><a name="TarLog">TarLog</a></h2>
<strong>Syntax:</strong> TarLog <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tar<br>
<strong>Compatibility:</strong> 1.3.1rc1 and later
<p>
The <code>TarLog</code> directive is used to a specify a log file for
<code>mod_tar</code> reporting and debugging, and can be done a per-server
basis. The <em>file</em> parameter must be the full path to the file to use for
logging. Note that this path must <b>not</b> be to a world-writeable
directory and, unless <code>AllowLogSymlinks</code> is explicitly set to
<em>on</em> (generally a bad idea), the path must <b>not</b> be a symbolic
link.
<p>
If <em>file</em> is "none", no logging will be done at all; this
setting can be used to override a <code>TarLog</code> setting inherited from
a <code><Global></code> context.
<hr>
<h2><a name="TarOptions">TarOptions</a></h2>
<strong>Syntax:</strong> TarOptions <em>opt1 ...</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> "server config", <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code><br>
<strong>Module:</strong> mod_tar<br>
<strong>Compatibility:</strong> 1.3.1rc1 and later
<p>
The <code>TarOptions</code> directive is used to configure various optional
behavior of <code>mod_tar</code>, usually pertaining to how the
<code>.tar</code> files are constructed.
<p>
Example:
<pre>
TarOptions dereference
</pre>
<p>
The currently implemented options are:
<ul>
<li><code>dereference</code><br>
<p>
Instead of creating <code>.tar</code> files which include symlinks,
include the files that the symlinks point to.
</ul>
<hr>
<h2><a name="TarTempPath">TarTempPath</a></h2>
<strong>Syntax:</strong> TarTempPath <em>path</em><br>
<strong>Default:</strong> <em>"./"</em><br>
<strong>Context:</strong> "server config", <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code><br>
<strong>Module:</strong> mod_tar<br>
<strong>Compatibility:</strong> 1.3.1rc1 and later
<p>
The <code>TarTempPath</code> directive controls the directory where
<code>mod_tar</code> will writes its temporary <code>.tar</code> files.
Keep in mind that the <code>TarTempPath</code> is subject to any chroot
(<i>i.e.</i> use of <code>DefaultRoot</code> or
<code><Anonymous></code>).
<p>
The default <code>TarTempPath</code> is "./", which means that the
temporary <code>.tar</code> files are written in the current directory of
the FTP session.
<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
To install <code>mod_tar</code>, copy the <code>mod_tar.c</code> file into:
<pre>
<i>proftpd-dir</i>/contrib/
</pre>
after unpacking the latest proftpd-1.3.<i>x</i> source code. For including
<code>mod_tar</code> as a staticly linked module:
<pre>
./configure --with-modules=mod_tar
</pre>
To build <code>mod_tar</code> as a DSO module:
<pre>
./configure --enable-dso --with-shared=mod_tar
</pre>
Then follow the usual steps:
<pre>
make
make install
</pre>
<p>
For those with an existing ProFTPD installation, you can use the
<code>prxs</code> tool to add <code>mod_tar</code>, as a DSO module, to
your existing server:
<pre>
# prxs -c -i -d -I /path/to/libtar/include -L /path/to/libtar/lib mod_tar.c
</pre>
<p>
Note that in order to support gzip and bzip2 compression, the
<code>mod_tar</code> module requires linking with the zlib (<code>-lz</code>)
and bzip2 lib (<code>-lbz2</code>) libraries. You may need to install
these packages on your system in order to build <code>mod_tar</code>.
<p>
<hr>
<h2><a name="Usage">Usage</a></h2>
<p>
The <code>mod_tar</code> module works by watching all download requests
(<i>i.e.</i> <code>RETR</code> commands), looking specifically for requests
like:
<pre>
RETR <i>$dir</i>.tar.gz
</pre>
The following extensions will trigger <code>mod_tar</code> to attempt
on-the-fly tar file creation:
<ul>
<li>.tar
<li>.tgz
<li>.tar.gz
<li>.tar.bz2
</ul>
<p>
If the requested tar file already exists, then <code>mod_tar</code> does
nothing, and lets the download proceed normally. If the requested tar file is
<i>not</i> for a directory, then <code>mod_tar</code> does nothing.
<p>
Next, the <code>mod_tar</code> module checks for the existence of a
"<i>$dir</i>/.notar" file. If this file is present, then <code>mod_tar</code>
does nothing. (This provides feature compatibility with wu-ftpd's on-the-fly
tar file creation feature.)
<p>
The <code>mod_tar</code> module then checks to see if <code>TarEnable</code>
has been configured for the requested directory. For example, you can
block certain directories from being bundled up by <code>mod_tar</code>
by using:
<pre>
<Directory $dir>
TarEnable off
</Directory>
</pre>
<p>
Once these checks have passed, a randomly generated unique filename is
generated for the tar file to be created; the tar file is created in the
session's <i>current working directory</i> (although this can be changed
using the <a href="#TarTempPath"><code>TarTempPath</code></a> directive), and
is deleted after the download finishes. This means that the client will need
write privileges in that directory in order for the tar file to be created.
<p>
<b>No external commands are used for creating the tar file.</b> Searches
for on-the-fly tar file creation will turn up <a href="http://www.governmentsecurity.org/articles/Thedangersofftpconversionsonmisconfiguredsystems.php">reports</a>
of vulnerabilities and issues with the tar file feature in wu-ftpd. The
problem there was that wu-ftpd used external commands, such as
<code>/bin/tar</code>, to create the tar files. These commands take a range
of command-line options; malicious FTP clients could exploit those
command-line options, and wu-ftpd's on-the-fly tar file implementation, to
attack the server. By contrast, the <code>mod_tar</code> module does
<b>not</b> use any external commands; it uses the <code>libtar</code> library
for creating the tar file. And <code>mod_tar</code> ensures that the
requested path is indeed a directory and that that directory path is treated
as-is, with no special interpolation or interpretation.
<p>
Example configuration:
<pre>
<IfModule mod_tar.c>
TarEngine on
TarLog /var/ftpd/tar.log
</IfModule>
</pre>
<p>
<hr><br>
Author: <i>$Author: tj $</i><br>
Last Updated: <i>$Date: 2009/08/20 17:07:14 $</i><br>
<br><hr>
<font size=2><b><i>
© Copyright 2009 TJ Saunders<br>
All Rights Reserved<br>
</i></b></font>
<hr><br>
</body>
</html>
|