ftp-proxy, test-ftp — File Transfer Protocol (FTP) proxy


ftp-proxy [-hv] [-d dbglev] -f cfgfile

test-ftp [-hv] [-d dbglev] -f cfgfile [-r] [-t test_expr]


The ftp-proxy provides proxying service for the File Transfer Protocol (RFC 959) and its extensions. For crucial commands, it behaves like a server for the client and vice versa, with full syntax and semantics verification, commands not impacting session state are only recognized and simply forwarded to server.

Proxy reads its configuration file and starts listening on specified IP sockets (address/port couples), as specified in the listen-on configuration section (see listen-on(5)).

Format of the configuration file is described in ftp-proxy.cfg(5).

Program test-ftp tests syntax and partially semantics of the configuration; for test expression syntax, see test-expr(5).

Access Control Lists

FTP-proxy uses three layers ACL (see access-control(7)), namely session-acls, command-acls and doc-acls.


When a connection arrives, configuration is consulted, proper session-acl is selected and according to it, connection is allowed or not.

When a transparent connection arrives (i.e., a connection destined for a real server, transparently redirected to the proxy by PF, see transparency(7) for details), the proxy will connect to the original destination server.

When a non-transparent connection arrives (i.e., a connection destined directly for one of the sockets the proxy is listening on) and is allowed by policy, either the proxy must be configured to connect to a specific remote server with the plug-to configuration directive (see below) or user must specify remote server (see below).

If a plug-to directive is used for a transparent connection, it has precedence over the original destination. This means that the proxy will ignore the original destination and connect to the plug-to server, instead.

Another possible operation mode is to forward all FTP traffic to another proxy in chain. In this case, name or address of this hand-off proxy must be specified in configuration together with a method used to introduce the remote server to the hand-off proxy. The current version of Kernun ftp-proxy can use all methods that it understands, i.e.

  • appending server name to the first USER command

  • using SITE command (or aliases of it).

Firewall administrator can choose any method described in auth(7) (except for NTLM) for authenticating users on the proxy. If the method requires sending of proxy-username and proxy-password, the client can use several methods of combination of USER and PASS commands (see below).


After successful proxy-authentication, proxy attempts to find a command-acl acceptable for this session. When found, access is either denied or granted and ACL restrictions are applied. Then, connection to the remote server (or hand-off proxy) is made and normal FTP operation starts. At this point, the so called initialization phase is finished. Firewall administrator can limit, for how long this phase can last at maximum, measured both in seconds and in number of commands. ACL search is then repeated for each incoming user command.

There are three FTP specific restrictions in command-acl:


This item specifies that user can request connection to any port, not only to standard FTP port (21).


Set of these items specify restrictions for the FTP Protocol commands (permitting/denying or data-transfer size limits). By default, all commands are denied. If you use restrictive policy, be careful when allowing commands — some of them are used in groups (e.g. PASV+RETR, RNFR+RNTO etc.).


Set of these items specify restrictions for the FTP Protocol extensions. When the proxy forwards server reply to the FEAT command, all options are compared to the set of these items and proper filtration is applied. The options unimplemented in the proxy are denied and cannot be permited. Other options can be permited and/or denied, the default proxy behavior is passing all known and removing all unknown ones.


When a data transfer (downloading or uploading a file), is initiated the list of doc-acls are searched. Among standard layer 3 conditions, the foolowing should be used: direction (incoming or outgoing data), size and mime-type. For the MIME type identification (see doctype-identification(7)), only filename extension and magic number recognition should be used in FTP. In adition, a FTP specific condition, the filename — matching the file name (without path) can be applied.


Be careful when using both filename and mime-type entry conditions. As they are two different item types, they are checked in conjunction, so the file must match both of them to match the ACL.

A doc-acl controls how the proxy handles the data. In addition to standard ACL actions accept and deny, additional processing may be configured:


Specifies parameters and actions for checking data for viruses.


Specifies parameters for filtration of HTML documents. Details about HTML filter configuration can be found in mod-html-filter(5).

Data Transfers

For data connections, proxy uses the same transfer initiation method as the client, by default. If client uses active method, proxy uses PORT command, if client uses passive method, proxy tries EPSV command and if it is rejected, PASV command. Forcing of active/passive method for particular servers can be specified by data-transfer configuration directive. When connecting to a server, it is checked against all data-transfer lists (using MATCH-ANY style, see host-matching(7) for details) and if it matches, proper data transfer method is used.

If client uses active data transfer, the proxy binds generic source-port for the data connection, unless another port is forced by data-port configuration directive. Under normal circumstances, the proxy runs under non-root user and cannot use reserved data ports (0..1023) this way.

User can choose data transfer method used from proxy to server by Kernun specific FTP command BNB (see below).

If the proxy executes the antivirus check, it must receive the whole file content before sending any data to destination. It can cause problems with some timeouts on peers. In such situations, the admin can decide to use the antivirus keepalive feature (see antivirus(5)). In this case, proxy sends some data to destination before it completes antivirus checking and (if a virus is found) aborts the file transfer. However, on the destination side, an invalid fragment of transferred file will occur.

Common Kernun Features

The proxy uses common Kernun mechanism for listening on its sockets, forking new processes as needed and killing old redundant processes, optionally changing root directory and running with alternative user privileges. For more detailed information, see application(5) and tcpserver(7).

