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

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   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
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  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.
  21 -->
  22
  23 <modulesynopsis metafile="mod_proxy_ftp.xml.meta">
  24
  25 <name>mod_proxy_ftp</name>
  26 <description>FTP support module for
  27 <module>mod_proxy</module></description>
  28 <status>Extension</status>
  29 <sourcefile>proxy_ftp.c</sourcefile>
  30 <identifier>proxy_ftp_module</identifier>
  31
  32 <summary>
  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
  36     the GET method.</p>
  37
  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>
  41
  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
  46       large.</p>
  47     </note>
  48 </summary>
  49 <seealso><module>mod_proxy</module></seealso>
  50
  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>
  56
  57       <example>
  58 <pre>application/octet-stream   bin dms lha lzh exe class tgz taz</pre>
  59       </example>
  60         <p>Alternatively you may prefer to default everything to binary:</p>
  61       <example>
  62 <pre>DefaultType application/octet-stream</pre>
  63       </example>
  64     </section> <!-- /mimetypes -->
  65
  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,
  73       however.)</p>
  74     </section> <!-- /type -->
  75
  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>
  79     </section>
  80
  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>
  94
  95       <example>
  96         ftp://<var>user</var>@<var>host</var>/%2f/etc/motd
  97       </example>
  98     </section> <!-- /percent2fhck -->
  99
 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 absense of a user name and password in the URL
 104       altogether, Apache sends an anonymous login to the FTP server,
 105       <em>i.e.</em>,</p>
 106
 107       <example>
 108         user: anonymous<br />
 109         password: apache_proxy@
 110       </example>
 111
 112       <p>This works for all popular FTP servers which are configured for
 113       anonymous access.</p>
 114
 115       <p>For a personal login with a specific username, you can embed the user
 116       name into the URL, like in:</p>
 117
 118       <example>
 119         ftp://<var>username</var>@<var>host</var>/myfile
 120       </example>
 121
 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>
 129
 130       <example>
 131         ftp://<var>username</var>:<var>password</var>@<var>host</var>/myfile
 132       </example>
 133
 134       <p>in the first place).</p>
 135
 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 unsecure channels, an eavesdropper
 143         might intercept your password on its way.</p>
 144       </note>
 145     </section> <!-- /ftppass -->
 146
 147
 148 </modulesynopsis>