+subject: ftp.server - FTP server
ftp.server(1) System General Commands Manual ftp.server(1)
NAME
ftp.server - FTP server
SYNOPSIS
ftp.server [options]
DESCRIPTION
is an FTP server for a subset of the file tranfer protocol described in
RFC 959. It behaves to some extent like a normal FTP server and can usu-
allay be used as a drop-in replacement to the system's standard FTP
server.
Additional features like access control, command control and SITE com-
mands may be added by external programs (e.g. shell scripts) See below
for more information.
After a user has succesfully logged in the user's passwd entry is used
for setting up the user's uid and gid, his home directory and (if set)
the virtual root. These setting can be changed with the -u, -q and -r
options.
Blanks in FTP command parameters are not supported by default, only the
characters up to the first blank are taken as argument, the remainder is
ignored. This behaviour can be changed with the -b option.
The `LIST' command does not accept options like .e.g `ls -lR', even if
the -b option is given and only the wildcard characters `*' and `?' are
supported. This is because the server uses a simple internal replacement
for the external ls command.
Anonymous Access
ftp.server allows anonymous access with the login names `ftp' or `anony-
mous' if the allow-anonymous option is set. By default the local system
account `ftp' is used for the user session configuration (user/group id
and directories). A different account can be specified with the anony-
mous-user option. Anonymous sessions are read-only unless the anonymous-
writes option is set to yes. In this case normal file permissions apply.
Password Free Accounts
A list of usernames that can login with giving a password can be given
with the nopwlist configuration option. In contrast to anonymous users,
password free accounts require that the login name exists as local user
account. With the nopwuser option a different user account can be set
for all password free sessions.
Root Directory
ftp.server implements two types of root directories (areas which cannot
be left be the client).
The first is set with the rootdir (or path) option. In this mode
ftp.server keeps track that the client does not access any file outside
the given virtual root directory and the virtual root itself appears as
`/' to the client. The virtual root may be left by following symbolic
links. If ftp.server detects that the client is outside the given vir-
tual root (by changing the directory) it will terminate the session imme-
diately. It's however possible to access files outside the root area
from within.
The other method of setting a session specific root directory is the
chroot option. In this mode ftp.server will do a chroot(2) to the given
directory during the session setup sequence. Files outside this
chroot'ed area are then not accessable (but notice here that hardlinks
may again give access to files and directories outside the chroot'ed
area).
In chroot mode almost all configured files and directories have to exist
inside the chroot'ed area. The only exceptions are statdir and xferlog.
These pathnames are relative to the real system's root directory.
Notice that ftp.server can make use of external helper programs which
rely on the availability of certain operating system components (e.g.
libraries). Setting up such a complete chroot'ed environment is possible
but difficult and not covered here. If running a chroot'ed environment
it should contain the files passwd (GECOS field, user shell and home
directory may be emptied) and group (group memberships may be cleared) in
the /etc directory so that ftp.server can read them for directory list-
ings.
Services
ftp.server can export different filesystem areas (FTP services) in dif-
ferent configurations. Each service must be configured in ftp.server's
configuration file with a section starting with [service] (see Configura-
tion File below). The user can select a service during the login by pre-
fixing his login name with the service name in the form service/username.
The configuration file may also have a section named `.' which is read in
case the user does not select a particular service.
Session Setup
The detailed FTP session setup sequence is as follows.
1. Read the configuration file and command line options in the given
order.
2. If ftp.server runs in daemon mode it binds to the given port and
waits for incoming requests.
3. Get the client's IP number and name.
4. Get the interface address on which the client is connected. If an
interface list is given, check if the connected interface is on that
list and, if not, drop the connection without an error message.
5. Read the optional configuration section from the configuration file.
6. Send the 220 login prompt and read the login name from the client.
7. If the client's login name contains the name of a particular ser-
vice, read it's configuration section, terminate if no such section
is available. Otherwise read additional configuration from the sec-
tion named `.' (this section is optional). Configuration sections
requires the presence of a configuration file.
8. Check the login name against the denylist, if the user is on the
list drop the connection with 530.
9. If the user is on the nopwlist assume the user as authenticated,
otherwise read the password.
10. If a valid-users list is given and the login name is on that list,
deny access with 530.
11. If a statdir and a non-zero mspc-count is given, check the client's
session limit. If the current session is above the limit, terminate
with 421.
12. If configured, open the xferlog and the statfile.
13. Run the access control program if one is configured.
14. Select the local system account:
o If the login is password free choose either the configured nop-
wuser or the login name.
o If the login name is either `ftp' or `anonymous' check if anony-
mous logins are allowed (allow-anonymous option), drop with 530
if not. Otherwise use either `ftp' or the configured anonymous-
user username.
o If the user is already authenticated by the access control pro-
gram (acp-authenticates) do nothing, else check the given user-
name and password.
15. Read the user's passwd entry. Drop the connection with 530 if no
system account exists.
16. Translate the configured chroot directory (if set) and virtual root.
If a virtual root directory is given but no home directory the vir-
tual root is used as home directory. Otherwise the configured home
directory parameter is translated.
17. Read the mapfile if given.
18. If a chroot directory is configured, go there and make it the new
root directory.
19. Choose either the configured home directory (home option) or the
user's home directory from the system's passwd as session start
directory and change to it.
20. Update the virtual root directory if it's `.' or the session's home
directory contains the sequence `/./'. Otherwise check that the
session's home directory is inside the virtual root.
21. Set the supplementary groups from /etc/group. If a chroot'ed envi-
ronment is in effect, the /etc/group from inside the chroot'ed area
is used.
22. Set the primary user and group id (read from the system's
/etc/passwd).
23. Send `230 login accepted' to the client.
Permissions
All file and directory accesses are subject to normal UNIX permission
control. These permissions can be restricted. If the readonly option is
set to `yes' (the default is `no') all modification requests are
rejected, there are no exceptions, even not for root.
If readonly is `no' and the user is on the readlist, and not on the
writelist, the user will only have read permissions. The writelist
option can be used to define exclusions for users which are for some rea-
son included in the readonly list.
- File Creation Modes
The umask can be used to set the permissions for newly created file and
directories. It's used as usual, a umask value of `022' (which is the
default) excludes write permissions for the owning group and the `other
users'.
In addition to umask the group option is used to control the owning group
of created files and directories. But notice that the owning group is
only assigned if the user is a member of that group. If this is not the
case the session will run under the user's primary group as given in the
/etc/passwd file.
- Sticky Group Bit Permission Hack
If the sgp-hack option is turned on ftp.server checks for each file or
directory that is created if the parent directory has the sticky group
bit set and if the group permissions allow read/write/search (`rwx')
access for that group. If the directory meets this conditions then the
file or directory gets automatically the group write bit set. Created
subdirectories get also the sticky-group bit and the executable bit set.
- Changing Access Modes
The user may use the SITE command (if enabled) to query or modify group
ownership and permissions. If however special modes are configured (see
above) these commands are blocked. Setting a umask parameter revokes
permissions for the SITE commands CHMOD, UMASK, ATIME and MTIME while
group disables `SITE CHGRP' and `SITE GROUP'. Turning sgp-hack on dis-
ables all of them.
External Handler
ftp.server supports external handler programs for various purposes. Han-
dlers receive their arguments in environment variables and signal success
or failure with their exit code: `0' means success, anything else fail-
ure. An external handler may return also a single line on their stderr.
If they do the line must be a valid FTP server response line (numeric
status code followed by an optional message) and the status must match
the handler's exit code. For the exit code `0' the status code must be
greater or equal than 200 and less than 400. Otherwise (non-zero exit-
code) the status code must be between 400 and 599. If the handler output
doesn't match this conditions ftp.server terminates the session with an
error message to syslog, the client receives nothing.
There are some defaults on the handler output processing.
handler exits with `0', no message line:
ftp.server provides `200 ok'.
handler exit with non-zero exit code, no message line:
ftp.server provides `421 closing connection'.
handler provides status code matching it's exit code but no message:
In this case ftp.server sets the message text to `ok' for
positive responses and `permission denied' otherwise.
Notice furthermore that if ftp.server recognises a 421 status code the
session it terminated immediately.
Additionally a handler may print a single line on it's stderr which is
written to syslog. There are not restrictions on the format of this
line.
- Environment Variables
All external handlers receive their parameter in environment variables.
Furthermore there is a common set of variables which is set for all han-
dlers.
This variable set is:
FTP_CLIENT the client's IP number.
FTP_CLIENTNAME
the client's DNS name if defined, it's ip number otherwise.
FTP_INTERFACE
the interface on which the client is connected.
FTP_HOME (*) the home directory.
FTP_PORT the server's port.
FTP_ROOTDIR (*)
the virtual root directory if set (not the chroot direc-
tory).
FTP_STARTED (*)
the number of seconds since 01.01.1970 when the server pro-
cess was started.
FTP_SERVERPID (*)
the process id of the calling ftp.server.
FTP_USERNAME the user's login name.
See below for the additional variables.
- Access Control
Access control programs (acp's) are called after the login information
has been read from the client and the user's login name was matched
against the validuser's list.
Since the acp is called at that early stage the variables from above
marked with a `(*)' are not set. An acp receives the following additio-
nanl variable:
FTP_PASSWORD the user's login password. This variable is only set if
the acp-authenticates option is set.
acp's can be used to grant or deny server access based on anything.
- Command Control
Command control program are called for the FTP commands APPE, CDUP, CWD,
DELE, LIST, NLST, MDTM, MKD, RMD, RETR, RNFR, RNTO, SITE, SIZE, STOR and
STOU (in other words, each command that wants to read or write from the
server), after the user's write permissions have been verified (if the
command requires write permissions).
FTP_COMMAND the FTP command.
FTP_FILENAME the filename part of FTP_SYSPATH.
FTP_FTPDIR the directory part of the addressed filename or directory
relative to the virtual root (if configured).
FTP_SYSDIR the directory part of FTP_SYSPATH.
FTP_SYSPATH the full pathname to the addressed file or directory rela-
tive to the system's root directory, not the virtual root.
- Unique Name Handler
The STOU unique filename handler receives the same variables as the ccp
but notice that FTP_FTPDIR and FTP_SYSDIR are not set because there is no
filename.
- Command Handler
If a command handler is configured it's called for the same FTP commands
as a ccp (with the exception of the SITE command) but after the operation
has been done.
For the commands APPE, RETR, STOR and STOU the handler is also called for
some additional events, receiving a pseudo FTP command name: `+cmd' for
successful data transfers and `cmd-' in case the transfer was aborted.
Furthermore the command handler is called with FTP_COMMAND set to +LOGIN
after a successful login and +QUIT after the user quitted. Notice that
the +QUIT call is not reliable since the server might terminate other-
wise.
- External Site Handler
The external SITE handler is called with the environment variables as
ccps and additionally
FTP_ARG the SITE command argument.
FTP_ARGV the SITE command argument as akanga(1) list.
The site handler is not bound to the output restrictions (exitcode
matches FTP resonse) explained above. It's output (including stderr) is
send to the client `as-is' as long as it's a valid FTP response. No out-
put is translated to `500 error' and a 421 status code makes ftp.server
terminate the connection after running the SITE handler.
SITE command
ftp.server supports SITE commands with a builtin handler and an optional
external handler which may be configured with the site-handler option.
If an external handler is set it receives all SITE commands which are
unknown to then internal handler, see External Handler for details.
The SITE commands are
ATIME timestamp path
sets the last access time of path to timestamp which must
be of the form YYYYMMDDHHMMSS.
CHMOD mode path
changes the access permissions of path to mode which is
expected to be an octal value.
CHOWN owner path
changes the owner of path to owner.
GROUP groupname
makes groupname the new primary group. The logged in user
must be a member of groupname.
GROUPS lists all groups in which the logged in user is a member
and can change to with the GROUP command.
MTIME timestamp path
sets the last modification time of path to timestamp. See
ATIME for timestamps's format.
Note: Setting a path's last modification time with the nor-
mal (non-SITE) MTIME command is not supported.
STAT path returns path's type (which may be `file' or `dir'), access
mode (as octal number), owning user and group, last modifi-
cation and last access time, filesize and path as blank
separated list in the FTP status response.
UMASK mode sets the session's umask to mode which is expected to be an
octal value.
All of the operations above are subject to the usual UNIX permission
checking, e.g. CHOWN is only possible if the user is logged in as root.
The SITE command itself requires that the user has write permissions on
the FTP server. Furthermore the use of SITE commands may be denied by
permission or group configuration options, see Permissions.
Configuration File
ftp.server may use a configuration file. This file may contain blanks
lines and comments (line starting with a hash mark `#'). All other lines
are expected to be of the form
option value
value must be of one of the following types:
boolean can be yes or no, usually the default value for a boolean
option is no.
number a non-negative decimal number.
string a string, any sequence of characters, including white
space.
list a white-space and/or comma separated of string (which can
neither contain white-space nor commas).
pathlist Parameters with a list type are processed the following way
before using them: For each list item ftp.server replaces
escape sequences (see FILENAME REMAPPING) in that item and
checks then if it refers to an existing file or directory.
If yes, list processing stops and this pathname is used as
configuration value. Otherwise ftp.server tries the next
list item until the last one is reached which is used any-
way.
userlist specifies a white-space and/or comma separated list of
usernames, numeric user ids, system group names (a name
starting with a `@') or user id range (numeric id prefixed
with either `<' or `>' which adds all ids less or greater
than the given id) or a star `*' to add all users by
default.
Furthermore, each list item may be prefixed with a minus
`-' to exclude the item from the list.
ftp.server interprets the items with the following decreas-
ing precedence: username, groupname, '<' and '>' ranges,
star `*'. To add e.g. all users but `root' and `ftp' to a
user list
denylist *, -root, -ftp
or
denylist -root, -ftp, *
could be used.
Every configuration option must have a value, ftp.server terminates with
an error if it finds one without. To clear a string type (or list, path-
list or userlist etc.) option a dash `-' must be given as `magic value'.
The following options are recognized.
acp string sets the path to the access control program.
acp-auth boolean
if set to yes ftp.server does not check the user login.
Instead it relies on the acp's exit code.
allow-anon boolean
if set to yes anonymous server logins using either `anony-
mous' or `ftp' as login name without a valid password are
allowed.
allow-anyremote boolean
if set to yes the client may give any address for data
transfers. Setting this option to yes is required for FXP.
allow-blanks boolean
if set to yes ftp.server accepts blanks in filenames.
anon-user string
defines which local user id is used for anonymous sessions.
ccp string sets the path to the command control program.
chroot pathlist
set's the directory to which ftp.server changes it's root
directory after a succesful login.
debug boolean
turns debug mode on if set to yes.
denylist userlist
defines a list of users for which logins are refused before
asking for a password.
handler string
sets the path to ftp.server's command handler.
homedir pathlist
sets a global home directory which is applied to every
user.
group string defines a group which should be assigned as primary group
for the session. This is only possible if the login user
is a member of the given group. In the case that he's not
the session runs under the user's primary group.
ignore-anyremote boolean
if allow-anyremote is set to yes and the client uses FXP
ftp.server writes a message to syslog about this. Setting
ignore-anyremote to yes suppresses this.
interface list
specifies the list of interfaces on which ftp.server should
accept requests.
internal-site list
defines which SITE commands ftp.server should handle inter-
nally. A star `*' enables all.
mapfile pathlist
sets the mapfile (see FILENAME REMAPPING).
message string
sets the name of the message file which is automatically
displayed if a user changes into a directory when the mes-
sage file exists. The message file is displayed as part of
the CWD FTP response.
mspc-count number
sets the maximum number of parallel session which are
allowed for a single client.
mspu-count number
set the maximum number of parallel session which are
allowed for a single user.
nopwlist userlist
defines which users can login without a password.
nopwuser string
even users on the nopwlist need an account on the FTP
server. If nopwuser is set ftp.server uses the given user-
name for all no-password user logins.
path pathlist
a synonym for rootdir.
readlist userlist
defines which user receive only read permissions, even if
the FTP server if writeable.
readonly boolean
if readonly is set to yes the FTP server space is read-only
for all users, no exceptions. The default is no.
rootdir pathlist
sets a virtual root directory.
sgp-hack boolean
turns ftp.server's sgp hack on.
site-handler string
sets the path to ftp.server's SITE command handler.
statdir string
sets the path to ftp.server's directory where it writes
it's current session state. This directory should be
`chmod 1777'.
timeout number
sets the session timout in seconds.
uname-handler string
defines ftp.server's STOU handler. Without an uname han-
dler ftp.server rejects STOU command requests.
umask octal-number
sets ftp.server's UMASK.
user string|number.number
sets the user id under which all session run. The first
form read uid and gid from the system's passwd file while
the second gives the values numerically. If this option is
not set the sessions run with the login's user id and
groups.
varname string
sets a different environment variable prefix than the
default `FTP_'.
writeable boolean
is the opposite of readonly, it's default is yes.
writelist userlist
if the FTP server is writeable the writelist assigns write
permissions to users which are also included on the read-
list.
xferlog string
defines where ftp.server should write it's transfer logs.
ftp.server terminates with an error message if an unknown configuration
option is found.
- Configuration Sections
The configuration file may contain sections for different filesystem
areas (FTP services) or interfaces. For an interface-specific configura-
tion the section's name is the IP-number of the interface an for a ser-
vice the service's name. They are read as soon as the corresponding
information is available. Interface-specific sections are optional, ser-
vice-specific sections not (the default section `.' is an exception).
A section starts with a line beginning with a `[' followed by the sec-
tion's name followed by a `]' and end with the start of the next section.
If sections are present, the global configuration ends at the first sec-
tion.
Filename Remapping
ftp.server can optionally use a mapfile for request rewriting. If a map-
file is given, ftp.server will match all FTP command file- and directory
names against the given pattern list and take the processed output of the
rule processor as command argument.
This mapfile is mostly compatible to in.tftpd(8)'s mapfile but is has
some additional features.
Each non blank line in the mapfile is expected to have at least two
whitespace (blanks and tabs) separated fields which are operation and
regular expression. Comments may appear anywhere in a line, starting
with a hash mark `#'. If this character should be part of the rule data
it must be quoted, just as whitespace, with a backslash '\'.
Each rule operation is made out of one or more operation flags. Valid
operation flag characters are
r This is replace rule. The third field of the line is the
substitution string (see below).
g global replace: The replace rule is applied until it no
longer matches.
i ignore case: The match pattern is used case insensitive.
e End rule processing if this rule matches.
s restart: After processing this rule restart processing the
whole mapfile.
a deny access: If this rule matches, rule prcessing stops
immediately and the access is denied.
G This rule applies only to read requests.
L This rule applies only to list requests.
P This rule applies only to write requests.
These operation flags can (and must) be combined into the rule operation.
Each set of rule flags must contain either an r or a. Otherwise
ftp.server terminates with an error. ftp.server terminates also on regex
compilation errors.
- Substitution
If the rule is a substitution rule ftp.server expects a third rule field
containing the substitution string. This string may contain escape
sequences of the form `\char' where char is one of:
0 inserts the whole string.
1 to 9 inserts the n-th `\(' `\)' parentesized subexpression
i inserts the client's IP-number (e.g. 192.168.1.8).
u inserts the user's login name.
x inserts the client's IP-number in hexadecimal notation
(e.g. C0A80108).
# inserts a literal hash mark `#'.
Use `\\' to include a single backslash `\' in the sustitution string.
- Matching and Virtual Root
If ftp.server is configured to work with a virtual root directory the
mapfile patterns and substitutions are relative to that virtual root
directory. It is not required (and in fact it's wrong) to include the
virtual root in either argument.
- Path Translation
ftp.server allows some configuration parameters to be comma separated
lists. If a parameter is a list ftp.server, applies some substitution to
each list member. For each substituted value it checks then if it refers
to either a file or directory and stop further list processing if yes,
using this value as configuration parameter. The supported substitution
sequences here are i, u and x, or in other words, those sequences that
are not related to a previous match.
OPTIONS
-a acp specifies an access control program that grants or denies
access to the ftp.server after the user has been authenti-
cated.
-b allow blanks in command arguments.
-c ccp sets the command control program that grants or denies the
usage of FTP commands.
-d debug mode: client-server conversation is printed to
stderr, in daemon mode ftp.server will not fork into back-
ground.
-e this option accepts (and logs) data connection peers to be
different from the control connection peer. This is
required for FXP. Giving -e twice switches logging of
suche events off.
-f filename read configuration option from filename.
-h handler sets the FTP command handler program.
-m umask specifies the umask value.
-n unamehandler
sets the path to the uname handler program. This is
required for STOU to work.
-o mapfile specifies the mapfile to use.
-p turns the sticky-group-permission hack on.
-q directory specifies a global home directory that is used for all FTP
sessions.
-r directory set's the virtual root directory. If the directory is `.'
the user's home directory becomes his virtual root.
-s sitehandler
specifies the program that handles SITE commands.
-t timeout specifies a different FTP timeout in seconds than the
default of 3600 (1 hour).
-u username | -u [userid][.groupid]
specifies a user (either by name or numerical id) under
which the server runs after the client has been authenti-
cated. ftp.server must be started as root for this to
work.
-v prefix sets prefix as the variable prefix for the environment
variables instead of the default FTP_.
-w userlist defines usernames for which server access is denied.
-y | -yy username
allows anonymous access with either `ftp' or `anonymous' as
login name and any password.
-D | -DD port
tells ftp.server to run as daemon. If -D is given twice
ftp.server expects the server port number.
May 08, 2004
