ftp-proxy.conf

ftp-proxy.conf(5)                 Proxy-Suite                ftp-proxy.conf(5)



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).




SuSE                         September 20th, 1999            ftp-proxy.conf(5)