Demi-ftpd documentation
-----------------------

1.  Getting started
1.1   Inetd configuration
1.2   DWAT
1.3   Upgrading from pre-1.2 versions
2.  Configuration file
3.  Command line options
4.  Scripts
5.  Cookies/macros
6.  Upload checker
7.  Anonymous access
8.  Ident/IP checker
9.  Flags
9.1   Daemon supported flags
9.2   Ident/IP checker flags
10. File formats
11. Plugins
12. Implemented commands
12.1 Raw protocol commands
12.2 SITE commands
13. Contact info


1. Getting started

This is what you need to do to get your ftp server up and running:
 1. (compile + )Install: either make; make install or rpm -i
    dftpd-x.xx-x.xxxxarch.rpm, depending on the form you received this package in.
    Note: if you don't use shadow passwords, comment the LOGINFLAGS line out
    in Makefile before compiling.
 2. Build the site tree: Use the included buildsite.sh shell script.
 3. Configure server: Edit dftpd.conf(normally in /etc/dftpd directory).
    See next section for details on setting server options.
 4. Create groups and users: Either use dftpcfg or fire up DWAT
    and use your favourite www browser to do it all.
    NOTE: You need at least one group for user creation to work.
 5. Start the daemon(unless you want to run it in inetd mode - see section 1.1 for
    inetd instructions). /usr/local/dftpd/dftpd is the default path for the dftpd
    server binary. Make sure it doesn't report any  errors, or else it will not start.

1.1 Inetd installation(optional)

 1. Create the following entries in /etc/services:
    dftpd	5444/tcp
    dwat	5445/tcp
 2. Add the following lines to /etc/inetd.conf(exact paths depend
     on where you installed dftpd):
    dftpd   stream  tcp    nowait  root    /usr/local/dftpd/dftpd dftpd -i
    dwat    stream  tcp    nowait  root    /usr/local/dftpd/dwat dwat -i

1.2 DWAT(Demi-FTPd Web Administration Tool)

When you first connect to DWAT(default port is 5445), login as
'siteop' with password 'siteop'. You should remove this account
after you've done the initial setup. Remember to add at least
one account with site operator(S) status.

1.3 Upgrading from previous versions

Dftpd v1.2 adds support for home directories and user taglines, which
makes old user databases incompatible with the new software. Use the command
"cat /etc/dftpd/passwd.dftp|awk -f convert.awk >/etc/dftpd/passwd.dftp"
to fix it.


2. Configuration file(dftpd.conf)

token		description
---------------------------
port		Port on which the daemon will listen for incoming connections.
		Default: 5444
httpport	Port on which the web administration server daemon will listen.
		Default: [port]+1
log		Enable logging of certain events.
		Example 1: "log *=blah.log" logs everything to file
		 'blah.log'.
		Example 2: "log blah:*:SEND:*=blah.log"
		 logs all file downloads by user blah to 'blah.log'.
		Leave filename empty to prevent logging of the specified
		event.
sitedir		Directory which becomes the root directory for guest and anonymous
		users unless they have the root directory specified within their
		home directories.
		Example: setting the user's home directory to "/home/./user" causes
		  dftpd to chroot to /home and the chdir to /user.
		Default: /site
debuglevel	Sets the debug level (accepted values range from 0 to 2)
		Default: 0
maxloginfails	Maximum number of failed logins before control connection is
		terminated
maxviewsize	Maximum size of file that can be viewed with 'SITE VIEW'
		Default: 10240(=10Kb)
loginidletime	Maximum idletime(in minutes) before logged in.
		Default: 3
maxidletime	Maximum idletime when logged in
		Default: 1
stupdatetime	Time(in seconds) between updating transfer progress in UTMP.
		Default: 10
createmode	Default permissions for new files(in octal format).
		Default: 0644
welcomefile	Name of the file shown to a user upon login
ulcheck		Controls the behavior of upload checker. Replace handler
		name with a '-' to ban(prevent uploading) the defined
		filemask and '+' to automatically accept the file and give
		credits appropriately if ratio is nonzero.
		Syntax: ulcheck <filemask>=<handler script name>
