NetBSD/libexec/ftpd/ftpd.conf.5

.\"	$NetBSD: ftpd.conf.5,v 1.16 2001/06/26 19:30:45 lukem Exp $
.\"
.\" Copyright (c) 1997-2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Luke Mewburn.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 27, 2001
.Dt FTPD.CONF 5
.Os
.Sh NAME
.Nm ftpd.conf
.Nd
.Xr ftpd 8
configuration file
.Sh DESCRIPTION
The
.Nm
file specifies various configuration options for
.Xr ftpd 8
that apply once a user has authenticated their connection.
.Pp
.Nm
consists of a series of lines, each of which may contain a
configuration directive, a comment, or a blank line.
Directives that appear later in the file override settings by previous
directives.
This allows
.Sq wildcard
entries to define defaults, and then have class-specific overrides.
.Pp
A directive line has the format:
.Dl command class [arguments]
.Pp
A
.Dq \e
is the escape character; it can be used to escape the meaning of the
comment character, or if it is the last character on a line, extends
a configuration directive across multiple lines.
A
.Dq #
is the comment character, and all characters from it to the end of
line are ignored (unless it is escaped with the escape character).
.Pp
Each authenticated user is a member of a
.Em class ,
which is determined by
.Xr ftpusers 5 .
.Em class
is used to determine which
.Nm
entries apply to the user.
The following special classes exist when parsing entries in
.Nm "" :
.Bl -tag -width "chroot" -compact -offset indent
.It Sy all
Matches any class.
.It Sy none
Matches no class.
.El
.Pp
Each class has a type, which may be one of:
.Bl -tag -width "CHROOT" -offset indent
.It Sy GUEST
Guests (as per the
.Dq anonymous
and
.Dq ftp
logins).
A
.Xr chroot 2
is performed after login.
.It Sy CHROOT
.Xr chroot 2 ed
users (as per
.Xr ftpchroot 5 ) .
A
.Xr chroot 2
is performed after login.
.It Sy REAL
Normal users.
.El
.Pp
The
.Xr ftpd 8
.Sy STAT
command will return the class settings for the current user as defined by
.Nm "" .
.Pp
Each configuration line may be one of:
.Bl -tag -width 4n
.It Sy advertise Ar class Ar host
.It Sy advertize Ar class Ar host
Set the address to advertize in the response to the
.Sy PASV
and
.Sy LPSV
commands to the address for
.Ar host
(which may be either a host name or IP address).
This may be useful in some firewall configurations, although many
ftp clients may not work if the address being advertized is different
to the address that they've connected to.
If
.Ar class
is
.Dq none
or no argument is given, disable this.
.It Sy checkportcmd Ar class Op Sy off
Check the
.Sy PORT
command for validity.
The
.Sy PORT
command will fail if the IP address specified does not match the
.Tn FTP
command connection, or if the remote TCP port number is less than
.Dv IPPORT_RESERVED .
It is
.Em strongly
encouraged that this option be used, espcially for sites concerned
with potential security problems with
.Tn FTP
bounce attacks.
If
.Ar class
is
.Dq none
or
.Sy off
is given, disable this feature, otherwise enable it.
.It Sy chroot Ar class Op Sy pathformat
If
.Ar pathformat
is not given or
.Ar class
is
.Dq none ,
use the default behaviour (see below).
Otherwise,
.Ar pathformat
is parsed to create a directory to create as the root directory with
.Xr chroot 2
into upon login.
.Pp
.Ar pathformat
can contain the following escape strings:
.Bl -tag -width "Escape" -offset indent -compact
.It Sy "Escape"
.Sy Description
.It "\&%c"
Class name.
.It "\&%d"
Home directory of user.
.It "\&%u"
User name.
.It "\&%\&%"
A
.Dq \&%
character.
.El
.Pp
The default root directory is:
.Bl -tag -width "CHROOT" -offset indent -compact
.It Sy CHROOT
The user's home directory.
.It Sy GUEST
If
.Fl a Ar anondir
is given, use
.Ar anondir ,
otherwise the home directory of the
.Sq ftp
user.
.It Sy REAL
By default no
.Xr chroot 2
is performed.
.El
.It Sy classtype Ar class Ar type
Set the class type of
.Ar class
to
.Ar type 
(see above).
.It Xo Sy conversion Ar class
.Ar suffix Op Ar "type disable command"
.Xc
Define an automatic in-line file conversion.
If a file to retrieve ends in
.Ar suffix ,
and a real file (sans
.Ar suffix )
exists, then the output of
.Ar command
is returned instead of the contents of the file.
.Pp
.Bl -tag -width "disable" -offset indent
.It Ar suffix
The suffix to initiate the conversion.
.It Ar type
A list of valid filetypes for the conversion.
Valid types are:
.Sq f
(file), and
.Sq d
(directory).
.It Ar disable
The name of file that will prevent conversion if it exists.
A file name of
.Dq Pa \&.
will prevent this disabling action
(i.e., the conversion is always permitted.)
.It Ar command
The command to run for the conversion.
The first word should be the full path name
of the command, as
.Xr execv 3
is used to execute the command.
All instances of the word
.Dq %s
in
.Ar command
are replaced with the requested file (sans
.Ar suffix ) .
.El
.Pp
Conversion directives specified later in the file override earlier
conversions with the same suffix.
.It Sy display Ar class Op Ar file
If
.Ar file
is not given or
.Ar class
is
.Dq none ,
disable this.
Otherwise, each time the user enters a new directory, check if
.Ar file
exists, and if so, display its contents to the user.
Escape sequences are supported; refer to
.Sx Display file escape sequences
in
.Xr ftpd 8
for more information.
.It Sy homedir Ar class Op Sy pathformat
If
.Ar pathformat
is not given or
.Ar class
is
.Dq none ,
use the default behaviour (see below).
Otherwise,
.Ar pathformat
is parsed to create a directory to change into upon login, and to use
as the
.Sq home
directory of the user for tilde expansion in pathnames, etc.
.Ar pathformat
is parsed as per the
.Sy chroot
directive.
.Pp
The default home directory is the home directory of the user for
.Sy REAL
users, and
.Pa /
for
.Sy GUEST
and
.Sy CHROOT
users.
.It Xo Sy limit Ar class
.Ar count Op Ar file
.Xc
Limit the maximum number of concurrent connections for
.Ar class
to
.Ar count ,
with
.Sq 0
meaning unlimited connections.
If the limit is exceeded and
.Ar file
is given, display its contents to the user.
If
.Ar class
is
.Dq none
or
.Ar count
is not specified, disable this.
If
.Ar file
is a relative path, it will be searched for in
.Pa /etc
(which can be overridden with
.Fl c Ar confdir ) .
.It Sy maxfilesize Ar class Ar size
Set the maximum size of an uploaded file to
.Ar size .
If
.Ar class
is
.Dq none
or no argument is given, disable this.
.It Sy maxtimeout Ar class Ar time
Set the maximum timeout period that a client may request,
defaulting to two hours.
This cannot be less than 30 seconds, or the value for
.Sy timeout .
If
.Ar class
is
.Dq none
or
.Ar time
is not specified, set to default of 2 hours.
.It Sy modify Ar class Op Sy off
If
.Ar class
is
.Dq none
or
.Sy off
is given, disable the following commands:
.Sy CHMOD ,
.Sy DELE ,
.Sy MKD ,
.Sy RMD ,
.Sy RNFR ,
and
.Sy UMASK .
Otherwise, enable them.
.It Sy motd Ar class Op Ar file
If
.Ar file
is not given or
.Ar class
is
.Dq none ,
disable this.
Otherwise, use
.Ar file
as the message of the day file to display after login.
Escape sequences are supported; refer to
.Sx Display file escape sequences
in
.Xr ftpd 8
for more information.
If
.Ar file
is a relative path, it will be searched for in
.Pa /etc
(which can be overridden with
.Fl c Ar confdir ) .
.It Sy notify Ar class Op Ar fileglob
If
.Ar fileglob
is not given or
.Ar class
is
.Dq none ,
disable this.
Otherwise, each time the user enters a new directory,
notify the user of any files matching
.Ar fileglob .
.It Sy passive Ar class Op Sy off
If
.Ar class
is
.Dq none
or
.Sy off
is given, disallow passive
.Sy ( PASV ,
.Sy LPSV ,
and
.Sy EPSV )
connections.
Otherwise, enable them.
.It Sy portrange Ar class Ar min Ar max
Set the range of port number which will be used for the passive data port.
.Ar max
must be greater than
.Ar min ,
and both numbers must be be between
.Dv IPPORT_RESERVED 
(1024) and 65535.
If
.Ar class
is
.Dq none
or no arguments are given, disable this.
.It Sy rateget Ar class Ar rate
Set the maximum get
.Pq Sy RETR
transfer rate throttle for
.Ar class
to
.Ar rate
bytes per second.
If
.Ar rate
is 0, the throttle is disabled.
If
.Ar class
is
.Dq none
or no arguments are given, disable this.
.Pp
An optional suffix may be provided, which changes the intrepretation of
.Ar rate
as follows:
.Bl -tag -width 3n -offset indent -compact
.It b
Causes no modification. (Default; optional)
.It k
Kilo; multiply the argument by 1024
.It m
Mega; multiply the argument by 1048576
.It g
Giga; multiply the argument by 1073741824
.It t
Tera; multiply the argument by 1099511627776
.El
.It Sy rateput Ar class Ar rate
Set the maximum put
.Pq Sy STOR
transfer rate throttle for
.Ar class
to
.Ar rate 
bytes per second,
which is parsed as per
.Sy rateget Ar rate .
If
.Ar class
is
.Dq none
or no arguments are given, disable this.
.It Sy sanenames Ar class Op Sy off
If
.Ar class
is
.Dq none
or
.Sy off
is given, allow uploaded file names to contain any characters valid for a
file name.
Otherwise, only permit file names which don't start with a
.Sq \&.
and only comprise of characters from the set
.Dq [-+,._A-Za-z0-9] .
.It Sy template Ar class Op Ar refclass
Define
.Ar refclass
as the
.Sq template
for
.Ar class ;
any reference to
.Ar refclass
in following directives will also apply to members of
.Ar class .
This is useful to define a template class so that other classes which are
to share common attributes can be easily defined without unnecessary
duplication.
There can be only one template defined at a time.
If
.Ar refclass
is not given, disable the template for
.Ar class .
.It Sy timeout Ar class Ar time
Set the inactivity timeout period.
(the default is fifteen minutes).
This cannot be less than 30 seconds, or greater than the value for
.Sy maxtimeout .
If
.Ar class
is
.Dq none
or
.Ar time
is not specified, set to the default of 15 minutes.
.It Sy umask Ar class Ar umaskval
Set the umask to
.Ar umaskval .
If
.Ar class
is
.Dq none
or
.Ar umaskval
is not specified, set to the default of 
.Li 027 .
.It Sy upload Ar class Op Sy off
If
.Ar class
is
.Dq none
or
.Sy off
is given, disable the following commands:
.Sy APPE ,
.Sy STOR ,
and
.Sy STOU ,
as well as the modify commands:
.Sy CHMOD ,
.Sy DELE ,
.Sy MKD ,
.Sy RMD ,
.Sy RNFR ,
and
.Sy UMASK .
Otherwise, enable them.
.El
.Sh DEFAULTS
The following defaults are used:
.Pp
.Bd -literal -offset indent -compact
checkportcmd  all
classtype     chroot CHROOT
classtype     guest  GUEST
classtype     real   REAL
display       none
limit         all    -1     # unlimited connections
maxtimeout    all    7200   # 2 hours
modify        all
motd          all    motd
notify        none
passive       all
timeout       all    900    # 15 minutes
umask         all    027
upload        all
modify        guest  off
umask         guest  0707
.Ed
.Sh FILES
.Bl -tag -width /usr/share/examples/ftpd/ftpd.conf -compact
.It Pa /etc/ftpd.conf
This file.
.It Pa /usr/share/examples/ftpd/ftpd.conf
A sample
.Nm
file.
.El
.Sh SEE ALSO
.Xr ftpchroot 5 ,
.Xr ftpusers 5 ,
.Xr ftpd 8
.Sh HISTORY
The
.Nm
functionality was implemented in
.Nx 1.3
and later releases by Luke Mewburn, based on work by Simon Burge.