mod_proxy_ftp - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

# Apache Module mod_proxy_ftp

Available Languages: en | fr

Description: | FTP support module for `mod_proxy`
Status: | Extension
Module Identifier: | proxy_ftp_module
Source File: | mod_proxy_ftp.c

### Summary

This module requires the service of `mod_proxy`. It provides support for the proxying FTP sites. Note that FTP support is currently limited to the GET method.

Thus, in order to get the ability of handling FTP proxy requests, `mod_proxy` and `mod_proxy_ftp` have to be present in the server.

### Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

### Topics

- Why doesn't file type xxx download via FTP?
- How can I force an FTP ASCII download of File xxx?
- How can I do FTP upload?
- How can I access FTP files outside of my home directory?
- How can I hide the FTP cleartext password in my browser's URL line?
- Why do I get a file listing when I expected a file to be downloaded?

### Directives

### Bugfix checklist

- httpd changelog
- Known issues
- Report a bug

### See also

- `mod_proxy`
- Comments

## Why doesn't file type xxx download via FTP?

You probably don't have that particular file type defined as `application/octet-stream` in your proxy's mime.types configuration file. A useful line can be

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

Alternatively you may prefer to default everything to binary:

    ForceType application/octet-stream

## How can I force an FTP ASCII download of File xxx?

In the rare situation where you must download a specific file using the FTP `ASCII` transfer method (while the default transfer is in `binary` mode), you can override `mod_proxy`'s default by suffixing the request with `;type=a` to force an ASCII transfer. (FTP Directory listings are always executed in ASCII mode, however.)

## How can I do FTP upload?

Currently, only GET is supported for FTP in mod_proxy. You can of course use HTTP upload (POST or PUT) through an Apache proxy.

## How can I access FTP files outside of my home directory?

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 Squid %2f hack was implemented in the Apache FTP proxy; it is a solution which is also used by other popular proxy servers like the Squid Proxy Cache. By prepending `/%2f` to the path of your request, you can make such a proxy change the FTP starting directory to `/` (instead of the home directory). For example, to retrieve the file `/etc/motd`, you would use the URL:

`ftp://user@host/%2f/etc/motd`

## How can I hide the FTP cleartext password in my browser's URL line?

To log in to an FTP server by username and password, Apache uses different strategies. In absence of a user name and password in the URL altogether, Apache sends an anonymous login to the FTP server, i.e.,

`user: anonymous
password: apache_proxy@`

This works for all popular FTP servers which are configured for anonymous access.

For a personal login with a specific username, you can embed the user name into the URL, like in:

`ftp://username@host/myfile`

If the FTP server asks for a password when given this username (which it should), then Apache will reply with a `401` (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

`ftp://username:password@host/myfile`

in the first place).

### Note

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 insecure channels, an eavesdropper might intercept your password on its way.

## Why do I get a file listing when I expected a file to be downloaded?

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.

You can disable the special handling of names with wildcard characters. See the `ProxyFtpListOnWildcard` directive.

## ProxyFtpDirCharset Directive

Description: | Define the character set for proxied FTP listings
Syntax: | `ProxyFtpDirCharset character set`
Default: | `ProxyFtpDirCharset ISO-8859-1`
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy_ftp
Compatibility: | Available in Apache 2.2.7 and later. Moved from `mod_proxy` in Apache 2.3.5.

The `ProxyFtpDirCharset` directive defines the character set to be set for FTP directory listings in HTML generated by `mod_proxy_ftp`.

## ProxyFtpEscapeWildcards Directive

Description: | Whether wildcards in requested filenames are escaped when sent to the FTP server
Syntax: | `ProxyFtpEscapeWildcards [on|off]`
Default: | `on`
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy_ftp
Compatibility: | Available in Apache 2.3.3 and later

The `ProxyFtpEscapeWildcards` 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.

Set to "off" to allow downloading files with wildcards in their names from FTP servers that don't understand wildcard escaping.

## ProxyFtpListOnWildcard Directive

Description: | Whether wildcards in requested filenames trigger a file listing
Syntax: | `ProxyFtpListOnWildcard [on|off]`
Default: | `on`
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy_ftp
Compatibility: | Available in Apache 2.3.3 and later

The `ProxyFtpListOnWildcard` directive controls whether wildcard characters ("*?[{~") in requested filenames cause `mod_proxy_ftp` 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.

Available Languages: en | fr

## Comments

Notice:
This is not a Q&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 mailing lists.