dupecheck	Similar as above, but applies for the duplicate file
                checker. Only specified filemasks will be checked against 
		and added to dupe checker database.
welcomemsg	The message shown to a connected user. No CR or LF, please.
goodbyemsg	Message show when a user disconnects.
statusline	Message shown after LIST, NLST, STOR and RETR.
proctitle	Process title flag:
		0 = disable, 1 = enable(default)
resolvehosts	Resolve hostnames for logs and UTMP
		0 = disable, 1 = enable(default)
realusersupport	Enable/disable "real" accounts(those in /etc/passwd)
		0 = disable, 1 = enable(default)

NOTE: See the bash(1) and fnmatch(3) manual pages for description of how the UNIX
filemasks work.


3. Command line options

-d <level>		Set to debuglevel to <level> which is a digit ranging 
			from 0 to 2(default is 0 - no debug data is logged).
-p <port>		Set the server port to <port>. Default is 5444.
-q			Sets quiet mode - nothing gets written to stdout.
-i			Run in inetd mode. Use when started by inetd.

NOTE: Command line options override options given in the configuration file.
Implemented commands


4. Scripts

Scripts are executed via SITE EXEC command. They must be located in
<SITEDIR>/bin/exec and must, of course, be flagged executable
(chmod a+x <file>). The following environment variables are provided
for your convenience:
USER      = <current username>
GROUP     = <current groupname>
ULBYTES   = <uploaded bytes>
DLBYTES   = <downloaded bytes>
SESSIONUL = <bytes uploaded during current session>
SESSIONDL = <bytes downloaded during current session>
CREDITS   = <current credits>
HOME      = <home directory>
FLAGS     = <user's flags>


5. Cookies/macros

These are special codes which the the daemon replaces with appropriate
values whenever they are written to the socket. A minus ('-') after
the cookie tells the daemon not to do bytes formatting(= Kb, Mb etc).

%un	User name
%ui	User id
%gi	Group id
%gn	Effective(current) group name
%e	Effective group id
%u	Total uploaded bytes
%d	Total downloaded bytes
%cr	Remaining credits(returns "unlimited" if ratio == 0)
%su	Uploaded bytes for this session
%sd	Downloaded bytes for this session
%f	Remaining free disk space
%i	Peer's ident string
%hn	Remote control host name
%hd	User's home directory
%tx	Time - replace the x with a strftime() symbol(see strftime(3) manual
	page for the complete list)
%fv[]	View file -- prints the first line of the file specified within the
	brackets
