Ubuntu Manpage: ftp-proxy.conf - configuration file for FTP-Proxy

NAME

       ftp-proxy.conf - configuration file for FTP-Proxy

SYNOPSIS

       /etc/proxy-suite/ftp-proxy.conf

DESCRIPTION

This manual page documents the configuration file format of the ftp-proxy(8) program.
FTP-Proxy is an application level gateway between FTP clients and servers. Its main
purpose is to secure servers against attacks based on the FTP protocol.

The FTP-Proxy configuration file consists of option lines and comments. A line starting
with a '#' character is a comment. The general format of a option line is

[WhiteSpace] Name WhiteSpace Value [WhiteSpace]

It is recommended to use up to 24 characters for the name and no more than 1024 for the
value, although theoretically both can be up to 4096 in size. Lines can be continued if
the last character is a backslash. The whole file is not case sensitive.

CONTEXT
Option lines always have a context which may be global or user specific. A context is
introduced by a [name] line, where name is the FTP-login name or authuser if the
UserAuthMagic feature is used. It is allowed to use '*' wildcard character at the end of
the context name [name*] i.e. [foo*] to match multiple usernames beginning with "foo".
The beginning of the file is implicitly the [-Global-] context (the dashes allow a user
context named [global] without conflict). It is legal to include an option more than
once; the last one will be the one used. Options in user contexts usually take precedence
over the equivalent global option.

Some of the options can be used in a user or the global context, while others make sense
only in one of them. See below.

VARIABLE SUBSTITUTION
Several options (see the individual discussion below for details) support a limited set of
variable substitution when evaluated. The following replacements will be performed:

%b build date of the ftp-proxy(8) program
%d current system date in the form YYYY/MM/DD
%h host name from gethostname(2)
%n network name from getdomainname(2)
%t current system time in the form HH:MM:SS
%v version of the ftp-proxy(8) program
%% a single percent sign

OPTIONS

ActiveMaxDataPort
Both user and global context. Defines the maximum local port number used when
connecting to the client's data port. The latter is either the same as the
client's control port or the one given in the most recent PORT command. If either
minimum or maximum value is not given, the program defaults to using port 20, the
ftp-data port as per RFC 959, for the local end of the socket if the proxy is
running as root (user ID 0) or to use a random port. See also ActiveMinDataPort and
User options.

ActiveMinDataPort
Both user and global context. Defines the minimum local port number used when
connecting to the client's data port. See also ActiveMaxDataPort and User options.

AllowMagicUser
Global context only. Defines a flag that when set to yes, true, or on allows the
USER name to be optionally interpreted as user[@host[:port]] where host overrides
the DestinationAddress and port the DestinationPort directive below. It should only
be activated with "trusted" users, like in an outgoing FTP proxy scenario. See also
the UserMagicChar and ForceMagicUser options.

AllowTransProxy
Global context only. Defines a flag that when set to yes, true, or on allows one
to use the proxy as transparent proxy for outgoing ftp. To get it working you also
have to redirect client requests on a gateway or firewall host (i.e. via ipchains)
to the ftp-proxy. It should only be activated with "trusted" users, like in an
outgoing FTP proxy scenario. You can combine this with the AllowMagicUser option.

DenyMessage
Global context only. Defines the name of a file which prevents any successful
login if it exists, even if it is empty. The file contents will be sent to the
client, each line prefixed with '421-' and with variable substitution applied. The
whole file is followed by a line starting with '421 ' followed by the DenyString
below. After sending the connection is closed. If no such file exists, the deny
mechanism is not triggered altogether. See also DenyString option.

DenyString
Global context only. Defines a string that will be displayed to clients, prefixed
with '421 ' and variable substitution applied, if and only if a DenyMessage file
exists. The default is 'Service not available'. See also DenyMessage option.

DestinationAddress
Both user and global context. Defines where to redirect incoming FTP traffic. Can
be given as either dotted decimal IP address or as DNS host name. Please note that
the global section must always contain this option as a basic sanity check.

DestinationMaxPort
Both user and global context. Defines the maximum local port number to be used
when opening a connection to the FTP server. Valid both for control and for data
connections. Defaults to not binding prior to connecting and listening, so that
the system selects an arbitrary ephemeral port. See also DestinationMinPort
option.

