Muddleftpd reference text.
Copyright Beau Kuiper 2000.

1.0	Config file format overview

1.0.1	Main sections

1.0.2	Virtual server sections

1.0.3	Group sections.

1.1	Directive reference

1.1.1	Quick reference

This is a quick list of all muddleftpd directives, and where they are valid.

	access (group)
	altlongreplies (main)
	authmethod (group)
	authuser (group)
	badauthwait (virtual-server, main)
	busydump (group)
	busydumpdata (group)
	byteratios (group)
	cddump (group)
	cddumpdata (group)
	chmoding (group)
	chroot (group)
	cmdoff (group)
	devaccess (group)
	droproot (group)
	email (virtual-server, main)
	fakegroup (group)
	fakemode (group)
	fakename (group)
	fileratios (group)
	fnaccess (group)
	ftpport (virtual-server, main)
	fxpallow (group)
	gid (group)
	greeting (virtual-server, main)
	group (virtual-server, main)
	homedir (group)
	hostname (virtual-server, main)
	include
	initalbytes (group)
	initalfiles (group)
	ipacl (virtual-server, main, group)
	logfile (virtual-server, main)
	logindump (virtual-server, main)
	logindumpdata (virtual-server, main)
	logintries (virtual-server, main)
	logstrength (virtual-server, main)
	maxconnectperip (virtual-server, main)
	maxspeed (group)
	maxusers (virtual-server, main, group)
	nameacl (group)
	nice (group)
	pfnaccess (group)
	quitdump (group)
	quitdumpdata (group)
	ratiofile (group)
	ratios (group)
	rdnstimeout (main)
	realdir (group)
	rootdir (group)
	runasuser (main)
	sitecmdoff (group)
	smartbind (main)
	supgid (group)
	timeout (virtual-server, main, group)
	uid (group)
	umask (virtual-server, main, group)
	userjail (group)
	vserver (main)
	welcome (group)
	welcomedumpdata (group)
	zerobind (main)

1.1.2	Detailed reference

1.1.2.1 "access" directive

Used in:	group sections

Syntax:		access [DIR]:[MODE]

Examples:	access %h/:ALL		# give all access to home directory
		access /secure/:NONE	# deny all access to /secure directory
		access /:RCL		# only allow reading, listing and
					# chdir to users 

Cookie support: Yes, see 1.2.2

Default:	access /:NONE

access is used to change the permissions on files or directories muddleftpd
gives to users logged into a particular group. If [DIR] ends with /, then
muddleftpd assumes it is refering to a directory and permissions only
apply to files in the directory, not [DIR] itself. Otherwise, muddleftpd
assumes it is a file, and the permissions will only apply to that filename.
[MODE] is documented in 1.2.1. 

WARNING: when a symbolic link is encountered, muddleftpd will apply the
	 access directives to the symbolic link only, not to the
	 destination of the symbolic link. Users who can create
	 symbolic links in the same areas they access with the ftp server
	 will be able to easily circumvent the access directives.
	 Therefore you MUST not depend on access being safe in
	 groups where the user can create symbolic links in the same
	 area as they can access via the ftp server.

1.1.2.2 "altlongreplies" directive

Used in:	main section

Syntax:		altlongreplies [VALUE]

Examples:	altlongreplies 0	# use rfc format for long replies
		altlongreplies 1	# use more compatible format for
					# long replies

Cookie support: No

Default:	altlongreplies 0

altlongreplies makes muddleftpd use a different format for long FTP replies.
When set to 1, it uses the following format for long replies:

220-Start long reply
220-Contiune
220 End long reply

When set to 0, it uses this format:

220-Start long reply
    Continue
220 End long reply.

When set to 1, muddleftpd may be more compatible with older clients and
proxies.

1.1.2.3 "authmethod" directive

Used in:	group sections

Syntax:		authmethod [modulename]

Examples:	authmethod pam		# use pam to authenticate users
		authmethod unix		# use unix passwd to authenticate
					# users.
		authmethod /etc/muddleftpd/libauthmysql.so
					# use external authentication module.

Cookie support: Yes, see 1.2.2

Default:	(none), you must specify this.

authmethod sets how muddleftpd chooses a user's group and how that user is
authenticated. You can specify one of the internal authentication modules
(unix,pam,internal,anonymous,deny) or an external module. If you use an
external authentication module, its full path MUST be specified. Section
2.0 outlines 

1.1.2.4 "authuser" directive

Used in:	group sections

Syntax:		authuser [username]

Examples:	authuser %U		# no rewriting.
		authuser %U-servb	# add the suffix -servb to the
					# username
		authuser %(5,100)U	# remove first 5 characters of
					# username

Cookie support: Yes, see 1.2.2

Default:	authuser %U

Authuser allows the server to do some very basic rewriting of the username
before passing it to the authentication module (specifed in authmodule). 
This re-written username is ONLY used when communicating with the
authentication module, and the original username is used everywhere else.

1.1.2.5	"badauthwait" directive

Used in:	virtual server sections or the main section. If virtual
		servers are defined, any occurence in the main section is
		taken as the default for virtual servers.

Syntax:		badauthwait [milliseconds]

Examples:	badauthwait 2000	# wait 2 seconds
		badauthwait 500		# wait 1/2 second

Cookie support: No

Default:	badauthwait 3000

When a login fails (PASS command) for any reason, muddleftpd will wait a 
defined time before accepting a new command. Use this option to specify an 
appropriate time for muddleftpd to wait.

1.1.2.6	"busydump" directive

Used in:	group sections

Syntax:		busydump [filename]

Examples:	busydump /etc/muddleftpd/TOOBUSY
					# print this when too many users 
					# are on

Cookie support: Yes, see 1.2.2

Default:	(none)

When the server cannot log a user into a particular group due to maxusers
limits, it will print this message before disconnecting the user from the
server. This is not used when the server's or the virtual server's maxusers
limit is reaches. When this occurs, the user is simply disconnected without
any messages. Section 1.2.4 documents cookies you can use in files specified
with this directive. The file must given with a full path.

1.1.2.7	"busydumpdata" directive

Used in:	group sections

Syntax:		busydumpdata [dump-string]

Examples:	busydumpdata Cannot log you in/nMaximum %M users exceeded./n
					# print this when too many users 
					# are on

Cookie support: Yes, see 1.2.4

Default:	(none)

