FTPCONFIG(5) BSD Programmer's Manual FTPCONFIG(5)NAMEftpconfig - ftpd configuration file
SYNOPSIS
/etc/ftpd/config
DESCRIPTION
The /etc/ftpd/config file contains the configuration parameters for use
by the ftpd(8) daemon. It consists of lines which contain a parameter
and its value:
parameter value
(Except where noted below.)
Comments are denoted by the `#' character and any text following a `#' is
ignored. Some parameters may be specified differently for guest sessions
(anonymous ftp) and normal user sessions. All parameters may be speci-
fied per virtual host. When the same parameter is specified more than
once, the final setting found will be used.
Guest Sessions
To specify parameters which are to be applied for guest sessions they
must be within a guest block. A guest block is started with the line:
<Guest>
and concludes with:
</Guest>
There may be multiple guest blocks.
Virtual Hosts
A virtual host is defined by a line of the form:
<VirtualHost hostname>
All parameters specified following this line are specific to the virtual
host hostname. A virtual host definition is concluded with:
</VirtualHost>
Multiple definitions for the same hostname are allowed and are all merged
together. Note that only the first Internet address found for hostname
will be listened to. Guest blocks may be contained in a virtual host
definition, but virtual host definitions may not be nested.
A virtual host starts with a copy of the global values so all global val-
ues must be specified prior to defining any virtual hosts. Specifing a
global value after a virtual host has been defined produces an error.
Parameters
There are four types of parameters:
o Variables which contain values, such as pathnames, hostnames, or num-
bers. These may not appear within a guest block, but may be virtual
host specific.
o Flags which determine availability of certain features. These may
both appear in a guest block and be virtual host specific.
o Commands to disable (or enable). These make specific FTP commands
appear to be unimplemented. They may be within a guest block as well
as virtual host specific.
o Incoming (upload) directory definitions. These only apply to guest
sessions.
Variables
The following variables may be set:
AnonymousDir The directory to which guest sessions initially are
chdir(1)'d and limited to. This defaults to the home
directory of AnonymousUser.
AnonymousUser The account name which implies guest sessions. By de-
fault this is the account ``ftp''.
BannedUserList A filename containing users or groups that are not al-
lowed to use FTP. Groups are denoted by a leading `@'.
This defaults to /etc/ftpd/banned.
ChrootUserList A filename containing users or groups that will be ch-
rooted to their home directory. Groups are denoted by a
leading `@'. This defaults to /etc/ftpd/chroot.
GroupFile Specifies a filename which contains a mapping of ftp
group names (specified with SITE GROUP) to real group
names. The file also contains the encrypted password
(see passwd(5)) needed for access to the group. the syn-
tax of:
groupname:password:realgroup
where groupname is the name specified to the SITE GROUP
command, password is the encrypted version of the pass-
word supplied to the SITE GPASS command, and realgroup is
the group name in the /etc/group file that this group is
mapped to. Specifying a group by SITE GROUP and SITE
GPASS gives the user access to files readable to
realgroup.
LogFormat Specify the format to be used in the statistics file.
This format string is similar to a printf(3) format
string with the exception that the conversions must be
one of the following:
{time} The 20 character string representing the
current time. (e.g., ``Jan 5 10:02:41
1998'').
{duration} The duration of the transfer, in seconds.
{remote} The remote host names.
{size} The number of bytes transfered.
{path} The pathname retrieved or stored.
{type} The type of transfer, `a' for ASCII and `b'
for binary.
{action} For compatability with wu-ftpd. This cur-
rently always is always printed as `_'.
{direction} The direction of the transfer, `i' for in-
coming and `o' for outgoing.
{session} The type of session, `a' for guest sessions
(anonymous) and `r' for registered users.
{user} The registered user name for normal sessions
or the password provided for guest sessions.
{authtype} If UseRFC931 (see below) has been turned on
and RFC 931 authentication (ident) was suc-
cessful this is printed as `1', else it is
printed as `0'.
{authuser} If UseRFC931 (see below) has been turned on
and RFC 931 authentication (ident) was suc-
cessful this prints the authenticated name,
otherwise a `*' is printed.
The default format, which produces the same results as
wu-ftpd, is:
%{time} %{duration} %{remote} %{size} %{path} %{type}
%{action} %{direction} %{session} %{user} %{authtype}
%{authuser}
Since all white space between LogFormat and the start of
the format are stripped, a leading `\' will be stripped,
allowing the format to start with a white space.
LoginMessage Specifies a filename to display to the client after the
client has logged in to the server. Note that this is
read after the user has been chrooted so it must exist
within the chrooted environment. This defaults to
/etc/ftpd/motd.
MaxTimeout The maximum value the user may increase the idle timeout
value to. Defaults to 7200 seconds.
MaxUsers This parameter is only settable for guest sessions and
only has effect if ftpd(8) is run in daemon mode. When
set to a positive value it limits the number of guest
sessions allowed. If the current total number of ses-
sions for a particular virtual host (including both guest
and non-guest sessions) is greater than or equal to this
value then only non-guest sessions are allowed.
MessageFile This parameter is only settable for guest sessions. Af-
ter a successful CWD request, the contents of this file
are printed. The file name must not contain a `/' (that
is, it is a file name in the new directory). By default
this is ``.message''.
PathFilter This parameter is only settable for guest sessions. It
limits the file names allowed for storing or the names of
directories that may be created. The value is a series
of strings, each being a regular expression (see
re_format(7)). The first regular expression must match
the last component of the file or directory name. The
following regular expressions must not match. A common
invocation might be:
PathFilter ^[-A-Za-z0-9._]*$ ^\. ^-
This limits files to the character set of the alphanumer-
ic characters, `-', `.', and `_'. The second and third
regular expressions prohibit names that start with a `.'
or `-'.
PermittedUserList
A filename containing users or groups that are allowed to
use FTP. If the specified file exists, only users or
users in the groups listed in that file are allowed to
connect, but are still subject to rejection by the
BannedUserList file. Groups are denoted by a leading
`@'.
ServerName The name to use in the initial banner instead of the
standard hostname. For virtual hosts this defaults to
the hostname specified on the <VirtualHost ...> line.
StatFile The file to keep track of file transfer statistics. You
must also turn on the Stats flag, below. This defaults
to /var/log/ftpd/xferlog.
Timeout The inactivity timeout value, in seconds. Defaults to
900 seconds.
Umask The default umask to use for creating files. This de-
faults to 027. The user's login.conf entry may override
this value.
WelcomeMessage Specifies a filename to display to the client when they
first contact this server. This defaults to
/etc/ftpd/welcome.
The value for variable parameters is taken as is and should not be en-
closed in quotation marks. I.e., use
LoginMessage /etc/welcome
rather than
LoginMessage ``/etc/welcome''
Flags
Flags may have either the value of ``On'' or ``Off''. When inside of a
guest block the setting will only be for guest sessions. When outside of
a guest block the definition will be for both normal user sessions and
for guest sessions. (You should first set all the global settings out-
side of a guest block and then make any alterations needed within the
guest block.) The following flags are available:
AllowAnonymous Defaults to on. If turned off then guest sessions
are not allowed.
AnonymousOnly Defaults to off. If turned on then only guest ses-
sions are allowed.
BuiltinLS Defaults to on. If specified then a builtin version
of ls(1) is used rather than /bin/ls for listing
files. This allows chrooted environment (including
guest sessions) to not require a /bin or /shlib di-
rectory.
Debug Defaults to off. When turned on detailed informa-
tion about the session is sent to syslog.
ExtraLogging Defaults to off. When turned on the retrieve (get),
store (put), append, delete, make directory, remove
directory and rename operations and their filename
arguments using syslog.
KeepAlive Defaults to off. When turned on the SO_KEEPALIVE
option is turned on for all data connections. This
will cause data connections to eventually timeout if
the remote client disappears.
Logging Defaults to off. When turned on, each successful
and failed ftp(1) session is logged using syslog
with a facility of LOG_FTP.
Proxy Defaults to off for guest sessions and on for normal
sessions. When on it allows third party transfers.
This is required to be on for RFC 959 conformance.
Please see RFC 959 COMPLIANCE below.
RestrictedDataPorts Defaults to on. When on, outgoing port requests to
ports under 1024 are not allowed. This must be off
to be RFC 959 compliant. Please see RFC 959 COMPLI-
ANCE below.
Stats Defaults to off. When on, ftpd logs all transfers
to the statistics file defined above, if it already
exists. This file will not be created if it does
not already exist.
UseHighPorts Defaults to on. When on, the system uses data ports
in the range of 40000..44999. If turned off, and
the operating system supports turning it off, the
traditional range of 1024..4999 is used. This op-
tion is not needed and is ignored under BSD/OS.
UseRFC931 Defaults to off. When on, ftpd uses RFC 931 authen-
tication protocol (ident) to try and establish the
identification of the remote user. Note that this
information cannot be trusted and can only be cor-
rectly interpreted by the remote system administra-
tor.
VirtualOnly Defaults to off. When on, only requests to defined
virtual hosts are allowed.
Commands
In addition to the above parameters, individual FTP commands may be en-
abled or disabled for all sessions, or just for guest sessions. This may
be virtual host specific. By default, all implemented commands are
available to normal sessions. Guest sessions, by default, have the fol-
lowing commands disabled:
Request Description
APPE append to a file
DELE delete a file
MKD make a directory
RMD remove a directory
RNFR specify rename-from file name
RNTO specify rename-to file name
XMKD make a directory (deprecated)
XRMD remove a directory (deprecated)
SITE-UMASK change umask, e.g. ``SITE UMASK 002''
SITE-IDLE set idle-timer, e.g. ``SITE IDLE 60''
SITE-CHMOD change mode of a file, e.g. ``SITE CHMOD 755 filename''
Commands are enabled with the value ``On'' and disabled with the the val-
ue ``Off''. The complete list of commands can be found in ftpd(8). Note
that SITE commands are specified as SITE-CMD and are not as SITE CMD.
Incoming
For guest sessions, stores (uploads) are only possible into directories
that have been explicitly allowed to have stores. The Incoming directive
is used to specify a directory for stores. It must exist within a guest
block, though it can be virtual host specific.
The incoming directive takes the form:
Incoming path user group mode [dmode]
The arguments are defined as:
path The full pathname to the directory which allows stores.
This pathname is always relative to AnonymousDir. Stores
may also be made into sub-directories, up to 7 levels deep,
from this directory.
user Name of the user in the /etc/passwd file who should own all
files stored into this directory.
group Name of the group in the /etc/group file which should be
used for all files stored into this directory.
mode The octal mode bits that should be set for all files stored
into this directory. Typically this should be something
like 600 (only readable and writable by user.)
dmode If specified, the octal mode bits that should be set for
all directories created in this directory. Typically this
should be something like 733. Directories can only be cre-
ated when dmode is specified.
Typically the directory specified by path should be owned by user / group
and be mode 733 (u+rwx g+wx o+wx) or 773 (u+rwx g+rwx o+wx).
RFC 959 COMPLIANCE
Due to misconfigurations of some sites, ftpd(8) is configured by default
to try and protect against an attack against misconfigured machines.
This attack is only possible when other machines trust the ftp host for
rhosts(5) authentication and also allow connections from the ftp data
port, 20. The protection is to both disable third party transfers as
well as limit the the ports to which the FTP server is allowed to connect
to at the request of the client.
To be compliant with RFC 959 you must set the following flags:
Flag Value Description
RestrictedDataPorts Off allow PORT requests from any port
Proxy On allow third party transfers
EXAMPLE
The following sample /etc/ftpd/config file sets up two virtual hosts
(ftp.mycompany.com and ftp.yourcompany.com) and does not allow ftp ses-
sions to any other host.
#
# Turn on some standard options we desire for all servers
# BuiltinLS is required to allow listing in chrooted environments
# We keep logs and statistics
# Timeout dead connections
# We only allow virtual hosts to run
# We specify a shorter format string for the logfile
#
BuiltinLS On
Logging On
ExtraLogging On
Stats On
KeepAlive On
VirtualOnly On
LogFormat %{time} %{remote} %{user} %{direction} %{path} %{size} %{duration}
#
# Make sure we use the account "ftp" for guest sessions
# Set up for a welcome banner once they get logged in
#
AnonymousUser ftp
LoginMessage /etc/welcome
#
# These are turned off by default, but lets be
# paranoid and make sure they are off for guests.
# Also add in a filter on the path names.
#
<Guest>
APPE Off
RNFR Off
RNTO Off
DELE Off
MKD Off
XMKD Off
RMD Off
XRMD Off
SITE-UMASK Off
SITE-IDLE Off
SITE-CHMOD Off
PathFilter ^[-A-Za-z0-9._]*$ ^\. ^-
</Guest>
#
# Define mycompany's ftp server
# We have a list of users we don't want to allow
# access to our server.
#
<VirtualHost ftp.mycompany.com>
AnonymousDir /var/spool/ftp.mycompany.com
StatFile /var/log/ftpd/ftp.mycompany.com
BannedUserList /etc/ftpd/banned.mycompany.com
<Guest>
Incoming /incoming bob user 600
</Guest>
</VirtualHost>
#
# Define yourcompany's ftp server
# They have a special welcome message they want displayed.
# They also have their own ls command for guest sessions
# so we cannot use the builtin version.
# We also disable the ability of guest to store any files
#
<VirtualHost ftp.yourcompany.com>
AnonymousDir /var/spool/ftp.yourcompany.com
StatFile /var/log/ftpd/ftp.yourcompany.com
WelcomeMessage /etc/ftpd/welcome.yourcompany.com
<Guest>
BuiltinLS Off
ALLO Off
STOR Off
STOU Off
</Guest>
</VirtualHost>
SEE ALSOls(1), ftp(1), login.conf(5), ftpd(8)