DestinationMinPort
Both user and global context. Defines the minimum local port number to be used
when opening a connection to the FTP server. See also DestinationMaxPort option.

DestinationPort
Both user and global context. Defines the FTP server's control port where the
proxy itself will connect. This option can either be given as a numeric value or
as the service name retrieved by getservbyname(3) and defaults to port 21, the ftp
port as per RFC 959.

DestinationTransferMode
Both user and global context. Defines the FTP transfer mode to be used from the
proxy to the server. Legal values are active, passive, or client. The latter
means to follow the mode the client is using. The default value is client.

FailResetsPasv
Global context only. Defines the action that is taken when a data transfer command
is failed on the server side. If the option is set to yes, true, or on the client
data transfer socket will be closed and the transfer mode set to the default
(active-ftp).
If this flag is set to no, false, or off (which is also the default) the socket can
be reused for the next data transfer command in passive mode. This options is a
workaround for Netscape (4.x) clients, that sends a second data transfer command if
the first is failed, while the user clicks on a symbolic link pointing to a
directory.
Note, that this behavior may break the RFC definitions.

ForceMagicUser
Global context only. Same as AllowMagicUser, but makes the host and port portion
mandatory.

ForkLimit
Global context only. Limits the number of incoming client connections per minute in
daemon mode - it defaults to 40 connections per minute.

Group Global context only. Defines the UNIX style group ID which is set by the process
before it serves clients. Default is to keep the current real group ID.

LDAPAuthDN
Global context only. Defines a different base distinguished name that is used when
accessing an LDAP directory for user authentication purposes. It defaults to the
value of LDAPBaseDN. See also LDAPAuthPWAttr, LDAPAuthPWType, LDAPAuthOKFlag,
UserAuthType, LDAPBindDN options.

LDAPAuthOKFlag
Global context only. Defines an attribute and its value as attr=value string, i.e.
userEnabled=yes, that will be checked while user authentication in the directory
tree specified using LDAPAuthDN or LDAPBaseDN. Defaults to an empty string - no
flag check used.

LDAPAuthPWAttr
Global context only. Defines the LDAP password attribute name used for user
authentication.
A common used attribute name is userPassword. Defaults to an empty string -
password authentication disabled. See also LDAPAuthPWType option.

LDAPAuthPWType
Global context only. Defines the LDAP password type / format and a minimal allowed
password length expected as value for attribute name specified using
LDAPAuthPWAttr.

Valid values are plain, crypt, {crypt} followed by one number 0-9, i.e. {crypt}7,
plain9 or plain.

If no minimum length specified the default minimum length of 5 characters is used.

A password type {crypt} means, the password value in the LDAP directory is prefixed
by the {crypt} scheme specification. Other password schemes, i.e. MD5, are not
supported at the moment.
Crypted passwords are only available, if the proxy is compiled with crypt support -
see also --with-crypt compile time option in configure script.

If the password (without scheme prefix) stored in LDAP directory is * or ! the
account is disabled and the authentication fails.

Defaults to plain (equivalent to plain5). See also the LDAPAuthOKFlag.

LDAPBaseDN
Global context only. Defines the base distinguished name that is used when
accessing an LDAP directory, i.e. the root of the tree containing the FTP-Proxy
entries. Defaults to an empty string. If UserAuthMagic is used, the authuser is
used as user name for authentication and user profiles, otherwise the normal ftp-
user name. See also LDAPIdentifier, LDAPObjectClass, LDAPServer, UserAuthMagic
options.

LDAPBindDN
Defines the distinguished name that is used to (simple) bind the directory service.
Defaults to an empty string (anonymous bind). It is allowed to include one %s in
this string, that will be replaced with the FTP username or authuser if
UserAuthMagic is used. See also UserAuthMagic, LDAPAuthDN, LDAPBindPW options.

LDAPBindPW
Defines the credential (password) that is used to (simple) bind the directory
service using distinguished name given in the LDAPBindDN option. Defaults to an
empty string (anonymous bind).