%cxxx	ANSI color codes, first 'x' is attribute, second is foreground color
	and the third is background color. Second and third codes are
	optional.
	Attributes(3. and 6. don't exist, dunno why):
	0 all attributes off
	1 bold
	2 dim
	4 underline
	5 blink
	7 reverse video
	8 invisible
	Colors:
	0 black
	1 red
	2 green
	3 yellow
	4 blue
	5 magenta
	6 cyan
	7 white
%v	Daemon revision string
%%	Literal '%'


6. Upload checker

Upload checkers are executables that inspect the uploaded file and return
zero if the file is ok. Remember to install /bin/sh and the libraries it
needs if you need to run shell scripts. The following additional environment
variables are provided:
FILENAME = <what would you think?>
FILESIZE = <file size in bytes>


7. Anonymous access
To allow anonymous access, you must have a user with the name "ftp"
in your userfile. You also need a group with the same name.
Anonymous account is disabled by default - you can enable it by changing
its maximum connections value to higher than 0.
Gained credits will not be saved.
Some of the default SITE commands are disabled for anonymous.
These include: group, chmod, chown and chpass.


8. Ident/IP checker

All connections are checked against any ident/ip masks
specified for the user they are trying to log in as.
CONTROL connections are those that are opened when you order the
client to connect to the server. Connections that are estabilished
to transfer files are considered DATA connections by the ident/ip
checker(technically, LIST and NLST commands also open data
connections, but those are considered CONTROL connections by the
ident/ip checker).
The checker tries to match the masks in the order they were
specified for the user. If a match is found without the 'B' flag,
the connection will pass the check.
If no masks are specified for the connection type, it will let the
user login. If a match is found for the incoming connection with
the 'B' flag, the connection is considered as banned and the
connection will terminate.


9. Flags

9.1 Daemon supported userflags

D = Delete/rename/overwrite access
W = Write/upload access
R = Read/download access
X = eXtended WHO access(get to see where other users come from)
S = Site administrator(root/admin access)
P = Change own password access

9.2 Ident/ip flags

B = Ban(disallow users from this ident@ip combination)
D = Data(applies for data connections)
C = Control(applies for control connections and DWAT connections)


10. File formats

passwd.dftp:
   name:password(encrypted):flags:maximum connections:uid:gid:ratio:
   uploaded bytes:downloaded bytes:credits:homedir:tagline:[flags<!>][identmask<@>]ipmask ..
group.dftp:
   name:id:members(names separated by ',')
dupebase.dftp:
   filename:upload time(in time_t format):uploader:directory(in which
   the file was uploaded)
utmp.dftp:
   name:pid:login time(time_t):last time active(time_t):activity:control
   host:data host
logfiles:
   name:pid:date:time:event class:data


11. Plugins

Plugins are specially linked object files which contain code that dftpd can
add to its SITE command arsenal. Install plugins by dropping them to
$CONFDIR/plugins(typically /etc/dftpd/plugins). All you need to do is to
reconnect. To develop your own plugins, check out the plugindk directory of
dftpd distribution.


12. Implemented commands

12.1 Raw protocol commands

command	description
-------	-----------
USER	Login to server
PASS	Supply a password after USER
PORT	Change data connection destination address and port
QUIT	Logout from server
TYPE	Change data connection type. Allowed types are (A)scii and (I)mage(binary)
LIST	Transmits directory listing via data connection
NLST	Same as LIST, but always one file per line
DELE	Delete a file
RETR	Retrieve a file(download)
STOR	Store a file(upload)
MKD	Create a directory
RMD	Remove a directory
CWD	Change working directory
CDUP	Same as "CWD .."
PWD	Print working directory
NOOP	No operation(does nothing)
REST	Insert restart marker(allows to continue a cancelled transmission)
SIZE	Print file size[works only with (I)mage type]
HELP	Gives list of supported commands
MDTM	Displays modification time of a file
RNFR	Rename from(rename command step 1)
RNTO	Rename to(rename command step 2)
SITE	Contains specific site feature commands
PASV	Initiates passive transfer mode

12.2 Site specific commands(contained in defaultcmds.so)

command	description
-------	-----------
EXEC	Executes a script or binary in /bin/exec.
GROUP	Changes your effective group(works if you are a member of that group).
GROUPS	Lists the groups you are in and mark your current group with "*".
HELP	Gives you help on either all SITE commands or on a specific command.
VIEW	Displays a file via control connection. If the specified file is not
	found, it will be looked for in a special directory 'view' inside
	the configuration directory. Note that the directory must exist
	before the connection is opened.
WHO	Gives a listing of online users. Users with the eXtended who flag
	also get to see where the users are coming from.
FIND	Performs a recursive search for a specified file(starts from /).
	The search is normally a case insensitive substring search, but if
	you specify the '-f' flag, a case sensitive filemask search will be
	performed.
CHMOD	Changes permissions of a file. Only numeric permissions are
	accepted.
CHOWN	Changes ownership of a file.
UMASK	Changes the umask value for the current session. All files are
	created with mode 0777&umask.
SU	Changes to and from superuser(root) mode. Effective user and group
	ids are set to 0 when superuser mode is active.


13. Contact info

Dftpd home page is currently http://www.karico.fi/dftpd/index.html.

Problems? Send mail to demigod@karico.fi.
NOTE: Before sending any e-mail, please read BUGS to see if your problem is
an already known bug. Though if you have a fix, you can(and should) tell me
about it.
