<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<modulesynopsis metafile="mod_proxy_ftp.xml.meta">

<name>mod_proxy_ftp</name>

<description>FTP support module for

<module>mod_proxy</module></description>

<status>Extension</status>

<sourcefile>mod_proxy_ftp.c</sourcefile>

<identifier>proxy_ftp_module</identifier>

<summary>

<p>This module <em>requires</em> the service of <module

>mod_proxy</module>. It provides support for the proxying

FTP sites. Note that FTP support is currently limited to

the GET method.</p>

<p>Thus, in order to get the ability of handling FTP proxy requests,

<module>mod_proxy</module> and <module>mod_proxy_ftp</module>

have to be present in the server.</p>

<note type="warning"><title>Warning</title>

<p>Do not enable proxying until you have <a

href="mod_proxy.html#access">secured your server</a>. Open proxy

servers are dangerous both to your network and to the Internet at

large.</p>

</note>

</summary>

<seealso><module>mod_proxy</module></seealso>

<section id="mimetypes"><title>Why doesn't file type <var>xxx</var>

download via FTP?</title>

<p>You probably don't have that particular file type defined as

<code>application/octet-stream</code> in your proxy's mime.types

configuration file. A useful line can be</p>

<example>

<pre>application/octet-stream bin dms lha lzh exe class tgz taz</pre>

</example>

<p>Alternatively you may prefer to default everything to binary:</p>

<example>

<pre>ForceType application/octet-stream</pre>

</example>

</section> <!-- /mimetypes -->

<section id="type"><title>How can I force an FTP ASCII download of

File <var>xxx</var>?</title>

<p>In the rare situation where you must download a specific file using the

FTP <code>ASCII</code> transfer method (while the default transfer is in

<code>binary</code> mode), you can override <module>mod_proxy</module>'s

default by suffixing the request with <code>;type=a</code> to force an

ASCII transfer. (FTP Directory listings are always executed in ASCII mode,

however.)</p>

</section> <!-- /type -->

<section id="ftpnonget"><title>How can I do FTP upload?</title>

<p>Currently, only GET is supported for FTP in mod_proxy. You can

of course use HTTP upload (POST or PUT) through an Apache proxy.</p>

</section>

<section id="percent2fhck"><title>How can I access FTP files outside

of my home directory?</title>

<p>An FTP URI is interpreted relative to the home directory of the user

who is logging in. Alas, to reach higher directory levels you cannot

use /../, as the dots are interpreted by the browser and not actually

sent to the FTP server. To address this problem, the so called <dfn>Squid

%2f hack</dfn> was implemented in the Apache FTP proxy; it is a

solution which is also used by other popular proxy servers like the <a

href="http://www.squid-cache.org/">Squid Proxy Cache</a>. By

prepending <code>/%2f</code> to the path of your request, you can make

such a proxy change the FTP starting directory to <code>/</code> (instead

of the home directory). For example, to retrieve the file

<code>/etc/motd</code>, you would use the URL:</p>

<example>

ftp://<var>user</var>@<var>host</var>/%2f/etc/motd

</example>

</section> <!-- /percent2fhck -->

<section id="ftppass"><title>How can I hide the FTP cleartext password

in my browser's URL line?</title>

<p>To log in to an FTP server by username and password, Apache uses

different strategies. In absense of a user name and password in the URL

altogether, Apache sends an anonymous login to the FTP server,

<em>i.e.</em>,</p>

<example>

user: anonymous<br />

password: apache_proxy@

</example>

<p>This works for all popular FTP servers which are configured for

anonymous access.</p>

<p>For a personal login with a specific username, you can embed the user

name into the URL, like in:</p>

<example>

ftp://<var>username</var>@<var>host</var>/myfile

</example>

<p>If the FTP server asks for a password when given this username (which

it should), then Apache will reply with a <code>401</code> (Authorization

required) response, which causes the Browser to pop up the

username/password dialog. Upon entering the password, the connection

attempt is retried, and if successful, the requested resource is

presented. The advantage of this procedure is that your browser does not

display the password in cleartext (which it would if you had used</p>

<example>

ftp://<var>username</var>:<var>password</var>@<var>host</var>/myfile

</example>

<p>in the first place).</p>

<note><title>Note</title>

<p>The password which is transmitted in such a way is not encrypted on

its way. It travels between your browser and the Apache proxy server in

a base64-encoded cleartext string, and between the Apache proxy and the

FTP server as plaintext. You should therefore think twice before

accessing your FTP server via HTTP (or before accessing your personal

files via FTP at all!) When using unsecure channels, an eavesdropper

might intercept your password on its way.</p>

</note>

</section> <!-- /ftppass -->

<section id="wildcard"><title>Why do I get a file listing when I expected

a file to be downloaded?</title>

<p>In order to allow both browsing the directories on an FTP server and

downloading files, Apache looks at the request URL. If it looks like

a directory, or contains wildcard characters ("*?[{~"), then it

guesses that a listing is wanted instead of a download.</p>

<p>You can disable the special handling of names with wildcard characters.

See the <directive>ProxyFtpListOnWildcard</directive> directive.

</p>

</section> <!-- /wildcard -->

<directivesynopsis>

<name>ProxyFtpListOnWildcard</name>

<description>Whether wildcards in requested filenames trigger a file listing</description>

<syntax>ProxyFtpListOnWildcard [on|off]</syntax>

<default>on</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context></contextlist>

<compatibility>Available in Apache xxx and later</compatibility>

<usage>

<p>The <directive>ProxyFtpListOnWildcard</directive> directive

controls whether wildcard characters ("*?[{~") in requested

filenames cause <module>mod_proxy_ftp</module> to return a listing

of files instead of downloading a file. By default (value on),

they do. Set to "off" to allow downloading files even if they

have wildcard characters in their names.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ProxyFtpEscapeWildcards</name>

<description>Whether wildcards in requested filenames are escaped when sent to the FTP server</description>

<syntax>ProxyFtpEscapeWildcards [on|off]</syntax>

<default>on</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context></contextlist>

<compatibility>Available in Apache xxx and later</compatibility>

<usage>

<p>The <directive>ProxyFtpEscapeWildcards</directive> directive

controls whether wildcard characters ("*?[{~") in requested

filenames are escaped with backslash before sending them to the

FTP server. That is the default behavior, but many FTP servers

don't know about the escaping and try to serve the literal filenames

they were sent, including the backslashes in the names. </p>

<p>Set to "off" to allow downloading files with wildcards

in their names from FTP servers that don't understand wildcard

escaping.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ProxyFtpDirCharset</name>

<description>Define the character set for proxied FTP listings</description>

<syntax>ProxyFtpDirCharset <var>character set</var></syntax>

<default>ProxyFtpDirCharset ISO-8859-1</default>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context></contextlist>

<compatibility>Available in Apache 2.2.7 and later. Moved from <module>mod_proxy</module> in Apache 2.3.5.</compatibility>

<usage>

<p>The <directive>ProxyFtpDirCharset</directive> directive defines the

character set to be set for FTP directory listings in HTML generated by

<module>mod_proxy_ftp</module>.</p>

</usage>

</directivesynopsis>

</modulesynopsis>