LDAPIdentifier
Global context only. Defines the identification attribute for the access to the
LDAP directory. This can be thought of as the primary key and defaults to the
string CN which is short for "Common Name." See also LDAPBaseDN, LDAPObjectClass,
LDAPServer options.

LDAPObjectClass
Global context only. Defines the LDAP object class which holds the entries for the
FTP-Proxy access control. It is assumed that the possible user specific config
options exist as attributes within a record of this type. There is no default, but
a value of FTPProxyUser is recommended. See also LDAPBaseDN, LDAPIdentifier,
LDAPServer options.

LDAPServer
Global context only. This is the main option for using an LDAP directory for
retrieving user specific values. If given, it denotes the server (and possible
port separated by a colon) where FTP-Proxy will ask for the attributes. The
program will bind as the anonymous user and try to retrieve the values from the
tree rooted at LDAPBaseDN, having an object class of LDAPObjectClass and identified
by the LDAPIdentifier. If the server cannot be reached, the program aborts. If
the user cannot be found, the program falls back to the configuration file, but
will query only the global values and not the user specific ones. See also
LDAPBaseDN, LDAPBindDN, LDAPIdentifier, LDAPObjectClass options.

LDAPVersion
Global context only. Use this option to set the LDAP API version, the proxy should
set: 2 or 3. Use 0 to skip explicit version setting and use library defaults.
Defaults is version 3 if supported by the library or 2 if not.
Note: OpenLDAP 2.x library defaults to version 2 bind, but the OpenLDAP server
refuses LDAPv2 bind by default.

Listen Global context only. Defines the address where the proxy itself opens the
listening port. The default is 0.0.0.0 which instructs the server to bind to any
address. See also Port option.

LogDestination
Global context only. Defines the destination of the logging information the
program wishes to emit. If the value starts with a slash (/) it will be
interpreted as an absolute path. This file will be created and kept open during
the lifetime of the process. The signal SIGUSR1 can be sent to the (daemon)
process in order to rotate this log file.

A second way to provide logging is via a pipe and is employed when the first
character of the option is a pipe symbol (|). In this case the rest of the value
is interpreted as the name of a UNIX command which is invoked and receives logging
information on its standard input.

The third way is to use the syslog(3) service which is assumed for all other
values. The option value is interpreted as the syslog facility while the severity
is defined by the various messages themselves.

LogLevel
Global context only. Defines the maximal level of logged messages. The levels are,
in order of decreasing importance: FLT, ERR, WRN, INF, DBG
The default level is INF. A LogLevel set to WRN causes, that only messages with
levels FLT, ERR, WRN will be logged.

MaxClients
Global context only. Defines the maximum number of clients the proxy will allow
concurrently. The valid range for this option is 1 to 512, with a default of 64.
See also MaxClientsMessage, MaxClientsString options.

MaxClientsMessage
Global context only. Defines the name of a file that is displayed to clients if
their maximum number defined with MaxClients has been exceeded. If no such file
exists only the MaxClientsString is displayed, else both the file and the string
are transmitted. After transmission the connection is terminated in any case.
When sending the file, each line is prefixed with '421-' and variable substitution
is applied to it. See also MaxClients, MaxClientsString options.

MaxClientsString
Global context only. Defines a string that will be displayed to clients, prefixed
with '421 ' and variable substitution applied, if the maximum client number has
been exceeded. The default is 'Service not available' . See also MaxClients,
MaxClientsMessage options.

MaxRecvBufSize
Global context only. Defines the maximum number of bytes read from socket at once
while data transfers. Default is to read all data as reported by the kernel.
It may be useful to set a limit (i.e. to 8192), if your proxy machine uses two
interfaces of different speed, i.e. the clients are accessing the proxy via a high-
speed interface (i.e. Fast-Ethernet) and the proxy is accessing servers using a
slower one (i.e. modem, ISDN link) and your ftp-clients aborts the data transfers
because of a timeout.

PassiveMaxDataPort
Both user and global context. Defines the maximum local port number used when
listening for the client's data connection. This is the port number transmitted to
the client in a 227 response to the PASV command. If either minimum or maximum
value is not given, the program defaults to let the system choose an arbitrary
ephemeral port. See also PassiveMinDataPort option.

PassiveMinDataPort
Both user and global context. Defines the minimum local port number used when
listening for the client's data connection. See also PassiveMaxDataPort option.

