granicus.if.org Git - apache/blob - docs/manual/mod/mod_proxy_ftp.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
   4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>mod_proxy_ftp - Apache HTTP Server Version 2.5</title>
  11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  18 <body>
  19 <div id="page-header">
  20 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  21 <p class="apache">Apache HTTP Server Version 2.5</p>
  22 <img alt="" src="../images/feather.png" /></div>
  23 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  24 <div id="path">
  25 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  26 <div id="page-content">
  27 <div id="preamble"><h1>Apache Module mod_proxy_ftp</h1>
  28 <div class="toplang">
  29 <p><span>Available Languages: </span><a href="../en/mod/mod_proxy_ftp.html" title="English">&nbsp;en&nbsp;</a> |
  30 <a href="../fr/mod/mod_proxy_ftp.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  31 </div>
  32 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>FTP support module for
  33 <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></td></tr>
  34 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  35 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>proxy_ftp_module</td></tr>
  36 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_proxy_ftp.c</td></tr></table>
  37 <h3>Summary</h3>
  38
  39     <p>This module <em>requires</em> the service of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. It provides support for the proxying
  40     FTP sites.  Note that FTP support is currently limited to
  41     the GET method.</p>
  42
  43     <p>Thus, in order to get the ability of handling FTP proxy requests,
  44     <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> and <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code>
  45     have to be present in the server.</p>
  46
  47     <div class="warning"><h3>Warning</h3>
  48       <p>Do not enable proxying until you have <a href="mod_proxy.html#access">secured your server</a>. Open proxy
  49       servers are dangerous both to your network and to the Internet at
  50       large.</p>
  51     </div>
  52 </div>
  53 <div id="quickview"><h3>Topics</h3>
  54 <ul id="topics">
  55 <li><img alt="" src="../images/down.gif" /> <a href="#mimetypes">Why doesn't file type <var>xxx</var>
  56     download via FTP?</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#type">How can I force an FTP ASCII download of
  58     file <var>xxx</var>?</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#ftpnonget">How can I do FTP upload?</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#percent2fhck">How can I access FTP files outside
  61     of my home directory?</a></li>
  62 <li><img alt="" src="../images/down.gif" /> <a href="#ftppass">How can I hide the FTP cleartext password
  63     in my browser's URL line?</a></li>
  64 <li><img alt="" src="../images/down.gif" /> <a href="#wildcard">Why do I get a file listing when I expected
  65         a file to be downloaded?</a></li>
  66 </ul><h3 class="directives">Directives</h3>
  67 <ul id="toc">
  68 <li><img alt="" src="../images/down.gif" /> <a href="#proxyftpdircharset">ProxyFtpDirCharset</a></li>
  69 <li><img alt="" src="../images/down.gif" /> <a href="#proxyftpescapewildcards">ProxyFtpEscapeWildcards</a></li>
  70 <li><img alt="" src="../images/down.gif" /> <a href="#proxyftplistonwildcard">ProxyFtpListOnWildcard</a></li>
  71 </ul>
  72 <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&amp;list_id=144532&amp;product=Apache%20httpd-2&amp;query_format=specific&amp;order=changeddate%20DESC%2Cpriority%2Cbug_severity&amp;component=mod_proxy_ftp">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=mod_proxy_ftp">Report a bug</a></li></ul><h3>See also</h3>
  73 <ul class="seealso">
  74 <li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
  75 <li><a href="#comments_section">Comments</a></li></ul></div>
  76 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  77 <div class="section">
  78 <h2><a name="mimetypes" id="mimetypes">Why doesn't file type <var>xxx</var>
  79     download via FTP?</a> <a title="Permanent link" href="#mimetypes" class="permalink">&para;</a></h2>
  80       <p>You probably don't have that particular file type defined as
  81       <code>application/octet-stream</code> in your proxy's mime.types
  82       configuration file. A useful line can be:</p>
  83
  84       <div class="example"><pre>application/octet-stream   bin dms lha lzh exe class tgz taz</pre></div>
  85       <p>Alternatively you may prefer to use the <code class="directive"><a href="../mod/core.html#forcetype">ForceType</a></code>
  86       directive to default everything to binary:</p>
  87       <div class="example"><pre class="prettyprint lang-config">ForceType application/octet-stream</pre>
  88 </div>
  89     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  90 <div class="section">
  91 <h2><a name="type" id="type">How can I force an FTP ASCII download of
  92     file <var>xxx</var>?</a> <a title="Permanent link" href="#type" class="permalink">&para;</a></h2>
  93       <p>In the rare situation where you must download a specific file using the
  94       FTP <code>ASCII</code> transfer method (while the default transfer is in
  95       <code>binary</code> mode), you can override <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>'s
  96       default by suffixing the request with <code>;type=a</code> to force an
  97       ASCII transfer. (FTP Directory listings are always executed in ASCII mode,
  98       however.)</p>
  99     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 100 <div class="section">
 101 <h2><a name="ftpnonget" id="ftpnonget">How can I do FTP upload?</a> <a title="Permanent link" href="#ftpnonget" class="permalink">&para;</a></h2>
 102     <p>Currently, only GET is supported for FTP in <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>.  You can
 103     of course use HTTP upload (POST or PUT) through an Apache proxy.</p>
 104     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 105 <div class="section">
 106 <h2><a name="percent2fhck" id="percent2fhck">How can I access FTP files outside
 107     of my home directory?</a> <a title="Permanent link" href="#percent2fhck" class="permalink">&para;</a></h2>
 108       <p>An FTP URI is interpreted relative to the home directory of the user
 109       who is logging in. Alas, to reach higher directory levels you cannot
 110       use /../, as the dots are interpreted by the browser and not actually
 111       sent to the FTP server. To address this problem, the so called <dfn>Squid
 112       %2f hack</dfn> was implemented in the Apache FTP proxy; it is a
 113       solution which is also used by other popular proxy servers like the <a href="http://www.squid-cache.org/">Squid Proxy Cache</a>. By
 114       prepending <code>/%2f</code> to the path of your request, you can make
 115       such a proxy change the FTP starting directory to <code>/</code> (instead
 116       of the home directory). For example, to retrieve the file
 117       <code>/etc/motd</code>, you would use the URL:</p>
 118
 119       <div class="example"><p><code>
 120         ftp://<var>user</var>@<var>host</var>/%2f/etc/motd
 121       </code></p></div>
 122     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 123 <div class="section">
 124 <h2><a name="ftppass" id="ftppass">How can I hide the FTP cleartext password
 125     in my browser's URL line?</a> <a title="Permanent link" href="#ftppass" class="permalink">&para;</a></h2>
 126       <p>To log in to an FTP server by username and password, Apache uses
 127       different strategies. In absence of a user name and password in the URL
 128       altogether, Apache sends an anonymous login to the FTP server,
 129       <em>i.e.</em>,</p>
 130
 131       <div class="example"><p><code>
 132         user: anonymous<br />
 133         password: apache-proxy@
 134       </code></p></div>
 135
 136       <p>This works for all popular FTP servers which are configured for
 137       anonymous access.</p>
 138
 139       <p>For a personal login with a specific username, you can embed the user
 140       name into the URL, like in:</p>
 141
 142       <div class="example"><p><code>
 143         ftp://<var>username</var>@<var>host</var>/myfile
 144       </code></p></div>
 145
 146       <p>If the FTP server asks for a password when given this username (which
 147       it should), then Apache will reply with a <code>401</code> (Authorization
 148       required) response, which causes the Browser to pop up the
 149       username/password dialog. Upon entering the password, the connection
 150       attempt is retried, and if successful, the requested resource is
 151       presented. The advantage of this procedure is that your browser does not
 152       display the password in cleartext (which it would if you had used</p>
 153
 154       <div class="example"><p><code>
 155         ftp://<var>username</var>:<var>password</var>@<var>host</var>/myfile
 156       </code></p></div>
 157
 158       <p>in the first place).</p>
 159
 160       <div class="note"><h3>Note</h3>
 161         <p>The password which is transmitted in such a way is not encrypted on
 162         its way. It travels between your browser and the Apache proxy server in
 163         a base64-encoded cleartext string, and between the Apache proxy and the
 164         FTP server as plaintext. You should therefore think twice before
 165         accessing your FTP server via HTTP (or before accessing your personal
 166         files via FTP at all!) When using insecure channels, an eavesdropper
 167         might intercept your password on its way.</p>
 168       </div>
 169     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 170 <div class="section">
 171 <h2><a name="wildcard" id="wildcard">Why do I get a file listing when I expected
 172         a file to be downloaded?</a> <a title="Permanent link" href="#wildcard" class="permalink">&para;</a></h2>
 173       <p>In order to allow both browsing the directories on an FTP server and
 174         downloading files, Apache looks at the request URL.  If it looks like
 175         a directory, or contains wildcard characters ("*?[{~"), then it
 176         guesses that a listing is wanted instead of a download.</p>
 177       <p>You can disable the special handling of names with wildcard characters.
 178         See the <code class="directive"><a href="#proxyftplistonwildcard">ProxyFtpListOnWildcard</a></code> directive.
 179       </p>
 180     </div>
 181 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 182 <div class="directive-section"><h2><a name="ProxyFtpDirCharset" id="ProxyFtpDirCharset">ProxyFtpDirCharset</a> <a name="proxyftpdircharset" id="proxyftpdircharset">Directive</a> <a title="Permanent link" href="#proxyftpdircharset" class="permalink">&para;</a></h2>
 183 <table class="directive">
 184 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define the character set for proxied FTP listings</td></tr>
 185 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFtpDirCharset <var>character_set</var></code></td></tr>
 186 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyFtpDirCharset ISO-8859-1</code></td></tr>
 187 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 188 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 189 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_ftp</td></tr>
 190 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Moved from <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> in Apache 2.3.5.</td></tr>
 191 </table>
 192     <p>The <code class="directive">ProxyFtpDirCharset</code> directive defines the
 193     character set to be set for FTP directory listings in HTML generated by
 194     <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code>.</p>
 195
 196 </div>
 197 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 198 <div class="directive-section"><h2><a name="ProxyFtpEscapeWildcards" id="ProxyFtpEscapeWildcards">ProxyFtpEscapeWildcards</a> <a name="proxyftpescapewildcards" id="proxyftpescapewildcards">Directive</a> <a title="Permanent link" href="#proxyftpescapewildcards" class="permalink">&para;</a></h2>
 199 <table class="directive">
 200 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether wildcards in requested filenames are escaped when sent to the FTP server</td></tr>
 201 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFtpEscapeWildcards on|off</code></td></tr>
 202 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyFtpEscapeWildcards on</code></td></tr>
 203 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 204 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 205 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_ftp</td></tr>
 206 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.3 and later</td></tr>
 207 </table>
 208   <p>The <code class="directive">ProxyFtpEscapeWildcards</code> directive
 209     controls whether wildcard characters ("*?[{~") in requested
 210     filenames are escaped with backslash before sending them to the
 211     FTP server.  That is the default behavior, but many FTP servers
 212     don't know about the escaping and try to serve the literal filenames
 213     they were sent, including the backslashes in the names.</p>
 214     <p>Set to "off" to allow downloading files with wildcards
 215     in their names from FTP servers that don't understand wildcard
 216     escaping.</p>
 217
 218 </div>
 219 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 220 <div class="directive-section"><h2><a name="ProxyFtpListOnWildcard" id="ProxyFtpListOnWildcard">ProxyFtpListOnWildcard</a> <a name="proxyftplistonwildcard" id="proxyftplistonwildcard">Directive</a> <a title="Permanent link" href="#proxyftplistonwildcard" class="permalink">&para;</a></h2>
 221 <table class="directive">
 222 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether wildcards in requested filenames trigger a file listing</td></tr>
 223 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFtpListOnWildcard on|off</code></td></tr>
 224 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyFtpListOnWildcard on</code></td></tr>
 225 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 226 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 227 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_ftp</td></tr>
 228 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.3 and later</td></tr>
 229 </table>
 230   <p>The <code class="directive">ProxyFtpListOnWildcard</code> directive
 231     controls whether wildcard characters ("*?[{~") in requested
 232     filenames cause <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code> to return a listing
 233     of files instead of downloading a file.  By default (value on),
 234     they do.</p>
 235     <p>Set to "off" to allow downloading files even if they
 236     have wildcard characters in their names.</p>
 237
 238 </div>
 239 </div>
 240 <div class="bottomlang">
 241 <p><span>Available Languages: </span><a href="../en/mod/mod_proxy_ftp.html" title="English">&nbsp;en&nbsp;</a> |
 242 <a href="../fr/mod/mod_proxy_ftp.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 243 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 244 <script type="text/javascript"><!--//--><![CDATA[//><!--
 245 var comments_shortname = 'httpd';
 246 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_proxy_ftp.html';
 247 (function(w, d) {
 248     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 249         d.write('<div id="comments_thread"><\/div>');
 250         var s = d.createElement('script');
 251         s.type = 'text/javascript';
 252         s.async = true;
 253         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 254         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 255     }
 256     else {
 257         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 258     }
 259 })(window, document);
 260 //--><!]]></script></div><div id="footer">
 261 <p class="apache">Copyright 2019 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 262 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 263 if (typeof(prettyPrint) !== 'undefined') {
 264     prettyPrint();
 265 }
 266 //--><!]]></script>
 267 </body></html>