Provided by: ftp-proxy_1.9.2.4-8_amd64 bug

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