The proxy uses common Kernun mechanism for network input/output operations. Configuration allows for specifying several parameters like buffer sizes and timeouts, both for client and server connections. They can be included in client-conn and server-conn configuration sections, respectively. For more detailed information, see netio(7).

The proxy uses common Kernun mechanism for logging (see logging(7)). For every session, a couple of SESSION-START (FTPP-808-I) and SESSION-END (FTPP-809-I) messages is logged (besides one or two ACL messages - FTPS-810-I and FTPS-820-I). For every data transfer, two DATA-INIT (FTPT-880-I) and one summarization DATA-END (FTPT-890-I) messages are logged.

The proxy uses common Kernun mechanism for name resolving (see resolving(7)).

The proxy uses common Kernun mechanism for runtime monitoring. For more detailed information, see monitoring(7).

The proxy uses common Kernun mechanism for traffic shaping. For more detailed information, see traffic-shaping(7).

Program Options

The program options are as follows:


Print usage information and exit.


Display version information and exit.

-d dbglev

Set debug level to a specific number. Permitted values are 3 through to 9, 3 being the least and 9 the most verbose. See logging(7) for details. This setting is relevant only till configuration reading is finished.

-f cfgfile

Read cfgfile for configuration information.


Resolve names in configuration prior to testing.

-t test_expr

Test configuration according to given expression. Format of the test_expr is described in test-expr(5).

Kernun Specific Commands

Kernun FTP Proxy recognizes several specific commands during session initialization and one special command within FTP Protocol ('BNB') for setting some options during normal operation.

Transparent/plug-to Case, No Authentication

In this case, no initialization commands are needed, because the proxy knows the targer server either from socket destination IP address (see transparency(7)) or from configuration plug-to directive (see ftp-proxy.cfg(5)).

Non-transparent/plug-to Case, No Authentication

In this case, the proxy must get to know name or address of the target server. The client can specify it by two ways:

a)  SITE server [port]

This command must be used as the first one in session. The proxy tries to connect to the given server and port and if succeeds, the initialization phase is completed.

b)  USER remote-user@server[:port]


    USER remote-user@server [port]


    USER server!remote-user [port]

This command must be used as the first one in session. Proxy tries to connect to given server and port and to apply a new USER command with the given user name to this server. If it succeeds, the initialization phase is completed.

In both cases, the server can be specified by a host name or by an IP address, port can be specified by a number or as a Well-Known Service (WKS, see /etc/services file and services(5) system manual page).

Transparent/Plug-to Case, with Authentication

In this case, the proxy must get to know the name of proxy user. The client can specify it by two ways:

a)  USER proxy-user
    PASS proxy-pasw

These commands must be used as the first ones in session. If the proxy receives the first USER command with argument containing no '@'s, it handles this command as proxy-authentication command and expects PASS command with proxy-user password. After successful authentication, proxy tries to connect to target server and if succeeds, the initialization phase is completed.

b)  USER proxy-user@remote-user
    PASS proxy-pasw@remote-pasw

These commands must be used as the first ones in session. The proxy remembers both user names and expects the PASS command. Then tries to authenticate the proxy-user and after connecting to the target server applies both USER and PASS commands for the remote user, too. If it succeeds, the initialization phase is completed.


For this case, the proxy-user password must not contain the '@' character.

Non-transparent, non plug-to Case, with Authentication

In this case, the proxy must get to know both the target server and the proxy-user name/password. The client can specify it by many ways resulting as combination of methods described in the last two sections, e.g.:

a)  USER proxy-user@remote-user@server[:port]
    PASS proxy-pasw@remote-pasw
b)  SITE server [port]
    USER proxy-user@remote-user
    PASS proxy-pasw@remote-pasw
c)  USER proxy-user
    PASS proxy-pasw
    USER remote-user@server[:port]
d)  SITE server [port]
    USER proxy-user
    PASS proxy-pasw
e)  USER proxy-user
    PASS proxy-pasw
    SITE server [port]

BNB Command

BNB Command is intended to allow communication with the proxy not only during the initialization phase, but within whole session. In current version, the communication language and data transfer mode (active/passive) to server can be set using this command. Quick help on this command is available by using 'BNB HELP' command. This command should be send from regular ftp client by using the QUOTE command (see ftp(1) for details).


The ftp-proxy is able to cooperate with the http-proxy. If an HTTP request with ftp: scheme is received by the http-proxy, it is forwarded to the ftp-proxy according to the item ftp-proxy in http-proxy configuration. Then the ftp-proxy handles the request using FTP and returns the result back to the http-proxy. A Kernun-specific protocol called HTFTP is used for communication between the two proxies. If the ftp-proxy should cooperate with the http-proxy, it is necessary to set htftp-mode in one of its session-acls. Any connection matching this session-acl is handled in HTFTP mode while other connections use normal FTP. A typical configuration reserves a single non-transparent listening port accessible only from localhost for HTFTP.

Note that it is possible to configure the HTML filter and antivirus checking both in the ftp-proxy and in the http-proxy. Since double-checking the same data is redundant, it is recommended to configure filtration and antivirus checking in only one proxy for data passing through both proxies via HTFTP.


Currently, the ftp-proxy doesn't implement RFC 1639 (LPSV and LPRT commands) and RFC 2228 (Authentication).

See Also


This man page is a part of Kernun Firewall.
Copyright © 2000–2023 Trusted Network Solutions, a. s.
All rights reserved.