PidFile
Global context only. Defines the name of a process ID file where FTP-Proxy will
store its process ID if running as daemon. The file contents will be an ASCII
string with a trailing newline. On many operating systems such PID files will be
located in the /var/run directory.

Port Global context only. Defines the listening port where the FTP-Proxy offers its
service. The port can be given as a number or as a string suitable for retrieval
by the getservbyname(3) function. It defaults to port 21, the ftp port as per RFC
959. See also Listen option.

PortResetsPasv
Global context only. Defines the action that is taken when a PORT command is
received while a passive port is open for listening. If the option is set to yes,
true, or on, (which is also the default) the socket will be closed and the passive
mode will be terminated (set to active-ftp). Setting the option to no, false, or
off does not cancel the listen. This flag seems necessary because the RFC is not
really clear enough about the correct handling.

SameAddress
Both user and global context. Defines a boolean value which determines if the
proxy is allowed to be included in so-called third party server to server
transfers. In this situation the client first sends a PASV command to one server,
then a PORT command with the response code to the second server, and then initiates
the transfer with mutual transfer commands on the two servers. Specifying this
option as no, false, or off allows FTP-Proxy to take part in such a transfer, while
saying yes, true, or on (the default) will enforce that transfers can only take
place to/from the client itself.

ServerRoot
Defines the directory into which the FTP-Proxy performs a chroot(2) in order to
increase its security level. See also the User and Group options.

Note, that you have to copy needed libraries, configuration files, etc into this
directory first!

ServerType
Global context only. Defines the mode in which the FTP-Proxy is running if no
command line switch (-d/-i) has been provided. The option value can either be
inetd in which case the proxy expects the client to be available at standard input
and output, or it can be standalone which means the process will become a daemon,
open the listening port and fork child processes for all future connections. The
child processes themselves will behave exactly as if they were started from inetd.

SockBindRand
Global context only. Defines a flag that when set to yes, true, or on , causes the
proxy to use a random port in the specified range via DestinationMinPort/MaxPort,
ActiveMinPort/MaxDataPort, PassiveMinDataPort/MaxDataPort instead of increment the
port number inside of this range. See also DestinationMinPort, DestinationMaxPort,
PassiveMinDataPort, PassiveMaxDataPort, ActiveMinPort, ActiveMaxPort options.

TCPWrapper
Global context only. Defines a boolean value which is evaluated by the FTP-Proxy
running as a standalone daemon only. Saying yes, true, or on activate the TCP
Wrapper library, whereas no, false, or off (the default) disable the function. See
also TCPWrapperName option.

TCPWrapperName
Global context only. Use given name for TCP-Wrapper checks instead of the program
name (argv[0]). See also TCPWrapper option.

TimeOut
Both user and global context. Defines the time in seconds after which a client is
assumed to be disconnected. If no activity is detected from the client after this
time, the connection is closed and the process terminates. Default value is 900
seconds.

TranslatedAddress
Global context only. Defines an IP address the server will use in 227 replies to
PASV commands instead of its own address. Usually the address where the client
connected to is taken, but this may not be appropriate in situations where an NAT
(Network Address Translation) device is located in the way from the client to the
proxy. In this situation the response can be changed to include the input address
of the NAT device.

The value for this option can be given as a DNS host name, as a dotted decimal IP
address, or as a file name. The latter is assumed when the name starts with a
slash. The file is opened and scanned for the desired address. Blank lines or
lines starting with '#' are ignored. Reading the address from a file may be useful
for environments with masquerading and dynamic PPP connections.

User Global context only. Defines the UNIX style user ID which is given to the process
before it serves clients. Default is to keep the current real user ID.

If the proxy does not run as a privileged user (root, user ID 0), it has no
permission to bind a socket to port < 1024 or to preform a chroot(2) call. See
also ActiveMinDataPort, ActiveMaxDataPort, ServerRoot options.

UserMagicChar or UseMagicChar
Global context only. Defines the character to use as separator between user and
host[:port] in the target setting of AllowMagicUser Default is the '@' character.
This allows you to use E-Mail addresses as usernames for login to the ftp server
(i.e. me@mydomain%ftp.server:21 if you set it to %).

