apache/docs/manual/mod/mod_proxy_ftp.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<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>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>DefaultType 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 -->


</modulesynopsis>