2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_proxy_ftp.xml.meta">
25 <name>mod_proxy_ftp</name>
26 <description>FTP support module for
27 <module>mod_proxy</module></description>
28 <status>Extension</status>
29 <sourcefile>mod_proxy_ftp.c</sourcefile>
30 <identifier>proxy_ftp_module</identifier>
33 <p>This module <em>requires</em> the service of <module
34 >mod_proxy</module>. It provides support for the proxying
35 FTP sites. Note that FTP support is currently limited to
38 <p>Thus, in order to get the ability of handling FTP proxy requests,
39 <module>mod_proxy</module> and <module>mod_proxy_ftp</module>
40 have to be present in the server.</p>
42 <note type="warning"><title>Warning</title>
43 <p>Do not enable proxying until you have <a
44 href="mod_proxy.html#access">secured your server</a>. Open proxy
45 servers are dangerous both to your network and to the Internet at
49 <seealso><module>mod_proxy</module></seealso>
51 <section id="mimetypes"><title>Why doesn't file type <var>xxx</var>
52 download via FTP?</title>
53 <p>You probably don't have that particular file type defined as
54 <code>application/octet-stream</code> in your proxy's mime.types
55 configuration file. A useful line can be</p>
58 <pre>application/octet-stream bin dms lha lzh exe class tgz taz</pre>
60 <p>Alternatively you may prefer to default everything to binary:</p>
62 <highlight language="config">ForceType application/octet-stream</highlight>
64 </section> <!-- /mimetypes -->
66 <section id="type"><title>How can I force an FTP ASCII download of
67 File <var>xxx</var>?</title>
68 <p>In the rare situation where you must download a specific file using the
69 FTP <code>ASCII</code> transfer method (while the default transfer is in
70 <code>binary</code> mode), you can override <module>mod_proxy</module>'s
71 default by suffixing the request with <code>;type=a</code> to force an
72 ASCII transfer. (FTP Directory listings are always executed in ASCII mode,
74 </section> <!-- /type -->
76 <section id="ftpnonget"><title>How can I do FTP upload?</title>
77 <p>Currently, only GET is supported for FTP in mod_proxy. You can
78 of course use HTTP upload (POST or PUT) through an Apache proxy.</p>
81 <section id="percent2fhck"><title>How can I access FTP files outside
82 of my home directory?</title>
83 <p>An FTP URI is interpreted relative to the home directory of the user
84 who is logging in. Alas, to reach higher directory levels you cannot
85 use /../, as the dots are interpreted by the browser and not actually
86 sent to the FTP server. To address this problem, the so called <dfn>Squid
87 %2f hack</dfn> was implemented in the Apache FTP proxy; it is a
88 solution which is also used by other popular proxy servers like the <a
89 href="http://www.squid-cache.org/">Squid Proxy Cache</a>. By
90 prepending <code>/%2f</code> to the path of your request, you can make
91 such a proxy change the FTP starting directory to <code>/</code> (instead
92 of the home directory). For example, to retrieve the file
93 <code>/etc/motd</code>, you would use the URL:</p>
96 ftp://<var>user</var>@<var>host</var>/%2f/etc/motd
98 </section> <!-- /percent2fhck -->
100 <section id="ftppass"><title>How can I hide the FTP cleartext password
101 in my browser's URL line?</title>
102 <p>To log in to an FTP server by username and password, Apache uses
103 different strategies. In absence of a user name and password in the URL
104 altogether, Apache sends an anonymous login to the FTP server,
108 user: anonymous<br />
109 password: apache_proxy@
112 <p>This works for all popular FTP servers which are configured for
113 anonymous access.</p>
115 <p>For a personal login with a specific username, you can embed the user
116 name into the URL, like in:</p>
119 ftp://<var>username</var>@<var>host</var>/myfile
122 <p>If the FTP server asks for a password when given this username (which
123 it should), then Apache will reply with a <code>401</code> (Authorization
124 required) response, which causes the Browser to pop up the
125 username/password dialog. Upon entering the password, the connection
126 attempt is retried, and if successful, the requested resource is
127 presented. The advantage of this procedure is that your browser does not
128 display the password in cleartext (which it would if you had used</p>
131 ftp://<var>username</var>:<var>password</var>@<var>host</var>/myfile
134 <p>in the first place).</p>
136 <note><title>Note</title>
137 <p>The password which is transmitted in such a way is not encrypted on
138 its way. It travels between your browser and the Apache proxy server in
139 a base64-encoded cleartext string, and between the Apache proxy and the
140 FTP server as plaintext. You should therefore think twice before
141 accessing your FTP server via HTTP (or before accessing your personal
142 files via FTP at all!) When using insecure channels, an eavesdropper
143 might intercept your password on its way.</p>
145 </section> <!-- /ftppass -->
147 <section id="wildcard"><title>Why do I get a file listing when I expected
148 a file to be downloaded?</title>
149 <p>In order to allow both browsing the directories on an FTP server and
150 downloading files, Apache looks at the request URL. If it looks like
151 a directory, or contains wildcard characters ("*?[{~"), then it
152 guesses that a listing is wanted instead of a download.</p>
153 <p>You can disable the special handling of names with wildcard characters.
154 See the <directive>ProxyFtpListOnWildcard</directive> directive.
156 </section> <!-- /wildcard -->
159 <name>ProxyFtpListOnWildcard</name>
160 <description>Whether wildcards in requested filenames trigger a file listing</description>
161 <syntax>ProxyFtpListOnWildcard [on|off]</syntax>
162 <default>on</default>
163 <contextlist><context>server config</context><context>virtual host</context>
164 <context>directory</context></contextlist>
165 <compatibility>Available in Apache 2.3.3 and later</compatibility>
168 <p>The <directive>ProxyFtpListOnWildcard</directive> directive
169 controls whether wildcard characters ("*?[{~") in requested
170 filenames cause <module>mod_proxy_ftp</module> to return a listing
171 of files instead of downloading a file. By default (value on),
172 they do. Set to "off" to allow downloading files even if they
173 have wildcard characters in their names.</p>
178 <name>ProxyFtpEscapeWildcards</name>
179 <description>Whether wildcards in requested filenames are escaped when sent to the FTP server</description>
180 <syntax>ProxyFtpEscapeWildcards [on|off]</syntax>
181 <default>on</default>
182 <contextlist><context>server config</context><context>virtual host</context>
183 <context>directory</context></contextlist>
184 <compatibility>Available in Apache 2.3.3 and later</compatibility>
187 <p>The <directive>ProxyFtpEscapeWildcards</directive> directive
188 controls whether wildcard characters ("*?[{~") in requested
189 filenames are escaped with backslash before sending them to the
190 FTP server. That is the default behavior, but many FTP servers
191 don't know about the escaping and try to serve the literal filenames
192 they were sent, including the backslashes in the names. </p>
193 <p>Set to "off" to allow downloading files with wildcards
194 in their names from FTP servers that don't understand wildcard
200 <name>ProxyFtpDirCharset</name>
201 <description>Define the character set for proxied FTP listings</description>
202 <syntax>ProxyFtpDirCharset <var>character set</var></syntax>
203 <default>ProxyFtpDirCharset ISO-8859-1</default>
204 <contextlist><context>server config</context><context>virtual host</context>
205 <context>directory</context></contextlist>
206 <compatibility>Moved from <module>mod_proxy</module> in Apache 2.3.5.</compatibility>
209 <p>The <directive>ProxyFtpDirCharset</directive> directive defines the
210 character set to be set for FTP directory listings in HTML generated by
211 <module>mod_proxy_ftp</module>.</p>