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
SEE ALSO¶
ftp-proxy(8)
The
SuSE Proxy-Suite documentation included in the
doc
subdirectory of the package.
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).