
		MUDDLEFTPD DOCUMENTATION (Version 1.3.4)
		Beau Kuiper (support@muddleftpd.cx)
		License under GPL

1) MAGIC COOKIES UNDER MUDDLEFTPD

1a) Overview:

Magic cookies are used in the group sections of muddleftpd config files and in files 
displayed to the user. Magic cookies recognized in files are replaced with the values
they represent as muddleftpd parses them. eg:

	my email is %E

has the magic cookie %E. Since %E represents the FTP server maintainer's
email address, muddleftpd would create the following:

	my email is ekuiperba@cc.curtin.edu.au

1b) Syntax:

All magic cookies in muddleftpd start with a % char. There are 2 formats
available:

The %x Format:

This format is simplest syntax and simply replaces the cookie (%x) with the
entire string that represents the character x.

The %(m,n)x Format:

This format selects a range of characters from the string cookie (%x)
represents. m is the first character to insert and n is the last character
to insert from cookie x. The first character in a magic cookie is numbered
is 0. m and n are both adjusted so m >= 0 and n <= length of the Magic
cookie. if n > m, then the cookie is considered invalid, see below.

eg.
	%(0,5)u		will give the first six characters of what magic 
			cookie u represents.
	%(10,10)E	returns the 11th character of what cookie E
			represents.
	%(6,8)M		returns the 7th to 9th characters from what cookie M 
			represents.
	%(10,8)F	This is invalid because n > m.

Invalid Syntax:

If muddleftpd determines that a magic cookie is invalid (ie, it doesn't 
exist or is the format is bad), then the line where the magic cookie was
found will not be parsed.

2) MAGIC COOKIES IN DUMPED FILES.

2a) Overview:

At certain times, muddleftpd can print the contents of a file to the screen
in an extended FTP request. eg:

230-
230-Hello rugger@127.0.0.1
230-
230-WELCOME. IF YOU HAVE PROBLEMS WITH THIS SERVER EMAIL:
230-	ekuiperba@cc.curtin.edu.au
230-
230 User rugger login successful.

Magic cookies can be used in these files to create semi-dynamic content
involving the remote user, the current directory, and statistics.

2b) Available Magic Cookies. 
 
The following magic cookies are recognized in dumped files:

	%T	The current time in the format: Wed Jan 30 21:49:08 1993
	%U	The username the user used to login.
	%C	The current directory of the user.
	%E	The administrators email, set in the main config file.
		(see config.txt)
	%M	The maximum number of users muddleftpd will log on at a
		time.
	%N	The current number of users logged into this muddleftpd
		server.
	%R	The hostname of the remote user connected to muddleftpd.
	%L	The hostname of the virtual server the user is on. If no
		virtual servers are defined, it will be the main hostname/
	%f	The number of files the user has downloaded.
	%F	The number of files the user has uploaded.
	%b	The number of bytes the user has downloaded, downloading
		files.
	%B	The number of bytes the user has uploaded, uploading files.
	%I	The number of bytes the user has downloaded, from listings.
	%i	The number of listings the user has downloaded.
	%D	The total number of bytes downloaded (listing and file
		downloads) over data connections.
	%d	The total number of connections opened for downloading.
		(listing and file downloads)  
	%t	The total number of bytes transfered (listing, uploading and
		downloading) over data connections.
	%c	The total number of data connections made (for listing,
		uploading and downloading)
	%v	The name of the section the users virtual server declaration 
		is from.
	

You can also use the %(m,n)x format on any of the above cookies. (although
doing so may not be useful for many of the cookies) The %C magic cookie is
invalid during the logindump file, (see config.txt) because the user has no
current directory before startup.

2c) Examples:

Text file that is dumped when someone is logged in:

Hello %U@%R.
Welcome to %L. 
You are user %N of %M.

Send any problem reports to %E

Current time over here is: %(11,18)T

The resulting dumped file:

230-
230-Hello rugger&127.0.0.1.
230-Welcome to darkstar.example.net. 
230-You are user 1 of 5.
230-
230-Send any problem reports to ekuiperba@cc.curtin.edu.au
230-
230-Current time over here is: 01:31:38
230 User rugger login successful.

And the text file that is dumped as the user quits:

you downloaded %b bytes in %f files
you uploaded %B bytes in %F files
you downloaded %I bytes in %i listings

in total:
        download transfers %d
        downloaded bytes %D
        total transfers %c
        total transfered bytes %t
        
The results when the user quits:

221-you downloaded 14082785 bytes in 4 files
221-you uploaded 1727152 bytes in 2 files
221-you downloaded 17015 bytes in 3 listings
221-
221-in total:
221-    download transfers 7
221-    downloaded bytes 14099800
221-    total transfers 9
221-    total transfered bytes 15826952
221-
221 muddleftpd Logging out user.

after i had down some downloads and uploads and listings.

3) MAGIC COOKIES IN GROUP SECTIONS:

3a) Overview:

To make user configuration files flexable, a set of magic cookies are accepted
in these files. Most of these magic cookies get read from the authentication
module.

3b) Avaliable magic cookies:
 
The following magic cookies are recognized in group sections of config files: 
(note that some of these cookies are determined by the authetication module
and are not avaliable until it has run)

	%U	The username of the connecting party.
	%v	The section name of the virtual server the user is
		connecting to.
	%V	The host name of the virutal server the user is connecting
		to.
	%u	The uid from the authentication module.
	%g	The gid from the authentication module.
	%G	A list of suplementary gids from the authentication module.
	%h	The home directory from the authentication module.
	%r	The root directory from the authentication module.

You can also use the %(m,n)x format on any of the above cookies. (although
doing so may not be useful for many of the cookies) For the authuser, and
any directives used by the authentication module, only %U, %v and %V will be
avaliable.

3c) Examples

See the examples directory for examples of magic cookie usage in user config
files.