This command is exactly like busydump (1.1.2.7), except the actual data is 
stored in the config file instead of an external file. The format for 
[dump-string] is described in section 1.2.3. This overrides any busydump
directives in the same section.

1.1.2.8 "byteratios" directive

Used in:	group sections, only valid if ratios is set to 1

Syntax:		byteratios [down:up]

Examples:	byteratios 10:3		# for every 3 bytes the user uploads
					# give 10 bytes of download credit.
		byteratios 1:5		# for every 5 bytes the user uploads
					# give 1 byte of credit.

Cookie support:	No

Default:	(none)

This directive sets the ratios that will be placed on byte usage for users
not found in the ratio file. (users in the ratio file have already got a
ratio stored) If no ratio file is given, this will always be used.

1.1.2.9 "cddump" directive

Used in:	group sections

Syntax:		cddump [filename]

Examples:	cddump README		# print the README file in the 
					# directory the user is entering
		cddump /etc/cdinfo	# print /etc/cdinfo out.

Cookie support: Yes, see 1.2.2

Default:	(none)

When a user changes directory, this file will be printed. If it is relative
filename (no / at the beginning), then the file will relative to the new
directory the user is entering. A relativly specified file will also have
to be normally accessable to the user via permissions and access directives.
If the file is specified absolute (with a / at the beginning) then
muddleftpd will not check it against access directives. Absolute files are
not relative to rootdir.

1.1.2.10 "cddumpdata" directive

Used in:	group sections

Syntax:		cddumpdata [dump-string]

Examples:	cddumpdata You changed dir/nIt is now %C/n
					# print this when muddleftpd changes
					# dir

Cookie support: Yes, see 1.2.4

Default:	(none)

This command is exactly like cddump (1.1.2.9), except the actual data is 
stored in the config file instead of an external file. The format for 
[dump-string] is described in section 1.2.3. This overrides any cddump
directives in the same section.

1.1.2.11 "chmoding" directive

Used in:	group sections

Syntax:		chmoding [0 or 1]

Examples:	chmoding 1		# allow site chmod
		chmoding 0		# disallow site chmod

Cookie support: Yes, see 1.2.2

Default:	chmoding 0

This command controls whether users can change the permissions on files
using "site chmod". By default, it is 0 and users cannot change file
permissions on ANY files. Setting it to 1 will enable this ability.

1.1.2.12 "chroot" directive

Used in:	group sections

Syntax:		chroot [VALUE]

Examples:	chroot 1		# chroot after successful login
		chroot 0		# don't chroot after successful
					# login

Cookie support: Yes, see 1.2.2

Default:	chroot 0

This controls whether muddleftpd will change the system root directory to
the users rootdir after login is complete. This means symbolic links that
point outside of the users rootdir will NOT work. It has the following
side effects:

	1) userjail is set to 1, thus the user cannot login again.
	2) welcome, cddump and quitdump, will complain if you attempt to
	   use files outside of rootdir
	3) log messages for file operations will now have filenames absolute
	   to the user's rootdir. (may be fixed later)
	4) log rotation will not be done for any muddleftpd process that
	   has performed chroot.

1.1.2.13 "cmdoff" directive

Used in:	group sections

Syntax:		cmdoff [CMD]

Examples:	cmdoff SITE		# disable all site commands.
		cmdoff PASV		# disable passive transfers.
		cmdoff DELE		# disable file deletion.

Cookie support: Yes, see 1.2.2

Default:	(none)

This directive disables FTP commands. This can disable things like file 
rename, deleting, storing files, ect. When commands are disabled, they 
appear unimplemented to the user (ie, they become no different to commands 
that don't exist). See section 3.1 for commands that can be disabled with 
this command.

1.1.2.14 "devaccess" directive

Used in:	group sections

Syntax:		devaccess [VALUE]

Examples:	devaccess 1		# enable access to device files.
		devaccess 0		# disable access to device files.

Cookie support: Yes, see 1.2.2

Default:	devaccess 0

This directive sets whether users in a group can access device files. The
default is to disallow this, although it does incur a very small performace
penalty. (file must be checked to make sure it isn't a device). Attempting
to access a device will result in a permission error.

1.1.2.15 "droproot" directive

Used in:	group sections

Syntax:		droproot [VALUE]

Examples:	droproot 1		# drop all root privliges after
					# login
		droproot 0		# don't drop root privliges.

Cookie support: Yes, see 1.2.2

Default:	droproot 0

This directive sets whether the server will drop all root privlidges after
login. When enabled, security for the paranoid is enhanced (muddleftpd
doesn't have root exploits), but:

	1) muddleftpd cannot bind the server data port to 20. This means
	that ftp clients may not work through firewalls. However, this
	limitation will automaticly be removed if you have linux and the 
	capibilities library installed.
	2) userjail is set to 1. (user cannot relogin as another user)
	3) logfiles cannot be rotated by any muddleftpd process that
	has a user logged into a group where droproot is set.

1.1.2.16 "email" directive

Used in:	virtual server sections or the main section. If virtual
		servers are defined, any occurence in the main section is
		taken as the default for virtual servers.

Syntax:		email [STRING]

Examples:	email ftpadmin@ftp.host.com	# set email to this
		email user@hostname		# another silly example

Cookie support: No

Default:	email ftp@localhost

This sets the email address returned when the HELP ftp command is used,
and when the %e cookie is used in dumped files or strings. This can
be anything you want really.

1.1.2.17 "fakegroup" directive

Used in:	group sections

Syntax:		fakegroup [STRING]

Examples:	fakegroup mudgroup	# set group to mudgroup
		fakegroup anonymous	# set group to anonymous

Cookie support: Yes, see section 1.2.2

Default:	(none)

This is used to hide all group names in all listings, replacing them with
the name you specify for the given group. This can hide the real group names
in the group files from ftp users.

1.1.2.18 "fakemode" directive

Used in:	group sections

Syntax:		fakemode [OCTAL-VALUE]

Examples:	fakemode 777		# set mode to rwxrwxrwx
		fakemode 700		# set mode to rwx------

Cookie support: Yes, see section 1.2.2

Default:	(none)

This specifies that listings should always return a certain mode for
filenames. This hides the real permissions from the ftp user.

1.1.2.19 "fakename" directive

Used in:	group sections

Syntax:		fakename [STRING]

Examples:	fakename mud		# set username to mud
		fakename mp3		# set username to mp3
		fakename %U		# set username to the login username

