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).
FTP-proxy uses three layers ACL (see access-control(7)),
namely session-acls, command-acls
and doc-acls.
session-aclWhen 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).
command-aclAfter 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:
enable-portThis item specifies that user can request connection to any port, not only to standard FTP port (21).
commandSet 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.).
featureSet 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.
doc-aclWhen 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:
antivirusSpecifies parameters and actions for checking data for viruses.
html-filterSpecifies parameters for filtration of HTML documents. Details about HTML filter configuration can be found in mod-html-filter(5).
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.
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).
The program options are as follows:
-hPrint usage information and exit.
-vDisplay version information and exit.
-d dbglevSet 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 cfgfileRead cfgfile
for configuration information.
-rResolve names in configuration prior to testing.
-t test_exprTest configuration according to given expression.
Format of the test_expr is described in test-expr(5).
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.
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)).
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) SITEserver[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) USERremote-user@server[:port]
or
USER remote-user@server [port]
or
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).
In this case, the proxy must get to know the name of proxy user. The client can specify it by two ways:
a)USERproxy-userPASSproxy-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)USERproxy-user@remote-userPASSproxy-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.
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) USERproxy-user@remote-user@server[:port] PASSproxy-pasw@remote-pasw
b) SITEserver[port] USERproxy-user@remote-userPASSproxy-pasw@remote-pasw
c) USERproxy-userPASSproxy-paswUSERremote-user@server[:port]
d) SITEserver[port] USERproxy-userPASSproxy-pasw
e) USERproxy-userPASSproxy-paswSITEserver[port]
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).
antivirus(5), application(5), ftp-proxy.cfg(5), listen-on(5), mod-html-filter(5), test-expr(5), FTPP-808(6), FTPS-810(6), FTPS-820(6), FTPP-809(6), FTPT-880(6), FTPT-890(6), access-control(7), auth(7), configuration(7), doctype-identification(7), host-matching(7), logging(7), monitoring(7), netio(7), resolving(7), tcpserver(7), time-matching(7), traffic-shaping(7), transparency(7)
ftp(1), services(5)