UserAuthMagic
Global context only. This is an authentication extension like AllowMagicUser,
allowing encoding of additional username and password in the USER and PASS commands
for authentication. Valid values are @auth for ftpuser@authuser[@host:port] and
ftppass@authpass or auth@ for authuser@[ftpuser@host:port] and authpass@ftppass.
See also LDAPBindDN, LDAPAuthType and AllowMagicUser.

UserAuthType
Global context only. Defines the authentication mechanism the proxy should use.
Currently "ldap" is implemented to support simple LDAP authentication using FTP
username and password from USER and PASS commands or the special authuser and
authpass encoded using UserAuthMagic. See also LDAPBindDN, LDAPAuthDN,
LDAPAuthPWAttr, LDAPAuthPWType, LDAPAuthOKFlag and UserAuthMagic options.

UserNameRule
Global context only. Defines a regular expression rule for validation of the user
name (used for profile-setup and authentication purposes). Defaults to:

^[[:alnum:]]+([%20@/\._-][[:alnum:]]+)*$

It checks, if the first character is alphanumeric, optionally followed by @/_-. or
alphanumeric characters and ending with an alphanumeric one.

This matches the usual cases inclusive E-Mail addresses and "domain/user" names.

If regex support is not available, above default rule is still used and the option
ignored. See also ValidCommands option for regex encoding description.

ValidCommands
Both user and global context. Defines the list of allowed FTP commands for the
client. If this option is not installed, there will be no restriction on the
allowed commands. But if it is given, then all commands not on this list will be
denied. The list is space separated and may consist of the following commands:
USER, PASS, ACCT, CWD, CDUP, SMNT, QUIT, REIN, PORT, PASV, TYPE, STRU, MODE, RETR,
STOR, STOU, APPE, ALLO, REST, RNFR, RNTO, ABOR, DELE, RMD, MKD, PWD, LIST, NLST,
SITE, SYST, STAT, HELP, NOOP, SIZE, MDTM, MLFL, MAIL, MSND, MSOM, MSAM, MRSQ, MRCP,
XCWD, XMKD, XRMD, XPWD, XCUP, AUTH, APSV, EPRT, and EPSV.

Each command can be followed by an optional equals sign and POSIX 1003.2 Extended
Regular Expression (RE) that describes the valid argument(s) for the command. If
the whole string is to be matched, the pattern has to start with a caret (^) and
end with a dollar ($). If no pattern follows a command, its arguments are not
checked. An example for a name would be the pattern '^[a-zA-Z0-9]{1,512}$' for an
argument that is mandatory and may consist of up to 512 letters or digits only. A
command that does not allow any arguments can also easily be represented: 'QUIT=^$'
.

Please note that the regular expression is "pre-processed". This means that a
pattern in the form %xx will be interpreted as a hexadecimal constant and will be
replaced by the value of that constant. This looks a bit like HTML and helps to
include characters that might not be handled as expected, like %20 for space or %5c
(equivalent to %5C) for backslash. The space is especially important because it is
the separator for the commands within the list itself.

Please note also that regular expression support must have been enabled with the
--with-regex switch during the configure compilation step of the whole package.

WelcomeMessage
Global context only. Defines the name of a file that will be displayed to all
clients as the first action when they open the control connection. Each line is
prefixed with '220-' and variable substitution is applied to it. If no such file
exists it is silently ignored. See also WelcomeString option.

WelcomeString
Global context only. Defines the string that is sent to the client in order to
start login negotiation. The string is prefixed with '220 ' and variable
substitution is applied to it. If this option is not given it defaults to the
following string:
'%h FTP server (%v - %b) ready'.
See also WelcomeMessage option.

FILES

       /etc/proxy-suite/ftp-proxy.conf
       /usr/sbin/ftp-proxy

AUTHORS

       Jens-Gero Boehm <jens-gero.boehm@suse.de>
       Pieter Hollants <pieter.hollants@suse.de>
       Volker Wiegand <volker.wiegand@suse.de>
       Marius Tomaschewski <mt@suse.de>

COPYRIGHT

       The SuSE Proxy-Suite is released under the
       GNU General Public License (GPL).