Cookie support: Yes, see section 1.2.2

Default:	(none)

This specifies that listings should always return a certain user ownership
for files. This hides the files original owner from ftp users.

1.1.2.20 "fileratios" directive

Used in:	group sections, only valid if ratios is set to 1

Syntax:		fileratios [down:up]

Examples:	fileratios 2:1		# for every file the user uploads
					# allow 2 to be downloaded
		fileratios 1:5		# for every 5 bytes the user uploads
					# give 1 byte of credit.

Cookie support:	No

Default:	(none)

This sets inital ratios on how many files a user must upload to how many 
credits they recieve for doing so. This will not override information
in the ratio file. If no ratio file is specified, this is always used.

1.1.2.21 "fnaccess" directive

Used in:	group sections

Syntax:		fnaccess [PATTERN]:[MODE]

Examples:	fnaccess *.mp3:NONE	# no access to files with mp3
					# extension
		fnaccess *.o:NONE	# no access to object files.
		fnaccess /home/%U/*:R	# give read access to all files in
					# user home dir and subdirs

Cookie support: Yes, see section 1.2.2.

Default:	(none)

This specifies access setting using basic regular expressions. fnaccess
setting have priority over regular access directives, so care must be
exercised in the specifing fnaccess directives. Eg,

	access /:C
	access /home/mud/:LC
	fnaccess *.c:R

will allow access to filenames /a.c or /home/a.c. Also, fnaccess directives
are checked in the order they are specified in the config file, so fnaccess
directives specified earilier have higher priority over fnaccess directives
specified later.

WARNING: when a symbolic link is encountered, muddleftpd will apply the
	 fnaccess directives to the symbolic link only, not to the
	 destination of the symbolic link. Users who can create
	 symbolic links in the same areas they access with the ftp server
	 will be able to easily circumvent the fnaccess directives.
	 Therefore you MUST not depend on fnaccess being safe in
	 groups where the user can create symbolic links in the same
	 area as they can access via the ftp server.

1.1.2.22 "ftpport" directive

Used in:	either the main section or virtual server sections. If used
		in the main section when virtual servers are defined, then
		the declaration in the main section is ignored.

Syntax:		ftpport	[PORTNUM]
		or
		ftpport [PORTNUM]:[IPADDR]

Examples:	ftpport 21		# bind to port 21, all interfaces
		ftpport 21:10.1.1.1	# bind to port 21, interface 
					# on 10.1.1.1 only
		ftpport 4008		# bind to port 4008.

Cookie support: No

Default:	(none), must be specified.

This directive specifies what ports muddleftpd will listen for connections
on. It may be specified more than once in the same section, where muddleftpd
will listen for all specified ports. If you don't supply the ip of an
interface to bind to, muddleftpd will listen on all ports. When setting
up virtual servers, it is often done by using the same port, while using 
a different ip for the interface in each virtual server definition.

1.1.2.23 "fxpallow" directive

Used in:	group sections

Syntax:		fxpallow [VALUE]

Examples:	fxpallow 0		# disallow server-server transfers.
		fxpallow 1		# allow server-server transfers.

Cookie support: Yes, see section 1.2.2.

Default:	fxpallow 0

This directive specifies whether users of a particular group can perform
server to server transfers. It is highly recommended that you do not set
this unless you really, really need to. Setting this to true allows users
to send a file to an abitary port (above 1024) on any remote server. It also
allows a third party to steal a passive connection from a user from any
remote computer.

1.1.2.24 "gid" directive

Used in:	group sections

Syntax:		gid [VALUE or NAME]

Examples:	gid %g		# set gid from users gid from authentication
				# module
		gid 10		# set users group to 10
		gid ftpuser	# set the users group to ftpuser.

Cookie support: Yes, see section 1.2.2.

Default:	gid %g

This specifies what gid a user connected to the server will use to access
files. It can be specified using a group name or an integer group value.
By default, the gid from the authentication module is used. If you set it
to 0 (the root group), then muddleftpd will automaticly demote it to
nobody's group.

1.1.2.25 "greeting" directive

Used in:	virtual server sections or the main section. If virtual
		servers are defined, any occurence in the main section is
		taken as the default for virtual servers.

Syntax:		greeting [STRING]

Examples:	greeting Welcome to %L		# set greeting to display 
						# server name

Cookie support: Yes, see section 1.2.4

Default:	greeting muddleftpd (1.3.4-devel) server ready. Enter Username.

Sets the greeting line when a person connects to the server. This accepts
all of the cookies the logindump file will accept. This is used to
personalize your server and hide the server name, version from users.

1.1.2.26 "group" directive

Used in:	either the main section or virtual server sections. If used
		in the main section when virtual servers are defined, then
		the declarations in the main section are ignored.

Syntax:		group [SECTION]

Examples:	group badusers		# set to check badusers section first
		group anonymous		# set to check anonymous section next
		group users		# set to check users section last
			or
		group badsites		# check badsites section first
		group users		# then users section next

Cookie support: No

Default:	(none), must be specified.

This directive sets the sections muddleftpd will check as groups when
logging someone in to the server, or one of its virtual servers. The groups 
are checked in the same order as specified in the config file. Group
sections are discussed in detail in section 1.0.3

1.1.2.27 "homedir" directive

Used in:	group sections

Syntax:		homedir [DIRECTORY]

Examples:	homedir /		# set homedir to same as rootdir
		homedir %h		# set homedir to homedir from
					# authentication module.

Cookie support: Yes, see section 1.2.2.

Default:	homedir %h

This directive describes the home directory a user logging in will have. It
is ALWAYS relative to the rootdir. This is so users don't have homedir's
outside of their root directory. By default, homedir is set by the
authentication module.

1.1.2.28 "hostname" directive

Used in:	virtual server sections or the main section. If virtual
		servers are defined, any occurence in the main section is
		taken as the default for virtual servers.

Syntax:		hostname [STRING]

Examples:	hostname mud.serious.net	# a hostname
		hostname hostname		# another example

Cookie support: No

Default:	(same as the hostname from /etc/HOSTNAME)

This sets the hostname muddleftpd will report to users when they use the 
ftp server. It sets the %L cookie for files dumped to the user (see section
1.2.4). It also sets the %V cookie for group sections (see section 1.2.2)

1.1.2.29 "include" directive

Used in:	anywhere

Syntax:		include [SECTIONNAME]

Examples:	include asection		# include section asection

Cookie support: No

Default:	(none)

This is a low level function that allows a section to be included into
another section. No cookies are interpretted by include. An example:

[section] a
	hostname v
	access /:ALL
	access /test/:NONE

[section] b

	access /:NONE
	include a
	access /test/:ALL

when section b is interpreted, will become

	access /:NONE
	hostname v
	access /:ALL
	access /test/:NONE
	access /test/:ALL

Here, the included data is inserted in order, so you must be careful of the
order the final result will be. In this example, the access to / is
overriden by the data in the included section.

1.1.2.30 "initalbytes" directive

Used in:	group sections, only valid if ratios is set to 1, and
		byteratios is set (see 1.1.2.8)

Syntax:		initalbytes [64bit-INT]

Examples:	initalbytes 2000000	# give 2 meg of inital credits.
		initalbytes 0		# give 0 meg of credits initally. 

Cookie support:	No

Default:	(none)

This sets how many byte credits a user has initally when using ratios. If 
you have ratiofile defined, then this is only used for new users. Otherwise 
the setting will be read from the ratiofile. This is specified as a 64-bit
integer (ie, can have virtually any size)

1.1.2.31 "initalfiles" directive

Used in:	group sections, only valid if ratios is set to 1, and
		fileratios is set (see 1.1.2.20)

Syntax:		initalfiles [COUNT]

Examples:	initalfiles 100		# give 100 inital file credits.
		initalfiles 0		# give 0 file credits initally. 

Cookie support:	No

Default:	(none)

This sets how many file credits a user has initally when using ratios. If you 
have ratiofile defined, then this is only used for new users. Otherwise the
setting will be read from the ratiofile.

1.1.2.32 "ipacl" directive

Used in:	main, vserver and group sections

Syntax:		ipacl [A or D]/[IP]/[NETMASK]
		ipacl [A or D]/[IP-PATTERN]
		ipacl [A or D]/([HOST-PATTERN])

Examples:	ipacl A/10.1.1.0/255.255.255.0	# allow 10.X.X.X
		ipacl A/127.*			# allow localhost addresses
		ipacl A/(localhost)		# allow hostname localhost
		ipacl A/(*.edu)			# allow any .edu address
		ipacl D/(*.com.??)		# disallow country .com 

Cookie support: No

Default:	ipacl D/*

Ipacl is a generic way of declaring what IP address/hostnames have access to
something. The first format above allows you to specify a range of IP's
using an ip address and a netmask. The second format allows you to specify a
range of IP's using a basic regular expressions. The third fromat allows you
to sepecify a basic regular expression to match the user's hostname. You
must be very careful when using regular expressions against hostnames.
Users may spoof DNS and their hostname, allowing them to get accesss they
otherwise shouldn't have. Ipacl's are checked in the order they are in the 
config file. The first ipacl to match the user's hostname or IP will decide
the access of a particular user. The access a user will get is defined by
the first character before ':', an 'A' will grant access, anything else will
deny it.

When used in the main section, ipacl controls who is given access to the
server. If the user is not accepted by these controls, they are dumped from
the server immediately. If virtual servers are defined, ipacl's in the 
virtual server section decide if the user is accepted into the server (after
the main ones are checked). In group sections, ipacl controls if a user can
login to that group after the user has entered a username/password. If the
user is not accepted, muddleftpd will check the next group.

1.1.2.33 "logfile" directive

Used in:	virtual server sections or the main section. 

Syntax:		logfile [FILENAME]

Examples:	logfile /var/log/ftpd.log		# set logfile

Cookie support: No

Default:	logfile /var/log/muddleftpd.log

Sets the logfile for muddleftpd logs. This file must be an absolute
filename. When defined in virtual server sections, muddleftpd will log
information users using that virual server into that file instead of the
main log file. The parameter to logfile must be an absolute filename. (ie
start with /)

1.1.2.34 "logindump" directive

Used in:	virtual server sections or the main section. If virtual
		servers are defined, any occurence in the main section is
		taken as the default for virtual servers.

Syntax:		logindump [filename]

Examples:	logindump /etc/issue	# print this before user logs in

Cookie support: No

Default:	(none)

When a new user connection to the server occurs, this is printed before the
greeting (see section 1.1.2.25). All new users will see this file before
they login using a username/password.

1.1.2.35 "logindumpdata" directive

Used in:	virtual server sections or the main section. If virtual
		servers are defined, any occurence in the main section is
		taken as the default for virtual servers.

Syntax:		logindumpdata [dump-string]

Examples:	logindumpdata Welcome/nThis server will allow %M users./n
					# print this when a user connects

Cookie support: Yes, see 1.2.4

Default:	(none)

This command is exactly like logindump (1.1.2.32), except the actual data is 
stored in the config file instead of an external file. The format for 
[dump-string] is described in section 1.2.3. This directive overrides any
logindump directives in the same section. 

1.1.2.36 "logintries" directive

Used in:	virtual server sections or the main section. If virtual
		servers are defined, any occurence in the main section is
		taken as the default for virtual servers.

Syntax:		logintries [COUNT]

Examples:	logintries 10		# give 10 tries to login.
		logintries 1		# give only one try to login.

Cookie support: No

Default:	logintries 3

This command limits the number of incorrect username/password combinations
a connection can make before it is locked out. After this, any USER command
the client will fail. This can slow down the brute forcing of passwords.

1.1.2.37 "logstrength" directive

Used in:	virtual server and main sections.

Syntax:		logstrength [VALUE]

Examples:	logstrength 63		# Log Everything
		logstrength 25		# Log bad connections, commands
					# resposes and generic info.

Cookie support: No

Default:	logstrength 63

This command sets how much logging muddleftpd and/or its virtual servers
will perform. It is a value created by adding up one or more of the
following numbers:

	1	Log connections that fail due to ipacl settings
	2	Log file transfers (uploads, downloads, SITE DUMP)
	4	Log command the client sends to the server.
	8	Log responses to commands the client sends.
	16	Log generic information, including config errors
			(highly recommended)
	32	Log successful/unsuccessful logins and logouts of clients.

So to log file transfers and generic information, use a setting of 18.

1.1.2.38 "maxconnectperip" directive

Used in:	virtual server sections or the main section. 

Syntax:		maxconnectperip [COUNT]

Examples:	maxconnectperip 0	# set no limit
		maxconnectperip 2	# only 2 connections from the same
					# ip

Cookie support: No

Default:	maxconnectperip

This directive limits the number of logins from the same IP address to the
server (or one of its virtual servers). This options will reduce the login
performace of the server if it is running in standalone mode. If used in the
main section, it sets the total number of connections from any one IP
regardless of the virtual server the client is connected to. When used in
virtual server sections, it will only affect conections to that single
virtual server.

1.1.2.39 "maxspeed" directive

Used in:	group sections

Syntax:		maxspeed [BYTES-PER-SECOND]

Examples:	maxspeed 4096		# set max transfer speed to 4096 b/s
		maxspeed 1000000	# set max transfer speed to 1 Meg/sec

Cookie support: Yes, see section 1.2.2.

Default:	(none)

This directive specifies how fast a user may download/upload data at. This
can be used to conserve bandwidth/annoy users. The value used is specified
in bytes per second. Control port data is not affected by this command, so
you may wish to also use the directive "sitecmdoff dump" when using this
option.

1.1.2.40 "maxusers" directive

Used in:	main, vserver and group sections

Syntax:		maxusers [COUNT]

Examples:	maxusers 100		# set maximum users to 5
		maxusers 0		# allow no users, hide group.

Cookie support: No

Default:	maxusers 30

maxusers sets the maximum number of users for a server, a virtual server, or
for a group. When used in the main section, maxusers will set the maximum
number of users the server will allow in. Any connections that would exceed
this count are immediately dropped, without any messages. When used in a 
virtual server section, maxusers will set the maximum number of users the
server will allow to connect to that virtual server. As with the main
section, connections that overflow that count will be dropped. In group
sections, maxusers sets the maximum number of users that can login via that
group. When that limit is reached, new connections will be given the
busydump message and disconnected instead of quietly disconnected. When
maxusers is set to 0 in a group section, that group will not be displayed
in ftpwho listings.

1.1.2.41 "nameacl" directive

Used in:	group sections

Syntax:		nameacl [A or D]:[PATTERN]

Examples:	nameacl A:*			# accept any username
		nameacl A:anonymous		# accept only anonymous.
		nameacl D:root			# deny username root.

Cookie support: No

Default:	nameacl D:*

This directive declares which usernames will be accepting when attempting to
authenticate against a group. nameacl directives are checked in order, and
the first one to match the username will determine the final result. If
the final result is accept, than the username will continue to be
authenticated against that group. If the final result is deny, muddleftpd
will try the next group.

1.1.2.42 "nice" directive

Used in:	group sections

Syntax:		nice [VALUE]

Examples:	nice -20		# give very low priority
		nice 5			# give higher priority.

Cookie support: Yes, see section 1.2.2.

Default:	nice 0

This directive sets the CPU priority of a user in a group after they have
logged on. VALUE may be from -20 (highest priority) to 20 (lowest priority)
with 0 being normal priority. Note that you cannot use negative values
unless you run muddleftpd as root and runasuser isn't set.

1.1.2.43 "pfnaccess" directive

Used in:	group sections

Syntax:		pfnaccess [PATTERN]:[MODE]

Examples:	pfnaccess /b/*.mp3:NONE	# no access to files with mp3
					# extension in only the b dir
		pfnaccess /*.o:NONE	# no access to object files in root
					# dir.
		pfnaccess /home/%U/*:R	# give read access to all files in
					# user home dir and subdirs

Cookie support: Yes, see section 1.2.2.

Default:	(none)

This specifies access setting using basic regular expressions, however 
wildcard characters cannot match / characters, so only a single directory
is affected. pfnaccess have lower priority to fnaccess, and higher priority
to plain access. All the rules for fnaccess (see section 1.1.2.21) also
apply to pfnaccess.

1.1.2.44 "quitdump" directive

Used in:	group sections

Syntax:		quitdump [filename]

Examples:	quitdump /etc/muddleftpd/BYEMSG
					# print this when user exits

Cookie support: Yes, see 1.2.2

Default:	(none)

When a user quits muddleftpd, the data from the specified filename will be 
printed to the user as they leave. Section 1.2.4 documents cookies you can 
use in files specified with this directive. The file must given with a full 
path.

1.1.2.45 "quitdumpdata" directive

Used in:	group sections

Syntax:		quitdumpdata [dump-string]

Examples:	quitdumpdata Thank you/nYou downloaded %b bytes./n
					# print this when user exits

Cookie support: Yes, see 1.2.4

Default:	(none)

This command is exactly like quitdump (1.1.2.40), except the actual data is 
stored in the config file instead of an external file. The format for 
[dump-string] is described in section 1.2.3. This overrides any quitdump
directives in the same section.

1.1.2.46 "ratios" directive

Used in:	group sections.

Syntax:		ratios [0 or 1]

Examples:	ratios 1		# enable ratios.

Cookie support:	Yes, see section 1.2.2

Default:	ratios 0

This directive specifies whether a user in a group will be subject to ratios. 
These ratios are specified by:
	
	byteratios (see section 1.1.2.8)
	fileratios (see section 1.1.2.20)
	initalbytes (see section 1.1.2.30)
	initalfiles (see section 1.1.2.31)
	ratiofile (see section 1.1.2.47)

1.1.2.47 "ratiofile" directive

Used in:	group sections, only valid if ratios is set to 1

Syntax:		ratiofile [filename]

Examples:	ratiofile /etc/ratios
		ratiofile /home/rugger/ratios	# location of persistant
						# ratios

Cookie support:	No

Default:	(none)

This directive specifes that persistant ratios are to be used, and that
ratio information will be stored in the given file. The given file must
be specified with a full path (absolute path). This file will store what
a users private ratios are and what credits (byte, file) they have. This
file is in a binary format, and cannot be freely moved between differnent
types of systems. Using persistant ratios also causes a signifcant
performace drop in muddleftpd, since a lot of file access must occur to keep
ratio data consistant. Make sure the ratio file is stored on a filesystem
that isn't mounted syncronously (ie not write-back cache) otherwise
performace will be terrible.

1.1.2.48 "rdnstimeout" directive

Used in:	main section

Syntax:		rdnstimeout [VALUE]

Examples:	rdnstimeout 0	# disable reverse lookup.
		rdnstimeout 10	# allow reverse lookup 10 seconds.

Cookie support: No

Default:	rdnstimeout 15

rdnstimeout sets the amount of time muddleftpd will wait for reverse DNS
lookups to occur. During this time, muddleftpd will be non-responsive. If
set to 0, reverse DNS lookups will be disabled. If reverse DNS lookup fails
or times out, muddleftpd will use the IP address of the host to identify it.

1.1.2.49 "realdir" directive

Used in:	group sections

Syntax:		realdir [0 or 1]

Examples:	realdir 0		# don't resolve symlinks.
		realdir 1		# resolve symlinks

Cookie support: Yes, see section 1.2.2.

Default:	realdir 0

This specifies whether muddleftpd will attempt to resolve the real directory
when a user changes to a new directory. If set, muddleftpd will resolve
symlinks when changing directories if the resultant directory is within
rootdir. If the user changes to a  symlink that points outside of rootdir,
muddleftpd will not resolve it to its real directory.

1.1.2.50 "rootdir" directive

Used in:	group sections

Syntax:		rootdir [DIRECTORY]

Examples:	rootdir /		# set rootdir to system rootdir
		rootdir %r		# set rootdir from auth module
		rootdir %h		# set rootdir to users home
					# directory.

Cookie support: Yes, see section 1.2.2.

Default:	rootdir %r

This sets the root directory of a user in a group. rootdir must be specified
with a full pathname. By default, rootdir is set by the authentication
module. A user can only enter directories outside of rootdir with symlinks
(use chroot to disable this). rootdir will appear to be "/" to the logged in
user. 

1.1.2.51 "runasuser" directive

Used in:	main section

Syntax:		runasuser [username]

Examples:	runasuser rugger	# run as user rugger
		runasuser ftp		# run as ftp user

Cookie support: No

Default:	(none)

runasuser instructs muddleftpd to switch to a new uid/gid specified by
username after initalizing. This will prevent these things occuring in
addition to things that don't work without root:

	1) log rotation will not work.
	2) data ports binding to port 20.

1.1.2.52 "sitecmdoff" directive

Used in:	group sections

Syntax:		sitecmdoff [CMD]

Examples:	sitecmdoff IDLE		# disable site idle command.
		sitecmdoff DUMP		# disable site dump command

Cookie support: Yes, see 1.2.2

Default:	(none)

This directive selectivly disables FTP SITE commands. This can disable things 
like SITE ACCESS and SITE DUMP, that may improve security when using other
commands.

1.1.2.53 "smartbind" directive

Used in:	main section

Syntax:		smartbind [0 or 1]

Examples:	smartbind 0		# use simple binding method
		smartbind 1		# use smart binding method

Cookie support: No

Default:	smartbind 0

This directive instructs whether muddleftpd will take all the ports/IP's it
needs to listen to and collate them to use fewer file descriptors. Set to 1
to use smart binding, 0 otherwise. For example:

	ftpport 21/10.1.1.1
	ftpport 21/127.0.0.1
	ftpport 21/10.1.1.2

With simple binding, muddleftpd will simply bind each port individually and
use 3 file descriptors. With smart binding, muddleftpd will bind to all
interfaces on port 21, using one file descriptor. However, connections from 
extra interfaces that are bound by smart binding will simply be dropped and
other programs will not be able to use them.

NOTE: You must set smartbind to 1 if you wish to bind to individual
interfaces on most unix systems. On these unix systems, you must also set
zerobind to 1 as well. 

1.1.2.54 "supgid" directive

Used in:	group sections

Syntax:		supgid [SUP-GIDS]

Examples:	supgid %G,1		# add 1 to supgids
		supgid 1,2,3		# set supgids to 1, 2 and 3
		supgid %G,!10		# set supgids to authentication
					# module, but remove group 10
		supgid *		# set no sup groups.

Cookie support: Yes, see section 1.2.2.

Default:	supgid %G

supgid supplies a comma separated list of supplementary groups a user will
be in. Using * will cause no supplementary groups to be set. You can prefix
a group number with "!" to remove any eariler occurences of that group
number in the list.

1.1.2.55 "timeout" directive

Used in:	main, vserver and group sections

Syntax:		timeout [VALUE]

Examples:	timeout 15		# give 15 second timeout
		timeout 7200		# give 2 hour timeout

Cookie support: Yes, but only in group sections, see section 1.2.2.

Default:	timeout 300

Timeout sets the amount of time the server will wait for a user response
before disconnecting that user. If used in the main section or virtual
server sections, timeout specifies the timeout while the user logs in. If
used in a group section, it specifies the timeout after a user is logged
into that group. 

1.1.2.56 "uid" directive

Used in:	group sections

Syntax:		uid [VALUE or NAME]

Examples:	uid %u		# set uid from users uid from authentication
				# module
		uid 10		# set users uid to 10
		uid ftp		# set the users uid to ftp.

Cookie support: Yes, see section 1.2.2.

Default:	uid %u

This directive specifies what user id a user will access/create files as.
It can be speciifed either using an integer user id or a normal username.
By default, the uid from the authentication module is used. If you set it
to 0 (the root user), then muddleftpd will automaticly demote it to
nobody's user id.

1.1.2.57 "umask" directive

Used in:	main, vserver and group sections

Syntax:		umask [OCTAL-VALUE]

Examples:	umask 777		# make new files with no permisions
		umask 666		# make new files with only execute
					# permissions if directories.
		umask 022		# make new files only writeable by
					# owner

Cookie support: Yes, but only in group sections, see section 1.2.2.

Default:	(default system umask)

This sets the umask used when users create files using the ftp server. When
used in the main section, it sets the default for any virtual server or
groups. When set in a virtual server section it sets the default for groups
used by that virtual group. If used in a group section, it overrides any
other setting. Umask is defined by an octal value. Users can change their
umask using SITE UMASK unless the command is disabled or chmoding is set to
0.

1.1.2.58 "userjail" directive

Used in:	group sections

Syntax:		userjail [0 or 1]

Examples:	userjail 0		# User can relogin. 
		userjail 1		# User cannot change username

Cookie support: Yes, see section 1.2.2.

Default:	userjail 0

This specifies whether the user logged into a particular group can relogin
as a different username without disconnecting. If set to 1, the user cannot
relogin, otherwise the user will be able to use the USER command to login as
a different username. This is automaticly set to 1 if droproot (see section
1.1.2.15) and/or chroot (see section 1.1.2.12) are set to 1, since not
enough resources will be avaliable to change the users identity.

1.1.2.59 "vserver" directive

Used in:	main section.

Syntax:		vserver [SECTION]

Examples:	vserver internal	# declare section internal as a 
					# virtual server.
		vserver external	# declare section external as a
					# virtual server.

Cookie support: No

Default:	(none)

This directive, if used in the main section, changes muddleftpd behaviour
from being a regular server to a virtual server system. This directive is
used to declare what sections in the config file are to be definitions for
virtual server. By specifiing this directive multiple times in the main
section, muddleftpd will declare multiple virtual servers. For more
information on virtual server sections, see 1.0.2. If this directive is not
used, muddleftpd assumes that main defines server information.

1.1.2.60 "welcome" directive

Used in:	group sections

Syntax:		welcome [filename]

Examples:	welcome /etc/muddleftpd/WELCOMEMSG
					# print this when user logs into a
					# group

Cookie support: Yes, see 1.2.2

Default:	(none)

When a user logs into a group successfully, the data from the specified 
filename will be printed to the user. Section 1.2.4 documents cookies you can 
use in files specified with this directive. The file must given with a full 
path.

1.1.2.61 "welcomedumpdata" directive

Used in:	group sections

Syntax:		welcomedumpdata [dump-string]

Examples:	welcomedumpdata You have logged in/nThere are %N users./n
					# print this when user logs on.

Cookie support: Yes, see 1.2.4

Default:	(none)

This command is exactly like welcome (see 1.1.2.60), except the actual data is 
stored in the config file instead of an external file. The format for 
[dump-string] is described in section 1.2.3. This overrides any quitdump
directives in the same section.

1.1.2.62 "zerobind" directive

Used in:	main section, ignored if smartbind (see 1.1.2.53) is not
		set to 1

Syntax:		zerobind [0 or 1]

Examples:	zerobind 0		# bind to individual interfaces
		zerobind 1		# always bind to all interfaces.

Cookie support: No

Default:	zerobind 0

This is a compatiblity option for unix systems that don't support listening
for connections on only one interface. If you have a BSD system, or
muddleftpd is refusing to bind to the ports you specify, set zerobind and
smartbind (see 1.1.2.53) to 1.

1.2	Misc references

1.2.1	Access modes [MODE]

The directives that specify permissions for users when they access files
are:
	access (see 1.1.2.1)
	fnaccess (see 1.1.2.21)
	pfnaccess (see 1.1.2.43)

These require a mode string to specify what permissions a user has when a
particular access line is matched. A mode string is a combination of one or
more charaters, or:

	ALL	- give all access permissions
	NONE	- give no access permissions

Letters that may make up a mode string:

	A	- Create new filenames that don't already exist.
	R	- Read files that already exist.
	L	- List files (only for directories)
	X	- Replace files that already exist. 
	M	- Create new directories.
	I	- Remove existing directories.
	W	- Write to existing files.
	H	- Chmod existing files.
	C	- allow to change to that directory.

By combining these letters, any access level can be set.

1.2.2	Cookies in group sections.

In group sections, cookies allow you to customize how information from the
authentication module and the server is used to generate information about a
new users session. Most commands valid in group sections support the use of
these cookies:

	%U	- The username the user gave the server.
	%v	- The section name of the virtual server the user is logged
		  into. Set to "main" if no virtual servers are defined.
	%V	- The hostname of the virtual server the user is logged
		  into. If no virtual servers are defined, this is set the
		  the hostname provided by the main section, or by the
		  machines hostname.
	%u	- The uid of the user from the authentication module.
	%g	- The gid of the user from the authentication module.
	%h	- The home directory of the user from the authentication
		  module.
	%r	- The root directory of the user from the authentication
		  module.
	%G	- A comma delimited list of supplementary gids from the 
		  authentication module. 

Depending on the particular authentication module used, one or more of these
cookies may not be set. See 2.0 for more information on authentication
modules and what cookies are set by each individual one.

Group directives where group section cookies are not supported:

	busydumpdata, byteratios, cddumpdata, fileratios, include,
	initalbytes, initalfiles, ipacl, maxusers, nameacl,
	quitdumpdata, ratiofile, welcomdumpdata.

Group directives where group section cookies are avaliable, but only 
cookies not derived from the authentication module.

	authuser, and any directives which are used by the authentication 
	module currently selected.

1.2.3	Specifing a string for busydumpdata, cddumpdata, welcomedumpdata and
		quitdumpdata.

To use these directives, a string must be specified on a single line
describing what to dump onto the screen. To get over the limitation, you can
use control characters to perform tabs, insert spaces, and move to the next
line. Note that all the control characters are specified with a / prefix, 
not a \. All uses of \ result in the following character being quoted 
exactly before the / are resolved:

eg:
	\/\n is the same as /n and will be resolved to a newline.

Control characters that are valid are:

	/n	- Goto the next line.
	/s	- Insert a space. You need this if you need spaces at the
		  beginning or end of the directive.
	/t	- Insert a tab.
	//	- Insert a regular forward slash

The strings specified for the dumpdata directives may also contain cookies
specified in 1.2.4.

Examples:

cddumpdata You are now in %C/nYou have %a credits left

	would result in the following output (for chdir /)

	250-You are now in /
	    You have 1000000 credits left
	250 "/" is the current directory.

busydumpdata /s/s/sThe server is full./n Please try again later/nBye!

	would result in the following output (on login to a full group)

	421-   The server is full.
	     Please try again later
	    Bye!
	421 Too many users. Cannot login.

1.2.4	Cookies in dumped files.

When you specify a file to be dumped onto the screen, or set a string to be
dumped on the screen, the following cookies can be inserted into that string
or file to use information the server has internally:

	%T	- current date and time
	%U	- username of the user connecting. set to <unknown>
		  before login.
	%C	- Current working directory, relitive to a user's root
		  directory. Only avaliable after user is logged in.
	%E	- The email address set in the configuration file. (See
		  1.1.2.14 for more info)
	%M	- The maximum number of users that may exist in the current 
		  virtual server the user is connected to, or main server 
		  (before login) or maxiumun number of users a group can
		  allow in.
	%N	- The number of users currently in a group just after the 
		  user has logged in. It is not set before login.
	%L	- The hostname of the server. Can be overridden. (see
		  1.1.2.28 for more information)
	%R	- The hostname of the client obtained by reverse host lookup.
	%f	- The number of files a user has downloaded.
	%F	- The number of files a user has uploaded.
	%b	- The number of bytes the user has downloaded in file
		  transfers. 
	%B	- The number of bytes the user has uploaded in file
		  transfers.
	%I	- The number of bytes the user has downloaded in listings.
	%i	- The number of listings the user has performed.
	%D	- The total number of bytes the user has downloaded over
		  data connections.
	%t	- The total number of bytes the user has transfered over
		  data connections (both upload and downloads)
	%c	- The total number of data transfers the user has made.
		  (for listing, downloads and uploads)
	%d	- The total number of data transfers the user has made for
		  downloading (listing and downloading)
	%v	- The section name of the virtual server the user is
		  connected to (or main if no virtual servers are declared)
	
If the user is using ratios, the following are also avaliable.

	%a	- The number of download byte credits a user has.
	%A	- The number of download file credits a user has.

2.0	Authentication modules

2.0.1	Overview.

Muddleftpd uses authentication modules to determine the following:

	- whether a user will be authenticated within a particular group.
	- is the username and password the user supplied correct.
	- what parameters are associated with that user (home directory,
	  uid, gid, ...)

Authentication modules under muddleftpd come in two flavours:

	- Static modules. These modules are already compiled into muddleftpd
	  and can be accessed using a keyword for the authmethod. These
	  modules are documented in 2.1
	- Dynamic modules. These modules are not built with muddleftpd,
	  but are dynamicly linked in while muddleftpd is authenticating an 
	  user. These are distributed separately from muddleftpd, and don't
	  require muddleftpd to be recompiled to use. They can even be added 
	  while muddleftpd is still running.

All modules are able to probe the configuration file for settings. They will
often add several configuration options of their own, and the following
cookies will work on them:

	%U	- The username the user gave the server.
	%v	- The section name of the virtual server the user is logged
		  into. Set to "main" if no virtual servers are defined.
	%V	- The hostname of the virtual server the user is logged
		  into. If no virtual servers are defined, this is set the
		  the hostname provided by the main section, or by the
		  machines hostname.

When a module has finished, the following cookies may be used on other
options (see 1.2.2 for more info). Each individual module may or may provide 
information to set the following cookies:

	%u	- The uid of the user.
	%g	- The gid of the user.
	%h	- The home directory of the user.
	%r	- The root directory of the user.
	%G	- A comma delimited list of supplementary gids for the user.

You must check the documentation for the particular module you are going to
use as to whether these options are set.

2.1	Static modules in muddleftpd

The following modules are compiled into muddleftpd.

2.1.1	"unix" authentication module.

This authentication module authenticates using the unix system passwords. It
will automaticly detect shadow passwords and use them. It fully supports
account and password expiry with shadow passwords. It requires root access
to authenticate against shadow password files.

To use this module in a group section, set the following directive:

	authmethod unix

The following options may also be set in the same group section to configure 
the "unix" module:

	unix_passwdtype <mode>

	This forces what type of passwords are used by the module. If
	set to normal, shadow passwords will never be used. If set to
	shadow, normal passwords will never be acceped. 

All cookies described in 2.0 are set by the unix authentication module.

The unix module will affect group selection by accepting any user found
in the password file and authenticated them. If the user is not found in
the password file, authentication will continue to the next group.

Note: If muddleftpd is compiled when shadow passwords are not installed,
and you wish to use shadow passwords, you will need to compile muddleftpd
again after installing shadow passwords to enable the use of shadow passwords.

2.1.2	"anonymous" authentication module.

The anonymous authentication module will authenticate users for anonymous
access to the server. It will accept any username, using any password. It
will log the password the user uses. The usernames this module will accept
can be limited using the nameacl directive (see 1.1.2.41). Any users 
authenticated by this module will access files as user nobody in group
nogroup. The module will set the users root directory to the home directory
of the user "ftp". The users home directory will be set to /.

To use this module in a group section, set the following directive:

	authmethod anonymous

These directives can be used to tune the anonymous module:

	anonymous_user <username>

	This changes the user muddleftpd probes to determine the root
	directory for the anonymous user. By default it is the user "ftp"

This module will set all cookies described in 2.0 except for the
suplementary groups cookie(%G)

This module affects group selection by accepting all usernames presented to
the module. You can limit what usernames it accepts by using the nameacl
directive. However, if the username specified in anonymous_user (or "ftp" if
anonymous_user isn't specified) cannot be read the module will cancel
authentication.

2.1.3	"internal" authentication module.

This module will use a separate password file in muddleftpd's own format
to authenticate users. It is designed to provide password protection for
authentication when users don't need an associated uid/gid. The password 
file consistes of one or more lines with the following format, one user per 
line.

	<username> <encrypted-password>:<homedir>:<rootdir>

eg:
	rugger NvAdfesdaesEr:/home/rugger/:/

These password files may be modified using the external program mudpasswd.
See mudpasswd.txt for more information on this program. 

To use the internal module, set the following directive in the relevent
group section:

	authmethod internal
	
The following directives may be set to configure the internal password 
module:

	internal_passfile <password-filename>

	This sets the path to the password file that the internal
	authentication module will read passwords and user info from. This
	file must be owned by the user running the server and must not be
	group or world writable, otherwise the module will refuse to use 
	it.

The internal authentication module will set the root directory (%r) and
home directory (%h) cookies only.

This module affects group selection by accepting any usernames defined in
the given password file. If it isn't defined in the password file, the user
is then passed onto the next group. If the password file cannot be loaded,
or the password file is not safe, then authentication of the user is
cancelled.

Note: If the users in the separate password file map to the users in the
main password file, and you want each user to use their own uid, you can
set:
	uid %U

to accomplish this.

2.1.4	"disabled" authentication module

This built in module will cancel the authentication of anyone passed to the
module. You need to use nameacl to restrict what usernames get canceled by
this module.

To use the disabled module in a group, use the following directive in that
group:
	authmethod disabled

This module does not set any of the cookies described in 2.0.1

This module affects group selection by canceling any username it is allowed
to authenticate.

2.1.5	"pam" authentication module.

This module allows muddleftpd to authenticate using PAM and PAM modules.
This module also uses the password file to determine the session information
the user will have. PAM is useful for systems where password encryption is
not provided by regular crypt.

To use the pam module, set the following directive in the relevent
group sections:

	authmethod pam


3.0	FTP commands.

3.1	Non-site commands.